// Copyright 2020 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.ram.metrics;

using zx;

const MAX_COUNT_CHANNELS uint32 = 8;

/// Configures bus hardware to make one measurement.
type BandwidthMeasurementConfig = struct {
    /// How many bus cycles to perform the measurement over.
    cycles_to_measure uint64;
    /// Contains which ports to aggregate for each channel.
    channels array<uint64, MAX_COUNT_CHANNELS>;
};

/// Contains the actual cycles granted to each channel. Not all hardware
/// supports all 3 counters. If a counter is not supported the value
/// returned is zero.
type GrantedCyclesResult = struct {
    read_cycles uint64;
    write_cycles uint64;
    readwrite_cycles uint64;
};

type BandwidthInfo = struct {
    // Time when the measurement started.
    timestamp zx.time;
    // Bus frequency in hertz (Hz) when the measurement started.
    frequency uint64;
    // Number of bytes per cycle.
    bytes_per_cycle uint64;
    channels array<GrantedCyclesResult, MAX_COUNT_CHANNELS>;
    total GrantedCyclesResult;
};

/// Interface to obtain memory bandwidth usage measurements from hardware
/// cycle counters. The interface supports up to 6 hardware counters
/// (called channels) which aggregate up to 64 unique buses (called ports).
///
/// An example of a possible configuration:
/// channel[0] <- A53x4 + M3x1
/// channel[1] <- gpu
/// channel[2] <- vpu + h264_decoder + hdmi
/// channel[3] <- image_isp + h264_encoder
///
/// The number of channels and which bit patterns to use for each port
/// are hardware specific.
///
protocol Device {
    /// Trigger one measurement. This can be called again before the reply
    /// arrives but it won't be serviced until previous requests are completed.
    ///
    /// The return on success is the measurement.
    ///
    /// The return on failure are as follows:
    /// ZX_ERR_INVALID_ARGS : The BandwidthMeasurementConfig values are incorrect.
    /// ZX_ERR_NOT_SUPPORTED : The BandwidthMeasurementConfig values are not supported
    /// by the hardware.
    /// ZX_ERR_SHOULD_WAIT : Too many requests pending. A future request might succeed.
    /// Other errors indicate internal failure.
    MeasureBandwidth(struct {
        config BandwidthMeasurementConfig;
    }) -> (struct {
        info BandwidthInfo;
    }) error zx.status;

    /// Retrieve the DDR Windowing tool results
    /// The windowing tool runs in the bootloader and stores results in a sticky register.
    ///
    /// The return on success is the register value
    ///
    /// The return on failure is ZX_ERR_NOT_SUPPORTED if the hardware does not support
    /// reading the sticky register.
    GetDdrWindowingResults() -> (struct {
        value uint32;
    }) error zx.status;
};