// 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
type SpiVmoRight = strict enum : 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")
@banjo_layout("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() -> (struct {
        count uint32;
    });

    /// 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(struct {
        chip_select uint32;
        txdata vector<uint8>:MAX;
    }) -> (struct {
        status zx.status;
        rxdata vector<uint8>:MAX;
    });

    /// Lock the bus.
    LockBus(struct {
        chip_select uint32;
    }) -> (struct {
        status zx.status;
    });
    /// Unlock the bus.
    UnlockBus(struct {
        chip_select uint32;
    }) -> (struct {
        status 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.
    RegisterVmo(resource struct {
        chip_select uint32;
        vmo_id uint32;
        vmo zx.handle:VMO;
        offset uint64;
        size uint64;
        rights uint32;
    }) -> (struct {
        status zx.status;
    });
    UnregisterVmo(struct {
        chip_select uint32;
        vmo_id uint32;
    }) -> (resource struct {
        status zx.status;
        vmo zx.handle:VMO;
    });

    /// 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.
    ReleaseRegisteredVmos(struct {
        chip_select uint32;
    });

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