| // Copyright 2019 The Fuchsia Authors. All rights reserved. |
| // Use of this source code is governed by a BSD-style license that can be |
| // found in the LICENSE file. |
| library fuchsia.hardware.block; |
| |
| using fuchsia.storage.metrics as storage_metrics; |
| using fuchsia.unknown; |
| using zx; |
| |
| /// The maximum value for a transfer size, identifying that there |
| /// effectively exists no maximum for a single operation. |
| const MAX_TRANSFER_UNBOUNDED uint32 = 0xFFFFFFFF; |
| |
| /// Value reserved for "invalid" VmoId. Will never be allocated by the server, |
| /// and may be utilized as a local value for an unallocated ID. |
| const VMOID_INVALID uint16 = 0; |
| |
| /// Represents a session with a block device. |
| /// |
| /// This protocol encodes the underlying object's lifetime in both directions; the underlying object |
| /// is alive iff both ends of the protocol are open. That is: |
| /// |
| /// - Closing the client end causes the object to be destroyed. |
| /// - Observing a closure of the server end indicates the object no longer exists. |
| /// |
| /// The object can be destroyed synchronously using [`fuchsia.unknown/Closeable.Close`]. |
| protocol Session { |
| compose fuchsia.unknown.Closeable; |
| |
| /// Returns a handle to the client end of the FIFO. |
| GetFifo() -> (resource struct { |
| fifo zx.handle:<FIFO>; |
| }) error zx.status; |
| |
| /// Attaches a VMO to the session. |
| /// |
| /// Returns an identifer that can be used to refer to the VMO. |
| AttachVmo(resource struct { |
| vmo zx.handle:VMO; |
| }) -> (struct { |
| // TODO(https://fxbug.dev/103484): consider removing the outer struct when the issue is |
| // resolved. |
| vmoid @generated_name("VmoId") struct { |
| id uint16; |
| }; |
| }) error zx.status; |
| }; |
| |
| /// Defines access to a device which is accessible in block-granularity chunks |
| /// for reading and writing. |
| protocol Block { |
| /// Get information about the underlying block device. |
| GetInfo() -> (struct { |
| // TODO(https://fxbug.dev/103484): consider removing the outer struct when the issue is |
| // resolved. |
| info @generated_name("BlockInfo") struct { |
| /// The number of blocks in this block device. |
| block_count uint64; |
| |
| /// The size of a single block. |
| block_size uint32; |
| |
| /// The maximum size, in bytes, of a transfer. |
| /// Set to MAX_TRANSFER_UNBOUNDED if no such maximum exists. |
| max_transfer_size uint32; |
| |
| /// Identifiers about the device. |
| flags @generated_name("Flag") strict bits : uint32 { |
| /// All writes to the block device will fail. |
| READONLY = 0x00000001; |
| |
| /// The block device may be removed from the device during operation. |
| REMOVABLE = 0x00000002; |
| |
| /// The device has a bootdata partition map. |
| BOOTPART = 0x00000004; |
| |
| /// The device provides trim support. |
| TRIM_SUPPORT = 0x00000008; |
| |
| /// The device provides fua support. |
| FUA_SUPPORT = 0x00000010; |
| }; |
| }; |
| }) error zx.status; |
| |
| /// Returns stats about the block device on the provided buffer and optionally |
| /// clears the counters. |
| /// |
| /// storage_metrics.CallStat.bytes_transferred is number of bytes requested |
| /// to be transferred. |
| GetStats(struct { |
| clear bool; |
| }) -> (struct { |
| // TODO(https://fxbug.dev/103484): consider removing the outer struct when the issue is |
| // resolved. |
| stats @generated_name("BlockStats") struct { |
| /// The stats about read from the device. |
| read storage_metrics.CallStat; |
| |
| /// The stats about write to the device. |
| write storage_metrics.CallStat; |
| |
| /// The stats about trim commands. |
| trim storage_metrics.CallStat; |
| |
| /// The stats about flush commands. |
| flush storage_metrics.CallStat; |
| }; |
| }) error zx.status; |
| |
| /// Opens a new FIFO-based session on the block device. |
| OpenSession(resource struct { |
| session server_end:Session; |
| }); |
| |
| /// Reads from a block device. |
| /// |
| /// This read does not require exclusive access. |
| /// length, dev_offset and vmo_offset are specified in bytes, but they must be |
| /// block-aligned. |
| /// This method is provided for backward compatibility, and is not intended for new code. |
| /// New code should use the FIFO interface along with the client libraries to |
| /// read and write from block devices. |
| ReadBlocks(resource struct { |
| vmo zx.handle:VMO; |
| length uint64; |
| dev_offset uint64; |
| vmo_offset uint64; |
| }) -> () error zx.status; |
| |
| /// Writes to a block device. |
| /// |
| /// This write does not require exclusive access. |
| /// length, dev_offset and vmo_offset are specified in bytes, but they must be |
| /// block-aligned. |
| /// This method is provided for backward compatibility, and is not intended for new code. |
| /// New code should use the FIFO interface along with the client libraries to |
| /// read and write from block devices. |
| WriteBlocks(resource struct { |
| vmo zx.handle:VMO; |
| length uint64; |
| dev_offset uint64; |
| vmo_offset uint64; |
| }) -> () error zx.status; |
| }; |