1 1.32 thorpej /* $NetBSD: i2cvar.h,v 1.32 2025/09/21 14:43:19 thorpej Exp $ */ 2 1.1 thorpej 3 1.1 thorpej /* 4 1.1 thorpej * Copyright (c) 2003 Wasabi Systems, Inc. 5 1.1 thorpej * All rights reserved. 6 1.1 thorpej * 7 1.1 thorpej * Written by Steve C. Woodford and Jason R. Thorpe for Wasabi Systems, Inc. 8 1.1 thorpej * 9 1.1 thorpej * Redistribution and use in source and binary forms, with or without 10 1.1 thorpej * modification, are permitted provided that the following conditions 11 1.1 thorpej * are met: 12 1.1 thorpej * 1. Redistributions of source code must retain the above copyright 13 1.1 thorpej * notice, this list of conditions and the following disclaimer. 14 1.1 thorpej * 2. Redistributions in binary form must reproduce the above copyright 15 1.1 thorpej * notice, this list of conditions and the following disclaimer in the 16 1.1 thorpej * documentation and/or other materials provided with the distribution. 17 1.1 thorpej * 3. All advertising materials mentioning features or use of this software 18 1.1 thorpej * must display the following acknowledgement: 19 1.1 thorpej * This product includes software developed for the NetBSD Project by 20 1.1 thorpej * Wasabi Systems, Inc. 21 1.1 thorpej * 4. The name of Wasabi Systems, Inc. may not be used to endorse 22 1.1 thorpej * or promote products derived from this software without specific prior 23 1.1 thorpej * written permission. 24 1.1 thorpej * 25 1.1 thorpej * THIS SOFTWARE IS PROVIDED BY WASABI SYSTEMS, INC. ``AS IS'' AND 26 1.1 thorpej * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27 1.1 thorpej * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28 1.1 thorpej * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL WASABI SYSTEMS, INC 29 1.1 thorpej * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30 1.1 thorpej * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31 1.1 thorpej * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32 1.1 thorpej * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33 1.1 thorpej * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34 1.1 thorpej * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35 1.1 thorpej * POSSIBILITY OF SUCH DAMAGE. 36 1.1 thorpej */ 37 1.1 thorpej 38 1.1 thorpej #ifndef _DEV_I2C_I2CVAR_H_ 39 1.1 thorpej #define _DEV_I2C_I2CVAR_H_ 40 1.1 thorpej 41 1.14 thorpej #include <sys/device.h> 42 1.19 thorpej #include <sys/mutex.h> 43 1.1 thorpej #include <dev/i2c/i2c_io.h> 44 1.9 jmcneill #include <prop/proplib.h> 45 1.1 thorpej 46 1.1 thorpej /* Flags passed to i2c routines. */ 47 1.21 thorpej #define I2C_F_WRITE 0 /* new transfer is a write */ 48 1.21 thorpej #define I2C_F_READ __BIT(0) /* new transfer is a read */ 49 1.21 thorpej #define I2C_F_LAST __BIT(1) /* last byte of read */ 50 1.21 thorpej #define I2C_F_STOP __BIT(2) /* send stop after byte */ 51 1.21 thorpej #define I2C_F_POLL __BIT(3) /* poll, don't sleep */ 52 1.21 thorpej #define I2C_F_PEC __BIT(4) /* smbus packet error checking */ 53 1.21 thorpej #define I2C_F_SPEED __BITS(28,31) /* I2C transfer speed selector */ 54 1.21 thorpej 55 1.21 thorpej #define I2C_SPEED_SM 0 /* standard mode (100Kb/s) */ 56 1.21 thorpej #define I2C_SPEED_FM 1 /* fast mode (400Kb/s) */ 57 1.21 thorpej #define I2C_SPEED_FMPLUS 2 /* fast mode+ (1Mb/s) */ 58 1.21 thorpej #define I2C_SPEED_HS 3 /* high speed (3.4Mb/s) */ 59 1.1 thorpej 60 1.13 thorpej /* i2c bus instance properties */ 61 1.13 thorpej #define I2C_PROP_INDIRECT_PROBE_STRATEGY \ 62 1.13 thorpej "i2c-indirect-probe-strategy" 63 1.13 thorpej #define I2C_PROBE_STRATEGY_QUICK_WRITE \ 64 1.13 thorpej "smbus-quick-write" 65 1.13 thorpej #define I2C_PROBE_STRATEGY_RECEIVE_BYTE \ 66 1.13 thorpej "smbus-receive-byte" 67 1.13 thorpej #define I2C_PROBE_STRATEGY_NONE \ 68 1.13 thorpej "none" 69 1.13 thorpej 70 1.20 thorpej #define I2C_PROP_INDIRECT_DEVICE_PERMITLIST \ 71 1.20 thorpej "i2c-indirect-device-permitlist" 72 1.13 thorpej /* value is a prop_array of prop_strings */ 73 1.13 thorpej 74 1.1 thorpej /* 75 1.1 thorpej * This structure provides the interface between the i2c framework 76 1.1 thorpej * and the underlying i2c controller. 77 1.1 thorpej * 78 1.1 thorpej * Note that this structure is designed specifically to allow us 79 1.1 thorpej * to either use the autoconfiguration framework or not. This 80 1.1 thorpej * allows a driver for a board with a private i2c bus use generic 81 1.1 thorpej * i2c client drivers for chips that might be on that board. 82 1.1 thorpej */ 83 1.1 thorpej typedef struct i2c_controller { 84 1.1 thorpej void *ic_cookie; /* controller private */ 85 1.1 thorpej 86 1.1 thorpej /* 87 1.32 thorpej * Multi-channel i2c controllers and i2c muxes allow 88 1.32 thorpej * for multiple busses to be driven by a single block 89 1.32 thorpej * of controller logic. Each of these busses is 90 1.32 thorpej * represented by a logical controller with its own 91 1.32 thorpej * i2c_tag_t. By default, each i2c_tag_t is initialized 92 1.32 thorpej * indicating a single-bus controller, but multi-channel 93 1.32 thorpej * controllers and muxes should initialize this field to 94 1.32 thorpej * indicate which logical bus number this i2c_tag_t is 95 1.32 thorpej * associated with. 96 1.32 thorpej */ 97 1.32 thorpej int ic_channel; 98 1.32 thorpej 99 1.32 thorpej /* 100 1.1 thorpej * These provide synchronization in the presence of 101 1.1 thorpej * multiple users of the i2c bus. When a device 102 1.1 thorpej * driver wishes to perform transfers on the i2c 103 1.1 thorpej * bus, the driver should acquire the bus. When 104 1.1 thorpej * the driver is finished, it should release the 105 1.1 thorpej * bus. 106 1.1 thorpej * 107 1.19 thorpej * The main synchronization logic is handled by the 108 1.19 thorpej * generic i2c layer, but optional hooks to back-end 109 1.19 thorpej * drivers are provided in case additional processing 110 1.19 thorpej * is needed (e.g. enabling the i2c controller). 111 1.1 thorpej */ 112 1.19 thorpej kmutex_t ic_bus_lock; 113 1.1 thorpej int (*ic_acquire_bus)(void *, int); 114 1.1 thorpej void (*ic_release_bus)(void *, int); 115 1.1 thorpej 116 1.1 thorpej /* 117 1.1 thorpej * The preferred API for clients of the i2c interface 118 1.1 thorpej * is the scripted API. This handles i2c controllers 119 1.1 thorpej * that do not provide raw access to the i2c signals. 120 1.1 thorpej */ 121 1.1 thorpej int (*ic_exec)(void *, i2c_op_t, i2c_addr_t, const void *, size_t, 122 1.1 thorpej void *, size_t, int); 123 1.1 thorpej 124 1.1 thorpej int (*ic_send_start)(void *, int); 125 1.1 thorpej int (*ic_send_stop)(void *, int); 126 1.1 thorpej int (*ic_initiate_xfer)(void *, i2c_addr_t, int); 127 1.1 thorpej int (*ic_read_byte)(void *, uint8_t *, int); 128 1.1 thorpej int (*ic_write_byte)(void *, uint8_t, int); 129 1.5 jmcneill 130 1.32 thorpej /* For future expansion; do not remove. */ 131 1.26 riastrad struct i2c_tag_private *ic_tag_private; 132 1.1 thorpej } *i2c_tag_t; 133 1.1 thorpej 134 1.32 thorpej #define I2C_CHANNEL_DEFAULT -1 135 1.32 thorpej 136 1.32 thorpej static inline int 137 1.32 thorpej i2c_tag_channel(i2c_tag_t tag) 138 1.32 thorpej { 139 1.32 thorpej return tag->ic_channel == I2C_CHANNEL_DEFAULT ? 0 140 1.32 thorpej : tag->ic_channel; 141 1.32 thorpej } 142 1.32 thorpej 143 1.1 thorpej /* Used to attach the i2c framework to the controller. */ 144 1.1 thorpej struct i2cbus_attach_args { 145 1.1 thorpej i2c_tag_t iba_tag; /* the controller */ 146 1.1 thorpej }; 147 1.1 thorpej 148 1.1 thorpej /* Used to attach devices on the i2c bus. */ 149 1.1 thorpej struct i2c_attach_args { 150 1.1 thorpej i2c_tag_t ia_tag; /* our controller */ 151 1.1 thorpej i2c_addr_t ia_addr; /* address of device */ 152 1.32 thorpej 153 1.7 martin /* only set if using direct config */ 154 1.7 martin const char * ia_name; /* name of the device */ 155 1.32 thorpej const char * ia_clist; /* compatible strlist */ 156 1.32 thorpej size_t ia_clist_size; /* size of compatible strlist */ 157 1.32 thorpej devhandle_t ia_devhandle; /* device handle for the device */ 158 1.1 thorpej }; 159 1.1 thorpej 160 1.1 thorpej /* 161 1.1 thorpej * API presented to i2c controllers. 162 1.1 thorpej */ 163 1.1 thorpej int iicbus_print(void *, const char *); 164 1.19 thorpej void iic_tag_init(i2c_tag_t); 165 1.19 thorpej void iic_tag_fini(i2c_tag_t); 166 1.14 thorpej 167 1.31 thorpej int iic_acquire_bus_lock(kmutex_t *, int); 168 1.31 thorpej void iic_release_bus_lock(kmutex_t *); 169 1.31 thorpej 170 1.27 thorpej static inline device_t 171 1.28 thorpej iicbus_attach_with_devhandle(device_t dev, i2c_tag_t tag, devhandle_t devhandle) 172 1.27 thorpej { 173 1.27 thorpej struct i2cbus_attach_args iba = { 174 1.27 thorpej .iba_tag = tag, 175 1.27 thorpej }; 176 1.27 thorpej return config_found(dev, &iba, iicbus_print, 177 1.27 thorpej CFARGS(.iattr = "i2cbus", 178 1.28 thorpej .devhandle = devhandle)); 179 1.28 thorpej } 180 1.28 thorpej 181 1.28 thorpej static inline device_t 182 1.28 thorpej iicbus_attach(device_t dev, i2c_tag_t tag) 183 1.28 thorpej { 184 1.28 thorpej return iicbus_attach_with_devhandle(dev, tag, device_handle(dev)); 185 1.27 thorpej } 186 1.27 thorpej 187 1.14 thorpej /* 188 1.14 thorpej * API presented to i2c devices. 189 1.14 thorpej */ 190 1.16 thorpej int iic_compatible_match(const struct i2c_attach_args *, 191 1.22 thorpej const struct device_compatible_entry *); 192 1.15 thorpej bool iic_use_direct_match(const struct i2c_attach_args *, const cfdata_t, 193 1.15 thorpej const struct device_compatible_entry *, int *); 194 1.22 thorpej const struct device_compatible_entry * 195 1.22 thorpej iic_compatible_lookup(const struct i2c_attach_args *, 196 1.22 thorpej const struct device_compatible_entry *); 197 1.1 thorpej 198 1.13 thorpej /* 199 1.13 thorpej * Constants to indicate the quality of a match made by a driver's 200 1.25 andvar * match routine, from lowest to highest: 201 1.13 thorpej * 202 1.13 thorpej * -- Address only; no other checks were made. 203 1.13 thorpej * 204 1.13 thorpej * -- Address + device probed and recognized. 205 1.13 thorpej * 206 1.13 thorpej * -- Direct-config match by "compatible" string. 207 1.13 thorpej * 208 1.13 thorpej * -- Direct-config match by specific driver name. 209 1.13 thorpej */ 210 1.13 thorpej #define I2C_MATCH_ADDRESS_ONLY 1 211 1.13 thorpej #define I2C_MATCH_ADDRESS_AND_PROBE 2 212 1.13 thorpej #define I2C_MATCH_DIRECT_COMPATIBLE 10 213 1.14 thorpej #define I2C_MATCH_DIRECT_COMPATIBLE_MAX 99 214 1.14 thorpej #define I2C_MATCH_DIRECT_SPECIFIC 100 215 1.13 thorpej 216 1.1 thorpej #ifdef _I2C_PRIVATE 217 1.1 thorpej /* 218 1.1 thorpej * Macros used internally by the i2c framework. 219 1.1 thorpej */ 220 1.1 thorpej #define iic_send_start(ic, flags) \ 221 1.1 thorpej (*(ic)->ic_send_start)((ic)->ic_cookie, (flags)) 222 1.1 thorpej #define iic_send_stop(ic, flags) \ 223 1.1 thorpej (*(ic)->ic_send_stop)((ic)->ic_cookie, (flags)) 224 1.1 thorpej #define iic_initiate_xfer(ic, addr, flags) \ 225 1.1 thorpej (*(ic)->ic_initiate_xfer)((ic)->ic_cookie, (addr), (flags)) 226 1.1 thorpej 227 1.1 thorpej #define iic_read_byte(ic, bytep, flags) \ 228 1.1 thorpej (*(ic)->ic_read_byte)((ic)->ic_cookie, (bytep), (flags)) 229 1.1 thorpej #define iic_write_byte(ic, byte, flags) \ 230 1.1 thorpej (*(ic)->ic_write_byte)((ic)->ic_cookie, (byte), (flags)) 231 1.1 thorpej #endif /* _I2C_PRIVATE */ 232 1.1 thorpej 233 1.1 thorpej /* 234 1.1 thorpej * Simplified API for clients of the i2c framework. Definitions 235 1.1 thorpej * in <dev/i2c/i2c_io.h>. 236 1.1 thorpej */ 237 1.18 thorpej int iic_acquire_bus(i2c_tag_t, int); 238 1.18 thorpej void iic_release_bus(i2c_tag_t, int); 239 1.1 thorpej int iic_exec(i2c_tag_t, i2c_op_t, i2c_addr_t, const void *, 240 1.1 thorpej size_t, void *, size_t, int); 241 1.1 thorpej 242 1.1 thorpej int iic_smbus_write_byte(i2c_tag_t, i2c_addr_t, uint8_t, uint8_t, int); 243 1.3 jmcneill int iic_smbus_write_word(i2c_tag_t, i2c_addr_t, uint8_t, uint16_t, int); 244 1.1 thorpej int iic_smbus_read_byte(i2c_tag_t, i2c_addr_t, uint8_t, uint8_t *, int); 245 1.3 jmcneill int iic_smbus_read_word(i2c_tag_t, i2c_addr_t, uint8_t, uint16_t *, int); 246 1.1 thorpej int iic_smbus_receive_byte(i2c_tag_t, i2c_addr_t, uint8_t *, int); 247 1.3 jmcneill int iic_smbus_send_byte(i2c_tag_t, i2c_addr_t, uint8_t, int); 248 1.3 jmcneill int iic_smbus_quick_read(i2c_tag_t, i2c_addr_t, int); 249 1.3 jmcneill int iic_smbus_quick_write(i2c_tag_t, i2c_addr_t, int); 250 1.3 jmcneill int iic_smbus_block_read(i2c_tag_t, i2c_addr_t, uint8_t, uint8_t *, 251 1.3 jmcneill size_t, int); 252 1.3 jmcneill int iic_smbus_block_write(i2c_tag_t, i2c_addr_t, uint8_t, uint8_t *, 253 1.3 jmcneill size_t, int); 254 1.1 thorpej 255 1.1 thorpej #endif /* _DEV_I2C_I2CVAR_H_ */ 256