Initial Pull Request for xmhf-64

CHANGELOG.md

@@ -2,6 +2,61 @@
 
 ## Changelog
 
+* Version 6.2.0
+
+	* Features
+		* xmhf-64: initial commit, copied from xmhf
+		* xmhf-64: fix compile errors found in high GCC version
+		* xmhf-64: support running XMHF in 64-bit mode
+		* xmhf-64: support continuous integration testing
+		* xmhf-64: support running XMHF in QEMU
+		* xmhf-64: support running XMHF with modern guest operating systems
+		* xmhf-64: support running guests that use PAE paging
+		* xmhf-64: provide ``pal_demo``, which compiles TrustVisor PALs in
+		  Windows and Linux, without using linker scripts
+		* xmhf-64: decrease compilation artifact size (e.g. object files)
+		* xmhf-64: support optimized compile (e.g. ``-O3``)
+		* xmhf-64: support DMAP in Intel
+		* xmhf-64: allow the guest OS to change MTRR
+		* xmhf-64: support x2APIC
+		* xmhf-64: support Intel microcode update
+
+	* Bug fixes
+		* xmhf-64: check `grube820list_numentries` in `dealwithE820()` to
+		  prevent possible buffer overflow
+		* xmhf-64: fix Makefile dependencies problems
+		* xmhf-64: fix unsigned overflow in `udelay()`. This bug causes sleep
+		  to be shorter than expected
+		* xmhf-64: fix the CR0 intercept handler
+		* xmhf-64: fix WRMSR intercept handler when MSR comes from
+		  `vmx_msr_area_msrs`. This bug leads to unexpected values read by the
+		  guest
+		* xmhf-64: block guests' access to x2APIC. This bug may allow guests to
+		  to send INIT to a CPU
+		* xmhf-64: fix incorrect assert in hpt.c for long mode paging. This bug
+		  is on a code path that is likely unused by 32-bit guests
+		* xmhf-64: fix logic in NMI quiesce handling. This bug can cause
+		  deadlock and lose of guest NMIs
+		* xmhf-64: fix the problem that `HALT()` does not halt forever. This
+		  bug can cause troubles during debugging
+		* xmhf-64: fix the problem that the last entry of E820 is dropped
+		* xmhf-64: unset CR4.VMXE, which is incorrectly set
+		* xmhf-64: fix logic in booting, which causes problems for single CPU
+		  machines
+		* xmhf-64: fix guest initial state (e.g. DX, CR0, ...)
+		* xmhf-64: truncate RSP in `_vmx_int15_handleintercept()`
+		* xmhf-64: fix incorrect assumption about default MTRR type. This bug
+		  causes strange cache errors in Windows 10
+		* xmhf-64: block guests' change to MTRRs. This bug allows guests to
+		  change host's memory cache settings
+		* xmhf-64: block guest microcode update. This bug allows guests to
+		  update microcode arbitrarily
+		* xmhf-64: fix NULL pointer reference in the VGA driver. This bug is on
+		  a code path that only happens when debugging
+		* xmhf-64: fix incorrect use of .fill in `xmhf_xcphandler_idt_start()`.
+		  This bug leads to less area allocated for IDT than expected
+		* xmhf-64: remove two unused nmm functions that may contain bugs
+
 * Version 6.1.0
 
 	* Features
@@ -153,4 +208,4 @@
 
 * Version 0.1 
    * Initial Release
-
+

docs/.gitignore

@@ -0,0 +1,3 @@
+/_build
+/_temp
+/_themes

docs/index.rst

@@ -57,6 +57,19 @@ framework and associated components.
    rpi3-cortex_a53-armv8_32/debugging
 
 
+.. toctree::
+   :maxdepth: 2
+   :caption: PC Intel x86 64-bit:
+
+   pc-intel-x86_64/introduction
+   pc-intel-x86_64/hw-requirements
+   pc-intel-x86_64/supported-os
+   pc-intel-x86_64/build
+   pc-intel-x86_64/installing   
+   pc-intel-x86_64/debugging
+   pc-intel-x86_64/uberapp-trustvisor
+
+
 .. toctree::
    :maxdepth: 2
    :caption: Legacy PC AMD/Intel x86 32-bit:

docs/pc-intel-x86_64/build.rst

@@ -0,0 +1,241 @@
+.. include:: /macros.rst
+
+.. _pc-intel-x86_64-building:
+
+Building
+========
+
+uberXMHF (pc-intel-x86_64) and uberapps (e.g., :doc:`TrustVisor </pc-intel-x86_64/uberapp-trustvisor>`\ ) get built 
+in a Linux environment with 
+a recent version of gcc. uberXMHF (pc-intel-x86_64) has been verified to 
+build on Debian 11 and Fedora 35, both 32 and 64 bit.
+
+It is also possible to build uberXMHF in docker. The ``debian:11`` Docker tag is known to work.
+
+Build tools
+-----------
+
+A (partial) list of packages to install on Ubuntu / Debian:
+
+.. code-block:: bash
+
+   aptitude install pbuilder texinfo ruby build-essential autoconf libtool
+
+A (partial) list of packages to install on Fedora:
+
+.. code-block:: bash
+
+   dnf install autoconf automake make gcc
+   # The next line installs fallocate, which is recommended
+   dnf install util-linux
+
+On 64-bit Debian, you will also need to install 32-bit libraries:
+
+.. code-block:: bash
+
+   aptitude install build-essential crossbuild-essential-i386
+
+On 32-bit Debian, to compile XMHF in 64-bit, install 64-bit cross compiler:
+
+.. code-block:: bash
+
+   apt-get install build-essential crossbuild-essential-amd64
+
+High-level Build Summary
+------------------------
+
+One "drives" the build from the root directory of uberXMHF (pc-intel-x86_64):
+
+The interesting high-level build commands include:
+
+.. code-block:: bash
+
+   ./autogen.sh           # creates ./configure
+   ./configure            # creates Makefile from Makefile.in
+   make                   # builds the selected hypapp and the XMHF core
+   make install           # installs binaries
+   make install-dev       # (hypapp specific) installs dev headers and libs
+   make test              # (hypapp specific) runs various automated tests
+   make clean             # cleanup
+   make htmldoc           # generates the HTML documentation you are reading in the `./doc` sub-folder
+
+
+The functioning of ``make install-dev`` and ``make test`` are
+uberapp-specific. For example, in the TrustVisor uberapp, the primary prerequisite
+for tee-sdk and PAL development is having successfully run 
+``make install-dev``.
+
+How do I build a uberXMHF (pc-intel-x86_64) uberapp?
+-----------------------------------------------------
+
+The method for building different uberapps (e.g., TrustVisor) is by specifying
+which uberapp to build using ``./configure``.
+The following describes the sequence of steps for building a 
+uberXMHF (pc-intel-x86_64) uberapp using the helloworld 
+uberapp as a running example.
+
+Change working directory to the uberXMHF (pc-intel-x86_64) root directory.
+
+.. code-block:: bash
+
+   cd ./xmhf-64
+
+
+Generate the ``./configure`` script.
+
+.. code-block:: bash
+
+   ./autogen.sh
+
+
+Configure the uberXMHF (pc-intel-x86_64) uberapp (see below for the
+``--with-target-subarch=`` configuration option).
+
+.. code-block:: bash
+
+   ./configure --with-approot=hypapps/helloworld --with-target-subarch=...
+
+
+Generate and install the binaries:
+
+.. code-block:: bash
+
+   make
+   make install
+   make install-dev  # optional (hypapp-specific)
+   make test         # optional (hypapp-specific)
+
+
+To use multiple processors on the compiling machine, try ``make -j $(nproc)``.
+
+Note that ``make install`` is only useful if the development system and 
+the target system (on which uberXMHF (pc-intel-x86_64) is installed) are 
+the same. If not, 
+you will need to manually copy the files ``./xmhf/init-x86.bin`` 
+and ``./xmhf/hypervisor-x86.bin.gz`` to the ``/boot`` folder of the
+target system (see :doc:`Installing uberXMHF (pc-intel-x86_64) </pc-intel-x86_64/installing>` ).  
+
+Build configuration options
+---------------------------
+
+Mandatory arguments
+^^^^^^^^^^^^^^^^^^^
+
+* 
+  --with-approot=[UBERAPP_PATH], specifies the uberapp source root; must be provided
+
+*
+  --with-target-subarch=[TARGET_SUBARCH], specify which subarch of uberXMHF to
+  build (32-bit or 64-bit); must be provided
+
+	*
+	  When building 32-bit uberXMHF on 32-bit Debian or Fedora:
+	  ``--with-target-subarch=i386``
+	*
+	  When building 64-bit uberXMHF on 32-bit Debian:
+	  ``--with-target-subarch=amd64 CC=x86_64-linux-gnu-gcc LD=x86_64-linux-gnu-ld``
+	*
+	  When building 64-bit uberXMHF on 32-bit Fedora:
+	  ``--with-target-subarch=amd64``
+	* 
+	  When building 32-bit uberXMHF on 64-bit Debian:
+	  ``--with-target-subarch=i386 CC=i686-linux-gnu-gcc LD=i686-linux-gnu-ld``
+	*
+	  When building 32-bit uberXMHF on 64-bit Fedora:
+	  ``--with-target-subarch=i386``
+	*
+	  When building 64-bit uberXMHF on 64-bit Debian or Fedora:
+	  ``--with-target-subarch=amd64``
+	*
+	  If these argument is not added correctly, an error message like
+	  ``ld: cannot find -lgcc`` may appear when building.
+
+* 
+  --with-target-platform=[PLATFORM], specifies the target platform for the build; 
+  optional, current options are: x86pc (x86 hardware virtualized platforms, default)
+
+* 
+  --with-target-arch=[ARCH], specifies the target CPU architecture; 
+  optional, current options are: x86vmx (Intel, default)
+
+Recommended arguments
+^^^^^^^^^^^^^^^^^^^^^
+
+*
+  --enable-debug-symbols, adds debug info to generated ELF files. With this
+  configuration, GDB can print symbols in ``*.exe`` files.
+
+*
+  --disable-drt, disables Dynamic Root-of-Trust (DRT); optional, useful for builds 
+  targeting platforms without support for DRT and/or TPM
+
+*
+  --disable-dmap, disables DMA protection; optional, useful for builds targeting 
+  platforms without DMA protection capabilities
+
+*
+  --with-amd64-max-phys-addr=[MAX_PHYS_ADDR], configures maximum physical
+  address (in bytes) supported by 64-bit uberXMHF
+
+	*
+	  For example, ``--with-amd64-max-phys-addr=0x140000000`` sets physical
+	  address to 5 GiB. The default is 16 GiB. When XMHF runs on a machine that
+	  has more physical memory than this value, XMHF will halt. This
+	  configuration is ignored in i386 XMHF
+
+*
+  --enable-update-intel-ucode, allows the guest to perform microcode update
+
+Other arguments
+^^^^^^^^^^^^^^^
+
+*
+  --disable-debug-serial --enable-debug-vga, print debug messages on VGA, not
+  serial port. This is useful for builds targeting platforms without serial
+  ports
+
+*
+  --with-opt=[COMPILER_FLAGS], compiles XMHF with optimization. For example,
+  ``--with-opt='-O3 -Wno-stringop-overflow'`` adds ``-O3`` and
+  ``-Wno-stringop-overflow`` to GCC's arguments to compile in optimization
+  ``-O3``. As of writing of this documentation, ``-Wno-stringop-overflow`` is
+  needed due to a `bug <https://gcc.gnu.org/bugzilla/show_bug.cgi?id=105100>`_
+  in GCC:
+
+*
+  --enable-optimize-nested-virt, enables some risky optimizations in intercept
+  handling
+
+	*
+	  When running XMHF under many levels of nested virtualization, VMREAD and
+	  VMWRITE instructions become expensive. This configuration enables
+	  manually optimized intercept handling for some cases to prevent XMHF from
+	  running too slow to boot the guest OS. However, these optimizations need
+	  to be manually maintained and may be incorrect.
+
+Configuration examples
+^^^^^^^^^^^^^^^^^^^^^^
+
+``xmhf-64/.github/build.sh`` can be used to generate configuration options. It
+automatically detects the compiling machine's bit size and can be especially
+helpful to figure out cross-compile options. See comments at the start of this
+file. The following will print sample configuration commands:
+
+.. code-block:: bash
+
+   ./.github/build.sh i386 release -n
+   ./.github/build.sh amd64 release -n
+
+Other examples:
+
+.. code-block:: bash
+
+   # Build i386 XMHF on i386 Ubuntu, without DRT and DMAP
+   ./configure --with-approot=hypapps/trustvisor --disable-dmap --disable-drt
+
+   # Build i386 on amd64 Debian
+   ./configure --with-approot=hypapps/trustvisor --enable-debug-symbols --enable-debug-qemu CC=i686-linux-gnu-gcc LD=i686-linux-gnu-ld
+
+   # Build amd64 on amd64 Debian, with 8 GiB memory, and use VGA instead of serial
+   ./configure --with-approot=hypapps/trustvisor --with-target-subarch=amd64 --enable-debug-symbols --enable-debug-qemu --with-amd64-max-phys-addr=0x200000000 --disable-debug-serial --enable-debug-vga
+