bkgpl/cyb4_linux
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Creation of Cybook 2416 (actually Gen4) repository

Browse Source
This commit is contained in:
mlt
2009-12-18 17:10:00 +00:00
committed by godzil
commit 76f20f4d40
13791 changed files with 6812321 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

42
Documentation/i2c/busses/i2c-ali1535 Normal file
View File

@@ -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.

27
Documentation/i2c/busses/i2c-ali1563 Normal file
View File

@@ -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.

112
Documentation/i2c/busses/i2c-ali15x3 Normal file
View File

@@ -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.

25
Documentation/i2c/busses/i2c-amd756 Normal file
View File

@@ -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.

41
Documentation/i2c/busses/i2c-amd8111 Normal file
View File

@@ -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 the publicly available ACPI 2.0 specification, which the adapter
follows.
Author: Vojtech Pavlik <vojtech@suse.cz>
Description
-----------
If you see something like this:
00:07.2 SMBus: Advanced Micro Devices [AMD] AMD-8111 SMBus 2.0 (rev 02)
Subsystem: Advanced Micro Devices [AMD] AMD-8111 SMBus 2.0
Flags: medium devsel, IRQ 19
I/O ports at d400 [size=32]
in your 'lspci -v', then this driver is for your chipset.
Process Call Support
--------------------
Supported.
SMBus 2.0 Support
-----------------
Supported. Both PEC and block process call support is implemented. Slave
mode or host notification are not yet implemented.
Notes
-----
Note that for the 8111, there are two SMBus adapters. The SMBus 2.0 adapter
is supported by this driver, and the SMBus 1.0 adapter is supported by the
i2c-amd756 driver.

132
Documentation/i2c/busses/i2c-i801 Normal file
View File

@@ -0,0 +1,132 @@
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 82801G (ICH7)
* Intel 631xESB/632xESB (ESB2)
* Intel 82801H (ICH8)
* Intel ICH9
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
-----------------
None.
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.
The ICH chips are quite similar to Intel's PIIX4 chip, at least in the
SMBus controller.
Process Call Support
--------------------
Not supported.
I2C Block Read Support
----------------------
Not supported at the moment.
SMBus 2.0 Support
-----------------
The 82801DB (ICH4) and later chips support several SMBus 2.0 features.
Hidden ICH SMBus
----------------
If your system has an Intel ICH south bridge, but you do NOT see the
SMBus device at 00:1f.3 in lspci, and you can't figure out any way in the
BIOS to enable it, it means it has been hidden by the BIOS code. Asus is
well known for first doing this on their P4B motherboard, and many other
boards after that. Some vendor machines are affected as well.
The first thing to try is the "i2c_ec" ACPI driver. It could be that the
SMBus was hidden on purpose because it'll be driven by ACPI. If the
i2c_ec driver works for you, just forget about the i2c-i801 driver and
don't try to unhide the ICH SMBus. Even if i2c_ec doesn't work, you
better make sure that the SMBus isn't used by the ACPI code. Try loading
the "fan" and "thermal" drivers, and check in /proc/acpi/fan and
/proc/acpi/thermal_zone. If you find anything there, it's likely that
the ACPI is accessing the SMBus and it's safer not to unhide it. Only
once you are certain that ACPI isn't using the SMBus, you can attempt
to unhide it.
In order to unhide the SMBus, we need to change the value of a PCI
register before the kernel enumerates the PCI devices. This is done in
drivers/pci/quirks.c, where all affected boards must be listed (see
function asus_hides_smbus_hostbridge.) If the SMBus device is missing,
and you think there's something interesting on the SMBus (e.g. a
hardware monitoring chip), you need to add your board to the list.
The motherboard is identified using the subvendor and subdevice IDs of the
host bridge PCI device. Get yours with "lspci -n -v -s 00:00.0":
00:00.0 Class 0600: 8086:2570 (rev 02)
Subsystem: 1043:80f2
Flags: bus master, fast devsel, latency 0
Memory at fc000000 (32-bit, prefetchable) [size=32M]
Capabilities: [e4] #09 [2106]
Capabilities: [a0] AGP version 3.0
Here the host bridge ID is 2570 (82865G/PE/P), the subvendor ID is 1043
(Asus) and the subdevice ID is 80f2 (P4P800-X). You can find the symbolic
names for the bridge ID and the subvendor ID in include/linux/pci_ids.h,
and then add a case for your subdevice ID at the right place in
drivers/pci/quirks.c. Then please give it very good testing, to make sure
that the unhidden SMBus doesn't conflict with e.g. ACPI.
If it works, proves useful (i.e. there are usable chips on the SMBus)
and seems safe, please submit a patch for inclusion into the kernel.
Note: There's a useful script in lm_sensors 2.10.2 and later, named
unhide_ICH_SMBus (in prog/hotplug), which uses the fakephp driver to
temporarily unhide the SMBus without having to patch and recompile your
kernel. It's very convenient if you just want to check if there's
anything interesting on your hidden ICH SMBus.
**********************
The lm_sensors project gratefully acknowledges the support of Texas
Instruments in the initial development of this driver.
The lm_sensors project gratefully acknowledges the support of Intel in the
development of SMBus 2.0 / ICH4 features of this driver.

47
Documentation/i2c/busses/i2c-i810 Normal file
View File

@@ -0,0 +1,47 @@
Kernel driver i2c-i810
Supported adapters:
* Intel 82810, 82810-DC100, 82810E, and 82815 (GMCH)
* Intel 82845G (GMCH)
Authors:
Frodo Looijaard <frodol@dds.nl>,
Philip Edelbrock <phil@netroedge.com>,
Ky<4B>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.

44
Documentation/i2c/busses/i2c-nforce2 Normal file
View File

@@ -0,0 +1,44 @@
Kernel driver i2c-nforce2
Supported adapters:
* nForce2 MCP 10de:0064
* nForce2 Ultra 400 MCP 10de:0084
* nForce3 Pro150 MCP 10de:00D4
* nForce3 250Gb MCP 10de:00E4
* nForce4 MCP 10de:0052
* nForce4 MCP-04 10de:0034
* nForce4 MCP51 10de:0264
* nForce4 MCP55 10de:0368
Datasheet: not publicly available, but seems to be similar to the
AMD-8111 SMBus 2.0 adapter.
Authors:
Hans-Frieder Vogt <hfvogt@gmx.net>,
Thomas Leibold <thomas@plx.com>,
Patrick Dreker <patrick@dreker.de>
Description
-----------
i2c-nforce2 is a driver for the SMBuses included in the nVidia nForce2 MCP.
If your 'lspci -v' listing shows something like the following,
00:01.1 SMBus: nVidia Corporation: Unknown device 0064 (rev a2)
Subsystem: Asustek Computer, Inc.: Unknown device 0c11
Flags: 66Mhz, fast devsel, IRQ 5
I/O ports at c000 [size=32]
Capabilities: <available only to root>
then this driver should support the SMBuses of your motherboard.
Notes
-----
The SMBus adapter in the nForce2 chipset seems to be very similar to the
SMBus 2.0 adapter in the AMD-8111 south bridge. However, I could only get
the driver to work with direct I/O access, which is different to the EC
interface of the AMD-8111. Tested on Asus A7N8X. The ACPI DSDT table of the
Asus A7N8X lists two SMBuses, both of which are supported by this driver.

51
Documentation/i2c/busses/i2c-ocores Normal file
View File

@@ -0,0 +1,51 @@
Kernel driver i2c-ocores
Supported adapters:
* OpenCores.org I2C controller by Richard Herveille (see datasheet link)
Datasheet: http://www.opencores.org/projects.cgi/web/i2c/overview
Author: Peter Korsgaard <jacmet@sunsite.dk>
Description
-----------
i2c-ocores is an i2c bus driver for the OpenCores.org I2C controller
IP core by Richard Herveille.
Usage
-----
i2c-ocores uses the platform bus, so you need to provide a struct
platform_device with the base address and interrupt number. The
dev.platform_data of the device should also point to a struct
ocores_i2c_platform_data (see linux/i2c-ocores.h) describing the
distance between registers and the input clock speed.
E.G. something like:
static struct resource ocores_resources[] = {
[0] = {
.start = MYI2C_BASEADDR,
.end = MYI2C_BASEADDR + 8,
.flags = IORESOURCE_MEM,
},
[1] = {
.start = MYI2C_IRQ,
.end = MYI2C_IRQ,
.flags = IORESOURCE_IRQ,
},
};
static struct ocores_i2c_platform_data myi2c_data = {
.regstep = 2, /* two bytes between registers */
.clock_khz = 50000, /* input clock of 50MHz */
};
static struct platform_device myi2c = {
.name = "ocores-i2c",
.dev = {
.platform_data = &myi2c_data,
},
.num_resources = ARRAY_SIZE(ocores_resources),
.resource = ocores_resources,
};

174
Documentation/i2c/busses/i2c-parport Normal file
View File

@@ -0,0 +1,174 @@
Kernel driver i2c-parport
Author: Jean Delvare <khali@linux-fr.org>
This is a unified driver for several i2c-over-parallel-port adapters,
such as the ones made by Philips, Velleman or ELV. This driver is
meant as a replacement for the older, individual drivers:
* i2c-philips-par
* i2c-elv
* i2c-velleman
* video/i2c-parport (NOT the same as this one, dedicated to home brew
teletext adapters)
It currently supports the following devices:
* (type=0) Philips adapter
* (type=1) home brew teletext adapter
* (type=2) Velleman K8000 adapter
* (type=3) ELV adapter
* (type=4) Analog Devices ADM1032 evaluation board
* (type=5) Analog Devices evaluation boards: ADM1025, ADM1030, ADM1031
* (type=6) Barco LPT->DVI (K5800236) adapter
* (type=7) One For All JP1 parallel port adapter
These devices use different pinout configurations, so you have to tell
the driver what you have, using the type module parameter. There is no
way to autodetect the devices. Support for different pinout configurations
can be easily added when needed.
Earlier kernels defaulted to type=0 (Philips). But now, if the type
parameter is missing, the driver will simply fail to initialize.
Building your own adapter
-------------------------
If you want to build you own i2c-over-parallel-port adapter, here is
a sample electronics schema (credits go to Sylvain Munaut):
Device PC
Side ___________________Vdd (+) Side
| | |
--- --- ---
| | | | | |
|R| |R| |R|
| | | | | |
--- --- ---
| | |
| | /| |
SCL ----------x--------o |-----------x------------------- pin 2
| \| | |
| | |
| |\ | |
SDA ----------x----x---| o---x--------------------------- pin 13
| |/ |
| |
| /| |
---------o |----------------x-------------- pin 3
\| | |
| |
--- ---
| | | |
|R| |R|
| | | |
--- ---
| |
### ###
GND GND
Remarks:
- This is the exact pinout and electronics used on the Analog Devices
evaluation boards.
/|
- All inverters -o |- must be 74HC05, they must be open collector output.
\|
- All resitors are 10k.
- Pins 18-25 of the parallel port connected to GND.
- Pins 4-9 (D2-D7) could be used as VDD is the driver drives them high.
The ADM1032 evaluation board uses D4-D7. Beware that the amount of
current you can draw from the parallel port is limited. Also note that
all connected lines MUST BE driven at the same state, else you'll short
circuit the output buffers! So plugging the I2C adapter after loading
the i2c-parport module might be a good safety since data line state
prior to init may be unknown.
- This is 5V!
- Obviously you cannot read SCL (so it's not really standard-compliant).
Pretty easy to add, just copy the SDA part and use another input pin.
That would give (ELV compatible pinout):
Device PC
Side ______________________________Vdd (+) Side
| | | |
--- --- --- ---
| | | | | | | |
|R| |R| |R| |R|
| | | | | | | |
--- --- --- ---
| | | |
| | |\ | |
SCL ----------x--------x--| o---x------------------------ pin 15
| | |/ |
| | |
| | /| |
| ---o |-------------x-------------- pin 2
| \| | |
| | |
| | |
| |\ | |
SDA ---------------x---x--| o--------x------------------- pin 10
| |/ |
| |
| /| |
---o |------------------x--------- pin 3
\| | |
| |
--- ---
| | | |
|R| |R|
| | | |
--- ---
| |
### ###
GND GND
If possible, you should use the same pinout configuration as existing
adapters do, so you won't even have to change the code.
Similar (but different) drivers
-------------------------------
This driver is NOT the same as the i2c-pport driver found in the i2c
package. The i2c-pport driver makes use of modern parallel port features so
that you don't need additional electronics. It has other restrictions
however, and was not ported to Linux 2.6 (yet).
This driver is also NOT the same as the i2c-pcf-epp driver found in the
lm_sensors package. The i2c-pcf-epp driver doesn't use the parallel port as
an I2C bus directly. Instead, it uses it to control an external I2C bus
master. That driver was not ported to Linux 2.6 (yet) either.
Legacy documentation for Velleman adapter
-----------------------------------------
Useful links:
Velleman http://www.velleman.be/
Velleman K8000 Howto http://howto.htlw16.ac.at/k8000-howto.html
The project has lead to new libs for the Velleman K8000 and K8005:
LIBK8000 v1.99.1 and LIBK8005 v0.21
With these libs, you can control the K8000 interface card and the K8005
stepper motor card with the simple commands which are in the original
Velleman software, like SetIOchannel, ReadADchannel, SendStepCCWFull and
many more, using /dev/velleman.
http://home.wanadoo.nl/hihihi/libk8000.htm
http://home.wanadoo.nl/hihihi/libk8005.htm
http://struyve.mine.nu:8080/index.php?block=k8000
http://sourceforge.net/projects/libk8005/
One For All JP1 parallel port adapter
-------------------------------------
The JP1 project revolves around a set of remote controls which expose
the I2C bus their internal configuration EEPROM lives on via a 6 pin
jumper in the battery compartment. More details can be found at:
http://www.hifi-remote.com/jp1/
Details of the simple parallel port hardware can be found at:
http://www.hifi-remote.com/jp1/hardware.shtml

11
Documentation/i2c/busses/i2c-parport-light Normal file
View File

@@ -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.

23
Documentation/i2c/busses/i2c-pca-isa Normal file
View File

@@ -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

98
Documentation/i2c/busses/i2c-piix4 Normal file
View File

@@ -0,0 +1,98 @@
Kernel driver i2c-piix4
Supported adapters:
* Intel 82371AB PIIX4 and PIIX4E
* Intel 82443MX (440MX)
Datasheet: Publicly available at the Intel website
* ServerWorks OSB4, CSB5, CSB6 and HT-1000 southbridges
Datasheet: Only available via NDA from ServerWorks
* ATI IXP200, IXP300, IXP400 and SB600 southbridges
Datasheet: Not publicly available
* Standard Microsystems (SMSC) SLC90E66 (Victory66) southbridge
Datasheet: Publicly available at the SMSC website http://www.smsc.com
Authors:
Frodo Looijaard <frodol@dds.nl>
Philip Edelbrock <phil@netroedge.com>
Module Parameters
-----------------
* force: int
Forcibly enable the PIIX4. DANGEROUS!
* force_addr: int
Forcibly enable the PIIX4 at the given address. EXTREMELY DANGEROUS!
Description
-----------
The PIIX4 (properly known as the 82371AB) is an Intel chip with a lot of
functionality. Among other things, it implements the PCI bus. One of its
minor functions is implementing a System Management Bus. This is a true
SMBus - you can not access it on I2C levels. The good news is that it
natively understands SMBus commands and you do not have to worry about
timing problems. The bad news is that non-SMBus devices connected to it can
confuse it mightily. Yes, this is known to happen...
Do 'lspci -v' and see whether it contains an entry like this:
0000:00:02.3 Bridge: Intel Corp. 82371AB/EB/MB PIIX4 ACPI (rev 02)
Flags: medium devsel, IRQ 9
Bus and device numbers may differ, but the function number must be
identical (like many PCI devices, the PIIX4 incorporates a number of
different 'functions', which can be considered as separate devices). If you
find such an entry, you have a PIIX4 SMBus controller.
On some computers (most notably, some Dells), the SMBus is disabled by
default. If you use the insmod parameter 'force=1', the kernel module will
try to enable it. THIS IS VERY DANGEROUS! If the BIOS did not set up a
correct address for this module, you could get in big trouble (read:
crashes, data corruption, etc.). Try this only as a last resort (try BIOS
updates first, for example), and backup first! An even more dangerous
option is 'force_addr=<IOPORT>'. This will not only enable the PIIX4 like
'force' foes, but it will also set a new base I/O port address. The SMBus
parts of the PIIX4 needs a range of 8 of these addresses to function
correctly. If these addresses are already reserved by some other device,
you will get into big trouble! DON'T USE THIS IF YOU ARE NOT VERY SURE
ABOUT WHAT YOU ARE DOING!
The PIIX4E is just an new version of the PIIX4; it is supported as well.
The PIIX/PIIX3 does not implement an SMBus or I2C bus, so you can't use
this driver on those mainboards.
The ServerWorks Southbridges, the Intel 440MX, and the Victory66 are
identical to the PIIX4 in I2C/SMBus support.
If you own Force CPCI735 motherboard or other OSB4 based systems you may need
to change the SMBus Interrupt Select register so the SMBus controller uses
the SMI mode.
1) Use lspci command and locate the PCI device with the SMBus controller:
00:0f.0 ISA bridge: ServerWorks OSB4 South Bridge (rev 4f)
The line may vary for different chipsets. Please consult the driver source
for all possible PCI ids (and lspci -n to match them). Lets assume the
device is located at 00:0f.0.
2) Now you just need to change the value in 0xD2 register. Get it first with
command: lspci -xxx -s 00:0f.0
If the value is 0x3 then you need to change it to 0x1
setpci -s 00:0f.0 d2.b=1
Please note that you don't need to do that in all cases, just when the SMBus is
not working properly.
Hardware-specific issues
------------------------
This driver will refuse to load on IBM systems with an Intel PIIX4 SMBus.
Some of these machines have an RFID EEPROM (24RF08) connected to the SMBus,
which can easily get corrupted due to a state machine bug. These are mostly
Thinkpad laptops, but desktop systems may also be affected. We have no list
of all affected systems, so the only safe solution was to prevent access to
the SMBus on all IBM systems (detected using DMI data.)
For additional information, read:
http://www2.lm-sensors.nu/~lm78/cvs/lm_sensors2/README.thinkpad

23
Documentation/i2c/busses/i2c-prosavage Normal file
View File

@@ -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.

26
Documentation/i2c/busses/i2c-savage4 Normal file
View File

@@ -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.

59
Documentation/i2c/busses/i2c-sis5595 Normal file
View File

@@ -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.

49
Documentation/i2c/busses/i2c-sis630 Normal file
View File

@@ -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!

73
Documentation/i2c/busses/i2c-sis96x Normal file
View File

@@ -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: <i2c@lm-sensors.org>. Please send bug
reports and/or success stories as well.
TO DOs
------
* The driver does not support SMBus block reads/writes; I may add them if a
scenario is found where they're needed.
Thank You
---------
Mark D. Studebaker <mdsxyz123@yahoo.com>
- design hints and bug fixes
Alexander Maylsh <amalysh@web.de>
- ditto, plus an important datasheet... almost the one I really wanted
Hans-G<>nter L<>tke Uphues <hg_lu@t-online.de>
- patch for SiS735
Robert Zwerus <arzie@dds.nl>
- testing for SiS645DX
Kianusch Sayah Karadji <kianusch@sk-tech.net>
- patch for SiS645DX/962
Ken Healy
- patch for SiS655
To anyone else who has written w/ feedback, thanks!

34
Documentation/i2c/busses/i2c-via Normal file
View File

@@ -0,0 +1,34 @@
Kernel driver i2c-via
Supported adapters:
* VIA Technologies, InC. VT82C586B
Datasheet: Publicly available at the VIA website
Author: Ky<4B>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.

60
Documentation/i2c/busses/i2c-viapro Normal file
View File

@@ -0,0 +1,60 @@
Kernel driver i2c-viapro
Supported adapters:
* VIA Technologies, Inc. VT82C596A/B
Datasheet: Sometimes available at the VIA website
* VIA Technologies, Inc. VT82C686A/B
Datasheet: Sometimes available at the VIA website
* VIA Technologies, Inc. VT8231, VT8233, VT8233A
Datasheet: available on request from VIA
* VIA Technologies, Inc. VT8235, VT8237R, VT8237A, VT8251
Datasheet: available on request and under NDA from VIA
* VIA Technologies, Inc. CX700
Datasheet: available on request and under NDA from VIA
Authors:
Ky<4B>sti M<>lkki <kmalkki@cc.hut.fi>,
Mark D. Studebaker <mdsxyz123@yahoo.com>,
Jean Delvare <khali@linux-fr.org>
Module Parameters
-----------------
* force: int
Forcibly enable the SMBus controller. DANGEROUS!
* force_addr: int
Forcibly enable the SMBus at the given address. EXTREMELY DANGEROUS!
Description
-----------
i2c-viapro is a true SMBus host driver for motherboards with one of the
supported VIA south bridges.
Your lspci -n listing must show one of these :
device 1106:3050 (VT82C596A function 3)
device 1106:3051 (VT82C596B function 3)
device 1106:3057 (VT82C686 function 4)
device 1106:3074 (VT8233)
device 1106:3147 (VT8233A)
device 1106:8235 (VT8231 function 4)
device 1106:3177 (VT8235)
device 1106:3227 (VT8237R)
device 1106:3337 (VT8237A)
device 1106:3287 (VT8251)
device 1106:8324 (CX700)
If none of these show up, you should look in the BIOS for settings like
enable ACPI / SMBus or even USB.
Except for the oldest chips (VT82C596A/B, VT82C686A and most probably
VT8231), this driver supports I2C block transactions. Such transactions
are mainly useful to read from and write to EEPROMs.
The CX700 additionally appears to support SMBus PEC, although this driver
doesn't implement it yet.

62
Documentation/i2c/busses/i2c-voodoo3 Normal file
View File

@@ -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.

32
Documentation/i2c/busses/scx200_acb Normal file
View File

@@ -0,0 +1,32 @@
Kernel driver scx200_acb
Author: Christer Weinigel <wingel@nano-system.com>
The driver supersedes the older, never merged driver named i2c-nscacb.
Module Parameters
-----------------
* base: up to 4 ints
Base addresses for the ACCESS.bus controllers on SCx200 and SC1100 devices
By default the driver uses two base addresses 0x820 and 0x840.
If you want only one base address, specify the second as 0 so as to
override this default.
Description
-----------
Enable the use of the ACCESS.bus controller on the Geode SCx200 and
SC1100 processors and the CS5535 and CS5536 Geode companion devices.
Device-specific notes
---------------------
The SC1100 WRAP boards are known to use base addresses 0x810 and 0x820.
If the scx200_acb driver is built into the kernel, add the following
parameter to your boot command line:
scx200_acb.base=0x810,0x820
If the scx200_acb driver is built as a module, add the following line to
the file /etc/modprobe.conf instead:
options scx200_acb base=0x810,0x820

96
Documentation/i2c/chips/eeprom Normal file
View File

@@ -0,0 +1,96 @@
Kernel driver eeprom
====================
Supported chips:
* Any EEPROM chip in the designated address range
Prefix: 'eeprom'
Addresses scanned: I2C 0x50 - 0x57
Datasheets: Publicly available from:
Atmel (www.atmel.com),
Catalyst (www.catsemi.com),
Fairchild (www.fairchildsemi.com),
Microchip (www.microchip.com),
Philips (www.semiconductor.philips.com),
Rohm (www.rohm.com),
ST (www.st.com),
Xicor (www.xicor.com),
and others.
Chip Size (bits) Address
24C01 1K 0x50 (shadows at 0x51 - 0x57)
24C01A 1K 0x50 - 0x57 (Typical device on DIMMs)
24C02 2K 0x50 - 0x57
24C04 4K 0x50, 0x52, 0x54, 0x56
(additional data at 0x51, 0x53, 0x55, 0x57)
24C08 8K 0x50, 0x54 (additional data at 0x51, 0x52,
0x53, 0x55, 0x56, 0x57)
24C16 16K 0x50 (additional data at 0x51 - 0x57)
Sony 2K 0x57
Atmel 34C02B 2K 0x50 - 0x57, SW write protect at 0x30-37
Catalyst 34FC02 2K 0x50 - 0x57, SW write protect at 0x30-37
Catalyst 34RC02 2K 0x50 - 0x57, SW write protect at 0x30-37
Fairchild 34W02 2K 0x50 - 0x57, SW write protect at 0x30-37
Microchip 24AA52 2K 0x50 - 0x57, SW write protect at 0x30-37
ST M34C02 2K 0x50 - 0x57, SW write protect at 0x30-37
Authors:
Frodo Looijaard <frodol@dds.nl>,
Philip Edelbrock <phil@netroedge.com>,
Jean Delvare <khali@linux-fr.org>,
Greg Kroah-Hartman <greg@kroah.com>,
IBM Corp.
Description
-----------
This is a simple EEPROM module meant to enable reading the first 256 bytes
of an EEPROM (on a SDRAM DIMM for example). However, it will access serial
EEPROMs on any I2C adapter. The supported devices are generically called
24Cxx, and are listed above; however the numbering for these
industry-standard devices may vary by manufacturer.
This module was a programming exercise to get used to the new project
organization laid out by Frodo, but it should be at least completely
effective for decoding the contents of EEPROMs on DIMMs.
DIMMS will typically contain a 24C01A or 24C02, or the 34C02 variants.
The other devices will not be found on a DIMM because they respond to more
than one address.
DDC Monitors may contain any device. Often a 24C01, which responds to all 8
addresses, is found.
Recent Sony Vaio laptops have an EEPROM at 0x57. We couldn't get the
specification, so it is guess work and far from being complete.
The Microchip 24AA52/24LCS52, ST M34C02, and others support an additional
software write protect register at 0x30 - 0x37 (0x20 less than the memory
location). The chip responds to "write quick" detection at this address but
does not respond to byte reads. If this register is present, the lower 128
bytes of the memory array are not write protected. Any byte data write to
this address will write protect the memory array permanently, and the
device will no longer respond at the 0x30-37 address. The eeprom driver
does not support this register.
Lacking functionality:
* Full support for larger devices (24C04, 24C08, 24C16). These are not
typically found on a PC. These devices will appear as separate devices at
multiple addresses.
* Support for really large devices (24C32, 24C64, 24C128, 24C256, 24C512).
These devices require two-byte address fields and are not supported.
* Enable Writing. Again, no technical reason why not, but making it easy
to change the contents of the EEPROMs (on DIMMs anyway) also makes it easy
to disable the DIMMs (potentially preventing the computer from booting)
until the values are restored somehow.
Use:
After inserting the module (and any other required SMBus/i2c modules), you
should have some EEPROM directories in /sys/bus/i2c/devices/* of names such
as "0-0050". Inside each of these is a series of files, the eeprom file
contains the binary data from EEPROM.

108
Documentation/i2c/chips/max6875 Normal file
View File

@@ -0,0 +1,108 @@
Kernel driver max6875
=====================
Supported chips:
* Maxim MAX6874, MAX6875
Prefix: 'max6875'
Addresses scanned: None (see below)
Datasheet:
http://pdfserv.maxim-ic.com/en/ds/MAX6874-MAX6875.pdf
Author: Ben Gardner <bgardner@wabtec.com>
Description
-----------
The Maxim MAX6875 is an EEPROM-programmable power-supply sequencer/supervisor.
It provides timed outputs that can be used as a watchdog, if properly wired.
It also provides 512 bytes of user EEPROM.
At reset, the MAX6875 reads the configuration EEPROM into its configuration
registers. The chip then begins to operate according to the values in the
registers.
The Maxim MAX6874 is a similar, mostly compatible device, with more intputs
and outputs:
vin gpi vout
MAX6874 6 4 8
MAX6875 4 3 5
See the datasheet for more information.
Sysfs entries
-------------
eeprom - 512 bytes of user-defined EEPROM space.
General Remarks
---------------
Valid addresses for the MAX6875 are 0x50 and 0x52.
Valid addresses for the MAX6874 are 0x50, 0x52, 0x54 and 0x56.
The driver does not probe any address, so you must force the address.
Example:
$ modprobe max6875 force=0,0x50
The MAX6874/MAX6875 ignores address bit 0, so this driver attaches to multiple
addresses. For example, for address 0x50, it also reserves 0x51.
The even-address instance is called 'max6875', the odd one is 'max6875 subclient'.
Programming the chip using i2c-dev
----------------------------------
Use the i2c-dev interface to access and program the chips.
Reads and writes are performed differently depending on the address range.
The configuration registers are at addresses 0x00 - 0x45.
Use i2c_smbus_write_byte_data() to write a register and
i2c_smbus_read_byte_data() to read a register.
The command is the register number.
Examples:
To write a 1 to register 0x45:
i2c_smbus_write_byte_data(fd, 0x45, 1);
To read register 0x45:
value = i2c_smbus_read_byte_data(fd, 0x45);
The configuration EEPROM is at addresses 0x8000 - 0x8045.
The user EEPROM is at addresses 0x8100 - 0x82ff.
Use i2c_smbus_write_word_data() to write a byte to EEPROM.
The command is the upper byte of the address: 0x80, 0x81, or 0x82.
The data word is the lower part of the address or'd with data << 8.
cmd = address >> 8;
val = (address & 0xff) | (data << 8);
Example:
To write 0x5a to address 0x8003:
i2c_smbus_write_word_data(fd, 0x80, 0x5a03);
Reading data from the EEPROM is a little more complicated.
Use i2c_smbus_write_byte_data() to set the read address and then
i2c_smbus_read_byte() or i2c_smbus_read_i2c_block_data() to read the data.
Example:
To read data starting at offset 0x8100, first set the address:
i2c_smbus_write_byte_data(fd, 0x81, 0x00);
And then read the data
value = i2c_smbus_read_byte(fd);
or
count = i2c_smbus_read_i2c_block_data(fd, 0x84, buffer);
The block read should read 16 bytes.
0x84 is the block read command.
See the datasheet for more details.

47
Documentation/i2c/chips/pca9539 Normal file
View File

@@ -0,0 +1,47 @@
Kernel driver pca9539
=====================
Supported chips:
* Philips PCA9539
Prefix: 'pca9539'
Addresses scanned: 0x74 - 0x77
Datasheet:
http://www.semiconductors.philips.com/acrobat/datasheets/PCA9539_2.pdf
Author: Ben Gardner <bgardner@wabtec.com>
Description
-----------
The Philips PCA9539 is a 16 bit low power I/O device.
All 16 lines can be individually configured as an input or output.
The input sense can also be inverted.
The 16 lines are split between two bytes.
Sysfs entries
-------------
Each is a byte that maps to the 8 I/O bits.
A '0' suffix is for bits 0-7, while '1' is for bits 8-15.
input[01] - read the current value
output[01] - sets the output value
direction[01] - direction of each bit: 1=input, 0=output
invert[01] - toggle the input bit sense
input reads the actual state of the line and is always available.
The direction defaults to input for all channels.
General Remarks
---------------
Note that each output, direction, and invert entry controls 8 lines.
You should use the read, modify, write sequence.
For example. to set output bit 0 of 1.
val=$(cat output0)
val=$(( $val | 1 ))
echo $val > output0

69
Documentation/i2c/chips/pcf8574 Normal file
View File

@@ -0,0 +1,69 @@
Kernel driver pcf8574
=====================
Supported chips:
* Philips PCF8574
Prefix: 'pcf8574'
Addresses scanned: I2C 0x20 - 0x27
Datasheet: Publicly available at the Philips Semiconductors website
http://www.semiconductors.philips.com/pip/PCF8574P.html
* Philips PCF8574A
Prefix: 'pcf8574a'
Addresses scanned: I2C 0x38 - 0x3f
Datasheet: Publicly available at the Philips Semiconductors website
http://www.semiconductors.philips.com/pip/PCF8574P.html
Authors:
Frodo Looijaard <frodol@dds.nl>,
Philip Edelbrock <phil@netroedge.com>,
Dan Eaton <dan.eaton@rocketlogix.com>,
Aurelien Jarno <aurelien@aurel32.net>,
Jean Delvare <khali@linux-fr.org>,
Description
-----------
The PCF8574(A) is an 8-bit I/O expander for the I2C bus produced by Philips
Semiconductors. It is designed to provide a byte I2C interface to up to 16
separate devices (8 x PCF8574 and 8 x PCF8574A).
This device consists of a quasi-bidirectional port. Each of the eight I/Os
can be independently used as an input or output. To setup an I/O as an
input, you have to write a 1 to the corresponding output.
For more informations see the datasheet.
Accessing PCF8574(A) via /sys interface
-------------------------------------
! Be careful !
The PCF8574(A) is plainly impossible to detect ! Stupid chip.
So every chip with address in the interval [20..27] and [38..3f] are
detected as PCF8574(A). If you have other chips in this address
range, the workaround is to load this module after the one
for your others chips.
On detection (i.e. insmod, modprobe et al.), directories are being
created for each detected PCF8574(A):
/sys/bus/i2c/devices/<0>-<1>/
where <0> is the bus the chip was detected on (e. g. i2c-0)
and <1> the chip address ([20..27] or [38..3f]):
(example: /sys/bus/i2c/devices/1-0020/)
Inside these directories, there are two files each:
read and write (and one file with chip name).
The read file is read-only. Reading gives you the current I/O input
if the corresponding output is set as 1, otherwise the current output
value, that is to say 0.
The write file is read/write. Writing a value outputs it on the I/O
port. Reading returns the last written value.
On module initialization the chip is configured as eight inputs (all
outputs to 1), so you can connect any circuit to the PCF8574(A) without
being afraid of short-circuit.

90
Documentation/i2c/chips/pcf8591 Normal file
View File

@@ -0,0 +1,90 @@
Kernel driver pcf8591
=====================
Supported chips:
* Philips PCF8591
Prefix: 'pcf8591'
Addresses scanned: I2C 0x48 - 0x4f
Datasheet: Publicly available at the Philips Semiconductor website
http://www.semiconductors.philips.com/pip/PCF8591P.html
Authors:
Aurelien Jarno <aurelien@aurel32.net>
valuable contributions by Jan M. Sendler <sendler@sendler.de>,
Jean Delvare <khali@linux-fr.org>
Description
-----------
The PCF8591 is an 8-bit A/D and D/A converter (4 analog inputs and one
analog output) for the I2C bus produced by Philips Semiconductors. It
is designed to provide a byte I2C interface to up to 4 separate devices.
The PCF8591 has 4 analog inputs programmable as single-ended or
differential inputs :
- mode 0 : four single ended inputs
Pins AIN0 to AIN3 are single ended inputs for channels 0 to 3
- mode 1 : three differential inputs
Pins AIN3 is the common negative differential input
Pins AIN0 to AIN2 are positive differential inputs for channels 0 to 2
- mode 2 : single ended and differential mixed
Pins AIN0 and AIN1 are single ended inputs for channels 0 and 1
Pins AIN2 is the positive differential input for channel 3
Pins AIN3 is the negative differential input for channel 3
- mode 3 : two differential inputs
Pins AIN0 is the positive differential input for channel 0
Pins AIN1 is the negative differential input for channel 0
Pins AIN2 is the positive differential input for channel 1
Pins AIN3 is the negative differential input for channel 1
See the datasheet for details.
Module parameters
-----------------
* input_mode int
Analog input mode:
0 = four single ended inputs
1 = three differential inputs
2 = single ended and differential mixed
3 = two differential inputs
Accessing PCF8591 via /sys interface
-------------------------------------
! Be careful !
The PCF8591 is plainly impossible to detect ! Stupid chip.
So every chip with address in the interval [48..4f] is
detected as PCF8591. If you have other chips in this address
range, the workaround is to load this module after the one
for your others chips.
On detection (i.e. insmod, modprobe et al.), directories are being
created for each detected PCF8591:
/sys/bus/devices/<0>-<1>/
where <0> is the bus the chip was detected on (e. g. i2c-0)
and <1> the chip address ([48..4f])
Inside these directories, there are such files:
in0, in1, in2, in3, out0_enable, out0_output, name
Name contains chip name.
The in0, in1, in2 and in3 files are RO. Reading gives the value of the
corresponding channel. Depending on the current analog inputs configuration,
files in2 and/or in3 do not exist. Values range are from 0 to 255 for single
ended inputs and -128 to +127 for differential inputs (8-bit ADC).
The out0_enable file is RW. Reading gives "1" for analog output enabled and
"0" for analog output disabled. Writing accepts "0" and "1" accordingly.
The out0_output file is RW. Writing a number between 0 and 255 (8-bit DAC), send
the value to the digital-to-analog converter. Note that a voltage will
only appears on AOUT pin if aout0_enable equals 1. Reading returns the last
value written.

38
Documentation/i2c/chips/x1205 Normal file
View File

@@ -0,0 +1,38 @@
Kernel driver x1205
===================
Supported chips:
* Xicor X1205 RTC
Prefix: 'x1205'
Addresses scanned: none
Datasheet: http://www.intersil.com/cda/deviceinfo/0,1477,X1205,00.html
Authors:
Karen Spearel <kas11@tampabay.rr.com>,
Alessandro Zummo <a.zummo@towertech.it>
Description
-----------
This module aims to provide complete access to the Xicor X1205 RTC.
Recently Xicor has merged with Intersil, but the chip is
still sold under the Xicor brand.
This chip is located at address 0x6f and uses a 2-byte register addressing.
Two bytes need to be written to read a single register, while most
other chips just require one and take the second one as the data
to be written. To prevent corrupting unknown chips, the user must
explicitely set the probe parameter.
example:
modprobe x1205 probe=0,0x6f
The module supports one more option, hctosys, which is used to set the
software clock from the x1205. On systems where the x1205 is the
only hardware rtc, this parameter could be used to achieve a correct
date/time earlier in the system boot sequence.
example:
modprobe x1205 probe=0,0x6f hctosys=1

149
Documentation/i2c/dev-interface Normal file
View File

@@ -0,0 +1,149 @@
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-dev.h>". Please note that
there are two files named "i2c-dev.h" out there, one is distributed
with the Linux kernel and is meant to be included from kernel
driver code, the other one is distributed with lm_sensors and is
meant to be included from user-space programs. You obviously want
the second one here.
Now, you have to decide which adapter you want to access. You should
inspect /sys/class/i2c-dev/ to decide this. Adapter numbers are assigned
somewhat dynamically, so you can not even assume /dev/i2c-0 is the
first adapter.
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):
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_rdwr_ioctl_data *msgset)
Do combined read/write transaction without stop in between.
The argument is a pointer to a struct i2c_rdwr_ioctl_data {
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.

136
Documentation/i2c/functionality Normal file
View File

@@ -0,0 +1,136 @@
INTRODUCTION
------------
Because not every I2C or SMBus adapter implements everything in the
I2C specifications, a client can not trust that everything it needs
is implemented when it is given the option to attach to an adapter:
the client needs some way to check whether an adapter has the needed
functionality.
FUNCTIONALITY CONSTANTS
-----------------------
For the most up-to-date list of functionality constants, please check
<linux/i2c.h>!
I2C_FUNC_I2C Plain i2c-level commands (Pure SMBus
adapters typically can not do these)
I2C_FUNC_10BIT_ADDR Handles the 10-bit address extensions
I2C_FUNC_PROTOCOL_MANGLING Knows about the I2C_M_IGNORE_NAK,
I2C_M_REV_DIR_ADDR, I2C_M_NOSTART and
I2C_M_NO_RD_ACK 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 i2cdetect
program, is below:
int file;
if (file = open("/dev/i2c-0",O_RDWR) < 0) {
/* Some kind of error handling */
exit(1);
}
if (ioctl(file,I2C_FUNCS,&funcs) < 0) {
/* Some kind of error handling */
exit(1);
}
if (! (funcs & I2C_FUNC_SMBUS_QUICK)) {
/* Oops, the needed functionality (SMBus write_quick function) is
not available! */
exit(1);
}
/* Now it is safe to use the SMBus write_quick command */

76
Documentation/i2c/i2c-protocol Normal file
View File

@@ -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<61>[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.

49
Documentation/i2c/i2c-stub Normal file
View File

@@ -0,0 +1,49 @@
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.
You need to provide a chip address as a module parameter when loading
this driver, which will then only react to SMBus commands to this address.
No hardware is needed nor associated with this module. It will accept write
quick commands to one address; it will respond to the other commands (also
to one address) 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
PARAMETERS:
int chip_addr:
The SMBus address to emulate a chip at.
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.
Only one chip address is supported - although this module could be
extended to support more.
If you spam it hard enough, printk can be lossy. This module really wants
something like relayfs.

162
Documentation/i2c/porting-clients Normal file
View File

@@ -0,0 +1,162 @@
Revision 6, 2005-11-20
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.
Note that this guide is strongly oriented towards hardware monitoring
drivers. Many points are still valid for other type of drivers, but
others may be irrelevant.
There are two sets of points below. The first set concerns technical
changes. The second set concerns coding policy. Both are mandatory.
Although reading this guide will help you porting drivers, I suggest
you keep an eye on an already ported driver while porting your own
driver. This will help you a lot understanding what this guide
exactly means. Choose the chip driver that is the more similar to
yours for best results.
Technical changes:
* [Includes] Get rid of "version.h" and <linux/i2c-proc.h>.
Includes typically look like that:
#include <linux/module.h>
#include <linux/init.h>
#include <linux/slab.h>
#include <linux/jiffies.h>
#include <linux/i2c.h>
#include <linux/i2c-isa.h> /* for ISA drivers */
#include <linux/hwmon.h> /* for hardware monitoring drivers */
#include <linux/hwmon-sysfs.h>
#include <linux/hwmon-vid.h> /* if you need VRM support */
#include <linux/err.h> /* for class registration */
#include <asm/io.h> /* if you have I/O operations */
Please respect this inclusion order. Some extra headers may be
required for a given driver (e.g. "lm75.h").
* [Addresses] SENSORS_I2C_END becomes I2C_CLIENT_END, ISA addresses
are no more handled by the i2c core. Address ranges are no more
supported either, define each individual address separately.
SENSORS_INSMOD_<n> becomes I2C_CLIENT_INSMOD_<n>.
* [Client data] Get rid of sysctl_id. Try using standard names for
register values (for example, temp_os becomes temp_max). You're
still relatively free here, but you *have* to follow the standard
names for sysfs files (see the Sysctl section below).
* [Function prototypes] The detect functions loses its flags
parameter. Sysctl (e.g. lm75_temp) and miscellaneous functions
are off the list of prototypes. This usually leaves five
prototypes:
static int lm75_attach_adapter(struct i2c_adapter *adapter);
static int lm75_detect(struct i2c_adapter *adapter, int address,
int kind);
static void lm75_init_client(struct i2c_client *client);
static int lm75_detach_client(struct i2c_client *client);
static struct lm75_data lm75_update_device(struct device *dev);
* [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 (it87 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/hwmon/sysfs-interface for the individual files. Also
convert the units these files read and write to the specified ones.
If you need to add a new type of file, please discuss it on the
sensors mailing list <lm-sensors@lm-sensors.org> by providing a
patch to the Documentation/hwmon/sysfs-interface file.
* [Attach] For I2C drivers, the attach function should make sure
that the adapter's class has I2C_CLASS_HWMON (or whatever class is
suitable for your driver), using the following construct:
if (!(adapter->class & I2C_CLASS_HWMON))
return 0;
ISA-only drivers of course don't need this.
Call i2c_probe() instead of i2c_detect().
* [Detect] As mentioned earlier, the flags parameter is gone.
The type_name and client_name strings are replaced by a single
name string, which will be filled with a lowercase, short string.
In i2c-only drivers, drop the i2c_is_isa_adapter check, it's
useless. Same for isa-only drivers, as the test would always be
true. Only hybrid drivers (which are quite rare) still need it.
The labels used for error paths are reduced to the number needed.
It is advised that the labels are given descriptive names such as
exit and exit_free. Don't forget to properly set err before
jumping to error labels. By the way, labels should be left-aligned.
Use kzalloc instead of kmalloc.
Use i2c_set_clientdata to set the client data (as opposed to
a direct access to client->data).
Use strlcpy instead of strcpy or snprintf 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.
Register the client with the hwmon class (using hwmon_device_register)
if applicable.
Drop client->id.
Drop any 24RF08 corruption prevention you find, as this is now done
at the i2c-core level, and doing it twice voids it.
Don't add I2C_CLIENT_ALLOW_USE to client->flags, it's the default now.
* [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 it), and initialization should be
limited to the strictly necessary steps.
* [Detach] Remove the call to i2c_deregister_entry. Do not log an
error message if i2c_detach_client fails, as i2c-core will now do
it for you.
Unregister from the hwmon class if applicable.
* [Update] The function prototype changed, it is now
passed a device structure, which you have to convert to a client
using to_i2c_client(dev). The update function should return a
pointer to the client data.
Don't access client->data directly, use i2c_get_clientdata(client)
instead.
Use time_after() instead of direct jiffies comparison.
* [Interface] Make sure there is a MODULE_LICENSE() line, at the bottom
of the file (after MODULE_AUTHOR() and MODULE_DESCRIPTION(), in this
order).
* [Driver] The flags field of the i2c_driver structure is gone.
I2C_DF_NOTIFY is now the default behavior.
The i2c_driver structure has a driver member, which is itself a
structure, those name member should be initialized to a driver name
string. i2c_driver itself has no name member anymore.
* [Driver model] Instead of shutdown or reboot notifiers, provide a
shutdown() method in your driver.
* [Power management] Use the driver model suspend() and resume()
callbacks instead of the obsolete pm_register() calls.
Coding policy:
* [Copyright] Use (C), not (c), for copyright.
* [Debug/log] Get rid of #ifdef DEBUG/#endif constructs whenever you
can. Calls to printk for debugging purposes are replaced by calls to
dev_dbg where possible, else to pr_debug. Here is an example of 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) should be
aligned. This greatly improves readability.
Alignments are achieved by the means of tabs, not spaces. Remember
that tabs are set to 8 in the Linux kernel code.
* [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.

216
Documentation/i2c/smbus-protocol Normal file
View File

@@ -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 written to a device, to the designated register that is
specified through the Comm byte.
S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A] P
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

75
Documentation/i2c/summary Normal file
View File

@@ -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)

22
Documentation/i2c/ten-bit-addresses Normal file
View File

@@ -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.

741
Documentation/i2c/writing-clients Normal file
View File

@@ -0,0 +1,741 @@
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, and should be zero-initialized except for fields with data you
provide. A client structure holds device-specific information like the
driver model device node, and its I2C address.
static struct i2c_driver foo_driver = {
.driver = {
.name = "foo",
},
.attach_adapter = foo_attach_adapter,
.detach_client = foo_detach_client,
.shutdown = foo_shutdown, /* optional */
.suspend = foo_suspend, /* optional */
.resume = foo_resume, /* optional */
.command = foo_command, /* optional */
}
The name field is the driver name, and must not contain spaces. It
should match the module name (if the driver can be compiled as a module),
although you can use MODULE_ALIAS (passing "foo" in this example) to add
another name for the module.
All other fields are for call-back functions which will be explained
below.
Extra client data
=================
Each client structure has a special `data' field that can point to any
structure at all. You should use this to keep device-specific data,
especially in drivers that handle multiple I2C or SMBUS devices. You
do not always need this, but especially for `sensors' drivers, it can
be very useful.
/* store the value */
void i2c_set_clientdata(struct i2c_client *client, void *data);
/* retrieve the value */
void *i2c_get_clientdata(struct i2c_client *client);
An example structure is below.
struct foo_data {
struct i2c_client client;
struct semaphore lock; /* For ISA access in `sensors' drivers. */
int sysctl_id; /* To keep the /proc directory entry for
`sensors' drivers. */
enum chips type; /* To keep the chips type for `sensors' drivers. */
/* Because the i2c bus is slow, it is often useful to cache the read
information of a chip for some time (for example, 1 or 2 seconds).
It depends of course on the device whether this is really worthwhile
or even sensible. */
struct semaphore update_lock; /* When we are reading lots of information,
another process should not update the
below information */
char valid; /* != 0 if the following fields are valid. */
unsigned long last_updated; /* In jiffies */
/* Add the read information here too */
};
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() if you don't.
NOTE: If you want to write a `sensors' driver, the interface is slightly
different! See below.
Probing classes
---------------
All parameters are given as lists of unsigned 16-bit integers. Lists are
terminated by I2C_CLIENT_END.
The following lists are used internally:
normal_i2c: filled in by the module writer.
A list of I2C addresses which should normally be examined.
probe: insmod parameter.
A list of pairs. The first value is a bus number (-1 for any I2C bus),
the second is the address. These addresses are also probed, as if they
were in the 'normal' list.
ignore: insmod parameter.
A list of pairs. The first value is a bus number (-1 for any I2C bus),
the second is the I2C address. These addresses are never probed.
This parameter overrules the 'normal_i2c' list only.
force: insmod parameter.
A list of pairs. The first value is a bus number (-1 for any I2C bus),
the second is the I2C address. A device is blindly assumed to be on
the given address, no probing is done.
Additionally, kind-specific force lists may optionally be defined if
the driver supports several chip kinds. They are grouped in a
NULL-terminated list of pointers named forces, those first element if the
generic force list mentioned above. Each additional list correspond to an
insmod parameter of the form force_<kind>.
Fortunately, as a module writer, you just have to define the `normal_i2c'
parameter. The complete declaration could look like this:
/* Scan 0x37, and 0x48 to 0x4f */
static unsigned short normal_i2c[] = { 0x37, 0x48, 0x49, 0x4a, 0x4b, 0x4c,
0x4d, 0x4e, 0x4f, I2C_CLIENT_END };
/* Magic definition of all other variables and things */
I2C_CLIENT_INSMOD;
/* Or, if your driver supports, say, 2 kind of devices: */
I2C_CLIENT_INSMOD_2(foo, bar);
If you use the multi-kind form, an enum will be defined for you:
enum chips { any_chip, foo, bar, ... }
You can then (and certainly should) use it in the driver code.
Note that you *have* to call the defined variable `normal_i2c',
without any prefix!
Attaching to an adapter
-----------------------
Whenever a new adapter is inserted, or for all adapters if the driver is
being registered, the callback attach_adapter() is called. Now is the
time to determine what devices are present on the adapter, and to register
a client for each of them.
The attach_adapter callback is really easy: we just call the generic
detection function. This function will scan the bus for us, using the
information as defined in the lists explained above. If a device is
detected at a specific address, another callback is called.
int foo_attach_adapter(struct i2c_adapter *adapter)
{
return i2c_probe(adapter,&addr_data,&foo_detect_client);
}
Remember, structure `addr_data' is defined by the macros explained above,
so you do not have to define it yourself.
The i2c_probe function will call the foo_detect_client
function only for those i2c addresses that actually have a device on
them (unless a `force' parameter was used). In addition, addresses that
are already in use (by some other registered client) are skipped.
The detect client function
--------------------------
The detect client function is called by i2c_probe. The `kind' parameter
contains -1 for a probed detection, 0 for a forced detection, or a positive
number for a forced detection with a chip type forced.
Below, some things are only needed if this is a `sensors' driver. Those
parts are between /* SENSORS ONLY START */ and /* SENSORS ONLY END */
markers.
Returning an error different from -ENODEV in a detect function will cause
the detection to stop: other addresses and adapters won't be scanned.
This should only be done on fatal or internal errors, such as a memory
shortage or i2c_attach_client failing.
For now, you can ignore the `flags' parameter. It is there for future use.
int foo_detect_client(struct i2c_adapter *adapter, int address,
unsigned short flags, int kind)
{
int err = 0;
int i;
struct i2c_client *new_client;
struct foo_data *data;
const char *client_name = ""; /* For non-`sensors' drivers, put the real
name here! */
/* Let's see whether this adapter can support what we need.
Please substitute the things you need here!
For `sensors' drivers, add `! is_isa &&' to the if statement */
if (!i2c_check_functionality(adapter,I2C_FUNC_SMBUS_WORD_DATA |
I2C_FUNC_SMBUS_WRITE_BYTE))
goto ERROR0;
/* SENSORS ONLY START */
const char *type_name = "";
int is_isa = i2c_is_isa_adapter(adapter);
/* Do this only if the chip can additionally be found on the ISA bus
(hybrid chip). */
if (is_isa) {
/* Discard immediately if this ISA range is already used */
/* FIXME: never use check_region(), only request_region() */
if (check_region(address,FOO_EXTENT))
goto ERROR0;
/* Probe whether there is anything on this address.
Some example code is below, but you will have to adapt this
for your own driver */
if (kind < 0) /* Only if no force parameter was used */ {
/* We may need long timeouts at least for some chips. */
#define REALLY_SLOW_IO
i = inb_p(address + 1);
if (inb_p(address + 2) != i)
goto ERROR0;
if (inb_p(address + 3) != i)
goto ERROR0;
if (inb_p(address + 7) != i)
goto ERROR0;
#undef REALLY_SLOW_IO
/* Let's just hope nothing breaks here */
i = inb_p(address + 5) & 0x7f;
outb_p(~i & 0x7f,address+5);
if ((inb_p(address + 5) & 0x7f) != (~i & 0x7f)) {
outb_p(i,address+5);
return 0;
}
}
}
/* SENSORS ONLY END */
/* OK. For now, we presume we have a valid client. We now create the
client structure, even though we cannot fill it completely yet.
But it allows us to access several i2c functions safely */
if (!(data = kzalloc(sizeof(struct foo_data), GFP_KERNEL))) {
err = -ENOMEM;
goto ERROR0;
}
new_client = &data->client;
i2c_set_clientdata(new_client, data);
new_client->addr = address;
new_client->adapter = adapter;
new_client->driver = &foo_driver;
new_client->flags = 0;
/* Now, we do the remaining detection. If no `force' parameter is used. */
/* First, the generic detection (if any), that is skipped if any force
parameter was used. */
if (kind < 0) {
/* The below is of course bogus */
if (foo_read(new_client,FOO_REG_GENERIC) != FOO_GENERIC_VALUE)
goto ERROR1;
}
/* SENSORS ONLY START */
/* Next, specific detection. This is especially important for `sensors'
devices. */
/* Determine the chip type. Not needed if a `force_CHIPTYPE' parameter
was used. */
if (kind <= 0) {
i = foo_read(new_client,FOO_REG_CHIPTYPE);
if (i == FOO_TYPE_1)
kind = chip1; /* As defined in the enum */
else if (i == FOO_TYPE_2)
kind = chip2;
else {
printk("foo: Ignoring 'force' parameter for unknown chip at "
"adapter %d, address 0x%02x\n",i2c_adapter_id(adapter),address);
goto ERROR1;
}
}
/* Now set the type and chip names */
if (kind == chip1) {
type_name = "chip1"; /* For /proc entry */
client_name = "CHIP 1";
} else if (kind == chip2) {
type_name = "chip2"; /* For /proc entry */
client_name = "CHIP 2";
}
/* Reserve the ISA region */
if (is_isa)
request_region(address,FOO_EXTENT,type_name);
/* SENSORS ONLY END */
/* Fill in the remaining client fields. */
strcpy(new_client->name,client_name);
/* SENSORS ONLY BEGIN */
data->type = kind;
/* SENSORS ONLY END */
data->valid = 0; /* Only if you use this field */
init_MUTEX(&data->update_lock); /* Only if you use this field */
/* Any other initializations in data must be done here too. */
/* Tell the i2c layer a new client has arrived */
if ((err = i2c_attach_client(new_client)))
goto ERROR3;
/* SENSORS ONLY BEGIN */
/* Register a new directory entry with module sensors. See below for
the `template' structure. */
if ((i = i2c_register_entry(new_client, type_name,
foo_dir_table_template,THIS_MODULE)) < 0) {
err = i;
goto ERROR4;
}
data->sysctl_id = i;
/* SENSORS ONLY END */
/* This function can write default values to the client registers, if
needed. */
foo_init_client(new_client);
return 0;
/* OK, this is not exactly good programming practice, usually. But it is
very code-efficient in this case. */
ERROR4:
i2c_detach_client(new_client);
ERROR3:
ERROR2:
/* SENSORS ONLY START */
if (is_isa)
release_region(address,FOO_EXTENT);
/* SENSORS ONLY END */
ERROR1:
kfree(data);
ERROR0:
return err;
}
Removing the client
===================
The detach_client call back function is called when a client should be
removed. It may actually fail, but only when panicking. This code is
much simpler than the attachment code, fortunately!
int foo_detach_client(struct i2c_client *client)
{
int err,i;
/* SENSORS ONLY START */
/* Deregister with the `i2c-proc' module. */
i2c_deregister_entry(((struct lm78_data *)(client->data))->sysctl_id);
/* SENSORS ONLY END */
/* Try to detach the client from i2c space */
if ((err = i2c_detach_client(client)))
return err;
/* HYBRID SENSORS CHIP ONLY START */
if i2c_is_isa_client(client)
release_region(client->addr,LM78_EXTENT);
/* HYBRID SENSORS CHIP ONLY END */
kfree(i2c_get_clientdata(client));
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.
Power Management
================
If your I2C device needs special handling when entering a system low
power state -- like putting a transceiver into a low power mode, or
activating a system wakeup mechanism -- do that in the suspend() method.
The resume() method should reverse what the suspend() method does.
These are standard driver model calls, and they work just like they
would for any other driver stack. The calls can sleep, and can use
I2C messaging to the device being suspended or resumed (since their
parent I2C adapter is active when these calls are issued, and IRQs
are still enabled).
System Shutdown
===============
If your I2C device needs special handling when the system shuts down
or reboots (including kexec) -- like turning something off -- use a
shutdown() method.
Again, this is a standard driver model call, working just like it
would for any other driver stack: the calls can sleep, and can use
I2C messaging.
Command function
================
A generic ioctl-like function call back is supported. You will seldom
need this, and its use is deprecated anyway, so newer design should not
use it. Set it to NULL.
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);
extern s32 i2c_smbus_read_i2c_block_data(struct i2c_client * client,
u8 command, u8 *values);
These ones were removed in Linux 2.6.10 because they had no users, but could
be added back later if needed:
extern s32 i2c_smbus_read_block_data(struct i2c_client * client,
u8 command, u8 *values);
extern s32 i2c_smbus_write_i2c_block_data(struct i2c_client * client,
u8 command, u8 length,
u8 *values);
extern s32 i2c_smbus_process_call(struct i2c_client * client,
u8 command, u16 value);
extern s32 i2c_smbus_block_process_call(struct i2c_client *client,
u8 command, u8 length,
u8 *values)
All these transactions return -1 on failure. The 'write' transactions
return 0 on success; the 'read' transactions return the read value, except
for read_block, which returns the number of values read. The block buffers
need not be longer than 32 bytes.
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]);
}
}
}