bmvm

bmvm (BareMetal Virtual Machine) is a minimal Type-1 hypervisor, intended for performing runtime instrumentation of the OS, while not acting as a middleman for hardware access. The OS runs at full speed with direct access to native hardware, but the hypervisor can be used to perform instrumentation and/or virtualize specialized hardware.

License

Unless stated otherwise, all code in this repository is licensed on the terms of the GNU GPL version 2 or above. A copy of GNU GPL version 2 is included in the repository.

Building

BMVM is built using the build.py script. Its help message is provided below:

usage: build.py <target> [options...]

<target> may be one of:

    clean [other target...]
        Remove the build directory.

    loader
        Build only the loader.

    lib<name>
        Build the specified library.

    initrd <output> <config.txt>
        Build an initrd with the specified config.txt.

    amalgam <output> <config.txt> [cmdline...]
        Build a BIOS-bootable disk image with the specified config.txt and (optional) loader command line, which is also a UEFI executable.
        This build target is also available as "biosdisk".

For example, to build a BIOS-bootable image that performs the SMP test you can do the following:

python3 build.py biosdisk output.img libs/smptest.txt

Configuration

bmvm is configured using the "config.txt" file in the initrd ("libs/config.txt" in the source tree). An example config is provided at that path. An alternative path (within the initrd) can be specified using the "configfile" boot option (e.g. "configfile=config2.txt".

The configuration file specifies the load order of libraries and the arguments being passed to each library. See the libraries' source code for information on the format of these arguments.

If build.py is used to build the initrd, then config.txt specifies which libraries and other files should be included in the initrd.

Booting (linux16 or linux32)

bmvm implements the kernel side of the "linux16" and (partially) "linux32" boot protocols. For these protocols, "build/loader/vmlinux" is passed as the kernel, "initrd.img" (tarball with libraries & config files, usually built with build.py initrd) is passed as the initrd, and an optional command line can be passed.

Booting (direct BIOS boot)

You can build a BIOS disk image using build.py biosdisk. If you want to build it manually, you can do that by simply concatenating (using cat) the vmlinux, initrd and the command line into a disk image. This image is bootable on a BIOS-based x86_64 system.

Caveats:

• Some VMs tend to truncate HDD images slightly. You may have to append zero padding to the end of the image to make it bootable. If using build.py, 1MB of zeroes is automatically appended.
• If several disks have BMVM flashed onto them, the bootsector may boot from the wrong one. build.py embeds a SHA-256 hash of the image into the bootsector to avoid this misdetection.

Booting (UEFI)

build/loader/vmlinux can be used as a UEFI MZ/PE executable. In this case a command-line parameter initrd= must be assigned with the filesystem path where the initrd should be loaded from.

uefi=1 can be specified if you don't want BMVM to terminate the EFI boot services. In this case, uefimem=<size in bytes> must also be specified to allocate a block of runtime memory for internal use.

Amalgamations generated by build.py amalgam can be booted on UEFI. In this case, the externally-passed command line is completely ignored. This can be used to create sealed BMVM images that can be signed for secure boot.

Note: this does not amalgamations created by direct concatenation, these work as normal vmlinux images if booted on UEFI.

Booting guests

As an instrumentation hypervisor that does not virtualize hardware, bmvm can only boot 1 guest OS per instance. How the guest OS is booted is specified in the "boot=" option in the configuration file. See "libboot/main.cpp" for a list of valid options.