Crate scsi_buffers 

Guest memory buffer abstractions for storage IO.

This crate provides RequestBuffers, the primary type used by disk backends to access guest memory during IO operations. It wraps a [PagedRange] (a single contiguous byte range across guest pages) with direction flags and provides:

• Byte-level streaming via reader() / writer()
• DMA-ready locked buffers via lock()
• Alignment checking via is_aligned()

Alignment and bounce buffering

Disk backends that use direct IO (O_DIRECT, io_uring) require buffers to be aligned to the disk’s sector size. When guest-provided buffers are not aligned, a BounceBuffer is used: data is copied to/from a page-aligned temporary buffer for the actual disk IO.

BounceBufferTracker manages a per-thread page budget to limit memory consumption from concurrent bounce-buffered IOs.

Important: PagedRange constraints

RequestBuffers wraps a single PagedRange, which can only represent a contiguous byte range where interior pages are fully covered (see [PagedRange] docs). This means:

• You cannot combine two guest memory regions with arbitrary GPAs into one RequestBuffers unless every boundary falls on a page boundary.
• When a device (e.g., virtio-blk) receives multiple descriptors forming a scatter-gather list, each descriptor typically gets its own RequestBuffers. If a descriptor boundary falls mid-sector, bounce buffering or coalescing is needed to issue correct IO.

Structs

AtomicIoVec

A pointer/length pair that is ABI compatible with the iovec type on Linux.

BounceBuffer

A page-aligned temporary buffer used to double-buffer IO data.

BounceBufferTracker

Tracks active bounce buffers against a set limit of pages. If no limit is specified a default of 8Mb will be applied. This limit is tracked per thread specified by the backing AffinitizedThreadpool.

IoBuffer

Wrapper around an &AtomicU8 guaranteed to be ABI compatible with the iovec type on Linux.

LockedIoBuffers

A set of locked memory ranges, represented by IoBuffers.

OwnedRequestBuffers

A memory range.

RequestBuffers

An accessor for guest memory associated with a storage IO request.

TrackedBounceBuffer

Tracks an active bounce buffer, signaling to the bounce buffer tracker upon drop that pages can be reclaimed.