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

/// Stats captured for specific block requests. Unless specified otherwise, time units are in
/// nanoseconds and data transferred is in bytes
type RequestStats = struct {
    /// Minimum time taken by a request to be served.
    minimum_latency uint64;

    /// Maximum time taken by a request to be served.
    maximum_latency uint64;

    /// Total time spent to serve requests.
    total_time_spent uint64;

    /// Total number of calls.
    total_calls uint64;

    /// bytes_transferred represents a specific quantity to the operation being measured. It has
    /// special meaning for success vs failed calls.
    /// On success:
    ///    Partitally succeeded calls, bytes fetched is less than bytes requested,
    ///    can be considered as successful. To keep latency and time_spent numbers
    ///    accurate, on success, bytes transferred is number bytes returned to
    ///    caller. It is NOT the number of bytes fetched from underlying subsystem
    ///    and it is NOT number of bytes requested by the caller.
    /// On failure:
    ///    On failure, bytes_transferred is the number of bytes requested by the caller.
    bytes_transferred uint64;
};

/// Helper struct to track device requests grouped by successful versus failed requests.
type OperationStats = struct {
    /// Stats for successful requests.
    success RequestStats;
    /// Stats for failed requests.
    failure RequestStats;
};

/// Returns stats about the block device on the provided buffer. If `clear` is true, the
/// operation counters will be cleared.
type BlockStats = struct {
    /// Stats about block read operations from the device.
    read OperationStats;

    /// Stats about block write operations to the device.
    write OperationStats;

    /// Stats about TRIM commands issued to the device.
    trim OperationStats;

    /// Stats about flush commands issued to the device.
    flush OperationStats;
};