Google is committed to advancing racial equity for Black communities. See how.

fuchsia.hardware.block

PROTOCOLS

Block

Defined in fuchsia.hardware.block/block.fidl

Query

Obtains the parameters of the block device (block_info_t) and the required size of block_txn_t. The block_txn_t's submitted via queue() must have block_op_size_out - sizeof(block_op_t) bytes available at the end of the structure for the use of the driver.

Request

NameType

Response

NameType
info BlockInfo
block_op_size uint64

Queue

Submits an IO request for processing. Ownership of |op| is transferred to callee until |completion_cb| is invoked|. Success or failure will be reported via the |completion_cb|. This / callback may be called before the queue() method returns.

Request

NameType
txn BlockOp

Response

NameType
status zx/status
op BlockOp

Block

Defined in fuchsia.hardware.block/block.fidl

Defines access to a device which is accessible in block-granularity chunks for reading and writing.

AttachVmo

Attaches a VMO to the currently running FIFO server.

Request

NameType
vmo handle<vmo>

Response

NameType
status zx/status
vmoid VmoId?

CloseFifo

Shuts down the fifo server, waiting for it to be ready to be started again.

When this method returns, a client may safely invoke GetFifo to acquire a new connection to the block server, without being told that a server is already serving requests on a different fifo.

If, instead of invoking "CloseFifo", a client merely closes their fifo, the server automatically cleans up all resources anyway. In this case, however, the client will have no guarantee that the next invocation of "GetFifo" will return a connection successfully.

Request

NameType

Response

NameType
status zx/status

GetFifo

Sets up a FIFO-based server on the block device; acquire the handle to it.

Request

NameType

Response

NameType
status zx/status
fifo handle<fifo>?

GetInfo

Get information about the underlying block device.

Request

NameType

Response

NameType
status zx/status
info BlockInfo?

GetStats

Returns stats about the block device on the provided buffer and optionally clears the counters.

Request

NameType
clear bool

Response

NameType
status zx/status
stats BlockStats?

RebindDevice

Rebinds the block device (if supported).

WARNING: This is only added for parity with block device ioctls; this is going to move into the device FIDL API.

Request

NameType

Response

NameType
status zx/status

BlockImpl

Defined in fuchsia.hardware.block/block.fidl

Query

Obtains the parameters of the block device (block_info_t) and the required size of block_txn_t. The block_txn_t's submitted via queue() must have block_op_size_out - sizeof(block_op_t) bytes available at the end of the structure for the use of the driver.

Request

NameType

Response

NameType
info BlockInfo
block_op_size uint64

Queue

Submits an IO request for processing. Ownership of |op| is transferred to callee until |completion_cb| is invoked|. Success or failure will be reported via the |completion_cb|. This / callback may be called before the queue() method returns.

Request

NameType
txn BlockOp

Response

NameType
status zx/status
op BlockOp

Ftl

Defined in fuchsia.hardware.block/ftl.fidl

Format

Discards previous contents and reinitializes the device.

Request

NameType

Response

NameType
status zx/status

GetVmo

Requests the inspect vmo from the entity.

  • |vmo| has |ZX_RIGHTS_DUPLICATE|, |ZX_RIGHTS_TRANSFER|, |ZX_RIGHTS_READ|

Request

NameType

Response

NameType
result InspectVmoProvider_GetVmo_Result

InspectVmoProvider

Defined in fuchsia.hardware.block/ftl.fidl

It is treated as a separate protocol for extension if necessary.

GetVmo

Requests the inspect vmo from the entity.

  • |vmo| has |ZX_RIGHTS_DUPLICATE|, |ZX_RIGHTS_TRANSFER|, |ZX_RIGHTS_READ|

Request

NameType

Response

NameType
result InspectVmoProvider_GetVmo_Result

STRUCTS

BlockFifoRequest

Defined in fuchsia.hardware.block/block.fidl

NameTypeDescriptionDefault
opcode uint32 No default
reqid Reqid

Transmitted in the block_fifo_response_t.

No default
group Groupid

Only used if opcode & BLOCK_GROUP_ITEM.

No default
vmoid Vmoid No default
length uint32 No default
vmo_offset uint64 No default
dev_offset uint64 No default
trace_flow_id uint64 No default

BlockFifoResponse

Defined in fuchsia.hardware.block/block.fidl

NameTypeDescriptionDefault
status zx/status No default
reqid Reqid No default
group Groupid

Only valid if transmitted in request.

No default
reserved0 uint16 No default
count uint32

The number of messages in the transaction completed by the block server.

No default
reserved1 uint64 No default
reserved2 uint64 No default
reserved3 uint64 No default

BlockInfo

Defined in fuchsia.hardware.block/block.fidl

NameTypeDescriptionDefault
block_count uint64

The number of blocks in this block device.

No default
block_size uint32

The size of a single block.

No default
max_transfer_size uint32

Max size in bytes per transfer. May be BLOCK_MAX_TRANSFER_UNBOUNDED if there is no restriction.

No default
flags uint32 No default
reserved uint32 No default

BlockInfo

Defined in fuchsia.hardware.block/block.fidl

Describes metatadata about a block device.

NameTypeDescriptionDefault
block_count uint64

The number of blocks in this block device.

No default
block_size uint32

The size of a single block.

No default
max_transfer_size uint32

The maximum size, in bytes, of a transfer. Set to MAX_TRANSFER_UNBOUNDED if no such maximum exists.

No default
flags uint32

Identifiers about the device; refer to the "FLAG_*" documentation above.

No default
reserved uint32 No default

BlockReadWrite resource

Defined in fuchsia.hardware.block/block.fidl

BLOCK_OP_READ, BLOCK_OP_WRITE

NameTypeDescriptionDefault
command uint32

Command and flags.

No default
extra uint32

Available for temporary use.

No default
vmo handle<vmo>

VMO of data to read or write.

No default
length uint32

Transfer length in blocks (0 is invalid).

No default
offset_dev uint64

Device offset in blocks.

No default
offset_vmo uint64

VMO offset in blocks.

No default

BlockStats

Defined in fuchsia.hardware.block/block.fidl

NameTypeDescriptionDefault
total_ops uint64

Total number of block ops processed

No default
total_blocks uint64

Total number of blocks processed

No default
total_reads uint64 No default
total_blocks_read uint64 No default
total_writes uint64 No default
total_blocks_written uint64 No default

BlockStats

Defined in fuchsia.hardware.block/block.fidl

Describes statistics about the operations on the block device since boot. storage_metrics.CallStat.bytes_transferred is number of bytes requested to be transferred.

NameTypeDescriptionDefault
read fuchsia.storage.metrics/CallStat

The stats about read from the device.

No default
write fuchsia.storage.metrics/CallStat

The stats about write to the device.

No default
trim fuchsia.storage.metrics/CallStat

The stats about trim commands.

No default
flush fuchsia.storage.metrics/CallStat

The stats about flush commands.

No default
barrier_before fuchsia.storage.metrics/CallStat

The stats about barrier before commands.

No default
barrier_after fuchsia.storage.metrics/CallStat

The stats about barrier after commands.

No default

BlockTrim

Defined in fuchsia.hardware.block/block.fidl

BLOCK_OP_TRIM

NameTypeDescriptionDefault
command uint32

Command and flags.

No default
length uint32

Transfer length in blocks (0 is invalid).

No default
offset_dev uint64

Device offset in blocks.

No default

InspectVmoProvider_GetVmo_Response resource

Defined in fuchsia.hardware.block/ftl.fidl

NameTypeDescriptionDefault
vmo handle<vmo> No default

VmoId

Defined in fuchsia.hardware.block/block.fidl

A client-identifier to a VMO. This value may be utilized by clients to refer to a VMO which is being held by a block device server.

NameTypeDescriptionDefault
id uint16 No default

UNIONS

BlockOp strict resource

Defined in fuchsia.hardware.block/block.fidl

NameTypeDescription
command uint32

All Commands

rw BlockReadWrite

Read and Write ops use rw for parameters.

trim BlockTrim

InspectVmoProvider_GetVmo_Result strict resource

Defined in fuchsia.hardware.block/ftl.fidl

NameTypeDescription
response InspectVmoProvider_GetVmo_Response
err zx/status

CONSTANTS

NameValueTypeDescription
BLOCK_FLAG_BOOTPART 4 uint32

Block device has bootdata partition map provided by device metadata.

BLOCK_FLAG_MASK 65280 uint32
BLOCK_FLAG_READONLY 1 uint32
BLOCK_FLAG_REMOVABLE 2 uint32
BLOCK_FLAG_TRIM_SUPPORT 8 uint32

Flag advertising trim support.

BLOCK_FL_BARRIER_AFTER 512 uint32

Require that this operation complete before any subsequent operations are started.

Prevents later operations from being reordered before this one.

BLOCK_FL_BARRIER_BEFORE 256 uint32

Require that this operation will not begin until all previous operations have completed.

Prevents earlier operations from being reordered after this one.

BLOCK_FL_FORCE_ACCESS 4096 uint32

Mark this operation as "Force Unit Access" (FUA), indicating that it should not complete until the data is written to the non-volatile medium (write), and that reads should bypass any on-device caches.

BLOCK_GROUP_ITEM 1024 uint32

Associate the following request with |group|.

BLOCK_GROUP_LAST 2048 uint32

Only respond after this request (and all previous within group) have completed. Only valid with BLOCKIO_GROUP_ITEM.

BLOCK_GUID_LEN 16 uint32
BLOCK_MAX_TRANSFER_UNBOUNDED 4294967295 uint32
BLOCK_OP_CLOSE_VMO 5 uint32

Detaches the VMO from the block device.

BLOCK_OP_FLUSH 3 uint32

Write any controller or device cached data to nonvolatile storage. This operation always implies BARRIER_BEFORE and BARRIER_AFTER, meaning that previous operations will complete before it starts and later operations will not start until it is done.

BLOCK_OP_MASK 255 uint32
BLOCK_OP_READ 1 uint32

Performs a regular data read or write from the device. The operation may be cached internally.

BLOCK_OP_TRIM 4 uint32

Instructs the device to invalidate a number of blocks, making them usable for storing something else. This is basically a "delete" optimization, where the device is in charge of discarding the old content without clients having to write a given pattern. The operation may be cached internally.

BLOCK_OP_WRITE 2 uint32
BLOCK_VMOID_INVALID 0 uint32
FLAG_BOOTPART 4 uint32

The device has a bootdata partition map.

FLAG_READONLY 1 uint32

All writes to the block device will fail.

FLAG_REMOVABLE 2 uint32

The block device may be removed from the device during operation.

FLAG_TRIM_SUPPORT 8 uint32

The device provides trim support.

MAX_TRANSFER_UNBOUNDED 4294967295 uint32

The maximum value for a transfer size, identifying that there effectively exists no maximum for a single operation.

MAX_TXN_GROUP_COUNT 8 uint32

Multiple Block IO operations may be sent at once before a response is actually sent back. Block IO ops may be sent concurrently to different vmoids, and they also may be sent to different groups at any point in time.

MAX_TXN_GROUP_COUNT "groups" are pre-allocated lanes separated on the block server. Using a group allows multiple message to be buffered at once on a single communication channel before receiving a response.

Usage of groups is identified by BLOCKIO_GROUP_ITEM, and is optional.

These groups may be referred to with a "groupid", in the range [0, MAX_TXN_GROUP_COUNT).

The protocol to communicate with a single group is as follows:

  1. SEND [N - 1] messages with an allocated groupid for any value of 1 <= N. The BLOCKIO_GROUP_ITEM flag is set for these messages.
  2. SEND a final Nth message with the same groupid. The BLOCKIO_GROUP_ITEM | BLOCKIO_GROUP_LAST flags are set for this message.
  3. RECEIVE a single response from the Block IO server after all N requests have completed. This response is sent once all operations either complete or a single operation fails. At this point, step (1) may begin again for the same groupid.

For BLOCKIO_READ and BLOCKIO_WRITE, N may be greater than 1. Otherwise, N == 1 (skipping step (1) in the protocol above).

Notes:

  • groupids may operate on any number of vmoids at once.
  • If additional requests are sent on the same groupid before step (3) has completed, then the additional request will not be processed. If BLOCKIO_GROUP_LAST is set, an error will be returned. Otherwise, the request will be silently dropped.
  • Messages within a group are not guaranteed to be processed in any order relative to each other.
  • All requests receive responses, except for ones with BLOCKIO_GROUP_ITEM that do not have BLOCKIO_GROUP_LAST set.

For example, the following is a valid sequence of transactions: -> (groupid = 1, vmoid = 1, OP = Write | GroupItem, reqid = 1) -> (groupid = 1, vmoid = 2, OP = Write | GroupItem, reqid = 2) -> (groupid = 2, vmoid = 3, OP = Write | GroupItem | GroupLast, reqid = 0) <- Response sent to groupid = 2, reqid = 0 -> (groupid = 1, vmoid = 1, OP = Read | GroupItem | GroupLast, reqid = 3) <- Response sent to groupid = 1, reqid = 3 -> (groupid = 3, vmoid = 1, OP = Write | GroupItem, reqid = 4) -> (groupid = don't care, vmoid = 1, OP = Read, reqid = 5) <- Response sent to reqid = 5 -> (groupid = 3, vmoid = 1, OP = Read | GroupItem | GroupLast, reqid = 6) <- Response sent to groupid = 3, reqid = 6

Each transaction reads or writes up to 'length' blocks from the device, starting at 'dev_offset' blocks, into the VMO associated with 'vmoid', starting at 'vmo_offset' blocks. If the transaction is out of range, for example if 'length' is too large or if 'dev_offset' is beyond the end of the device, ZX_ERR_OUT_OF_RANGE is returned.

VMOID_INVALID 0 uint16

Value reserved for "invalid" VmoId. Will never be allocated by the server, and may be utilized as a local value for an unallocated ID.

TYPE ALIASES

NameValueDescription
Groupid uint16
Reqid uint32

The Request ID allowing callers to correspond requests with responses. This field is entirely for client-side bookkeeping; there is no obligation to make request IDs unique.

Vmoid uint16