docs: book: add --disk options

Document the various optional disk settings.

BUG=None
TEST=read mdbook

Change-Id: I0f797c840e35a7993d13386d2dc6e75e2898f854
Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/platform/crosvm/+/3691973
Tested-by: kokoro <noreply+kokoro@google.com>
Commit-Queue: Keiichi Watanabe <keiichiw@chromium.org>
Reviewed-by: Keiichi Watanabe <keiichiw@chromium.org>

docs/book/src/devices/block.md

@@ -25,4 +25,105 @@ To expose the block device as a read-only disk, you can use `--disk` instead of
 ## Rootfs
 
 If you use a block device as guest's rootfs, you can specify `--root` (for a read-only disk) or
-`--rwroot` (for writable disk). See `crosvm run --help` for the detailed usage.
+`--rwroot` (for writable disk). These options are equivalent to `--disk` or `--rwdisk`,
+respectively, except that the `root` variants automatically add a `root=/dev/vdX ro` kernel
+parameter with the corresponding virtio-block device name and read-only (`ro`) or read-write (`rw`)
+option.
+
+## Options
+
+The block device flags (`--disk`, `--rwdisk`, `--root`, and `--rwroot`) support additional options
+to enable features and control disk parameters. These may be specified as extra comma-separated
+`key=value` options appended to the required filename option. For example:
+
+```sh
+crosvm run
+  --disk disk.img,sparse=false,o_direct=true,block_size=4096,id=MYSERIALNO
+  ... # usual crosvm args
+```
+
+The available options are documented in the following sections.
+
+### Sparse
+
+- Syntax: `sparse=(true|false)`
+- Default: `sparse=true`
+
+The `sparse` option controls whether the disk exposes the thin provisioning `discard` command. If
+`sparse` is set to `true`, the `VIRTIO_BLK_T_DISCARD` request will be available, and it will be
+translated to the appropriate system call on the host disk image file (for example,
+`fallocate(FALLOC_FL_PUNCH_HOLE)` for raw disk images on Linux). If `sparse` is set to `false`, the
+disk will be fully allocated at startup (using [`fallocate()`] or equivalent on other platforms),
+and the `VIRTIO_BLK_T_DISCARD` request will not be supported for this device.
+
+### `O_DIRECT`
+
+- Syntax: `o_direct=(true|false)`
+- Default: `o_direct=false`
+
+The `o_direct` option enables the Linux `O_DIRECT` flag on the underlying disk image, indicating
+that I/O should be sent directly to the backing storage device rather than using the host page
+cache. This should only be used with raw disk images, not qcow2 or other formats. The `block_size`
+option may need to be adjusted to ensure that I/O is sufficiently aligned for the host block device
+and filesystem requirements.
+
+### Block size
+
+- Syntax: `block_size=BYTES`
+- Default: `block_size=512`
+
+The `block_size` option overrides the reported block size (also known as sector size) of the
+virtio-block device. This should be a power of two larger than or equal to 512.
+
+### ID
+
+- Syntax: `id=DISK_ID`
+- Default: No identifier
+
+The `id` option provides the virtio-block device with a unique identifier. The `DISK_ID` string must
+be 20 or fewer ASCII printable characters. The `id` may be used by the guest environment to uniquely
+identify a specific block device rather than making assumptions about block device names.
+
+The Linux virtio-block driver exposes the disk identifer in a `sysfs` file named `serial`; an
+example path looks like `/sys/devices/pci0000:00/0000:00:02.0/virtio1/block/vda/serial` (the PCI
+address may differ depending on which other devices are enabled).
+
+## Resizing
+
+The crosvm block device supports run-time resizing. This can be accomplished by starting crosvm with
+the `-s` control socket, then using the `crosvm disk` command to send a resize request:
+
+`crosvm disk resize DISK_INDEX NEW_SIZE VM_SOCKET`
+
+- `DISK_INDEX`: 0-based index of the block device (counting all `--disk`, `--root`, and `rw`
+  variants in order).
+- `NEW_SIZE`: desired size of the disk image in bytes.
+- `VM_SOCKET`: path to the VM control socket specified when running crosvm (`-s`/`--socket` option).
+
+For example:
+
+```sh
+# Create a 1 GiB disk image
+truncate -s 1G disk.img
+
+# Run crosvm with a control socket
+crosvm run \
+  --rwdisk disk.img,sparse=false \
+  -s /tmp/crosvm.sock \
+  ... # other crosvm args
+
+# In another shell, extend the disk image to 2 GiB.
+crosvm disk resize \
+  0 \
+  $((2 * 1024 * 1024 * 1024)) \
+  /tmp/crosvm.sock
+
+# The guest OS should recognize the updated size and log a message:
+#   virtio_blk virtio1: [vda] new size: 4194304 512-byte logical blocks (2.15 GB/2.00 GiB)
+```
+
+The `crosvm disk resize` command only resizes the block device and its backing disk image. It is the
+responsibility of the VM socket user to perform any partition table or filesystem resize operations,
+if required.
+
+[`fallocate()`]: https://man7.org/linux/man-pages/man2/fallocate.2.html#DESCRIPTION