Commit | Line | Data |
---|---|---|
ccf988b6 | 1 | ============================== |
764c1691 JD |
2 | How to instantiate I2C devices |
3 | ============================== | |
4 | ||
5 | Unlike PCI or USB devices, I2C devices are not enumerated at the hardware | |
6 | level. Instead, the software must know which devices are connected on each | |
7 | I2C bus segment, and what address these devices are using. For this | |
8 | reason, the kernel code must instantiate I2C devices explicitly. There are | |
9 | several ways to achieve this, depending on the context and requirements. | |
10 | ||
11 | ||
da9a80bf LC |
12 | Method 1: Declare the I2C devices statically |
13 | -------------------------------------------- | |
764c1691 JD |
14 | |
15 | This method is appropriate when the I2C bus is a system bus as is the case | |
da9a80bf LC |
16 | for many embedded systems. On such systems, each I2C bus has a number which |
17 | is known in advance. It is thus possible to pre-declare the I2C devices | |
18 | which live on this bus. | |
764c1691 | 19 | |
da9a80bf LC |
20 | This information is provided to the kernel in a different way on different |
21 | architectures: device tree, ACPI or board files. | |
764c1691 | 22 | |
da9a80bf LC |
23 | When the I2C bus in question is registered, the I2C devices will be |
24 | instantiated automatically by i2c-core. The devices will be automatically | |
25 | unbound and destroyed when the I2C bus they sit on goes away (if ever). | |
764c1691 | 26 | |
764c1691 | 27 | |
da9a80bf LC |
28 | Declare the I2C devices via devicetree |
29 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
764c1691 | 30 | |
da9a80bf LC |
31 | On platforms using devicetree, the declaration of I2C devices is done in |
32 | subnodes of the master controller. | |
aeca0fe6 | 33 | |
43310e27 LC |
34 | Example: |
35 | ||
36 | .. code-block:: dts | |
aeca0fe6 WS |
37 | |
38 | i2c1: i2c@400a0000 { | |
39 | /* ... master properties skipped ... */ | |
40 | clock-frequency = <100000>; | |
41 | ||
42 | flash@50 { | |
43 | compatible = "atmel,24c256"; | |
44 | reg = <0x50>; | |
45 | }; | |
46 | ||
47 | pca9532: gpio@60 { | |
48 | compatible = "nxp,pca9532"; | |
49 | gpio-controller; | |
50 | #gpio-cells = <2>; | |
51 | reg = <0x60>; | |
52 | }; | |
53 | }; | |
54 | ||
55 | Here, two devices are attached to the bus using a speed of 100kHz. For | |
56 | additional properties which might be needed to set up the device, please refer | |
57 | to its devicetree documentation in Documentation/devicetree/bindings/. | |
58 | ||
59 | ||
da9a80bf LC |
60 | Declare the I2C devices via ACPI |
61 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
fde1e418 WS |
62 | |
63 | ACPI can also describe I2C devices. There is special documentation for this | |
25edd3a1 | 64 | which is currently located at Documentation/firmware-guide/acpi/enumeration.rst. |
fde1e418 WS |
65 | |
66 | ||
da9a80bf LC |
67 | Declare the I2C devices in board files |
68 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
69 | ||
70 | In many embedded architectures, devicetree has replaced the old hardware | |
71 | description based on board files, but the latter are still used in old | |
72 | code. Instantiating I2C devices via board files is done with an array of | |
73 | struct i2c_board_info which is registered by calling | |
74 | i2c_register_board_info(). | |
75 | ||
43310e27 LC |
76 | Example (from omap2 h4): |
77 | ||
78 | .. code-block:: c | |
da9a80bf LC |
79 | |
80 | static struct i2c_board_info h4_i2c_board_info[] __initdata = { | |
81 | { | |
82 | I2C_BOARD_INFO("isp1301_omap", 0x2d), | |
83 | .irq = OMAP_GPIO_IRQ(125), | |
84 | }, | |
85 | { /* EEPROM on mainboard */ | |
86 | I2C_BOARD_INFO("24c01", 0x52), | |
87 | .platform_data = &m24c01, | |
88 | }, | |
89 | { /* EEPROM on cpu card */ | |
90 | I2C_BOARD_INFO("24c01", 0x57), | |
91 | .platform_data = &m24c01, | |
92 | }, | |
93 | }; | |
94 | ||
95 | static void __init omap_h4_init(void) | |
96 | { | |
97 | (...) | |
98 | i2c_register_board_info(1, h4_i2c_board_info, | |
99 | ARRAY_SIZE(h4_i2c_board_info)); | |
100 | (...) | |
101 | } | |
102 | ||
103 | The above code declares 3 devices on I2C bus 1, including their respective | |
104 | addresses and custom data needed by their drivers. | |
105 | ||
106 | ||
764c1691 JD |
107 | Method 2: Instantiate the devices explicitly |
108 | -------------------------------------------- | |
109 | ||
110 | This method is appropriate when a larger device uses an I2C bus for | |
111 | internal communication. A typical case is TV adapters. These can have a | |
112 | tuner, a video decoder, an audio decoder, etc. usually connected to the | |
113 | main chip by the means of an I2C bus. You won't know the number of the I2C | |
114 | bus in advance, so the method 1 described above can't be used. Instead, | |
115 | you can instantiate your I2C devices explicitly. This is done by filling | |
e634a50c | 116 | a struct i2c_board_info and calling i2c_new_client_device(). |
764c1691 | 117 | |
43310e27 LC |
118 | Example (from the sfe4001 network driver): |
119 | ||
120 | .. code-block:: c | |
764c1691 | 121 | |
ccf988b6 | 122 | static struct i2c_board_info sfe4001_hwmon_info = { |
764c1691 | 123 | I2C_BOARD_INFO("max6647", 0x4e), |
ccf988b6 | 124 | }; |
764c1691 | 125 | |
ccf988b6 MCC |
126 | int sfe4001_init(struct efx_nic *efx) |
127 | { | |
764c1691 JD |
128 | (...) |
129 | efx->board_info.hwmon_client = | |
e634a50c | 130 | i2c_new_client_device(&efx->i2c_adap, &sfe4001_hwmon_info); |
764c1691 JD |
131 | |
132 | (...) | |
ccf988b6 | 133 | } |
764c1691 JD |
134 | |
135 | The above code instantiates 1 I2C device on the I2C bus which is on the | |
136 | network adapter in question. | |
137 | ||
138 | A variant of this is when you don't know for sure if an I2C device is | |
139 | present or not (for example for an optional feature which is not present | |
140 | on cheap variants of a board but you have no way to tell them apart), or | |
141 | it may have different addresses from one board to the next (manufacturer | |
142 | changing its design without notice). In this case, you can call | |
e634a50c | 143 | i2c_new_scanned_device() instead of i2c_new_client_device(). |
764c1691 | 144 | |
43310e27 LC |
145 | Example (from the nxp OHCI driver): |
146 | ||
147 | .. code-block:: c | |
764c1691 | 148 | |
ccf988b6 | 149 | static const unsigned short normal_i2c[] = { 0x2c, 0x2d, I2C_CLIENT_END }; |
764c1691 | 150 | |
ccf988b6 MCC |
151 | static int usb_hcd_nxp_probe(struct platform_device *pdev) |
152 | { | |
764c1691 JD |
153 | (...) |
154 | struct i2c_adapter *i2c_adap; | |
155 | struct i2c_board_info i2c_info; | |
156 | ||
157 | (...) | |
158 | i2c_adap = i2c_get_adapter(2); | |
159 | memset(&i2c_info, 0, sizeof(struct i2c_board_info)); | |
220ee02a | 160 | strscpy(i2c_info.type, "isp1301_nxp", sizeof(i2c_info.type)); |
c1d08475 WS |
161 | isp1301_i2c_client = i2c_new_scanned_device(i2c_adap, &i2c_info, |
162 | normal_i2c, NULL); | |
764c1691 JD |
163 | i2c_put_adapter(i2c_adap); |
164 | (...) | |
ccf988b6 | 165 | } |
764c1691 JD |
166 | |
167 | The above code instantiates up to 1 I2C device on the I2C bus which is on | |
168 | the OHCI adapter in question. It first tries at address 0x2c, if nothing | |
169 | is found there it tries address 0x2d, and if still nothing is found, it | |
170 | simply gives up. | |
171 | ||
172 | The driver which instantiated the I2C device is responsible for destroying | |
173 | it on cleanup. This is done by calling i2c_unregister_device() on the | |
e634a50c | 174 | pointer that was earlier returned by i2c_new_client_device() or |
c1d08475 | 175 | i2c_new_scanned_device(). |
764c1691 JD |
176 | |
177 | ||
178 | Method 3: Probe an I2C bus for certain devices | |
179 | ---------------------------------------------- | |
180 | ||
181 | Sometimes you do not have enough information about an I2C device, not even | |
c1d08475 | 182 | to call i2c_new_scanned_device(). The typical case is hardware monitoring |
764c1691 JD |
183 | chips on PC mainboards. There are several dozen models, which can live |
184 | at 25 different addresses. Given the huge number of mainboards out there, | |
185 | it is next to impossible to build an exhaustive list of the hardware | |
186 | monitoring chips being used. Fortunately, most of these chips have | |
187 | manufacturer and device ID registers, so they can be identified by | |
188 | probing. | |
189 | ||
190 | In that case, I2C devices are neither declared nor instantiated | |
191 | explicitly. Instead, i2c-core will probe for such devices as soon as their | |
192 | drivers are loaded, and if any is found, an I2C device will be | |
193 | instantiated automatically. In order to prevent any misbehavior of this | |
194 | mechanism, the following restrictions apply: | |
ccf988b6 | 195 | |
764c1691 JD |
196 | * The I2C device driver must implement the detect() method, which |
197 | identifies a supported device by reading from arbitrary registers. | |
198 | * Only buses which are likely to have a supported device and agree to be | |
199 | probed, will be probed. For example this avoids probing for hardware | |
200 | monitoring chips on a TV adapter. | |
201 | ||
202 | Example: | |
203 | See lm90_driver and lm90_detect() in drivers/hwmon/lm90.c | |
204 | ||
205 | I2C devices instantiated as a result of such a successful probe will be | |
206 | destroyed automatically when the driver which detected them is removed, | |
207 | or when the underlying I2C bus is itself destroyed, whichever happens | |
208 | first. | |
209 | ||
2f07c05f | 210 | Those of you familiar with the I2C subsystem of 2.4 kernels and early 2.6 |
764c1691 JD |
211 | kernels will find out that this method 3 is essentially similar to what |
212 | was done there. Two significant differences are: | |
ccf988b6 | 213 | |
764c1691 JD |
214 | * Probing is only one way to instantiate I2C devices now, while it was the |
215 | only way back then. Where possible, methods 1 and 2 should be preferred. | |
216 | Method 3 should only be used when there is no other way, as it can have | |
217 | undesirable side effects. | |
218 | * I2C buses must now explicitly say which I2C driver classes can probe | |
219 | them (by the means of the class bitfield), while all I2C buses were | |
220 | probed by default back then. The default is an empty class which means | |
221 | that no probing happens. The purpose of the class bitfield is to limit | |
222 | the aforementioned undesirable side effects. | |
223 | ||
224 | Once again, method 3 should be avoided wherever possible. Explicit device | |
225 | instantiation (methods 1 and 2) is much preferred for it is safer and | |
226 | faster. | |
99cd8e25 JD |
227 | |
228 | ||
229 | Method 4: Instantiate from user-space | |
230 | ------------------------------------- | |
231 | ||
232 | In general, the kernel should know which I2C devices are connected and | |
233 | what addresses they live at. However, in certain cases, it does not, so a | |
234 | sysfs interface was added to let the user provide the information. This | |
235 | interface is made of 2 attribute files which are created in every I2C bus | |
22714ef8 LC |
236 | directory: ``new_device`` and ``delete_device``. Both files are write |
237 | only and you must write the right parameters to them in order to properly | |
238 | instantiate, respectively delete, an I2C device. | |
99cd8e25 | 239 | |
22714ef8 LC |
240 | File ``new_device`` takes 2 parameters: the name of the I2C device (a |
241 | string) and the address of the I2C device (a number, typically expressed | |
242 | in hexadecimal starting with 0x, but can also be expressed in decimal.) | |
99cd8e25 | 243 | |
22714ef8 | 244 | File ``delete_device`` takes a single parameter: the address of the I2C |
99cd8e25 JD |
245 | device. As no two devices can live at the same address on a given I2C |
246 | segment, the address is sufficient to uniquely identify the device to be | |
247 | deleted. | |
248 | ||
ccf988b6 MCC |
249 | Example:: |
250 | ||
251 | # echo eeprom 0x50 > /sys/bus/i2c/devices/i2c-3/new_device | |
99cd8e25 JD |
252 | |
253 | While this interface should only be used when in-kernel device declaration | |
254 | can't be done, there is a variety of cases where it can be helpful: | |
ccf988b6 | 255 | |
99cd8e25 JD |
256 | * The I2C driver usually detects devices (method 3 above) but the bus |
257 | segment your device lives on doesn't have the proper class bit set and | |
258 | thus detection doesn't trigger. | |
259 | * The I2C driver usually detects devices, but your device lives at an | |
260 | unexpected address. | |
261 | * The I2C driver usually detects devices, but your device is not detected, | |
262 | either because the detection routine is too strict, or because your | |
263 | device is not officially supported yet but you know it is compatible. | |
264 | * You are developing a driver on a test board, where you soldered the I2C | |
265 | device yourself. | |
266 | ||
267 | This interface is a replacement for the force_* module parameters some I2C | |
268 | drivers implement. Being implemented in i2c-core rather than in each | |
269 | device driver individually, it is much more efficient, and also has the | |
270 | advantage that you do not have to reload the driver to change a setting. | |
271 | You can also instantiate the device before the driver is loaded or even | |
272 | available, and you don't need to know what driver the device needs. |