docs: document threaded block and multiqueue

Describe threaded processing, multiqueue limits, and worker resources.

Document seccomp requirements and partial updates across queues.

Signed-off-by: Pierre Bertholom <pbertho@amazon.com>

Author: PierreBertholom

docs/api_requests/patch-block.md

@@ -19,7 +19,9 @@ guest driver which will update the size of the raw block device. With that being
 said, a sequence which performs resizing/altering of the block underlying host
 file followed by a PATCH /drives API call is not an atomic operation as the
 guest can also modify the block file via emulation during the sequence, if the
-raw block device is mounted or accessible.
+raw block device is mounted or accessible. Multiqueue follows the same update
+path, but Firecracker updates each queue separately, so in-flight I/O can
+observe a partially updated device.
 
 ### Supported use case
 

docs/block.md

@@ -91,6 +91,50 @@ The `io_engine` field selects the host-side IO backend:
 
 See [block-io-engine.md](api_requests/block-io-engine.md) for more information.
 
+### Threaded Mode and Multiqueue
+
+By default, Firecracker processes block requests on the VMM thread and exposes
+one queue for each drive. Set `threaded` to `true` to process each queue on a
+dedicated host worker thread. Threaded mode supports both the `Sync` and `Async`
+IO engines. This moves block processing off the VMM thread. Multiple queues let
+Firecracker process requests from separate queues in parallel.
+
+The `num_queues` field sets the number of queues that Firecracker exposes to the
+guest. Its default value is `1`. A value greater than `1` enables virtio-blk
+multiqueue and requires `threaded` to be `true`. The queue count cannot exceed
+the configured vCPU count. Firecracker also rejects a machine configuration
+update that would reduce the vCPU count below an existing drive's queue count.
+
+Firecracker creates one worker thread for each configured queue, including
+queues that the guest does not use. All queues share the drive's rate limiter,
+so its limits apply to the total traffic for the drive.
+
+Each worker thread is named `fc_q<index>_<drive_id>`, for example `fc_q0_data`.
+Linux limits thread names to 15 bytes, so longer names are truncated in tools
+that read the kernel thread name (`top`, `ps`, `perf`, ...). The queue index
+comes first so truncation applies to the end of the `drive_id`. Drives whose
+`drive_id` share a long prefix might still collide. Firecracker logs keep the
+full name. To keep names distinct across drives, use a `drive_id` of at most 9
+bytes when using up to 10 queues, and at most 8 bytes for more than 10 queues.
+
+The following configuration creates a drive with 4 queues and 4 worker threads:
+
+```json
+{
+    "drive_id": "data",
+    "path_on_host": "./data.ext4",
+    "is_root_device": false,
+    "is_read_only": false,
+    "threaded": true,
+    "num_queues": 4
+}
+```
+
+The microVM must have at least 4 vCPUs before Firecracker accepts this drive. If
+a custom seccomp filter is used, it must include the `blk_worker` thread
+category described in the
+[seccompiler documentation](seccompiler.md#json-file-format).
+
 ### Read-only Devices
 
 Setting `is_read_only` to `true` causes Firecracker to open the backing file