i2cvar.h revision 1.32 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