include/usb_i2c.h

/* Copyright 2016 The Chromium OS Authors. All rights reserved.
 * Use of this source code is governed by a BSD-style license that can be
 * found in the LICENSE file.
 */

#include "consumer.h"
#include "producer.h"
#include "registers.h"
#include "task.h"
#include "usb_descriptor.h"
#include "util.h"

#ifndef __CROS_USB_I2C_H
#define __CROS_USB_I2C_H

/*
 * 2 forms of command are supported:
 *   - When write payload + header is larger than 64 bytes, which exceed the
 *     common USB packet (64 bytes), remaining payload should send without
 *     header.
 *
 *   - CONFIG_USB_I2C_MAX_WRITE_COUNT / CONFIG_USB_I2C_MAX_READ_COUNT have to
 *     be defined properly based on the use cases.
 *
 *   - Read less than 128 (0x80) bytes.
 *   +------+------+----+----+---------------+
 *   | port | addr | wc | rc | write payload |
 *   +------+------+----+----+---------------+
 *   |  1B  |  1B  | 1B | 1B |  < 256 bytes  |
 *   +------+------+----+----+---------------+
 *
 *   - Read less than 32768 (0x8000) bytes.
 *   +------+------+----+----+-----+----------+---------------+
 *   | port | addr | wc | rc | rc1 | reserved | write payload |
 *   +------+------+----+----+----------------+---------------+
 *   |  1B  |  1B  | 1B | 1B |  1B |    1B    |  < 256 bytes  |
 *   +------+------+----+----+----------------+---------------+
 *
 *   - Special notes for rc and rc1:
 *     If the most significant bit in rc is set (rc >= 0x80), this indicates
 *     that we want to read back more than 127 bytes, so the first byte of
 *     data contains rc1 (read count continuation), and the final read count
 *     will be (rc1 << 7) | (rc & 0x7F).
 *
 *   Fields:
 *   - port: port address, 1 byte, i2c interface index.
 *
 *   - addr: slave address, 1 byte, i2c 7-bit bus address.
 *
 *   - wc: write count, 1 byte, zero based count of bytes to write. If the
 *         indicated write count cause the payload + header exceeds 64 bytes,
 *         Following packets are expected to continue the payload without
 *         header.
 *
 *   - rc: read count, 1 byte, zero based count of bytes to read. To read more
 *         than 127 (0x7F) bytes please see the special notes above.
 *
 *   - data: payload of data to write. See wc above for more information.
 *
 *   - rc1: extended read count, 1 byte. An extended version indicates we want
 *          to read more data. While the most significant bits is set in read
 *          count (rc >= 0x80), rc1 will concatenate with rc together. See the
 *          special notes above for concatenating details.
 *
 *   - reserved: reserved byte, 1 byte.
 *
 * Response:
 *     +-------------+---+---+--------------+
 *     | status : 2B | 0 | 0 | read payload |
 *     +-------------+---+---+--------------+
 *
 *   - read payload might not fit into a single USB packets. Remaining will be
 *     transimitted witout header. Receiving side should concatenate them.
 *
 *     status: 2 byte status
 *         0x0000: Success
 *         0x0001: I2C timeout
 *         0x0002: Busy, try again
 *             This can happen if someone else has acquired the shared memory
 *             buffer that the I2C driver uses as /dev/null
 *         0x0003: Write count invalid (mismatch with merged payload)
 *         0x0004: Read count invalid (e.g. larger than available buffer)
 *         0x0005: The port specified is invalid.
 *         0x0006: The I2C interface is disabled.
 *         0x8000: Unknown error mask
 *             The bottom 15 bits will contain the bottom 15 bits from the EC
 *             error code.
 *
 *     read payload: Depends on the buffer size and implementation. Length will
 *             match requested read count
 */

enum usb_i2c_error {
	USB_I2C_SUCCESS             = 0x0000,
	USB_I2C_TIMEOUT             = 0x0001,
	USB_I2C_BUSY                = 0x0002,
	USB_I2C_WRITE_COUNT_INVALID = 0x0003,
	USB_I2C_READ_COUNT_INVALID  = 0x0004,
	USB_I2C_PORT_INVALID        = 0x0005,
	USB_I2C_DISABLED            = 0x0006,
	USB_I2C_UNKNOWN_ERROR       = 0x8000,
};


#define USB_I2C_WRITE_BUFFER (CONFIG_USB_I2C_MAX_WRITE_COUNT + 4)
/* If read payload is larger or equal to 128 bytes, header contains rc1 */
#define USB_I2C_READ_BUFFER  ((CONFIG_USB_I2C_MAX_READ_COUNT < 128) ?	\
	(CONFIG_USB_I2C_MAX_READ_COUNT + 4) :				\
	(CONFIG_USB_I2C_MAX_READ_COUNT + 6))

#define USB_I2C_BUFFER_SIZE					\
	(USB_I2C_READ_BUFFER > USB_I2C_WRITE_BUFFER ?	\
		USB_I2C_READ_BUFFER : USB_I2C_WRITE_BUFFER)

BUILD_ASSERT(POWER_OF_TWO(USB_I2C_READ_BUFFER));
BUILD_ASSERT(POWER_OF_TWO(USB_I2C_WRITE_BUFFER));

/*
 * Compile time Per-USB gpio configuration stored in flash.  Instances of this
 * structure are provided by the user of the USB i2c.  This structure binds
 * together all information required to operate a USB i2c.
 */
struct usb_i2c_config {
	uint16_t *buffer;

	/* Deferred function to call to handle SPI request. */
	const struct deferred_data *deferred;

	struct consumer const consumer;
	struct queue const *tx_queue;
};

extern struct consumer_ops const usb_i2c_consumer_ops;

/*
 * Convenience macro for defining a USB I2C bridge driver.
 *
 * NAME is used to construct the names of the trampoline functions and the
 * usb_i2c_config struct, the latter is just called NAME.
 *
 * INTERFACE is the index of the USB interface to associate with this
 * I2C driver.
 *
 * INTERFACE_NAME is the index of the USB string descriptor (iInterface).
 *
 * ENDPOINT is the index of the USB bulk endpoint used for receiving and
 * transmitting bytes.
 */
#define USB_I2C_CONFIG(NAME,						\
		       INTERFACE,					\
		       INTERFACE_NAME,					\
		       ENDPOINT)					\
	static uint16_t							\
		CONCAT2(NAME, _buffer_)					\
			[USB_I2C_BUFFER_SIZE / 2];			\
	static void CONCAT2(NAME, _deferred_)(void);			\
	DECLARE_DEFERRED(CONCAT2(NAME, _deferred_));			\
	static struct queue const CONCAT2(NAME, _to_usb_);		\
	static struct queue const CONCAT3(usb_to_, NAME, _);		\
	USB_STREAM_CONFIG_FULL(CONCAT2(NAME, _usb_),			\
			       INTERFACE,				\
			       USB_CLASS_VENDOR_SPEC,			\
			       USB_SUBCLASS_GOOGLE_I2C,			\
			       USB_PROTOCOL_GOOGLE_I2C,			\
			       INTERFACE_NAME,				\
			       ENDPOINT,				\
			       USB_MAX_PACKET_SIZE,			\
			       USB_MAX_PACKET_SIZE,			\
			       CONCAT3(usb_to_, NAME, _),		\
			       CONCAT2(NAME, _to_usb_))			\
	struct usb_i2c_config const NAME = {				\
		.buffer    = CONCAT2(NAME, _buffer_),			\
		.deferred  = &CONCAT2(NAME, _deferred__data),		\
		.consumer  = {						\
			.queue = &CONCAT3(usb_to_, NAME, _),		\
			.ops   = &usb_i2c_consumer_ops,			\
		},							\
		.tx_queue = &CONCAT2(NAME, _to_usb_),			\
	};								\
	static struct queue const CONCAT2(NAME, _to_usb_) =		\
		QUEUE_DIRECT(USB_I2C_READ_BUFFER, uint8_t,	\
		null_producer, CONCAT2(NAME, _usb_).consumer);		\
	static struct queue const CONCAT3(usb_to_, NAME, _) =		\
		QUEUE_DIRECT(USB_I2C_WRITE_BUFFER, uint8_t,	\
		CONCAT2(NAME, _usb_).producer, NAME.consumer);		\
	static void CONCAT2(NAME, _deferred_)(void)			\
	{ usb_i2c_deferred(&NAME); }

/*
 * Handle I2C request in a deferred callback.
 */
void usb_i2c_deferred(struct usb_i2c_config const *config);

/*
 * These functions should be implemented by the board to provide any board
 * specific operations required to enable or disable access to the I2C device,
 * and to return the current board enable state.
 */

/**
 * Check if the I2C device is enabled
 *
 * @return 1 if enabled, 0 if disabled.
 */
int usb_i2c_board_is_enabled(void);

#endif  /* __CROS_USB_I2C_H */