doc(block): document VIRTIO_BLK_F_WRITE_ZEROES support

Add docs/api_requests/block-write-zeroes.md describing:
  - automatic advertisement on writable devices
  - UNMAP=0 → FALLOC_FL_ZERO_RANGE (zeros in place)
  - UNMAP=1 → FALLOC_FL_PUNCH_HOLE (zeros + deallocate)
  - host filesystem requirements
  - EOPNOTSUPP fallback (silent VIRTIO_BLK_S_UNSUPP, shared cache)
  - known limitations

Remove the "write_zeroes is not supported" line from block-discard.md
now that the feature is implemented.

Signed-off-by: Nikita Kalyazin <nikita.kalyazin@e2b.dev>

Author: kalyazin

docs/api_requests/block-discard.md

@@ -40,5 +40,3 @@ discard requests with `VIRTIO_BLK_S_UNSUPP` immediately — no additional
 - At most one discard segment per request is supported (`max_discard_seg = 1`).
 - The discard segment flags field must be zero; non-zero flags are rejected with
   an I/O error.
-- The `write_zeroes` variant of the feature (`VIRTIO_BLK_T_WRITE_ZEROES`) is not
-  supported.

docs/api_requests/block-write-zeroes.md

@@ -0,0 +1,61 @@
+# Block device write-zeroes
+
+Firecracker supports the `VIRTIO_BLK_F_WRITE_ZEROES` feature, which allows the
+guest to ask the device to zero a range of sectors without transferring a buffer
+of zeros over the virtqueue. Common consumers are `mkfs` (clearing inode tables
+and journals), filesystem snapshots, encrypted-volume initial wipe, and
+`blkdiscard -z` / `blkzeroout` from userspace.
+
+## How it works
+
+For all non-read-only block devices, Firecracker automatically advertises the
+`VIRTIO_BLK_F_WRITE_ZEROES` feature to the guest driver. No API configuration
+is required — write-zeroes support is always-on for writable drives.
+
+Each `VIRTIO_BLK_T_WRITE_ZEROES` request carries a 16-byte segment with a
+`flags` field. Bit 0 (`VIRTIO_BLK_WRITE_ZEROES_FLAG_UNMAP`) tells the device
+whether it may also deallocate the underlying backing-file blocks. Firecracker
+advertises `write_zeroes_may_unmap=1`, so guests are free to set this flag.
+
+Firecracker translates the guest's UNMAP bit into a `fallocate(2)` mode on the
+backing file:
+
+| UNMAP | fallocate mode                              | Effect                                |
+|-------|---------------------------------------------|---------------------------------------|
+| 0     | `FALLOC_FL_ZERO_RANGE \| FALLOC_FL_KEEP_SIZE` | zeros in place, no deallocation     |
+| 1     | `FALLOC_FL_PUNCH_HOLE \| FALLOC_FL_KEEP_SIZE` | zeros + deallocate (sparse holes)   |
+
+The virtio spec requires that when UNMAP is clear the device MUST NOT
+deallocate sectors (so `ZERO_RANGE` is mandatory for that path); when UNMAP
+is set, the device MAY deallocate, and `PUNCH_HOLE` reads as zeros on every
+filesystem that supports it.
+
+## Host requirements
+
+The backing file must reside on a filesystem that supports the corresponding
+`fallocate` mode:
+
+- `FALLOC_FL_PUNCH_HOLE` (UNMAP=1) is widely supported: ext4, xfs, btrfs, tmpfs.
+- `FALLOC_FL_ZERO_RANGE` (UNMAP=0) is supported on ext4, xfs, btrfs; on tmpfs
+  it requires Linux 6.8+. Other filesystems may not support it.
+
+If `fallocate` returns `EOPNOTSUPP` for either mode, Firecracker logs a one-time
+warning and replies with `VIRTIO_BLK_S_UNSUPP`. The Linux virtio-blk driver
+propagates that status through the block layer and stops issuing further
+write-zeroes requests, so subsequent guest writes fall back to plain
+`REQ_OP_WRITE` traffic. Firecracker short-circuits any in-flight write-zeroes
+requests with `VIRTIO_BLK_S_UNSUPP` for the rest of the device's lifetime — no
+additional `fallocate` calls are made.
+
+The EOPNOTSUPP cache is shared across UNMAP=0 and UNMAP=1 paths: a single
+fallback flag disables both. This is conservative — a filesystem that
+supports `PUNCH_HOLE` but not `ZERO_RANGE` will see UNMAP=1 requests rejected
+once an UNMAP=0 request fails — but it matches the discard fallback design
+and avoids subtle host-side state.
+
+## Limitations
+
+- Write-zeroes is only available for non-read-only block devices.
+- At most one segment per request is supported (`max_write_zeroes_seg = 1`).
+- Only bit 0 (UNMAP) of the segment flags is allowed; non-zero reserved bits
+  are rejected with an I/O error.