diff options
Diffstat (limited to 'Documentation/i2c/instantiating-devices')
| -rw-r--r-- | Documentation/i2c/instantiating-devices | 248 |
1 files changed, 0 insertions, 248 deletions
diff --git a/Documentation/i2c/instantiating-devices b/Documentation/i2c/instantiating-devices deleted file mode 100644 index 345e9ea8281a..000000000000 --- a/Documentation/i2c/instantiating-devices +++ /dev/null @@ -1,248 +0,0 @@ -How to instantiate I2C devices -============================== - -Unlike PCI or USB devices, I2C devices are not enumerated at the hardware -level. Instead, the software must know which devices are connected on each -I2C bus segment, and what address these devices are using. For this -reason, the kernel code must instantiate I2C devices explicitly. There are -several ways to achieve this, depending on the context and requirements. - - -Method 1a: Declare the I2C devices by bus number ------------------------------------------------- - -This method is appropriate when the I2C bus is a system bus as is the case -for many embedded systems. On such systems, each I2C bus has a number -which is known in advance. It is thus possible to pre-declare the I2C -devices which live on this bus. This is done with an array of struct -i2c_board_info which is registered by calling i2c_register_board_info(). - -Example (from omap2 h4): - -static struct i2c_board_info h4_i2c_board_info[] __initdata = { - { - I2C_BOARD_INFO("isp1301_omap", 0x2d), - .irq = OMAP_GPIO_IRQ(125), - }, - { /* EEPROM on mainboard */ - I2C_BOARD_INFO("24c01", 0x52), - .platform_data = &m24c01, - }, - { /* EEPROM on cpu card */ - I2C_BOARD_INFO("24c01", 0x57), - .platform_data = &m24c01, - }, -}; - -static void __init omap_h4_init(void) -{ - (...) - i2c_register_board_info(1, h4_i2c_board_info, - ARRAY_SIZE(h4_i2c_board_info)); - (...) -} - -The above code declares 3 devices on I2C bus 1, including their respective -addresses and custom data needed by their drivers. When the I2C bus in -question is registered, the I2C devices will be instantiated automatically -by i2c-core. - -The devices will be automatically unbound and destroyed when the I2C bus -they sit on goes away (if ever.) - - -Method 1b: Declare the I2C devices via devicetree -------------------------------------------------- - -This method has the same implications as method 1a. The declaration of I2C -devices is here done via devicetree as subnodes of the master controller. - -Example: - - i2c1: i2c@400a0000 { - /* ... master properties skipped ... */ - clock-frequency = <100000>; - - flash@50 { - compatible = "atmel,24c256"; - reg = <0x50>; - }; - - pca9532: gpio@60 { - compatible = "nxp,pca9532"; - gpio-controller; - #gpio-cells = <2>; - reg = <0x60>; - }; - }; - -Here, two devices are attached to the bus using a speed of 100kHz. For -additional properties which might be needed to set up the device, please refer -to its devicetree documentation in Documentation/devicetree/bindings/. - - -Method 1c: Declare the I2C devices via ACPI -------------------------------------------- - -ACPI can also describe I2C devices. There is special documentation for this -which is currently located at Documentation/firmware-guide/acpi/enumeration.rst. - - -Method 2: Instantiate the devices explicitly --------------------------------------------- - -This method is appropriate when a larger device uses an I2C bus for -internal communication. A typical case is TV adapters. These can have a -tuner, a video decoder, an audio decoder, etc. usually connected to the -main chip by the means of an I2C bus. You won't know the number of the I2C -bus in advance, so the method 1 described above can't be used. Instead, -you can instantiate your I2C devices explicitly. This is done by filling -a struct i2c_board_info and calling i2c_new_device(). - -Example (from the sfe4001 network driver): - -static struct i2c_board_info sfe4001_hwmon_info = { - I2C_BOARD_INFO("max6647", 0x4e), -}; - -int sfe4001_init(struct efx_nic *efx) -{ - (...) - efx->board_info.hwmon_client = - i2c_new_device(&efx->i2c_adap, &sfe4001_hwmon_info); - - (...) -} - -The above code instantiates 1 I2C device on the I2C bus which is on the -network adapter in question. - -A variant of this is when you don't know for sure if an I2C device is -present or not (for example for an optional feature which is not present -on cheap variants of a board but you have no way to tell them apart), or -it may have different addresses from one board to the next (manufacturer -changing its design without notice). In this case, you can call -i2c_new_probed_device() instead of i2c_new_device(). - -Example (from the nxp OHCI driver): - -static const unsigned short normal_i2c[] = { 0x2c, 0x2d, I2C_CLIENT_END }; - -static int usb_hcd_nxp_probe(struct platform_device *pdev) -{ - (...) - struct i2c_adapter *i2c_adap; - struct i2c_board_info i2c_info; - - (...) - i2c_adap = i2c_get_adapter(2); - memset(&i2c_info, 0, sizeof(struct i2c_board_info)); - strscpy(i2c_info.type, "isp1301_nxp", sizeof(i2c_info.type)); - isp1301_i2c_client = i2c_new_probed_device(i2c_adap, &i2c_info, - normal_i2c, NULL); - i2c_put_adapter(i2c_adap); - (...) -} - -The above code instantiates up to 1 I2C device on the I2C bus which is on -the OHCI adapter in question. It first tries at address 0x2c, if nothing -is found there it tries address 0x2d, and if still nothing is found, it -simply gives up. - -The driver which instantiated the I2C device is responsible for destroying -it on cleanup. This is done by calling i2c_unregister_device() on the -pointer that was earlier returned by i2c_new_device() or -i2c_new_probed_device(). - - -Method 3: Probe an I2C bus for certain devices ----------------------------------------------- - -Sometimes you do not have enough information about an I2C device, not even -to call i2c_new_probed_device(). The typical case is hardware monitoring -chips on PC mainboards. There are several dozen models, which can live -at 25 different addresses. Given the huge number of mainboards out there, -it is next to impossible to build an exhaustive list of the hardware -monitoring chips being used. Fortunately, most of these chips have -manufacturer and device ID registers, so they can be identified by -probing. - -In that case, I2C devices are neither declared nor instantiated -explicitly. Instead, i2c-core will probe for such devices as soon as their -drivers are loaded, and if any is found, an I2C device will be -instantiated automatically. In order to prevent any misbehavior of this -mechanism, the following restrictions apply: -* The I2C device driver must implement the detect() method, which - identifies a supported device by reading from arbitrary registers. -* Only buses which are likely to have a supported device and agree to be - probed, will be probed. For example this avoids probing for hardware - monitoring chips on a TV adapter. - -Example: -See lm90_driver and lm90_detect() in drivers/hwmon/lm90.c - -I2C devices instantiated as a result of such a successful probe will be -destroyed automatically when the driver which detected them is removed, -or when the underlying I2C bus is itself destroyed, whichever happens -first. - -Those of you familiar with the i2c subsystem of 2.4 kernels and early 2.6 -kernels will find out that this method 3 is essentially similar to what -was done there. Two significant differences are: -* Probing is only one way to instantiate I2C devices now, while it was the - only way back then. Where possible, methods 1 and 2 should be preferred. - Method 3 should only be used when there is no other way, as it can have - undesirable side effects. -* I2C buses must now explicitly say which I2C driver classes can probe - them (by the means of the class bitfield), while all I2C buses were - probed by default back then. The default is an empty class which means - that no probing happens. The purpose of the class bitfield is to limit - the aforementioned undesirable side effects. - -Once again, method 3 should be avoided wherever possible. Explicit device -instantiation (methods 1 and 2) is much preferred for it is safer and -faster. - - -Method 4: Instantiate from user-space -------------------------------------- - -In general, the kernel should know which I2C devices are connected and -what addresses they live at. However, in certain cases, it does not, so a -sysfs interface was added to let the user provide the information. This -interface is made of 2 attribute files which are created in every I2C bus -directory: new_device and delete_device. Both files are write only and you -must write the right parameters to them in order to properly instantiate, -respectively delete, an I2C device. - -File new_device takes 2 parameters: the name of the I2C device (a string) -and the address of the I2C device (a number, typically expressed in -hexadecimal starting with 0x, but can also be expressed in decimal.) - -File delete_device takes a single parameter: the address of the I2C -device. As no two devices can live at the same address on a given I2C -segment, the address is sufficient to uniquely identify the device to be -deleted. - -Example: -# echo eeprom 0x50 > /sys/bus/i2c/devices/i2c-3/new_device - -While this interface should only be used when in-kernel device declaration -can't be done, there is a variety of cases where it can be helpful: -* The I2C driver usually detects devices (method 3 above) but the bus - segment your device lives on doesn't have the proper class bit set and - thus detection doesn't trigger. -* The I2C driver usually detects devices, but your device lives at an - unexpected address. -* The I2C driver usually detects devices, but your device is not detected, - either because the detection routine is too strict, or because your - device is not officially supported yet but you know it is compatible. -* You are developing a driver on a test board, where you soldered the I2C - device yourself. - -This interface is a replacement for the force_* module parameters some I2C -drivers implement. Being implemented in i2c-core rather than in each -device driver individually, it is much more efficient, and also has the -advantage that you do not have to reload the driver to change a setting. -You can also instantiate the device before the driver is loaded or even -available, and you don't need to know what driver the device needs. |