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

using zx;

/// The protocol for interacting with a instance of a ramdisk.
closed protocol Ramdisk {
    /// Sets any of the `RAMDISK_FLAG_*` flags.
    strict SetFlags(struct {
        flags @generated_name("RamdiskFlag") strict bits : uint32 {
            /// Identifies if requests which are sent ot the ramdisk while it is
            /// considered "asleep" should be processed when the ramdisk wakes
            /// up. If this flag is not set, those requests are failed
            /// immediately.
            RESUME_ON_WAKE = 0x00000001;

            /// If set, blocks written after the last flush are filled with an
            /// indeterminate value when waking after sleeping.
            DISCARD_NOT_FLUSHED_ON_WAKE = 0x00000002;

            /// If set, blocks written after the last flush are filled at
            /// random rather than all blocks.  This can be used to simulate
            /// out-of-order writes.
            DISCARD_RANDOM = 0x00000004;
        };
    }) -> ();

    /// Wakes a ramdisk, if it was sleeping.
    ///
    /// Resets the block counts being stored by the ramdisk.
    strict Wake() -> ();

    /// Causes the ramdisk to sleep after `count` blocks are written successfully.
    /// After `count` blocks are written, requests either wait for the ramdisk to
    /// be awoken (if RESUME_ON_WAKE has been set), or begin failing immediately.
    ///
    /// Resets the block counts being stored by the ramdisk.
    strict SleepAfter(struct {
        count uint64;
    }) -> ();

    /// Returns the number of write requests since the last call to either
    /// "SleepAfter" or "Wake".
    strict GetBlockCounts() -> (struct {
        /// Counters for the number of write requests since the last call to either
        /// "SleepAfter" or "Wake". All units are in individual blocks.
        counts @generated_name("BlockWriteCounts") struct {
            received uint64;
            successful uint64;
            failed uint64;
        };
    });

    /// Causes the ramdisk size to grow to `required_size` in bytes.
    /// If `required_size` is smaller than the current size an error will be
    /// returned. `required_size` must be a multiple of `block_size`.
    strict Grow(struct {
        new_size uint64;
    }) -> () error zx.Status;
};

// TODO(smklein): Deduplicate GUID declarations with other FIDL interfaces.

/// Matches the value of ZBI_PARTITION_GUID_LEN.
const GUID_LEN uint32 = 16;

/// An array of bytes interpreted as a GUID. Wrapped in a struct to
/// allow optional GUIDs.
type Guid = struct {
    value array<uint8, GUID_LEN>;
};

const MAX_NAME_LENGTH uint32 = 32;

closed protocol RamdiskController {
    /// Initializes a new Ramdisk instance with the provided block size and block count.
    /// Takes an optional `type_guid`, which may be queried from the ramdisk instance.
    strict Create(struct {
        block_size uint64;
        block_count uint64;
        type_guid box<Guid>;
    }) -> (struct {
        name string:<MAX_NAME_LENGTH, optional>;
    }) error zx.Status;

    /// Initializes a new Ramdisk instance from a VMO. Uses a block size of `PAGE_SIZE`,
    /// and derives the block count from the size of the VMO.
    strict CreateFromVmo(resource struct {
        vmo zx.Handle:VMO;
    }) -> (struct {
        name string:<MAX_NAME_LENGTH, optional>;
    }) error zx.Status;

    /// Same as CreateFromVmo, but with the given `block_size` and optional `type_guid`. If
    /// `block_size` is zero, `PAGE_SIZE` will be used as `block_size`.
    strict CreateFromVmoWithParams(resource struct {
        vmo zx.Handle:VMO;
        block_size uint64;
        type_guid box<Guid>;
    }) -> (struct {
        name string:<MAX_NAME_LENGTH, optional>;
    }) error zx.Status;
};