Extending XMHF to support 64-bit Intel and modern operating systems

Hi all,

I am working on a project extending XMHF. I forked the uberXMHF repository and made some updates. After my change, XMHF can run in 64-bit Intel CPUs and supports some modern operating systems (Windows 7, Windows 8.1, Windows 10, Debian 11, etc.). I am planning to support nested virtualization in the future. My repository is GitHub - lxylxy123456/uberxmhf: uber eXtensible Micro-Hypervisor Framework (branch “xmhf64”).

For the current maintainers of uberXMHF, I would like to know whether you would like to merge my changes to the uberspark/uberxmhf repo (maybe under a new folder)?

I also discovered some bugs in XMHF, and I wonder whether these may help XMHF or uberXMHF. For example, I found that NMI quiescing code may deadlock under rare conditions. These bugs are fixed in my fork, but I have not separated them from the commits that add the new features. If useful, I can go back to all my commits and generate a list of bugs I found.

Thank you,
Eric Li

Linked PR(s):

Welcome to the forums @lxylxy123456 !

Yes, we can definitely do that. Would you be able to briefly enumerate the new capabilities that you have added? We can then decide the best way to bring them upstream.

Also, I found an outstanding PR made to uberspark/uberxmhf.git as below:

Is this the PR towards the proposed addition? Are you planning on submitting additional PRs?

Thanks for your contribution!

It might be useful to identify features vs fixes when you enumerate the changes that you are introducing within your PR(s).

Hi Amit,

The PR #34 on uberspark/uberxmhf.git is only a small part of my changes. I have a lot more changes.

While working on the project, I kept a “change log” at uberxmhf/branches.md at notes · lxylxy123456/uberxmhf · GitHub. The log items are low level, and I will try to enumerate the high level changes (features / fixes) in a future post.

I think the best way is to merge my change as a new folder in the repository (currently there are xmhf, uxmhf, uxmhf-rpi3; maybe my change can be in xmhf64). The reasoning is that my code has not been formally verified, but xmhf is verified.

Thank you,
Eric Li

I would recommend you then submit a full PR with all your changes. We can cancel existing PR #34 and use your new PR as a starting point for the merge.

Sounds good. We will need this information to populate the PR merge, possibly revisions to the documentation as well as for the changelog. I am assuming your PR will also have the required documentation for each supported OS/platform and how to build, install and run.

xmhf-64 seems a resonable home for this. Documentation can go into docs/pc-intel-x86_64. Please submit a PR rebased on uberspark/uberxmhf.git on the master branch and we can go from there.


1 Like

I have created Pull request 35 for uberspark/uberxmhf.git for now (for some reason I cannot post a URL to this). I have used the names xmhf-64 and docs/pc-intel-x86_64. Does the structure look right? The documentation is not done yet.

I see currently there are docs/pc-intel-x86_32 and docs/pc-legacy-x86_32. Should I make a copy of one of these directories and update it with my documentation? Do you know which one corresponds to the old XMHF (not uberXMHF)?

I have linked the PR to the OP of this thread.

Looks good for starters.

docs/pc-legacy-x86_32 is what you want. Would be great if you can copy and follow the existing structure and add your changes/revisions to it.

Also, I see in the PR that you have both lockdown and trustvisor hypapps within the hypapps folder. Does the 64-bit version support building/running both these hypapps?

I see, I will copy documentation from pc-legacy-x86_32 and start from there.

Lockdown is not supported, so I have just removed it. TrustVisor is supported in 64-bit mode.

1 Like

I have updated the documentation in the repo. I would say that my PR is ready for review at this point.

I currently have a list of features and bugs in mind, but I am not sure what is the best way to present them.

  • In the documentation, “Introduction” contains a one-sentence description of each bug / feature: (the blog does not allow me to post a link to GitHub. It is docs/pc-intel-x86_64/introduction.rst)
  • My own notes contain a mapping from each feature / bug to a list of related commits: (the blog does not allow me to post a link to GitHub) https:// github dot com /lxylxy123456/uberxmhf/blob/notes/bug_068/feature_bug.md
  • Maybe we can schedule a meeting and talk about each bug and feature?

This should be sorted now.

Upon a cursory review I found that the PR contains deleted references to xmhf/hypapps/lockdown/src. Please revert that for starters since all your changes need to be within the xmhf-64 folder as we previously discussed.

Also, the introduction section of the documentation is probably not the best place for the features/bugs list. This should go into CHANGELOG within the root folder.

I can make another pass on the PR once you have had a chance to resolve the above as a first step. Thanks!

You could include a high level paragraph or points of the feature set you support for xmhf-64 within the introduction but the laundry list should go into the CHANGELOG

I have fixed the lockdown problem. The problem is that many files has the UNIX execute bit (e.g. rwx below, but should be rw-)

$ ls -l xmhf/hypapps/lockdown/src/guestos/windows/win2k3/ldnvnet/sys/miniport.c
-rwxrwxr-x. 1 ... xmhf/hypapps/lockdown/src/guestos/windows/win2k3/ldnvnet/sys/miniport.c

However, I agree that this problem should not be fixed in my PR.

I have moved the list of features and bugs to CHANGELOG.md. Could you please take a look at the PR again? Thanks.

The CHANGELOG looks good. I made another brief pass on the PR and have the following questions/comments:

  1. You can remove xmhf-64/hypapps/verify altogether
  2. What does xmhf-64/.circleci contain?
  3. What does xmhf-64/.github contain?
  4. What does xmhf-64/.jenkins contain?

Thanks your patience as we work through the review process!

Some more comments on the documentation portion:

  1. Would be great if you can include within docs/pc-intel-x86_64/supported-os.rst the combinations of OS/arch supported. I liked the table you had in your initial link which shows real hardware, QEMU and the different combinations of DRT, DMAP, i386 and x86_64.
  2. docs/pc-intel-x86_64/installing.rst should include a section on QEMU, right now it is all on real hardware
  3. Likewise docs/pc-intel-x86_64/debugging.rst should have a section on QEMU based debugging if available.

I have removed xmhf-64/hypapps/verify. Should I also remove xmhf-64/xmhf/src/xmhf-core/verification?

The 3 folders contain continuous integration setup code. They should be in the root directory of the repository in order to be effective (e.g. .github instead of xmhf-64/.github). Would you be ok if I create new directories there?

I was going to get to the xmhf-64/xmhf/src folder for review next, but yes you can go ahead and remove that folder for now.

Ahh I see. Ok lets stick it into xmhf-64/tools/githubci, xmhf-64/tools/circleci and xmhf-64/tools/jenkins respectively for now. Perhaps you can add a README within each folder with the respective description that you mentioned in the previous post. For jenkins it might be beneficial to add the server setup instructions or point to an external link/tutorial for it. We can revisit these CI tools later and perhaps move it into the root folder as a separate task later once this PR is merged upstream.

I also see a lot of binary files within xmhf-64/.jenkins/boot/grub/i386-pc. Do we really need to add these to version control or can they be downloaded from an external link/repository somewhere?

  1. I have added a table. But in the future this table will grow in dimension (e.g. UEFI / no UEFI), and we may need to consider a new way to present this information. Currently I do not have test results for DMAP. @superymk may know more about it.
  2. Installing on real and hardware are the same. (I have added the previous sentence to the docs). I am not covering how to install an OS in QEMU.
  3. Added.

Moved to xmhf-64/*

Most of these files should be able to be downloaded from something like Debian -- Details of package grub2 in bullseye. The magic a.img may be difficult to construct from online, but if it is compressed it is only 53 KiB. We can figure this out later. I have removed them for now. In the future PR I can try to download the files from an external source.

Ok, but it might make sense to add this information into the README within the jenkins folder. Also when you say magic a.img, what magic are we talking about here? :slight_smile:

For sake of completeness, is there an external link you could add to the docs which can inform the user how to install an OS if he/she chooses to go the QEMU route? I do remember seeing a few lines of qemu disk image invocations within your CI scripts; you could perhaps just add something to that effect as an example to be able to install and execute a QEMU OS image with xmhf-64 installed within it.