überSpark: Add x86_32 hardware model to next-gen toolkit

Task to migrate existing x86_32 hardware model into the next generation toolkit.

Current hardware model source folder:
src/hwm/*.c

Current hardware model header folder:
src/hwm/include/*

This needs to be migrated into the following folder structure within the next generation toolkit:

  • src-nextgen/hwm/platform/pc ==> will contain PC platform specific hardware modeling (e.g., xmhfhwm_bios.c)
  • src-nextgen/hwm/arch/x86/generic ==> will contain generic x86 architecture specific hardware modeling of instructions common to both Intel and AMD x86 architecture that have the same semantics regardless of 32-bit or 64-bit
  • src-nextgen/hwm/arch/x86/intel ==> will contain intel x86 architecture specific hardware modeling of instructions that have the same semantics regardless of 32-bit or 64-bit
  • src-nextgen/hwm/arch/x86_32/generic ==> will contain x86 architecture specific hardware modeling of instructions in 32-bit common to both Intel and AMD
  • src-nextgen/hwm/arch/x86_32/intel ==> will contain intel x86 architecture specific hardware modeling of instructions in 32-bit
  • src-nextgen/hwm/device/ ==> will contain device specific transaction level hardware modeling. let us base this on the Linux OS kernel drivers folder organization (see https://github.com/torvalds/linux/tree/master/drivers). Thus for the e1000 device model that exists currently, the folder will be src-nextgen/hwm/device/net/ethernet/intel/e1000/

I am thinking the organization of src-nextgen/hwm/include should mimic the folder organization of src-nextgen/hwm/. i.e., the header for src-nextgen/hwm/platform/pc will be src-nextgen/hwm/include/platform/pc/hwm.h

Let me know your thoughts.

Linked PRs:

Sounds good! I’ll get to work and update this thread with further questions.

I setup the directory structure, and I want to make sure my understanding of where to move the files is correct before I adjust the function names and include headers.

My updated hwm directory structure would look like:

hwm
├── arch
│   ├── x86
│   │   ├── generic
│   │   │   └── xmhfhwm_mem.c
│   │   └── intel
│   │       ├── xmhfhwm_lapic.c
│   │       └── xmhfhwm_txt.c
│   └── x86_32
│       ├── generic
│       └── intel
├── cpu
│   ├── README.rst
│   ├── x86
│   │   ├── generic
│   │   │   └── xmhfhwm_cpu.c
│   │   └── intel
│   └── x86_32
├── device
│   ├── iommu
│   │   └── intel
│   │       └── xmhfhwm_vtd.c
│   ├── net
│   │   └── ethernet
│   │       └── intel
│   │           └── e1000
│   │               └── xmhfhwm_e1000.c
│   ├── pci
│   └── README.rst
├── include
│   ├── arch
│   │   ├── x86
│   │   │   ├── generic
│   │   │   │   └── xmhfhwm_mem.h
│   │   │   └── intel
│   │   │       ├── xmhfhwm_lapic.h
│   │   │       └── xmhfhwm_txt.h
│   │   └── x86_32
│   │       ├── generic
│   │       └── intel
│   ├── cpu
│   │   ├── README.rst
│   │   └── x86
│   │       ├── generic
│   │       │   └── xmhfhwm_cpu.h
│   │       └── intel
│   ├── device
│   │   ├── iommu
│   │   │   └── intel
│   │   │       └── xmhfhwm_vtd.h
│   │   ├── net
│   │   │   └── ethernet
│   │   │       └── intel
│   │   │           └── e1000
│   │   │               └── xmhfhwm_e1000.h
│   │   ├── pci
│   │   │   └── xmhfhwm_pci.h
│   │   └── README.rst
│   ├── platform
│   │   ├── pc
│   │   │   └── xmhfhwm_bios.h
│   │   └── README.rst
│   └── xmhf-hwm.h
├── platform
│   ├── pc
│   │   └── xmhfhwm_bios.c
│   └── README.rst
└── README.rst

I really wasn’t sure about where to move lapic, mem, and txt, and I tried to emulate the linux drivers directory for vtd and pci. Let me know if I should rearrange things.

Also, should the CASM declarations (hwm/include/xmhfhwm_casm) be included in the new hwm folder, or would it make more sense to move it out of the hardware model?

Thanks!

This looks great as a starting point. The entire cpu subtree should feature under arch. i.e., cpu/x86/generic should go into arch/x86/generic

I really wasn’t sure about where to move lapic, mem, and txt,

txt should go into arch/x86_32/intel
mem is fine where it is currently
lapic should go into arch/x86/generic

and I tried to emulate the linux drivers directory for vtd and pci.

perfect!

Also, should the CASM declarations ( hwm/include/xmhfhwm_casm ) be included in the new hwm folder, or would it make more sense to move it out of the hardware model?

CASM is the überSpark assembly language interface to CPU instructions, so it should go into arch/x86/generic for the time-being.

Eventually, the CASM interface has to be split into arch/x86/intel, arch/x86/generic, arch/x86_32/generic, and arch/x86_32/intel based on the instruction. i.e., eventually there will be a casm.h in each of the aforementioned folder that exposes the corresponding instruction semantics. However, we can handle this later.

Thanks for jump-starting this re-organization effort Ethan!

Hey Amit,
I have a few more questions and then I should be ready to submit a pr on this task.

  • Should the naming scheme for functions follow the same convention from the uobjrtl libraries? Something like xmhfhwm_cpu_insn_movl_cr0_eax --> uberspark_hwm__arch_x86_generic_cpu__insn_movl_cr0_eax?
    • Should I also rename the internal _impl_xmhfhwm_... functions to fit this naming scheme?
  • Should hwm.h still include all of the other hwm headers, or should I add the appropriate includes to the hw runtime library to have it be more modular?

Thanks!

Great Ethan! Please find my response below:

Should the naming scheme for functions follow the same convention from the uobjrtl libraries? Something like xmhfhwm_cpu_insn_movl_cr0_eax --> uberspark_hwm__arch_x86_generic_cpu__insn_movl_cr0_eax ?

The hardware model CPU instructions should probably have just a __casm__ prefix. For example: __casm__movl_cr0_eax . This way we keep it close to the inline __asm__ directive that programmers are typically used to.

Should I also rename the internal _impl_xmhfhwm_... functions to fit this naming scheme?

Following aforementioned rationale, we could go with __impl__casm__movl_cr0_eax

Should hwm.h still include all of the other hwm headers, or should I add the appropriate includes to the hw runtime library to have it be more modular?

This is a good point you raise.

For now, I would say we have a hwm.h within each of the arch/x86/generic, arch/x86/intel, arch/x86_32/generic and arch/x86_32/intel folders that includes the corresponding headers within those folders.

A similar situation will apply to device subtree. For example: device/iommu/intel/ will have a hwm.h that includes xmhfhwm_vtd.h.

One rule we probably need to apply to the arch subtree is dependency. For example:

arch/x86/intel/hwm.h should include arch/x86/generic/hwm.h since intel is a subset of x86

Similarly,

arch/x86_32/generic/hwm.h should include arch/x86/generic/hwm.h since x86_32 generic is a subset of x86.

and so on.

Hope this is clear. Please feel free to seek any clarification. Thanks!

Thanks! I just opened a pull request: https://github.com/uberspark/uberspark/pull/18

Let me know how it looks and if I should modify anything.

Thanks Ethan!

Just reviewed the PR. Please see my comments below:

  • Let us move hwm/arch/, hwm/device and hwm/platform into hwm/src/arch, hwm/src/device, and hwm/arc/platform respectively. This is so that: hwm/src can be the hardware model source subtree and hwm/include can be the corresponding header subtree

  • It would be great if you can add some preliminary documentation to the hardware model. Specifically,

    1. within docs/genuser-gude/terminology411.rst – add a brief blurb about what the hardware model is
    2. within docs/contrib-guide/ add a new hwm.rst and describe how one would go about adding a new hardware model extension (e.g., cpu, device or platform) based on the discussions on this thread and your experience in migrating the hardware model so far.
    3. within docs/reference create hwm.rst and add placeholder for hardware model interfaces. e.g., the cpu’s currently modeled, the devices currently modeled, the platform elements currently modeled along with their interfaces (e.g., for hwm/device/iommu/intel the current interfaces within vtd.h are _impl_hwm_vtd_read and _impl_hwm_vtd_write)

Of course, feel free to amend the aforementioned list with other items that I might have missed out.

Thanks for your effort. This is really helping us better define the hardware model, hardware uobj runtime libraries and associated interfaces!

Thanks! I’ll get to work on the docs and update you once it’s done.

I just pushed a draft of the hwm documentation. Let me know how it looks.

Thanks Ethan!

Linked PR to OP. Am going though it now…

Hi Ethan,

I am having some issues with the build harness and noticed that the PR was not rebased on top of current develop HEAD.

Can you rebase the PR to make it current with develop: HEAD and do a force push to update? See https://github.com/edx/edx-platform/wiki/How-to-Rebase-a-Pull-Request

Thanks!

Hey Amit,
I just rebased both PRs.

PR merged. Closing topic thread. Thanks Ethan!