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