Crate vmbus_ring

This module implements the low-level interface to the VmBus ring buffer. The ring buffer resides in guest memory and is mapped into the host, allowing efficient transfer of variable-sized packets.

Ring buffer packets have headers called descriptors, which can specify a transaction ID and metadata referring to memory outside the ring buffer. Each packet is a multiple of 8 bytes.

In practice, ring buffers always come in pairs so that packets can be both sent and received. However, this module’s interfaces operate on them singly.

Modules

• gparange

Structs

• FlatRingMem
  An implementation of RingMem over a flat allocation. Useful for tests.
• IncomingOffset
  The current incoming ring state.
• IncomingPacket
  An incoming packet.
• IncomingRing
  The interface to the receiving endpoint of a ring buffer.
• OutgoingOffset
  An outgoing ring offset, used to determine the position to write packets to.
• OutgoingPacket
  Information about an outgoing packet.
• OutgoingRing
  The sending side of a ring buffer.
• PacketSize
  Namespace type with methods to compute packet sizes, for use with set_pending_send_size.
• PagedRingMem
  An implementation of RingMem on top of discontiguous pages.
• PipeHeader
  Pipe channel packets are prefixed with this header to allow for non-8-multiple lengths.
• RingRange
  A range within a ring buffer.
• RingRangeReader
  A type implementing MemoryRead accessing a RingRange.
• RingRangeWriter
  A type implementing MemoryWrite accessing a RingRange.
• TransferPageRange
  A transfer range specifying a length and offset within a transfer page set. Only used by NetVSP.

Enums

• Error
• IncomingPacketType
  The alternate types of incoming packets. For packets with external data, includes a RingRange whose data is the variable portion of the packet descriptor.
• OutgoingPacketType
  The outgoing packet type variants.
• ReadError
• WriteError

Constants

• CONTROL_WORD_COUNT
  The size of the control region in 32-bit words.
• MAXIMUM_PIPE_PACKET_SIZE
  The maximum size of a pipe packet’s payload.
• PAGE_SIZE
  VmBus ring buffers are sized in multiples 4KB pages, with a 4KB control page.
• PIPE_PACKET_TYPE_DATA
  Regular data packet.
• PIPE_PACKET_TYPE_PARTIAL
  Data packet that has been partially consumed, in which case the len field’s high word is the number of bytes already read. The opposite endpoint will never write this type.
• PIPE_PACKET_TYPE_SETUP_GPA_DIRECT
  Setup a GPA direct buffer for RDMA.
• PIPE_PACKET_TYPE_TEARDOWN_GPA_DIRECT
  Tear down a GPA direct buffer.

Traits

• PagedMemory
  A trait for ring buffer memory divided into discontiguous pages.
• Ring
  A trait shared by the incoming and outgoing ring buffers. Used primarily with RingRange::reader and RingRange::writer.
• RingMem
  A trait for memory backing a ring buffer.

Functions

• inspect_ring
  Inspects ring buffer state without creating an IncomingRing or OutgoingRing structure.
• reader_needs_signal
  Returns whether a ring buffer is in a state where the receiving end might need a signal.
• writer_needs_signal
  Returns whether a ring buffer is in a state where the sending end might need a signal.