// 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`].
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.
    strict GetStats(struct {
        clear bool;
    }) -> (struct {
        stats BlockStats;
    }) error zx.Status;


    /// Opens a new FIFO-based session on the block device.
    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;
};