sdk/fidl/fuchsia.hardware.block/block.fidl

// 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.io;
using zx;
using fuchsia.storage.metrics as storage_metrics;

/// All writes to the block device will fail.
const FLAG_READONLY uint32 = 0x00000001;

/// The block device may be removed from the device during operation.
const FLAG_REMOVABLE uint32 = 0x00000002;

/// The device has a bootdata partition map.
const FLAG_BOOTPART uint32 = 0x00000004;

/// The device provides trim support.
const FLAG_TRIM_SUPPORT uint32 = 0x00000008;

/// The maximum value for a transfer size, identifying that there
/// effectively exists no maximum for a single operation.
const MAX_TRANSFER_UNBOUNDED uint32 = 0xFFFFFFFF;

/// Describes metatadata about a block device.
@for_deprecated_c_bindings
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; refer to the "FLAG_*" documentation above.
    flags uint32;

    reserved uint32;
};

/// Describes statistics about the operations on the block device since boot.
/// storage_metrics.CallStat.bytes_transferred is number of bytes requested
/// to be transferred.
@for_deprecated_c_bindings
type 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;
};

/// 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.
@for_deprecated_c_bindings
type VmoId = struct {
    id 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.
const VMOID_INVALID uint16 = 0;

/// Defines access to a device which is accessible in block-granularity chunks
/// for reading and writing.
@for_deprecated_c_bindings
protocol Block {
    /// Get information about the underlying block device.
    GetInfo() -> (struct {
        status zx.status;
        info box<BlockInfo>;
    });

    /// Returns stats about the block device on the provided buffer and optionally
    /// clears the counters.
    GetStats(struct {
        clear bool;
    }) -> (struct {
        status zx.status;
        stats box<BlockStats>;
    });

    /// Sets up a FIFO-based server on the block device; acquire the handle to it.
    GetFifo() -> (resource struct {
        status zx.status;
        fifo zx.handle:<FIFO, optional>;
    });

    /// Attaches a VMO to the currently running FIFO server.
    AttachVmo(resource struct {
        vmo zx.handle:VMO;
    }) -> (struct {
        status zx.status;
        vmoid box<VmoId>;
    });

    /// 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.
    CloseFifo() -> (struct {
        status zx.status;
    });

    /// 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.
    RebindDevice() -> (struct {
        status zx.status;
    });

    /// 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.
    @transitional
    ReadBlocks(resource struct {
        vmo zx.handle:VMO;
        length uint64;
        dev_offset uint64;
        vmo_offset uint64;
    }) -> (struct {
        status 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.
    @transitional
    WriteBlocks(resource struct {
        vmo zx.handle:VMO;
        length uint64;
        dev_offset uint64;
        vmo_offset uint64;
    }) -> (struct {
        status zx.status;
    });
};

/// This protocol is intended for servers that handles both hardware.block.block
/// and io.Node.
///
/// In the C++ implementation, such a server is able to test for the requests
/// from each protocol. However, Rust bindings make it difficult to do
/// so and requires that we create a new protocol that is composed of the two.
protocol BlockAndNode {
    compose Block;
    compose fuchsia.io.Node;
};