1 /* 2 * This file and its contents are supplied under the terms of the 3 * Common Development and Distribution License ("CDDL"), version 1.0. 4 * You may only use this file in accordance with the terms of version 5 * 1.0 of the CDDL. 6 * 7 * A full copy of the text of the CDDL should have accompanied this 8 * source. A copy of the CDDL is also available via the Internet at 9 * http://www.illumos.org/license/CDDL. 10 */ 11 12 /* 13 * Copyright 2025 Oxide Computer Company 14 */ 15 16 #ifndef _SYS_I2C_CONTROLLER_H 17 #define _SYS_I2C_CONTROLLER_H 18 19 /* 20 * This file contains the definitions that I2C, I3C, and SMBus controller 21 * drivers should use to interface with the system's i2c stack. 22 */ 23 24 #include <sys/devops.h> 25 #include <sys/i2c/i2c.h> 26 27 #ifdef __cplusplus 28 extern "C" { 29 #endif 30 31 /* 32 * Current version of the interface expected by the i2c controller provider. 33 */ 34 #define I2C_CTRL_PROVIDER_V0 0 35 #define I2C_CTRL_PROVIDER I2C_CTRL_PROVIDER_V0 36 37 typedef struct i2c_prop_info i2c_prop_info_t; 38 39 typedef struct i2c_ctrl_ops { 40 bool (*i2c_port_name_f)(void *, uint32_t, char *, size_t); 41 void (*i2c_io_smbus_f)(void *, uint32_t, smbus_req_t *); 42 void (*i2c_io_i2c_f)(void *, uint32_t, i2c_req_t *); 43 i2c_errno_t (*i2c_prop_info_f)(void *, i2c_prop_t, i2c_prop_info_t *); 44 i2c_errno_t (*i2c_prop_get_f)(void *, i2c_prop_t, void *, size_t); 45 i2c_errno_t (*i2c_prop_set_f)(void *, i2c_prop_t, const void *, size_t); 46 } i2c_ctrl_ops_t; 47 48 typedef struct i2c_ctrl_register { 49 uint32_t ic_vers; 50 i2c_ctrl_type_t ic_type; 51 const char *ic_name; 52 uint32_t ic_nports; 53 dev_info_t *ic_dip; 54 void *ic_drv; 55 const i2c_ctrl_ops_t *ic_ops; 56 } i2c_ctrl_register_t; 57 58 /* 59 * Opaque structures for registration handles. 60 */ 61 typedef struct i2c_ctrl_hdl i2c_ctrl_hdl_t; 62 63 typedef enum { 64 I2C_CTRL_REG_E_OK = 0, 65 I2C_CTRL_REG_E_BAD_VERS, 66 I2C_CTRL_REG_E_NULL_ARG, 67 I2C_CTRL_REG_E_BAD_OPS, 68 I2C_CTRL_REG_E_NEED_PORT_NAME_FUNC, 69 I2C_CTRL_REG_E_NEED_PROP_GET_FUNC, 70 I2C_CTRL_REG_E_NEED_PROP_INFO_FUNC, 71 I2C_CTRL_REG_E_BAD_CTRL_TYPE, 72 I2C_CTRL_REG_E_UNSUP_CTRL_TYPE, 73 I2C_CTRL_REG_E_BAD_DIP, 74 I2C_CTRL_REG_E_BAD_NPORTS, 75 I2C_CTRL_REG_E_BAD_NAME, 76 I2C_CTRL_REG_E_INTERNAL, 77 I2C_CTRL_REG_E_BAD_MOD_TYPE, 78 I2C_CTRL_REG_E_NEXUS, 79 I2C_CTRL_REG_E_NOT_UNIQUE, 80 I2C_CTRL_REG_E_REQ_PROP, 81 I2C_CTLR_REG_E_BAD_PROP_VAL 82 } i2c_ctrl_reg_error_t; 83 84 extern void i2c_ctrl_mod_init(struct dev_ops *); 85 extern void i2c_ctrl_mod_fini(struct dev_ops *); 86 extern i2c_ctrl_reg_error_t i2c_ctrl_register_alloc(uint32_t, 87 i2c_ctrl_register_t **); 88 extern void i2c_ctrl_register_free(i2c_ctrl_register_t *); 89 90 extern i2c_ctrl_reg_error_t i2c_ctrl_register(const i2c_ctrl_register_t *, 91 i2c_ctrl_hdl_t **); 92 extern i2c_ctrl_reg_error_t i2c_ctrl_unregister(i2c_ctrl_hdl_t *); 93 94 /* 95 * The i2c_ctrl_port_name_portno() function is the default controller port 96 * naming function that names the port after the controller. For systems where 97 * ther isn't a complex I/O Mux element or some other naming case, this should 98 * be what they use. 99 */ 100 extern bool i2c_ctrl_port_name_portno(void *, uint32_t, char *, size_t); 101 102 /* 103 * Various functions that can be called to set the results of I/O commands. 104 */ 105 extern void i2c_ctrl_io_success(i2c_error_t *); 106 extern void i2c_ctrl_io_error(i2c_error_t *, i2c_errno_t, i2c_ctrl_error_t); 107 108 /* 109 * Property information interfaces. 110 */ 111 extern void i2c_prop_info_set_perm(i2c_prop_info_t *, i2c_prop_perm_t); 112 extern void i2c_prop_info_set_def_u32(i2c_prop_info_t *, uint32_t); 113 extern void i2c_prop_info_set_range_u32(i2c_prop_info_t *, uint32_t, uint32_t); 114 extern void i2c_prop_info_set_pos_bit32(i2c_prop_info_t *, uint32_t); 115 116 /* 117 * Ways for a driver to discover timeout parameters to use. 118 */ 119 typedef enum { 120 /* 121 * This is the amount of time that a given I/O command should take 122 * before the request is timed out. 123 */ 124 I2C_CTRL_TO_IO, 125 /* 126 * This is the amount of time to busy-wait while polling the controller 127 * for I/O to advance. 128 */ 129 I2C_CTRL_TO_POLL_CTRL, 130 /* 131 * This is the amount of time to wait for the bus to be clear for use 132 * before beginning a transaction. 133 */ 134 I2C_CTRL_TO_BUS_ACT, 135 /* 136 * This is the amount of time to wait for an abort to complete. 137 */ 138 I2C_CTRL_TO_ABORT 139 } i2c_ctrl_timeout_t; 140 extern uint32_t i2c_ctrl_timeout_count(i2c_ctrl_hdl_t *, i2c_ctrl_timeout_t); 141 extern uint32_t i2c_ctrl_timeout_delay_us(i2c_ctrl_hdl_t *, i2c_ctrl_timeout_t); 142 143 #ifdef __cplusplus 144 } 145 #endif 146 147 #endif /* _SYS_I2C_CONTROLLER_H */ 148