Repository files navigation

This repository hosts various 'vhost-user' device backends in their own crates.See their individual README.md files for specific information about thosecrates.

To be included here device backends must:

• be based on a publishedVIRTIO specification
• fulfil basic functionality requirements (in conjunction with a implemented driver)
• meet therust-vmm dev requirements

Here is the list of device backends that we support:

• CAN
• Console
• GPIO
• I2C
• Input
• RNG
• SCMI
• SCSI
• Sound
• SPI
• VSOCK

The vhost-device workspace also provides atemplateto help new developers understand how to write their own vhost-user backend.

Implementing a proper VirtIO device requires co-ordination between thespecification, drivers and backend implementations. As these can allbe in flux during development it was decided introducing a stagingworkspace which would allow developers to work within the main rust-vmmproject while clearly marking the backends as not production ready.

To be included in the staging workspace there must at least be:

• A public proposal to extend theVIRTIO specification
• A public implementation of a device driver
• Documentation pointing to the above

More information may be found in itsREADME file.

Here is the list of device backends instaging:

• Video
• GPU

Like the wider rust-vmm project we expect new features to come withcomprehensive code coverage. However as a multi-binary repositorythere are cases where avoiding a drop in coverage can be hard and anexception to the approach is allowable. These are:

• adding a new binary target (aim at least 60% overall coverage)
• expanding the main function (a small drop is acceptable)

However any new feature added to an existing binary should not cause adrop in coverage. The general aim should be to always improvecoverage.

The binaries built by this repository can be run with any VMM whichcan act as a vhost-user frontend. Typically they have been tested withQEMU although the rust-vmm project doesprovide avhost-userfrontendcrate for rust based VMMs.

While it's possible to implement all parts of the backend inside thevhost-device workspace consideration should be given to separating theVirtQueue handling and response logic to a device crate in thevm-virtio repository.This way a monolithic rust-vmm VMM implementation can reuse the corelogic to service the virtio requests directly in the application.

The GPIO crate needs a local installation of libgpiod library to be available.If your distro ships libgpiod >= v2.0, then you should be fine.

Otherwise, you will need to build libgpiod yourself:

git clone --depth 1 --branch v2.0.x https://git.kernel.org/pub/scm/libs/libgpiod/libgpiod.git/cd libgpiod./autogen.sh --prefix="$PWD/install/"make install

In order to inform tools about the build location, you can now set:

export PKG_CONFIG_PATH="<PATH-TO-LIBGPIOD>/install/lib/pkgconfig/"

To prevent setting this in every terminal session, you can also configurecargo toset it automatically.

Supporting Xen requires special handling while mapping the guest memory. Thevm-memory crate implements xen memory mapping support via a separate featurexen, and this crate uses the same feature name to enable Xen support.

It was decided by therust-vmm maintainers to keep the interface simple andbuild the crate for either standard Unix memory mapping or Xen, and not both.