| 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 1: 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 __initdata h4_i2c_board_info[] = { |
| { |
| 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 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 pnx4008 OHCI driver): |
| |
| static const unsigned short normal_i2c[] = { 0x2c, 0x2d, I2C_CLIENT_END }; |
| |
| static int __devinit usb_hcd_pnx4008_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)); |
| strlcpy(i2c_info.type, "isp1301_pnx", I2C_NAME_SIZE); |
| isp1301_i2c_client = i2c_new_probed_device(i2c_adap, &i2c_info, |
| normal_i2c); |
| 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. |