| 1 | ==============================
|
| 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 |
|
| 12 | Method 1: Declare the I2C devices statically
|
| 13 | --------------------------------------------
|
| 14 |
|
| 15 | This method is appropriate when the I2C bus is a system bus as is the case
|
| 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.
|
| 19 |
|
| 20 | This information is provided to the kernel in a different way on different
|
| 21 | architectures: device tree, ACPI or board files.
|
| 22 |
|
| 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).
|
| 26 |
|
| 27 |
|
| 28 | Declare the I2C devices via devicetree
|
| 29 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
| 30 |
|
| 31 | On platforms using devicetree, the declaration of I2C devices is done in
|
| 32 | subnodes of the master controller.
|
| 33 |
|
| 34 | Example:
|
| 35 |
|
| 36 | .. code-block:: dts
|
| 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 |
|
| 60 | Declare the I2C devices via ACPI
|
| 61 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
| 62 |
|
| 63 | ACPI can also describe I2C devices. There is special documentation for this
|
| 64 | which is currently located at Documentation/firmware-guide/acpi/enumeration.rst.
|
| 65 |
|
| 66 |
|
| 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 |
|
| 76 | Example (from omap2 h4):
|
| 77 |
|
| 78 | .. code-block:: c
|
| 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 |
|
| 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
|
| 116 | a struct i2c_board_info and calling i2c_new_client_device().
|
| 117 |
|
| 118 | Example (from the sfe4001 network driver):
|
| 119 |
|
| 120 | .. code-block:: c
|
| 121 |
|
| 122 | static struct i2c_board_info sfe4001_hwmon_info = {
|
| 123 | I2C_BOARD_INFO("max6647", 0x4e),
|
| 124 | };
|
| 125 |
|
| 126 | int sfe4001_init(struct efx_nic *efx)
|
| 127 | {
|
| 128 | (...)
|
| 129 | efx->board_info.hwmon_client =
|
| 130 | i2c_new_client_device(&efx->i2c_adap, &sfe4001_hwmon_info);
|
| 131 |
|
| 132 | (...)
|
| 133 | }
|
| 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
|
| 143 | i2c_new_scanned_device() instead of i2c_new_client_device().
|
| 144 |
|
| 145 | Example (from the nxp OHCI driver):
|
| 146 |
|
| 147 | .. code-block:: c
|
| 148 |
|
| 149 | static const unsigned short normal_i2c[] = { 0x2c, 0x2d, I2C_CLIENT_END };
|
| 150 |
|
| 151 | static int usb_hcd_nxp_probe(struct platform_device *pdev)
|
| 152 | {
|
| 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));
|
| 160 | strscpy(i2c_info.type, "isp1301_nxp", sizeof(i2c_info.type));
|
| 161 | isp1301_i2c_client = i2c_new_scanned_device(i2c_adap, &i2c_info,
|
| 162 | normal_i2c, NULL);
|
| 163 | i2c_put_adapter(i2c_adap);
|
| 164 | (...)
|
| 165 | }
|
| 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
|
| 174 | pointer that was earlier returned by i2c_new_client_device() or
|
| 175 | i2c_new_scanned_device().
|
| 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
|
| 182 | to call i2c_new_scanned_device(). The typical case is hardware monitoring
|
| 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:
|
| 195 |
|
| 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 |
|
| 210 | Those of you familiar with the I2C subsystem of 2.4 kernels and early 2.6
|
| 211 | kernels will find out that this method 3 is essentially similar to what
|
| 212 | was done there. Two significant differences are:
|
| 213 |
|
| 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.
|
| 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
|
| 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.
|
| 239 |
|
| 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.)
|
| 243 |
|
| 244 | File ``delete_device`` takes a single parameter: the address of the I2C
|
| 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 |
|
| 249 | Example::
|
| 250 |
|
| 251 | # echo eeprom 0x50 > /sys/bus/i2c/devices/i2c-3/new_device
|
| 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:
|
| 255 |
|
| 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.
|