// Copyright 2018 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.
@available(added=7)
library fuchsia.hardware.i2c;

using zx;

/// Clients should be aware of the max channel message size when using large transfers or many
/// transactions. It is possible to generate a message that uses values less than the limits below
/// but is still too big for the channel.
///
/// The maximum number of bytes that can be read or written in a single `Transaction`.
const MAX_TRANSFER_SIZE uint32 = 32768;

/// The maximum number of transactions that can be specified in a call to `Transfer`.
const MAX_COUNT_TRANSACTIONS uint32 = 256;

/// If `read_size` is set: This is a read transfer, and `read_size` bytes will be read from the
/// target.
/// If `write_data` is set: This is a write transfer, and `write_data` will be written to the
/// target.
type DataTransfer = flexible union {
    1: read_size uint32;
    2: write_data bytes:MAX_TRANSFER_SIZE;
};

/// `data_transfer` is mandatory, and specifies whether this transaction has a read or a write
/// transfer (see above).
/// `stop` is optional, and specifies whether this transaction is terminated by a stop condition (if
/// true) or by a repeated-start (if false or unspecified). If this transaction is the last in the
/// list then a stop condition is generated regardless of the value of `stop`.
type Transaction = table {
    1: data_transfer DataTransfer;
    2: stop bool;
};

/// Used to return data from read transfers.
alias ReadData = bytes:MAX_TRANSFER_SIZE;

@discoverable
protocol Device {
    /// Issue one or more transactions to a particular I2C device.
    ///
    /// Each `Transaction` is performed in the order in which it appears in `transactions`. Data for
    /// read transfers (if there are any) is returned through `read_data`, which has one entry for
    /// each read transfer in `transactions`. Transaction processing continues until all transfers
    /// have been completed, an error occurs, or the target issues a NACK in response to a write
    /// transfer.
    ///
    /// The possible error values are:
    ///   ZX_ERR_INVALID_ARGS: `transactions` has zero elements, `data_transfer` was not specified
    ///     for a `Transaction`, or there was a zero-length `DataTransfer`.
    ///   ZX_ERR_OUT_OF_RANGE: A `DataTransfer` was too large to be handled by this I2C controller.
    ///   ZX_ERR_IO_NOT_PRESENT: The device did not respond to its I2C address.
    ///   ZX_ERR_IO_REFUSED: The device issued a NACK before the end of a write transfer.
    Transfer(struct {
        transactions vector<Transaction>:MAX_COUNT_TRANSACTIONS;
    }) -> (struct {
        read_data vector<ReadData>:MAX_COUNT_TRANSACTIONS;
    }) error zx.status;
};