Module protocol 

This module defines the communication protocol over the VMOs shared between the filesystem (Fxfs), the block driver (block_server), and the client/verifier (e.g., pkg-cache). The two VMOs (mapping queue and delivery queue) are provided to fuchsia.storage.block/Mapper.OpenSession to initialize a session.

Two main channels of communication exist for paging:

1. Mapping Queue (RawMappingCommand): Direction: Filesystem (Fxfs) -> Driver (Established via the client during initialization) Purpose: The filesystem informs the driver of where a file resides on the storage device (its extents). When the driver receives a page fault from the kernel for a specific key, it consults this mapping to know which blocks to read from disk.

2. Delivery Queue (RawDeliveryCommand): Direction: Driver -> Client/Verifier (e.g., pkg-cache, which also acts as the Pager) Purpose: After the driver reads (and decompresses) the requested blocks, it writes the data into the delivery queue VMO and sends a delivery command. The verifier receives this command, cryptographically verifies the payload against the Merkle tree, and then supplies it to the kernel pager (zx_pager_supply_pages). The blob’s Merkle leaf data is also transported via the delivery queue when the driver fetches and caches the metadata.

Structs

RawDeliveryCommand

A command packet used by the driver to deliver merkle leaves and data chunks for verification.

RawMappingCommand

A command packet used to communicate extent mappings.

Enums

DeliveryCommand

MappingCommand

Constants

CLOSE_BLOB_COMMAND

DELIVERY_DATA_COMMAND

DELIVERY_DATA_SIZE

The chunk size requirement for delivering payloads from the block driver across the delivery queue. The driver must supply DeliveryCommand::Data chunks where the target_offset and length align to DELIVERY_DATA_SIZE boundaries (unless representing the final chunk of the blob).

DELIVERY_REGISTER_BLOB_COMMAND

DELIVERY_VMO_SIZE

ENCRYPTION_KEY_SIZE

Size of the encryption key in bytes (256 bits).

MAPPINGS_COMMAND

MAPPINGS_FLAG_ENCRYPTED

Flag indicating that the mapping payload contains an encryption key.

MAPPING_VMO_SIZE

PENDING_COMMANDS_CAPACITY

PENDING_DELIVERY_COMMANDS_CAPACITY