PROTOCOLS
Block
Defined in fuchsia.hardware.block/block.banjo
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
Name | Type |
---|
Response
Name | Type |
---|---|
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
Name | Type |
---|---|
txn |
BlockOp
|
Response
Name | Type |
---|---|
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
Name | Type |
---|---|
vmo |
handle<vmo>
|
Response
Name | Type |
---|---|
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
Name | Type |
---|
Response
Name | Type |
---|---|
status |
zx/status
|
GetFifo
Sets up a FIFO-based server on the block device; acquire the handle to it.
Request
Name | Type |
---|
Response
Name | Type |
---|---|
status |
zx/status
|
fifo |
handle<fifo>?
|
GetInfo
Get information about the underlying block device.
Request
Name | Type |
---|
Response
Name | Type |
---|---|
status |
zx/status
|
info |
BlockInfo?
|
GetStats
Returns stats about the block device on the provided buffer and optionally clears the counters.
Request
Name | Type |
---|---|
clear |
bool
|
Response
Name | Type |
---|---|
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
Name | Type |
---|
Response
Name | Type |
---|---|
status |
zx/status
|
BlockImpl
Defined in fuchsia.hardware.block/block.banjo
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
Name | Type |
---|
Response
Name | Type |
---|---|
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
Name | Type |
---|---|
txn |
BlockOp
|
Response
Name | Type |
---|---|
status |
zx/status
|
op |
BlockOp
|
Ftl
Defined in fuchsia.hardware.block/ftl.fidl
Format
Discards previous contents and reinitializes the device.
Request
Name | Type |
---|
Response
Name | Type |
---|---|
status |
zx/status
|
GetVmo
Requests the inspect vmo from the entity.
- |vmo| has |ZX_RIGHTS_DUPLICATE|, |ZX_RIGHTS_TRANSFER|, |ZX_RIGHTS_READ|
Request
Name | Type |
---|
Response
Name | Type |
---|---|
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
Name | Type |
---|
Response
Name | Type |
---|---|
result |
InspectVmoProvider_GetVmo_Result
|
STRUCTS
BlockFifoRequest
Defined in fuchsia.hardware.block/block.banjo
Name | Type | Description | Default |
---|---|---|---|
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.banjo
Name | Type | Description | Default |
---|---|---|---|
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
Describes metatadata about a block device.
Name | Type | Description | Default |
---|---|---|---|
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 |
BlockInfo
Defined in fuchsia.hardware.block/block.banjo
Name | Type | Description | Default |
---|---|---|---|
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 |
BlockReadWrite
Defined in fuchsia.hardware.block/block.banjo
BLOCK_OP_READ
, BLOCK_OP_WRITE
Name | Type | Description | Default |
---|---|---|---|
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
Describes statistics about the operations on the block device since boot. storage_metrics.CallStat.bytes_transferred is number of bytes requested to be transferred.
Name | Type | Description | Default |
---|---|---|---|
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 |
BlockStats
Defined in fuchsia.hardware.block/block.banjo
Name | Type | Description | Default |
---|---|---|---|
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 |
BlockTrim
Defined in fuchsia.hardware.block/block.banjo
BLOCK_OP_TRIM
Name | Type | Description | Default |
---|---|---|---|
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
Defined in fuchsia.hardware.block/ftl.fidl
Name | Type | Description | Default |
---|---|---|---|
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.
Name | Type | Description | Default |
---|---|---|---|
id |
uint16
|
No default |
UNIONS
BlockOp
Defined in fuchsia.hardware.block/block.banjo
Name | Type | Description |
---|---|---|
command |
uint32
|
All Commands |
rw |
BlockReadWrite
|
Read and Write ops use rw for parameters. |
trim |
BlockTrim
|
InspectVmoProvider_GetVmo_Result
Defined in fuchsia.hardware.block/ftl.fidl
Name | Type | Description |
---|---|---|
response |
InspectVmoProvider_GetVmo_Response
|
|
err |
zx/status
|
CONSTANTS
Name | Value | Type | Description |
---|---|---|---|
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:
For BLOCKIO_READ and BLOCKIO_WRITE, N may be greater than 1. Otherwise, N == 1 (skipping step (1) in the protocol above). Notes:
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 |
Dummy 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
Name | Value | Description |
---|---|---|
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 |