Descriptors point to buffers
Virtio exchanges requests through defined queue structures. This lesson focuses on one split virtqueue. A descriptor describes a buffer’s address, length, direction, and possible chaining; it is not a copy of the complete payload. The model separately shows descriptors, buffers, and published indices. It teaches a request lifecycle without claiming real DMA or a complete virtio block device.
The first player provides a table of sixteen descriptors and uses three per request for header, data, and status. Three requests therefore allocate nine descriptors, leaving seven free. This is the chosen example, not a rule that every virtio request always needs three entries. Fixing the chain length makes the distinction between request count and resource count visible; a real driver derives its requirements from device type, negotiated features, and the actual buffer arrangement.
Finish preparation before publication
For example, descriptor 0 can describe request information and descriptor 1 a device-writable result area. Prepare buffer contents, addresses, lengths, directions, and chaining before publishing the head descriptor through the available ring. Publishing first could expose an incomplete request. The model separates those logical phases; a real implementation additionally needs the applicable memory-ordering guarantees.
For the three-descriptor example, publish each chain’s head rather than every member as an independent request. If request 0 uses 0→1→2 and request 1 uses 3→4→5, the available heads are 0 and 3. Treating all six numbers as unrelated requests loses the chain structure. The view therefore distinguishes chain head, total allocated descriptors, and request count. These are related values, but substituting one for another can misstate both ownership and queue capacity.
Available and used progress independently
The driver publishes requests through the available side, while the device reports completed work through the used side. In a queue of four entries, counters and slot positions are related by wrapping but are not the same quantity. Real split-ring indices also have fixed-width wrap rules. The small model displays positions, published counts, and completions separately rather than advancing both sides together.
The driver’s publication and the device’s completion reports have different writers. Use labels as well as visual styling to identify them. Even when the counters reach equal values, the driver can still have completion-processing and reclamation work remaining. The player separates publishing a used completion from reclaiming resources, exposing a state where work has been returned but descriptors have not yet been added back to the free pool. Queue progress and software housekeeping are related but distinct.
Notification is not completion
Notification tells the other side that work may be available. It does not mean processing has finished, and notification suppression or batching prevents assuming one notification per request. The trace separates publication, notification, device consumption, processing, and used-ring return. The buffer stays in flight after notification until completion is established.
With three requests and one notification, used.idx remains zero immediately after notification in this trace. Subsequent completion events advance it to one, two, and three. Pausing at those points distinguishes three outstanding requests from one completed request and two still outstanding. The model need not implement every notification-suppression detail to teach that temporal distinction, but it must not reinterpret the animation’s event count as a measurement of real interrupt frequency or device throughput.
| Phase | Responsible party | Reuse condition |
|---|---|---|
| Preparation | Driver | Manage before publication |
| Published in available | Device may reference buffers | Do not repurpose before completion |
| Notified, no used completion | Work may still be in flight | Do not reuse yet |
| Used completion checked and reclaimed | Driver | Reclaimed resources may be reused |
Keep resources alive while work is in flight
Reusing an in-flight result buffer as another request’s input can let a late device write corrupt the new request. Match completion to the right request before reclaiming its resources. Rust ownership can help express responsibility, but the language does not automatically know when an external device finishes. Software must connect the completion protocol to resource lifetime.
If two of three requests complete and are reclaimed, one three-descriptor request remains outstanding, leaving 16−3×1=13 free descriptors. The early-reuse variant rejects reclamation before completion and must not increase the free count. Checking resource arithmetic as well as a completion label catches a class of errors that a visually convincing success message would miss. It also makes the cost of retaining one outstanding request concrete without inventing a full allocator or a hardware measurement.
size = 16
descriptors_per_request = 3
published = 3
completed = 2
reclaimed = completed
outstanding = published - reclaimed
free = size - descriptors_per_request * outstanding
assert (outstanding, free) == (1, 13)
assert published - completed == 1
print('outstanding:', outstanding, 'free:', free)
Queue completion and durable storage differ
For a future block-device exercise, a used-ring return alone does not prove survival after power loss. Device cache and flush contracts matter, and operation-specific status must be interpreted before reporting application success. This first model teaches queue ownership and completion exchange; it does not measure persistence or storage failure behavior.
When operation-specific status is added, keep returned in used, request succeeded, and persistence established in separate fields. One check mark obscures the guarantee actually obtained. Reads and writes can also require different downstream interpretation. Complete the publication, return, and reclamation model first, then add device-specific status with an explicit boundary. This ordering avoids claiming durable storage or application-level success merely because the queue protocol has returned ownership of a descriptor chain.
Exercise: four requests published, three returned
Publish A, B, C, and D, notify once, then observe used completions for A, B, and C. Reclaim the resources whose completions have been matched; keep D’s resources alive. Neither one notification nor the other three completions establishes D’s status. Before publication, finish buffer contents, address, length, direction, chaining, and the required ordering.
As an additional exercise, select three requests with one left outstanding and calculate the free count after reclaiming the other two: thirteen descriptors. The remaining three cannot be reused. Then select premature reuse and explain its rejection using the in-flight lifetime diagram. Naming the request still available to an external actor is more informative than memorizing the number thirteen. That explanation connects the queue protocol to ownership, borrowing, and the need to model external completion explicitly.