Study guides · Advanced

One virtqueue round trip: publish, complete, and reclaim

Follow split-ring descriptors, available and used entries, and buffer ownership without confusing notification with completion.

Ask Logeia about this articleTry the three questionsReview your answers

Updated

On this page
  1. Descriptors point to buffers
  2. Finish preparation before publication
  3. Available and used progress independently
  4. Notification is not completion
  5. Keep resources alive while work is in flight
  6. Queue completion and durable storage differ
  7. Exercise: four requests published, three returned
  8. Ask Logeia about this articleCheck your understanding

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.

PhaseResponsible partyReuse condition
PreparationDriverManage before publication
Published in availableDevice may reference buffersDo not repurpose before completion
Notified, no used completionWork may still be in flightDo not reuse yet
Used completion checked and reclaimedDriverReclaimed 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.

python
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.

Try the interactive model

Requests and completions in virtqueue

Loading demo checkpoint…

Reading and practice are recorded separately in this browser, for each language.

Choose a learning path