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.

SingleMappedRingMem

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.