From 9cac83921f59b572b69f18d1e06d5e138d5cc4fb Mon Sep 17 00:00:00 2001 From: Daniel Verkamp Date: Mon, 6 Jun 2022 16:33:01 -0700 Subject: [PATCH] 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 Commit-Queue: Keiichi Watanabe Reviewed-by: Keiichi Watanabe --- docs/book/src/devices/block.md | 103 ++++++++++++++++++++++++++++++++- 1 file changed, 102 insertions(+), 1 deletion(-) diff --git a/docs/book/src/devices/block.md b/docs/book/src/devices/block.md index fe4b79e642..6ce00f63fa 100644 --- a/docs/book/src/devices/block.md +++ b/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