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

using fuchsia.hardware.sharedmemory;
using zx;

const MAX_TRANSFER_SIZE uint32 = 8196; // arbitrary - to be removed
const MAX_SPI_CHANNEL uint32 = 32; // arbitrary.
type SpiClockPhase = flexible enum {
    CLOCK_PHASE_FIRST = 0;
    CLOCK_PHASE_SECOND = 1;
};

/// Represents a single device on a SPI bus.
type SpiChannel = table {
    /// ID of the bus that this device is on.
    1: bus_id uint32;
    /// Chip select number for the device.
    2: cs uint32;

    /// Vendor ID. Used when binding via platform bus device IDs.
    3: vid uint32;
    /// Product ID. Used when binding via platform bus device IDs.
    4: pid uint32;
    /// Device ID. Used when binding via platform bus device IDs.
    5: did uint32;

    // Bus configuration.
    /// Chip select polarity: true == high, false == low.
    6: cs_polarity_high bool;
    /// Size in bits of a single word on the SPI bus.
    7: word_length_bits uint8;

    /// Are we in charge of the bus?
    8: is_bus_controller bool;
    /// Clock polarity. true == high, false == low.
    9: clock_polarity_high bool;
    ///  Clock phase.
   10: clock_phase SpiClockPhase;
};

/// Passed to the spi driver in metadata as DEVICE_METADATA_SPI_CHANNELS.
type SpiBusMetadata = table {
    1: channels vector<SpiChannel>:MAX_SPI_CHANNEL;
};

protocol Device {
    /// Half-duplex transmit data to a SPI device; always transmits the entire buffer on success.
    TransmitVector(struct {
        data vector<uint8>:MAX_TRANSFER_SIZE;
    }) -> (struct {
        status zx.status;
    });
    /// Half-duplex receive data from a SPI device; always reads the full size requested.
    ReceiveVector(struct {
        size uint32;
    }) -> (struct {
        status zx.status;
        data vector<uint8>:MAX_TRANSFER_SIZE;
    });
    /// Full-duplex SPI transaction. Received data will exactly equal the length of the transmit
    /// buffer.
    ExchangeVector(struct {
        txdata vector<uint8>:MAX_TRANSFER_SIZE;
    }) -> (struct {
        status zx.status;
        rxdata vector<uint8>:MAX_TRANSFER_SIZE;
    });

    /// Returns true if the device can call |AssertCs()| and |DeassertCs()|.
    CanAssertCs() -> (struct {
        can bool;
    });

    /// Assert CS for this device.
    /// Returns ZX_ERR_NOT_SUPPORTED if there is more than one device on the bus.
    AssertCs() -> (struct {
        status zx.status;
    });
    /// Deassert CS for this device.
    /// Returns ZX_ERR_BAD_STATE if CS is already deasserted.
    /// Returns ZX_ERR_NOT_SUPPORTED if there is more than one device on the bus.
    DeassertCs() -> (struct {
        status zx.status;
    });

    compose fuchsia.hardware.sharedmemory.SharedVmoIo;
    compose fuchsia.hardware.sharedmemory.SharedVmoRegister;
};