diff options
Diffstat (limited to 'Documentation/i2c')
36 files changed, 776 insertions, 716 deletions
diff --git a/Documentation/i2c/busses/i2c-ali1535 b/Documentation/i2c/busses/i2c-ali1535 index 0db3b4c74ad..5d46342e486 100644 --- a/Documentation/i2c/busses/i2c-ali1535 +++ b/Documentation/i2c/busses/i2c-ali1535 @@ -3,15 +3,15 @@ Kernel driver i2c-ali1535 Supported adapters: * Acer Labs, Inc. ALI 1535 (south bridge) Datasheet: Now under NDA - http://www.ali.com.tw/eng/support/datasheet_request.php + http://www.ali.com.tw/ Authors: - Frodo Looijaard <frodol@dds.nl>, + Frodo Looijaard <frodol@dds.nl>, Philip Edelbrock <phil@netroedge.com>, Mark D. Studebaker <mdsxyz123@yahoo.com>, Dan Eaton <dan.eaton@rocketlogix.com>, Stephen Rousset<stephen.rousset@rocketlogix.com> - + Description ----------- diff --git a/Documentation/i2c/busses/i2c-ali1563 b/Documentation/i2c/busses/i2c-ali1563 index 99ad4b9bcc3..41b1a077e4c 100644 --- a/Documentation/i2c/busses/i2c-ali1563 +++ b/Documentation/i2c/busses/i2c-ali1563 @@ -3,7 +3,7 @@ Kernel driver i2c-ali1563 Supported adapters: * Acer Labs, Inc. ALI 1563 (south bridge) Datasheet: Now under NDA - http://www.ali.com.tw/eng/support/datasheet_request.php + http://www.ali.com.tw/ Author: Patrick Mochel <mochel@digitalimplant.org> @@ -18,7 +18,7 @@ For an overview of these chips see http://www.acerlabs.com The M1563 southbridge is deceptively similar to the M1533, with a few notable exceptions. One of those happens to be the fact they upgraded the i2c core to be SMBus 2.0 compliant, and happens to be almost identical to -the i2c controller found in the Intel 801 south bridges. +the i2c controller found in the Intel 801 south bridges. Features -------- diff --git a/Documentation/i2c/busses/i2c-ali15x3 b/Documentation/i2c/busses/i2c-ali15x3 index ff28d381beb..42888d8ac12 100644 --- a/Documentation/i2c/busses/i2c-ali15x3 +++ b/Documentation/i2c/busses/i2c-ali15x3 @@ -3,11 +3,11 @@ Kernel driver i2c-ali15x3 Supported adapters: * Acer Labs, Inc. ALI 1533 and 1543C (south bridge) Datasheet: Now under NDA - http://www.ali.com.tw/eng/support/datasheet_request.php + http://www.ali.com.tw/ Authors: - Frodo Looijaard <frodol@dds.nl>, - Philip Edelbrock <phil@netroedge.com>, + Frodo Looijaard <frodol@dds.nl>, + Philip Edelbrock <phil@netroedge.com>, Mark D. Studebaker <mdsxyz123@yahoo.com> Module Parameters @@ -40,10 +40,10 @@ M1541 and M1543C South Bridges. The M1543C is a South bridge for desktop systems. The M1541 is a South bridge for portable systems. They are part of the following ALI chipsets: - - * "Aladdin Pro 2" includes the M1621 Slot 1 North bridge with AGP and + + * "Aladdin Pro 2" includes the M1621 Slot 1 North bridge with AGP and 100MHz CPU Front Side bus - * "Aladdin V" includes the M1541 Socket 7 North bridge with AGP and 100MHz + * "Aladdin V" includes the M1541 Socket 7 North bridge with AGP and 100MHz CPU Front Side bus Some Aladdin V motherboards: Asus P5A @@ -77,7 +77,7 @@ output of lspci will show something similar to the following: ** then run lspci. ** If you see the 1533 and 5229 devices but NOT the 7101 device, ** then you must enable ACPI, the PMU, SMB, or something similar -** in the BIOS. +** in the BIOS. ** The driver won't work if it can't find the M7101 device. The SMB controller is part of the M7101 device, which is an ACPI-compliant @@ -87,8 +87,8 @@ The whole M7101 device has to be enabled for the SMB to work. You can't just enable the SMB alone. The SMB and the ACPI have separate I/O spaces. We make sure that the SMB is enabled. We leave the ACPI alone. -Features --------- +Features +-------- This driver controls the SMB Host only. The SMB Slave controller on the M15X3 is not enabled. This driver does not use diff --git a/Documentation/i2c/busses/i2c-diolan-u2c b/Documentation/i2c/busses/i2c-diolan-u2c new file mode 100644 index 00000000000..0d6018c316c --- /dev/null +++ b/Documentation/i2c/busses/i2c-diolan-u2c @@ -0,0 +1,26 @@ +Kernel driver i2c-diolan-u2c + +Supported adapters: + * Diolan U2C-12 I2C-USB adapter + Documentation: + http://www.diolan.com/i2c/u2c12.html + +Author: Guenter Roeck <linux@roeck-us.net> + +Description +----------- + +This is the driver for the Diolan U2C-12 USB-I2C adapter. + +The Diolan U2C-12 I2C-USB Adapter provides a low cost solution to connect +a computer to I2C slave devices using a USB interface. It also supports +connectivity to SPI devices. + +This driver only supports the I2C interface of U2C-12. The driver does not use +interrupts. + + +Module parameters +----------------- + +* frequency: I2C bus frequency diff --git a/Documentation/i2c/busses/i2c-i801 b/Documentation/i2c/busses/i2c-i801 index 81c0c59a60e..adf5e33e831 100644 --- a/Documentation/i2c/busses/i2c-i801 +++ b/Documentation/i2c/busses/i2c-i801 @@ -15,18 +15,39 @@ Supported adapters: * Intel 82801I (ICH9) * Intel EP80579 (Tolapai) * Intel 82801JI (ICH10) - * Intel PCH + * Intel 5/3400 Series (PCH) + * Intel 6 Series (PCH) + * Intel Patsburg (PCH) + * Intel DH89xxCC (PCH) + * Intel Panther Point (PCH) + * Intel Lynx Point (PCH) + * Intel Lynx Point-LP (PCH) + * Intel Avoton (SOC) + * Intel Wellsburg (PCH) + * Intel Coleto Creek (PCH) + * Intel Wildcat Point-LP (PCH) + * Intel BayTrail (SOC) Datasheets: Publicly available at the Intel website +On Intel Patsburg and later chipsets, both the normal host SMBus controller +and the additional 'Integrated Device Function' controllers are supported. + Authors: Mark Studebaker <mdsxyz123@yahoo.com> - Jean Delvare <khali@linux-fr.org> + Jean Delvare <jdelvare@suse.de> Module Parameters ----------------- -None. +* disable_features (bit vector) +Disable selected features normally supported by the device. This makes it +possible to work around possible driver or hardware bugs if the feature in +question doesn't work as intended for whatever reason. Bit values: + 0x01 disable SMBus PEC + 0x02 disable the block buffer + 0x08 disable the I2C block read functionality + 0x10 don't use interrupts Description @@ -72,6 +93,12 @@ SMBus 2.0 Support The 82801DB (ICH4) and later chips support several SMBus 2.0 features. +Interrupt Support +----------------- + +PCI interrupt support is supported on the 82801EB (ICH5) and later chips. + + Hidden ICH SMBus ---------------- diff --git a/Documentation/i2c/busses/i2c-ismt b/Documentation/i2c/busses/i2c-ismt new file mode 100644 index 00000000000..737355822c0 --- /dev/null +++ b/Documentation/i2c/busses/i2c-ismt @@ -0,0 +1,36 @@ +Kernel driver i2c-ismt + +Supported adapters: + * Intel S12xx series SOCs + +Authors: + Bill Brown <bill.e.brown@intel.com> + + +Module Parameters +----------------- + +* bus_speed (unsigned int) +Allows changing of the bus speed. Normally, the bus speed is set by the BIOS +and never needs to be changed. However, some SMBus analyzers are too slow for +monitoring the bus during debug, thus the need for this module parameter. +Specify the bus speed in kHz. +Available bus frequency settings: + 0 no change + 80 kHz + 100 kHz + 400 kHz + 1000 kHz + + +Description +----------- + +The S12xx series of SOCs have a pair of integrated SMBus 2.0 controllers +targeted primarily at the microserver and storage markets. + +The S12xx series contain a pair of PCI functions. An output of lspci will show +something similar to the following: + + 00:13.0 System peripheral: Intel Corporation Centerton SMBus 2.0 Controller 0 + 00:13.1 System peripheral: Intel Corporation Centerton SMBus 2.0 Controller 1 diff --git a/Documentation/i2c/busses/i2c-nforce2 b/Documentation/i2c/busses/i2c-nforce2 index fae3495bcba..9698c396b83 100644 --- a/Documentation/i2c/busses/i2c-nforce2 +++ b/Documentation/i2c/busses/i2c-nforce2 @@ -7,10 +7,14 @@ Supported adapters: * nForce3 250Gb MCP 10de:00E4 * nForce4 MCP 10de:0052 * nForce4 MCP-04 10de:0034 - * nForce4 MCP51 10de:0264 - * nForce4 MCP55 10de:0368 - * nForce4 MCP61 10de:03EB - * nForce4 MCP65 10de:0446 + * nForce MCP51 10de:0264 + * nForce MCP55 10de:0368 + * nForce MCP61 10de:03EB + * nForce MCP65 10de:0446 + * nForce MCP67 10de:0542 + * nForce MCP73 10de:07D8 + * nForce MCP78S 10de:0752 + * nForce MCP79 10de:0AA2 Datasheet: not publicly available, but seems to be similar to the AMD-8111 SMBus 2.0 adapter. diff --git a/Documentation/i2c/busses/i2c-ocores b/Documentation/i2c/busses/i2c-ocores index cfcebb10d14..c269aaa2f26 100644 --- a/Documentation/i2c/busses/i2c-ocores +++ b/Documentation/i2c/busses/i2c-ocores @@ -20,6 +20,8 @@ platform_device with the base address and interrupt number. The dev.platform_data of the device should also point to a struct ocores_i2c_platform_data (see linux/i2c-ocores.h) describing the distance between registers and the input clock speed. +There is also a possibility to attach a list of i2c_board_info which +the i2c-ocores driver will add to the bus upon creation. E.G. something like: @@ -36,9 +38,24 @@ static struct resource ocores_resources[] = { }, }; +/* optional board info */ +struct i2c_board_info ocores_i2c_board_info[] = { + { + I2C_BOARD_INFO("tsc2003", 0x48), + .platform_data = &tsc2003_platform_data, + .irq = TSC_IRQ + }, + { + I2C_BOARD_INFO("adv7180", 0x42 >> 1), + .irq = ADV_IRQ + } +}; + static struct ocores_i2c_platform_data myi2c_data = { .regstep = 2, /* two bytes between registers */ .clock_khz = 50000, /* input clock of 50MHz */ + .devices = ocores_i2c_board_info, /* optional table of devices */ + .num_devices = ARRAY_SIZE(ocores_i2c_board_info), /* table size */ }; static struct platform_device myi2c = { diff --git a/Documentation/i2c/busses/i2c-parport b/Documentation/i2c/busses/i2c-parport index dceaba1ad93..0e2d17b460f 100644 --- a/Documentation/i2c/busses/i2c-parport +++ b/Documentation/i2c/busses/i2c-parport @@ -1,6 +1,6 @@ Kernel driver i2c-parport -Author: Jean Delvare <khali@linux-fr.org> +Author: Jean Delvare <jdelvare@suse.de> This is a unified driver for several i2c-over-parallel-port adapters, such as the ones made by Philips, Velleman or ELV. This driver is @@ -29,6 +29,9 @@ can be easily added when needed. Earlier kernels defaulted to type=0 (Philips). But now, if the type parameter is missing, the driver will simply fail to initialize. +SMBus alert support is available on adapters which have this line properly +connected to the parallel port's interrupt pin. + Building your own adapter ------------------------- diff --git a/Documentation/i2c/busses/i2c-parport-light b/Documentation/i2c/busses/i2c-parport-light index 28743647852..7071b8ba0af 100644 --- a/Documentation/i2c/busses/i2c-parport-light +++ b/Documentation/i2c/busses/i2c-parport-light @@ -1,11 +1,22 @@ Kernel driver i2c-parport-light -Author: Jean Delvare <khali@linux-fr.org> +Author: Jean Delvare <jdelvare@suse.de> This driver is a light version of i2c-parport. It doesn't depend on the parport driver, and uses direct I/O access instead. This might be -prefered on embedded systems where wasting memory for the clean but heavy +preferred on embedded systems where wasting memory for the clean but heavy parport handling is not an option. The drawback is a reduced portability and the impossibility to daisy-chain other parallel port devices. Please see i2c-parport for documentation. + +Module parameters: + +* type: type of adapter (see i2c-parport or modinfo) + +* base: base I/O address + Default is 0x378 which is fairly common for parallel ports, at least on PC. + +* irq: optional IRQ + This must be passed if you want SMBus alert support, assuming your adapter + actually supports this. diff --git a/Documentation/i2c/busses/i2c-pca-isa b/Documentation/i2c/busses/i2c-pca-isa index 6fc8f4c27c3..b044e526548 100644 --- a/Documentation/i2c/busses/i2c-pca-isa +++ b/Documentation/i2c/busses/i2c-pca-isa @@ -1,10 +1,10 @@ Kernel driver i2c-pca-isa Supported adapters: -This driver supports ISA boards using the Philips PCA 9564 -Parallel bus to I2C bus controller +This driver supports ISA boards using the Philips PCA 9564 +Parallel bus to I2C bus controller -Author: Ian Campbell <icampbell@arcom.com>, Arcom Control Systems +Author: Ian Campbell <icampbell@arcom.com>, Arcom Control Systems Module Parameters ----------------- @@ -12,12 +12,12 @@ Module Parameters * base int I/O base address * irq int - IRQ interrupt -* clock int + IRQ interrupt +* clock int Clock rate as described in table 1 of PCA9564 datasheet Description ----------- -This driver supports ISA boards using the Philips PCA 9564 -Parallel bus to I2C bus controller +This driver supports ISA boards using the Philips PCA 9564 +Parallel bus to I2C bus controller diff --git a/Documentation/i2c/busses/i2c-piix4 b/Documentation/i2c/busses/i2c-piix4 index ef1efa79b1d..aa959fd2245 100644 --- a/Documentation/i2c/busses/i2c-piix4 +++ b/Documentation/i2c/busses/i2c-piix4 @@ -4,10 +4,17 @@ Supported adapters: * Intel 82371AB PIIX4 and PIIX4E * Intel 82443MX (440MX) Datasheet: Publicly available at the Intel website - * ServerWorks OSB4, CSB5, CSB6 and HT-1000 southbridges + * ServerWorks OSB4, CSB5, CSB6, HT-1000 and HT-1100 southbridges Datasheet: Only available via NDA from ServerWorks * ATI IXP200, IXP300, IXP400, SB600, SB700 and SB800 southbridges Datasheet: Not publicly available + SB700 register reference available at: + http://support.amd.com/us/Embedded_TechDocs/43009_sb7xx_rrg_pub_1.00.pdf + * AMD SP5100 (SB700 derivative found on some server mainboards) + Datasheet: Publicly available at the AMD website + http://support.amd.com/us/Embedded_TechDocs/44413.pdf + * AMD Hudson-2, ML, CZ + Datasheet: Not publicly available * Standard Microsystems (SMSC) SLC90E66 (Victory66) southbridge Datasheet: Publicly available at the SMSC website http://www.smsc.com @@ -66,6 +73,11 @@ this driver on those mainboards. The ServerWorks Southbridges, the Intel 440MX, and the Victory66 are identical to the PIIX4 in I2C/SMBus support. +The AMD SB700, SB800, SP5100 and Hudson-2 chipsets implement two +PIIX4-compatible SMBus controllers. If your BIOS initializes the +secondary controller, it will be detected by this driver as +an "Auxiliary SMBus Host Controller". + If you own Force CPCI735 motherboard or other OSB4 based systems you may need to change the SMBus Interrupt Select register so the SMBus controller uses the SMI mode. @@ -95,4 +107,4 @@ of all affected systems, so the only safe solution was to prevent access to the SMBus on all IBM systems (detected using DMI data.) For additional information, read: -http://www.lm-sensors.org/browser/lm-sensors/trunk/README.thinkpad +http://www.lm-sensors.org/browser/lm-sensors/trunk/README diff --git a/Documentation/i2c/busses/i2c-sis5595 b/Documentation/i2c/busses/i2c-sis5595 index cc47db7d00a..ecd21fb49a8 100644 --- a/Documentation/i2c/busses/i2c-sis5595 +++ b/Documentation/i2c/busses/i2c-sis5595 @@ -1,41 +1,41 @@ Kernel driver i2c-sis5595 -Authors: +Authors: Frodo Looijaard <frodol@dds.nl>, Mark D. Studebaker <mdsxyz123@yahoo.com>, - Philip Edelbrock <phil@netroedge.com> + Philip Edelbrock <phil@netroedge.com> Supported adapters: * Silicon Integrated Systems Corp. SiS5595 Southbridge Datasheet: Publicly available at the Silicon Integrated Systems Corp. site. -Note: all have mfr. ID 0x1039. - - SUPPORTED PCI ID - 5595 0008 - - Note: these chips contain a 0008 device which is incompatible with the - 5595. We recognize these by the presence of the listed - "blacklist" PCI ID and refuse to load. - - NOT SUPPORTED PCI ID BLACKLIST PCI ID - 540 0008 0540 - 550 0008 0550 - 5513 0008 5511 - 5581 0008 5597 - 5582 0008 5597 - 5597 0008 5597 - 5598 0008 5597/5598 - 630 0008 0630 - 645 0008 0645 - 646 0008 0646 - 648 0008 0648 - 650 0008 0650 - 651 0008 0651 - 730 0008 0730 - 735 0008 0735 - 745 0008 0745 - 746 0008 0746 +Note: all have mfr. ID 0x1039. + + SUPPORTED PCI ID + 5595 0008 + + Note: these chips contain a 0008 device which is incompatible with the + 5595. We recognize these by the presence of the listed + "blacklist" PCI ID and refuse to load. + + NOT SUPPORTED PCI ID BLACKLIST PCI ID + 540 0008 0540 + 550 0008 0550 + 5513 0008 5511 + 5581 0008 5597 + 5582 0008 5597 + 5597 0008 5597 + 5598 0008 5597/5598 + 630 0008 0630 + 645 0008 0645 + 646 0008 0646 + 648 0008 0648 + 650 0008 0650 + 651 0008 0651 + 730 0008 0730 + 735 0008 0735 + 745 0008 0745 + 746 0008 0746 Module Parameters ----------------- diff --git a/Documentation/i2c/busses/i2c-sis630 b/Documentation/i2c/busses/i2c-sis630 index 9aca6889f74..ee794363107 100644 --- a/Documentation/i2c/busses/i2c-sis630 +++ b/Documentation/i2c/busses/i2c-sis630 @@ -2,11 +2,13 @@ Kernel driver i2c-sis630 Supported adapters: * Silicon Integrated Systems Corp (SiS) - 630 chipset (Datasheet: available at http://amalysh.bei.t-online.de/docs/SIS/) + 630 chipset (Datasheet: available at http://www.sfr-fresh.com/linux) 730 chipset + 964 chipset * Possible other SiS chipsets ? Author: Alexander Malysh <amalysh@web.de> + Amaury Decrême <amaury.decreme@gmail.com> - SiS964 support Module Parameters ----------------- @@ -14,10 +16,11 @@ Module Parameters * force = [1|0] Forcibly enable the SIS630. DANGEROUS! This can be interesting for chipsets not named above to check if it works for you chipset, but DANGEROUS! - -* high_clock = [1|0] Forcibly set Host Master Clock to 56KHz (default, - what your BIOS use). DANGEROUS! This should be a bit + +* high_clock = [1|0] Forcibly set Host Master Clock to 56KHz (default, + what your BIOS use). DANGEROUS! This should be a bit faster, but freeze some systems (i.e. my Laptop). + SIS630/730 chip only. Description @@ -36,6 +39,12 @@ or like this: 00:00.0 Host bridge: Silicon Integrated Systems [SiS] 730 Host (rev 02) 00:01.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513 +or like this: + +00:00.0 Host bridge: Silicon Integrated Systems [SiS] 760/M760 Host (rev 02) +00:02.0 ISA bridge: Silicon Integrated Systems [SiS] SiS964 [MuTIOL Media IO] + LPC Controller (rev 36) + in your 'lspci' output , then this driver is for your chipset. Thank You @@ -44,6 +53,6 @@ Philip Edelbrock <phil@netroedge.com> - testing SiS730 support Mark M. Hoffman <mhoffman@lightlink.com> - bug fixes - + To anyone else which I forgot here ;), thanks! diff --git a/Documentation/i2c/busses/i2c-sis96x b/Documentation/i2c/busses/i2c-sis96x index 70e6a0cc1e1..0b979f3252a 100644 --- a/Documentation/i2c/busses/i2c-sis96x +++ b/Documentation/i2c/busses/i2c-sis96x @@ -35,7 +35,7 @@ or perhaps this... (kernel versions later than 2.4.18 may fill in the "Unknown"s) -If you cant see it please look on quirk_sis_96x_smbus +If you can't see it please look on quirk_sis_96x_smbus (drivers/pci/quirks.c) (also if southbridge detection fails) I suspect that this driver could be made to work for the following SiS diff --git a/Documentation/i2c/busses/i2c-taos-evm b/Documentation/i2c/busses/i2c-taos-evm index 9146e33be6d..60299555dcf 100644 --- a/Documentation/i2c/busses/i2c-taos-evm +++ b/Documentation/i2c/busses/i2c-taos-evm @@ -1,6 +1,6 @@ Kernel driver i2c-taos-evm -Author: Jean Delvare <khali@linux-fr.org> +Author: Jean Delvare <jdelvare@suse.de> This is a driver for the evaluation modules for TAOS I2C/SMBus chips. The modules include an SMBus master with limited capabilities, which can @@ -13,7 +13,7 @@ Currently supported devices are: * TAOS TSL2550 EVM -For addtional information on TAOS products, please see +For additional information on TAOS products, please see http://www.taosinc.com/ diff --git a/Documentation/i2c/busses/i2c-viapro b/Documentation/i2c/busses/i2c-viapro index 22efedf60c8..ab64ce21c25 100644 --- a/Documentation/i2c/busses/i2c-viapro +++ b/Documentation/i2c/busses/i2c-viapro @@ -19,10 +19,16 @@ Supported adapters: * VIA Technologies, Inc. VX800/VX820 Datasheet: available on http://linux.via.com.tw + * VIA Technologies, Inc. VX855/VX875 + Datasheet: available on http://linux.via.com.tw + + * VIA Technologies, Inc. VX900 + Datasheet: available on http://linux.via.com.tw + Authors: Kyösti Mälkki <kmalkki@cc.hut.fi>, Mark D. Studebaker <mdsxyz123@yahoo.com>, - Jean Delvare <khali@linux-fr.org> + Jean Delvare <jdelvare@suse.de> Module Parameters ----------------- @@ -53,6 +59,8 @@ Your lspci -n listing must show one of these : device 1106:3287 (VT8251) device 1106:8324 (CX700) device 1106:8353 (VX800/VX820) + device 1106:8409 (VX855/VX875) + device 1106:8410 (VX900) If none of these show up, you should look in the BIOS for settings like enable ACPI / SMBus or even USB. diff --git a/Documentation/i2c/busses/i2c-voodoo3 b/Documentation/i2c/busses/i2c-voodoo3 deleted file mode 100644 index 62d90a454d3..00000000000 --- a/Documentation/i2c/busses/i2c-voodoo3 +++ /dev/null @@ -1,62 +0,0 @@ -Kernel driver i2c-voodoo3 - -Supported adapters: - * 3dfx Voodoo3 based cards - * Voodoo Banshee based cards - -Authors: - Frodo Looijaard <frodol@dds.nl>, - Philip Edelbrock <phil@netroedge.com>, - Ralph Metzler <rjkm@thp.uni-koeln.de>, - Mark D. Studebaker <mdsxyz123@yahoo.com> - -Main contact: Philip Edelbrock <phil@netroedge.com> - -The code is based upon Ralph's test code (he did the hard stuff ;') - -Description ------------ - -The 3dfx Voodoo3 chip contains two I2C interfaces (aka a I2C 'master' or -'host'). - -The first interface is used for DDC (Data Display Channel) which is a -serial channel through the VGA monitor connector to a DDC-compliant -monitor. This interface is defined by the Video Electronics Standards -Association (VESA). The standards are available for purchase at -http://www.vesa.org . - -The second interface is a general-purpose I2C bus. The intent by 3dfx was -to allow manufacturers to add extra chips to the video card such as a -TV-out chip such as the BT869 or possibly even I2C based temperature -sensors like the ADM1021 or LM75. - -Stability ---------- - -Seems to be stable on the test machine, but needs more testing on other -machines. Simultaneous accesses of the DDC and I2C busses may cause errors. - -Supported Devices ------------------ - -Specifically, this driver was written and tested on the '3dfx Voodoo3 AGP -3000' which has a tv-out feature (s-video or composite). According to the -docs and discussions, this code should work for any Voodoo3 based cards as -well as Voodoo Banshee based cards. The DDC interface has been tested on a -Voodoo Banshee card. - -Issues ------- - -Probably many, but it seems to work OK on my system. :') - - -External Device Connection --------------------------- - -The digital video input jumpers give availability to the I2C bus. -Specifically, pins 13 and 25 (bottom row middle, and bottom right-end) are -the I2C clock and I2C data lines, respectively. +5V and GND are probably -also easily available making the addition of extra I2C/SMBus devices easy -to implement. diff --git a/Documentation/i2c/busses/scx200_acb b/Documentation/i2c/busses/scx200_acb index 7c07883d4df..ce83c871fe9 100644 --- a/Documentation/i2c/busses/scx200_acb +++ b/Documentation/i2c/busses/scx200_acb @@ -28,5 +28,5 @@ If the scx200_acb driver is built into the kernel, add the following parameter to your boot command line: scx200_acb.base=0x810,0x820 If the scx200_acb driver is built as a module, add the following line to -the file /etc/modprobe.conf instead: +a configuration file in /etc/modprobe.d/ instead: options scx200_acb base=0x810,0x820 diff --git a/Documentation/i2c/chips/eeprom b/Documentation/i2c/chips/eeprom deleted file mode 100644 index f7e8104b576..00000000000 --- a/Documentation/i2c/chips/eeprom +++ /dev/null @@ -1,96 +0,0 @@ -Kernel driver eeprom -==================== - -Supported chips: - * Any EEPROM chip in the designated address range - Prefix: 'eeprom' - Addresses scanned: I2C 0x50 - 0x57 - Datasheets: Publicly available from: - Atmel (www.atmel.com), - Catalyst (www.catsemi.com), - Fairchild (www.fairchildsemi.com), - Microchip (www.microchip.com), - Philips (www.semiconductor.philips.com), - Rohm (www.rohm.com), - ST (www.st.com), - Xicor (www.xicor.com), - and others. - - Chip Size (bits) Address - 24C01 1K 0x50 (shadows at 0x51 - 0x57) - 24C01A 1K 0x50 - 0x57 (Typical device on DIMMs) - 24C02 2K 0x50 - 0x57 - 24C04 4K 0x50, 0x52, 0x54, 0x56 - (additional data at 0x51, 0x53, 0x55, 0x57) - 24C08 8K 0x50, 0x54 (additional data at 0x51, 0x52, - 0x53, 0x55, 0x56, 0x57) - 24C16 16K 0x50 (additional data at 0x51 - 0x57) - Sony 2K 0x57 - - Atmel 34C02B 2K 0x50 - 0x57, SW write protect at 0x30-37 - Catalyst 34FC02 2K 0x50 - 0x57, SW write protect at 0x30-37 - Catalyst 34RC02 2K 0x50 - 0x57, SW write protect at 0x30-37 - Fairchild 34W02 2K 0x50 - 0x57, SW write protect at 0x30-37 - Microchip 24AA52 2K 0x50 - 0x57, SW write protect at 0x30-37 - ST M34C02 2K 0x50 - 0x57, SW write protect at 0x30-37 - - -Authors: - Frodo Looijaard <frodol@dds.nl>, - Philip Edelbrock <phil@netroedge.com>, - Jean Delvare <khali@linux-fr.org>, - Greg Kroah-Hartman <greg@kroah.com>, - IBM Corp. - -Description ------------ - -This is a simple EEPROM module meant to enable reading the first 256 bytes -of an EEPROM (on a SDRAM DIMM for example). However, it will access serial -EEPROMs on any I2C adapter. The supported devices are generically called -24Cxx, and are listed above; however the numbering for these -industry-standard devices may vary by manufacturer. - -This module was a programming exercise to get used to the new project -organization laid out by Frodo, but it should be at least completely -effective for decoding the contents of EEPROMs on DIMMs. - -DIMMS will typically contain a 24C01A or 24C02, or the 34C02 variants. -The other devices will not be found on a DIMM because they respond to more -than one address. - -DDC Monitors may contain any device. Often a 24C01, which responds to all 8 -addresses, is found. - -Recent Sony Vaio laptops have an EEPROM at 0x57. We couldn't get the -specification, so it is guess work and far from being complete. - -The Microchip 24AA52/24LCS52, ST M34C02, and others support an additional -software write protect register at 0x30 - 0x37 (0x20 less than the memory -location). The chip responds to "write quick" detection at this address but -does not respond to byte reads. If this register is present, the lower 128 -bytes of the memory array are not write protected. Any byte data write to -this address will write protect the memory array permanently, and the -device will no longer respond at the 0x30-37 address. The eeprom driver -does not support this register. - -Lacking functionality: - -* Full support for larger devices (24C04, 24C08, 24C16). These are not -typically found on a PC. These devices will appear as separate devices at -multiple addresses. - -* Support for really large devices (24C32, 24C64, 24C128, 24C256, 24C512). -These devices require two-byte address fields and are not supported. - -* Enable Writing. Again, no technical reason why not, but making it easy -to change the contents of the EEPROMs (on DIMMs anyway) also makes it easy -to disable the DIMMs (potentially preventing the computer from booting) -until the values are restored somehow. - -Use: - -After inserting the module (and any other required SMBus/i2c modules), you -should have some EEPROM directories in /sys/bus/i2c/devices/* of names such -as "0-0050". Inside each of these is a series of files, the eeprom file -contains the binary data from EEPROM. diff --git a/Documentation/i2c/chips/max6875 b/Documentation/i2c/chips/max6875 deleted file mode 100644 index 10ca43cd1a7..00000000000 --- a/Documentation/i2c/chips/max6875 +++ /dev/null @@ -1,108 +0,0 @@ -Kernel driver max6875 -===================== - -Supported chips: - * Maxim MAX6874, MAX6875 - Prefix: 'max6875' - Addresses scanned: None (see below) - Datasheet: - http://pdfserv.maxim-ic.com/en/ds/MAX6874-MAX6875.pdf - -Author: Ben Gardner <bgardner@wabtec.com> - - -Description ------------ - -The Maxim MAX6875 is an EEPROM-programmable power-supply sequencer/supervisor. -It provides timed outputs that can be used as a watchdog, if properly wired. -It also provides 512 bytes of user EEPROM. - -At reset, the MAX6875 reads the configuration EEPROM into its configuration -registers. The chip then begins to operate according to the values in the -registers. - -The Maxim MAX6874 is a similar, mostly compatible device, with more intputs -and outputs: - vin gpi vout -MAX6874 6 4 8 -MAX6875 4 3 5 - -See the datasheet for more information. - - -Sysfs entries -------------- - -eeprom - 512 bytes of user-defined EEPROM space. - - -General Remarks ---------------- - -Valid addresses for the MAX6875 are 0x50 and 0x52. -Valid addresses for the MAX6874 are 0x50, 0x52, 0x54 and 0x56. -The driver does not probe any address, so you must force the address. - -Example: -$ modprobe max6875 force=0,0x50 - -The MAX6874/MAX6875 ignores address bit 0, so this driver attaches to multiple -addresses. For example, for address 0x50, it also reserves 0x51. -The even-address instance is called 'max6875', the odd one is 'dummy'. - - -Programming the chip using i2c-dev ----------------------------------- - -Use the i2c-dev interface to access and program the chips. -Reads and writes are performed differently depending on the address range. - -The configuration registers are at addresses 0x00 - 0x45. -Use i2c_smbus_write_byte_data() to write a register and -i2c_smbus_read_byte_data() to read a register. -The command is the register number. - -Examples: -To write a 1 to register 0x45: - i2c_smbus_write_byte_data(fd, 0x45, 1); - -To read register 0x45: - value = i2c_smbus_read_byte_data(fd, 0x45); - - -The configuration EEPROM is at addresses 0x8000 - 0x8045. -The user EEPROM is at addresses 0x8100 - 0x82ff. - -Use i2c_smbus_write_word_data() to write a byte to EEPROM. - -The command is the upper byte of the address: 0x80, 0x81, or 0x82. -The data word is the lower part of the address or'd with data << 8. - cmd = address >> 8; - val = (address & 0xff) | (data << 8); - -Example: -To write 0x5a to address 0x8003: - i2c_smbus_write_word_data(fd, 0x80, 0x5a03); - - -Reading data from the EEPROM is a little more complicated. -Use i2c_smbus_write_byte_data() to set the read address and then -i2c_smbus_read_byte() or i2c_smbus_read_i2c_block_data() to read the data. - -Example: -To read data starting at offset 0x8100, first set the address: - i2c_smbus_write_byte_data(fd, 0x81, 0x00); - -And then read the data - value = i2c_smbus_read_byte(fd); - - or - - count = i2c_smbus_read_i2c_block_data(fd, 0x84, 16, buffer); - -The block read should read 16 bytes. -0x84 is the block read command. - -See the datasheet for more details. - diff --git a/Documentation/i2c/chips/pca9539 b/Documentation/i2c/chips/pca9539 deleted file mode 100644 index 6aff890088b..00000000000 --- a/Documentation/i2c/chips/pca9539 +++ /dev/null @@ -1,58 +0,0 @@ -Kernel driver pca9539 -===================== - -NOTE: this driver is deprecated and will be dropped soon, use -drivers/gpio/pca9539.c instead. - -Supported chips: - * Philips PCA9539 - Prefix: 'pca9539' - Addresses scanned: none - Datasheet: - http://www.semiconductors.philips.com/acrobat/datasheets/PCA9539_2.pdf - -Author: Ben Gardner <bgardner@wabtec.com> - - -Description ------------ - -The Philips PCA9539 is a 16 bit low power I/O device. -All 16 lines can be individually configured as an input or output. -The input sense can also be inverted. -The 16 lines are split between two bytes. - - -Detection ---------- - -The PCA9539 is difficult to detect and not commonly found in PC machines, -so you have to pass the I2C bus and address of the installed PCA9539 -devices explicitly to the driver at load time via the force=... parameter. - - -Sysfs entries -------------- - -Each is a byte that maps to the 8 I/O bits. -A '0' suffix is for bits 0-7, while '1' is for bits 8-15. - -input[01] - read the current value -output[01] - sets the output value -direction[01] - direction of each bit: 1=input, 0=output -invert[01] - toggle the input bit sense - -input reads the actual state of the line and is always available. -The direction defaults to input for all channels. - - -General Remarks ---------------- - -Note that each output, direction, and invert entry controls 8 lines. -You should use the read, modify, write sequence. -For example. to set output bit 0 of 1. - val=$(cat output0) - val=$(( $val | 1 )) - echo $val > output0 - diff --git a/Documentation/i2c/chips/pcf8574 b/Documentation/i2c/chips/pcf8574 deleted file mode 100644 index 235815c075f..00000000000 --- a/Documentation/i2c/chips/pcf8574 +++ /dev/null @@ -1,65 +0,0 @@ -Kernel driver pcf8574 -===================== - -Supported chips: - * Philips PCF8574 - Prefix: 'pcf8574' - Addresses scanned: none - Datasheet: Publicly available at the Philips Semiconductors website - http://www.semiconductors.philips.com/pip/PCF8574P.html - - * Philips PCF8574A - Prefix: 'pcf8574a' - Addresses scanned: none - Datasheet: Publicly available at the Philips Semiconductors website - http://www.semiconductors.philips.com/pip/PCF8574P.html - -Authors: - Frodo Looijaard <frodol@dds.nl>, - Philip Edelbrock <phil@netroedge.com>, - Dan Eaton <dan.eaton@rocketlogix.com>, - Aurelien Jarno <aurelien@aurel32.net>, - Jean Delvare <khali@linux-fr.org>, - - -Description ------------ -The PCF8574(A) is an 8-bit I/O expander for the I2C bus produced by Philips -Semiconductors. It is designed to provide a byte I2C interface to up to 16 -separate devices (8 x PCF8574 and 8 x PCF8574A). - -This device consists of a quasi-bidirectional port. Each of the eight I/Os -can be independently used as an input or output. To setup an I/O as an -input, you have to write a 1 to the corresponding output. - -For more informations see the datasheet. - - -Accessing PCF8574(A) via /sys interface -------------------------------------- - -The PCF8574(A) is plainly impossible to detect ! Stupid chip. -So, you have to pass the I2C bus and address of the installed PCF857A -and PCF8574A devices explicitly to the driver at load time via the -force=... parameter. - -On detection (i.e. insmod, modprobe et al.), directories are being -created for each detected PCF8574(A): - -/sys/bus/i2c/devices/<0>-<1>/ -where <0> is the bus the chip was detected on (e. g. i2c-0) -and <1> the chip address ([20..27] or [38..3f]): - -(example: /sys/bus/i2c/devices/1-0020/) - -Inside these directories, there are two files each: -read and write (and one file with chip name). - -The read file is read-only. Reading gives you the current I/O input -if the corresponding output is set as 1, otherwise the current output -value, that is to say 0. - -The write file is read/write. Writing a value outputs it on the I/O -port. Reading returns the last written value. As it is not possible -to read this value from the chip, you need to write at least once to -this file before you can read back from it. diff --git a/Documentation/i2c/chips/pcf8575 b/Documentation/i2c/chips/pcf8575 deleted file mode 100644 index 40b268eb276..00000000000 --- a/Documentation/i2c/chips/pcf8575 +++ /dev/null @@ -1,69 +0,0 @@ -About the PCF8575 chip and the pcf8575 kernel driver -==================================================== - -The PCF8575 chip is produced by the following manufacturers: - - * Philips NXP - http://www.nxp.com/#/pip/cb=[type=product,path=50807/41735/41850,final=PCF8575_3]|pip=[pip=PCF8575_3][0] - - * Texas Instruments - http://focus.ti.com/docs/prod/folders/print/pcf8575.html - - -Some vendors sell small PCB's with the PCF8575 mounted on it. You can connect -such a board to a Linux host via e.g. an USB to I2C interface. Examples of -PCB boards with a PCF8575: - - * SFE Breakout Board for PCF8575 I2C Expander by RobotShop - http://www.robotshop.ca/home/products/robot-parts/electronics/adapters-converters/sfe-pcf8575-i2c-expander-board.html - - * Breakout Board for PCF8575 I2C Expander by Spark Fun Electronics - http://www.sparkfun.com/commerce/product_info.php?products_id=8130 - - -Description ------------ -The PCF8575 chip is a 16-bit I/O expander for the I2C bus. Up to eight of -these chips can be connected to the same I2C bus. You can find this -chip on some custom designed hardware, but you won't find it on PC -motherboards. - -The PCF8575 chip consists of a 16-bit quasi-bidirectional port and an I2C-bus -interface. Each of the sixteen I/O's can be independently used as an input or -an output. To set up an I/O pin as an input, you have to write a 1 to the -corresponding output. - -For more information please see the datasheet. - - -Detection ---------- - -There is no method known to detect whether a chip on a given I2C address is -a PCF8575 or whether it is any other I2C device, so you have to pass the I2C -bus and address of the installed PCF8575 devices explicitly to the driver at -load time via the force=... parameter. - -/sys interface --------------- - -For each address on which a PCF8575 chip was found or forced the following -files will be created under /sys: -* /sys/bus/i2c/devices/<bus>-<address>/read -* /sys/bus/i2c/devices/<bus>-<address>/write -where bus is the I2C bus number (0, 1, ...) and address is the four-digit -hexadecimal representation of the 7-bit I2C address of the PCF8575 -(0020 .. 0027). - -The read file is read-only. Reading it will trigger an I2C read and will hence -report the current input state for the pins configured as inputs, and the -current output value for the pins configured as outputs. - -The write file is read-write. Writing a value to it will configure all pins -as output for which the corresponding bit is zero. Reading the write file will -return the value last written, or -EAGAIN if no value has yet been written to -the write file. - -On module initialization the configuration of the chip is not changed -- the -chip is left in the state it was already configured in through either power-up -or through previous I2C write actions. diff --git a/Documentation/i2c/chips/pcf8591 b/Documentation/i2c/chips/pcf8591 deleted file mode 100644 index 5628fcf4207..00000000000 --- a/Documentation/i2c/chips/pcf8591 +++ /dev/null @@ -1,90 +0,0 @@ -Kernel driver pcf8591 -===================== - -Supported chips: - * Philips PCF8591 - Prefix: 'pcf8591' - Addresses scanned: I2C 0x48 - 0x4f - Datasheet: Publicly available at the Philips Semiconductor website - http://www.semiconductors.philips.com/pip/PCF8591P.html - -Authors: - Aurelien Jarno <aurelien@aurel32.net> - valuable contributions by Jan M. Sendler <sendler@sendler.de>, - Jean Delvare <khali@linux-fr.org> - - -Description ------------ -The PCF8591 is an 8-bit A/D and D/A converter (4 analog inputs and one -analog output) for the I2C bus produced by Philips Semiconductors. It -is designed to provide a byte I2C interface to up to 4 separate devices. - -The PCF8591 has 4 analog inputs programmable as single-ended or -differential inputs : -- mode 0 : four single ended inputs - Pins AIN0 to AIN3 are single ended inputs for channels 0 to 3 - -- mode 1 : three differential inputs - Pins AIN3 is the common negative differential input - Pins AIN0 to AIN2 are positive differential inputs for channels 0 to 2 - -- mode 2 : single ended and differential mixed - Pins AIN0 and AIN1 are single ended inputs for channels 0 and 1 - Pins AIN2 is the positive differential input for channel 3 - Pins AIN3 is the negative differential input for channel 3 - -- mode 3 : two differential inputs - Pins AIN0 is the positive differential input for channel 0 - Pins AIN1 is the negative differential input for channel 0 - Pins AIN2 is the positive differential input for channel 1 - Pins AIN3 is the negative differential input for channel 1 - -See the datasheet for details. - -Module parameters ------------------ - -* input_mode int - - Analog input mode: - 0 = four single ended inputs - 1 = three differential inputs - 2 = single ended and differential mixed - 3 = two differential inputs - - -Accessing PCF8591 via /sys interface -------------------------------------- - -! Be careful ! -The PCF8591 is plainly impossible to detect ! Stupid chip. -So every chip with address in the interval [48..4f] is -detected as PCF8591. If you have other chips in this address -range, the workaround is to load this module after the one -for your others chips. - -On detection (i.e. insmod, modprobe et al.), directories are being -created for each detected PCF8591: - -/sys/bus/devices/<0>-<1>/ -where <0> is the bus the chip was detected on (e. g. i2c-0) -and <1> the chip address ([48..4f]) - -Inside these directories, there are such files: -in0, in1, in2, in3, out0_enable, out0_output, name - -Name contains chip name. - -The in0, in1, in2 and in3 files are RO. Reading gives the value of the -corresponding channel. Depending on the current analog inputs configuration, -files in2 and/or in3 do not exist. Values range are from 0 to 255 for single -ended inputs and -128 to +127 for differential inputs (8-bit ADC). - -The out0_enable file is RW. Reading gives "1" for analog output enabled and -"0" for analog output disabled. Writing accepts "0" and "1" accordingly. - -The out0_output file is RW. Writing a number between 0 and 255 (8-bit DAC), send -the value to the digital-to-analog converter. Note that a voltage will -only appears on AOUT pin if aout0_enable equals 1. Reading returns the last -value written. diff --git a/Documentation/i2c/fault-codes b/Documentation/i2c/fault-codes index 045765c0b9b..47c25abb7d5 100644 --- a/Documentation/i2c/fault-codes +++ b/Documentation/i2c/fault-codes @@ -64,9 +64,6 @@ EINVAL detected before any I/O operation was started. Use a more specific fault code when you can. - One example would be a driver trying an SMBus Block Write - with block size outside the range of 1-32 bytes. - EIO This rather vague error means something went wrong when performing an I/O operation. Use a more specific fault diff --git a/Documentation/i2c/functionality b/Documentation/i2c/functionality index 42c17c1fb3c..4556a3eb87c 100644 --- a/Documentation/i2c/functionality +++ b/Documentation/i2c/functionality @@ -18,9 +18,9 @@ For the most up-to-date list of functionality constants, please check adapters typically can not do these) I2C_FUNC_10BIT_ADDR Handles the 10-bit address extensions I2C_FUNC_PROTOCOL_MANGLING Knows about the I2C_M_IGNORE_NAK, - I2C_M_REV_DIR_ADDR, I2C_M_NOSTART and - I2C_M_NO_RD_ACK flags (which modify the - I2C protocol!) + I2C_M_REV_DIR_ADDR and I2C_M_NO_RD_ACK + flags (which modify the I2C protocol!) + I2C_FUNC_NOSTART Can skip repeated start sequence I2C_FUNC_SMBUS_QUICK Handles the SMBus write_quick command I2C_FUNC_SMBUS_READ_BYTE Handles the SMBus read_byte command I2C_FUNC_SMBUS_WRITE_BYTE Handles the SMBus write_byte command @@ -46,10 +46,13 @@ A few combinations of the above flags are also defined for your convenience: and write_block_data commands I2C_FUNC_SMBUS_I2C_BLOCK Handles the SMBus read_i2c_block_data and write_i2c_block_data commands - I2C_FUNC_SMBUS_EMUL Handles all SMBus commands than can be + I2C_FUNC_SMBUS_EMUL Handles all SMBus commands that can be emulated by a real I2C adapter (using the transparent emulation layer) +In kernel versions prior to 3.5 I2C_FUNC_NOSTART was implemented as +part of I2C_FUNC_PROTOCOL_MANGLING. + ADAPTER IMPLEMENTATION ---------------------- diff --git a/Documentation/i2c/i2c-protocol b/Documentation/i2c/i2c-protocol index 10518dd5881..ff6d6cee6c7 100644 --- a/Documentation/i2c/i2c-protocol +++ b/Documentation/i2c/i2c-protocol @@ -6,8 +6,8 @@ Key to symbols S (1 bit) : Start bit P (1 bit) : Stop bit Rd/Wr (1 bit) : Read/Write bit. Rd equals 1, Wr equals 0. -A, NA (1 bit) : Accept and reverse accept bit. -Addr (7 bits): I2C 7 bit address. Note that this can be expanded as usual to +A, NA (1 bit) : Accept and reverse accept bit. +Addr (7 bits): I2C 7 bit address. Note that this can be expanded as usual to get a 10 bit I2C address. Comm (8 bits): Command byte, a data byte which often selects a register on the device. @@ -49,9 +49,20 @@ a byte read, followed by a byte write: Modified transactions ===================== -We have found some I2C devices that needs the following modifications: +The following modifications to the I2C protocol can also be generated by +setting these flags for i2c messages. With the exception of I2C_M_NOSTART, they +are usually only needed to work around device issues: - Flag I2C_M_NOSTART: +I2C_M_IGNORE_NAK: + Normally message is interrupted immediately if there is [NA] from the + client. Setting this flag treats any [NA] as [A], and all of + message is sent. + These messages may still fail to SCL lo->hi timeout. + +I2C_M_NO_RD_ACK: + In a read message, master A/NA bit is skipped. + +I2C_M_NOSTART: In a combined transaction, no 'S Addr Wr/Rd [A]' is generated at some point. For example, setting I2C_M_NOSTART on the second partial message generates something like: @@ -60,17 +71,18 @@ We have found some I2C devices that needs the following modifications: we do not generate Addr, but we do generate the startbit S. This will probably confuse all other clients on your bus, so don't try this. - Flags I2C_M_REV_DIR_ADDR + This is often used to gather transmits from multiple data buffers in + system memory into something that appears as a single transfer to the + I2C device but may also be used between direction changes by some + rare devices. + +I2C_M_REV_DIR_ADDR: This toggles the Rd/Wr flag. That is, if you want to do a write, but need to emit an Rd instead of a Wr, or vice versa, you set this flag. For example: S Addr Rd [A] Data [A] Data [A] ... [A] Data [A] P - Flags I2C_M_IGNORE_NAK - Normally message is interrupted immediately if there is [NA] from the - client. Setting this flag treats any [NA] as [A], and all of - message is sent. - These messages may still fail to SCL lo->hi timeout. - - Flags I2C_M_NO_RD_ACK - In a read message, master A/NA bit is skipped. +I2C_M_STOP: + Force a stop condition (P) after the message. Some I2C related protocols + like SCCB require that. Normally, you really don't want to get interrupted + between the messages of one transfer. diff --git a/Documentation/i2c/i2c-stub b/Documentation/i2c/i2c-stub index 0d8be1c20c1..fa4b669c166 100644 --- a/Documentation/i2c/i2c-stub +++ b/Documentation/i2c/i2c-stub @@ -2,9 +2,9 @@ MODULE: i2c-stub DESCRIPTION: -This module is a very simple fake I2C/SMBus driver. It implements four -types of SMBus commands: write quick, (r/w) byte, (r/w) byte data, and -(r/w) word data. +This module is a very simple fake I2C/SMBus driver. It implements five +types of SMBus commands: write quick, (r/w) byte, (r/w) byte data, (r/w) +word data, and (r/w) I2C block data. You need to provide chip addresses as a module parameter when loading this driver, which will then only react to SMBus commands to these addresses. @@ -21,8 +21,8 @@ EEPROMs, among others. The typical use-case is like this: 1. load this module - 2. use i2cset (from lm_sensors project) to pre-load some data - 3. load the target sensors chip driver module + 2. use i2cset (from the i2c-tools project) to pre-load some data + 3. load the target chip driver module 4. observe its behavior in the kernel log There's a script named i2c-stub-from-dump in the i2c-tools package which @@ -33,6 +33,12 @@ PARAMETERS: int chip_addr[10]: The SMBus addresses to emulate chips at. +unsigned long functionality: + Functionality override, to disable some commands. See I2C_FUNC_* + constants in <linux/i2c.h> for the suitable values. For example, + value 0x1f0000 would only enable the quick, byte and byte data + commands. + CAVEATS: If your target driver polls some byte or word waiting for it to change, the diff --git a/Documentation/i2c/instantiating-devices b/Documentation/i2c/instantiating-devices new file mode 100644 index 00000000000..0d85ac1935b --- /dev/null +++ b/Documentation/i2c/instantiating-devices @@ -0,0 +1,248 @@ +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/acpi/enumeration.txt. + + +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)); + strlcpy(i2c_info.type, "isp1301_nxp", I2C_NAME_SIZE); + 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. diff --git a/Documentation/i2c/muxes/i2c-mux-gpio b/Documentation/i2c/muxes/i2c-mux-gpio new file mode 100644 index 00000000000..d4d91a53fc3 --- /dev/null +++ b/Documentation/i2c/muxes/i2c-mux-gpio @@ -0,0 +1,83 @@ +Kernel driver i2c-gpio-mux + +Author: Peter Korsgaard <peter.korsgaard@barco.com> + +Description +----------- + +i2c-gpio-mux is an i2c mux driver providing access to I2C bus segments +from a master I2C bus and a hardware MUX controlled through GPIO pins. + +E.G.: + + ---------- ---------- Bus segment 1 - - - - - + | | SCL/SDA | |-------------- | | + | |------------| | + | | | | Bus segment 2 | | + | Linux | GPIO 1..N | MUX |--------------- Devices + | |------------| | | | + | | | | Bus segment M + | | | |---------------| | + ---------- ---------- - - - - - + +SCL/SDA of the master I2C bus is multiplexed to bus segment 1..M +according to the settings of the GPIO pins 1..N. + +Usage +----- + +i2c-gpio-mux uses the platform bus, so you need to provide a struct +platform_device with the platform_data pointing to a struct +gpio_i2cmux_platform_data with the I2C adapter number of the master +bus, the number of bus segments to create and the GPIO pins used +to control it. See include/linux/i2c-gpio-mux.h for details. + +E.G. something like this for a MUX providing 4 bus segments +controlled through 3 GPIO pins: + +#include <linux/i2c-gpio-mux.h> +#include <linux/platform_device.h> + +static const unsigned myboard_gpiomux_gpios[] = { + AT91_PIN_PC26, AT91_PIN_PC25, AT91_PIN_PC24 +}; + +static const unsigned myboard_gpiomux_values[] = { + 0, 1, 2, 3 +}; + +static struct gpio_i2cmux_platform_data myboard_i2cmux_data = { + .parent = 1, + .base_nr = 2, /* optional */ + .values = myboard_gpiomux_values, + .n_values = ARRAY_SIZE(myboard_gpiomux_values), + .gpios = myboard_gpiomux_gpios, + .n_gpios = ARRAY_SIZE(myboard_gpiomux_gpios), + .idle = 4, /* optional */ +}; + +static struct platform_device myboard_i2cmux = { + .name = "i2c-gpio-mux", + .id = 0, + .dev = { + .platform_data = &myboard_i2cmux_data, + }, +}; + +If you don't know the absolute GPIO pin numbers at registration time, +you can instead provide a chip name (.chip_name) and relative GPIO pin +numbers, and the i2c-gpio-mux driver will do the work for you, +including deferred probing if the GPIO chip isn't immediately +available. + +Device Registration +------------------- + +When registering your i2c-gpio-mux device, you should pass the number +of any GPIO pin it uses as the device ID. This guarantees that every +instance has a different ID. + +Alternatively, if you don't need a stable device name, you can simply +pass PLATFORM_DEVID_AUTO as the device ID, and the platform core will +assign a dynamic ID to your device. If you do not know the absolute +GPIO pin numbers at registration time, this is even the only option. diff --git a/Documentation/i2c/old-module-parameters b/Documentation/i2c/old-module-parameters new file mode 100644 index 00000000000..8e2b629d533 --- /dev/null +++ b/Documentation/i2c/old-module-parameters @@ -0,0 +1,44 @@ +I2C device driver binding control from user-space +================================================= + +Up to kernel 2.6.32, many i2c drivers used helper macros provided by +<linux/i2c.h> which created standard module parameters to let the user +control how the driver would probe i2c buses and attach to devices. These +parameters were known as "probe" (to let the driver probe for an extra +address), "force" (to forcibly attach the driver to a given device) and +"ignore" (to prevent a driver from probing a given address). + +With the conversion of the i2c subsystem to the standard device driver +binding model, it became clear that these per-module parameters were no +longer needed, and that a centralized implementation was possible. The new, +sysfs-based interface is described in the documentation file +"instantiating-devices", section "Method 4: Instantiate from user-space". + +Below is a mapping from the old module parameters to the new interface. + +Attaching a driver to an I2C device +----------------------------------- + +Old method (module parameters): +# modprobe <driver> probe=1,0x2d +# modprobe <driver> force=1,0x2d +# modprobe <driver> force_<device>=1,0x2d + +New method (sysfs interface): +# echo <device> 0x2d > /sys/bus/i2c/devices/i2c-1/new_device + +Preventing a driver from attaching to an I2C device +--------------------------------------------------- + +Old method (module parameters): +# modprobe <driver> ignore=1,0x2f + +New method (sysfs interface): +# echo dummy 0x2f > /sys/bus/i2c/devices/i2c-1/new_device +# modprobe <driver> + +Of course, it is important to instantiate the "dummy" device before loading +the driver. The dummy device will be handled by i2c-core itself, preventing +other drivers from binding to it later on. If there is a real device at the +problematic address, and you want another driver to bind to it, then simply +pass the name of the device in question instead of "dummy". diff --git a/Documentation/i2c/smbus-protocol b/Documentation/i2c/smbus-protocol index 9df47441f0e..6012b12b351 100644 --- a/Documentation/i2c/smbus-protocol +++ b/Documentation/i2c/smbus-protocol @@ -23,6 +23,12 @@ don't match these function names. For some of the operations which pass a single data byte, the functions using SMBus protocol operation names execute a different protocol operation entirely. +Each transaction type corresponds to a functionality flag. Before calling a +transaction function, a device driver should always check (just once) for +the corresponding functionality flag to ensure that the underlying I2C +adapter supports the transaction in question. See +<file:Documentation/i2c/functionality> for the details. + Key to symbols ============== @@ -49,6 +55,8 @@ This sends a single bit to the device, at the place of the Rd/Wr bit. A Addr Rd/Wr [A] P +Functionality flag: I2C_FUNC_SMBUS_QUICK + SMBus Receive Byte: i2c_smbus_read_byte() ========================================== @@ -60,6 +68,8 @@ the previous SMBus command. S Addr Rd [A] [Data] NA P +Functionality flag: I2C_FUNC_SMBUS_READ_BYTE + SMBus Send Byte: i2c_smbus_write_byte() ======================================== @@ -69,6 +79,8 @@ to a device. See Receive Byte for more information. S Addr Wr [A] Data [A] P +Functionality flag: I2C_FUNC_SMBUS_WRITE_BYTE + SMBus Read Byte: i2c_smbus_read_byte_data() ============================================ @@ -78,6 +90,8 @@ The register is specified through the Comm byte. S Addr Wr [A] Comm [A] S Addr Rd [A] [Data] NA P +Functionality flag: I2C_FUNC_SMBUS_READ_BYTE_DATA + SMBus Read Word: i2c_smbus_read_word_data() ============================================ @@ -88,6 +102,12 @@ byte. But this time, the data is a complete word (16 bits). S Addr Wr [A] Comm [A] S Addr Rd [A] [DataLow] A [DataHigh] NA P +Functionality flag: I2C_FUNC_SMBUS_READ_WORD_DATA + +Note the convenience function i2c_smbus_read_word_swapped is +available for reads where the two data bytes are the other way +around (not SMBus compliant, but very popular.) + SMBus Write Byte: i2c_smbus_write_byte_data() ============================================== @@ -98,6 +118,8 @@ the Read Byte operation. S Addr Wr [A] Comm [A] Data [A] P +Functionality flag: I2C_FUNC_SMBUS_WRITE_BYTE_DATA + SMBus Write Word: i2c_smbus_write_word_data() ============================================== @@ -108,9 +130,15 @@ specified through the Comm byte. S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A] P +Functionality flag: I2C_FUNC_SMBUS_WRITE_WORD_DATA + +Note the convenience function i2c_smbus_write_word_swapped is +available for writes where the two data bytes are the other way +around (not SMBus compliant, but very popular.) + -SMBus Process Call: i2c_smbus_process_call() -============================================= +SMBus Process Call: +=================== This command selects a device register (through the Comm byte), sends 16 bits of data to it, and reads 16 bits of data in return. @@ -118,6 +146,8 @@ This command selects a device register (through the Comm byte), sends S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A] S Addr Rd [A] [DataLow] A [DataHigh] NA P +Functionality flag: I2C_FUNC_SMBUS_PROC_CALL + SMBus Block Read: i2c_smbus_read_block_data() ============================================== @@ -129,6 +159,8 @@ of data is specified by the device in the Count byte. S Addr Wr [A] Comm [A] S Addr Rd [A] [Count] A [Data] A [Data] A ... A [Data] NA P +Functionality flag: I2C_FUNC_SMBUS_READ_BLOCK_DATA + SMBus Block Write: i2c_smbus_write_block_data() ================================================ @@ -139,6 +171,8 @@ Comm byte. The amount of data is specified in the Count byte. S Addr Wr [A] Comm [A] Count [A] Data [A] Data [A] ... [A] Data [A] P +Functionality flag: I2C_FUNC_SMBUS_WRITE_BLOCK_DATA + SMBus Block Write - Block Read Process Call =========================================== @@ -152,6 +186,8 @@ This command selects a device register (through the Comm byte), sends S Addr Wr [A] Comm [A] Count [A] Data [A] ... S Addr Rd [A] [Count] A [Data] ... A P +Functionality flag: I2C_FUNC_SMBUS_BLOCK_PROC_CALL + SMBus Host Notify ================= @@ -185,6 +221,22 @@ the protocol. All ARP communications use slave address 0x61 and require PEC checksums. +SMBus Alert +=========== + +SMBus Alert was introduced in Revision 1.0 of the specification. + +The SMBus alert protocol allows several SMBus slave devices to share a +single interrupt pin on the SMBus master, while still allowing the master +to know which slave triggered the interrupt. + +This is implemented the following way in the Linux kernel: +* I2C bus drivers which support SMBus alert should call + i2c_setup_smbus_alert() to setup SMBus alert support. +* I2C drivers for devices which can trigger SMBus alerts should implement + the optional alert() callback. + + I2C Block Transactions ====================== @@ -205,15 +257,7 @@ designated register that is specified through the Comm byte. S Addr Wr [A] Comm [A] S Addr Rd [A] [Data] A [Data] A ... A [Data] NA P - -I2C Block Read (2 Comm bytes) -============================= - -This command reads a block of bytes from a device, from a -designated register that is specified through the two Comm bytes. - -S Addr Wr [A] Comm1 [A] Comm2 [A] - S Addr Rd [A] [Data] A [Data] A ... A [Data] NA P +Functionality flag: I2C_FUNC_SMBUS_READ_I2C_BLOCK I2C Block Write: i2c_smbus_write_i2c_block_data() @@ -225,3 +269,5 @@ Comm byte. Note that command lengths of 0, 2, or more bytes are supported as they are indistinguishable from data. S Addr Wr [A] Comm [A] Data [A] Data [A] ... [A] Data [A] P + +Functionality flag: I2C_FUNC_SMBUS_WRITE_I2C_BLOCK diff --git a/Documentation/i2c/ten-bit-addresses b/Documentation/i2c/ten-bit-addresses index 200074f8136..cdfe13901b9 100644 --- a/Documentation/i2c/ten-bit-addresses +++ b/Documentation/i2c/ten-bit-addresses @@ -1,22 +1,24 @@ -The I2C protocol knows about two kinds of device addresses: normal 7 bit +The I2C protocol knows about two kinds of device addresses: normal 7 bit addresses, and an extended set of 10 bit addresses. The sets of addresses do not intersect: the 7 bit address 0x10 is not the same as the 10 bit -address 0x10 (though a single device could respond to both of them). You -select a 10 bit address by adding an extra byte after the address -byte: - S Addr7 Rd/Wr .... -becomes - S 11110 Addr10 Rd/Wr -S is the start bit, Rd/Wr the read/write bit, and if you count the number -of bits, you will see the there are 8 after the S bit for 7 bit addresses, -and 16 after the S bit for 10 bit addresses. +address 0x10 (though a single device could respond to both of them). -WARNING! The current 10 bit address support is EXPERIMENTAL. There are -several places in the code that will cause SEVERE PROBLEMS with 10 bit -addresses, even though there is some basic handling and hooks. Also, -almost no supported adapter handles the 10 bit addresses correctly. +I2C messages to and from 10-bit address devices have a different format. +See the I2C specification for the details. -As soon as a real 10 bit address device is spotted 'in the wild', we -can and will add proper support. Right now, 10 bit address devices -are defined by the I2C protocol, but we have never seen a single device -which supports them. +The current 10 bit address support is minimal. It should work, however +you can expect some problems along the way: +* Not all bus drivers support 10-bit addresses. Some don't because the + hardware doesn't support them (SMBus doesn't require 10-bit address + support for example), some don't because nobody bothered adding the + code (or it's there but not working properly.) Software implementation + (i2c-algo-bit) is known to work. +* Some optional features do not support 10-bit addresses. This is the + case of automatic detection and instantiation of devices by their, + drivers, for example. +* Many user-space packages (for example i2c-tools) lack support for + 10-bit addresses. + +Note that 10-bit address devices are still pretty rare, so the limitations +listed above could stay for a long time, maybe even forever if nobody +needs them to be fixed. diff --git a/Documentation/i2c/upgrading-clients b/Documentation/i2c/upgrading-clients index 9a45f9bb6a2..8e5fbd88c7d 100644 --- a/Documentation/i2c/upgrading-clients +++ b/Documentation/i2c/upgrading-clients @@ -61,7 +61,7 @@ static int example_attach(struct i2c_adapter *adap, int addr, int kind) return 0; } -static int __devexit example_detach(struct i2c_client *client) +static int example_detach(struct i2c_client *client) { struct example_state *state = i2c_get_clientdata(client); @@ -81,7 +81,7 @@ static struct i2c_driver example_driver = { .name = "example", }, .attach_adapter = example_attach_adapter, - .detach_client = __devexit_p(example_detach), + .detach_client = example_detach, .suspend = example_suspend, .resume = example_resume, }; @@ -93,7 +93,7 @@ Updating the client The new style binding model will check against a list of supported devices and their associated address supplied by the code registering the busses. This means that the driver .attach_adapter and -.detach_adapter methods can be removed, along with the addr_data, +.detach_client methods can be removed, along with the addr_data, as follows: - static struct i2c_driver example_driver; @@ -110,14 +110,14 @@ as follows: static struct i2c_driver example_driver = { - .attach_adapter = example_attach_adapter, -- .detach_client = __devexit_p(example_detach), +- .detach_client = example_detach, } Add the probe and remove methods to the i2c_driver, as so: static struct i2c_driver example_driver = { + .probe = example_probe, -+ .remove = __devexit_p(example_remove), ++ .remove = example_remove, } Change the example_attach method to accept the new parameters @@ -196,11 +196,11 @@ static int example_probe(struct i2c_client *i2c_client, Update the detach method, by changing the name to _remove and to delete the i2c_detach_client call. It is possible that you -can also remove the ret variable as it is not not needed for -any of the core functions. +can also remove the ret variable as it is not needed for any +of the core functions. -- static int __devexit example_detach(struct i2c_client *client) -+ static int __devexit example_remove(struct i2c_client *client) +- static int example_detach(struct i2c_client *client) ++ static int example_remove(struct i2c_client *client) { struct example_state *state = i2c_get_clientdata(client); @@ -253,7 +253,7 @@ static int example_probe(struct i2c_client *client, return 0; } -static int __devexit example_remove(struct i2c_client *client) +static int example_remove(struct i2c_client *client) { struct example_state *state = i2c_get_clientdata(client); @@ -275,7 +275,7 @@ static struct i2c_driver example_driver = { }, .id_table = example_idtable, .probe = example_probe, - .remove = __devexit_p(example_remove), + .remove = example_remove, .suspend = example_suspend, .resume = example_resume, }; diff --git a/Documentation/i2c/writing-clients b/Documentation/i2c/writing-clients index 6b9af7d479c..6b344b516bf 100644 --- a/Documentation/i2c/writing-clients +++ b/Documentation/i2c/writing-clients @@ -38,13 +38,13 @@ static struct i2c_driver foo_driver = { .name = "foo", }, - .id_table = foo_ids, + .id_table = foo_idtable, .probe = foo_probe, .remove = foo_remove, /* if device autodetection is needed: */ .class = I2C_CLASS_SOMETHING, .detect = foo_detect, - .address_data = &addr_data, + .address_list = normal_i2c, .shutdown = foo_shutdown, /* optional */ .suspend = foo_suspend, /* optional */ @@ -74,6 +74,11 @@ structure at all. You should use this to keep device-specific data. /* retrieve the value */ void *i2c_get_clientdata(const struct i2c_client *client); +Note that starting with kernel 2.6.34, you don't have to set the `data' field +to NULL in remove() or if probe() failed anymore. The i2c-core does this +automatically on these occasions. Those are also the only times the core will +touch this field. + Accessing the client ==================== @@ -126,19 +131,9 @@ different) configuration information, as do drivers handling chip variants that can't be distinguished by protocol probing, or which need some board specific information to operate correctly. -Accordingly, the I2C stack now has two models for associating I2C devices -with their drivers: the original "legacy" model, and a newer one that's -fully compatible with the Linux 2.6 driver model. These models do not mix, -since the "legacy" model requires drivers to create "i2c_client" device -objects after SMBus style probing, while the Linux driver model expects -drivers to be given such device objects in their probe() routines. - -The legacy model is deprecated now and will soon be removed, so we no -longer document it here. - -Standard Driver Model Binding ("New Style") -------------------------------------------- +Device/Driver Binding +--------------------- System infrastructure, typically board-specific initialization code or boot firmware, reports what I2C devices exist. For example, there may be @@ -201,21 +196,32 @@ a given I2C bus. This is for example the case of hardware monitoring devices on a PC's SMBus. In that case, you may want to let your driver detect supported devices automatically. This is how the legacy model was working, and is now available as an extension to the standard -driver model (so that we can finally get rid of the legacy model.) +driver model. You simply have to define a detect callback which will attempt to identify supported devices (returning 0 for supported ones and -ENODEV for unsupported ones), a list of addresses to probe, and a device type (or class) so that only I2C buses which may have that type of device -connected (and not otherwise enumerated) will be probed. The i2c -core will then call you back as needed and will instantiate a device -for you for every successful detection. +connected (and not otherwise enumerated) will be probed. For example, +a driver for a hardware monitoring chip for which auto-detection is +needed would set its class to I2C_CLASS_HWMON, and only I2C adapters +with a class including I2C_CLASS_HWMON would be probed by this driver. +Note that the absence of matching classes does not prevent the use of +a device of that type on the given I2C adapter. All it prevents is +auto-detection; explicit instantiation of devices is still possible. Note that this mechanism is purely optional and not suitable for all devices. You need some reliable way to identify the supported devices (typically using device-specific, dedicated identification registers), otherwise misdetections are likely to occur and things can get wrong -quickly. +quickly. Keep in mind that the I2C protocol doesn't include any +standard way to detect the presence of a chip at a given address, let +alone a standard way to identify devices. Even worse is the lack of +semantics associated to bus transfers, which means that the same +transfer can be seen as a read operation by a chip and as a write +operation by another chip. For these reasons, explicit device +instantiation should always be preferred to auto-detection where +possible. Device Deletion @@ -239,21 +245,17 @@ static int __init foo_init(void) { return i2c_add_driver(&foo_driver); } +module_init(foo_init); static void __exit foo_cleanup(void) { i2c_del_driver(&foo_driver); } +module_exit(foo_cleanup); -/* Substitute your own name and email address */ -MODULE_AUTHOR("Frodo Looijaard <frodol@dds.nl>" -MODULE_DESCRIPTION("Driver for Barf Inc. Foo I2C devices"); - -/* a few non-GPL license types are also allowed */ -MODULE_LICENSE("GPL"); +The module_i2c_driver() macro can be used to reduce above code. -module_init(foo_init); -module_exit(foo_cleanup); +module_i2c_driver(foo_driver); Note that some functions are marked by `__init'. These functions can be removed after kernel booting (or module loading) is completed. @@ -261,6 +263,17 @@ Likewise, functions marked by `__exit' are dropped by the compiler when the code is built into the kernel, as they would never be called. +Driver Information +================== + +/* Substitute your own name and email address */ +MODULE_AUTHOR("Frodo Looijaard <frodol@dds.nl>" +MODULE_DESCRIPTION("Driver for Barf Inc. Foo I2C devices"); + +/* a few non-GPL license types are also allowed */ +MODULE_LICENSE("GPL"); + + Power Management ================ @@ -317,8 +330,9 @@ Plain I2C communication These routines read and write some bytes from/to a client. The client contains the i2c address, so you do not have to include it. The second parameter contains the bytes to read/write, the third the number of bytes -to read/write (must be less than the length of the buffer.) Returned is -the actual number of bytes read/written. +to read/write (must be less than the length of the buffer, also should be +less than 64k since msg.len is u16.) Returned is the actual number of bytes +read/written. int i2c_transfer(struct i2c_adapter *adap, struct i2c_msg *msg, int num); @@ -351,8 +365,6 @@ in terms of it. Never use this function directly! s32 i2c_smbus_read_word_data(struct i2c_client *client, u8 command); s32 i2c_smbus_write_word_data(struct i2c_client *client, u8 command, u16 value); - s32 i2c_smbus_process_call(struct i2c_client *client, - u8 command, u16 value); s32 i2c_smbus_read_block_data(struct i2c_client *client, u8 command, u8 *values); s32 i2c_smbus_write_block_data(struct i2c_client *client, @@ -367,6 +379,8 @@ These ones were removed from i2c-core because they had no users, but could be added back later if needed: s32 i2c_smbus_write_quick(struct i2c_client *client, u8 value); + s32 i2c_smbus_process_call(struct i2c_client *client, + u8 command, u16 value); s32 i2c_smbus_block_process_call(struct i2c_client *client, u8 command, u8 length, u8 *values); |