Xvisor: a type-1 hypervisor you can read in the source

A monolithic hypervisor with a small, readable core

Xvisor stands for eXtensible versatile hypervISOR, and it is an open-source type-1 hypervisor aiming to provide a monolithic, light-weight, portable and flexible virtualisation solution.

The claims it makes are specific about the trade. It provides a high performance and low memory footprint virtualisation solution for ARMv7a-ve, ARMv8a, x86_64, RISC-V and other CPU architectures. The word monolithic here describes the design choice, not a limitation to apologise for: the hypervisor is one binary with guest management built in, rather than a separate microkernel plus a user-space management layer. For a research and learning context that is a feature, because there is one code path to follow.

Virtualisation approach is stated just as plainly. Xvisor primarily supports full virtualisation, hence it supports a wide range of unmodified guest operating systems. Paravirtualisation is optional, and the plan is to support it in an architecture independent manner, with examples given as VirtIO PCI and MMIO devices, so that using paravirtualisation does not require changing the guest OS.

The feature list covers what you would expect from something claiming to be a modern hypervisor: device tree based configuration, tickless and high resolution timekeeping, a threading framework, a host device driver framework, an IO device emulation framework, runtime loadable modules, pass-through hardware access, dynamic guest creation and destruction, a management terminal, network virtualization, input device virtualization and display device virtualization.

Two of those are worth pausing on. Runtime loadable modules mean the device model can be extended without rebuilding the hypervisor, which is how a research project stays current. Tickless and high resolution timekeeping is the kind of detail that separates a hypervisor intended for real guests from one intended for demos.

The code is C, the licence is the GNU General Public License, the primary language of the repository is C, and the last push was on 2026-10-01 with no GitHub releases published.

Documentation that lives in the source

The documentation policy is unusual and worth knowing about before you decide this project is under documented.

For Xvisor the project prefers source level documentation, so wherever possible things are described directly in the source code. The stated reason is that this helps maintain source and its documentation at the same place. For source level documentation the project strictly follows Doxygen style, and the readme links the Doxygen manual for details.

In addition there are various README files in the docs subdirectory, with docs/00-INDEX given as the list of what is contained in each file or sub-directory. The top level of the repository supports that structure: an arch directory for the architecture ports, core for the hypervisor core, drivers for host drivers, emulators for the device models, libs for the support libraries, commands and daemons for the management side, tools for the build tooling including openconf, tests for the per guest bring-up instructions, and docs.

The openconf tool inside tools/openconf is itself part of the build, and there is a syntax reference file in the tree, tools/openconf/openconf_syntax.txt.

The guest level documentation is the other half, and it is organised by target rather than by feature. The guidelines required for running a guest OS on a particular type of guest, described as a combination of Guest CPU and Guest Board, live under tests/<Guest CPU>/<Guest Board>/README, and the readme asks you to refer to that README for detailed information on running a particular type of OS on a particular type of guest.

That structure is a real strength and a real cost. A developer porting to a new board has an exact document to follow, including the guest CPU and board combination. A developer who just wants to know how network virtualisation works has to read source.

The readme also says plainly that sometimes a guest OS may expect a specific type of hypervisor configuration at compile time, and that sometimes the guest OS may need patching for proper functioning under the hypervisor. That honesty is useful, because it tells you the compatibility work is not always free.

Configuring with a Linux style Kconfig

The build system is a deliberate copy of the Linux kernel's, and the readme makes a point of not letting you skip it.

Do not skip this step even if you are only upgrading one minor version. New configuration options are added in each release, and odd problems will turn up if the configuration files are not set up as expected. If you want to carry your existing configuration to a new version with minimal work, use make oldconfig, which only asks you for the answers to new questions.

The commands themselves are the kernel ones. To configure the hypervisor you use make <configuration_command>, or make O=<output_dir> <configuration_command> to put the output somewhere else. The available configuration commands are config, a plain text interface, menuconfig, text based colour menus with radiolists and dialogs, oldconfig, which defaults all questions based on the contents of your existing ./.config file and asks about new config symbols, and <xyz>_defconfig, which creates a ./.config file using the default values from arch/$ARCH/configs/<xyz>_defconfig.

The configuration system is Openconf, described as a modified version of Linux Kconfig. The motivation given is to get Xvisor specific information from environment variables, and to later extend the Kconfig syntax to check for dependent libraries and tools at configuration time. That second half is the interesting part: the configuration step can check whether the tools you need are present, which turns a link error at compile time into a question at configure time.

The output directory is handled with the same kernel convention. When compiling or configuring, all output files by default go to a directory called build in the hypervisor source directory, and the make O=<output_dir> option specifies an alternate place for the output files including the .config. The note is that if the O option is used then it must be used for all invocations of make, which is a small trap that produces a confusing build if you mix it.

The Makefile also guards against two footguns explicitly, erroring out if the build directory is the same as the source directory and if the install directory is the same as the source directory.

Which hosts it runs on, and what portability actually requires

The portability claim comes with a stated precondition, and it is a more useful one than a bare list of architectures.

The Xvisor source code is described as highly portable and as able to be easily ported to most general-purpose 32-bit or 64-bit architectures, as long as they have a paged memory management unit and a port of the GNU C compiler. So the two real requirements are a MMU and a GCC port. That is a short list, and it is the reason the project can claim ARMv7a-ve, ARMv8a, x86_64 and RISC-V support from one codebase: a type-1 hypervisor needs to trap and manage page tables, and everything else follows from the CPU interface.

The detailed and formatted list of supported host hardware is not in the readme. The readme tells you to refer to the HOSTS text file in the top level directory of the source code for it, and there is a HOSTS file at the repository root alongside the COPYING file, the Makefile, the MAINTAINERS file and the architecture directories.

That is a real characteristic of the project rather than an omission on the readme's part. The project explicitly prefers source level documentation, and a hardware support matrix maintained in a plain text file in the tree is a reasonable place for it, though it does mean you have to go and read it.

The tests directory, mentioned in the readme as holding the per guest CPU and guest board recipes, is a good companion to the HOSTS file, since between them they cover the host side and the guest side of what a new port has to satisfy. The arch directory is where the per architecture port lives, and the presence of an arch/$ARCH/configs directory referenced by the defconfig mechanism is what lets each architecture ship its own default configuration.

So the realistic picture is that a new host port means writing an architecture backend, a driver for the host's interrupt and timer hardware, and a set of configuration defaults, and that the HOSTS file and the tests tree are the two places to look for what has already been done.

Building, verbosity and the per guest tests

Compiling is a single make, or make O=<output_dir> to place the output elsewhere, and the requirement is at least gcc 4.x.

There is a verbosity mode for when the quiet build is not what you need. The build system normally runs in a fairly quiet mode, though not totally silent, and when you need to see compile, link and other commands exactly as they are executed, you insert VERBOSE=y in the make command:

	make VERBOSE=y

The Makefile in the repository shows how that is wired: a VERBOSE_DEFAULT and a CMD_PREFIX_DEFAULT, where the default command prefix is the at sign that suppresses command echoing, and an ifdef VERBOSE branch that changes it.

Then there is testing, and the word means something narrower than usual here. Configuring and compiling are common steps for any architecture, but that is not sufficient for running the hypervisor. The readme says we also need guidelines for configuring, compiling and running a guest OS in the hypervisor environment, and that the guidelines for a particular guest live under the tests directory keyed by guest CPU and guest board.

So the test suite is really a set of per-target recipes rather than an automated pass and fail. Some guest operating systems may expect a specific type of hypervisor configuration at compile time, and sometimes the guest OS may need patching for proper functioning under the hypervisor environment.

The top level Makefile also records the version, MAJOR 0, MINOR 3, RELEASE 2, and carries the copyright lines for Anup Patel and the Institut de Recherche Technologique SystemX and OpenWide contributions, including a modification by Jimmy Durand Wesolowski to improve the device tree dependency generation. That attribution is a good clue about the shape of the project, since the device tree dependency generation is exactly the sort of build tooling that a hypervisor needs and most people do not want to write.

The readme closes with the line it is known for, that it is all just for fun, and a happy hacking sign off.

Editorial conclusion

Adopt Xvisor if you are building or studying a hypervisor and want a type-1 design small enough to read, with a configuration system borrowed from the Linux kernel and a per architecture port layer you can follow. Do not adopt it as a general purpose virtualisation platform for production workloads, because the project presents itself as something for fun and publishes no releases, and expect a steeper curve than a packaged hypervisor, since guest bring-up is documented per guest CPU and board in the tests directory. Before you commit, read the HOSTS file for the hardware list, run the configuration step rather than skipping it, and pick the guest board whose README matches your target.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-2.0
3. Project website
4. README
5. xvisor/xvisor on GitHub