1# Block 2 3crosvm supports 4[virtio-block](https://docs.oasis-open.org/virtio/virtio/v1.1/csprd01/virtio-v1.1-csprd01.html#x1-2390002) 5device that works as a disk for the guest. 6 7First, create a ext4 (or whatever file system you want) disk file. 8 9```sh 10fallocate -l 1G disk.img 11mkfs.ext4 disk.img 12``` 13 14Then, pass it with `--block` flag so the disk will be exposed as `/dev/vda`, `/dev/vdb`, etc. The 15device can be mounted with the `mount` command. 16 17```sh 18crosvm run \ 19 --block disk.img 20 ... # usual crosvm args 21``` 22 23To expose the block device as a read-only disk, you can add the `ro` flag after the disk image path: 24 25```sh 26crosvm run \ 27 --block disk.img,ro 28 ... # usual crosvm args 29``` 30 31## Rootfs 32 33If you use a block device as guest's rootfs, you can add the `root` flag to the `--block` parameter: 34 35```sh 36crosvm run \ 37 --block disk.img,root 38 ... # usual crosvm args 39``` 40 41This flag automatically adds a `root=/dev/vdX` kernel parameter with the corresponding virtio-block 42device name and read-only (`ro`) or read-write (`rw`) option depending on whether the `ro` flag has 43also been specified or not. 44 45## Options 46 47The `--block` parameter support additional options to enable features and control disk parameters. 48These may be specified as extra comma-separated `key=value` options appended to the required 49filename option. For example: 50 51```sh 52crosvm run 53 --block disk.img,ro,sparse=false,o_direct=true,block_size=4096,id=MYSERIALNO 54 ... # usual crosvm args 55``` 56 57The available options are documented in the following sections. 58 59### Sparse 60 61- Syntax: `sparse=(true|false)` 62- Default: `sparse=true` 63 64The `sparse` option controls whether the disk exposes the thin provisioning `discard` command. If 65`sparse` is set to `true`, the `VIRTIO_BLK_T_DISCARD` request will be available, and it will be 66translated to the appropriate system call on the host disk image file (for example, 67`fallocate(FALLOC_FL_PUNCH_HOLE)` for raw disk images on Linux). If `sparse` is set to `false`, the 68disk will be fully allocated at startup (using [`fallocate()`] or equivalent on other platforms), 69and the `VIRTIO_BLK_T_DISCARD` request will not be supported for this device. 70 71### `O_DIRECT` 72 73- Syntax: `o_direct=(true|false)` 74- Default: `o_direct=false` 75 76The `o_direct` option enables the Linux `O_DIRECT` flag on the underlying disk image, indicating 77that I/O should be sent directly to the backing storage device rather than using the host page 78cache. This should only be used with raw disk images, not qcow2 or other formats. The `block_size` 79option may need to be adjusted to ensure that I/O is sufficiently aligned for the host block device 80and filesystem requirements. 81 82### Block size 83 84- Syntax: `block_size=BYTES` 85- Default: `block_size=512` 86 87The `block_size` option overrides the reported block size (also known as sector size) of the 88virtio-block device. This should be a power of two larger than or equal to 512. 89 90### ID 91 92- Syntax: `id=DISK_ID` 93- Default: No identifier 94 95The `id` option provides the virtio-block device with a unique identifier. The `DISK_ID` string must 96be 20 or fewer ASCII printable characters. The `id` may be used by the guest environment to uniquely 97identify a specific block device rather than making assumptions about block device names. 98 99The Linux virtio-block driver exposes the disk identifer in a `sysfs` file named `serial`; an 100example path looks like `/sys/devices/pci0000:00/0000:00:02.0/virtio1/block/vda/serial` (the PCI 101address may differ depending on which other devices are enabled). 102 103## Resizing 104 105The crosvm block device supports run-time resizing. This can be accomplished by starting crosvm with 106the `-s` control socket, then using the `crosvm disk` command to send a resize request: 107 108`crosvm disk resize DISK_INDEX NEW_SIZE VM_SOCKET` 109 110- `DISK_INDEX`: 0-based index of the block device (counting all `--block` in order). 111- `NEW_SIZE`: desired size of the disk image in bytes. 112- `VM_SOCKET`: path to the VM control socket specified when running crosvm (`-s`/`--socket` option). 113 114For example: 115 116```sh 117# Create a 1 GiB disk image 118truncate -s 1G disk.img 119 120# Run crosvm with a control socket 121crosvm run \ 122 --block disk.img,sparse=false \ 123 -s /tmp/crosvm.sock \ 124 ... # other crosvm args 125 126# In another shell, extend the disk image to 2 GiB. 127crosvm disk resize \ 128 0 \ 129 $((2 * 1024 * 1024 * 1024)) \ 130 /tmp/crosvm.sock 131 132# The guest OS should recognize the updated size and log a message: 133# virtio_blk virtio1: [vda] new size: 4194304 512-byte logical blocks (2.15 GB/2.00 GiB) 134``` 135 136The `crosvm disk resize` command only resizes the block device and its backing disk image. It is the 137responsibility of the VM socket user to perform any partition table or filesystem resize operations, 138if required. 139 140[`fallocate()`]: https://man7.org/linux/man-pages/man2/fallocate.2.html#DESCRIPTION 141