From d64f73be1b59b9556de0a8fbd4f1a003c6a45a5c Mon Sep 17 00:00:00 2001 From: David Brownell Date: Thu, 12 Jul 2007 14:12:28 +0200 Subject: i2c: Add kernel documentation Generate I2C kerneldoc; fix various glitches and add "context" sections to that documentation. Most I2C and SMBus functions still have no kerneldoc. Let me suggest providing kerneldoc for all the i2c_smbus_*() functions as a small and mostly self-contained project for anyone so inclined. :) Signed-off-by: David Brownell Signed-off-by: Jean Delvare --- Documentation/DocBook/kernel-api.tmpl | 55 +++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) (limited to 'Documentation') diff --git a/Documentation/DocBook/kernel-api.tmpl b/Documentation/DocBook/kernel-api.tmpl index 8c5698a8c2e..46bcff2849b 100644 --- a/Documentation/DocBook/kernel-api.tmpl +++ b/Documentation/DocBook/kernel-api.tmpl @@ -643,6 +643,60 @@ X!Idrivers/video/console/fonts.c !Edrivers/spi/spi.c + + I<superscript>2</superscript>C and SMBus Subsystem + + + I2C (or without fancy typography, "I2C") + is an acronym for the "Inter-IC" bus, a simple bus protocol which is + widely used where low data rate communications suffice. + Since it's also a licensed trademark, some vendors use another + name (such as "Two-Wire Interface", TWI) for the same bus. + I2C only needs two signals (SCL for clock, SDA for data), conserving + board real estate and minimizing signal quality issues. + Most I2C devices use seven bit addresses, and bus speeds of up + to 400 kHz; there's a high speed extension (3.4 MHz) that's not yet + found wide use. + I2C is a multi-master bus; open drain signaling is used to + arbitrate between masters, as well as to handshake and to + synchronize clocks from slower clients. + + + + The Linux I2C programming interfaces support only the master + side of bus interactions, not the slave side. + The programming interface is structured around two kinds of driver, + and two kinds of device. + An I2C "Adapter Driver" abstracts the controller hardware; it binds + to a physical device (perhaps a PCI device or platform_device) and + exposes a struct i2c_adapter representing + each I2C bus segment it manages. + On each I2C bus segment will be I2C devices represented by a + struct i2c_client. Those devices will + be bound to a struct i2c_driver, + which should follow the standard Linux driver model. + (At this writing, a legacy model is more widely used.) + There are functions to perform various I2C protocol operations; at + this writing all such functions are usable only from task context. + + + + The System Management Bus (SMBus) is a sibling protocol. Most SMBus + systems are also I2C conformant. The electrical constraints are + tighter for SMBus, and it standardizes particular protocol messages + and idioms. Controllers that support I2C can also support most + SMBus operations, but SMBus controllers don't support all the protocol + options that an I2C controller will. + There are functions to perform various SMBus protocol operations, + either using I2C primitives or by issuing SMBus commands to + i2c_adapter devices which don't support those I2C operations. + + +!Iinclude/linux/i2c.h +!Fdrivers/i2c/i2c-boardinfo.c i2c_register_board_info +!Edrivers/i2c/i2c-core.c + + splice API ) @@ -654,4 +708,5 @@ X!Idrivers/video/console/fonts.c !Ffs/splice.c + -- cgit v1.2.3 From 890e037509f5b3f967b16ea0ea525c7c75b213ae Mon Sep 17 00:00:00 2001 From: Jean Delvare Date: Thu, 12 Jul 2007 14:12:28 +0200 Subject: i2c: Delete outdated x1205 driver documentation The x1205 driver moved to the RTC subsystem and was significantly modified since then, so just delete the outdated documentation. Signed-off-by: Jean Delvare Cc: Alessandro Zummo --- Documentation/i2c/chips/x1205 | 38 -------------------------------------- 1 file changed, 38 deletions(-) delete mode 100644 Documentation/i2c/chips/x1205 (limited to 'Documentation') 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 , - Alessandro Zummo - -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 -- cgit v1.2.3 From ba7fbb723f50ab2607989a282af655fb0fab0492 Mon Sep 17 00:00:00 2001 From: Jean Delvare Date: Thu, 12 Jul 2007 14:12:29 +0200 Subject: i2c: Deprecate legacy RTC drivers We have a new RTC subsystem with better drivers. Legacy driver status: * ds1337: The DS1337 and DS1339 are now supported by the rtc-ds1307 driver, so it looks to me like we could even delete the ds1337 driver right away. * ds1374: Will soon be replaced with Scott Wood's rtc-ds1374 driver. * m41t00: The M41T00 is supported by the rtc-ds1307 driver. For the M41T81 and M41T85, the rtc-m41t80 driver written by Atsushi Nemoto should work. Signed-off-by: Jean Delvare Cc: Alessandro Zummo Acked-by: Mark A. Greer Acked-by: James Chapman Cc: Randy Vinson --- Documentation/feature-removal-schedule.txt | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'Documentation') diff --git a/Documentation/feature-removal-schedule.txt b/Documentation/feature-removal-schedule.txt index 3a159dac04f..281458b47d7 100644 --- a/Documentation/feature-removal-schedule.txt +++ b/Documentation/feature-removal-schedule.txt @@ -330,3 +330,10 @@ Who: Tejun Heo --------------------------- +What: Legacy RTC drivers (under drivers/i2c/chips) +When: November 2007 +Why: Obsolete. We have a RTC subsystem with better drivers. +Who: Jean Delvare + +--------------------------- + -- cgit v1.2.3 From 4b2643d7d9bdcd776749e17f73c168ddf02e93cb Mon Sep 17 00:00:00 2001 From: Jean Delvare Date: Thu, 12 Jul 2007 14:12:29 +0200 Subject: i2c: Fix the i2c_smbus_read_i2c_block_data() prototype Let the drivers specify how many bytes they want to read with i2c_smbus_read_i2c_block_data(). So far, the block count was hard-coded to I2C_SMBUS_BLOCK_MAX (32), which did not make much sense. Many driver authors complained about this before, and I believe it's about time to fix it. Right now, authors have to do technically stupid things, such as individual byte reads or full-fledged I2C messaging, to work around the problem. We do not want to encourage that. I even found that some bus drivers (e.g. i2c-amd8111) already implemented I2C block read the "right" way, that is, they didn't follow the old, broken standard. The fact that it was never noticed before just shows how little i2c_smbus_read_i2c_block_data() was used, which isn't that surprising given how broken its prototype was so far. There are some obvious compatiblity considerations: * This changes the i2c_smbus_read_i2c_block_data() prototype. Users outside the kernel tree will notice at compilation time, and will have to update their code. * User-space has access to i2c_smbus_xfer() directly using i2c-dev, so the changed expectations would affect tools such as i2cdump. In order to preserve binary compatibility, we give I2C_SMBUS_I2C_BLOCK_DATA a new numeric value, and define I2C_SMBUS_I2C_BLOCK_BROKEN with the old numeric value. When i2c-dev receives a transaction with the old value, it can convert it to the new format on the fly. Signed-off-by: Jean Delvare --- Documentation/i2c/chips/max6875 | 2 +- Documentation/i2c/writing-clients | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/i2c/chips/max6875 b/Documentation/i2c/chips/max6875 index 96fec562a8e..a0cd8af2f40 100644 --- a/Documentation/i2c/chips/max6875 +++ b/Documentation/i2c/chips/max6875 @@ -99,7 +99,7 @@ And then read the data or - count = i2c_smbus_read_i2c_block_data(fd, 0x84, buffer); + count = i2c_smbus_read_i2c_block_data(fd, 0x84, 16, buffer); The block read should read 16 bytes. 0x84 is the block read command. diff --git a/Documentation/i2c/writing-clients b/Documentation/i2c/writing-clients index 3d8d36b0ad1..2c170032bf3 100644 --- a/Documentation/i2c/writing-clients +++ b/Documentation/i2c/writing-clients @@ -571,7 +571,7 @@ SMBus communication u8 command, u8 length, u8 *values); extern s32 i2c_smbus_read_i2c_block_data(struct i2c_client * client, - u8 command, u8 *values); + u8 command, u8 length, u8 *values); These ones were removed in Linux 2.6.10 because they had no users, but could be added back later if needed: -- cgit v1.2.3 From c29c22218b99dad95f7cd0281415a854aeee805c Mon Sep 17 00:00:00 2001 From: Henry Su Date: Thu, 12 Jul 2007 14:12:29 +0200 Subject: i2c-piix4: Add support for the ATI SB700 Add the SMBus device ID for ATI SB700. Signed-off-by: Henry Su Signed-off-by: Jean Delvare --- Documentation/i2c/busses/i2c-piix4 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/i2c/busses/i2c-piix4 b/Documentation/i2c/busses/i2c-piix4 index 7cbe43fa270..fa0c786a8bf 100644 --- a/Documentation/i2c/busses/i2c-piix4 +++ b/Documentation/i2c/busses/i2c-piix4 @@ -6,7 +6,7 @@ Supported adapters: Datasheet: Publicly available at the Intel website * ServerWorks OSB4, CSB5, CSB6 and HT-1000 southbridges Datasheet: Only available via NDA from ServerWorks - * ATI IXP200, IXP300, IXP400 and SB600 southbridges + * ATI IXP200, IXP300, IXP400, SB600 and SB700 southbridges Datasheet: Not publicly available * Standard Microsystems (SMSC) SLC90E66 (Victory66) southbridge Datasheet: Publicly available at the SMSC website http://www.smsc.com -- cgit v1.2.3 From 7edcb9abb594a8f3b4ca756e03d01c870aeae127 Mon Sep 17 00:00:00 2001 From: Oleg Ryjkov Date: Thu, 12 Jul 2007 14:12:31 +0200 Subject: i2c-i801: Use the internal 32-byte buffer on ICH4+ Add an ability to utilize the internal SRAM buffer on ICH4 and newer host controllers to speed up execution of block operations. I've split the code so that it is more clear which block transaction is performed. First of all the host controller's type is identified. isich4 is set when we think that the controller has the internal buffer. Then, before every block transaction, if isich4 is set, we attempt to enable the E32B bit in SMBAUXCTL register. Signed-off-by: Oleg Ryjkov Signed-off-by: Jean Delvare --- Documentation/i2c/busses/i2c-i801 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/i2c/busses/i2c-i801 b/Documentation/i2c/busses/i2c-i801 index c34f0db78a3..fe6406f2f9a 100644 --- a/Documentation/i2c/busses/i2c-i801 +++ b/Documentation/i2c/busses/i2c-i801 @@ -5,8 +5,8 @@ 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 82801G (ICH7) -- cgit v1.2.3 From b9cdad74883a797952de52464d118d685cafc05a Mon Sep 17 00:00:00 2001 From: Jean Delvare Date: Thu, 12 Jul 2007 14:12:31 +0200 Subject: i2c: New bus driver for the TAOS evaluation modules This is a new I2C bus driver for the TAOS evaluation modules. Developped and tested on the TAOS TSL2550 EVM. Signed-off-by: Jean Delvare --- Documentation/i2c/busses/i2c-taos-evm | 46 +++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) create mode 100644 Documentation/i2c/busses/i2c-taos-evm (limited to 'Documentation') diff --git a/Documentation/i2c/busses/i2c-taos-evm b/Documentation/i2c/busses/i2c-taos-evm new file mode 100644 index 00000000000..9146e33be6d --- /dev/null +++ b/Documentation/i2c/busses/i2c-taos-evm @@ -0,0 +1,46 @@ +Kernel driver i2c-taos-evm + +Author: Jean Delvare + +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 addtional 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. -- cgit v1.2.3 From 0a85e9a271a754e352af8a8b625025017fd97449 Mon Sep 17 00:00:00 2001 From: Jean Delvare Date: Thu, 12 Jul 2007 14:12:32 +0200 Subject: i2c-rpx: Remove This driver has been broken forever. It depends on i2c-algo-8xx which has never been in the mainline kernel. Signed-off-by: Jean Delvare --- Documentation/i2c/summary | 2 -- 1 file changed, 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/i2c/summary b/Documentation/i2c/summary index aea60bf7e8f..003c7319b8c 100644 --- a/Documentation/i2c/summary +++ b/Documentation/i2c/summary @@ -67,7 +67,6 @@ 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) @@ -81,6 +80,5 @@ i2c-pcf-epp: PCF8584 on a EPP parallel port (uses i2c-algo-pcf) (NOT mkpatch 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) -- cgit v1.2.3