diff options
Diffstat (limited to 'Documentation/i2c')
44 files changed, 1925 insertions, 1674 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-amd8111 b/Documentation/i2c/busses/i2c-amd8111 index db294ee7455..460dd6635fd 100644 --- a/Documentation/i2c/busses/i2c-amd8111 +++ b/Documentation/i2c/busses/i2c-amd8111 @@ -5,7 +5,7 @@ Supported adapters: Datasheets: AMD datasheet not yet available, but almost everything can be found - in publically available ACPI 2.0 specification, which the adapter + in the publicly available ACPI 2.0 specification, which the adapter follows. Author: Vojtech Pavlik <vojtech@suse.cz> 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 fd4b2712d57..adf5e33e831 100644 --- a/Documentation/i2c/busses/i2c-i801 +++ b/Documentation/i2c/busses/i2c-i801 @@ -5,31 +5,56 @@ Supported adapters: '810' and '810E' chipsets) * Intel 82801BA (ICH2 - part of the '815E' chipset) * Intel 82801CA/CAM (ICH3) - * Intel 82801DB (ICH4) (HW PEC supported, 32 byte buffer not supported) - * Intel 82801EB/ER (ICH5) (HW PEC supported, 32 byte buffer not supported) + * Intel 82801DB (ICH4) (HW PEC supported) + * Intel 82801EB/ER (ICH5) (HW PEC supported) * Intel 6300ESB * Intel 82801FB/FR/FW/FRW (ICH6) - * Intel ICH7 - Datasheets: Publicly available at the Intel website + * Intel 82801G (ICH7) + * Intel 631xESB/632xESB (ESB2) + * Intel 82801H (ICH8) + * Intel 82801I (ICH9) + * Intel EP80579 (Tolapai) + * Intel 82801JI (ICH10) + * 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: - Frodo Looijaard <frodol@dds.nl>, - Philip Edelbrock <phil@netroedge.com>, Mark Studebaker <mdsxyz123@yahoo.com> + Jean Delvare <jdelvare@suse.de> Module Parameters ----------------- -* force_addr: int - Forcibly enable the ICH at the given address. EXTREMELY DANGEROUS! +* 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 ----------- The ICH (properly known as the 82801AA), ICH0 (82801AB), ICH2 (82801BA), -ICH3 (82801CA/CAM) and later devices are Intel chips that are a part of +ICH3 (82801CA/CAM) and later devices (PCH) are Intel chips that are a part of Intel's '810' chipset for Celeron-based PCs, '810E' chipset for Pentium-based PCs, '815E' chipset, and others. @@ -46,14 +71,9 @@ following: The SMBus controller is function 3 in device 1f. Class 0c05 is SMBus Serial Controller. -If you do NOT see the 24x3 device at function 3, and you can't figure out -any way in the BIOS to enable it, - The ICH chips are quite similar to Intel's PIIX4 chip, at least in the SMBus controller. -See the file i2c-piix4 for some additional information. - Process Call Support -------------------- @@ -64,7 +84,7 @@ Not supported. I2C Block Read Support ---------------------- -Not supported at the moment. +I2C block read is supported on the 82801EB (ICH5) and later chips. SMBus 2.0 Support @@ -72,6 +92,67 @@ 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 +---------------- + +If your system has an Intel ICH south bridge, but you do NOT see the +SMBus device at 00:1f.3 in lspci, and you can't figure out any way in the +BIOS to enable it, it means it has been hidden by the BIOS code. Asus is +well known for first doing this on their P4B motherboard, and many other +boards after that. Some vendor machines are affected as well. + +The first thing to try is the "i2c_ec" ACPI driver. It could be that the +SMBus was hidden on purpose because it'll be driven by ACPI. If the +i2c_ec driver works for you, just forget about the i2c-i801 driver and +don't try to unhide the ICH SMBus. Even if i2c_ec doesn't work, you +better make sure that the SMBus isn't used by the ACPI code. Try loading +the "fan" and "thermal" drivers, and check in /proc/acpi/fan and +/proc/acpi/thermal_zone. If you find anything there, it's likely that +the ACPI is accessing the SMBus and it's safer not to unhide it. Only +once you are certain that ACPI isn't using the SMBus, you can attempt +to unhide it. + +In order to unhide the SMBus, we need to change the value of a PCI +register before the kernel enumerates the PCI devices. This is done in +drivers/pci/quirks.c, where all affected boards must be listed (see +function asus_hides_smbus_hostbridge.) If the SMBus device is missing, +and you think there's something interesting on the SMBus (e.g. a +hardware monitoring chip), you need to add your board to the list. + +The motherboard is identified using the subvendor and subdevice IDs of the +host bridge PCI device. Get yours with "lspci -n -v -s 00:00.0": + +00:00.0 Class 0600: 8086:2570 (rev 02) + Subsystem: 1043:80f2 + Flags: bus master, fast devsel, latency 0 + Memory at fc000000 (32-bit, prefetchable) [size=32M] + Capabilities: [e4] #09 [2106] + Capabilities: [a0] AGP version 3.0 + +Here the host bridge ID is 2570 (82865G/PE/P), the subvendor ID is 1043 +(Asus) and the subdevice ID is 80f2 (P4P800-X). You can find the symbolic +names for the bridge ID and the subvendor ID in include/linux/pci_ids.h, +and then add a case for your subdevice ID at the right place in +drivers/pci/quirks.c. Then please give it very good testing, to make sure +that the unhidden SMBus doesn't conflict with e.g. ACPI. + +If it works, proves useful (i.e. there are usable chips on the SMBus) +and seems safe, please submit a patch for inclusion into the kernel. + +Note: There's a useful script in lm_sensors 2.10.2 and later, named +unhide_ICH_SMBus (in prog/hotplug), which uses the fakephp driver to +temporarily unhide the SMBus without having to patch and recompile your +kernel. It's very convenient if you just want to check if there's +anything interesting on your hidden ICH SMBus. + + ********************** The lm_sensors project gratefully acknowledges the support of Texas Instruments in the initial development of this driver. diff --git a/Documentation/i2c/busses/i2c-i810 b/Documentation/i2c/busses/i2c-i810 deleted file mode 100644 index 83c3b9743c3..00000000000 --- a/Documentation/i2c/busses/i2c-i810 +++ /dev/null @@ -1,47 +0,0 @@ -Kernel driver i2c-i810 - -Supported adapters: - * Intel 82810, 82810-DC100, 82810E, and 82815 (GMCH) - * Intel 82845G (GMCH) - -Authors: - Frodo Looijaard <frodol@dds.nl>, - Philip Edelbrock <phil@netroedge.com>, - Kyösti Mälkki <kmalkki@cc.hut.fi>, - Ralph Metzler <rjkm@thp.uni-koeln.de>, - Mark D. Studebaker <mdsxyz123@yahoo.com> - -Main contact: Mark Studebaker <mdsxyz123@yahoo.com> - -Description ------------ - -WARNING: If you have an '810' or '815' motherboard, your standard I2C -temperature sensors are most likely on the 801's I2C bus. You want the -i2c-i801 driver for those, not this driver. - -Now for the i2c-i810... - -The GMCH chip contains two I2C interfaces. - -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. It may be connected to a -TV-out chip such as the BT869 or possibly to a digital flat-panel display. - -Features --------- - -Both busses use the i2c-algo-bit driver for 'bit banging' -and support for specific transactions is provided by i2c-algo-bit. - -Issues ------- - -If you enable bus testing in i2c-algo-bit (insmod i2c-algo-bit bit_test=1), -the test may fail; if so, the i2c-i810 driver won't be inserted. However, -we think this has been fixed. 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 e379e182e64..9698c396b83 100644 --- a/Documentation/i2c/busses/i2c-nforce2 +++ b/Documentation/i2c/busses/i2c-nforce2 @@ -5,13 +5,22 @@ Supported adapters: * nForce2 Ultra 400 MCP 10de:0084 * nForce3 Pro150 MCP 10de:00D4 * nForce3 250Gb MCP 10de:00E4 - * nForce4 MCP 10de:0052 - -Datasheet: not publically available, but seems to be similar to the + * nForce4 MCP 10de:0052 + * nForce4 MCP-04 10de:0034 + * 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. Authors: - Hans-Frieder Vogt <hfvogt@arcor.de>, + Hans-Frieder Vogt <hfvogt@gmx.net>, Thomas Leibold <thomas@plx.com>, Patrick Dreker <patrick@dreker.de> @@ -35,7 +44,7 @@ Notes ----- The SMBus adapter in the nForce2 chipset seems to be very similar to the -SMBus 2.0 adapter in the AMD-8111 southbridge. However, I could only get +SMBus 2.0 adapter in the AMD-8111 south bridge. However, I could only get the driver to work with direct I/O access, which is different to the EC interface of the AMD-8111. Tested on Asus A7N8X. The ACPI DSDT table of the Asus A7N8X lists two SMBuses, both of which are supported by this driver. diff --git a/Documentation/i2c/busses/i2c-ocores b/Documentation/i2c/busses/i2c-ocores new file mode 100644 index 00000000000..c269aaa2f26 --- /dev/null +++ b/Documentation/i2c/busses/i2c-ocores @@ -0,0 +1,68 @@ +Kernel driver i2c-ocores + +Supported adapters: + * OpenCores.org I2C controller by Richard Herveille (see datasheet link) + Datasheet: http://www.opencores.org/projects.cgi/web/i2c/overview + +Author: Peter Korsgaard <jacmet@sunsite.dk> + +Description +----------- + +i2c-ocores is an i2c bus driver for the OpenCores.org I2C controller +IP core by Richard Herveille. + +Usage +----- + +i2c-ocores uses the platform bus, so you need to provide a struct +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: + +static struct resource ocores_resources[] = { + [0] = { + .start = MYI2C_BASEADDR, + .end = MYI2C_BASEADDR + 8, + .flags = IORESOURCE_MEM, + }, + [1] = { + .start = MYI2C_IRQ, + .end = MYI2C_IRQ, + .flags = IORESOURCE_IRQ, + }, +}; + +/* 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 = { + .name = "ocores-i2c", + .dev = { + .platform_data = &myi2c_data, + }, + .num_resources = ARRAY_SIZE(ocores_resources), + .resource = ocores_resources, +}; diff --git a/Documentation/i2c/busses/i2c-parport b/Documentation/i2c/busses/i2c-parport index 9f1d0082da1..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 @@ -12,17 +12,26 @@ meant as a replacement for the older, individual drivers: teletext adapters) It currently supports the following devices: - * Philips adapter - * home brew teletext adapter - * Velleman K8000 adapter - * ELV adapter - * Analog Devices evaluation boards (ADM1025, ADM1030, ADM1031, ADM1032) + * (type=0) Philips adapter + * (type=1) home brew teletext adapter + * (type=2) Velleman K8000 adapter + * (type=3) ELV adapter + * (type=4) Analog Devices ADM1032 evaluation board + * (type=5) Analog Devices evaluation boards: ADM1025, ADM1030, ADM1031 + * (type=6) Barco LPT->DVI (K5800236) adapter + * (type=7) One For All JP1 parallel port adapter These devices use different pinout configurations, so you have to tell the driver what you have, using the type module parameter. There is no way to autodetect the devices. Support for different pinout configurations 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 ------------------------- @@ -152,3 +161,17 @@ many more, using /dev/velleman. http://home.wanadoo.nl/hihihi/libk8005.htm http://struyve.mine.nu:8080/index.php?block=k8000 http://sourceforge.net/projects/libk8005/ + + +One For All JP1 parallel port adapter +------------------------------------- + +The JP1 project revolves around a set of remote controls which expose +the I2C bus their internal configuration EEPROM lives on via a 6 pin +jumper in the battery compartment. More details can be found at: + +http://www.hifi-remote.com/jp1/ + +Details of the simple parallel port hardware can be found at: + +http://www.hifi-remote.com/jp1/hardware.shtml 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 856b4b8b962..aa959fd2245 100644 --- a/Documentation/i2c/busses/i2c-piix4 +++ b/Documentation/i2c/busses/i2c-piix4 @@ -4,8 +4,17 @@ Supported adapters: * Intel 82371AB PIIX4 and PIIX4E * Intel 82443MX (440MX) Datasheet: Publicly available at the Intel website - * ServerWorks OSB4, CSB5 and CSB6 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 @@ -21,8 +30,6 @@ Module Parameters Forcibly enable the PIIX4. DANGEROUS! * force_addr: int Forcibly enable the PIIX4 at the given address. EXTREMELY DANGEROUS! -* fix_hstcfg: int - Fix config register. Needed on some boards (Force CPCI735). Description @@ -63,10 +70,41 @@ The PIIX4E is just an new version of the PIIX4; it is supported as well. The PIIX/PIIX3 does not implement an SMBus or I2C bus, so you can't use this driver on those mainboards. -The ServerWorks Southbridges, the Intel 440MX, and the Victory766 are +The ServerWorks Southbridges, the Intel 440MX, and the Victory66 are identical to the PIIX4 in I2C/SMBus support. -A few OSB4 southbridges are known to be misconfigured by the BIOS. In this -case, you have you use the fix_hstcfg module parameter. Do not use it -unless you know you have to, because in some cases it also breaks -configuration on southbridges that don't need it. +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. + +1) Use lspci command and locate the PCI device with the SMBus controller: + 00:0f.0 ISA bridge: ServerWorks OSB4 South Bridge (rev 4f) + The line may vary for different chipsets. Please consult the driver source + for all possible PCI ids (and lspci -n to match them). Lets assume the + device is located at 00:0f.0. +2) Now you just need to change the value in 0xD2 register. Get it first with + command: lspci -xxx -s 00:0f.0 + If the value is 0x3 then you need to change it to 0x1 + setpci -s 00:0f.0 d2.b=1 + +Please note that you don't need to do that in all cases, just when the SMBus is +not working properly. + + +Hardware-specific issues +------------------------ + +This driver will refuse to load on IBM systems with an Intel PIIX4 SMBus. +Some of these machines have an RFID EEPROM (24RF08) connected to the SMBus, +which can easily get corrupted due to a state machine bug. These are mostly +Thinkpad laptops, but desktop systems may also be affected. We have no list +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 diff --git a/Documentation/i2c/busses/i2c-prosavage b/Documentation/i2c/busses/i2c-prosavage deleted file mode 100644 index 70368790251..00000000000 --- a/Documentation/i2c/busses/i2c-prosavage +++ /dev/null @@ -1,23 +0,0 @@ -Kernel driver i2c-prosavage - -Supported adapters: - - S3/VIA KM266/VT8375 aka ProSavage8 - S3/VIA KM133/VT8365 aka Savage4 - -Author: Henk Vergonet <henk@god.dyndns.org> - -Description ------------ - -The Savage4 chips contain 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. - -Usefull for gaining access to the TV Encoder chips. - diff --git a/Documentation/i2c/busses/i2c-savage4 b/Documentation/i2c/busses/i2c-savage4 deleted file mode 100644 index 6ecceab618d..00000000000 --- a/Documentation/i2c/busses/i2c-savage4 +++ /dev/null @@ -1,26 +0,0 @@ -Kernel driver i2c-savage4 - -Supported adapters: - * Savage4 - * Savage2000 - -Authors: - Alexander Wold <awold@bigfoot.com>, - Mark D. Studebaker <mdsxyz123@yahoo.com> - -Description ------------ - -The Savage4 chips contain 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 DDC bus is not yet supported because its register -is not directly memory-mapped. - -The second interface is a general-purpose I2C bus. This is the only -interface supported by the driver at the moment. - 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-sis69x b/Documentation/i2c/busses/i2c-sis96x index b88953dfd58..0b979f3252a 100644 --- a/Documentation/i2c/busses/i2c-sis69x +++ b/Documentation/i2c/busses/i2c-sis96x @@ -7,7 +7,7 @@ Supported adapters: Any combination of these host bridges: 645, 645DX (aka 646), 648, 650, 651, 655, 735, 745, 746 and these south bridges: - 961, 962, 963(L) + 961, 962, 963(L) Author: Mark M. Hoffman <mhoffman@lightlink.com> @@ -29,21 +29,21 @@ The command "lspci" as root should produce something like these lines: or perhaps this... -00:00.0 Host bridge: Silicon Integrated Systems [SiS]: Unknown device 0645 +00:00.0 Host bridge: Silicon Integrated Systems [SiS]: Unknown device 0645 00:02.0 ISA bridge: Silicon Integrated Systems [SiS]: Unknown device 0961 00:02.1 SMBus: Silicon Integrated Systems [SiS]: Unknown device 0016 (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 chipsets as well: 635, and 635T. If anyone owns a board with those chips AND is willing to risk crashing & burning an otherwise well-behaved kernel in the name of progress... please contact me at <mhoffman@lightlink.com> or -via the project's mailing list: <lm-sensors@lm-sensors.org>. Please -send bug reports and/or success stories as well. +via the linux-i2c mailing list: <linux-i2c@vger.kernel.org>. Please send bug +reports and/or success stories as well. TO DOs @@ -60,7 +60,7 @@ Mark D. Studebaker <mdsxyz123@yahoo.com> - design hints and bug fixes Alexander Maylsh <amalysh@web.de> - ditto, plus an important datasheet... almost the one I really wanted -Hans-Günter Lütke Uphues <hg_lu@t-online.de> +Hans-Günter Lütke Uphues <hg_lu@t-online.de> - patch for SiS735 Robert Zwerus <arzie@dds.nl> - testing for SiS645DX diff --git a/Documentation/i2c/busses/i2c-taos-evm b/Documentation/i2c/busses/i2c-taos-evm new file mode 100644 index 00000000000..60299555dcf --- /dev/null +++ b/Documentation/i2c/busses/i2c-taos-evm @@ -0,0 +1,46 @@ +Kernel driver i2c-taos-evm + +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 +be controlled over the serial port. Virtually all evaluation modules +are supported, but a few lines of code need to be added for each new +module to instantiate the right I2C chip on the bus. Obviously, a driver +for the chip in question is also needed. + +Currently supported devices are: + +* TAOS TSL2550 EVM + +For additional information on TAOS products, please see + http://www.taosinc.com/ + + +Using this driver +----------------- + +In order to use this driver, you'll need the serport driver, and the +inputattach tool, which is part of the input-utils package. The following +commands will tell the kernel that you have a TAOS EVM on the first +serial port: + +# modprobe serport +# inputattach --taos-evm /dev/ttyS0 + + +Technical details +----------------- + +Only 4 SMBus transaction types are supported by the TAOS evaluation +modules: +* Receive Byte +* Send Byte +* Read Byte +* Write Byte + +The communication protocol is text-based and pretty simple. It is +described in a PDF document on the CD which comes with the evaluation +module. The communication is rather slow, because the serial port has +to operate at 1200 bps. However, I don't think this is a big concern in +practice, as these modules are meant for evaluation and testing only. diff --git a/Documentation/i2c/busses/i2c-via b/Documentation/i2c/busses/i2c-via index 55edfe1a640..343870661ac 100644 --- a/Documentation/i2c/busses/i2c-via +++ b/Documentation/i2c/busses/i2c-via @@ -4,7 +4,7 @@ Supported adapters: * VIA Technologies, InC. VT82C586B Datasheet: Publicly available at the VIA website -Author: Kyösti Mälkki <kmalkki@cc.hut.fi> +Author: Kyösti Mälkki <kmalkki@cc.hut.fi> Description ----------- diff --git a/Documentation/i2c/busses/i2c-viapro b/Documentation/i2c/busses/i2c-viapro index 9363b8bd610..ab64ce21c25 100644 --- a/Documentation/i2c/busses/i2c-viapro +++ b/Documentation/i2c/busses/i2c-viapro @@ -7,15 +7,28 @@ Supported adapters: * VIA Technologies, Inc. VT82C686A/B Datasheet: Sometimes available at the VIA website - * VIA Technologies, Inc. VT8231, VT8233, VT8233A, VT8235, VT8237 - Datasheet: available on request from Via + * VIA Technologies, Inc. VT8231, VT8233, VT8233A + Datasheet: available on request from VIA + + * VIA Technologies, Inc. VT8235, VT8237R, VT8237A, VT8237S, VT8251 + Datasheet: available on request and under NDA from VIA + + * VIA Technologies, Inc. CX700 + Datasheet: available on request and under NDA from VIA + + * 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: - Frodo Looijaard <frodol@dds.nl>, - Philip Edelbrock <phil@netroedge.com>, - Kyösti Mälkki <kmalkki@cc.hut.fi>, + 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 ----------------- @@ -41,6 +54,13 @@ Your lspci -n listing must show one of these : device 1106:8235 (VT8231 function 4) device 1106:3177 (VT8235) device 1106:3227 (VT8237R) + device 1106:3337 (VT8237A) + device 1106:3372 (VT8237S) + 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. @@ -48,3 +68,6 @@ enable ACPI / SMBus or even USB. Except for the oldest chips (VT82C596A/B, VT82C686A and most probably VT8231), this driver supports I2C block transactions. Such transactions are mainly useful to read from and write to EEPROMs. + +The CX700/VX800/VX820 additionally appears to support SMBus PEC, although +this driver doesn't implement it yet. 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 08c8cd1df60..ce83c871fe9 100644 --- a/Documentation/i2c/busses/scx200_acb +++ b/Documentation/i2c/busses/scx200_acb @@ -2,13 +2,31 @@ Kernel driver scx200_acb Author: Christer Weinigel <wingel@nano-system.com> +The driver supersedes the older, never merged driver named i2c-nscacb. + Module Parameters ----------------- -* base: int - Base addresses for the ACCESS.bus controllers +* base: up to 4 ints + Base addresses for the ACCESS.bus controllers on SCx200 and SC1100 devices + + By default the driver uses two base addresses 0x820 and 0x840. + If you want only one base address, specify the second as 0 so as to + override this default. Description ----------- -Enable the use of the ACCESS.bus controllers of a SCx200 processor. +Enable the use of the ACCESS.bus controller on the Geode SCx200 and +SC1100 processors and the CS5535 and CS5536 Geode companion devices. + +Device-specific notes +--------------------- + +The SC1100 WRAP boards are known to use base addresses 0x810 and 0x820. +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 +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 96fec562a8e..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 'max6875 subclient'. - - -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, 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 c4fce6a1353..00000000000 --- a/Documentation/i2c/chips/pca9539 +++ /dev/null @@ -1,47 +0,0 @@ -Kernel driver pca9539 -===================== - -Supported chips: - * Philips PCA9539 - Prefix: 'pca9539' - Addresses scanned: 0x74 - 0x77 - 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. - - -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 2752c8ce316..00000000000 --- a/Documentation/i2c/chips/pcf8574 +++ /dev/null @@ -1,69 +0,0 @@ -Kernel driver pcf8574 -===================== - -Supported chips: - * Philips PCF8574 - Prefix: 'pcf8574' - Addresses scanned: I2C 0x20 - 0x27 - Datasheet: Publicly available at the Philips Semiconductors website - http://www.semiconductors.philips.com/pip/PCF8574P.html - - * Philips PCF8574A - Prefix: 'pcf8574a' - Addresses scanned: I2C 0x38 - 0x3f - 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 -------------------------------------- - -! Be careful ! -The PCF8574(A) is plainly impossible to detect ! Stupid chip. -So every chip with address in the interval [20..27] and [38..3f] are -detected as PCF8574(A). 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 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. - -On module initialization the chip is configured as eight inputs (all -outputs to 1), so you can connect any circuit to the PCF8574(A) without -being afraid of short-circuit. 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/chips/x1205 b/Documentation/i2c/chips/x1205 deleted file mode 100644 index 09407c991fe..00000000000 --- a/Documentation/i2c/chips/x1205 +++ /dev/null @@ -1,38 +0,0 @@ -Kernel driver x1205 -=================== - -Supported chips: - * Xicor X1205 RTC - Prefix: 'x1205' - Addresses scanned: none - Datasheet: http://www.intersil.com/cda/deviceinfo/0,1477,X1205,00.html - -Authors: - Karen Spearel <kas11@tampabay.rr.com>, - Alessandro Zummo <a.zummo@towertech.it> - -Description ------------ - -This module aims to provide complete access to the Xicor X1205 RTC. -Recently Xicor has merged with Intersil, but the chip is -still sold under the Xicor brand. - -This chip is located at address 0x6f and uses a 2-byte register addressing. -Two bytes need to be written to read a single register, while most -other chips just require one and take the second one as the data -to be written. To prevent corrupting unknown chips, the user must -explicitely set the probe parameter. - -example: - -modprobe x1205 probe=0,0x6f - -The module supports one more option, hctosys, which is used to set the -software clock from the x1205. On systems where the x1205 is the -only hardware rtc, this parameter could be used to achieve a correct -date/time earlier in the system boot sequence. - -example: - -modprobe x1205 probe=0,0x6f hctosys=1 diff --git a/Documentation/i2c/dev-interface b/Documentation/i2c/dev-interface index b849ad63658..3e742ba2553 100644 --- a/Documentation/i2c/dev-interface +++ b/Documentation/i2c/dev-interface @@ -4,6 +4,10 @@ the /dev interface. You need to load module i2c-dev for this. Each registered i2c adapter gets a number, counting from 0. You can examine /sys/class/i2c-dev/ to see what number corresponds to which adapter. +Alternatively, you can run "i2cdetect -l" to obtain a formated list of all +i2c adapters present on your system at a given time. i2cdetect is part of +the i2c-tools package. + I2C device files are character device files with major device number 89 and a minor device number corresponding to the number assigned as explained above. They should be called "i2c-%d" (i2c-0, i2c-1, ..., @@ -17,30 +21,34 @@ So let's say you want to access an i2c adapter from a C program. The first thing to do is "#include <linux/i2c-dev.h>". Please note that there are two files named "i2c-dev.h" out there, one is distributed with the Linux kernel and is meant to be included from kernel -driver code, the other one is distributed with lm_sensors and is +driver code, the other one is distributed with i2c-tools and is meant to be included from user-space programs. You obviously want the second one here. Now, you have to decide which adapter you want to access. You should -inspect /sys/class/i2c-dev/ to decide this. Adapter numbers are assigned -somewhat dynamically, so you can not even assume /dev/i2c-0 is the -first adapter. +inspect /sys/class/i2c-dev/ or run "i2cdetect -l" to decide this. +Adapter numbers are assigned somewhat dynamically, so you can not +assume much about them. They can even change from one boot to the next. Next thing, open the device file, as follows: + int file; int adapter_nr = 2; /* probably dynamically determined */ char filename[20]; - sprintf(filename,"/dev/i2c-%d",adapter_nr); - if ((file = open(filename,O_RDWR)) < 0) { + snprintf(filename, 19, "/dev/i2c-%d", adapter_nr); + file = open(filename, O_RDWR); + if (file < 0) { /* ERROR HANDLING; you can check errno to see what went wrong */ exit(1); } When you have opened the device, you must specify with what device address you want to communicate: + int addr = 0x40; /* The I2C address */ - if (ioctl(file,I2C_SLAVE,addr) < 0) { + + if (ioctl(file, I2C_SLAVE, addr) < 0) { /* ERROR HANDLING; you can check errno to see what went wrong */ exit(1); } @@ -48,31 +56,41 @@ address you want to communicate: Well, you are all set up now. You can now use SMBus commands or plain I2C to communicate with your device. SMBus commands are preferred if the device supports them. Both are illustrated below. + __u8 register = 0x10; /* Device register to access */ __s32 res; char buf[10]; + /* Using SMBus commands */ - res = i2c_smbus_read_word_data(file,register); + res = i2c_smbus_read_word_data(file, register); if (res < 0) { /* ERROR HANDLING: i2c transaction failed */ } else { /* res contains the read word */ } + /* Using I2C Write, equivalent of - i2c_smbus_write_word_data(file,register,0x6543) */ + i2c_smbus_write_word_data(file, register, 0x6543) */ buf[0] = register; buf[1] = 0x43; buf[2] = 0x65; - if ( write(file,buf,3) != 3) { + if (write(file, buf, 3) ! =3) { /* ERROR HANDLING: i2c transaction failed */ } + /* Using I2C Read, equivalent of i2c_smbus_read_byte(file) */ - if (read(file,buf,1) != 1) { + if (read(file, buf, 1) != 1) { /* ERROR HANDLING: i2c transaction failed */ } else { /* buf[0] contains the read byte */ } +Note that only a subset of the I2C and SMBus protocols can be achieved by +the means of read() and write() calls. In particular, so-called combined +transactions (mixing read and write messages in the same transaction) +aren't supported. For this reason, this interface is almost never used by +user-space programs. + IMPORTANT: because of the use of inline functions, you *have* to use '-O' or some variation when you compile your program! @@ -80,31 +98,34 @@ IMPORTANT: because of the use of inline functions, you *have* to use Full interface description ========================== -The following IOCTLs are defined and fully supported -(see also i2c-dev.h): +The following IOCTLs are defined: -ioctl(file,I2C_SLAVE,long addr) +ioctl(file, I2C_SLAVE, long addr) Change slave address. The address is passed in the 7 lower bits of the argument (except for 10 bit addresses, passed in the 10 lower bits in this case). -ioctl(file,I2C_TENBIT,long select) +ioctl(file, I2C_TENBIT, long select) Selects ten bit addresses if select not equals 0, selects normal 7 bit - addresses if select equals 0. Default 0. + addresses if select equals 0. Default 0. This request is only valid + if the adapter has I2C_FUNC_10BIT_ADDR. -ioctl(file,I2C_PEC,long select) +ioctl(file, I2C_PEC, long select) Selects SMBus PEC (packet error checking) generation and verification if select not equals 0, disables if select equals 0. Default 0. - Used only for SMBus transactions. + Used only for SMBus transactions. This request only has an effect if the + the adapter has I2C_FUNC_SMBUS_PEC; it is still safe if not, it just + doesn't have any effect. -ioctl(file,I2C_FUNCS,unsigned long *funcs) +ioctl(file, I2C_FUNCS, unsigned long *funcs) Gets the adapter functionality and puts it in *funcs. -ioctl(file,I2C_RDWR,struct i2c_rdwr_ioctl_data *msgset) - +ioctl(file, I2C_RDWR, struct i2c_rdwr_ioctl_data *msgset) Do combined read/write transaction without stop in between. - The argument is a pointer to a struct i2c_rdwr_ioctl_data { + Only valid if the adapter has I2C_FUNC_I2C. The argument is + a pointer to a + struct i2c_rdwr_ioctl_data { struct i2c_msg *msgs; /* ptr to array of simple messages */ int nmsgs; /* number of messages to exchange */ } @@ -115,10 +136,9 @@ ioctl(file,I2C_RDWR,struct i2c_rdwr_ioctl_data *msgset) The slave address and whether to use ten bit address mode has to be set in each message, overriding the values set with the above ioctl's. - -Other values are NOT supported at this moment, except for I2C_SMBUS, -which you should never directly call; instead, use the access functions -below. +ioctl(file, I2C_SMBUS, struct i2c_smbus_ioctl_data *args) + Not meant to be called directly; instead, use the access functions + below. You can do plain i2c transactions by using read(2) and write(2) calls. You do not need to pass the address byte; instead, set it through @@ -143,7 +163,52 @@ what happened. The 'write' transactions return 0 on success; the returns the number of values read. The block buffers need not be longer than 32 bytes. -The above functions are all macros, that resolve to calls to the -i2c_smbus_access function, that on its turn calls a specific ioctl +The above functions are all inline functions, that resolve to calls to +the i2c_smbus_access function, that on its turn calls a specific ioctl with the data in a specific format. Read the source code if you want to know what happens behind the screens. + + +Implementation details +====================== + +For the interested, here's the code flow which happens inside the kernel +when you use the /dev interface to I2C: + +1* Your program opens /dev/i2c-N and calls ioctl() on it, as described in +section "C example" above. + +2* These open() and ioctl() calls are handled by the i2c-dev kernel +driver: see i2c-dev.c:i2cdev_open() and i2c-dev.c:i2cdev_ioctl(), +respectively. You can think of i2c-dev as a generic I2C chip driver +that can be programmed from user-space. + +3* Some ioctl() calls are for administrative tasks and are handled by +i2c-dev directly. Examples include I2C_SLAVE (set the address of the +device you want to access) and I2C_PEC (enable or disable SMBus error +checking on future transactions.) + +4* Other ioctl() calls are converted to in-kernel function calls by +i2c-dev. Examples include I2C_FUNCS, which queries the I2C adapter +functionality using i2c.h:i2c_get_functionality(), and I2C_SMBUS, which +performs an SMBus transaction using i2c-core.c:i2c_smbus_xfer(). + +The i2c-dev driver is responsible for checking all the parameters that +come from user-space for validity. After this point, there is no +difference between these calls that came from user-space through i2c-dev +and calls that would have been performed by kernel I2C chip drivers +directly. This means that I2C bus drivers don't need to implement +anything special to support access from user-space. + +5* These i2c-core.c/i2c.h functions are wrappers to the actual +implementation of your I2C bus driver. Each adapter must declare +callback functions implementing these standard calls. +i2c.h:i2c_get_functionality() calls i2c_adapter.algo->functionality(), +while i2c-core.c:i2c_smbus_xfer() calls either +adapter.algo->smbus_xfer() if it is implemented, or if not, +i2c-core.c:i2c_smbus_xfer_emulated() which in turn calls +i2c_adapter.algo->master_xfer(). + +After your I2C bus driver has processed these requests, execution runs +up the call chain, with almost no processing done, except by i2c-dev to +package the returned data, if any, in suitable format for the ioctl. diff --git a/Documentation/i2c/fault-codes b/Documentation/i2c/fault-codes new file mode 100644 index 00000000000..47c25abb7d5 --- /dev/null +++ b/Documentation/i2c/fault-codes @@ -0,0 +1,124 @@ +This is a summary of the most important conventions for use of fault +codes in the I2C/SMBus stack. + + +A "Fault" is not always an "Error" +---------------------------------- +Not all fault reports imply errors; "page faults" should be a familiar +example. Software often retries idempotent operations after transient +faults. There may be fancier recovery schemes that are appropriate in +some cases, such as re-initializing (and maybe resetting). After such +recovery, triggered by a fault report, there is no error. + +In a similar way, sometimes a "fault" code just reports one defined +result for an operation ... it doesn't indicate that anything is wrong +at all, just that the outcome wasn't on the "golden path". + +In short, your I2C driver code may need to know these codes in order +to respond correctly. Other code may need to rely on YOUR code reporting +the right fault code, so that it can (in turn) behave correctly. + + +I2C and SMBus fault codes +------------------------- +These are returned as negative numbers from most calls, with zero or +some positive number indicating a non-fault return. The specific +numbers associated with these symbols differ between architectures, +though most Linux systems use <asm-generic/errno*.h> numbering. + +Note that the descriptions here are not exhaustive. There are other +codes that may be returned, and other cases where these codes should +be returned. However, drivers should not return other codes for these +cases (unless the hardware doesn't provide unique fault reports). + +Also, codes returned by adapter probe methods follow rules which are +specific to their host bus (such as PCI, or the platform bus). + + +EAGAIN + Returned by I2C adapters when they lose arbitration in master + transmit mode: some other master was transmitting different + data at the same time. + + Also returned when trying to invoke an I2C operation in an + atomic context, when some task is already using that I2C bus + to execute some other operation. + +EBADMSG + Returned by SMBus logic when an invalid Packet Error Code byte + is received. This code is a CRC covering all bytes in the + transaction, and is sent before the terminating STOP. This + fault is only reported on read transactions; the SMBus slave + may have a way to report PEC mismatches on writes from the + host. Note that even if PECs are in use, you should not rely + on these as the only way to detect incorrect data transfers. + +EBUSY + Returned by SMBus adapters when the bus was busy for longer + than allowed. This usually indicates some device (maybe the + SMBus adapter) needs some fault recovery (such as resetting), + or that the reset was attempted but failed. + +EINVAL + This rather vague error means an invalid parameter has been + detected before any I/O operation was started. Use a more + specific fault code when you can. + +EIO + This rather vague error means something went wrong when + performing an I/O operation. Use a more specific fault + code when you can. + +ENODEV + Returned by driver probe() methods. This is a bit more + specific than ENXIO, implying the problem isn't with the + address, but with the device found there. Driver probes + may verify the device returns *correct* responses, and + return this as appropriate. (The driver core will warn + about probe faults other than ENXIO and ENODEV.) + +ENOMEM + Returned by any component that can't allocate memory when + it needs to do so. + +ENXIO + Returned by I2C adapters to indicate that the address phase + of a transfer didn't get an ACK. While it might just mean + an I2C device was temporarily not responding, usually it + means there's nothing listening at that address. + + Returned by driver probe() methods to indicate that they + found no device to bind to. (ENODEV may also be used.) + +EOPNOTSUPP + Returned by an adapter when asked to perform an operation + that it doesn't, or can't, support. + + For example, this would be returned when an adapter that + doesn't support SMBus block transfers is asked to execute + one. In that case, the driver making that request should + have verified that functionality was supported before it + made that block transfer request. + + Similarly, if an I2C adapter can't execute all legal I2C + messages, it should return this when asked to perform a + transaction it can't. (These limitations can't be seen in + the adapter's functionality mask, since the assumption is + that if an adapter supports I2C it supports all of I2C.) + +EPROTO + Returned when slave does not conform to the relevant I2C + or SMBus (or chip-specific) protocol specifications. One + case is when the length of an SMBus block data response + (from the SMBus slave) is outside the range 1-32 bytes. + +ETIMEDOUT + This is returned by drivers when an operation took too much + time, and was aborted before it completed. + + SMBus adapters may return it when an operation took more + time than allowed by the SMBus specification; for example, + when a slave stretches clocks too far. I2C has no such + timeouts, but it's normal for I2C adapters to impose some + arbitrary limits (much longer than SMBus!) too. + diff --git a/Documentation/i2c/functionality b/Documentation/i2c/functionality index 60cca249e45..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,31 +46,46 @@ 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. -ALGORITHM/ADAPTER IMPLEMENTATION --------------------------------- -When you write a new algorithm driver, you will have to implement a -function callback `functionality', that gets an i2c_adapter structure -pointer as its only parameter: +ADAPTER IMPLEMENTATION +---------------------- - struct i2c_algorithm { - /* Many other things of course; check <linux/i2c.h>! */ - u32 (*functionality) (struct i2c_adapter *); +When you write a new adapter driver, you will have to implement a +function callback `functionality'. Typical implementations are given +below. + +A typical SMBus-only adapter would list all the SMBus transactions it +supports. This example comes from the i2c-piix4 driver: + + static u32 piix4_func(struct i2c_adapter *adapter) + { + return I2C_FUNC_SMBUS_QUICK | I2C_FUNC_SMBUS_BYTE | + I2C_FUNC_SMBUS_BYTE_DATA | I2C_FUNC_SMBUS_WORD_DATA | + I2C_FUNC_SMBUS_BLOCK_DATA; } -A typically implementation is given below, from i2c-algo-bit.c: +A typical full-I2C adapter would use the following (from the i2c-pxa +driver): - static u32 bit_func(struct i2c_adapter *adap) + static u32 i2c_pxa_functionality(struct i2c_adapter *adap) { - return I2C_FUNC_SMBUS_EMUL | I2C_FUNC_10BIT_ADDR | - I2C_FUNC_PROTOCOL_MANGLING; + return I2C_FUNC_I2C | I2C_FUNC_SMBUS_EMUL; } +I2C_FUNC_SMBUS_EMUL includes all the SMBus transactions (with the +addition of I2C block transactions) which i2c-core can emulate using +I2C_FUNC_I2C without any help from the adapter driver. The idea is +to let the client drivers check for the support of SMBus functions +without having to care whether the said functions are implemented in +hardware by the adapter, or emulated in software by i2c-core on top +of an I2C adapter. CLIENT CHECKING @@ -78,36 +93,33 @@ CLIENT CHECKING Before a client tries to attach to an adapter, or even do tests to check whether one of the devices it supports is present on an adapter, it should -check whether the needed functionality is present. There are two functions -defined which should be used instead of calling the functionality hook -in the algorithm structure directly: - - /* Return the functionality mask */ - extern u32 i2c_get_functionality (struct i2c_adapter *adap); - - /* Return 1 if adapter supports everything we need, 0 if not. */ - extern int i2c_check_functionality (struct i2c_adapter *adap, u32 func); +check whether the needed functionality is present. The typical way to do +this is (from the lm75 driver): -This is a typical way to use these functions (from the writing-clients -document): - int foo_detect_client(struct i2c_adapter *adapter, int address, - unsigned short flags, int kind) + static int lm75_detect(...) { - /* Define needed variables */ - - /* As the very first action, we check whether the adapter has the - needed functionality: we need the SMBus read_word_data, - write_word_data and write_byte functions in this example. */ - if (!i2c_check_functionality(adapter,I2C_FUNC_SMBUS_WORD_DATA | - I2C_FUNC_SMBUS_WRITE_BYTE)) - goto ERROR0; - - /* Now we can do the real detection */ - - ERROR0: - /* Return an error */ + (...) + if (!i2c_check_functionality(adapter, I2C_FUNC_SMBUS_BYTE_DATA | + I2C_FUNC_SMBUS_WORD_DATA)) + goto exit; + (...) } +Here, the lm75 driver checks if the adapter can do both SMBus byte data +and SMBus word data transactions. If not, then the driver won't work on +this adapter and there's no point in going on. If the check above is +successful, then the driver knows that it can call the following +functions: i2c_smbus_read_byte_data(), i2c_smbus_write_byte_data(), +i2c_smbus_read_word_data() and i2c_smbus_write_word_data(). As a rule of +thumb, the functionality constants you test for with +i2c_check_functionality() should match exactly the i2c_smbus_* functions +which you driver is calling. + +Note that the check above doesn't tell whether the functionalities are +implemented in hardware by the underlying adapter or emulated in +software by i2c-core. Client drivers don't have to care about this, as +i2c-core will transparently implement SMBus transactions on top of I2C +adapters. CHECKING THROUGH /DEV @@ -116,19 +128,19 @@ CHECKING THROUGH /DEV If you try to access an adapter from a userspace program, you will have to use the /dev interface. You will still have to check whether the functionality you need is supported, of course. This is done using -the I2C_FUNCS ioctl. An example, adapted from the lm_sensors i2cdetect -program, is below: +the I2C_FUNCS ioctl. An example, adapted from the i2cdetect program, is +below: int file; - if (file = open("/dev/i2c-0",O_RDWR) < 0) { + if (file = open("/dev/i2c-0", O_RDWR) < 0) { /* Some kind of error handling */ exit(1); } - if (ioctl(file,I2C_FUNCS,&funcs) < 0) { + if (ioctl(file, I2C_FUNCS, &funcs) < 0) { /* Some kind of error handling */ exit(1); } - if (! (funcs & I2C_FUNC_SMBUS_QUICK)) { + if (!(funcs & I2C_FUNC_SMBUS_QUICK)) { /* Oops, the needed functionality (SMBus write_quick function) is not available! */ exit(1); diff --git a/Documentation/i2c/i2c-protocol b/Documentation/i2c/i2c-protocol index b4022c91421..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 d6dcb138abf..fa4b669c166 100644 --- a/Documentation/i2c/i2c-stub +++ b/Documentation/i2c/i2c-stub @@ -2,14 +2,18 @@ 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. No hardware is needed nor associated with this module. It will accept write -quick commands to all addresses; it will respond to the other commands (also -to all addresses) by reading from or writing to an array in memory. It will -also spam the kernel logs for every command it handles. +quick commands to the specified addresses; it will respond to the other +commands (also to the specified addresses) by reading from or writing to +arrays in memory. It will also spam the kernel logs for every command it +handles. A pointer register with auto-increment is implemented for all byte operations. This allows for continuous byte reads like those supported by @@ -17,14 +21,25 @@ 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 -CAVEATS: +There's a script named i2c-stub-from-dump in the i2c-tools package which +can load register values automatically from a chip dump. + +PARAMETERS: -There are independent arrays for byte/data and word/data commands. Depending -on if/how a target driver mixes them, you'll need to be careful. +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 stub could lock it up. Use i2cset to unlock it. 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/porting-clients b/Documentation/i2c/porting-clients deleted file mode 100644 index 184fac2377a..00000000000 --- a/Documentation/i2c/porting-clients +++ /dev/null @@ -1,140 +0,0 @@ -Revision 5, 2005-07-29 -Jean Delvare <khali@linux-fr.org> -Greg KH <greg@kroah.com> - -This is a guide on how to convert I2C chip drivers from Linux 2.4 to -Linux 2.6. I have been using existing drivers (lm75, lm78) as examples. -Then I converted a driver myself (lm83) and updated this document. - -There are two sets of points below. The first set concerns technical -changes. The second set concerns coding policy. Both are mandatory. - -Although reading this guide will help you porting drivers, I suggest -you keep an eye on an already ported driver while porting your own -driver. This will help you a lot understanding what this guide -exactly means. Choose the chip driver that is the more similar to -yours for best results. - -Technical changes: - -* [Includes] Get rid of "version.h" and <linux/i2c-proc.h>. - Includes typically look like that: - #include <linux/module.h> - #include <linux/init.h> - #include <linux/slab.h> - #include <linux/i2c.h> - #include <linux/hwmon.h> /* for hardware monitoring drivers */ - #include <linux/hwmon-sysfs.h> - #include <linux/hwmon-vid.h> /* if you need VRM support */ - #include <asm/io.h> /* if you have I/O operations */ - Please respect this inclusion order. Some extra headers may be - required for a given driver (e.g. "lm75.h"). - -* [Addresses] SENSORS_I2C_END becomes I2C_CLIENT_END, ISA addresses - are no more handled by the i2c core. - SENSORS_INSMOD_<n> becomes I2C_CLIENT_INSMOD_<n>. - -* [Client data] Get rid of sysctl_id. Try using standard names for - register values (for example, temp_os becomes temp_max). You're - still relatively free here, but you *have* to follow the standard - names for sysfs files (see the Sysctl section below). - -* [Function prototypes] The detect functions loses its flags - parameter. Sysctl (e.g. lm75_temp) and miscellaneous functions - are off the list of prototypes. This usually leaves five - prototypes: - static int lm75_attach_adapter(struct i2c_adapter *adapter); - static int lm75_detect(struct i2c_adapter *adapter, int address, - int kind); - static void lm75_init_client(struct i2c_client *client); - static int lm75_detach_client(struct i2c_client *client); - static void lm75_update_client(struct i2c_client *client); - -* [Sysctl] All sysctl stuff is of course gone (defines, ctl_table - and functions). Instead, you have to define show and set functions for - each sysfs file. Only define set for writable values. Take a look at an - existing 2.6 driver for details (lm78 for example). Don't forget - to define the attributes for each file (this is that step that - links callback functions). Use the file names specified in - Documentation/i2c/sysfs-interface for the individual files. Also - convert the units these files read and write to the specified ones. - If you need to add a new type of file, please discuss it on the - sensors mailing list <lm-sensors@lm-sensors.org> by providing a - patch to the Documentation/i2c/sysfs-interface file. - -* [Attach] For I2C drivers, the attach function should make sure - that the adapter's class has I2C_CLASS_HWMON, using the - following construct: - if (!(adapter->class & I2C_CLASS_HWMON)) - return 0; - ISA-only drivers of course don't need this. - Call i2c_probe() instead of i2c_detect(). - -* [Detect] As mentioned earlier, the flags parameter is gone. - The type_name and client_name strings are replaced by a single - name string, which will be filled with a lowercase, short string - (typically the driver name, e.g. "lm75"). - In i2c-only drivers, drop the i2c_is_isa_adapter check, it's - useless. Same for isa-only drivers, as the test would always be - true. Only hybrid drivers (which are quite rare) still need it. - The errorN labels are reduced to the number needed. If that number - is 2 (i2c-only drivers), it is advised that the labels are named - exit and exit_free. For i2c+isa drivers, labels should be named - ERROR0, ERROR1 and ERROR2. Don't forget to properly set err before - jumping to error labels. By the way, labels should be left-aligned. - Use kzalloc instead of kmalloc. - Use i2c_set_clientdata to set the client data (as opposed to - a direct access to client->data). - Use strlcpy instead of strcpy to copy the client name. - Replace the sysctl directory registration by calls to - device_create_file. Move the driver initialization before any - sysfs file creation. - Drop client->id. - Drop any 24RF08 corruption prevention you find, as this is now done - at the i2c-core level, and doing it twice voids it. - -* [Init] Limits must not be set by the driver (can be done later in - user-space). Chip should not be reset default (although a module - parameter may be used to force is), and initialization should be - limited to the strictly necessary steps. - -* [Detach] Get rid of data, remove the call to - i2c_deregister_entry. Do not log an error message if - i2c_detach_client fails, as i2c-core will now do it for you. - -* [Update] Don't access client->data directly, use - i2c_get_clientdata(client) instead. - -* [Interface] Init function should not print anything. Make sure - there is a MODULE_LICENSE() line, at the bottom of the file - (after MODULE_AUTHOR() and MODULE_DESCRIPTION(), in this order). - -Coding policy: - -* [Copyright] Use (C), not (c), for copyright. - -* [Debug/log] Get rid of #ifdef DEBUG/#endif constructs whenever you - can. Calls to printk/pr_debug for debugging purposes are replaced - by calls to dev_dbg. Here is an example on how to call it (taken - from lm75_detect): - dev_dbg(&client->dev, "Starting lm75 update\n"); - Replace other printk calls with the dev_info, dev_err or dev_warn - function, as appropriate. - -* [Constants] Constants defines (registers, conversions, initial - values) should be aligned. This greatly improves readability. - Same goes for variables declarations. Alignments are achieved by the - means of tabs, not spaces. Remember that tabs are set to 8 in the - Linux kernel code. - -* [Structure definition] The name field should be standardized. All - lowercase and as simple as the driver name itself (e.g. "lm75"). - -* [Layout] Avoid extra empty lines between comments and what they - comment. Respect the coding style (see Documentation/CodingStyle), - in particular when it comes to placing curly braces. - -* [Comments] Make sure that no comment refers to a file that isn't - part of the Linux source tree (typically doc/chips/<chip name>), - and that remaining comments still match the code. Merging comment - lines when possible is encouraged. diff --git a/Documentation/i2c/smbus-protocol b/Documentation/i2c/smbus-protocol index 09f5e5ca492..6012b12b351 100644 --- a/Documentation/i2c/smbus-protocol +++ b/Documentation/i2c/smbus-protocol @@ -1,5 +1,6 @@ SMBus Protocol Summary ====================== + The following is a summary of the SMBus protocol. It applies to all revisions of the protocol (1.0, 1.1, and 2.0). Certain protocol features which are not supported by @@ -8,6 +9,7 @@ this package are briefly described at the end of this document. Some adapters understand only the SMBus (System Management Bus) protocol, which is a subset from the I2C protocol. Fortunately, many devices use only the same subset, which makes it possible to put them on an SMBus. + If you write a driver for some I2C device, please try to use the SMBus commands if at all possible (if the device uses only that subset of the I2C protocol). This makes it possible to use the device driver on both @@ -15,7 +17,18 @@ SMBus adapters and I2C adapters (the SMBus command set is automatically translated to I2C on I2C adapters, but plain I2C commands can not be handled at all on most pure SMBus adapters). -Below is a list of SMBus commands. +Below is a list of SMBus protocol operations, and the functions executing +them. Note that the names used in the SMBus protocol specifications usually +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 ============== @@ -35,17 +48,18 @@ Count (8 bits): A data byte containing the length of a block operation. [..]: Data sent by I2C device, as opposed to data sent by the host adapter. -SMBus Write Quick -================= +SMBus Quick Command +=================== This sends a single bit to the device, at the place of the Rd/Wr bit. -There is no equivalent Read Quick command. A Addr Rd/Wr [A] P +Functionality flag: I2C_FUNC_SMBUS_QUICK -SMBus Read Byte -=============== + +SMBus Receive Byte: i2c_smbus_read_byte() +========================================== This reads a single byte from a device, without specifying a device register. Some devices are so simple that this interface is enough; for @@ -54,57 +68,77 @@ the previous SMBus command. S Addr Rd [A] [Data] NA P +Functionality flag: I2C_FUNC_SMBUS_READ_BYTE + -SMBus Write Byte -================ +SMBus Send Byte: i2c_smbus_write_byte() +======================================== -This is the reverse of Read Byte: it sends a single byte to a device. -See Read Byte for more information. +This operation is the reverse of Receive Byte: it sends a single byte +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 Data -==================== + +SMBus Read Byte: i2c_smbus_read_byte_data() +============================================ This reads a single byte from a device, from a designated register. 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 Data -==================== +SMBus Read Word: i2c_smbus_read_word_data() +============================================ -This command is very like Read Byte Data; again, data is read from a +This operation is very like Read Byte; again, data is read from a device, from a designated register that is specified through the Comm 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 -SMBus Write Byte 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() +============================================== This writes a single byte to a device, to a designated register. The register is specified through the Comm byte. This is the opposite of -the Read Byte Data command. +the Read Byte operation. S Addr Wr [A] Comm [A] Data [A] P +Functionality flag: I2C_FUNC_SMBUS_WRITE_BYTE_DATA + -SMBus Write Word Data -===================== +SMBus Write Word: i2c_smbus_write_word_data() +============================================== -This is the opposite operation of the Read Word Data command. 16 bits -of data is read from a device, from a designated register that is +This is the opposite of the Read Word operation. 16 bits +of data is written to a device, to the designated register that is 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 -================== +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. @@ -112,9 +146,11 @@ 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 -================ + +SMBus Block Read: i2c_smbus_read_block_data() +============================================== This command reads a block of up to 32 bytes from a device, from a designated register that is specified through the Comm byte. The amount @@ -123,9 +159,11 @@ 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 -================= + +SMBus Block Write: i2c_smbus_write_block_data() +================================================ The opposite of the Block Read command, this writes up to 32 bytes to a device, to a designated register that is specified through the @@ -133,11 +171,14 @@ 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 Process Call -======================== +SMBus Block Write - Block Read Process Call +=========================================== -SMBus Block Process Call was introduced in Revision 2.0 of the specification. +SMBus Block Write - Block Read Process Call was introduced in +Revision 2.0 of the specification. This command selects a device register (through the Comm byte), sends 1 to 31 bytes of data to it, and reads 1 to 31 bytes of data in return. @@ -145,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 ================= @@ -159,13 +202,16 @@ alerting device's address. Packet Error Checking (PEC) =========================== + Packet Error Checking was introduced in Revision 1.1 of the specification. -PEC adds a CRC-8 error-checking byte to all transfers. +PEC adds a CRC-8 error-checking byte to transfers using it, immediately +before the terminating STOP. Address Resolution Protocol (ARP) ================================= + The Address Resolution Protocol was introduced in Revision 2.0 of the specification. It is a higher-layer protocol which uses the messages above. @@ -175,16 +221,35 @@ 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 ====================== + The following I2C block transactions are supported by the SMBus layer and are described here for completeness. +They are *NOT* defined by the SMBus specification. + I2C block transactions do not limit the number of bytes transferred but the SMBus layer places a limit of 32 bytes. -I2C Block Read -============== +I2C Block Read: i2c_smbus_read_i2c_block_data() +================================================ This command reads a block of bytes from a device, from a designated register that is specified through the Comm byte. @@ -192,19 +257,11 @@ 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 Block Write: i2c_smbus_write_i2c_block_data() +================================================== The opposite of the Block Read command, this writes bytes to a device, to a designated register that is specified through the @@ -213,4 +270,4 @@ 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/summary b/Documentation/i2c/summary index 41dde877679..13ab076dcd9 100644 --- a/Documentation/i2c/summary +++ b/Documentation/i2c/summary @@ -1,20 +1,24 @@ -This is an explanation of what i2c is, and what is supported in this package. - I2C and SMBus ============= I2C (pronounce: I squared C) is a protocol developed by Philips. It is a -slow two-wire protocol (10-400 kHz), but it suffices for many types of -devices. +slow two-wire protocol (variable speed, up to 400 kHz), with a high speed +extension (3.4 MHz). It provides an inexpensive bus for connecting many +types of devices with infrequent or low bandwidth communications needs. +I2C is widely used with embedded systems. Some systems use variants that +don't meet branding requirements, and so are not advertised as being I2C. -SMBus (System Management Bus) is a subset of the I2C protocol. Many -modern mainboards have a System Management Bus. There are a lot of -devices which can be connected to a SMBus; the most notable are modern -memory chips with EEPROM memories and chips for hardware monitoring. +SMBus (System Management Bus) is based on the I2C protocol, and is mostly +a subset of I2C protocols and signaling. Many I2C devices will work on an +SMBus, but some SMBus protocols add semantics beyond what is required to +achieve I2C branding. Modern PC mainboards rely on SMBus. The most common +devices connected through SMBus are RAM modules configured using I2C EEPROMs, +and hardware monitoring chips. -Because the SMBus is just a special case of the generalized I2C bus, we -can simulate the SMBus protocol on plain I2C busses. The reverse is -regretfully impossible. +Because the SMBus is mostly a subset of the generalized I2C bus, we can +use its protocols on many I2C systems. However, there are systems that don't +meet both SMBus and I2C electrical constraints; and others which can't +implement all the common SMBus protocol semantics or messages. Terminology @@ -27,49 +31,17 @@ When we talk about I2C, we use the following terms: Client An Algorithm driver contains general code that can be used for a whole class -of I2C adapters. Each specific adapter driver depends on one algorithm -driver. +of I2C adapters. Each specific adapter driver either depends on one algorithm +driver, or includes its own implementation. + A Driver driver (yes, this sounds ridiculous, sorry) contains the general code to access some type of device. Each detected device gets its own data in the Client structure. Usually, Driver and Client are more closely integrated than Algorithm and Adapter. -For a given configuration, you will need a driver for your I2C bus (usually -a separate Adapter and Algorithm driver), and drivers for your I2C devices -(usually one driver for each device). There are no I2C device drivers -in this package. See the lm_sensors project http://www.lm-sensors.nu -for device drivers. - - -Included Bus Drivers -==================== -Note that only stable drivers are patched into the kernel by 'mkpatch'. - - -Base modules ------------- - -i2c-core: The basic I2C code, including the /proc/bus/i2c* interface -i2c-dev: The /dev/i2c-* interface -i2c-proc: The /proc/sys/dev/sensors interface for device (client) drivers - -Algorithm drivers ------------------ - -i2c-algo-8xx: An algorithm for CPM's I2C device in Motorola 8xx processors (NOT BUILT BY DEFAULT) -i2c-algo-bit: A bit-banging algorithm -i2c-algo-pcf: A PCF 8584 style algorithm -i2c-algo-ibm_ocp: An algorithm for the I2C device in IBM 4xx processors (NOT BUILT BY DEFAULT) - -Adapter drivers ---------------- - -i2c-elektor: Elektor ISA card (uses i2c-algo-pcf) -i2c-elv: ELV parallel port adapter (uses i2c-algo-bit) -i2c-pcf-epp: PCF8584 on a EPP parallel port (uses i2c-algo-pcf) (NOT mkpatched) -i2c-philips-par: Philips style parallel port adapter (uses i2c-algo-bit) -i2c-adap-ibm_ocp: IBM 4xx processor I2C device (uses i2c-algo-ibm_ocp) (NOT BUILT BY DEFAULT) -i2c-pport: Primitive parallel port adapter (uses i2c-algo-bit) -i2c-rpx: RPX board Motorola 8xx I2C device (uses i2c-algo-8xx) (NOT BUILT BY DEFAULT) -i2c-velleman: Velleman K8000 parallel port adapter (uses i2c-algo-bit) +For a given configuration, you will need a driver for your I2C bus, and +drivers for your I2C devices (usually one driver for each device). +At this time, Linux only operates I2C (or SMBus) in master mode; you can't +use these APIs to make a Linux system behave as a slave/device, either to +speak a custom protocol or to emulate some other device. 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 new file mode 100644 index 00000000000..8e5fbd88c7d --- /dev/null +++ b/Documentation/i2c/upgrading-clients @@ -0,0 +1,281 @@ +Upgrading I2C Drivers to the new 2.6 Driver Model +================================================= + +Ben Dooks <ben-linux@fluff.org> + +Introduction +------------ + +This guide outlines how to alter existing Linux 2.6 client drivers from +the old to the new new binding methods. + + +Example old-style driver +------------------------ + + +struct example_state { + struct i2c_client client; + .... +}; + +static struct i2c_driver example_driver; + +static unsigned short ignore[] = { I2C_CLIENT_END }; +static unsigned short normal_addr[] = { OUR_ADDR, I2C_CLIENT_END }; + +I2C_CLIENT_INSMOD; + +static int example_attach(struct i2c_adapter *adap, int addr, int kind) +{ + struct example_state *state; + struct device *dev = &adap->dev; /* to use for dev_ reports */ + int ret; + + state = kzalloc(sizeof(struct example_state), GFP_KERNEL); + if (state == NULL) { + dev_err(dev, "failed to create our state\n"); + return -ENOMEM; + } + + example->client.addr = addr; + example->client.flags = 0; + example->client.adapter = adap; + + i2c_set_clientdata(&state->i2c_client, state); + strlcpy(client->i2c_client.name, "example", I2C_NAME_SIZE); + + ret = i2c_attach_client(&state->i2c_client); + if (ret < 0) { + dev_err(dev, "failed to attach client\n"); + kfree(state); + return ret; + } + + dev = &state->i2c_client.dev; + + /* rest of the initialisation goes here. */ + + dev_info(dev, "example client created\n"); + + return 0; +} + +static int example_detach(struct i2c_client *client) +{ + struct example_state *state = i2c_get_clientdata(client); + + i2c_detach_client(client); + kfree(state); + return 0; +} + +static int example_attach_adapter(struct i2c_adapter *adap) +{ + return i2c_probe(adap, &addr_data, example_attach); +} + +static struct i2c_driver example_driver = { + .driver = { + .owner = THIS_MODULE, + .name = "example", + }, + .attach_adapter = example_attach_adapter, + .detach_client = example_detach, + .suspend = example_suspend, + .resume = example_resume, +}; + + +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_client methods can be removed, along with the addr_data, +as follows: + +- static struct i2c_driver example_driver; + +- static unsigned short ignore[] = { I2C_CLIENT_END }; +- static unsigned short normal_addr[] = { OUR_ADDR, I2C_CLIENT_END }; + +- I2C_CLIENT_INSMOD; + +- static int example_attach_adapter(struct i2c_adapter *adap) +- { +- return i2c_probe(adap, &addr_data, example_attach); +- } + + static struct i2c_driver example_driver = { +- .attach_adapter = example_attach_adapter, +- .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 = example_remove, + } + +Change the example_attach method to accept the new parameters +which include the i2c_client that it will be working with: + +- static int example_attach(struct i2c_adapter *adap, int addr, int kind) ++ static int example_probe(struct i2c_client *client, ++ const struct i2c_device_id *id) + +Change the name of example_attach to example_probe to align it with the +i2c_driver entry names. The rest of the probe routine will now need to be +changed as the i2c_client has already been setup for use. + +The necessary client fields have already been setup before +the probe function is called, so the following client setup +can be removed: + +- example->client.addr = addr; +- example->client.flags = 0; +- example->client.adapter = adap; +- +- strlcpy(client->i2c_client.name, "example", I2C_NAME_SIZE); + +The i2c_set_clientdata is now: + +- i2c_set_clientdata(&state->client, state); ++ i2c_set_clientdata(client, state); + +The call to i2c_attach_client is no longer needed, if the probe +routine exits successfully, then the driver will be automatically +attached by the core. Change the probe routine as so: + +- ret = i2c_attach_client(&state->i2c_client); +- if (ret < 0) { +- dev_err(dev, "failed to attach client\n"); +- kfree(state); +- return ret; +- } + + +Remove the storage of 'struct i2c_client' from the 'struct example_state' +as we are provided with the i2c_client in our example_probe. Instead we +store a pointer to it for when it is needed. + +struct example_state { +- struct i2c_client client; ++ struct i2c_client *client; + +the new i2c client as so: + +- struct device *dev = &adap->dev; /* to use for dev_ reports */ ++ struct device *dev = &i2c_client->dev; /* to use for dev_ reports */ + +And remove the change after our client is attached, as the driver no +longer needs to register a new client structure with the core: + +- dev = &state->i2c_client.dev; + +In the probe routine, ensure that the new state has the client stored +in it: + +static int example_probe(struct i2c_client *i2c_client, + const struct i2c_device_id *id) +{ + struct example_state *state; + struct device *dev = &i2c_client->dev; + int ret; + + state = kzalloc(sizeof(struct example_state), GFP_KERNEL); + if (state == NULL) { + dev_err(dev, "failed to create our state\n"); + return -ENOMEM; + } + ++ state->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 needed for any +of the core functions. + +- static int example_detach(struct i2c_client *client) ++ static int example_remove(struct i2c_client *client) +{ + struct example_state *state = i2c_get_clientdata(client); + +- i2c_detach_client(client); + +And finally ensure that we have the correct ID table for the i2c-core +and other utilities: + ++ struct i2c_device_id example_idtable[] = { ++ { "example", 0 }, ++ { } ++}; ++ ++MODULE_DEVICE_TABLE(i2c, example_idtable); + +static struct i2c_driver example_driver = { + .driver = { + .owner = THIS_MODULE, + .name = "example", + }, ++ .id_table = example_ids, + + +Our driver should now look like this: + +struct example_state { + struct i2c_client *client; + .... +}; + +static int example_probe(struct i2c_client *client, + const struct i2c_device_id *id) +{ + struct example_state *state; + struct device *dev = &client->dev; + + state = kzalloc(sizeof(struct example_state), GFP_KERNEL); + if (state == NULL) { + dev_err(dev, "failed to create our state\n"); + return -ENOMEM; + } + + state->client = client; + i2c_set_clientdata(client, state); + + /* rest of the initialisation goes here. */ + + dev_info(dev, "example client created\n"); + + return 0; +} + +static int example_remove(struct i2c_client *client) +{ + struct example_state *state = i2c_get_clientdata(client); + + kfree(state); + return 0; +} + +static struct i2c_device_id example_idtable[] = { + { "example", 0 }, + { } +}; + +MODULE_DEVICE_TABLE(i2c, example_idtable); + +static struct i2c_driver example_driver = { + .driver = { + .owner = THIS_MODULE, + .name = "example", + }, + .id_table = example_idtable, + .probe = example_probe, + .remove = example_remove, + .suspend = example_suspend, + .resume = example_resume, +}; diff --git a/Documentation/i2c/writing-clients b/Documentation/i2c/writing-clients index cff7b652588..6b344b516bf 100644 --- a/Documentation/i2c/writing-clients +++ b/Documentation/i2c/writing-clients @@ -1,5 +1,5 @@ This is a small guide for those who want to write kernel drivers for I2C -or SMBus devices. +or SMBus devices, using Linux as the protocol host/master (not slave). To set up a driver, you need to do several things. Some are optional, and some things can be done slightly or completely different. Use this as a @@ -10,68 +10,74 @@ General remarks =============== Try to keep the kernel namespace as clean as possible. The best way to -do this is to use a unique prefix for all global symbols. This is +do this is to use a unique prefix for all global symbols. This is especially important for exported symbols, but it is a good idea to do it for non-exported symbols too. We will use the prefix `foo_' in this -tutorial, and `FOO_' for preprocessor variables. +tutorial. The driver structure ==================== Usually, you will implement a single driver structure, and instantiate -all clients from it. Remember, a driver structure contains general access -routines, a client structure specific information like the actual I2C -address. +all clients from it. Remember, a driver structure contains general access +routines, and should be zero-initialized except for fields with data you +provide. A client structure holds device-specific information like the +driver model device node, and its I2C address. + +static struct i2c_device_id foo_idtable[] = { + { "foo", my_id_for_foo }, + { "bar", my_id_for_bar }, + { } +}; + +MODULE_DEVICE_TABLE(i2c, foo_idtable); static struct i2c_driver foo_driver = { - .owner = THIS_MODULE, - .name = "Foo version 2.3 driver", - .flags = I2C_DF_NOTIFY, - .attach_adapter = &foo_attach_adapter, - .detach_client = &foo_detach_client, - .command = &foo_command /* may be NULL */ + .driver = { + .name = "foo", + }, + + .id_table = foo_idtable, + .probe = foo_probe, + .remove = foo_remove, + /* if device autodetection is needed: */ + .class = I2C_CLASS_SOMETHING, + .detect = foo_detect, + .address_list = normal_i2c, + + .shutdown = foo_shutdown, /* optional */ + .suspend = foo_suspend, /* optional */ + .resume = foo_resume, /* optional */ + .command = foo_command, /* optional, deprecated */ } - -The name field must match the driver name, including the case. It must not -contain spaces, and may be up to 31 characters long. -Don't worry about the flags field; just put I2C_DF_NOTIFY into it. This -means that your driver will be notified when new adapters are found. -This is almost always what you want. +The name field is the driver name, and must not contain spaces. It +should match the module name (if the driver can be compiled as a module), +although you can use MODULE_ALIAS (passing "foo" in this example) to add +another name for the module. If the driver name doesn't match the module +name, the module won't be automatically loaded (hotplug/coldplug). -All other fields are for call-back functions which will be explained +All other fields are for call-back functions which will be explained below. Extra client data ================= -The client structure has a special `data' field that can point to any -structure at all. You can use this to keep client-specific data. You -do not always need this, but especially for `sensors' drivers, it can -be very useful. - -An example structure is below. - - struct foo_data { - struct i2c_client client; - struct semaphore lock; /* For ISA access in `sensors' drivers. */ - int sysctl_id; /* To keep the /proc directory entry for - `sensors' drivers. */ - enum chips type; /* To keep the chips type for `sensors' drivers. */ - - /* Because the i2c bus is slow, it is often useful to cache the read - information of a chip for some time (for example, 1 or 2 seconds). - It depends of course on the device whether this is really worthwhile - or even sensible. */ - struct semaphore update_lock; /* When we are reading lots of information, - another process should not update the - below information */ - char valid; /* != 0 if the following fields are valid. */ - unsigned long last_updated; /* In jiffies */ - /* Add the read information here too */ - }; +Each client structure has a special `data' field that can point to any +structure at all. You should use this to keep device-specific data. + + /* store the value */ + void i2c_set_clientdata(struct i2c_client *client, void *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 @@ -79,460 +85,257 @@ Accessing the client Let's say we have a valid client structure. At some time, we will need to gather information from the client, or write new information to the -client. How we will export this information to user-space is less -important at this moment (perhaps we do not need to do this at all for -some obscure clients). But we need generic reading and writing routines. +client. -I have found it useful to define foo_read and foo_write function for this. +I have found it useful to define foo_read and foo_write functions for this. For some cases, it will be easier to call the i2c functions directly, but many chips have some kind of register-value idea that can easily -be encapsulated. Also, some chips have both ISA and I2C interfaces, and -it useful to abstract from this (only for `sensors' drivers). +be encapsulated. The below functions are simple examples, and should not be copied literally. - int foo_read_value(struct i2c_client *client, u8 reg) - { - if (reg < 0x10) /* byte-sized register */ - return i2c_smbus_read_byte_data(client,reg); - else /* word-sized register */ - return i2c_smbus_read_word_data(client,reg); - } - - int foo_write_value(struct i2c_client *client, u8 reg, u16 value) - { - if (reg == 0x10) /* Impossible to write - driver error! */ { - return -1; - else if (reg < 0x10) /* byte-sized register */ - return i2c_smbus_write_byte_data(client,reg,value); - else /* word-sized register */ - return i2c_smbus_write_word_data(client,reg,value); - } - -For sensors code, you may have to cope with ISA registers too. Something -like the below often works. Note the locking! - - int foo_read_value(struct i2c_client *client, u8 reg) - { - int res; - if (i2c_is_isa_client(client)) { - down(&(((struct foo_data *) (client->data)) -> lock)); - outb_p(reg,client->addr + FOO_ADDR_REG_OFFSET); - res = inb_p(client->addr + FOO_DATA_REG_OFFSET); - up(&(((struct foo_data *) (client->data)) -> lock)); - return res; - } else - return i2c_smbus_read_byte_data(client,reg); - } - -Writing is done the same way. +int foo_read_value(struct i2c_client *client, u8 reg) +{ + if (reg < 0x10) /* byte-sized register */ + return i2c_smbus_read_byte_data(client, reg); + else /* word-sized register */ + return i2c_smbus_read_word_data(client, reg); +} + +int foo_write_value(struct i2c_client *client, u8 reg, u16 value) +{ + if (reg == 0x10) /* Impossible to write - driver error! */ + return -EINVAL; + else if (reg < 0x10) /* byte-sized register */ + return i2c_smbus_write_byte_data(client, reg, value); + else /* word-sized register */ + return i2c_smbus_write_word_data(client, reg, value); +} Probing and attaching ===================== -Most i2c devices can be present on several i2c addresses; for some this -is determined in hardware (by soldering some chip pins to Vcc or Ground), -for others this can be changed in software (by writing to specific client -registers). Some devices are usually on a specific address, but not always; -and some are even more tricky. So you will probably need to scan several -i2c addresses for your clients, and do some sort of detection to see -whether it is actually a device supported by your driver. +The Linux I2C stack was originally written to support access to hardware +monitoring chips on PC motherboards, and thus used to embed some assumptions +that were more appropriate to SMBus (and PCs) than to I2C. One of these +assumptions was that most adapters and devices drivers support the SMBUS_QUICK +protocol to probe device presence. Another was that devices and their drivers +can be sufficiently configured using only such probe primitives. + +As Linux and its I2C stack became more widely used in embedded systems +and complex components such as DVB adapters, those assumptions became more +problematic. Drivers for I2C devices that issue interrupts need more (and +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. + + +Device/Driver Binding +--------------------- -To give the user a maximum of possibilities, some default module parameters -are defined to help determine what addresses are scanned. Several macros -are defined in i2c.h to help you support them, as well as a generic -detection algorithm. +System infrastructure, typically board-specific initialization code or +boot firmware, reports what I2C devices exist. For example, there may be +a table, in the kernel or from the boot loader, identifying I2C devices +and linking them to board-specific configuration information about IRQs +and other wiring artifacts, chip type, and so on. That could be used to +create i2c_client objects for each I2C device. -You do not have to use this parameter interface; but don't try to use -function i2c_probe() if you don't. +I2C device drivers using this binding model work just like any other +kind of driver in Linux: they provide a probe() method to bind to +those devices, and a remove() method to unbind. -NOTE: If you want to write a `sensors' driver, the interface is slightly - different! See below. + static int foo_probe(struct i2c_client *client, + const struct i2c_device_id *id); + static int foo_remove(struct i2c_client *client); +Remember that the i2c_driver does not create those client handles. The +handle may be used during foo_probe(). If foo_probe() reports success +(zero not a negative status code) it may save the handle and use it until +foo_remove() returns. That binding model is used by most Linux drivers. +The probe function is called when an entry in the id_table name field +matches the device's name. It is passed the entry that was matched so +the driver knows which one in the table matched. -Probing classes + +Device Creation --------------- -All parameters are given as lists of unsigned 16-bit integers. Lists are -terminated by I2C_CLIENT_END. -The following lists are used internally: - - normal_i2c: filled in by the module writer. - A list of I2C addresses which should normally be examined. - probe: insmod parameter. - A list of pairs. The first value is a bus number (-1 for any I2C bus), - the second is the address. These addresses are also probed, as if they - were in the 'normal' list. - ignore: insmod parameter. - A list of pairs. The first value is a bus number (-1 for any I2C bus), - the second is the I2C address. These addresses are never probed. - This parameter overrules the 'normal_i2c' list only. - force: insmod parameter. - A list of pairs. The first value is a bus number (-1 for any I2C bus), - the second is the I2C address. A device is blindly assumed to be on - the given address, no probing is done. - -Additionally, kind-specific force lists may optionally be defined if -the driver supports several chip kinds. They are grouped in a -NULL-terminated list of pointers named forces, those first element if the -generic force list mentioned above. Each additional list correspond to an -insmod parameter of the form force_<kind>. - -Fortunately, as a module writer, you just have to define the `normal_i2c' -parameter. The complete declaration could look like this: - - /* Scan 0x37, and 0x48 to 0x4f */ - static unsigned short normal_i2c[] = { 0x37, 0x48, 0x49, 0x4a, 0x4b, 0x4c, - 0x4d, 0x4e, 0x4f, I2C_CLIENT_END }; - - /* Magic definition of all other variables and things */ - I2C_CLIENT_INSMOD; - /* Or, if your driver supports, say, 2 kind of devices: */ - I2C_CLIENT_INSMOD_2(foo, bar); - -If you use the multi-kind form, an enum will be defined for you: - enum chips { any_chip, foo, bar, ... } -You can then (and certainly should) use it in the driver code. - -Note that you *have* to call the defined variable `normal_i2c', -without any prefix! - - -Attaching to an adapter ------------------------ +If you know for a fact that an I2C device is connected to a given I2C bus, +you can instantiate that device by simply filling an i2c_board_info +structure with the device address and driver name, and calling +i2c_new_device(). This will create the device, then the driver core will +take care of finding the right driver and will call its probe() method. +If a driver supports different device types, you can specify the type you +want using the type field. You can also specify an IRQ and platform data +if needed. + +Sometimes you know that a device is connected to a given I2C bus, but you +don't know the exact address it uses. This happens on TV adapters for +example, where the same driver supports dozens of slightly different +models, and I2C device addresses change from one model to the next. In +that case, you can use the i2c_new_probed_device() variant, which is +similar to i2c_new_device(), except that it takes an additional list of +possible I2C addresses to probe. A device is created for the first +responsive address in the list. If you expect more than one device to be +present in the address range, simply call i2c_new_probed_device() that +many times. + +The call to i2c_new_device() or i2c_new_probed_device() typically happens +in the I2C bus driver. You may want to save the returned i2c_client +reference for later use. + + +Device Detection +---------------- + +Sometimes you do not know in advance which I2C devices are connected to +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. + +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. 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. 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 +--------------- + +Each I2C device which has been created using i2c_new_device() or +i2c_new_probed_device() can be unregistered by calling +i2c_unregister_device(). If you don't call it explicitly, it will be +called automatically before the underlying I2C bus itself is removed, as a +device can't survive its parent in the device driver model. + + +Initializing the driver +======================= + +When the kernel is booted, or when your foo driver module is inserted, +you have to do some initializing. Fortunately, just registering the +driver module is usually enough. + +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); + +The module_i2c_driver() macro can be used to reduce above code. + +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. +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 +================ + +If your I2C device needs special handling when entering a system low +power state -- like putting a transceiver into a low power mode, or +activating a system wakeup mechanism -- do that in the suspend() method. +The resume() method should reverse what the suspend() method does. + +These are standard driver model calls, and they work just like they +would for any other driver stack. The calls can sleep, and can use +I2C messaging to the device being suspended or resumed (since their +parent I2C adapter is active when these calls are issued, and IRQs +are still enabled). + + +System Shutdown +=============== + +If your I2C device needs special handling when the system shuts down +or reboots (including kexec) -- like turning something off -- use a +shutdown() method. + +Again, this is a standard driver model call, working just like it +would for any other driver stack: the calls can sleep, and can use +I2C messaging. -Whenever a new adapter is inserted, or for all adapters if the driver is -being registered, the callback attach_adapter() is called. Now is the -time to determine what devices are present on the adapter, and to register -a client for each of them. - -The attach_adapter callback is really easy: we just call the generic -detection function. This function will scan the bus for us, using the -information as defined in the lists explained above. If a device is -detected at a specific address, another callback is called. - - int foo_attach_adapter(struct i2c_adapter *adapter) - { - return i2c_probe(adapter,&addr_data,&foo_detect_client); - } - -Remember, structure `addr_data' is defined by the macros explained above, -so you do not have to define it yourself. - -The i2c_probe function will call the foo_detect_client -function only for those i2c addresses that actually have a device on -them (unless a `force' parameter was used). In addition, addresses that -are already in use (by some other registered client) are skipped. - - -The detect client function --------------------------- - -The detect client function is called by i2c_probe. The `kind' parameter -contains -1 for a probed detection, 0 for a forced detection, or a positive -number for a forced detection with a chip type forced. - -Below, some things are only needed if this is a `sensors' driver. Those -parts are between /* SENSORS ONLY START */ and /* SENSORS ONLY END */ -markers. - -Returning an error different from -ENODEV in a detect function will cause -the detection to stop: other addresses and adapters won't be scanned. -This should only be done on fatal or internal errors, such as a memory -shortage or i2c_attach_client failing. - -For now, you can ignore the `flags' parameter. It is there for future use. - - int foo_detect_client(struct i2c_adapter *adapter, int address, - unsigned short flags, int kind) - { - int err = 0; - int i; - struct i2c_client *new_client; - struct foo_data *data; - const char *client_name = ""; /* For non-`sensors' drivers, put the real - name here! */ - - /* Let's see whether this adapter can support what we need. - Please substitute the things you need here! - For `sensors' drivers, add `! is_isa &&' to the if statement */ - if (!i2c_check_functionality(adapter,I2C_FUNC_SMBUS_WORD_DATA | - I2C_FUNC_SMBUS_WRITE_BYTE)) - goto ERROR0; - - /* SENSORS ONLY START */ - const char *type_name = ""; - int is_isa = i2c_is_isa_adapter(adapter); - - /* Do this only if the chip can additionally be found on the ISA bus - (hybrid chip). */ - - if (is_isa) { - - /* Discard immediately if this ISA range is already used */ - /* FIXME: never use check_region(), only request_region() */ - if (check_region(address,FOO_EXTENT)) - goto ERROR0; - - /* Probe whether there is anything on this address. - Some example code is below, but you will have to adapt this - for your own driver */ - - if (kind < 0) /* Only if no force parameter was used */ { - /* We may need long timeouts at least for some chips. */ - #define REALLY_SLOW_IO - i = inb_p(address + 1); - if (inb_p(address + 2) != i) - goto ERROR0; - if (inb_p(address + 3) != i) - goto ERROR0; - if (inb_p(address + 7) != i) - goto ERROR0; - #undef REALLY_SLOW_IO - - /* Let's just hope nothing breaks here */ - i = inb_p(address + 5) & 0x7f; - outb_p(~i & 0x7f,address+5); - if ((inb_p(address + 5) & 0x7f) != (~i & 0x7f)) { - outb_p(i,address+5); - return 0; - } - } - } - - /* SENSORS ONLY END */ - - /* OK. For now, we presume we have a valid client. We now create the - client structure, even though we cannot fill it completely yet. - But it allows us to access several i2c functions safely */ - - if (!(data = kzalloc(sizeof(struct foo_data), GFP_KERNEL))) { - err = -ENOMEM; - goto ERROR0; - } - - new_client = &data->client; - i2c_set_clientdata(new_client, data); - - new_client->addr = address; - new_client->adapter = adapter; - new_client->driver = &foo_driver; - new_client->flags = 0; - - /* Now, we do the remaining detection. If no `force' parameter is used. */ - - /* First, the generic detection (if any), that is skipped if any force - parameter was used. */ - if (kind < 0) { - /* The below is of course bogus */ - if (foo_read(new_client,FOO_REG_GENERIC) != FOO_GENERIC_VALUE) - goto ERROR1; - } - - /* SENSORS ONLY START */ - - /* Next, specific detection. This is especially important for `sensors' - devices. */ - - /* Determine the chip type. Not needed if a `force_CHIPTYPE' parameter - was used. */ - if (kind <= 0) { - i = foo_read(new_client,FOO_REG_CHIPTYPE); - if (i == FOO_TYPE_1) - kind = chip1; /* As defined in the enum */ - else if (i == FOO_TYPE_2) - kind = chip2; - else { - printk("foo: Ignoring 'force' parameter for unknown chip at " - "adapter %d, address 0x%02x\n",i2c_adapter_id(adapter),address); - goto ERROR1; - } - } - - /* Now set the type and chip names */ - if (kind == chip1) { - type_name = "chip1"; /* For /proc entry */ - client_name = "CHIP 1"; - } else if (kind == chip2) { - type_name = "chip2"; /* For /proc entry */ - client_name = "CHIP 2"; - } - - /* Reserve the ISA region */ - if (is_isa) - request_region(address,FOO_EXTENT,type_name); - - /* SENSORS ONLY END */ - - /* Fill in the remaining client fields. */ - strcpy(new_client->name,client_name); - - /* SENSORS ONLY BEGIN */ - data->type = kind; - /* SENSORS ONLY END */ - - data->valid = 0; /* Only if you use this field */ - init_MUTEX(&data->update_lock); /* Only if you use this field */ - - /* Any other initializations in data must be done here too. */ - - /* Tell the i2c layer a new client has arrived */ - if ((err = i2c_attach_client(new_client))) - goto ERROR3; - - /* SENSORS ONLY BEGIN */ - /* Register a new directory entry with module sensors. See below for - the `template' structure. */ - if ((i = i2c_register_entry(new_client, type_name, - foo_dir_table_template,THIS_MODULE)) < 0) { - err = i; - goto ERROR4; - } - data->sysctl_id = i; - - /* SENSORS ONLY END */ - - /* This function can write default values to the client registers, if - needed. */ - foo_init_client(new_client); - return 0; - - /* OK, this is not exactly good programming practice, usually. But it is - very code-efficient in this case. */ - - ERROR4: - i2c_detach_client(new_client); - ERROR3: - ERROR2: - /* SENSORS ONLY START */ - if (is_isa) - release_region(address,FOO_EXTENT); - /* SENSORS ONLY END */ - ERROR1: - kfree(new_client); - ERROR0: - return err; - } - - -Removing the client -=================== - -The detach_client call back function is called when a client should be -removed. It may actually fail, but only when panicking. This code is -much simpler than the attachment code, fortunately! - - int foo_detach_client(struct i2c_client *client) - { - int err,i; - - /* SENSORS ONLY START */ - /* Deregister with the `i2c-proc' module. */ - i2c_deregister_entry(((struct lm78_data *)(client->data))->sysctl_id); - /* SENSORS ONLY END */ - - /* Try to detach the client from i2c space */ - if ((err = i2c_detach_client(client))) - return err; - - /* HYBRID SENSORS CHIP ONLY START */ - if i2c_is_isa_client(client) - release_region(client->addr,LM78_EXTENT); - /* HYBRID SENSORS CHIP ONLY END */ - - kfree(data); - return 0; - } - - -Initializing the module or kernel -================================= - -When the kernel is booted, or when your foo driver module is inserted, -you have to do some initializing. Fortunately, just attaching (registering) -the driver module is usually enough. - - /* Keep track of how far we got in the initialization process. If several - things have to initialized, and we fail halfway, only those things - have to be cleaned up! */ - static int __initdata foo_initialized = 0; - - static int __init foo_init(void) - { - int res; - printk("foo version %s (%s)\n",FOO_VERSION,FOO_DATE); - - if ((res = i2c_add_driver(&foo_driver))) { - printk("foo: Driver registration failed, module not inserted.\n"); - foo_cleanup(); - return res; - } - foo_initialized ++; - return 0; - } - - void foo_cleanup(void) - { - if (foo_initialized == 1) { - if ((res = i2c_del_driver(&foo_driver))) { - printk("foo: Driver registration failed, module not removed.\n"); - return; - } - foo_initialized --; - } - } - - /* Substitute your own name and email address */ - MODULE_AUTHOR("Frodo Looijaard <frodol@dds.nl>" - MODULE_DESCRIPTION("Driver for Barf Inc. Foo I2C devices"); - - module_init(foo_init); - module_exit(foo_cleanup); - -Note that some functions are marked by `__init', and some data structures -by `__init_data'. Hose functions and structures can be removed after -kernel booting (or module loading) is completed. Command function ================ A generic ioctl-like function call back is supported. You will seldom -need this. You may even set it to NULL. - - /* No commands defined */ - int foo_command(struct i2c_client *client, unsigned int cmd, void *arg) - { - return 0; - } +need this, and its use is deprecated anyway, so newer design should not +use it. Sending and receiving ===================== If you want to communicate with your device, there are several functions -to do this. You can find all of them in i2c.h. +to do this. You can find all of them in <linux/i2c.h>. -If you can choose between plain i2c communication and SMBus level -communication, please use the last. All adapters understand SMBus level -commands, but only some of them understand plain i2c! +If you can choose between plain I2C communication and SMBus level +communication, please use the latter. All adapters understand SMBus level +commands, but only some of them understand plain I2C! -Plain i2c communication +Plain I2C communication ----------------------- - extern int i2c_master_send(struct i2c_client *,const char* ,int); - extern int i2c_master_recv(struct i2c_client *,char* ,int); + int i2c_master_send(struct i2c_client *client, const char *buf, + int count); + int i2c_master_recv(struct i2c_client *client, char *buf, int count); 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 the read/write, the third the length of the -buffer. Returned is the actual number of bytes read/written. - - extern int i2c_transfer(struct i2c_adapter *adap, struct i2c_msg *msg, - int num); +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, 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); This sends a series of messages. Each message can be a read or write, and they can be mixed in any way. The transactions are combined: no @@ -541,54 +344,50 @@ for each message the client address, the number of bytes of the message and the message data itself. You can read the file `i2c-protocol' for more information about the -actual i2c protocol. +actual I2C protocol. SMBus communication ------------------- - extern s32 i2c_smbus_xfer (struct i2c_adapter * adapter, u16 addr, - unsigned short flags, - char read_write, u8 command, int size, - union i2c_smbus_data * data); - - This is the generic SMBus function. All functions below are implemented - in terms of it. Never use this function directly! - - - extern s32 i2c_smbus_write_quick(struct i2c_client * client, u8 value); - extern s32 i2c_smbus_read_byte(struct i2c_client * client); - extern s32 i2c_smbus_write_byte(struct i2c_client * client, u8 value); - extern s32 i2c_smbus_read_byte_data(struct i2c_client * client, u8 command); - extern s32 i2c_smbus_write_byte_data(struct i2c_client * client, - u8 command, u8 value); - extern s32 i2c_smbus_read_word_data(struct i2c_client * client, u8 command); - extern s32 i2c_smbus_write_word_data(struct i2c_client * client, - u8 command, u16 value); - extern s32 i2c_smbus_write_block_data(struct i2c_client * client, - u8 command, u8 length, - u8 *values); - extern s32 i2c_smbus_read_i2c_block_data(struct i2c_client * client, - u8 command, u8 *values); - -These ones were removed in Linux 2.6.10 because they had no users, but could + s32 i2c_smbus_xfer(struct i2c_adapter *adapter, u16 addr, + unsigned short flags, char read_write, u8 command, + int size, union i2c_smbus_data *data); + +This is the generic SMBus function. All functions below are implemented +in terms of it. Never use this function directly! + + s32 i2c_smbus_read_byte(struct i2c_client *client); + s32 i2c_smbus_write_byte(struct i2c_client *client, u8 value); + s32 i2c_smbus_read_byte_data(struct i2c_client *client, u8 command); + s32 i2c_smbus_write_byte_data(struct i2c_client *client, + u8 command, u8 value); + 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_read_block_data(struct i2c_client *client, + u8 command, u8 *values); + s32 i2c_smbus_write_block_data(struct i2c_client *client, + u8 command, u8 length, const u8 *values); + s32 i2c_smbus_read_i2c_block_data(struct i2c_client *client, + u8 command, u8 length, u8 *values); + s32 i2c_smbus_write_i2c_block_data(struct i2c_client *client, + u8 command, u8 length, + const u8 *values); + +These ones were removed from i2c-core because they had no users, but could be added back later if needed: - extern s32 i2c_smbus_read_block_data(struct i2c_client * client, - u8 command, u8 *values); - extern s32 i2c_smbus_write_i2c_block_data(struct i2c_client * client, - u8 command, u8 length, - u8 *values); - extern s32 i2c_smbus_process_call(struct i2c_client * client, - u8 command, u16 value); - extern s32 i2c_smbus_block_process_call(struct i2c_client *client, - u8 command, u8 length, - u8 *values) - -All these transactions return -1 on failure. The 'write' transactions -return 0 on success; the 'read' transactions return the read value, except -for read_block, which returns the number of values read. The block buffers -need not be longer than 32 bytes. + 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); + +All these transactions return a negative errno value on failure. The 'write' +transactions return 0 on success; the 'read' transactions return the read +value, except for block transactions, which return the number of values +read. The block buffers need not be longer than 32 bytes. You can read the file `smbus-protocol' for more information about the actual SMBus protocol. @@ -600,110 +399,5 @@ General purpose routines Below all general purpose routines are listed, that were not mentioned before. - /* This call returns a unique low identifier for each registered adapter, - * or -1 if the adapter was not registered. - */ - extern int i2c_adapter_id(struct i2c_adapter *adap); - - -The sensors sysctl/proc interface -================================= - -This section only applies if you write `sensors' drivers. - -Each sensors driver creates a directory in /proc/sys/dev/sensors for each -registered client. The directory is called something like foo-i2c-4-65. -The sensors module helps you to do this as easily as possible. - -The template ------------- - -You will need to define a ctl_table template. This template will automatically -be copied to a newly allocated structure and filled in where necessary when -you call sensors_register_entry. - -First, I will give an example definition. - static ctl_table foo_dir_table_template[] = { - { FOO_SYSCTL_FUNC1, "func1", NULL, 0, 0644, NULL, &i2c_proc_real, - &i2c_sysctl_real,NULL,&foo_func }, - { FOO_SYSCTL_FUNC2, "func2", NULL, 0, 0644, NULL, &i2c_proc_real, - &i2c_sysctl_real,NULL,&foo_func }, - { FOO_SYSCTL_DATA, "data", NULL, 0, 0644, NULL, &i2c_proc_real, - &i2c_sysctl_real,NULL,&foo_data }, - { 0 } - }; - -In the above example, three entries are defined. They can either be -accessed through the /proc interface, in the /proc/sys/dev/sensors/* -directories, as files named func1, func2 and data, or alternatively -through the sysctl interface, in the appropriate table, with identifiers -FOO_SYSCTL_FUNC1, FOO_SYSCTL_FUNC2 and FOO_SYSCTL_DATA. - -The third, sixth and ninth parameters should always be NULL, and the -fourth should always be 0. The fifth is the mode of the /proc file; -0644 is safe, as the file will be owned by root:root. - -The seventh and eighth parameters should be &i2c_proc_real and -&i2c_sysctl_real if you want to export lists of reals (scaled -integers). You can also use your own function for them, as usual. -Finally, the last parameter is the call-back to gather the data -(see below) if you use the *_proc_real functions. - - -Gathering the data ------------------- - -The call back functions (foo_func and foo_data in the above example) -can be called in several ways; the operation parameter determines -what should be done: - - * If operation == SENSORS_PROC_REAL_INFO, you must return the - magnitude (scaling) in nrels_mag; - * If operation == SENSORS_PROC_REAL_READ, you must read information - from the chip and return it in results. The number of integers - to display should be put in nrels_mag; - * If operation == SENSORS_PROC_REAL_WRITE, you must write the - supplied information to the chip. nrels_mag will contain the number - of integers, results the integers themselves. - -The *_proc_real functions will display the elements as reals for the -/proc interface. If you set the magnitude to 2, and supply 345 for -SENSORS_PROC_REAL_READ, it would display 3.45; and if the user would -write 45.6 to the /proc file, it would be returned as 4560 for -SENSORS_PROC_REAL_WRITE. A magnitude may even be negative! - -An example function: - - /* FOO_FROM_REG and FOO_TO_REG translate between scaled values and - register values. Note the use of the read cache. */ - void foo_in(struct i2c_client *client, int operation, int ctl_name, - int *nrels_mag, long *results) - { - struct foo_data *data = client->data; - int nr = ctl_name - FOO_SYSCTL_FUNC1; /* reduce to 0 upwards */ - - if (operation == SENSORS_PROC_REAL_INFO) - *nrels_mag = 2; - else if (operation == SENSORS_PROC_REAL_READ) { - /* Update the readings cache (if necessary) */ - foo_update_client(client); - /* Get the readings from the cache */ - results[0] = FOO_FROM_REG(data->foo_func_base[nr]); - results[1] = FOO_FROM_REG(data->foo_func_more[nr]); - results[2] = FOO_FROM_REG(data->foo_func_readonly[nr]); - *nrels_mag = 2; - } else if (operation == SENSORS_PROC_REAL_WRITE) { - if (*nrels_mag >= 1) { - /* Update the cache */ - data->foo_base[nr] = FOO_TO_REG(results[0]); - /* Update the chip */ - foo_write_value(client,FOO_REG_FUNC_BASE(nr),data->foo_base[nr]); - } - if (*nrels_mag >= 2) { - /* Update the cache */ - data->foo_more[nr] = FOO_TO_REG(results[1]); - /* Update the chip */ - foo_write_value(client,FOO_REG_FUNC_MORE(nr),data->foo_more[nr]); - } - } - } + /* Return the adapter number for a specific adapter */ + int i2c_adapter_id(struct i2c_adapter *adap); |