xref: /illumos-gate/usr/src/uts/common/sys/i2c/i2c.h (revision 32002227574cf0a435dc03de622191ca53724f0a)

/*
 * This file and its contents are supplied under the terms of the
 * Common Development and Distribution License ("CDDL"), version 1.0.
 * You may only use this file in accordance with the terms of version
 * 1.0 of the CDDL.
 *
 * A full copy of the text of the CDDL should have accompanied this
 * source.  A copy of the CDDL is also available via the Internet at
 * http://www.illumos.org/license/CDDL.
 */

/*
 * Copyright 2025 Oxide Computer Company
 */

#ifndef _SYS_I2C_I2C_H
#define	_SYS_I2C_I2C_H

/*
 * General i2c definitions that should be shared between both userland and the
 * kernel. Kernel device drivers include <sys/i2c/controller.h>,
 * <sys/i2c/mux.h>, or <sys/i2c/client.h> depending on the type of device they
 * are. Userland should generally use <libi2c.h> or <sys/i2c/ui2c.h> if it's the
 * implementation of libi2c.
 */

#include <sys/stdint.h>
#include <sys/stdbool.h>

#ifdef __cplusplus
extern "C" {
#endif

/*
 * Different allowed values for I2C and SMBus speeds. In the future, we'll
 * determine how I3C based options like different supported clock rates and
 * SDR/DDR fit in here.
 */
typedef enum {
	/*
	 * 100 kHz Standard operation.
	 */
	I2C_SPEED_STD	= 1 << 0,
	/*
	 * 400 kHz Fast-mode operation.
	 */
	I2C_SPEED_FAST	= 1 << 1,
	/*
	 * 1000 MHz Fast-mode plus operation.
	 */
	I2C_SPEED_FPLUS	= 1 << 2,
	/*
	 * 3400 MHz High-speed mode operation.
	 */
	I2C_SPEED_HIGH	= 1 << 3,
	/*
	 * 5000 MHz Ultra-Fast mode operation.
	 */
	I2C_SPEED_ULTRA	= 1 << 4
} i2c_speed_t;

/*
 * Different types of controllers.
 */
typedef enum {
	I2C_CTRL_TYPE_I2C = 1,
	I2C_CTRL_TYPE_I3C,
	I2C_CTRL_TYPE_SMBUS
} i2c_ctrl_type_t;

/*
 * This represents the series of errors that can be generated by the various I2C
 * APIs. These are grouped into several different units that cover behavior
 * specific to the core (impacting everything) to properties, user-specific
 * behavior, kernel driver clients, etc.
 */
typedef enum {
	I2C_CORE_E_OK	= 0,
	/*
	 * Indicates that the controller I/O failed. The reason is specified in
	 * the controller error.
	 */
	I2C_CORE_E_CONTROLLER,
	/*
	 * The following pair indicate that a given address class or value for
	 * an address within a valid address class are wrong.
	 */
	I2C_CORE_E_BAD_ADDR_TYPE,
	I2C_CORE_E_BAD_ADDR,
	/*
	 * This indicates that the requested address type, while valid, is not
	 * supported. For example, trying to send to a 10-bit address on a
	 * controller that does not support it.
	 */
	I2C_CORE_E_UNSUP_ADDR_TYPE,
	/*
	 * Indicates that the address in question is reserved by a corresponding
	 * specification.
	 */
	I2C_CORE_E_ADDR_RSVD,
	/*
	 * Indicates that the address in question is already in use and
	 * therefore cannot be used.
	 */
	I2C_CORE_E_ADDR_IN_USE,
	/*
	 * Indicates that the address could be used, but it has exceeded the
	 * per-address usage count. This usually represents a place where the
	 * kernel can be improved.
	 */
	I2C_CORE_E_ADDR_REFCNT,
	/*
	 * Indicates that there is no device with the specified address.
	 */
	I2C_CORE_E_UNKNOWN_ADDR,
	/*
	 * Indicates that the request type can't be translated to something the
	 * underlying controller actually supports. For example, this would
	 * cover trying to translate certain kinds of I2C requests to an SMBus
	 * controller that supports limited types of operations or vice versa.
	 */
	I2C_CORE_E_CANT_XLATE_REQ,
	/*
	 * This indicates that a request had neither a read nor a write and
	 * therefore cannot continue. This constraint on I/O may be lifted in
	 * the future.
	 */
	I2C_CORE_E_NEED_READ_OR_WRITE,
	/*
	 * These indicate that invalid flags values, an invalid read length, or
	 * invalid write length was encountered.
	 */
	I2C_CORE_E_BAD_I2C_REQ_FLAGS,
	I2C_CORE_E_BAD_I2C_REQ_READ_LEN,
	I2C_CORE_E_BAD_I2C_REQ_WRITE_LEN,
	/*
	 * These indicate similar situations in the SMBus request field.
	 */
	I2C_CORE_E_BAD_SMBUS_REQ_FLAGS,
	I2C_CORE_E_BAD_SMBUS_READ_LEN,
	I2C_CORE_E_BAD_SMBUS_WRITE_LEN,
	I2C_CORE_E_BAD_SMBUS_OP,
	/*
	 * Indicates that the controller does not support the requested SMBus
	 * operation.
	 */
	I2C_CORE_E_UNSUP_SMBUS_OP,
	/*
	 * Indicates that the controller is already owned by someone and the
	 * caller asked not to block.
	 */
	I2C_CORE_E_LOCK_WOULD_BLOCK,
	/*
	 * Indicates that the caller took a signal while waiting to acquire the
	 * controller.
	 */
	I2C_CORE_E_LOCK_WAIT_SIGNAL,
	/*
	 * Indicates that a passed in nvlist was larger than the maximum value.
	 */
	I2C_IOCTL_E_NVL_TOO_BIG = 0x1000,
	/*
	 * Indicates that the nvlist was not parseable.
	 */
	I2C_IOCTL_E_NVL_INVALID,
	/*
	 * Indicates that the nvlist contained missing keys, keys that we don't
	 * know how to handle, and keys that are the wrong type. If this gets
	 * much more complex, the interface should change to the kgpio error
	 * style where there is an additional nvlist there.
	 */
	I2C_IOCTL_E_NVL_KEY_MISSING,
	I2C_IOCTL_E_NVL_KEY_UNKNOWN,
	I2C_IOCTL_E_NVL_KEY_BAD_TYPE,
	/*
	 * Indicates that a pointer to user data inside of an ioctl (not the
	 * overall ioctl itself) was not valid and generated a fault.
	 */
	I2C_IOCTL_E_BAD_USER_DATA,
	/*
	 * Indicates that there was no kernel memory available for the request.
	 */
	I2C_IOCTL_E_NO_KERN_MEM,
	/*
	 * Indicates that a string that is being used for a device name or
	 * compatible array contains illegal characters or is too long.
	 */
	I2C_IOCTL_E_BAD_DEV_NAME,
	/*
	 * Indicates that the length of the compatible range is longer than the
	 * system will allow to be set.
	 */
	I2C_IOCTL_E_COMPAT_LEN_RANGE,
	/*
	 * Indicates that something went wrong with trying to deal with nexus
	 * related operations on a child.
	 */
	I2C_IOCTL_E_NEXUS,
	/*
	 * Indicates that a nexus operations was attempted while trying to hold
	 * a bus lock.
	 */
	I2C_IOCTL_E_NO_BUS_LOCK_NEXUS,
	/*
	 * Indicates that an ioctl operation could not be started because the
	 * client in question already has one in flight that requires the
	 * controller lock.
	 */
	I2C_IOCTL_E_IN_PROGRESS,
	/*
	 * Indicates that the passed dev_info_t does not correspond to an i2c
	 * device.
	 */
	I2C_CLIENT_E_BAD_DIP = 0x2000,
	/*
	 * Indicates that the regs[] index is invalid for the device.
	 */
	I2C_CLIENT_E_BAD_REG_IDX,
	/*
	 * Indicates that the specific set of flags are invalid.
	 */
	I2C_CLIENT_E_BAD_CLAIM_FLAGS,
	I2C_CLIENT_E_BAD_IO_FLAGS,
	I2C_CLIENT_E_BAD_LOCK_FLAGS,
	/*
	 * Indicates that the caller was interrupted while trying to get access
	 * to the client for I/O.
	 */
	I2C_CLIENT_E_SIGNAL,
	/*
	 * Thee indicate that there are invalid values in the various register
	 * access attributes.
	 */
	I2C_CLIENT_E_BAD_REG_ATTR_VERS,
	I2C_CLIENT_E_BAD_REG_ATTR_FLAGS,
	I2C_CLIENT_E_BAD_REG_ATTR_RLEN,
	I2C_CLIENT_E_BAD_REG_ATTR_ALEN,
	I2C_CLIENT_E_BAD_REG_ATTR_ENDIAN,
	I2C_CLIENT_E_BAD_REG_ATTR_MAX,
	/*
	 * Indicates that while the register attributes are supported, the
	 * underlying hardware cannot support them.
	 */
	I2C_CLIENT_E_REG_ALEN_UNSUP_BY_CTRL,
	/*
	 * These indicate that I2C register operations were passed invalid
	 * values or that these values would lead to an overflow.
	 */
	I2C_CLIENT_E_BAD_REG_ADDR,
	I2C_CLIENT_E_BAD_REG_COUNT,
	I2C_CLIENT_E_REG_ADDR_OVERFLOW,
	I2C_CLIENT_E_REG_IO_TOO_LARGE,
	/*
	 * Indicates that the size in bytes is a partial number of registers.
	 */
	I2C_CLIENT_E_PARTIAL_REG,
	/*
	 * Indicates that the client has tried to claim a shared address, but
	 * they actually own the address directly.
	 */
	I2C_CLIENT_E_CLAIM_OWNED_ADDR,
	/*
	 * These two indicate that the property is unsupported by the device or
	 * a property ID that is unknown by the system.
	 */
	I2C_PROP_E_UNSUP = 0x3000,
	I2C_PROP_E_UNKNOWN,
	/*
	 * Indicates that the property can't be written to because it is
	 * read-only.
	 */
	I2C_PROP_E_READ_ONLY,
	/*
	 * Indicates that the property buffer is too small. The second indicates
	 * that the property buffer is too large and doesn't make sense for the
	 * property. The latter is only relevant when setting a property. The
	 * former can be triggered in all property interfaces.
	 */
	I2C_PROP_E_SMALL_BUF,
	I2C_PROP_E_TOO_BIG_BUF,
	/*
	 * Indicates that the property value is invalid.
	 */
	I2C_PROP_E_BAD_VAL,
	/*
	 * Indicates that the controller doesn't support setting properties.
	 */
	I2C_PROP_E_SET_UNSUP,
	/*
	 * Indicates that the mux flag is unknown.
	 */
	I2C_MUX_E_BAD_FLAG = 0x4000
} i2c_errno_t;

/*
 * These represent errors that the controller generates and/or detects while
 * attempting to perform I/O. Some controllers provide relatively rich
 * diagnostics as to what went wrong. Others, provide only generic classes of
 * errors. Try to use the most specific error possible.
 */
typedef enum {
	I2C_CTRL_E_OK = 0,
	/*
	 * This is a generic class that represents something happened internal
	 * to the controller. In general, this should be used sparingly and only
	 * for something that only makes semantic sense on a single controller.
	 * This should not be a property of something related to I2C/SMBus/I3C
	 * directly.
	 */
	I2C_CTRL_E_INTERNAL,
	/*
	 * This is a variant of the above that indicates a driver programming
	 * error violated a controller condition.
	 */
	I2C_CTRL_E_DRIVER,
	/*
	 * Indicates that the controller was given a type of command that it
	 * does not support. For example, an SMBus 1.0 controller given an SMBus
	 * 2.0 command. The framework generally is the only tying that will
	 * return this error as drivers should not have to encounter them.
	 */
	I2C_CTRL_E_UNSUP_CMD,
	/*
	 * Indicates that prior to trying to perform the operation, the
	 * controller detected that the bus was busy and after a timeout was
	 * unable to get control of the bus.
	 */
	I2C_CTRL_E_BUS_BUSY,
	/*
	 * This error indicates that there was a no acknowledgement condition.
	 * This should be used both for 7-bit and 10-bit cases. Similarly, for
	 * now this should also be used for cases where no one acknowledges a
	 * general call.
	 */
	I2C_CTRL_E_ADDR_NACK,
	/*
	 * This is a variant on the address NACK. This is used when the address
	 * has been acknowledged, but subsequent data has not been. Some devices
	 * may not be able to make the distinction. If they cannot, use the
	 * catch-all NACK below.
	 */
	I2C_CTRL_E_DATA_NACK,
	/*
	 * This is a case where no NACK occurred, but the controller cannot be
	 * more specific as to where in the process it occurred.
	 */
	I2C_CTRL_E_NACK,
	/*
	 * Indicates that the controller lost arbitration on the bus. A common
	 * cause for this is a data collision.
	 */
	I2C_CTRL_E_ARB_LOST,
	/*
	 * Indicates that a device incorrectly issued an ACK when it was not
	 * expected in the operation.
	 */
	I2C_CTRL_E_BAD_ACK,
	/*
	 * Indicates that the controller failed to successfully finish
	 * transmitting the command within the default request timeout. This
	 * results in the controller aborting the command. Callers cannot assume
	 * anything about the number of bytes that made it out onto the bus.
	 */
	I2C_CTRL_E_REQ_TO,
	/*
	 * Indicates that an SMBus device returned a block read length that
	 * could not be supported by the device or is illegal according to the
	 * specification. For example, a 0 byte length or a length exceeding 32
	 * bytes for an SMBus 2.0 controller.
	 */
	I2C_CTRL_E_BAD_SMBUS_RLEN,
	/*
	 * Indicates that an SMBus device held the clock low for too long to
	 * effectively trime out the transaction. This is different from the
	 * request timeout as it indicates something the target did.
	 */
	I2C_CTRL_E_SMBUS_CLOCK_LOW
} i2c_ctrl_error_t;

typedef struct {
	i2c_errno_t i2c_error;
	i2c_ctrl_error_t i2c_ctrl;
} i2c_error_t;

/*
 * General maximum length for an i2c related name, including the NUL.
 */
#define	I2C_NAME_MAX	32

typedef enum i2c_addr_type {
	I2C_ADDR_7BIT = 0,
	I2C_ADDR_10BIT
} i2c_addr_type_t;

/*
 * This represents the general form of our i2c addresses and what the nexus will
 * give client devices and drivers in the form of regs[].
 */
typedef struct i2c_addr {
	uint16_t ia_type;
	uint16_t ia_addr;
} i2c_addr_t;

/*
 * This indicates where an address came from.
 */
typedef enum i2c_addr_source {
	/*
	 * Indicates that this came from the devices reg[] array. It was either
	 * put there as part of discovering information about the system by the
	 * platform (e.g. ACPI, device tree, etc.) or based on a user's specific
	 * device creation.
	 */
	I2C_ADDR_SOURCE_REG = 1,
	/*
	 * Indicates that the address was one that the driver claimed.
	 */
	I2C_ADDR_SOURCE_CLAIMED,
	/*
	 * Indicates that the address was one that the driver claimed and is
	 * shared across multiple instances.
	 */
	I2C_ADDR_SOURCE_SHARED
} i2c_addr_source_t;

/*
 * Well-known and other special addresses. I2C reserves several addresses for
 * special purposes. SMBus has a more extensive of nominal assignments, but
 * things definitely stomp in that space.
 */
typedef enum {
	I2C_RSVD_ADDR_GEN_CALL	= 0x00,
	I2C_RSVD_ADDR_C_BUS	= 0x01,
	I2C_RSVD_ADDR_DIFF_BUS	= 0x02,
	I2C_RSVD_ADDR_FUTURE	= 0x03,
	I2C_RSVD_ADDR_HS_0	= 0x04,
	I2C_RSVD_ADDR_HS_1	= 0x05,
	I2C_RSVD_ADDR_HS_2	= 0x06,
	I2C_RSVD_ADDR_HS_3	= 0x07,
	I2C_RSVD_ADDR_10B_0	= 0x78,
	I2C_RSVD_ADDR_10B_1	= 0x79,
	I2C_RSVD_ADDR_10B_2	= 0x7a,
	I2C_RSVD_ADDR_10B_3	= 0x7b,
	I2C_RSVD_ADDR_DID_0	= 0x7c,
	I2C_RSVD_ADDR_DID_1	= 0x7d,
	I2C_RSVD_ADDR_DID_2	= 0x7e,
	I2C_RSVD_ADDR_DID_3	= 0x7f
} i2c_rsvd_addr_t;

/*
 * SMBus 2.0 controllers have a maximum byte size of 32 bytes. SMBus 3.0
 * increases that to a maximum of 255 bytes. As such we size our maximum request
 * sizes at 256 bytes in our structures.
 */
#define	SMBUS_V2_MAX_BLOCK	32
#define	SMBUS_V3_MAX_BLOCK	255
#define	I2C_REQ_MAX		256

typedef enum smbus_op {
	SMBUS_OP_QUICK_COMMAND,
	SMBUS_OP_SEND_BYTE,
	SMBUS_OP_RECV_BYTE,
	SMBUS_OP_WRITE_BYTE,
	SMBUS_OP_READ_BYTE,
	SMBUS_OP_WRITE_WORD,
	SMBUS_OP_READ_WORD,
	SMBUS_OP_PROCESS_CALL,
	SMBUS_OP_WRITE_BLOCK,
	SMBUS_OP_READ_BLOCK,
	/* Added in SMBUS 2.0 */
	SMBUS_OP_HOST_NOTIFY,
	SMBUS_OP_BLOCK_PROCESS_CALL,
	/* Added in SMBUS 3.x */
	SMBUS_OP_WRITE_U32,
	SMBUS_OP_READ_U32,
	SMBUS_OP_WRITE_U64,
	SMBUS_OP_READ_U64,
	/* I2C Compatibility */
	SMBUS_OP_I2C_WRITE_BLOCK,
	SMBUS_OP_I2C_READ_BLOCK
} smbus_op_t;

typedef enum {
	/*
	 * Indicates that regardless of whether or not interrupts are supported,
	 * this request should be polled.
	 */
	I2C_IO_REQ_F_POLL		= 1 << 0,
	/*
	 * Indicates that this zero-byte I/O quick command is a write. If this
	 * flag is not set then a quick command is a read.
	 */
	I2C_IO_REQ_F_QUICK_WRITE	= 1 << 1,
} i2c_req_flags_t;

typedef struct smbus_req {
	i2c_error_t smbr_error;
	smbus_op_t smbr_op;
	i2c_req_flags_t smbr_flags;
	i2c_addr_t smbr_addr;
	uint16_t smbr_wlen;
	uint16_t smbr_rlen;
	uint8_t smbr_cmd;
	uint8_t smbr_wdata[I2C_REQ_MAX];
	uint8_t smbr_rdata[I2C_REQ_MAX];
} smbus_req_t;

typedef struct i2c_req {
	i2c_error_t ir_error;
	i2c_req_flags_t ir_flags;
	i2c_addr_t ir_addr;
	uint16_t ir_wlen;
	uint16_t ir_rlen;
	uint8_t ir_wdata[I2C_REQ_MAX];
	uint8_t ir_rdata[I2C_REQ_MAX];
} i2c_req_t;

typedef enum i2c_prop_type {
	/*
	 * A property that is a standard, scalar uint32_t.
	 */
	I2C_PROP_TYPE_U32,
	/*
	 * A property that fits in a uint32_t, but represents a bitfield of
	 * values.
	 */
	I2C_PROP_TYPE_BIT32
} i2c_prop_type_t;

typedef enum i2c_prop_perm {
	I2C_PROP_PERM_RO,
	I2C_PROP_PERM_RW
} i2c_prop_perm_t;

typedef struct i2c_prop_u32_range {
	uint32_t ipur_min;
	uint32_t ipur_max;
} i2c_prop_u32_range_t;

typedef union i2c_prop_val_range {
	uint32_t ipvr_bit32;
	i2c_prop_u32_range_t ipvr_u32;
} i2c_prop_val_range_t;

typedef struct i2c_prop_range {
	uint32_t ipr_count;
	i2c_prop_type_t ipr_type;
	i2c_prop_val_range_t ipr_range[];
} i2c_prop_range_t;

/*
 * This enumeration contains a list of the properties that are supported.
 *
 * In earlier designs we had an initial set of properties for setup and hold
 * time related aspects, but controllers don't really have a uniform design
 * here. Some offer different values for RX and TX. Some offer only a single
 * value.
 */
typedef enum i2c_prop {
	/*
	 * This is a uint32_t that is covered by the i2c_speed_t.
	 */
	I2C_PROP_BUS_SPEED	= 0,
	/*
	 * This is a uint32_t that indicates the number of ports the device has.
	 */
	I2C_PROP_NPORTS,
	/*
	 * This indicates the controller's type, which is covered by the
	 * i2c_ctrl_type_t.
	 */
	I2C_PROP_TYPE,
	/*
	 * SMBus operations that are supported by the controller. This is a
	 * uint32_t that covers smbus_prop_op_t.
	 */
	SMBUS_PROP_SUP_OPS,
	/*
	 * Maximum sizes that a controller can support for performing different
	 * kinds of I/O. We expect that most I2C controllers will only support a
	 *
	 * single read/write buffer. For SMBus controllers, they should specify
	 * the maximum block size. This covers block reads, writes, and calls.
	 * If a controller supports an I2C mode with a different maximum, then
	 * it can additionally specify the I2c properties.
	 */
	I2C_PROP_MAX_READ,
	I2C_PROP_MAX_WRITE,
	SMBUS_PROP_MAX_BLOCK,
	/*
	 * Properties for different timing parameters in I2C devices. These are
	 * all uint32_t values generally in clock cycles.
	 */
	I2C_PROP_STD_SCL_HIGH,
	I2C_PROP_STD_SCL_LOW,
	I2C_PROP_FAST_SCL_HIGH,
	I2C_PROP_FAST_SCL_LOW,
	I2C_PROP_HIGH_SCL_HIGH,
	I2C_PROP_HIGH_SCL_LOW
} i2c_prop_t;

typedef enum smbus_prop_op {
	SMBUS_PROP_OP_QUICK_COMMAND = 1 << SMBUS_OP_QUICK_COMMAND,
	SMBUS_PROP_OP_SEND_BYTE = 1 << SMBUS_OP_SEND_BYTE,
	SMBUS_PROP_OP_RECV_BYTE = 1 << SMBUS_OP_RECV_BYTE,
	SMBUS_PROP_OP_WRITE_BYTE = 1 << SMBUS_OP_WRITE_BYTE,
	SMBUS_PROP_OP_READ_BYTE = 1 << SMBUS_OP_READ_BYTE,
	SMBUS_PROP_OP_WRITE_WORD = 1 << SMBUS_OP_WRITE_WORD,
	SMBUS_PROP_OP_READ_WORD = 1 << SMBUS_OP_READ_WORD,
	SMBUS_PROP_OP_PROCESS_CALL = 1 << SMBUS_OP_PROCESS_CALL,
	SMBUS_PROP_OP_WRITE_BLOCK = 1 << SMBUS_OP_WRITE_BLOCK,
	SMBUS_PROP_OP_READ_BLOCK = 1 << SMBUS_OP_READ_BLOCK,
	SMBUS_PROP_OP_HOST_NOTIFY = 1 << SMBUS_OP_HOST_NOTIFY,
	SMBUS_PROP_OP_BLOCK_PROCESS_CALL = 1 << SMBUS_OP_BLOCK_PROCESS_CALL,
	SMBUS_PROP_OP_WRITE_U32 = 1 << SMBUS_OP_WRITE_U32,
	SMBUS_PROP_OP_READ_U32 = 1 << SMBUS_OP_READ_U32,
	SMBUS_PROP_OP_WRITE_U64 = 1 << SMBUS_OP_WRITE_U64,
	SMBUS_PROP_OP_READ_U64 = 1 << SMBUS_OP_READ_U64,
	SMBUS_PROP_OP_I2C_WRITE_BLOCK = 1 << SMBUS_OP_I2C_WRITE_BLOCK,
	SMBUS_PROP_OP_I2C_READ_BLOCK = 1 << SMBUS_OP_I2C_READ_BLOCK
} smbus_prop_op_t;

/*
 * The size in bytes of the maximum property name (including the NUL) and the
 * largest data size.
 */
#define	I2C_PROP_NAME_MAX	32
#define	I2C_PROP_SIZE_MAX	256

#ifdef __cplusplus
}
#endif

#endif /* _SYS_I2C_I2C_H */