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

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

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

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

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

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

/// Describes metatadata about a block device.
struct BlockInfo {
    /// The number of blocks in this block device.
    uint64 block_count;

    /// The size of a single block.
    uint32 block_size;

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

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

    uint32 reserved;
};

/// Describes statistics about the operations on the block device since boot.
/// storage_metrics.CallStat.bytes_transferred is number of bytes requested
/// to be transferred.
struct BlockStats {
    /// The stats about read from the device.
    storage_metrics.CallStat read;

    /// The stats about write to the device.
    storage_metrics.CallStat write;

    /// The stats about trim commands.
    storage_metrics.CallStat trim;

    /// The stats about flush commands.
    storage_metrics.CallStat flush;

    /// The stats about barrier before commands.
    storage_metrics.CallStat barrier_before;

    /// The stats about barrier after commands.
    storage_metrics.CallStat barrier_after;
};

/// 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.
struct VmoId {
    uint16 id;
};

/// 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.
const uint16 VMOID_INVALID = 0;

/// Defines access to a device which is accessible in block-granularity chunks
/// for reading and writing.
[Layout = "Simple"]
protocol Block {
    /// Get information about the underlying block device.
    GetInfo() -> (zx.status status, BlockInfo? info);

    /// Returns stats about the block device on the provided buffer and optionally
    /// clears the counters.
    GetStats(bool clear) -> (zx.status status, BlockStats? stats);

    /// Sets up a FIFO-based server on the block device; acquire the handle to it.
    GetFifo() -> (zx.status status, handle<fifo>? fifo);

    /// Attaches a VMO to the currently running FIFO server.
    AttachVmo(handle<vmo> vmo) -> (zx.status status, VmoId? 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() -> (zx.status 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() -> (zx.status status);
};