Add vhost-user-sound crate

Cargo.toml

@@ -4,5 +4,7 @@ members = [
     "crates/gpio",
     "crates/i2c",
     "crates/rng",
+    "crates/scsi",
+    "crates/sound",
     "crates/vsock",
 ]

README.md

@@ -11,6 +11,7 @@ Here is the list of device backends that we support:
 - [GPIO](https://github.com/rust-vmm/vhost-device/blob/main/crates/gpio/README.md)
 - [I2C](https://github.com/rust-vmm/vhost-device/blob/main/crates/i2c/README.md)
 - [RNG](https://github.com/rust-vmm/vhost-device/blob/main/crates/rng/README.md)
+- [Sound](https://github.com/rust-vmm/vhost-device/blob/main/crates/sound/README.md)
 - [VSOCK](https://github.com/rust-vmm/vhost-device/blob/main/crates/vsock/README.md)
 
 ## Testing and Code Coverage
@@ -45,14 +46,20 @@ logic to service the virtio requests directly in the application.
 
 ## Build dependency
 
-The GPIO crate needs a local installation of libgpiod library to be available,
-which can be done like:
+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.
 
-$ git clone --depth 1 --branch v2.0-rc1 https://git.kernel.org/pub/scm/libs/libgpiod/libgpiod.git/
-$ cd libgpiod
-$ ./autogen.sh && make
+Otherwise, you will need to build libgpiod yourself:
 
-Either you can do a 'make install' now on your system, or provide path to the
-locally build library like this while building vhost-device crates:
+    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
 
-$ RUSTFLAGS='-L /home/<username>/libgpiod/lib/.libs/'  cargo build --release
+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 configure
+cargo to
+[set it automatically](https://doc.rust-lang.org/cargo/reference/config.html#env).

coverage_config_x86_64.json

@@ -1,5 +1,5 @@
 {
-  "coverage_score": 67.6,
+  "coverage_score": 69.6,
   "exclude_path": "",
   "crate_features": ""
 }

crates/gpio/Cargo.toml

@@ -12,21 +12,21 @@ edition = "2021"
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]
-clap = { version = "4.1",  features = ["derive"] }
+clap = { version = "4.3",  features = ["derive"] }
 env_logger = "0.10"
 libc = "0.2"
 log = "0.4"
 thiserror = "1.0"
-vhost = { version = "0.6", features = ["vhost-user-slave"] }
-vhost-user-backend = "0.8"
-virtio-bindings = "0.2"
-virtio-queue = "0.7"
-vm-memory = "0.10"
+vhost = { version = "0.7", features = ["vhost-user-slave"] }
+vhost-user-backend = "0.9"
+virtio-bindings = "0.2.1"
+virtio-queue = "0.8"
+vm-memory = "0.11"
 vmm-sys-util = "0.11"
 
 [target.'cfg(target_env = "gnu")'.dependencies]
-libgpiod = { git = "https://git.kernel.org/pub/scm/libs/libgpiod/libgpiod.git/", rev = "d8d3a84b2ddf" }
+libgpiod = { version = "0.1" }
 
 [dev-dependencies]
-virtio-queue = { version = "0.7", features = ["test-utils"] }
-vm-memory = { version = "0.10", features = ["backend-mmap", "backend-atomic"] }
+virtio-queue = { version = "0.8", features = ["test-utils"] }
+vm-memory = { version = "0.11", features = ["backend-mmap", "backend-atomic"] }

crates/gpio/LICENSE-APACHE

@@ -0,0 +1 @@
+../../LICENSE-APACHE

crates/gpio/LICENSE-BSD-3-Clause

@@ -0,0 +1 @@
+../../LICENSE-BSD-3-Clause

crates/i2c/Cargo.toml

@@ -12,18 +12,18 @@ edition = "2021"
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]
-clap = { version = "4.1",  features = ["derive"] }
+clap = { version = "4.3",  features = ["derive"] }
 env_logger = "0.10"
 libc = "0.2"
 log = "0.4"
 thiserror = "1.0"
-vhost = { version = "0.6", features = ["vhost-user-slave"] }
-vhost-user-backend = "0.8"
-virtio-bindings = "0.2"
-virtio-queue = "0.7"
-vm-memory = "0.10"
+vhost = { version = "0.7", features = ["vhost-user-slave"] }
+vhost-user-backend = "0.9"
+virtio-bindings = "0.2.1"
+virtio-queue = "0.8"
+vm-memory = "0.11"
 vmm-sys-util = "0.11"
 
 [dev-dependencies]
-virtio-queue = { version = "0.7", features = ["test-utils"] }
-vm-memory = { version = "0.10", features = ["backend-mmap", "backend-atomic"] }
+virtio-queue = { version = "0.8", features = ["test-utils"] }
+vm-memory = { version = "0.11", features = ["backend-mmap", "backend-atomic"] }

crates/i2c/LICENSE-APACHE

@@ -0,0 +1 @@
+../../LICENSE-APACHE

crates/i2c/LICENSE-BSD-3-Clause

@@ -0,0 +1 @@
+../../LICENSE-BSD-3-Clause

crates/rng/Cargo.toml

@@ -10,21 +10,21 @@ license = "Apache-2.0 OR BSD-3-Clause"
 edition = "2021"
 
 [dependencies]
-clap = { version = "4.1",  features = ["derive"] }
+clap = { version = "4.3",  features = ["derive"] }
 env_logger = "0.10"
 epoll = "4.3"
 libc = "0.2"
 log = "0.4"
 rand = "0.8.5"
-tempfile = "3.4"
+tempfile = "3.5"
 thiserror = "1.0"
-vhost = { version = "0.6", features = ["vhost-user-slave"] }
-vhost-user-backend = "0.8"
-virtio-bindings = "0.2"
-virtio-queue = "0.7"
-vm-memory = "0.10"
+vhost = { version = "0.7", features = ["vhost-user-slave"] }
+vhost-user-backend = "0.9"
+virtio-bindings = "0.2.1"
+virtio-queue = "0.8"
+vm-memory = "0.11"
 vmm-sys-util = "0.11"
 
 [dev-dependencies]
-virtio-queue = { version = "0.7", features = ["test-utils"] }
-vm-memory = { version = "0.10", features = ["backend-mmap", "backend-atomic"] }
+virtio-queue = { version = "0.8", features = ["test-utils"] }
+vm-memory = { version = "0.11", features = ["backend-mmap", "backend-atomic"] }

crates/rng/LICENSE-APACHE

@@ -0,0 +1 @@
+../../LICENSE-APACHE

crates/rng/LICENSE-BSD-3-Clause

@@ -0,0 +1 @@
+../../LICENSE-BSD-3-Clause

crates/scsi/ARCHITECTURE.md

@@ -0,0 +1,39 @@
+# vhost-user-scsi architecture
+
+Rough outline of the different pieces and how they fit together:
+
+## `scsi/mod.rs`
+
+This defines the `Target` trait, which represents a SCSI target. The code in
+this file is independent from:
+
+- A particular SCSI implementation: Currently, we have one implementation of
+  `Target`, which emulates the SCSI commands itself; but future implementations
+  could provide pass-through to an iSCSI target or SCSI devices attached to the
+  host.
+- A particular SCSI transport: Nothing in `src/scsi/*` knows anything about
+  virtio; this is helpful for maintainability, and also allows our SCSI
+  emulation code to be reusable as, for example, an iSCSI target. To this end,
+  the `Target` trait is generic over a `Read` and `Write` that it uses for SCSI
+  data transfer. This makes testing easy: we can just provide a `Vec<u8>` to
+  write into.
+
+## `scsi/emulation/*.rs`
+
+This is the SCSI emulation code, which forms the bulk of the crate. It provides
+`EmulatedTarget`, an implementation of `Target`. `EmulatedTarget`, in turn,
+looks at the LUN and delegates commands to an implementation of `LogicalUnit`.
+In most cases, this will be `BlockDevice`; there's also `MissingLun`, which is
+used for responding to commands to invalid LUNs.
+
+Currently, there is no separation between commands defined in the SPC standard
+(commands shared by all device types) and the SBC standard (block-device
+specific commands). If we ever implemented another device type (CD/DVD seems
+most likely), we'd want to separate those out.
+
+As noted above, the emulation code knows nothing about virtio.
+
+## `src/{main,virtio}.rs`
+
+This code handles vhost-user, virtio, and virtio-scsi; it's the only part of
+the crate that knows about these protocols.

crates/scsi/CHANGELOG.md

@@ -0,0 +1,3 @@
+# Upcoming Release
+
+- First initial daemon implementation.

crates/scsi/Cargo.toml

@@ -0,0 +1,30 @@
+[package]
+name = "vhost-device-scsi"
+version = "0.1.0"
+authors = ["Gaelan Steele <[email protected]>", "Erik Schilling <[email protected]>"]
+description = "vhost scsi backend device"
+repository = "https://github.com/rust-vmm/vhost-device"
+readme = "README.md"
+keywords = ["scsi", "vhost", "virt", "backend"]
+license = "Apache-2.0 OR BSD-3-Clause"
+edition = "2021"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+clap = { version = "4.3",  features = ["derive"] }
+env_logger = "0.10"
+epoll = "4.3"
+log = "0.4"
+num_enum = "0.5"
+thiserror = "1.0"
+vhost = { version = "0.7", features = ["vhost-user-slave"] }
+vhost-user-backend = "0.9"
+virtio-bindings = "0.2.1"
+virtio-queue = "0.8"
+vm-memory = "0.11"
+vmm-sys-util = "0.11"
+
+[dev-dependencies]
+tempfile = "3.2.0"
+

crates/scsi/LICENSE-APACHE

@@ -0,0 +1 @@
+../../LICENSE-APACHE

crates/scsi/LICENSE-BSD-3-Clause

@@ -0,0 +1 @@
+../../LICENSE-BSD-3-Clause

crates/scsi/README.md

@@ -0,0 +1,48 @@
+# vhost-user-scsi
+
+This is a Rust implementation of a vhost-user-scsi daemon.
+
+## Usage
+
+Run the vhost-user-scsi daemon:
+
+```
+vhost-user-scsi -r --socket-path /tmp/vhost-user-scsi.sock /path/to/image.raw /path/to/second-image.raw ...
+```
+
+Run QEMU:
+
+```
+qemu-system-x86_64 ... \
+  -device vhost-user-scsi-pci,num_queues=1,param_change=off,chardev=vus \
+  -chardev socket,id=vus,path=/tmp/vhost-user-scsi.sock \
+  # must match total guest meory
+  -object memory-backend-memfd,id=mem,size=384M,share=on \
+  -numa node,memdev=mem
+```
+
+## Limitations
+
+We are currently only supporting a single request queue and do not support
+dynamic reconfiguration of LUN parameters (VIRTIO_SCSI_F_CHANGE).
+
+## Features
+
+This crate is a work-in-progress. Currently, it's possible to mount and read
+up to 256 read-only raw disk images. Some features we might like to add
+at some point, roughly ordered from sooner to later:
+
+- Write support. This should just be a matter of implementing the WRITE
+  command, but there's a bit of complexity around writeback caching we
+  need to make sure we get right.
+- Support more LUNs. virtio-scsi supports up to 16384 LUNs per target.
+  After 256, the LUN encoding format is different; it's nothing too
+  complicated, but I haven't gotten around to implementing it.
+- Concurrency. Currently, we process SCSI commands one at a time. Eventually,
+  it'd be a good idea to use threads or some fancy async/io_uring stuff to
+  concurrently handle multiple commands. virtio-scsi also allows for multiple
+  request queues, allowing the guest to submit requests from multiple cores
+  in parallel; we should support that.
+- iSCSI passthrough. This shouldn't be too bad, but it might be a good idea
+  to decide on a concurrency model (threads or async) before we spend too much
+  time here.