scsi: Add documentation

Co-developed-by: Erik Schilling <[email protected]>
Signed-off-by: Erik Schilling <[email protected]>
Signed-off-by: Gaelan Steele <[email protected]>

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/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 /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 sumbit 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
+  decide on a concurrency model (threads or async) before we spend too much
+  time here.