Linux-2.6.12-rc2
Initial git repository build. I'm not bothering with the full history,
even though we have it. We can create a separate "historical" git
archive of that later if we want to, and in the meantime it's about
3.2GB when imported into git - space that would just make the early
git days unnecessarily complicated, when we don't have a lot of good
infrastructure for it.
Let it rip!
diff --git a/Documentation/i2c/busses/i2c-ali1535 b/Documentation/i2c/busses/i2c-ali1535
new file mode 100644
index 0000000..0db3b4c
--- /dev/null
+++ b/Documentation/i2c/busses/i2c-ali1535
@@ -0,0 +1,42 @@
+Kernel driver i2c-ali1535
+
+Supported adapters:
+ * Acer Labs, Inc. ALI 1535 (south bridge)
+ Datasheet: Now under NDA
+ http://www.ali.com.tw/eng/support/datasheet_request.php
+
+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
new file mode 100644
index 0000000..99ad4b9
--- /dev/null
+++ b/Documentation/i2c/busses/i2c-ali1563
@@ -0,0 +1,27 @@
+Kernel driver i2c-ali1563
+
+Supported adapters:
+ * Acer Labs, Inc. ALI 1563 (south bridge)
+ Datasheet: Now under NDA
+ http://www.ali.com.tw/eng/support/datasheet_request.php
+
+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
new file mode 100644
index 0000000..ff28d38
--- /dev/null
+++ b/Documentation/i2c/busses/i2c-ali15x3
@@ -0,0 +1,112 @@
+Kernel driver i2c-ali15x3
+
+Supported adapters:
+ * Acer Labs, Inc. ALI 1533 and 1543C (south bridge)
+ Datasheet: Now under NDA
+ http://www.ali.com.tw/eng/support/datasheet_request.php
+
+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
new file mode 100644
index 0000000..67f3087
--- /dev/null
+++ b/Documentation/i2c/busses/i2c-amd756
@@ -0,0 +1,25 @@
+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
new file mode 100644
index 0000000..db294ee
--- /dev/null
+++ b/Documentation/i2c/busses/i2c-amd8111
@@ -0,0 +1,41 @@
+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 publically 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-i801 b/Documentation/i2c/busses/i2c-i801
new file mode 100644
index 0000000..fd4b271
--- /dev/null
+++ b/Documentation/i2c/busses/i2c-i801
@@ -0,0 +1,80 @@
+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, 32 byte buffer not supported)
+ * Intel 82801EB/ER (ICH5) (HW PEC supported, 32 byte buffer not supported)
+ * Intel 6300ESB
+ * Intel 82801FB/FR/FW/FRW (ICH6)
+ * Intel ICH7
+ Datasheets: Publicly available at the Intel website
+
+Authors:
+ Frodo Looijaard <frodol@dds.nl>,
+ Philip Edelbrock <phil@netroedge.com>,
+ Mark Studebaker <mdsxyz123@yahoo.com>
+
+
+Module Parameters
+-----------------
+
+* force_addr: int
+ Forcibly enable the ICH at the given address. EXTREMELY DANGEROUS!
+
+
+Description
+-----------
+
+The ICH (properly known as the 82801AA), ICH0 (82801AB), ICH2 (82801BA),
+ICH3 (82801CA/CAM) and later devices are Intel chips that are a part of
+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.
+
+If you do NOT see the 24x3 device at function 3, and you can't figure out
+any way in the BIOS to enable it,
+
+The ICH chips are quite similar to Intel's PIIX4 chip, at least in the
+SMBus controller.
+
+See the file i2c-piix4 for some additional information.
+
+
+Process Call Support
+--------------------
+
+Not supported.
+
+
+I2C Block Read Support
+----------------------
+
+Not supported at the moment.
+
+
+SMBus 2.0 Support
+-----------------
+
+The 82801DB (ICH4) and later chips support several SMBus 2.0 features.
+
+**********************
+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-i810 b/Documentation/i2c/busses/i2c-i810
new file mode 100644
index 0000000..0544eb3
--- /dev/null
+++ b/Documentation/i2c/busses/i2c-i810
@@ -0,0 +1,46 @@
+Kernel driver i2c-i810
+
+Supported adapters:
+ * Intel 82810, 82810-DC100, 82810E, and 82815 (GMCH)
+
+Authors:
+ Frodo Looijaard <frodol@dds.nl>,
+ Philip Edelbrock <phil@netroedge.com>,
+ Kyösti Mälkki <kmalkki@cc.hut.fi>,
+ Ralph Metzler <rjkm@thp.uni-koeln.de>,
+ Mark D. Studebaker <mdsxyz123@yahoo.com>
+
+Main contact: Mark Studebaker <mdsxyz123@yahoo.com>
+
+Description
+-----------
+
+WARNING: If you have an '810' or '815' motherboard, your standard I2C
+temperature sensors are most likely on the 801's I2C bus. You want the
+i2c-i801 driver for those, not this driver.
+
+Now for the i2c-i810...
+
+The GMCH chip contains two I2C interfaces.
+
+The first interface is used for DDC (Data Display Channel) which is a
+serial channel through the VGA monitor connector to a DDC-compliant
+monitor. This interface is defined by the Video Electronics Standards
+Association (VESA). The standards are available for purchase at
+http://www.vesa.org .
+
+The second interface is a general-purpose I2C bus. It may be connected to a
+TV-out chip such as the BT869 or possibly to a digital flat-panel display.
+
+Features
+--------
+
+Both busses use the i2c-algo-bit driver for 'bit banging'
+and support for specific transactions is provided by i2c-algo-bit.
+
+Issues
+------
+
+If you enable bus testing in i2c-algo-bit (insmod i2c-algo-bit bit_test=1),
+the test may fail; if so, the i2c-i810 driver won't be inserted. However,
+we think this has been fixed.
diff --git a/Documentation/i2c/busses/i2c-nforce2 b/Documentation/i2c/busses/i2c-nforce2
new file mode 100644
index 0000000..e379e18
--- /dev/null
+++ b/Documentation/i2c/busses/i2c-nforce2
@@ -0,0 +1,41 @@
+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
+
+Datasheet: not publically available, but seems to be similar to the
+ AMD-8111 SMBus 2.0 adapter.
+
+Authors:
+ Hans-Frieder Vogt <hfvogt@arcor.de>,
+ 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 southbridge. 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-parport b/Documentation/i2c/busses/i2c-parport
new file mode 100644
index 0000000..9f1d008
--- /dev/null
+++ b/Documentation/i2c/busses/i2c-parport
@@ -0,0 +1,154 @@
+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:
+ * Philips adapter
+ * home brew teletext adapter
+ * Velleman K8000 adapter
+ * ELV adapter
+ * Analog Devices evaluation boards (ADM1025, ADM1030, ADM1031, ADM1032)
+
+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.
+
+
+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/
diff --git a/Documentation/i2c/busses/i2c-parport-light b/Documentation/i2c/busses/i2c-parport-light
new file mode 100644
index 0000000..2874364
--- /dev/null
+++ b/Documentation/i2c/busses/i2c-parport-light
@@ -0,0 +1,11 @@
+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
+prefered 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.
diff --git a/Documentation/i2c/busses/i2c-pca-isa b/Documentation/i2c/busses/i2c-pca-isa
new file mode 100644
index 0000000..6fc8f4c
--- /dev/null
+++ b/Documentation/i2c/busses/i2c-pca-isa
@@ -0,0 +1,23 @@
+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
new file mode 100644
index 0000000..856b4b8
--- /dev/null
+++ b/Documentation/i2c/busses/i2c-piix4
@@ -0,0 +1,72 @@
+Kernel driver i2c-piix4
+
+Supported adapters:
+ * Intel 82371AB PIIX4 and PIIX4E
+ * Intel 82443MX (440MX)
+ Datasheet: Publicly available at the Intel website
+ * ServerWorks OSB4, CSB5 and CSB6 southbridges
+ Datasheet: Only available via NDA from ServerWorks
+ * 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!
+* fix_hstcfg: int
+ Fix config register. Needed on some boards (Force CPCI735).
+
+
+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 Victory766 are
+identical to the PIIX4 in I2C/SMBus support.
+
+A few OSB4 southbridges are known to be misconfigured by the BIOS. In this
+case, you have you use the fix_hstcfg module parameter. Do not use it
+unless you know you have to, because in some cases it also breaks
+configuration on southbridges that don't need it.
diff --git a/Documentation/i2c/busses/i2c-prosavage b/Documentation/i2c/busses/i2c-prosavage
new file mode 100644
index 0000000..7036879
--- /dev/null
+++ b/Documentation/i2c/busses/i2c-prosavage
@@ -0,0 +1,23 @@
+Kernel driver i2c-prosavage
+
+Supported adapters:
+
+ S3/VIA KM266/VT8375 aka ProSavage8
+ S3/VIA KM133/VT8365 aka Savage4
+
+Author: Henk Vergonet <henk@god.dyndns.org>
+
+Description
+-----------
+
+The Savage4 chips contain two I2C interfaces (aka a I2C 'master' or
+'host').
+
+The first interface is used for DDC (Data Display Channel) which is a
+serial channel through the VGA monitor connector to a DDC-compliant
+monitor. This interface is defined by the Video Electronics Standards
+Association (VESA). The standards are available for purchase at
+http://www.vesa.org . The second interface is a general-purpose I2C bus.
+
+Usefull for gaining access to the TV Encoder chips.
+
diff --git a/Documentation/i2c/busses/i2c-savage4 b/Documentation/i2c/busses/i2c-savage4
new file mode 100644
index 0000000..6ecceab
--- /dev/null
+++ b/Documentation/i2c/busses/i2c-savage4
@@ -0,0 +1,26 @@
+Kernel driver i2c-savage4
+
+Supported adapters:
+ * Savage4
+ * Savage2000
+
+Authors:
+ Alexander Wold <awold@bigfoot.com>,
+ Mark D. Studebaker <mdsxyz123@yahoo.com>
+
+Description
+-----------
+
+The Savage4 chips contain two I2C interfaces (aka a I2C 'master'
+or 'host').
+
+The first interface is used for DDC (Data Display Channel) which is a
+serial channel through the VGA monitor connector to a DDC-compliant
+monitor. This interface is defined by the Video Electronics Standards
+Association (VESA). The standards are available for purchase at
+http://www.vesa.org . The DDC bus is not yet supported because its register
+is not directly memory-mapped.
+
+The second interface is a general-purpose I2C bus. This is the only
+interface supported by the driver at the moment.
+
diff --git a/Documentation/i2c/busses/i2c-sis5595 b/Documentation/i2c/busses/i2c-sis5595
new file mode 100644
index 0000000..cc47db7
--- /dev/null
+++ b/Documentation/i2c/busses/i2c-sis5595
@@ -0,0 +1,59 @@
+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
new file mode 100644
index 0000000..9aca688
--- /dev/null
+++ b/Documentation/i2c/busses/i2c-sis630
@@ -0,0 +1,49 @@
+Kernel driver i2c-sis630
+
+Supported adapters:
+ * Silicon Integrated Systems Corp (SiS)
+ 630 chipset (Datasheet: available at http://amalysh.bei.t-online.de/docs/SIS/)
+ 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-sis69x b/Documentation/i2c/busses/i2c-sis69x
new file mode 100644
index 0000000..5be4876
--- /dev/null
+++ b/Documentation/i2c/busses/i2c-sis69x
@@ -0,0 +1,73 @@
+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 cant see it please look on quirk_sis_96x_smbus
+(drivers/pci/quirks.c) (also if southbridge detection fails)
+
+I suspect that this driver could be made to work for the following SiS
+chipsets as well: 635, and 635T. If anyone owns a board with those chips
+AND is willing to risk crashing & burning an otherwise well-behaved kernel
+in the name of progress... please contact me at <mhoffman@lightlink.com> or
+via the project's mailing list: <sensors@stimpy.netroedge.com>. 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-via b/Documentation/i2c/busses/i2c-via
new file mode 100644
index 0000000..55edfe1
--- /dev/null
+++ b/Documentation/i2c/busses/i2c-via
@@ -0,0 +1,34 @@
+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
new file mode 100644
index 0000000..702f5ac
--- /dev/null
+++ b/Documentation/i2c/busses/i2c-viapro
@@ -0,0 +1,47 @@
+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, VT8235, VT8237
+ Datasheet: available on request from Via
+
+Authors:
+ Frodo Looijaard <frodol@dds.nl>,
+ Philip Edelbrock <phil@netroedge.com>,
+ Kyösti Mälkki <kmalkki@cc.hut.fi>,
+ Mark D. Studebaker <mdsxyz123@yahoo.com>
+
+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 southbridges.
+
+Your lspci -n listing must show one of these :
+
+ device 1106:3050 (VT82C596 function 3)
+ device 1106:3051 (VT82C596 function 3)
+ device 1106:3057 (VT82C686 function 4)
+ device 1106:3074 (VT8233)
+ device 1106:3147 (VT8233A)
+ device 1106:8235 (VT8231)
+ devide 1106:3177 (VT8235)
+ devide 1106:3227 (VT8237)
+
+If none of these show up, you should look in the BIOS for settings like
+enable ACPI / SMBus or even USB.
+
+
diff --git a/Documentation/i2c/busses/i2c-voodoo3 b/Documentation/i2c/busses/i2c-voodoo3
new file mode 100644
index 0000000..62d90a4
--- /dev/null
+++ b/Documentation/i2c/busses/i2c-voodoo3
@@ -0,0 +1,62 @@
+Kernel driver i2c-voodoo3
+
+Supported adapters:
+ * 3dfx Voodoo3 based cards
+ * Voodoo Banshee based cards
+
+Authors:
+ Frodo Looijaard <frodol@dds.nl>,
+ Philip Edelbrock <phil@netroedge.com>,
+ Ralph Metzler <rjkm@thp.uni-koeln.de>,
+ Mark D. Studebaker <mdsxyz123@yahoo.com>
+
+Main contact: Philip Edelbrock <phil@netroedge.com>
+
+The code is based upon Ralph's test code (he did the hard stuff ;')
+
+Description
+-----------
+
+The 3dfx Voodoo3 chip contains two I2C interfaces (aka a I2C 'master' or
+'host').
+
+The first interface is used for DDC (Data Display Channel) which is a
+serial channel through the VGA monitor connector to a DDC-compliant
+monitor. This interface is defined by the Video Electronics Standards
+Association (VESA). The standards are available for purchase at
+http://www.vesa.org .
+
+The second interface is a general-purpose I2C bus. The intent by 3dfx was
+to allow manufacturers to add extra chips to the video card such as a
+TV-out chip such as the BT869 or possibly even I2C based temperature
+sensors like the ADM1021 or LM75.
+
+Stability
+---------
+
+Seems to be stable on the test machine, but needs more testing on other
+machines. Simultaneous accesses of the DDC and I2C busses may cause errors.
+
+Supported Devices
+-----------------
+
+Specifically, this driver was written and tested on the '3dfx Voodoo3 AGP
+3000' which has a tv-out feature (s-video or composite). According to the
+docs and discussions, this code should work for any Voodoo3 based cards as
+well as Voodoo Banshee based cards. The DDC interface has been tested on a
+Voodoo Banshee card.
+
+Issues
+------
+
+Probably many, but it seems to work OK on my system. :')
+
+
+External Device Connection
+--------------------------
+
+The digital video input jumpers give availability to the I2C bus.
+Specifically, pins 13 and 25 (bottom row middle, and bottom right-end) are
+the I2C clock and I2C data lines, respectively. +5V and GND are probably
+also easily available making the addition of extra I2C/SMBus devices easy
+to implement.
diff --git a/Documentation/i2c/busses/scx200_acb b/Documentation/i2c/busses/scx200_acb
new file mode 100644
index 0000000..08c8cd1
--- /dev/null
+++ b/Documentation/i2c/busses/scx200_acb
@@ -0,0 +1,14 @@
+Kernel driver scx200_acb
+
+Author: Christer Weinigel <wingel@nano-system.com>
+
+Module Parameters
+-----------------
+
+* base: int
+ Base addresses for the ACCESS.bus controllers
+
+Description
+-----------
+
+Enable the use of the ACCESS.bus controllers of a SCx200 processor.
diff --git a/Documentation/i2c/chips/smsc47b397.txt b/Documentation/i2c/chips/smsc47b397.txt
new file mode 100644
index 0000000..389edae
--- /dev/null
+++ b/Documentation/i2c/chips/smsc47b397.txt
@@ -0,0 +1,146 @@
+November 23, 2004
+
+The following specification describes the SMSC LPC47B397-NC sensor chip
+(for which there is no public datasheet available). This document was
+provided by Craig Kelly (In-Store Broadcast Network) and edited/corrected
+by Mark M. Hoffman <mhoffman@lightlink.com>.
+
+* * * * *
+
+Methods for detecting the HP SIO and reading the thermal data on a dc7100.
+
+The thermal information on the dc7100 is contained in the SIO Hardware Monitor
+(HWM). The information is accessed through an index/data pair. The index/data
+pair is located at the HWM Base Address + 0 and the HWM Base Address + 1. The
+HWM Base address can be obtained from Logical Device 8, registers 0x60 (MSB)
+and 0x61 (LSB). Currently we are using 0x480 for the HWM Base Address and
+0x480 and 0x481 for the index/data pair.
+
+Reading temperature information.
+The temperature information is located in the following registers:
+Temp1 0x25 (Currently, this reflects the CPU temp on all systems).
+Temp2 0x26
+Temp3 0x27
+Temp4 0x80
+
+Programming Example
+The following is an example of how to read the HWM temperature registers:
+MOV DX,480H
+MOV AX,25H
+OUT DX,AL
+MOV DX,481H
+IN AL,DX
+
+AL contains the data in hex, the temperature in Celsius is the decimal
+equivalent.
+
+Ex: If AL contains 0x2A, the temperature is 42 degrees C.
+
+Reading tach information.
+The fan speed information is located in the following registers:
+ LSB MSB
+Tach1 0x28 0x29 (Currently, this reflects the CPU
+ fan speed on all systems).
+Tach2 0x2A 0x2B
+Tach3 0x2C 0x2D
+Tach4 0x2E 0x2F
+
+Important!!!
+Reading the tach LSB locks the tach MSB.
+The LSB Must be read first.
+
+How to convert the tach reading to RPM.
+The tach reading (TCount) is given by: (Tach MSB * 256) + (Tach LSB)
+The SIO counts the number of 90kHz (11.111us) pulses per revolution.
+RPM = 60/(TCount * 11.111us)
+
+Example:
+Reg 0x28 = 0x9B
+Reg 0x29 = 0x08
+
+TCount = 0x89B = 2203
+
+RPM = 60 / (2203 * 11.11111 E-6) = 2451 RPM
+
+Obtaining the SIO version.
+
+CONFIGURATION SEQUENCE
+To program the configuration registers, the following sequence must be followed:
+1. Enter Configuration Mode
+2. Configure the Configuration Registers
+3. Exit Configuration Mode.
+
+Enter Configuration Mode
+To place the chip into the Configuration State The config key (0x55) is written
+to the CONFIG PORT (0x2E).
+
+Configuration Mode
+In configuration mode, the INDEX PORT is located at the CONFIG PORT address and
+the DATA PORT is at INDEX PORT address + 1.
+
+The desired configuration registers are accessed in two steps:
+a. Write the index of the Logical Device Number Configuration Register
+ (i.e., 0x07) to the INDEX PORT and then write the number of the
+ desired logical device to the DATA PORT.
+
+b. Write the address of the desired configuration register within the
+ logical device to the INDEX PORT and then write or read the config-
+ uration register through the DATA PORT.
+
+Note: If accessing the Global Configuration Registers, step (a) is not required.
+
+Exit Configuration Mode
+To exit the Configuration State the write 0xAA to the CONFIG PORT (0x2E).
+The chip returns to the RUN State. (This is important).
+
+Programming Example
+The following is an example of how to read the SIO Device ID located at 0x20
+
+; ENTER CONFIGURATION MODE
+MOV DX,02EH
+MOV AX,055H
+OUT DX,AL
+; GLOBAL CONFIGURATION REGISTER
+MOV DX,02EH
+MOV AL,20H
+OUT DX,AL
+; READ THE DATA
+MOV DX,02FH
+IN AL,DX
+; EXIT CONFIGURATION MODE
+MOV DX,02EH
+MOV AX,0AAH
+OUT DX,AL
+
+The registers of interest for identifying the SIO on the dc7100 are Device ID
+(0x20) and Device Rev (0x21).
+
+The Device ID will read 0X6F
+The Device Rev currently reads 0x01
+
+Obtaining the HWM Base Address.
+The following is an example of how to read the HWM Base Address located in
+Logical Device 8.
+
+; ENTER CONFIGURATION MODE
+MOV DX,02EH
+MOV AX,055H
+OUT DX,AL
+; CONFIGURE REGISTER CRE0,
+; LOGICAL DEVICE 8
+MOV DX,02EH
+MOV AL,07H
+OUT DX,AL ;Point to LD# Config Reg
+MOV DX,02FH
+MOV AL, 08H
+OUT DX,AL;Point to Logical Device 8
+;
+MOV DX,02EH
+MOV AL,60H
+OUT DX,AL ; Point to HWM Base Addr MSB
+MOV DX,02FH
+IN AL,DX ; Get MSB of HWM Base Addr
+; EXIT CONFIGURATION MODE
+MOV DX,02EH
+MOV AX,0AAH
+OUT DX,AL
diff --git a/Documentation/i2c/dev-interface b/Documentation/i2c/dev-interface
new file mode 100644
index 0000000..09d6cda
--- /dev/null
+++ b/Documentation/i2c/dev-interface
@@ -0,0 +1,146 @@
+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.
+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.h>" and "#include <linux/i2c-dev.h>.
+Yes, I know, you should never include kernel header files, but until glibc
+knows about i2c, there is not much choice.
+
+Now, you have to decide which adapter you want to access. You should
+inspect /sys/class/i2c-dev/ to decide this. Adapter numbers are assigned
+somewhat dynamically, so you can not even assume /dev/i2c-0 is the
+first adapter.
+
+Next thing, open the device file, as follows:
+ int file;
+ int adapter_nr = 2; /* probably dynamically determined */
+ char filename[20];
+
+ sprintf(filename,"/dev/i2c-%d",adapter_nr);
+ if ((file = open(filename,O_RDWR)) < 0) {
+ /* 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 */
+ }
+
+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 and fully supported
+(see also i2c-dev.h and i2c.h):
+
+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.
+
+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.
+
+ioctl(file,I2C_FUNCS,unsigned long *funcs)
+ Gets the adapter functionality and puts it in *funcs.
+
+ioctl(file,I2C_RDWR,struct i2c_ioctl_rdwr_data *msgset)
+
+ Do combined read/write transaction without stop in between.
+ The argument is a pointer to a struct i2c_ioctl_rdwr_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.
+
+
+Other values are NOT supported at this moment, except for I2C_SMBUS,
+which you should never directly call; 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 macros, 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.
diff --git a/Documentation/i2c/functionality b/Documentation/i2c/functionality
new file mode 100644
index 0000000..8a78a95
--- /dev/null
+++ b/Documentation/i2c/functionality
@@ -0,0 +1,135 @@
+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_REV_DIR_ADDR,
+ I2C_M_REV_DIR_ADDR and I2C_M_REV_DIR_NOSTART
+ flags (which modify the i2c protocol!)
+ 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)
+
+
+ALGORITHM/ADAPTER IMPLEMENTATION
+--------------------------------
+
+When you write a new algorithm driver, you will have to implement a
+function callback `functionality', that gets an i2c_adapter structure
+pointer as its only parameter:
+
+ struct i2c_algorithm {
+ /* Many other things of course; check <linux/i2c.h>! */
+ u32 (*functionality) (struct i2c_adapter *);
+ }
+
+A typically implementation is given below, from i2c-algo-bit.c:
+
+ static u32 bit_func(struct i2c_adapter *adap)
+ {
+ return I2C_FUNC_SMBUS_EMUL | I2C_FUNC_10BIT_ADDR |
+ I2C_FUNC_PROTOCOL_MANGLING;
+ }
+
+
+
+CLIENT CHECKING
+---------------
+
+Before a client tries to attach to an adapter, or even do tests to check
+whether one of the devices it supports is present on an adapter, it should
+check whether the needed functionality is present. There are two functions
+defined which should be used instead of calling the functionality hook
+in the algorithm structure directly:
+
+ /* Return the functionality mask */
+ extern u32 i2c_get_functionality (struct i2c_adapter *adap);
+
+ /* Return 1 if adapter supports everything we need, 0 if not. */
+ extern int i2c_check_functionality (struct i2c_adapter *adap, u32 func);
+
+This is a typical way to use these functions (from the writing-clients
+document):
+ int foo_detect_client(struct i2c_adapter *adapter, int address,
+ unsigned short flags, int kind)
+ {
+ /* Define needed variables */
+
+ /* As the very first action, we check whether the adapter has the
+ needed functionality: we need the SMBus read_word_data,
+ write_word_data and write_byte functions in this example. */
+ if (!i2c_check_functionality(adapter,I2C_FUNC_SMBUS_WORD_DATA |
+ I2C_FUNC_SMBUS_WRITE_BYTE))
+ goto ERROR0;
+
+ /* Now we can do the real detection */
+
+ ERROR0:
+ /* Return an error */
+ }
+
+
+
+CHECKING THROUGH /DEV
+---------------------
+
+If you try to access an adapter from a userspace program, you will have
+to use the /dev interface. You will still have to check whether the
+functionality you need is supported, of course. This is done using
+the I2C_FUNCS ioctl. An example, adapted from the lm_sensors i2c_detect
+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
new file mode 100644
index 0000000..b4022c9
--- /dev/null
+++ b/Documentation/i2c/i2c-protocol
@@ -0,0 +1,76 @@
+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
+=====================
+
+We have found some I2C devices that needs the following modifications:
+
+ 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.
+
+ 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
new file mode 100644
index 0000000..d6dcb13
--- /dev/null
+++ b/Documentation/i2c/i2c-stub
@@ -0,0 +1,38 @@
+MODULE: i2c-stub
+
+DESCRIPTION:
+
+This module is a very simple fake I2C/SMBus driver. It implements four
+types of SMBus commands: write quick, (r/w) byte, (r/w) byte data, and
+(r/w) word data.
+
+No hardware is needed nor associated with this module. It will accept write
+quick commands to all addresses; it will respond to the other commands (also
+to all addresses) by reading from or writing to an array in memory. It will
+also spam the kernel logs for every command it handles.
+
+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 lm_sensors project) to pre-load some data
+ 3. load the target sensors chip driver module
+ 4. observe its behavior in the kernel log
+
+CAVEATS:
+
+There are independent arrays for byte/data and word/data commands. Depending
+on if/how a target driver mixes them, you'll need to be careful.
+
+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/porting-clients b/Documentation/i2c/porting-clients
new file mode 100644
index 0000000..5640491
--- /dev/null
+++ b/Documentation/i2c/porting-clients
@@ -0,0 +1,133 @@
+Revision 4, 2004-03-30
+Jean Delvare <khali@linux-fr.org>
+Greg KH <greg@kroah.com>
+
+This is a guide on how to convert I2C chip drivers from Linux 2.4 to
+Linux 2.6. I have been using existing drivers (lm75, lm78) as examples.
+Then I converted a driver myself (lm83) and updated this document.
+
+There are two sets of points below. The first set concerns technical
+changes. The second set concerns coding policy. Both are mandatory.
+
+Although reading this guide will help you porting drivers, I suggest
+you keep an eye on an already ported driver while porting your own
+driver. This will help you a lot understanding what this guide
+exactly means. Choose the chip driver that is the more similar to
+yours for best results.
+
+Technical changes:
+
+* [Includes] Get rid of "version.h". Replace <linux/i2c-proc.h> with
+ <linux/i2c-sensor.h>. Includes typically look like that:
+ #include <linux/module.h>
+ #include <linux/init.h>
+ #include <linux/slab.h>
+ #include <linux/i2c.h>
+ #include <linux/i2c-sensor.h>
+ #include <linux/i2c-vid.h> /* if you need VRM support */
+ #include <asm/io.h> /* if you have I/O operations */
+ Please respect this inclusion order. Some extra headers may be
+ required for a given driver (e.g. "lm75.h").
+
+* [Addresses] SENSORS_I2C_END becomes I2C_CLIENT_END, SENSORS_ISA_END
+ becomes I2C_CLIENT_ISA_END.
+
+* [Client data] Get rid of sysctl_id. Try using standard names for
+ register values (for example, temp_os becomes temp_max). You're
+ still relatively free here, but you *have* to follow the standard
+ names for sysfs files (see the Sysctl section below).
+
+* [Function prototypes] The detect functions loses its flags
+ parameter. Sysctl (e.g. lm75_temp) and miscellaneous functions
+ are off the list of prototypes. This usually leaves five
+ prototypes:
+ static int lm75_attach_adapter(struct i2c_adapter *adapter);
+ static int lm75_detect(struct i2c_adapter *adapter, int address,
+ int kind);
+ static void lm75_init_client(struct i2c_client *client);
+ static int lm75_detach_client(struct i2c_client *client);
+ static void lm75_update_client(struct i2c_client *client);
+
+* [Sysctl] All sysctl stuff is of course gone (defines, ctl_table
+ and functions). Instead, you have to define show and set functions for
+ each sysfs file. Only define set for writable values. Take a look at an
+ existing 2.6 driver for details (lm78 for example). Don't forget
+ to define the attributes for each file (this is that step that
+ links callback functions). Use the file names specified in
+ Documentation/i2c/sysfs-interface for the individual files. Also
+ convert the units these files read and write to the specified ones.
+ If you need to add a new type of file, please discuss it on the
+ sensors mailing list <sensors@stimpy.netroedge.com> by providing a
+ patch to the Documentation/i2c/sysfs-interface file.
+
+* [Attach] For I2C drivers, the attach function should make sure
+ that the adapter's class has I2C_CLASS_HWMON, using the
+ following construct:
+ if (!(adapter->class & I2C_CLASS_HWMON))
+ return 0;
+ ISA-only drivers of course don't need this.
+
+* [Detect] As mentioned earlier, the flags parameter is gone.
+ The type_name and client_name strings are replaced by a single
+ name string, which will be filled with a lowercase, short string
+ (typically the driver name, e.g. "lm75").
+ In i2c-only drivers, drop the i2c_is_isa_adapter check, it's
+ useless.
+ The errorN labels are reduced to the number needed. If that number
+ is 2 (i2c-only drivers), it is advised that the labels are named
+ exit and exit_free. For i2c+isa drivers, labels should be named
+ ERROR0, ERROR1 and ERROR2. Don't forget to properly set err before
+ jumping to error labels. By the way, labels should be left-aligned.
+ Use memset to fill the client and data area with 0x00.
+ Use i2c_set_clientdata to set the client data (as opposed to
+ a direct access to client->data).
+ Use strlcpy instead of strcpy to copy the client name.
+ Replace the sysctl directory registration by calls to
+ device_create_file. Move the driver initialization before any
+ sysfs file creation.
+ Drop client->id.
+
+* [Init] Limits must not be set by the driver (can be done later in
+ user-space). Chip should not be reset default (although a module
+ parameter may be used to force is), and initialization should be
+ limited to the strictly necessary steps.
+
+* [Detach] Get rid of data, remove the call to
+ i2c_deregister_entry.
+
+* [Update] Don't access client->data directly, use
+ i2c_get_clientdata(client) instead.
+
+* [Interface] Init function should not print anything. Make sure
+ there is a MODULE_LICENSE() line, at the bottom of the file
+ (after MODULE_AUTHOR() and MODULE_DESCRIPTION(), in this order).
+
+Coding policy:
+
+* [Copyright] Use (C), not (c), for copyright.
+
+* [Debug/log] Get rid of #ifdef DEBUG/#endif constructs whenever you
+ can. Calls to printk/pr_debug for debugging purposes are replaced
+ by calls to dev_dbg. Here is an example on how to call it (taken
+ from lm75_detect):
+ dev_dbg(&client->dev, "Starting lm75 update\n");
+ Replace other printk calls with the dev_info, dev_err or dev_warn
+ function, as appropriate.
+
+* [Constants] Constants defines (registers, conversions, initial
+ values) should be aligned. This greatly improves readability.
+ Same goes for variables declarations. Alignments are achieved by the
+ means of tabs, not spaces. Remember that tabs are set to 8 in the
+ Linux kernel code.
+
+* [Structure definition] The name field should be standardized. All
+ lowercase and as simple as the driver name itself (e.g. "lm75").
+
+* [Layout] Avoid extra empty lines between comments and what they
+ comment. Respect the coding style (see Documentation/CodingStyle),
+ in particular when it comes to placing curly braces.
+
+* [Comments] Make sure that no comment refers to a file that isn't
+ part of the Linux source tree (typically doc/chips/<chip name>),
+ and that remaining comments still match the code. Merging comment
+ lines when possible is encouraged.
diff --git a/Documentation/i2c/smbus-protocol b/Documentation/i2c/smbus-protocol
new file mode 100644
index 0000000..09f5e5c
--- /dev/null
+++ b/Documentation/i2c/smbus-protocol
@@ -0,0 +1,216 @@
+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 commands.
+
+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 Write Quick
+=================
+
+This sends a single bit to the device, at the place of the Rd/Wr bit.
+There is no equivalent Read Quick command.
+
+A Addr Rd/Wr [A] P
+
+
+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 Write Byte
+================
+
+This is the reverse of Read Byte: it sends a single byte to a device.
+See Read Byte for more information.
+
+S Addr Wr [A] Data [A] P
+
+
+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 Data
+====================
+
+This command is very like Read Byte Data; 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
+
+
+SMBus Write Byte Data
+=====================
+
+This writes a single byte to a device, to a designated register. The
+register is specified through the Comm byte. This is the opposite of
+the Read Byte Data command.
+
+S Addr Wr [A] Comm [A] Data [A] P
+
+
+SMBus Write Word Data
+=====================
+
+This is the opposite operation of the Read Word Data command. 16 bits
+of data is read from a device, from a designated register that is
+specified through the Comm byte.
+
+S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A] P
+
+
+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
+================
+
+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
+=================
+
+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 Process Call
+========================
+
+SMBus Block 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 all transfers.
+
+
+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.
+
+
+I2C Block Transactions
+======================
+The following I2C block transactions are supported by the
+SMBus layer and are described here for completeness.
+I2C block transactions do not limit the number of bytes transferred
+but the SMBus layer places a limit of 32 bytes.
+
+
+I2C Block Read
+==============
+
+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
+===============
+
+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
new file mode 100644
index 0000000..41dde87
--- /dev/null
+++ b/Documentation/i2c/summary
@@ -0,0 +1,75 @@
+This is an explanation of what i2c is, and what is supported in this package.
+
+I2C and SMBus
+=============
+
+I2C (pronounce: I squared C) is a protocol developed by Philips. It is a
+slow two-wire protocol (10-400 kHz), but it suffices for many types of
+devices.
+
+SMBus (System Management Bus) is a subset of the I2C protocol. Many
+modern mainboards have a System Management Bus. There are a lot of
+devices which can be connected to a SMBus; the most notable are modern
+memory chips with EEPROM memories and chips for hardware monitoring.
+
+Because the SMBus is just a special case of the generalized I2C bus, we
+can simulate the SMBus protocol on plain I2C busses. The reverse is
+regretfully impossible.
+
+
+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 depends on one algorithm
+driver.
+A Driver driver (yes, this sounds ridiculous, sorry) contains the general
+code to access some type of device. Each detected device gets its own
+data in the Client structure. Usually, Driver and Client are more closely
+integrated than Algorithm and Adapter.
+
+For a given configuration, you will need a driver for your I2C bus (usually
+a separate Adapter and Algorithm driver), and drivers for your I2C devices
+(usually one driver for each device). There are no I2C device drivers
+in this package. See the lm_sensors project http://www.lm-sensors.nu
+for device drivers.
+
+
+Included Bus Drivers
+====================
+Note that only stable drivers are patched into the kernel by 'mkpatch'.
+
+
+Base modules
+------------
+
+i2c-core: The basic I2C code, including the /proc/bus/i2c* interface
+i2c-dev: The /dev/i2c-* interface
+i2c-proc: The /proc/sys/dev/sensors interface for device (client) drivers
+
+Algorithm drivers
+-----------------
+
+i2c-algo-8xx: An algorithm for CPM's I2C device in Motorola 8xx processors (NOT BUILT BY DEFAULT)
+i2c-algo-bit: A bit-banging algorithm
+i2c-algo-pcf: A PCF 8584 style algorithm
+i2c-algo-ibm_ocp: An algorithm for the I2C device in IBM 4xx processors (NOT BUILT BY DEFAULT)
+
+Adapter drivers
+---------------
+
+i2c-elektor: Elektor ISA card (uses i2c-algo-pcf)
+i2c-elv: ELV parallel port adapter (uses i2c-algo-bit)
+i2c-pcf-epp: PCF8584 on a EPP parallel port (uses i2c-algo-pcf) (NOT mkpatched)
+i2c-philips-par: Philips style parallel port adapter (uses i2c-algo-bit)
+i2c-adap-ibm_ocp: IBM 4xx processor I2C device (uses i2c-algo-ibm_ocp) (NOT BUILT BY DEFAULT)
+i2c-pport: Primitive parallel port adapter (uses i2c-algo-bit)
+i2c-rpx: RPX board Motorola 8xx I2C device (uses i2c-algo-8xx) (NOT BUILT BY DEFAULT)
+i2c-velleman: Velleman K8000 parallel port adapter (uses i2c-algo-bit)
+
diff --git a/Documentation/i2c/sysfs-interface b/Documentation/i2c/sysfs-interface
new file mode 100644
index 0000000..3464005
--- /dev/null
+++ b/Documentation/i2c/sysfs-interface
@@ -0,0 +1,274 @@
+Naming and data format standards for sysfs files
+------------------------------------------------
+
+The libsensors library offers an interface to the raw sensors data
+through the sysfs interface. See libsensors documentation and source for
+more further information. As of writing this document, libsensors
+(from lm_sensors 2.8.3) is heavily chip-dependant. Adding or updating
+support for any given chip requires modifying the library's code.
+This is because libsensors was written for the procfs interface
+older kernel modules were using, which wasn't standardized enough.
+Recent versions of libsensors (from lm_sensors 2.8.2 and later) have
+support for the sysfs interface, though.
+
+The new sysfs interface was designed to be as chip-independant as
+possible.
+
+Note that motherboards vary widely in the connections to sensor chips.
+There is no standard that ensures, for example, that the second
+temperature sensor is connected to the CPU, or that the second fan is on
+the CPU. Also, some values reported by the chips need some computation
+before they make full sense. For example, most chips can only measure
+voltages between 0 and +4V. Other voltages are scaled back into that
+range using external resistors. Since the values of these resistors
+can change from motherboard to motherboard, the conversions cannot be
+hard coded into the driver and have to be done in user space.
+
+For this reason, even if we aim at a chip-independant libsensors, it will
+still require a configuration file (e.g. /etc/sensors.conf) for proper
+values conversion, labeling of inputs and hiding of unused inputs.
+
+An alternative method that some programs use is to access the sysfs
+files directly. This document briefly describes the standards that the
+drivers follow, so that an application program can scan for entries and
+access this data in a simple and consistent way. That said, such programs
+will have to implement conversion, labeling and hiding of inputs. For
+this reason, it is still not recommended to bypass the library.
+
+If you are developing a userspace application please send us feedback on
+this standard.
+
+Note that this standard isn't completely established yet, so it is subject
+to changes, even important ones. One more reason to use the library instead
+of accessing sysfs files directly.
+
+Each chip gets its own directory in the sysfs /sys/devices tree. To
+find all sensor chips, it is easier to follow the symlinks from
+/sys/i2c/devices/
+
+All sysfs values are fixed point numbers. To get the true value of some
+of the values, you should divide by the specified value.
+
+There is only one value per file, unlike the older /proc specification.
+The common scheme for files naming is: <type><number>_<item>. Usual
+types for sensor chips are "in" (voltage), "temp" (temperature) and
+"fan" (fan). Usual items are "input" (measured value), "max" (high
+threshold, "min" (low threshold). Numbering usually starts from 1,
+except for voltages which start from 0 (because most data sheets use
+this). A number is always used for elements that can be present more
+than once, even if there is a single element of the given type on the
+specific chip. Other files do not refer to a specific element, so
+they have a simple name, and no number.
+
+Alarms are direct indications read from the chips. The drivers do NOT
+make comparisons of readings to thresholds. This allows violations
+between readings to be caught and alarmed. The exact definition of an
+alarm (for example, whether a threshold must be met or must be exceeded
+to cause an alarm) is chip-dependent.
+
+
+-------------------------------------------------------------------------
+
+************
+* Voltages *
+************
+
+in[0-8]_min Voltage min value.
+ Unit: millivolt
+ Read/Write
+
+in[0-8]_max Voltage max value.
+ Unit: millivolt
+ Read/Write
+
+in[0-8]_input Voltage input value.
+ Unit: millivolt
+ Read only
+ Actual voltage depends on the scaling resistors on the
+ motherboard, as recommended in the chip datasheet.
+ This varies by chip and by motherboard.
+ Because of this variation, values are generally NOT scaled
+ by the chip driver, and must be done by the application.
+ However, some drivers (notably lm87 and via686a)
+ do scale, with various degrees of success.
+ These drivers will output the actual voltage.
+
+ Typical usage:
+ in0_* CPU #1 voltage (not scaled)
+ in1_* CPU #2 voltage (not scaled)
+ in2_* 3.3V nominal (not scaled)
+ in3_* 5.0V nominal (scaled)
+ in4_* 12.0V nominal (scaled)
+ in5_* -12.0V nominal (scaled)
+ in6_* -5.0V nominal (scaled)
+ in7_* varies
+ in8_* varies
+
+cpu[0-1]_vid CPU core reference voltage.
+ Unit: millivolt
+ Read only.
+ Not always correct.
+
+vrm Voltage Regulator Module version number.
+ Read only.
+ Two digit number, first is major version, second is
+ minor version.
+ Affects the way the driver calculates the CPU core reference
+ voltage from the vid pins.
+
+
+********
+* Fans *
+********
+
+fan[1-3]_min Fan minimum value
+ Unit: revolution/min (RPM)
+ Read/Write.
+
+fan[1-3]_input Fan input value.
+ Unit: revolution/min (RPM)
+ Read only.
+
+fan[1-3]_div Fan divisor.
+ Integer value in powers of two (1, 2, 4, 8, 16, 32, 64, 128).
+ Some chips only support values 1, 2, 4 and 8.
+ Note that this is actually an internal clock divisor, which
+ affects the measurable speed range, not the read value.
+
+*******
+* PWM *
+*******
+
+pwm[1-3] Pulse width modulation fan control.
+ Integer value in the range 0 to 255
+ Read/Write
+ 255 is max or 100%.
+
+pwm[1-3]_enable
+ Switch PWM on and off.
+ Not always present even if fan*_pwm is.
+ 0 to turn off
+ 1 to turn on in manual mode
+ 2 to turn on in automatic mode
+ Read/Write
+
+pwm[1-*]_auto_channels_temp
+ Select which temperature channels affect this PWM output in
+ auto mode. Bitfield, 1 is temp1, 2 is temp2, 4 is temp3 etc...
+ Which values are possible depend on the chip used.
+
+pwm[1-*]_auto_point[1-*]_pwm
+pwm[1-*]_auto_point[1-*]_temp
+pwm[1-*]_auto_point[1-*]_temp_hyst
+ Define the PWM vs temperature curve. Number of trip points is
+ chip-dependent. Use this for chips which associate trip points
+ to PWM output channels.
+
+OR
+
+temp[1-*]_auto_point[1-*]_pwm
+temp[1-*]_auto_point[1-*]_temp
+temp[1-*]_auto_point[1-*]_temp_hyst
+ Define the PWM vs temperature curve. Number of trip points is
+ chip-dependent. Use this for chips which associate trip points
+ to temperature channels.
+
+
+****************
+* Temperatures *
+****************
+
+temp[1-3]_type Sensor type selection.
+ Integers 1, 2, 3 or thermistor Beta value (3435)
+ Read/Write.
+ 1: PII/Celeron Diode
+ 2: 3904 transistor
+ 3: thermal diode
+ Not all types are supported by all chips
+
+temp[1-4]_max Temperature max value.
+ Unit: millidegree Celcius
+ Read/Write value.
+
+temp[1-3]_min Temperature min value.
+ Unit: millidegree Celcius
+ Read/Write value.
+
+temp[1-3]_max_hyst
+ Temperature hysteresis value for max limit.
+ Unit: millidegree Celcius
+ Must be reported as an absolute temperature, NOT a delta
+ from the max value.
+ Read/Write value.
+
+temp[1-4]_input Temperature input value.
+ Unit: millidegree Celcius
+ Read only value.
+
+temp[1-4]_crit Temperature critical value, typically greater than
+ corresponding temp_max values.
+ Unit: millidegree Celcius
+ Read/Write value.
+
+temp[1-2]_crit_hyst
+ Temperature hysteresis value for critical limit.
+ Unit: millidegree Celcius
+ Must be reported as an absolute temperature, NOT a delta
+ from the critical value.
+ Read/Write value.
+
+ If there are multiple temperature sensors, temp1_* is
+ generally the sensor inside the chip itself,
+ reported as "motherboard temperature". temp2_* to
+ temp4_* are generally sensors external to the chip
+ itself, for example the thermal diode inside the CPU or
+ a thermistor nearby.
+
+
+************
+* Currents *
+************
+
+Note that no known chip provides current measurements as of writing,
+so this part is theoretical, so to say.
+
+curr[1-n]_max Current max value
+ Unit: milliampere
+ Read/Write.
+
+curr[1-n]_min Current min value.
+ Unit: milliampere
+ Read/Write.
+
+curr[1-n]_input Current input value
+ Unit: milliampere
+ Read only.
+
+
+*********
+* Other *
+*********
+
+alarms Alarm bitmask.
+ Read only.
+ Integer representation of one to four bytes.
+ A '1' bit means an alarm.
+ Chips should be programmed for 'comparator' mode so that
+ the alarm will 'come back' after you read the register
+ if it is still valid.
+ Generally a direct representation of a chip's internal
+ alarm registers; there is no standard for the position
+ of individual bits.
+ Bits are defined in kernel/include/sensors.h.
+
+beep_enable Beep/interrupt enable
+ 0 to disable.
+ 1 to enable.
+ Read/Write
+
+beep_mask Bitmask for beep.
+ Same format as 'alarms' with the same bit locations.
+ Read/Write
+
+eeprom Raw EEPROM data in binary form.
+ Read only.
diff --git a/Documentation/i2c/ten-bit-addresses b/Documentation/i2c/ten-bit-addresses
new file mode 100644
index 0000000..200074f
--- /dev/null
+++ b/Documentation/i2c/ten-bit-addresses
@@ -0,0 +1,22 @@
+The I2C protocol knows about two kinds of device addresses: normal 7 bit
+addresses, and an extended set of 10 bit addresses. The sets of addresses
+do not intersect: the 7 bit address 0x10 is not the same as the 10 bit
+address 0x10 (though a single device could respond to both of them). You
+select a 10 bit address by adding an extra byte after the address
+byte:
+ S Addr7 Rd/Wr ....
+becomes
+ S 11110 Addr10 Rd/Wr
+S is the start bit, Rd/Wr the read/write bit, and if you count the number
+of bits, you will see the there are 8 after the S bit for 7 bit addresses,
+and 16 after the S bit for 10 bit addresses.
+
+WARNING! The current 10 bit address support is EXPERIMENTAL. There are
+several places in the code that will cause SEVERE PROBLEMS with 10 bit
+addresses, even though there is some basic handling and hooks. Also,
+almost no supported adapter handles the 10 bit addresses correctly.
+
+As soon as a real 10 bit address device is spotted 'in the wild', we
+can and will add proper support. Right now, 10 bit address devices
+are defined by the I2C protocol, but we have never seen a single device
+which supports them.
diff --git a/Documentation/i2c/writing-clients b/Documentation/i2c/writing-clients
new file mode 100644
index 0000000..ad27511
--- /dev/null
+++ b/Documentation/i2c/writing-clients
@@ -0,0 +1,816 @@
+This is a small guide for those who want to write kernel drivers for I2C
+or SMBus devices.
+
+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, and `FOO_' for preprocessor variables.
+
+
+The driver structure
+====================
+
+Usually, you will implement a single driver structure, and instantiate
+all clients from it. Remember, a driver structure contains general access
+routines, a client structure specific information like the actual I2C
+address.
+
+static struct i2c_driver foo_driver = {
+ .owner = THIS_MODULE,
+ .name = "Foo version 2.3 driver",
+ .id = I2C_DRIVERID_FOO, /* from i2c-id.h, optional */
+ .flags = I2C_DF_NOTIFY,
+ .attach_adapter = &foo_attach_adapter,
+ .detach_client = &foo_detach_client,
+ .command = &foo_command /* may be NULL */
+}
+
+The name can be chosen freely, and may be upto 40 characters long. Please
+use something descriptive here.
+
+If used, the id should be a unique ID. The range 0xf000 to 0xffff is
+reserved for local use, and you can use one of those until you start
+distributing the driver, at which time you should contact the i2c authors
+to get your own ID(s). Note that most of the time you don't need an ID
+at all so you can just omit it.
+
+Don't worry about the flags field; just put I2C_DF_NOTIFY into it. This
+means that your driver will be notified when new adapters are found.
+This is almost always what you want.
+
+All other fields are for call-back functions which will be explained
+below.
+
+There use to be two additional fields in this structure, inc_use et dec_use,
+for module usage count, but these fields were obsoleted and removed.
+
+
+Extra client data
+=================
+
+The client structure has a special `data' field that can point to any
+structure at all. You can use this to keep client-specific data. You
+do not always need this, but especially for `sensors' drivers, it can
+be very useful.
+
+An example structure is below.
+
+ struct foo_data {
+ struct semaphore lock; /* For ISA access in `sensors' drivers. */
+ int sysctl_id; /* To keep the /proc directory entry for
+ `sensors' drivers. */
+ enum chips type; /* To keep the chips type for `sensors' drivers. */
+
+ /* Because the i2c bus is slow, it is often useful to cache the read
+ information of a chip for some time (for example, 1 or 2 seconds).
+ It depends of course on the device whether this is really worthwhile
+ or even sensible. */
+ struct semaphore update_lock; /* When we are reading lots of information,
+ another process should not update the
+ below information */
+ char valid; /* != 0 if the following fields are valid. */
+ unsigned long last_updated; /* In jiffies */
+ /* Add the read information here too */
+ };
+
+
+Accessing the client
+====================
+
+Let's say we have a valid client structure. At some time, we will need
+to gather information from the client, or write new information to the
+client. How we will export this information to user-space is less
+important at this moment (perhaps we do not need to do this at all for
+some obscure clients). But we need generic reading and writing routines.
+
+I have found it useful to define foo_read and foo_write function for this.
+For some cases, it will be easier to call the i2c functions directly,
+but many chips have some kind of register-value idea that can easily
+be encapsulated. Also, some chips have both ISA and I2C interfaces, and
+it useful to abstract from this (only for `sensors' drivers).
+
+The below functions are simple examples, and should not be copied
+literally.
+
+ int foo_read_value(struct i2c_client *client, u8 reg)
+ {
+ if (reg < 0x10) /* byte-sized register */
+ return i2c_smbus_read_byte_data(client,reg);
+ else /* word-sized register */
+ return i2c_smbus_read_word_data(client,reg);
+ }
+
+ int foo_write_value(struct i2c_client *client, u8 reg, u16 value)
+ {
+ if (reg == 0x10) /* Impossible to write - driver error! */ {
+ return -1;
+ else if (reg < 0x10) /* byte-sized register */
+ return i2c_smbus_write_byte_data(client,reg,value);
+ else /* word-sized register */
+ return i2c_smbus_write_word_data(client,reg,value);
+ }
+
+For sensors code, you may have to cope with ISA registers too. Something
+like the below often works. Note the locking!
+
+ int foo_read_value(struct i2c_client *client, u8 reg)
+ {
+ int res;
+ if (i2c_is_isa_client(client)) {
+ down(&(((struct foo_data *) (client->data)) -> lock));
+ outb_p(reg,client->addr + FOO_ADDR_REG_OFFSET);
+ res = inb_p(client->addr + FOO_DATA_REG_OFFSET);
+ up(&(((struct foo_data *) (client->data)) -> lock));
+ return res;
+ } else
+ return i2c_smbus_read_byte_data(client,reg);
+ }
+
+Writing is done the same way.
+
+
+Probing and attaching
+=====================
+
+Most i2c devices can be present on several i2c addresses; for some this
+is determined in hardware (by soldering some chip pins to Vcc or Ground),
+for others this can be changed in software (by writing to specific client
+registers). Some devices are usually on a specific address, but not always;
+and some are even more tricky. So you will probably need to scan several
+i2c addresses for your clients, and do some sort of detection to see
+whether it is actually a device supported by your driver.
+
+To give the user a maximum of possibilities, some default module parameters
+are defined to help determine what addresses are scanned. Several macros
+are defined in i2c.h to help you support them, as well as a generic
+detection algorithm.
+
+You do not have to use this parameter interface; but don't try to use
+function i2c_probe() (or i2c_detect()) if you don't.
+
+NOTE: If you want to write a `sensors' driver, the interface is slightly
+ different! See below.
+
+
+
+Probing classes (i2c)
+---------------------
+
+All parameters are given as lists of unsigned 16-bit integers. Lists are
+terminated by I2C_CLIENT_END.
+The following lists are used internally:
+
+ normal_i2c: filled in by the module writer.
+ A list of I2C addresses which should normally be examined.
+ normal_i2c_range: filled in by the module writer.
+ A list of pairs of I2C addresses, each pair being an inclusive range of
+ addresses which should normally be examined.
+ probe: insmod parameter.
+ A list of pairs. The first value is a bus number (-1 for any I2C bus),
+ the second is the address. These addresses are also probed, as if they
+ were in the 'normal' list.
+ probe_range: insmod parameter.
+ A list of triples. The first value is a bus number (-1 for any I2C bus),
+ the second and third are addresses. These form an inclusive range of
+ addresses that are also probed, as if they were in the 'normal' list.
+ ignore: insmod parameter.
+ A list of pairs. The first value is a bus number (-1 for any I2C bus),
+ the second is the I2C address. These addresses are never probed.
+ This parameter overrules 'normal' and 'probe', but not the 'force' lists.
+ ignore_range: insmod parameter.
+ A list of triples. The first value is a bus number (-1 for any I2C bus),
+ the second and third are addresses. These form an inclusive range of
+ I2C addresses that are never probed.
+ This parameter overrules 'normal' and 'probe', but not the 'force' lists.
+ force: insmod parameter.
+ A list of pairs. The first value is a bus number (-1 for any I2C bus),
+ the second is the I2C address. A device is blindly assumed to be on
+ the given address, no probing is done.
+
+Fortunately, as a module writer, you just have to define the `normal'
+and/or `normal_range' parameters. The complete declaration could look
+like this:
+
+ /* Scan 0x20 to 0x2f, 0x37, and 0x40 to 0x4f */
+ static unsigned short normal_i2c[] = { 0x37,I2C_CLIENT_END };
+ static unsigned short normal_i2c_range[] = { 0x20, 0x2f, 0x40, 0x4f,
+ I2C_CLIENT_END };
+
+ /* Magic definition of all other variables and things */
+ I2C_CLIENT_INSMOD;
+
+Note that you *have* to call the two defined variables `normal_i2c' and
+`normal_i2c_range', without any prefix!
+
+
+Probing classes (sensors)
+-------------------------
+
+If you write a `sensors' driver, you use a slightly different interface.
+As well as I2C addresses, we have to cope with ISA addresses. Also, we
+use a enum of chip types. Don't forget to include `sensors.h'.
+
+The following lists are used internally. They are all lists of integers.
+
+ normal_i2c: filled in by the module writer. Terminated by SENSORS_I2C_END.
+ A list of I2C addresses which should normally be examined.
+ normal_i2c_range: filled in by the module writer. Terminated by
+ SENSORS_I2C_END
+ A list of pairs of I2C addresses, each pair being an inclusive range of
+ addresses which should normally be examined.
+ normal_isa: filled in by the module writer. Terminated by SENSORS_ISA_END.
+ A list of ISA addresses which should normally be examined.
+ normal_isa_range: filled in by the module writer. Terminated by
+ SENSORS_ISA_END
+ A list of triples. The first two elements are ISA addresses, being an
+ range of addresses which should normally be examined. The third is the
+ modulo parameter: only addresses which are 0 module this value relative
+ to the first address of the range are actually considered.
+ probe: insmod parameter. Initialize this list with SENSORS_I2C_END values.
+ A list of pairs. The first value is a bus number (SENSORS_ISA_BUS for
+ the ISA bus, -1 for any I2C bus), the second is the address. These
+ addresses are also probed, as if they were in the 'normal' list.
+ probe_range: insmod parameter. Initialize this list with SENSORS_I2C_END
+ values.
+ A list of triples. The first value is a bus number (SENSORS_ISA_BUS for
+ the ISA bus, -1 for any I2C bus), the second and third are addresses.
+ These form an inclusive range of addresses that are also probed, as
+ if they were in the 'normal' list.
+ ignore: insmod parameter. Initialize this list with SENSORS_I2C_END values.
+ A list of pairs. The first value is a bus number (SENSORS_ISA_BUS for
+ the ISA bus, -1 for any I2C bus), the second is the I2C address. These
+ addresses are never probed. This parameter overrules 'normal' and
+ 'probe', but not the 'force' lists.
+ ignore_range: insmod parameter. Initialize this list with SENSORS_I2C_END
+ values.
+ A list of triples. The first value is a bus number (SENSORS_ISA_BUS for
+ the ISA bus, -1 for any I2C bus), the second and third are addresses.
+ These form an inclusive range of I2C addresses that are never probed.
+ This parameter overrules 'normal' and 'probe', but not the 'force' lists.
+
+Also used is a list of pointers to sensors_force_data structures:
+ force_data: insmod parameters. A list, ending with an element of which
+ the force field is NULL.
+ Each element contains the type of chip and a list of pairs.
+ The first value is a bus number (SENSORS_ISA_BUS for the ISA bus,
+ -1 for any I2C bus), the second is the address.
+ These are automatically translated to insmod variables of the form
+ force_foo.
+
+So we have a generic insmod variabled `force', and chip-specific variables
+`force_CHIPNAME'.
+
+Fortunately, as a module writer, you just have to define the `normal'
+and/or `normal_range' parameters, and define what chip names are used.
+The complete declaration could look like this:
+ /* Scan i2c addresses 0x20 to 0x2f, 0x37, and 0x40 to 0x4f
+ static unsigned short normal_i2c[] = {0x37,SENSORS_I2C_END};
+ static unsigned short normal_i2c_range[] = {0x20,0x2f,0x40,0x4f,
+ SENSORS_I2C_END};
+ /* Scan ISA address 0x290 */
+ static unsigned int normal_isa[] = {0x0290,SENSORS_ISA_END};
+ static unsigned int normal_isa_range[] = {SENSORS_ISA_END};
+
+ /* Define chips foo and bar, as well as all module parameters and things */
+ SENSORS_INSMOD_2(foo,bar);
+
+If you have one chip, you use macro SENSORS_INSMOD_1(chip), if you have 2
+you use macro SENSORS_INSMOD_2(chip1,chip2), etc. If you do not want to
+bother with chip types, you can use SENSORS_INSMOD_0.
+
+A enum is automatically defined as follows:
+ enum chips { any_chip, chip1, chip2, ... }
+
+
+Attaching to an adapter
+-----------------------
+
+Whenever a new adapter is inserted, or for all adapters if the driver is
+being registered, the callback attach_adapter() is called. Now is the
+time to determine what devices are present on the adapter, and to register
+a client for each of them.
+
+The attach_adapter callback is really easy: we just call the generic
+detection function. This function will scan the bus for us, using the
+information as defined in the lists explained above. If a device is
+detected at a specific address, another callback is called.
+
+ int foo_attach_adapter(struct i2c_adapter *adapter)
+ {
+ return i2c_probe(adapter,&addr_data,&foo_detect_client);
+ }
+
+For `sensors' drivers, use the i2c_detect function instead:
+
+ int foo_attach_adapter(struct i2c_adapter *adapter)
+ {
+ return i2c_detect(adapter,&addr_data,&foo_detect_client);
+ }
+
+Remember, structure `addr_data' is defined by the macros explained above,
+so you do not have to define it yourself.
+
+The i2c_probe or i2c_detect function will call the foo_detect_client
+function only for those i2c addresses that actually have a device on
+them (unless a `force' parameter was used). In addition, addresses that
+are already in use (by some other registered client) are skipped.
+
+
+The detect client function
+--------------------------
+
+The detect client function is called by i2c_probe or i2c_detect.
+The `kind' parameter contains 0 if this call is due to a `force'
+parameter, and -1 otherwise (for i2c_detect, it contains 0 if
+this call is due to the generic `force' parameter, and the chip type
+number if it is due to a specific `force' parameter).
+
+Below, some things are only needed if this is a `sensors' driver. Those
+parts are between /* SENSORS ONLY START */ and /* SENSORS ONLY END */
+markers.
+
+This function should only return an error (any value != 0) if there is
+some reason why no more detection should be done anymore. If the
+detection just fails for this address, return 0.
+
+For now, you can ignore the `flags' parameter. It is there for future use.
+
+ int foo_detect_client(struct i2c_adapter *adapter, int address,
+ unsigned short flags, int kind)
+ {
+ int err = 0;
+ int i;
+ struct i2c_client *new_client;
+ struct foo_data *data;
+ const char *client_name = ""; /* For non-`sensors' drivers, put the real
+ name here! */
+
+ /* Let's see whether this adapter can support what we need.
+ Please substitute the things you need here!
+ For `sensors' drivers, add `! is_isa &&' to the if statement */
+ if (!i2c_check_functionality(adapter,I2C_FUNC_SMBUS_WORD_DATA |
+ I2C_FUNC_SMBUS_WRITE_BYTE))
+ goto ERROR0;
+
+ /* SENSORS ONLY START */
+ const char *type_name = "";
+ int is_isa = i2c_is_isa_adapter(adapter);
+
+ if (is_isa) {
+
+ /* If this client can't be on the ISA bus at all, we can stop now
+ (call `goto ERROR0'). But for kicks, we will assume it is all
+ right. */
+
+ /* Discard immediately if this ISA range is already used */
+ if (check_region(address,FOO_EXTENT))
+ goto ERROR0;
+
+ /* Probe whether there is anything on this address.
+ Some example code is below, but you will have to adapt this
+ for your own driver */
+
+ if (kind < 0) /* Only if no force parameter was used */ {
+ /* We may need long timeouts at least for some chips. */
+ #define REALLY_SLOW_IO
+ i = inb_p(address + 1);
+ if (inb_p(address + 2) != i)
+ goto ERROR0;
+ if (inb_p(address + 3) != i)
+ goto ERROR0;
+ if (inb_p(address + 7) != i)
+ goto ERROR0;
+ #undef REALLY_SLOW_IO
+
+ /* Let's just hope nothing breaks here */
+ i = inb_p(address + 5) & 0x7f;
+ outb_p(~i & 0x7f,address+5);
+ if ((inb_p(address + 5) & 0x7f) != (~i & 0x7f)) {
+ outb_p(i,address+5);
+ return 0;
+ }
+ }
+ }
+
+ /* SENSORS ONLY END */
+
+ /* OK. For now, we presume we have a valid client. We now create the
+ client structure, even though we cannot fill it completely yet.
+ But it allows us to access several i2c functions safely */
+
+ /* Note that we reserve some space for foo_data too. If you don't
+ need it, remove it. We do it here to help to lessen memory
+ fragmentation. */
+ if (! (new_client = kmalloc(sizeof(struct i2c_client) +
+ sizeof(struct foo_data),
+ GFP_KERNEL))) {
+ err = -ENOMEM;
+ goto ERROR0;
+ }
+
+ /* This is tricky, but it will set the data to the right value. */
+ client->data = new_client + 1;
+ data = (struct foo_data *) (client->data);
+
+ new_client->addr = address;
+ new_client->data = data;
+ new_client->adapter = adapter;
+ new_client->driver = &foo_driver;
+ new_client->flags = 0;
+
+ /* Now, we do the remaining detection. If no `force' parameter is used. */
+
+ /* First, the generic detection (if any), that is skipped if any force
+ parameter was used. */
+ if (kind < 0) {
+ /* The below is of course bogus */
+ if (foo_read(new_client,FOO_REG_GENERIC) != FOO_GENERIC_VALUE)
+ goto ERROR1;
+ }
+
+ /* SENSORS ONLY START */
+
+ /* Next, specific detection. This is especially important for `sensors'
+ devices. */
+
+ /* Determine the chip type. Not needed if a `force_CHIPTYPE' parameter
+ was used. */
+ if (kind <= 0) {
+ i = foo_read(new_client,FOO_REG_CHIPTYPE);
+ if (i == FOO_TYPE_1)
+ kind = chip1; /* As defined in the enum */
+ else if (i == FOO_TYPE_2)
+ kind = chip2;
+ else {
+ printk("foo: Ignoring 'force' parameter for unknown chip at "
+ "adapter %d, address 0x%02x\n",i2c_adapter_id(adapter),address);
+ goto ERROR1;
+ }
+ }
+
+ /* Now set the type and chip names */
+ if (kind == chip1) {
+ type_name = "chip1"; /* For /proc entry */
+ client_name = "CHIP 1";
+ } else if (kind == chip2) {
+ type_name = "chip2"; /* For /proc entry */
+ client_name = "CHIP 2";
+ }
+
+ /* Reserve the ISA region */
+ if (is_isa)
+ request_region(address,FOO_EXTENT,type_name);
+
+ /* SENSORS ONLY END */
+
+ /* Fill in the remaining client fields. */
+ strcpy(new_client->name,client_name);
+
+ /* SENSORS ONLY BEGIN */
+ data->type = kind;
+ /* SENSORS ONLY END */
+
+ data->valid = 0; /* Only if you use this field */
+ init_MUTEX(&data->update_lock); /* Only if you use this field */
+
+ /* Any other initializations in data must be done here too. */
+
+ /* Tell the i2c layer a new client has arrived */
+ if ((err = i2c_attach_client(new_client)))
+ goto ERROR3;
+
+ /* SENSORS ONLY BEGIN */
+ /* Register a new directory entry with module sensors. See below for
+ the `template' structure. */
+ if ((i = i2c_register_entry(new_client, type_name,
+ foo_dir_table_template,THIS_MODULE)) < 0) {
+ err = i;
+ goto ERROR4;
+ }
+ data->sysctl_id = i;
+
+ /* SENSORS ONLY END */
+
+ /* This function can write default values to the client registers, if
+ needed. */
+ foo_init_client(new_client);
+ return 0;
+
+ /* OK, this is not exactly good programming practice, usually. But it is
+ very code-efficient in this case. */
+
+ ERROR4:
+ i2c_detach_client(new_client);
+ ERROR3:
+ ERROR2:
+ /* SENSORS ONLY START */
+ if (is_isa)
+ release_region(address,FOO_EXTENT);
+ /* SENSORS ONLY END */
+ ERROR1:
+ kfree(new_client);
+ ERROR0:
+ return err;
+ }
+
+
+Removing the client
+===================
+
+The detach_client call back function is called when a client should be
+removed. It may actually fail, but only when panicking. This code is
+much simpler than the attachment code, fortunately!
+
+ int foo_detach_client(struct i2c_client *client)
+ {
+ int err,i;
+
+ /* SENSORS ONLY START */
+ /* Deregister with the `i2c-proc' module. */
+ i2c_deregister_entry(((struct lm78_data *)(client->data))->sysctl_id);
+ /* SENSORS ONLY END */
+
+ /* Try to detach the client from i2c space */
+ if ((err = i2c_detach_client(client))) {
+ printk("foo.o: Client deregistration failed, client not detached.\n");
+ return err;
+ }
+
+ /* SENSORS ONLY START */
+ if i2c_is_isa_client(client)
+ release_region(client->addr,LM78_EXTENT);
+ /* SENSORS ONLY END */
+
+ kfree(client); /* Frees client data too, if allocated at the same time */
+ return 0;
+ }
+
+
+Initializing the module or kernel
+=================================
+
+When the kernel is booted, or when your foo driver module is inserted,
+you have to do some initializing. Fortunately, just attaching (registering)
+the driver module is usually enough.
+
+ /* Keep track of how far we got in the initialization process. If several
+ things have to initialized, and we fail halfway, only those things
+ have to be cleaned up! */
+ static int __initdata foo_initialized = 0;
+
+ static int __init foo_init(void)
+ {
+ int res;
+ printk("foo version %s (%s)\n",FOO_VERSION,FOO_DATE);
+
+ if ((res = i2c_add_driver(&foo_driver))) {
+ printk("foo: Driver registration failed, module not inserted.\n");
+ foo_cleanup();
+ return res;
+ }
+ foo_initialized ++;
+ return 0;
+ }
+
+ void foo_cleanup(void)
+ {
+ if (foo_initialized == 1) {
+ if ((res = i2c_del_driver(&foo_driver))) {
+ printk("foo: Driver registration failed, module not removed.\n");
+ return;
+ }
+ foo_initialized --;
+ }
+ }
+
+ /* Substitute your own name and email address */
+ MODULE_AUTHOR("Frodo Looijaard <frodol@dds.nl>"
+ MODULE_DESCRIPTION("Driver for Barf Inc. Foo I2C devices");
+
+ module_init(foo_init);
+ module_exit(foo_cleanup);
+
+Note that some functions are marked by `__init', and some data structures
+by `__init_data'. Hose functions and structures can be removed after
+kernel booting (or module loading) is completed.
+
+Command function
+================
+
+A generic ioctl-like function call back is supported. You will seldom
+need this. You may even set it to NULL.
+
+ /* No commands defined */
+ int foo_command(struct i2c_client *client, unsigned int cmd, void *arg)
+ {
+ return 0;
+ }
+
+
+Sending and receiving
+=====================
+
+If you want to communicate with your device, there are several functions
+to do this. You can find all of them in i2c.h.
+
+If you can choose between plain i2c communication and SMBus level
+communication, please use the last. All adapters understand SMBus level
+commands, but only some of them understand plain i2c!
+
+
+Plain i2c communication
+-----------------------
+
+ extern int i2c_master_send(struct i2c_client *,const char* ,int);
+ extern int i2c_master_recv(struct i2c_client *,char* ,int);
+
+These routines read and write some bytes from/to a client. The client
+contains the i2c address, so you do not have to include it. The second
+parameter contains the bytes the read/write, the third the length of the
+buffer. Returned is the actual number of bytes read/written.
+
+ extern int i2c_transfer(struct i2c_adapter *adap, struct i2c_msg *msg,
+ int num);
+
+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
+-------------------
+
+ extern s32 i2c_smbus_xfer (struct i2c_adapter * adapter, u16 addr,
+ unsigned short flags,
+ char read_write, u8 command, int size,
+ union i2c_smbus_data * data);
+
+ This is the generic SMBus function. All functions below are implemented
+ in terms of it. Never use this function directly!
+
+
+ extern s32 i2c_smbus_write_quick(struct i2c_client * client, u8 value);
+ extern s32 i2c_smbus_read_byte(struct i2c_client * client);
+ extern s32 i2c_smbus_write_byte(struct i2c_client * client, u8 value);
+ extern s32 i2c_smbus_read_byte_data(struct i2c_client * client, u8 command);
+ extern s32 i2c_smbus_write_byte_data(struct i2c_client * client,
+ u8 command, u8 value);
+ extern s32 i2c_smbus_read_word_data(struct i2c_client * client, u8 command);
+ extern s32 i2c_smbus_write_word_data(struct i2c_client * client,
+ u8 command, u16 value);
+ extern s32 i2c_smbus_write_block_data(struct i2c_client * client,
+ u8 command, u8 length,
+ u8 *values);
+
+These ones were removed in Linux 2.6.10 because they had no users, but could
+be added back later if needed:
+
+ extern s32 i2c_smbus_read_i2c_block_data(struct i2c_client * client,
+ u8 command, u8 *values);
+ extern s32 i2c_smbus_read_block_data(struct i2c_client * client,
+ u8 command, u8 *values);
+ extern s32 i2c_smbus_write_i2c_block_data(struct i2c_client * client,
+ u8 command, u8 length,
+ u8 *values);
+ extern s32 i2c_smbus_process_call(struct i2c_client * client,
+ u8 command, u16 value);
+ extern s32 i2c_smbus_block_process_call(struct i2c_client *client,
+ u8 command, u8 length,
+ u8 *values)
+
+All these transactions return -1 on failure. The 'write' transactions
+return 0 on success; the 'read' transactions return the read value, except
+for read_block, which returns the number of values read. The block buffers
+need not be longer than 32 bytes.
+
+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.
+
+ /* This call returns a unique low identifier for each registered adapter,
+ * or -1 if the adapter was not registered.
+ */
+ extern int i2c_adapter_id(struct i2c_adapter *adap);
+
+
+The sensors sysctl/proc interface
+=================================
+
+This section only applies if you write `sensors' drivers.
+
+Each sensors driver creates a directory in /proc/sys/dev/sensors for each
+registered client. The directory is called something like foo-i2c-4-65.
+The sensors module helps you to do this as easily as possible.
+
+The template
+------------
+
+You will need to define a ctl_table template. This template will automatically
+be copied to a newly allocated structure and filled in where necessary when
+you call sensors_register_entry.
+
+First, I will give an example definition.
+ static ctl_table foo_dir_table_template[] = {
+ { FOO_SYSCTL_FUNC1, "func1", NULL, 0, 0644, NULL, &i2c_proc_real,
+ &i2c_sysctl_real,NULL,&foo_func },
+ { FOO_SYSCTL_FUNC2, "func2", NULL, 0, 0644, NULL, &i2c_proc_real,
+ &i2c_sysctl_real,NULL,&foo_func },
+ { FOO_SYSCTL_DATA, "data", NULL, 0, 0644, NULL, &i2c_proc_real,
+ &i2c_sysctl_real,NULL,&foo_data },
+ { 0 }
+ };
+
+In the above example, three entries are defined. They can either be
+accessed through the /proc interface, in the /proc/sys/dev/sensors/*
+directories, as files named func1, func2 and data, or alternatively
+through the sysctl interface, in the appropriate table, with identifiers
+FOO_SYSCTL_FUNC1, FOO_SYSCTL_FUNC2 and FOO_SYSCTL_DATA.
+
+The third, sixth and ninth parameters should always be NULL, and the
+fourth should always be 0. The fifth is the mode of the /proc file;
+0644 is safe, as the file will be owned by root:root.
+
+The seventh and eighth parameters should be &i2c_proc_real and
+&i2c_sysctl_real if you want to export lists of reals (scaled
+integers). You can also use your own function for them, as usual.
+Finally, the last parameter is the call-back to gather the data
+(see below) if you use the *_proc_real functions.
+
+
+Gathering the data
+------------------
+
+The call back functions (foo_func and foo_data in the above example)
+can be called in several ways; the operation parameter determines
+what should be done:
+
+ * If operation == SENSORS_PROC_REAL_INFO, you must return the
+ magnitude (scaling) in nrels_mag;
+ * If operation == SENSORS_PROC_REAL_READ, you must read information
+ from the chip and return it in results. The number of integers
+ to display should be put in nrels_mag;
+ * If operation == SENSORS_PROC_REAL_WRITE, you must write the
+ supplied information to the chip. nrels_mag will contain the number
+ of integers, results the integers themselves.
+
+The *_proc_real functions will display the elements as reals for the
+/proc interface. If you set the magnitude to 2, and supply 345 for
+SENSORS_PROC_REAL_READ, it would display 3.45; and if the user would
+write 45.6 to the /proc file, it would be returned as 4560 for
+SENSORS_PROC_REAL_WRITE. A magnitude may even be negative!
+
+An example function:
+
+ /* FOO_FROM_REG and FOO_TO_REG translate between scaled values and
+ register values. Note the use of the read cache. */
+ void foo_in(struct i2c_client *client, int operation, int ctl_name,
+ int *nrels_mag, long *results)
+ {
+ struct foo_data *data = client->data;
+ int nr = ctl_name - FOO_SYSCTL_FUNC1; /* reduce to 0 upwards */
+
+ if (operation == SENSORS_PROC_REAL_INFO)
+ *nrels_mag = 2;
+ else if (operation == SENSORS_PROC_REAL_READ) {
+ /* Update the readings cache (if necessary) */
+ foo_update_client(client);
+ /* Get the readings from the cache */
+ results[0] = FOO_FROM_REG(data->foo_func_base[nr]);
+ results[1] = FOO_FROM_REG(data->foo_func_more[nr]);
+ results[2] = FOO_FROM_REG(data->foo_func_readonly[nr]);
+ *nrels_mag = 2;
+ } else if (operation == SENSORS_PROC_REAL_WRITE) {
+ if (*nrels_mag >= 1) {
+ /* Update the cache */
+ data->foo_base[nr] = FOO_TO_REG(results[0]);
+ /* Update the chip */
+ foo_write_value(client,FOO_REG_FUNC_BASE(nr),data->foo_base[nr]);
+ }
+ if (*nrels_mag >= 2) {
+ /* Update the cache */
+ data->foo_more[nr] = FOO_TO_REG(results[1]);
+ /* Update the chip */
+ foo_write_value(client,FOO_REG_FUNC_MORE(nr),data->foo_more[nr]);
+ }
+ }
+ }