diff options
Diffstat (limited to 'Documentation/i2c')
33 files changed, 0 insertions, 3167 deletions
diff --git a/Documentation/i2c/busses/i2c-ali1535 b/Documentation/i2c/busses/i2c-ali1535 deleted file mode 100644 index 5d46342e486..00000000000 --- a/Documentation/i2c/busses/i2c-ali1535 +++ /dev/null @@ -1,42 +0,0 @@ -Kernel driver i2c-ali1535 - -Supported adapters: - * Acer Labs, Inc. ALI 1535 (south bridge) - Datasheet: Now under NDA - http://www.ali.com.tw/ - -Authors: - 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 ------------ - -This is the driver for the SMB Host controller on Acer Labs Inc. (ALI) -M1535 South Bridge. - -The M1535 is a South bridge for portable systems. It is very similar to the -M15x3 South bridges also produced by Acer Labs Inc. Some of the registers -within the part have moved and some have been redefined slightly. -Additionally, the sequencing of the SMBus transactions has been modified to -be more consistent with the sequencing recommended by the manufacturer and -observed through testing. These changes are reflected in this driver and -can be identified by comparing this driver to the i2c-ali15x3 driver. For -an overview of these chips see http://www.acerlabs.com - -The SMB controller is part of the M7101 device, which is an ACPI-compliant -Power Management Unit (PMU). - -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 --------- - -This driver controls the SMB Host only. This driver does not use -interrupts. diff --git a/Documentation/i2c/busses/i2c-ali1563 b/Documentation/i2c/busses/i2c-ali1563 deleted file mode 100644 index 41b1a077e4c..00000000000 --- a/Documentation/i2c/busses/i2c-ali1563 +++ /dev/null @@ -1,27 +0,0 @@ -Kernel driver i2c-ali1563 - -Supported adapters: - * Acer Labs, Inc. ALI 1563 (south bridge) - Datasheet: Now under NDA - http://www.ali.com.tw/ - -Author: Patrick Mochel <mochel@digitalimplant.org> - -Description ------------ - -This is the driver for the SMB Host controller on Acer Labs Inc. (ALI) -M1563 South Bridge. - -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. - -Features --------- - -This driver controls the SMB Host only. This driver does not use -interrupts. diff --git a/Documentation/i2c/busses/i2c-ali15x3 b/Documentation/i2c/busses/i2c-ali15x3 deleted file mode 100644 index 42888d8ac12..00000000000 --- a/Documentation/i2c/busses/i2c-ali15x3 +++ /dev/null @@ -1,112 +0,0 @@ -Kernel driver i2c-ali15x3 - -Supported adapters: - * Acer Labs, Inc. ALI 1533 and 1543C (south bridge) - Datasheet: Now under NDA - http://www.ali.com.tw/ - -Authors: - Frodo Looijaard <frodol@dds.nl>, - Philip Edelbrock <phil@netroedge.com>, - Mark D. Studebaker <mdsxyz123@yahoo.com> - -Module Parameters ------------------ - -* force_addr: int - Initialize the base address of the i2c controller - - -Notes ------ - -The force_addr parameter is useful for boards that don't set the address in -the BIOS. Does not do a PCI force; the device must still be present in -lspci. Don't use this unless the driver complains that the base address is -not set. - -Example: 'modprobe i2c-ali15x3 force_addr=0xe800' - -SMBus periodically hangs on ASUS P5A motherboards and can only be cleared -by a power cycle. Cause unknown (see Issues below). - - -Description ------------ - -This is the driver for the SMB Host controller on Acer Labs Inc. (ALI) -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 - 100MHz CPU Front Side bus - * "Aladdin V" includes the M1541 Socket 7 North bridge with AGP and 100MHz - CPU Front Side bus - Some Aladdin V motherboards: - Asus P5A - Atrend ATC-5220 - BCM/GVC VP1541 - Biostar M5ALA - Gigabyte GA-5AX (** Generally doesn't work because the BIOS doesn't - enable the 7101 device! **) - Iwill XA100 Plus - Micronics C200 - Microstar (MSI) MS-5169 - - * "Aladdin IV" includes the M1541 Socket 7 North bridge - with host bus up to 83.3 MHz. - -For an overview of these chips see http://www.acerlabs.com. At this time the -full data sheets on the web site are password protected, however if you -contact the ALI office in San Jose they may give you the password. - -The M1533/M1543C devices appear as FOUR separate devices on the PCI bus. An -output of lspci will show something similar to the following: - - 00:02.0 USB Controller: Acer Laboratories Inc. M5237 (rev 03) - 00:03.0 Bridge: Acer Laboratories Inc. M7101 <= THIS IS THE ONE WE NEED - 00:07.0 ISA bridge: Acer Laboratories Inc. M1533 (rev c3) - 00:0f.0 IDE interface: Acer Laboratories Inc. M5229 (rev c1) - -** IMPORTANT ** -** If you have a M1533 or M1543C on the board and you get -** "ali15x3: Error: Can't detect ali15x3!" -** 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. -** 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 -Power Management Unit (PMU). - -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 --------- - -This driver controls the SMB Host only. The SMB Slave -controller on the M15X3 is not enabled. This driver does not use -interrupts. - - -Issues ------- - -This driver requests the I/O space for only the SMB -registers. It doesn't use the ACPI region. - -On the ASUS P5A motherboard, there are several reports that -the SMBus will hang and this can only be resolved by -powering off the computer. It appears to be worse when the board -gets hot, for example under heavy CPU load, or in the summer. -There may be electrical problems on this board. -On the P5A, the W83781D sensor chip is on both the ISA and -SMBus. Therefore the SMBus hangs can generally be avoided -by accessing the W83781D on the ISA bus only. - diff --git a/Documentation/i2c/busses/i2c-amd756 b/Documentation/i2c/busses/i2c-amd756 deleted file mode 100644 index 67f30874d0b..00000000000 --- a/Documentation/i2c/busses/i2c-amd756 +++ /dev/null @@ -1,25 +0,0 @@ -Kernel driver i2c-amd756 - -Supported adapters: - * AMD 756 - * AMD 766 - * AMD 768 - * AMD 8111 - Datasheets: Publicly available on AMD website - - * nVidia nForce - Datasheet: Unavailable - -Authors: - Frodo Looijaard <frodol@dds.nl>, - Philip Edelbrock <phil@netroedge.com> - -Description ------------ - -This driver supports the AMD 756, 766, 768 and 8111 Peripheral Bus -Controllers, and the nVidia nForce. - -Note that for the 8111, there are two SMBus adapters. The SMBus 1.0 adapter -is supported by this driver, and the SMBus 2.0 adapter is supported by the -i2c-amd8111 driver. diff --git a/Documentation/i2c/busses/i2c-amd8111 b/Documentation/i2c/busses/i2c-amd8111 deleted file mode 100644 index 460dd6635fd..00000000000 --- a/Documentation/i2c/busses/i2c-amd8111 +++ /dev/null @@ -1,41 +0,0 @@ -Kernel driver i2c-adm8111 - -Supported adapters: - * AMD-8111 SMBus 2.0 PCI interface - -Datasheets: - AMD datasheet not yet available, but almost everything can be found - in the publicly available ACPI 2.0 specification, which the adapter - follows. - -Author: Vojtech Pavlik <vojtech@suse.cz> - -Description ------------ - -If you see something like this: - -00:07.2 SMBus: Advanced Micro Devices [AMD] AMD-8111 SMBus 2.0 (rev 02) - Subsystem: Advanced Micro Devices [AMD] AMD-8111 SMBus 2.0 - Flags: medium devsel, IRQ 19 - I/O ports at d400 [size=32] - -in your 'lspci -v', then this driver is for your chipset. - -Process Call Support --------------------- - -Supported. - -SMBus 2.0 Support ------------------ - -Supported. Both PEC and block process call support is implemented. Slave -mode or host notification are not yet implemented. - -Notes ------ - -Note that for the 8111, there are two SMBus adapters. The SMBus 2.0 adapter -is supported by this driver, and the SMBus 1.0 adapter is supported by the -i2c-amd756 driver. diff --git a/Documentation/i2c/busses/i2c-diolan-u2c b/Documentation/i2c/busses/i2c-diolan-u2c deleted file mode 100644 index 30fe4bb9a06..00000000000 --- a/Documentation/i2c/busses/i2c-diolan-u2c +++ /dev/null @@ -1,26 +0,0 @@ -Kernel driver i2c-diolan-u2c - -Supported adapters: - * Diolan U2C-12 I2C-USB adapter - Documentation: - http://www.diolan.com/i2c/u2c12.html - -Author: Guenter Roeck <guenter.roeck@ericsson.com> - -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 deleted file mode 100644 index 71f55bbcefc..00000000000 --- a/Documentation/i2c/busses/i2c-i801 +++ /dev/null @@ -1,148 +0,0 @@ -Kernel driver i2c-i801 - -Supported adapters: - * Intel 82801AA and 82801AB (ICH and ICH0 - part of the - '810' and '810E' chipsets) - * Intel 82801BA (ICH2 - part of the '815E' chipset) - * Intel 82801CA/CAM (ICH3) - * Intel 82801DB (ICH4) (HW PEC supported) - * Intel 82801EB/ER (ICH5) (HW PEC supported) - * Intel 6300ESB - * Intel 82801FB/FR/FW/FRW (ICH6) - * 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) - Datasheets: Publicly available at the Intel website - -On Intel Patsburg and later chipsets, both the normal host SMBus controller -and the additional 'Integrated Device Function' controllers are supported. - -Authors: - Mark Studebaker <mdsxyz123@yahoo.com> - Jean Delvare <khali@linux-fr.org> - - -Module Parameters ------------------ - -* 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: - 1 disable SMBus PEC - 2 disable the block buffer - 8 disable the I2C block read functionality - - -Description ------------ - -The ICH (properly known as the 82801AA), ICH0 (82801AB), ICH2 (82801BA), -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. - -The ICH chips contain at least SEVEN separate PCI functions in TWO logical -PCI devices. An output of lspci will show something similar to the -following: - - 00:1e.0 PCI bridge: Intel Corporation: Unknown device 2418 (rev 01) - 00:1f.0 ISA bridge: Intel Corporation: Unknown device 2410 (rev 01) - 00:1f.1 IDE interface: Intel Corporation: Unknown device 2411 (rev 01) - 00:1f.2 USB Controller: Intel Corporation: Unknown device 2412 (rev 01) - 00:1f.3 Unknown class [0c05]: Intel Corporation: Unknown device 2413 (rev 01) - -The SMBus controller is function 3 in device 1f. Class 0c05 is SMBus Serial -Controller. - -The ICH chips are quite similar to Intel's PIIX4 chip, at least in the -SMBus controller. - - -Process Call Support --------------------- - -Not supported. - - -I2C Block Read Support ----------------------- - -I2C block read is supported on the 82801EB (ICH5) and later chips. - - -SMBus 2.0 Support ------------------ - -The 82801DB (ICH4) and later chips support several SMBus 2.0 features. - - -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. - -The lm_sensors project gratefully acknowledges the support of Intel in the -development of SMBus 2.0 / ICH4 features of this driver. diff --git a/Documentation/i2c/busses/i2c-nforce2 b/Documentation/i2c/busses/i2c-nforce2 deleted file mode 100644 index 9698c396b83..00000000000 --- a/Documentation/i2c/busses/i2c-nforce2 +++ /dev/null @@ -1,50 +0,0 @@ -Kernel driver i2c-nforce2 - -Supported adapters: - * nForce2 MCP 10de:0064 - * nForce2 Ultra 400 MCP 10de:0084 - * nForce3 Pro150 MCP 10de:00D4 - * nForce3 250Gb MCP 10de:00E4 - * 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@gmx.net>, - Thomas Leibold <thomas@plx.com>, - Patrick Dreker <patrick@dreker.de> - -Description ------------ - -i2c-nforce2 is a driver for the SMBuses included in the nVidia nForce2 MCP. - -If your 'lspci -v' listing shows something like the following, - -00:01.1 SMBus: nVidia Corporation: Unknown device 0064 (rev a2) - Subsystem: Asustek Computer, Inc.: Unknown device 0c11 - Flags: 66Mhz, fast devsel, IRQ 5 - I/O ports at c000 [size=32] - Capabilities: <available only to root> - -then this driver should support the SMBuses of your motherboard. - - -Notes ------ - -The SMBus adapter in the nForce2 chipset seems to be very similar to the -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 deleted file mode 100644 index c269aaa2f26..00000000000 --- a/Documentation/i2c/busses/i2c-ocores +++ /dev/null @@ -1,68 +0,0 @@ -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 deleted file mode 100644 index 2461c7b53b2..00000000000 --- a/Documentation/i2c/busses/i2c-parport +++ /dev/null @@ -1,177 +0,0 @@ -Kernel driver i2c-parport - -Author: Jean Delvare <khali@linux-fr.org> - -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 -meant as a replacement for the older, individual drivers: - * i2c-philips-par - * i2c-elv - * i2c-velleman - * video/i2c-parport (NOT the same as this one, dedicated to home brew - teletext adapters) - -It currently supports the following devices: - * (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 -------------------------- - -If you want to build you own i2c-over-parallel-port adapter, here is -a sample electronics schema (credits go to Sylvain Munaut): - -Device PC -Side ___________________Vdd (+) Side - | | | - --- --- --- - | | | | | | - |R| |R| |R| - | | | | | | - --- --- --- - | | | - | | /| | -SCL ----------x--------o |-----------x------------------- pin 2 - | \| | | - | | | - | |\ | | -SDA ----------x----x---| o---x--------------------------- pin 13 - | |/ | - | | - | /| | - ---------o |----------------x-------------- pin 3 - \| | | - | | - --- --- - | | | | - |R| |R| - | | | | - --- --- - | | - ### ### - GND GND - -Remarks: - - This is the exact pinout and electronics used on the Analog Devices - evaluation boards. - /| - - All inverters -o |- must be 74HC05, they must be open collector output. - \| - - All resitors are 10k. - - Pins 18-25 of the parallel port connected to GND. - - Pins 4-9 (D2-D7) could be used as VDD is the driver drives them high. - The ADM1032 evaluation board uses D4-D7. Beware that the amount of - current you can draw from the parallel port is limited. Also note that - all connected lines MUST BE driven at the same state, else you'll short - circuit the output buffers! So plugging the I2C adapter after loading - the i2c-parport module might be a good safety since data line state - prior to init may be unknown. - - This is 5V! - - Obviously you cannot read SCL (so it's not really standard-compliant). - Pretty easy to add, just copy the SDA part and use another input pin. - That would give (ELV compatible pinout): - - -Device PC -Side ______________________________Vdd (+) Side - | | | | - --- --- --- --- - | | | | | | | | - |R| |R| |R| |R| - | | | | | | | | - --- --- --- --- - | | | | - | | |\ | | -SCL ----------x--------x--| o---x------------------------ pin 15 - | | |/ | - | | | - | | /| | - | ---o |-------------x-------------- pin 2 - | \| | | - | | | - | | | - | |\ | | -SDA ---------------x---x--| o--------x------------------- pin 10 - | |/ | - | | - | /| | - ---o |------------------x--------- pin 3 - \| | | - | | - --- --- - | | | | - |R| |R| - | | | | - --- --- - | | - ### ### - GND GND - - -If possible, you should use the same pinout configuration as existing -adapters do, so you won't even have to change the code. - - -Similar (but different) drivers -------------------------------- - -This driver is NOT the same as the i2c-pport driver found in the i2c -package. The i2c-pport driver makes use of modern parallel port features so -that you don't need additional electronics. It has other restrictions -however, and was not ported to Linux 2.6 (yet). - -This driver is also NOT the same as the i2c-pcf-epp driver found in the -lm_sensors package. The i2c-pcf-epp driver doesn't use the parallel port as -an I2C bus directly. Instead, it uses it to control an external I2C bus -master. That driver was not ported to Linux 2.6 (yet) either. - - -Legacy documentation for Velleman adapter ------------------------------------------ - -Useful links: -Velleman http://www.velleman.be/ -Velleman K8000 Howto http://howto.htlw16.ac.at/k8000-howto.html - -The project has lead to new libs for the Velleman K8000 and K8005: - LIBK8000 v1.99.1 and LIBK8005 v0.21 -With these libs, you can control the K8000 interface card and the K8005 -stepper motor card with the simple commands which are in the original -Velleman software, like SetIOchannel, ReadADchannel, SendStepCCWFull and -many more, using /dev/velleman. - http://home.wanadoo.nl/hihihi/libk8000.htm - 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 deleted file mode 100644 index c22ee063e1e..00000000000 --- a/Documentation/i2c/busses/i2c-parport-light +++ /dev/null @@ -1,22 +0,0 @@ -Kernel driver i2c-parport-light - -Author: Jean Delvare <khali@linux-fr.org> - -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 -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 deleted file mode 100644 index b044e526548..00000000000 --- a/Documentation/i2c/busses/i2c-pca-isa +++ /dev/null @@ -1,23 +0,0 @@ -Kernel driver i2c-pca-isa - -Supported adapters: -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 - -Module Parameters ------------------ - -* base int - I/O base address -* irq 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 diff --git a/Documentation/i2c/busses/i2c-piix4 b/Documentation/i2c/busses/i2c-piix4 deleted file mode 100644 index 475bb4ae072..00000000000 --- a/Documentation/i2c/busses/i2c-piix4 +++ /dev/null @@ -1,100 +0,0 @@ -Kernel driver i2c-piix4 - -Supported adapters: - * Intel 82371AB PIIX4 and PIIX4E - * Intel 82443MX (440MX) - Datasheet: Publicly available at the Intel website - * 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 - * AMD Hudson-2 - Datasheet: Not publicly available - * Standard Microsystems (SMSC) SLC90E66 (Victory66) southbridge - Datasheet: Publicly available at the SMSC website http://www.smsc.com - -Authors: - Frodo Looijaard <frodol@dds.nl> - Philip Edelbrock <phil@netroedge.com> - - -Module Parameters ------------------ - -* force: int - Forcibly enable the PIIX4. DANGEROUS! -* force_addr: int - Forcibly enable the PIIX4 at the given address. EXTREMELY DANGEROUS! - - -Description ------------ - -The PIIX4 (properly known as the 82371AB) is an Intel chip with a lot of -functionality. Among other things, it implements the PCI bus. One of its -minor functions is implementing a System Management Bus. This is a true -SMBus - you can not access it on I2C levels. The good news is that it -natively understands SMBus commands and you do not have to worry about -timing problems. The bad news is that non-SMBus devices connected to it can -confuse it mightily. Yes, this is known to happen... - -Do 'lspci -v' and see whether it contains an entry like this: - -0000:00:02.3 Bridge: Intel Corp. 82371AB/EB/MB PIIX4 ACPI (rev 02) - Flags: medium devsel, IRQ 9 - -Bus and device numbers may differ, but the function number must be -identical (like many PCI devices, the PIIX4 incorporates a number of -different 'functions', which can be considered as separate devices). If you -find such an entry, you have a PIIX4 SMBus controller. - -On some computers (most notably, some Dells), the SMBus is disabled by -default. If you use the insmod parameter 'force=1', the kernel module will -try to enable it. THIS IS VERY DANGEROUS! If the BIOS did not set up a -correct address for this module, you could get in big trouble (read: -crashes, data corruption, etc.). Try this only as a last resort (try BIOS -updates first, for example), and backup first! An even more dangerous -option is 'force_addr=<IOPORT>'. This will not only enable the PIIX4 like -'force' foes, but it will also set a new base I/O port address. The SMBus -parts of the PIIX4 needs a range of 8 of these addresses to function -correctly. If these addresses are already reserved by some other device, -you will get into big trouble! DON'T USE THIS IF YOU ARE NOT VERY SURE -ABOUT WHAT YOU ARE DOING! - -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 Victory66 are -identical to the PIIX4 in I2C/SMBus support. - -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-sis5595 b/Documentation/i2c/busses/i2c-sis5595 deleted file mode 100644 index ecd21fb49a8..00000000000 --- a/Documentation/i2c/busses/i2c-sis5595 +++ /dev/null @@ -1,59 +0,0 @@ -Kernel driver i2c-sis5595 - -Authors: - Frodo Looijaard <frodol@dds.nl>, - Mark D. Studebaker <mdsxyz123@yahoo.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 - -Module Parameters ------------------ - -* force_addr=0xaddr Set the I/O base address. Useful for boards - that don't set the address in the BIOS. Does not do a - PCI force; the device must still be present in lspci. - Don't use this unless the driver complains that the - base address is not set. - -Description ------------ - -i2c-sis5595 is a true SMBus host driver for motherboards with the SiS5595 -southbridges. - -WARNING: If you are trying to access the integrated sensors on the SiS5595 -chip, you want the sis5595 driver for those, not this driver. This driver -is a BUS driver, not a CHIP driver. A BUS driver is used by other CHIP -drivers to access chips on the bus. - diff --git a/Documentation/i2c/busses/i2c-sis630 b/Documentation/i2c/busses/i2c-sis630 deleted file mode 100644 index 0b969736693..00000000000 --- a/Documentation/i2c/busses/i2c-sis630 +++ /dev/null @@ -1,49 +0,0 @@ -Kernel driver i2c-sis630 - -Supported adapters: - * Silicon Integrated Systems Corp (SiS) - 630 chipset (Datasheet: available at http://www.sfr-fresh.com/linux) - 730 chipset - * Possible other SiS chipsets ? - -Author: Alexander Malysh <amalysh@web.de> - -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 - faster, but freeze some systems (i.e. my Laptop). - - -Description ------------ - -This SMBus only driver is known to work on motherboards with the above -named chipsets. - -If you see something like this: - -00:00.0 Host bridge: Silicon Integrated Systems [SiS] 630 Host (rev 31) -00:01.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513 - -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 - -in your 'lspci' output , then this driver is for your chipset. - -Thank You ---------- -Philip Edelbrock <phil@netroedge.com> -- testing SiS730 support -Mark M. Hoffman <mhoffman@lightlink.com> -- bug fixes - -To anyone else which I forgot here ;), thanks! - diff --git a/Documentation/i2c/busses/i2c-sis96x b/Documentation/i2c/busses/i2c-sis96x deleted file mode 100644 index 0b979f3252a..00000000000 --- a/Documentation/i2c/busses/i2c-sis96x +++ /dev/null @@ -1,73 +0,0 @@ -Kernel driver i2c-sis96x - -Replaces 2.4.x i2c-sis645 - -Supported adapters: - * Silicon Integrated Systems Corp (SiS) - 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) - -Author: Mark M. Hoffman <mhoffman@lightlink.com> - -Description ------------ - -This SMBus only driver is known to work on motherboards with the above -named chipset combinations. The driver was developed without benefit of a -proper datasheet from SiS. The SMBus registers are assumed compatible with -those of the SiS630, although they are located in a completely different -place. Thanks to Alexander Malysh <amalysh@web.de> for providing the -SiS630 datasheet (and driver). - -The command "lspci" as root should produce something like these lines: - -00:00.0 Host bridge: Silicon Integrated Systems [SiS]: Unknown device 0645 -00:02.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513 -00:02.1 SMBus: Silicon Integrated Systems [SiS]: Unknown device 0016 - -or perhaps this... - -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 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 linux-i2c mailing list: <linux-i2c@vger.kernel.org>. Please send bug -reports and/or success stories as well. - - -TO DOs ------- - -* The driver does not support SMBus block reads/writes; I may add them if a -scenario is found where they're needed. - - -Thank You ---------- - -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> - - patch for SiS735 -Robert Zwerus <arzie@dds.nl> - - testing for SiS645DX -Kianusch Sayah Karadji <kianusch@sk-tech.net> - - patch for SiS645DX/962 -Ken Healy - - patch for SiS655 - -To anyone else who has written w/ feedback, thanks! - diff --git a/Documentation/i2c/busses/i2c-taos-evm b/Documentation/i2c/busses/i2c-taos-evm deleted file mode 100644 index 63f62bcbf59..00000000000 --- a/Documentation/i2c/busses/i2c-taos-evm +++ /dev/null @@ -1,46 +0,0 @@ -Kernel driver i2c-taos-evm - -Author: Jean Delvare <khali@linux-fr.org> - -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 deleted file mode 100644 index 343870661ac..00000000000 --- a/Documentation/i2c/busses/i2c-via +++ /dev/null @@ -1,34 +0,0 @@ -Kernel driver i2c-via - -Supported adapters: - * VIA Technologies, InC. VT82C586B - Datasheet: Publicly available at the VIA website - -Author: Kyösti Mälkki <kmalkki@cc.hut.fi> - -Description ------------ - -i2c-via is an i2c bus driver for motherboards with VIA chipset. - -The following VIA pci chipsets are supported: - - MVP3, VP3, VP2/97, VPX/97 - - others with South bridge VT82C586B - -Your lspci listing must show this : - - Bridge: VIA Technologies, Inc. VT82C586B ACPI (rev 10) - - Problems? - - Q: You have VT82C586B on the motherboard, but not in the listing. - - A: Go to your BIOS setup, section PCI devices or similar. - Turn USB support on, and try again. - - Q: No error messages, but still i2c doesn't seem to work. - - A: This can happen. This driver uses the pins VIA recommends in their - datasheets, but there are several ways the motherboard manufacturer - can actually wire the lines. - diff --git a/Documentation/i2c/busses/i2c-viapro b/Documentation/i2c/busses/i2c-viapro deleted file mode 100644 index 2e758b0e945..00000000000 --- a/Documentation/i2c/busses/i2c-viapro +++ /dev/null @@ -1,69 +0,0 @@ -Kernel driver i2c-viapro - -Supported adapters: - * VIA Technologies, Inc. VT82C596A/B - Datasheet: Sometimes available at the VIA website - - * VIA Technologies, Inc. VT82C686A/B - Datasheet: Sometimes available at the VIA website - - * 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: Availability unknown - -Authors: - Kyösti Mälkki <kmalkki@cc.hut.fi>, - Mark D. Studebaker <mdsxyz123@yahoo.com>, - Jean Delvare <khali@linux-fr.org> - -Module Parameters ------------------ - -* force: int - Forcibly enable the SMBus controller. DANGEROUS! -* force_addr: int - Forcibly enable the SMBus at the given address. EXTREMELY DANGEROUS! - -Description ------------ - -i2c-viapro is a true SMBus host driver for motherboards with one of the -supported VIA south bridges. - -Your lspci -n listing must show one of these : - - device 1106:3050 (VT82C596A function 3) - device 1106:3051 (VT82C596B function 3) - device 1106:3057 (VT82C686 function 4) - device 1106:3074 (VT8233) - device 1106:3147 (VT8233A) - 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) - -If none of these show up, you should look in the BIOS for settings like -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/scx200_acb b/Documentation/i2c/busses/scx200_acb deleted file mode 100644 index ce83c871fe9..00000000000 --- a/Documentation/i2c/busses/scx200_acb +++ /dev/null @@ -1,32 +0,0 @@ -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: 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 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/dev-interface b/Documentation/i2c/dev-interface deleted file mode 100644 index 3e742ba2553..00000000000 --- a/Documentation/i2c/dev-interface +++ /dev/null @@ -1,214 +0,0 @@ -Usually, i2c devices are controlled by a kernel driver. But it is also -possible to access all devices on an adapter from userspace, through -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, ..., -i2c-10, ...). All 256 minor device numbers are reserved for i2c. - - -C example -========= - -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 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/ 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]; - - 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) { - /* ERROR HANDLING; you can check errno to see what went wrong */ - exit(1); - } - -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); - 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) */ - buf[0] = register; - buf[1] = 0x43; - buf[2] = 0x65; - 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) { - /* 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! - - -Full interface description -========================== - -The following IOCTLs are defined: - -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) - Selects ten bit addresses if select not equals 0, selects normal 7 bit - 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) - 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. 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) - Gets the adapter functionality and puts it in *funcs. - -ioctl(file, I2C_RDWR, struct i2c_rdwr_ioctl_data *msgset) - Do combined read/write transaction without stop in between. - 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 */ - } - - The msgs[] themselves contain further pointers into data buffers. - The function will write or read data to or from that buffers depending - on whether the I2C_M_RD flag is set in a particular message or not. - 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. - -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 -ioctl I2C_SLAVE before you try to access the device. - -You can do SMBus level transactions (see documentation file smbus-protocol -for details) through the following functions: - __s32 i2c_smbus_write_quick(int file, __u8 value); - __s32 i2c_smbus_read_byte(int file); - __s32 i2c_smbus_write_byte(int file, __u8 value); - __s32 i2c_smbus_read_byte_data(int file, __u8 command); - __s32 i2c_smbus_write_byte_data(int file, __u8 command, __u8 value); - __s32 i2c_smbus_read_word_data(int file, __u8 command); - __s32 i2c_smbus_write_word_data(int file, __u8 command, __u16 value); - __s32 i2c_smbus_process_call(int file, __u8 command, __u16 value); - __s32 i2c_smbus_read_block_data(int file, __u8 command, __u8 *values); - __s32 i2c_smbus_write_block_data(int file, __u8 command, __u8 length, - __u8 *values); -All these transactions return -1 on failure; you can read errno to see -what happened. 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. - -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 deleted file mode 100644 index 045765c0b9b..00000000000 --- a/Documentation/i2c/fault-codes +++ /dev/null @@ -1,127 +0,0 @@ -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. - - One example would be a driver trying an SMBus Block Write - with block size outside the range of 1-32 bytes. - -EIO - This rather vague error means something went wrong when - performing an I/O operation. Use a more specific fault - 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 deleted file mode 100644 index b0ff2ab596c..00000000000 --- a/Documentation/i2c/functionality +++ /dev/null @@ -1,148 +0,0 @@ -INTRODUCTION ------------- - -Because not every I2C or SMBus adapter implements everything in the -I2C specifications, a client can not trust that everything it needs -is implemented when it is given the option to attach to an adapter: -the client needs some way to check whether an adapter has the needed -functionality. - - -FUNCTIONALITY CONSTANTS ------------------------ - -For the most up-to-date list of functionality constants, please check -<linux/i2c.h>! - - I2C_FUNC_I2C Plain i2c-level commands (Pure SMBus - 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 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 - I2C_FUNC_SMBUS_READ_BYTE_DATA Handles the SMBus read_byte_data command - I2C_FUNC_SMBUS_WRITE_BYTE_DATA Handles the SMBus write_byte_data command - I2C_FUNC_SMBUS_READ_WORD_DATA Handles the SMBus read_word_data command - I2C_FUNC_SMBUS_WRITE_WORD_DATA Handles the SMBus write_byte_data command - I2C_FUNC_SMBUS_PROC_CALL Handles the SMBus process_call command - I2C_FUNC_SMBUS_READ_BLOCK_DATA Handles the SMBus read_block_data command - I2C_FUNC_SMBUS_WRITE_BLOCK_DATA Handles the SMBus write_block_data command - I2C_FUNC_SMBUS_READ_I2C_BLOCK Handles the SMBus read_i2c_block_data command - I2C_FUNC_SMBUS_WRITE_I2C_BLOCK Handles the SMBus write_i2c_block_data command - -A few combinations of the above flags are also defined for your convenience: - - I2C_FUNC_SMBUS_BYTE Handles the SMBus read_byte - and write_byte commands - I2C_FUNC_SMBUS_BYTE_DATA Handles the SMBus read_byte_data - and write_byte_data commands - I2C_FUNC_SMBUS_WORD_DATA Handles the SMBus read_word_data - and write_word_data commands - I2C_FUNC_SMBUS_BLOCK_DATA Handles the SMBus read_block_data - 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 - emulated by a real I2C adapter (using - the transparent emulation layer) - -In kernel versions prior to 3.5 I2C_FUNC_NOSTART was implemented as -part of I2C_FUNC_PROTOCOL_MANGLING. - - -ADAPTER IMPLEMENTATION ----------------------- - -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 typical full-I2C adapter would use the following (from the i2c-pxa -driver): - - static u32 i2c_pxa_functionality(struct i2c_adapter *adap) - { - 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 ---------------- - -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. The typical way to do -this is (from the lm75 driver): - - static int lm75_detect(...) - { - (...) - 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 ---------------------- - -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 i2cdetect program, is -below: - - int file; - if (file = open("/dev/i2c-0", O_RDWR) < 0) { - /* Some kind of error handling */ - exit(1); - } - if (ioctl(file, I2C_FUNCS, &funcs) < 0) { - /* Some kind of error handling */ - exit(1); - } - if (!(funcs & I2C_FUNC_SMBUS_QUICK)) { - /* Oops, the needed functionality (SMBus write_quick function) is - not available! */ - exit(1); - } - /* Now it is safe to use the SMBus write_quick command */ diff --git a/Documentation/i2c/i2c-protocol b/Documentation/i2c/i2c-protocol deleted file mode 100644 index 0b3e62d1f77..00000000000 --- a/Documentation/i2c/i2c-protocol +++ /dev/null @@ -1,83 +0,0 @@ -This document describes the i2c protocol. Or will, when it is finished :-) - -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 - get a 10 bit I2C address. -Comm (8 bits): Command byte, a data byte which often selects a register on - the device. -Data (8 bits): A plain data byte. Sometimes, I write DataLow, DataHigh - for 16 bit data. -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. - - -Simple send transaction -====================== - -This corresponds to i2c_master_send. - - S Addr Wr [A] Data [A] Data [A] ... [A] Data [A] P - - -Simple receive transaction -=========================== - -This corresponds to i2c_master_recv - - S Addr Rd [A] [Data] A [Data] A ... A [Data] NA P - - -Combined transactions -==================== - -This corresponds to i2c_transfer - -They are just like the above transactions, but instead of a stop bit P -a start bit S is sent and the transaction continues. An example of -a byte read, followed by a byte write: - - S Addr Rd [A] [Data] NA S Addr Wr [A] Data [A] P - - -Modified transactions -===================== - -The following modifications to the I2C protocol can also be generated, -with the exception of I2C_M_NOSTART these are usually only needed to -work around device issues: - - Flag 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: - S Addr Rd [A] [Data] NA Data [A] P - If you set the I2C_M_NOSTART variable for the first partial message, - 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. - - 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. - - Flags 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. diff --git a/Documentation/i2c/i2c-stub b/Documentation/i2c/i2c-stub deleted file mode 100644 index fa4b669c166..00000000000 --- a/Documentation/i2c/i2c-stub +++ /dev/null @@ -1,53 +0,0 @@ -MODULE: i2c-stub - -DESCRIPTION: - -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 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 -EEPROMs, among others. - -The typical use-case is like this: - 1. load this module - 2. use i2cset (from the i2c-tools project) to pre-load some data - 3. load the target chip driver module - 4. observe its behavior in the kernel log - -There's a script named i2c-stub-from-dump in the i2c-tools package which -can load register values automatically from a chip dump. - -PARAMETERS: - -int chip_addr[10]: - The SMBus addresses to emulate chips at. - -unsigned long functionality: - Functionality override, to disable some commands. See I2C_FUNC_* - constants in <linux/i2c.h> for the suitable values. For example, - value 0x1f0000 would only enable the quick, byte and byte data - commands. - -CAVEATS: - -If your target driver polls some byte or word waiting for it to change, the -stub could lock it up. Use i2cset to unlock it. - -If the hardware for your driver has banked registers (e.g. Winbond sensors -chips) this module will not work well - although it could be extended to -support that pretty easily. - -If you spam it hard enough, printk can be lossy. This module really wants -something like relayfs. - diff --git a/Documentation/i2c/instantiating-devices b/Documentation/i2c/instantiating-devices deleted file mode 100644 index abf63615ee0..00000000000 --- a/Documentation/i2c/instantiating-devices +++ /dev/null @@ -1,211 +0,0 @@ -How to instantiate I2C devices -============================== - -Unlike PCI or USB devices, I2C devices are not enumerated at the hardware -level. Instead, the software must know which devices are connected on each -I2C bus segment, and what address these devices are using. For this -reason, the kernel code must instantiate I2C devices explicitly. There are -several ways to achieve this, depending on the context and requirements. - - -Method 1: Declare the I2C devices by bus number ------------------------------------------------ - -This method is appropriate when the I2C bus is a system bus as is the case -for many embedded systems. On such systems, each I2C bus has a number -which is known in advance. It is thus possible to pre-declare the I2C -devices which live on this bus. This is done with an array of struct -i2c_board_info which is registered by calling i2c_register_board_info(). - -Example (from omap2 h4): - -static struct i2c_board_info __initdata h4_i2c_board_info[] = { - { - I2C_BOARD_INFO("isp1301_omap", 0x2d), - .irq = OMAP_GPIO_IRQ(125), - }, - { /* EEPROM on mainboard */ - I2C_BOARD_INFO("24c01", 0x52), - .platform_data = &m24c01, - }, - { /* EEPROM on cpu card */ - I2C_BOARD_INFO("24c01", 0x57), - .platform_data = &m24c01, - }, -}; - -static void __init omap_h4_init(void) -{ - (...) - i2c_register_board_info(1, h4_i2c_board_info, - ARRAY_SIZE(h4_i2c_board_info)); - (...) -} - -The above code declares 3 devices on I2C bus 1, including their respective -addresses and custom data needed by their drivers. When the I2C bus in -question is registered, the I2C devices will be instantiated automatically -by i2c-core. - -The devices will be automatically unbound and destroyed when the I2C bus -they sit on goes away (if ever.) - - -Method 2: Instantiate the devices explicitly --------------------------------------------- - -This method is appropriate when a larger device uses an I2C bus for -internal communication. A typical case is TV adapters. These can have a -tuner, a video decoder, an audio decoder, etc. usually connected to the -main chip by the means of an I2C bus. You won't know the number of the I2C -bus in advance, so the method 1 described above can't be used. Instead, -you can instantiate your I2C devices explicitly. This is done by filling -a struct i2c_board_info and calling i2c_new_device(). - -Example (from the sfe4001 network driver): - -static struct i2c_board_info sfe4001_hwmon_info = { - I2C_BOARD_INFO("max6647", 0x4e), -}; - -int sfe4001_init(struct efx_nic *efx) -{ - (...) - efx->board_info.hwmon_client = - i2c_new_device(&efx->i2c_adap, &sfe4001_hwmon_info); - - (...) -} - -The above code instantiates 1 I2C device on the I2C bus which is on the -network adapter in question. - -A variant of this is when you don't know for sure if an I2C device is -present or not (for example for an optional feature which is not present -on cheap variants of a board but you have no way to tell them apart), or -it may have different addresses from one board to the next (manufacturer -changing its design without notice). In this case, you can call -i2c_new_probed_device() instead of i2c_new_device(). - -Example (from the nxp OHCI driver): - -static const unsigned short normal_i2c[] = { 0x2c, 0x2d, I2C_CLIENT_END }; - -static int __devinit 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 deleted file mode 100644 index bd9b2299b73..00000000000 --- a/Documentation/i2c/muxes/i2c-mux-gpio +++ /dev/null @@ -1,65 +0,0 @@ -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, - }, -}; diff --git a/Documentation/i2c/old-module-parameters b/Documentation/i2c/old-module-parameters deleted file mode 100644 index 8e2b629d533..00000000000 --- a/Documentation/i2c/old-module-parameters +++ /dev/null @@ -1,44 +0,0 @@ -I2C device driver binding control from user-space -================================================= - -Up to kernel 2.6.32, many i2c drivers used helper macros provided by -<linux/i2c.h> which created standard module parameters to let the user -control how the driver would probe i2c buses and attach to devices. These -parameters were known as "probe" (to let the driver probe for an extra -address), "force" (to forcibly attach the driver to a given device) and -"ignore" (to prevent a driver from probing a given address). - -With the conversion of the i2c subsystem to the standard device driver -binding model, it became clear that these per-module parameters were no -longer needed, and that a centralized implementation was possible. The new, -sysfs-based interface is described in the documentation file -"instantiating-devices", section "Method 4: Instantiate from user-space". - -Below is a mapping from the old module parameters to the new interface. - -Attaching a driver to an I2C device ------------------------------------ - -Old method (module parameters): -# modprobe <driver> probe=1,0x2d -# modprobe <driver> force=1,0x2d -# modprobe <driver> force_<device>=1,0x2d - -New method (sysfs interface): -# echo <device> 0x2d > /sys/bus/i2c/devices/i2c-1/new_device - -Preventing a driver from attaching to an I2C device ---------------------------------------------------- - -Old method (module parameters): -# modprobe <driver> ignore=1,0x2f - -New method (sysfs interface): -# echo dummy 0x2f > /sys/bus/i2c/devices/i2c-1/new_device -# modprobe <driver> - -Of course, it is important to instantiate the "dummy" device before loading -the driver. The dummy device will be handled by i2c-core itself, preventing -other drivers from binding to it later on. If there is a real device at the -problematic address, and you want another driver to bind to it, then simply -pass the name of the device in question instead of "dummy". diff --git a/Documentation/i2c/smbus-protocol b/Documentation/i2c/smbus-protocol deleted file mode 100644 index 49f5b680809..00000000000 --- a/Documentation/i2c/smbus-protocol +++ /dev/null @@ -1,251 +0,0 @@ -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 -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 -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 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. - - -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 - get a 10 bit I2C address. -Comm (8 bits): Command byte, a data byte which often selects a register on - the device. -Data (8 bits): A plain data byte. Sometimes, I write DataLow, DataHigh - for 16 bit data. -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 Quick Command -=================== - -This sends a single bit to the device, at the place of the Rd/Wr bit. - -A Addr Rd/Wr [A] P - - -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 -others, it is a shorthand if you want to read the same register as in -the previous SMBus command. - -S Addr Rd [A] [Data] NA P - - -SMBus Send Byte: i2c_smbus_write_byte() -======================================== - -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 - - -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 - - -SMBus Read Word: i2c_smbus_read_word_data() -============================================ - -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 - -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 operation. - -S Addr Wr [A] Comm [A] Data [A] P - - -SMBus Write Word: i2c_smbus_write_word_data() -============================================== - -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 - -Note the convenience function i2c_smbus_write_word_swapped is -available for writes where the two data bytes are the other way -around (not SMBus compliant, but very popular.) - - -SMBus Process Call: i2c_smbus_process_call() -============================================= - -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. - -S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A] - S Addr Rd [A] [DataLow] A [DataHigh] NA P - - -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 -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 - - -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 -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 - - -SMBus Block Write - Block Read Process Call -=========================================== - -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. - -S Addr Wr [A] Comm [A] Count [A] Data [A] ... - S Addr Rd [A] [Count] A [Data] ... A P - - -SMBus Host Notify -================= - -This command is sent from a SMBus device acting as a master to the -SMBus host acting as a slave. -It is the same form as Write Word, with the command code replaced by the -alerting device's address. - -[S] [HostAddr] [Wr] A [DevAddr] A [DataLow] A [DataHigh] A [P] - - -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 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. - -ARP adds device enumeration and dynamic address assignment to -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_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. - -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 - - -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 -Comm byte. Note that command lengths of 0, 2, or more bytes are -supported as they are indistinguishable from data. - -S Addr Wr [A] Comm [A] Data [A] Data [A] ... [A] Data [A] P diff --git a/Documentation/i2c/summary b/Documentation/i2c/summary deleted file mode 100644 index 13ab076dcd9..00000000000 --- a/Documentation/i2c/summary +++ /dev/null @@ -1,47 +0,0 @@ -I2C and SMBus -============= - -I2C (pronounce: I squared C) is a protocol developed by Philips. It is a -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 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 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 -=========== - -When we talk about I2C, we use the following terms: - Bus -> Algorithm - Adapter - Device -> Driver - Client - -An Algorithm driver contains general code that can be used for a whole class -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, 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 deleted file mode 100644 index cdfe13901b9..00000000000 --- a/Documentation/i2c/ten-bit-addresses +++ /dev/null @@ -1,24 +0,0 @@ -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). - -I2C messages to and from 10-bit address devices have a different format. -See the I2C specification for the details. - -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 deleted file mode 100644 index d6991625c40..00000000000 --- a/Documentation/i2c/upgrading-clients +++ /dev/null @@ -1,281 +0,0 @@ -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 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 deleted file mode 100644 index 5aa53374ea2..00000000000 --- a/Documentation/i2c/writing-clients +++ /dev/null @@ -1,396 +0,0 @@ -This is a small guide for those who want to write kernel drivers for I2C -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 -guide, not as a rule book! - - -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 -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. - - -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, 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 = { - .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 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 -below. - - -Extra client data -================= - -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 -==================== - -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. - -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. - -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 -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 -===================== - -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 ---------------------- - -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. - -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. - - 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. - - -Device Creation ---------------- - -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); -} - -static void __exit foo_cleanup(void) -{ - i2c_del_driver(&foo_driver); -} - -/* 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"); - -module_init(foo_init); -module_exit(foo_cleanup); - -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. - - -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. - - -Command function -================ - -A generic ioctl-like function call back is supported. You will seldom -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 <linux/i2c.h>. - -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 ------------------------ - - 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 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 -stop bit is sent between transaction. The i2c_msg structure contains -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. - - -SMBus communication -------------------- - - 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_process_call(struct i2c_client *client, - u8 command, u16 value); - s32 i2c_smbus_read_block_data(struct i2c_client *client, - u8 command, u8 *values); - s32 i2c_smbus_write_block_data(struct i2c_client *client, - 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: - - s32 i2c_smbus_write_quick(struct i2c_client *client, u8 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. - - -General purpose routines -======================== - -Below all general purpose routines are listed, that were not mentioned -before. - - /* Return the adapter number for a specific adapter */ - int i2c_adapter_id(struct i2c_adapter *adap); |