// 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;

// 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 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.
struct BlockStats {
    // The total number of operations which have been processed.
    int64 ops;

    // The total number of blocks which have been acted upon.
    int64 blocks;

    // The total number of requests to read from the device.
    int64 reads;

    // The total number of blocks which have been read from the device.
    int64 blocks_read;

    // The total number of requests to write to the device.
    int64 writes;

    // The total number of blocks which have been written to the device.
    int64 blocks_written;
};

// 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", FragileBase]
interface 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);
};