| // 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.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`]. |
| @available(added=9) |
| closed protocol Session { |
| compose fuchsia.unknown.Closeable; |
| |
| /// Returns a handle to the client end of the FIFO. |
| strict 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. |
| strict AttachVmo(resource struct { |
| vmo zx.Handle:VMO; |
| }) -> (struct { |
| // TODO(https://fxbug.dev/42054535): consider removing the outer struct when the issue is |
| // resolved. |
| vmoid @generated_name("VmoId") struct { |
| id uint16; |
| }; |
| }) error zx.Status; |
| }; |
| |
| type 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; |
| }; |
| }; |
| |
| /// Defines access to a device which is accessible in block-granularity chunks |
| /// for reading and writing. |
| closed protocol Block { |
| /// Get information about the underlying block device. |
| strict GetInfo() -> (struct { |
| // TODO(https://fxbug.dev/42054535): consider removing the outer struct when the issue is |
| // resolved. |
| info BlockInfo; |
| }) error zx.Status; |
| |
| /// Returns stats about block device operations. Setting `clear` will reset stats counters. |
| @available(added=15) |
| strict GetStats(struct { |
| clear bool; |
| }) -> (struct { |
| stats BlockStats; |
| }) error zx.Status; |
| |
| |
| /// Opens a new FIFO-based session on the block device. |
| @available(added=9) |
| strict 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. |
| strict 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. |
| strict WriteBlocks(resource struct { |
| vmo zx.Handle:VMO; |
| length uint64; |
| dev_offset uint64; |
| vmo_offset uint64; |
| }) -> () error zx.Status; |
| }; |