// Copyright 2021 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.sharedmemory;
using fuchsia.mem;

using zx;

type SharedVmoRight = flexible bits : uint32 {
    /// The protocol implementation can read from this VMO (used for transmit requests).
    READ = 0x1;
    /// The protocol implementation can write to this VMO (used for receive requests).
    WRITE = 0x2;
};

type SharedVmoBuffer = struct {
    vmo_id uint32;
    offset uint64;
    size uint64;
};

/// This is a generic protocol for sharing VMOs that drivers may compose.
closed protocol SharedVmoRegister {
    /// Registers a VMO and transfers ownership to the driver.
    /// vmo_id: The ID chosen by the client that will be used in operations on this VMO.
    /// vmo: The handle, offset, and size of this VMO. IO operations on this VMO will be relative to
    /// the offset and size specified here.
    /// rights: A bit field of SharedVmoRight values indicating how this VMO may be used. Callers
    /// should assume that the driver will map and/or pin the VMO using these rights.
    strict RegisterVmo(resource struct {
        vmo_id uint32;
        vmo fuchsia.mem.Range;
        rights SharedVmoRight;
    }) -> () error zx.Status;

    /// Unmaps and/or unpins the VMO and returns the handle to the caller.
    strict UnregisterVmo(struct {
        vmo_id uint32;
    }) -> (resource struct {
        vmo zx.Handle:VMO;
    }) error zx.Status;
};

/// This is a generic protocol for driver IO using shared VMOs. Drivers may compose this protocol
/// and choose which methods to implement based on the uses of the hardware. This protocol is only
/// intended for simple use cases.
closed protocol SharedVmoIo {
    /// Sends the data in buffer to the device.
    strict Transmit(struct {
        buffer SharedVmoBuffer;
    }) -> () error zx.Status;

    /// Receives data from the device into buffer.
    strict Receive(struct {
        buffer SharedVmoBuffer;
    }) -> () error zx.Status;

    /// Simultaneously transmits and receives data. The size fields of tx_buffer and rx_buffer must
    /// be the same.
    strict Exchange(struct {
        tx_buffer SharedVmoBuffer;
        rx_buffer SharedVmoBuffer;
    }) -> () error zx.Status;
};