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

using zx;

// Must match //sdk/fidl/fuchsia.hardware.sharedmemory/sharedmemory.fidl
enum SpiVmoRight : uint32 {
    READ = 0x1;   // The protocol implementation can read from this VMO (used for write requests).
    WRITE = 0x2;  // The protocol implementation can write to this VMO (used for read requests).
};

/// Low-level protocol for spi drivers.
[Transport = "Banjo", BanjoLayout = "ddk-protocol"]
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.
    GetChipSelectCount() -> (uint32 count);

    /// Perform a SPI bus transaction of the specified length. Either txdata or rxdata may be
    /// NULL, in which case the transaction will be half-duplex in the appropriate direction.
    /// Regardless, both vectors must have the same length.
    Exchange(uint32 chip_select, vector<uint8> txdata) -> (zx.status status, vector<uint8> rxdata);

    /// rights is a bit field containing SpiVmoRight values, and determines the read/write
    /// permissions used by the implementation when pinning or mapping the VMO.
    RegisterVmo(uint32 chip_select, uint32 vmo_id, zx.handle:VMO vmo, uint64 offset, uint64 size,
                uint32 rights) -> (zx.status status);
    UnregisterVmo(uint32 chip_select, uint32 vmo_id) -> (zx.status status, zx.handle:VMO vmo);

    TransmitVmo(uint32 chip_select, uint32 vmo_id, uint64 offset, uint64 size)
            -> (zx.status status);
    ReceiveVmo(uint32 chip_select, uint32 vmo_id, uint64 offset, uint64 size)
            -> (zx.status status);
    ExchangeVmo(uint32 chip_select, uint32 tx_vmo_id, uint64 tx_offset, uint32 rx_vmo_id,
                uint64 rx_offset, uint64 size) -> (zx.status status);
};