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

using fuchsia.hardware.sharedmemory;
using fuchsia.mem;
using zx;

/// Low-level protocol for spi drivers.
@discoverable
@transport("Driver")
closed protocol SpiImpl {
    /// Returns the number of chip select lines available or provided by the driver instance.
    /// To be used as a limit on the acceptable values for the `chip_select' field in the Exchange()
    /// and ExchangeVmo() methods.
    strict GetChipSelectCount() -> (struct {
        count uint32;
    });

    /// Half-duplex transmit data to a SPI device; always transmits the entire buffer on success.
    strict TransmitVector(struct {
        chip_select uint32;
        data vector<uint8>:MAX;
    }) -> () error zx.Status;

    /// Half-duplex receive data from a SPI device; always reads the full size requested.
    strict ReceiveVector(struct {
        chip_select uint32;
        size uint32;
    }) -> (struct {
        data vector<uint8>:MAX;
    }) error zx.Status;

    /// Full-duplex SPI transaction. Received data will exactly equal the length of the transmit
    /// buffer.
    strict ExchangeVector(struct {
        chip_select uint32;
        txdata vector<uint8>:MAX;
    }) -> (struct {
        rxdata vector<uint8>:MAX;
    }) error zx.Status;

    /// Lock the bus.
    strict LockBus(struct {
        chip_select uint32;
    }) -> () error zx.Status;

    /// Unlock the bus.
    strict UnlockBus(struct {
        chip_select uint32;
    }) -> () error zx.Status;

    /// rights is a bit field containing SpiVmoRight values, and determines the read/write
    /// permissions used by the implementation when pinning or mapping the VMO.
    strict RegisterVmo(resource struct {
        chip_select uint32;
        vmo_id uint32;
        vmo fuchsia.mem.Range;
        rights fuchsia.hardware.sharedmemory.SharedVmoRight;
    }) -> () error zx.Status;

    strict UnregisterVmo(struct {
        chip_select uint32;
        vmo_id uint32;
    }) -> (resource struct {
        vmo zx.Handle:VMO;
    }) error zx.Status;

    /// Release all VMOs registered to this chip_select. Called by the core driver after the client
    /// has disconnected and the VMOs are no longer needed.
    strict ReleaseRegisteredVmos(struct {
        chip_select uint32;
    });

    strict TransmitVmo(struct {
        chip_select uint32;
        buffer fuchsia.hardware.sharedmemory.SharedVmoBuffer;
    }) -> () error zx.Status;

    strict ReceiveVmo(struct {
        chip_select uint32;
        buffer fuchsia.hardware.sharedmemory.SharedVmoBuffer;
    }) -> () error zx.Status;

    strict ExchangeVmo(struct {
        chip_select uint32;
        tx_buffer fuchsia.hardware.sharedmemory.SharedVmoBuffer;
        rx_buffer fuchsia.hardware.sharedmemory.SharedVmoBuffer;
    }) -> () error zx.Status;
};

service Service {
    device client_end:SpiImpl;
};