blob: e69c9669cdf1a70082ab7f115ccc44a8890a3570 [file] [log] [blame]
// 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;
};