Module virtio_device::chain

Descriptor chain walking.

The goal of the ReadableChain and WritableChain is to present a byte-wise view of the descriptor chain, and facilitate safe reading and writing to the chain.

Although walking these chains feels similar to using an iterator, the chains do not directly implement the std::iter::Iterator trait as iterator composition works against being able to then convert a ReadableChain into a WritableChain. An iterator can be built on top of these interfaces, but it has not been done here yet.

In addition to walking byte ranges via the next or [next_with_limit] (ReadableChain::next_with_limit) methods, the Read and [Write] (std::io::Write) traits are implemented for ReadableChain and WritableChain respectively.

When using the std::io::Write interface for the WritableChain the amount written is tracked, alleviating the need to manually perform add_written. Although not always appropriate depending on the particular virtio device, the Read/Write interfaces are therefore the preferred way to manipulate the chains.

The requirement from the virtio specification that all readable descriptors occur before all writable descriptors is enforced here, with explicit types that indicate what is being walked. Transitioning from the ReadableChain to the WritableChain is an explicit operation that allows for optional checking to ensure all readable descriptors have been consumed. This allows devices to easily check if the driver is violating any protocol assumptions on descriptor layouts.

Structs

• ReadableChain
  Access the readable portion of a descriptor chain.
• Remaining
• WritableChain
  Access the writable portion of a descriptor chain.

Enums

• ChainCompleteError
  Errors resulting from completing a chain.
• ChainError
  Errors from walking a descriptor chain.