xiaomi-sm8450/android_kernel_xiaomi_sm8450
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Linux-2.6.12-rc2

Browse Source 
Initial git repository build. I'm not bothering with the full history,
even though we have it. We can create a separate "historical" git
archive of that later if we want to, and in the meantime it's about
3.2GB when imported into git - space that would just make the early
git days unnecessarily complicated, when we don't have a lot of good
infrastructure for it.

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

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

@@ -0,0 +1,80 @@
Kernel driver i2c-i801
Supported adapters:
* Intel 82801AA and 82801AB (ICH and ICH0 - part of the
'810' and '810E' chipsets)
* Intel 82801BA (ICH2 - part of the '815E' chipset)
* Intel 82801CA/CAM (ICH3)
* Intel 82801DB (ICH4) (HW PEC supported, 32 byte buffer not supported)
* Intel 82801EB/ER (ICH5) (HW PEC supported, 32 byte buffer not supported)
* Intel 6300ESB
* Intel 82801FB/FR/FW/FRW (ICH6)
* Intel ICH7
Datasheets: Publicly available at the Intel website
Authors:
Frodo Looijaard <frodol@dds.nl>,
Philip Edelbrock <phil@netroedge.com>,
Mark Studebaker <mdsxyz123@yahoo.com>
Module Parameters
-----------------
* force_addr: int
Forcibly enable the ICH at the given address. EXTREMELY DANGEROUS!
Description
-----------
The ICH (properly known as the 82801AA), ICH0 (82801AB), ICH2 (82801BA),
ICH3 (82801CA/CAM) and later devices are Intel chips that are a part of
Intel's '810' chipset for Celeron-based PCs, '810E' chipset for
Pentium-based PCs, '815E' chipset, and others.
The ICH chips contain at least SEVEN separate PCI functions in TWO logical
PCI devices. An output of lspci will show something similar to the
following:
00:1e.0 PCI bridge: Intel Corporation: Unknown device 2418 (rev 01)
00:1f.0 ISA bridge: Intel Corporation: Unknown device 2410 (rev 01)
00:1f.1 IDE interface: Intel Corporation: Unknown device 2411 (rev 01)
00:1f.2 USB Controller: Intel Corporation: Unknown device 2412 (rev 01)
00:1f.3 Unknown class [0c05]: Intel Corporation: Unknown device 2413 (rev 01)
The SMBus controller is function 3 in device 1f. Class 0c05 is SMBus Serial
Controller.
If you do NOT see the 24x3 device at function 3, and you can't figure out
any way in the BIOS to enable it,
The ICH chips are quite similar to Intel's PIIX4 chip, at least in the
SMBus controller.
See the file i2c-piix4 for some additional information.
Process Call Support
--------------------
Not supported.
I2C Block Read Support
----------------------
Not supported at the moment.
SMBus 2.0 Support
-----------------
The 82801DB (ICH4) and later chips support several SMBus 2.0 features.
**********************
The lm_sensors project gratefully acknowledges the support of Texas
Instruments in the initial development of this driver.
The lm_sensors project gratefully acknowledges the support of Intel in the
development of SMBus 2.0 / ICH4 features of this driver.

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

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

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

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

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

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

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

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

@@ -0,0 +1,72 @@
Kernel driver i2c-piix4
Supported adapters:
* Intel 82371AB PIIX4 and PIIX4E
* Intel 82443MX (440MX)
Datasheet: Publicly available at the Intel website
* ServerWorks OSB4, CSB5 and CSB6 southbridges
Datasheet: Only available via NDA from ServerWorks
* Standard Microsystems (SMSC) SLC90E66 (Victory66) southbridge
Datasheet: Publicly available at the SMSC website http://www.smsc.com
Authors:
Frodo Looijaard <frodol@dds.nl>
Philip Edelbrock <phil@netroedge.com>
Module Parameters
-----------------
* force: int
Forcibly enable the PIIX4. DANGEROUS!
* force_addr: int
Forcibly enable the PIIX4 at the given address. EXTREMELY DANGEROUS!
* fix_hstcfg: int
Fix config register. Needed on some boards (Force CPCI735).
Description
-----------
The PIIX4 (properly known as the 82371AB) is an Intel chip with a lot of
functionality. Among other things, it implements the PCI bus. One of its
minor functions is implementing a System Management Bus. This is a true
SMBus - you can not access it on I2C levels. The good news is that it
natively understands SMBus commands and you do not have to worry about
timing problems. The bad news is that non-SMBus devices connected to it can
confuse it mightily. Yes, this is known to happen...
Do 'lspci -v' and see whether it contains an entry like this:
0000:00:02.3 Bridge: Intel Corp. 82371AB/EB/MB PIIX4 ACPI (rev 02)
Flags: medium devsel, IRQ 9
Bus and device numbers may differ, but the function number must be
identical (like many PCI devices, the PIIX4 incorporates a number of
different 'functions', which can be considered as separate devices). If you
find such an entry, you have a PIIX4 SMBus controller.
On some computers (most notably, some Dells), the SMBus is disabled by
default. If you use the insmod parameter 'force=1', the kernel module will
try to enable it. THIS IS VERY DANGEROUS! If the BIOS did not set up a
correct address for this module, you could get in big trouble (read:
crashes, data corruption, etc.). Try this only as a last resort (try BIOS
updates first, for example), and backup first! An even more dangerous
option is 'force_addr=<IOPORT>'. This will not only enable the PIIX4 like
'force' foes, but it will also set a new base I/O port address. The SMBus
parts of the PIIX4 needs a range of 8 of these addresses to function
correctly. If these addresses are already reserved by some other device,
you will get into big trouble! DON'T USE THIS IF YOU ARE NOT VERY SURE
ABOUT WHAT YOU ARE DOING!
The PIIX4E is just an new version of the PIIX4; it is supported as well.
The PIIX/PIIX3 does not implement an SMBus or I2C bus, so you can't use
this driver on those mainboards.
The ServerWorks Southbridges, the Intel 440MX, and the Victory766 are
identical to the PIIX4 in I2C/SMBus support.
A few OSB4 southbridges are known to be misconfigured by the BIOS. In this
case, you have you use the fix_hstcfg module parameter. Do not use it
unless you know you have to, because in some cases it also breaks
configuration on southbridges that don't need it.

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

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.

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

@@ -0,0 +1,47 @@
Kernel driver i2c-viapro
Supported adapters:
* VIA Technologies, Inc. VT82C596A/B
Datasheet: Sometimes available at the VIA website
* VIA Technologies, Inc. VT82C686A/B
Datasheet: Sometimes available at the VIA website
* VIA Technologies, Inc. VT8231, VT8233, VT8233A, VT8235, VT8237
Datasheet: available on request from Via
Authors:
Frodo Looijaard <frodol@dds.nl>,
Philip Edelbrock <phil@netroedge.com>,
Ky<4B>sti M<>lkki <kmalkki@cc.hut.fi>,
Mark D. Studebaker <mdsxyz123@yahoo.com>
Module Parameters
-----------------
* force: int
Forcibly enable the SMBus controller. DANGEROUS!
* force_addr: int
Forcibly enable the SMBus at the given address. EXTREMELY DANGEROUS!
Description
-----------
i2c-viapro is a true SMBus host driver for motherboards with one of the
supported VIA southbridges.
Your lspci -n listing must show one of these :
device 1106:3050 (VT82C596 function 3)
device 1106:3051 (VT82C596 function 3)
device 1106:3057 (VT82C686 function 4)
device 1106:3074 (VT8233)
device 1106:3147 (VT8233A)
device 1106:8235 (VT8231)
devide 1106:3177 (VT8235)
devide 1106:3227 (VT8237)
If none of these show up, you should look in the BIOS for settings like
enable ACPI / SMBus or even USB.

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.

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

@@ -0,0 +1,14 @@
Kernel driver scx200_acb
Author: Christer Weinigel <wingel@nano-system.com>
Module Parameters
-----------------
* base: int
Base addresses for the ACCESS.bus controllers
Description
-----------
Enable the use of the ACCESS.bus controllers of a SCx200 processor.

146
Documentation/i2c/chips/smsc47b397.txt Normal file
View File

@@ -0,0 +1,146 @@
November 23, 2004
The following specification describes the SMSC LPC47B397-NC sensor chip
(for which there is no public datasheet available). This document was
provided by Craig Kelly (In-Store Broadcast Network) and edited/corrected
by Mark M. Hoffman <mhoffman@lightlink.com>.
* * * * *
Methods for detecting the HP SIO and reading the thermal data on a dc7100.
The thermal information on the dc7100 is contained in the SIO Hardware Monitor
(HWM). The information is accessed through an index/data pair. The index/data
pair is located at the HWM Base Address + 0 and the HWM Base Address + 1. The
HWM Base address can be obtained from Logical Device 8, registers 0x60 (MSB)
and 0x61 (LSB). Currently we are using 0x480 for the HWM Base Address and
0x480 and 0x481 for the index/data pair.
Reading temperature information.
The temperature information is located in the following registers:
Temp1 0x25 (Currently, this reflects the CPU temp on all systems).
Temp2 0x26
Temp3 0x27
Temp4 0x80
Programming Example
The following is an example of how to read the HWM temperature registers:
MOV DX,480H
MOV AX,25H
OUT DX,AL
MOV DX,481H
IN AL,DX
AL contains the data in hex, the temperature in Celsius is the decimal
equivalent.
Ex: If AL contains 0x2A, the temperature is 42 degrees C.
Reading tach information.
The fan speed information is located in the following registers:
LSB MSB
Tach1 0x28 0x29 (Currently, this reflects the CPU
fan speed on all systems).
Tach2 0x2A 0x2B
Tach3 0x2C 0x2D
Tach4 0x2E 0x2F
Important!!!
Reading the tach LSB locks the tach MSB.
The LSB Must be read first.
How to convert the tach reading to RPM.
The tach reading (TCount) is given by: (Tach MSB * 256) + (Tach LSB)
The SIO counts the number of 90kHz (11.111us) pulses per revolution.
RPM = 60/(TCount * 11.111us)
Example:
Reg 0x28 = 0x9B
Reg 0x29 = 0x08
TCount = 0x89B = 2203
RPM = 60 / (2203 * 11.11111 E-6) = 2451 RPM
Obtaining the SIO version.
CONFIGURATION SEQUENCE
To program the configuration registers, the following sequence must be followed:
1. Enter Configuration Mode
2. Configure the Configuration Registers
3. Exit Configuration Mode.
Enter Configuration Mode
To place the chip into the Configuration State The config key (0x55) is written
to the CONFIG PORT (0x2E).
Configuration Mode
In configuration mode, the INDEX PORT is located at the CONFIG PORT address and
the DATA PORT is at INDEX PORT address + 1.
The desired configuration registers are accessed in two steps:
a. Write the index of the Logical Device Number Configuration Register
(i.e., 0x07) to the INDEX PORT and then write the number of the
desired logical device to the DATA PORT.
b. Write the address of the desired configuration register within the
logical device to the INDEX PORT and then write or read the config-
uration register through the DATA PORT.
Note: If accessing the Global Configuration Registers, step (a) is not required.
Exit Configuration Mode
To exit the Configuration State the write 0xAA to the CONFIG PORT (0x2E).
The chip returns to the RUN State. (This is important).
Programming Example
The following is an example of how to read the SIO Device ID located at 0x20
; ENTER CONFIGURATION MODE
MOV DX,02EH
MOV AX,055H
OUT DX,AL
; GLOBAL CONFIGURATION REGISTER
MOV DX,02EH
MOV AL,20H
OUT DX,AL
; READ THE DATA
MOV DX,02FH
IN AL,DX
; EXIT CONFIGURATION MODE
MOV DX,02EH
MOV AX,0AAH
OUT DX,AL
The registers of interest for identifying the SIO on the dc7100 are Device ID
(0x20) and Device Rev (0x21).
The Device ID will read 0X6F
The Device Rev currently reads 0x01
Obtaining the HWM Base Address.
The following is an example of how to read the HWM Base Address located in
Logical Device 8.
; ENTER CONFIGURATION MODE
MOV DX,02EH
MOV AX,055H
OUT DX,AL
; CONFIGURE REGISTER CRE0,
; LOGICAL DEVICE 8
MOV DX,02EH
MOV AL,07H
OUT DX,AL ;Point to LD# Config Reg
MOV DX,02FH
MOV AL, 08H
OUT DX,AL;Point to Logical Device 8
;
MOV DX,02EH
MOV AL,60H
OUT DX,AL ; Point to HWM Base Addr MSB
MOV DX,02FH
IN AL,DX ; Get MSB of HWM Base Addr
; EXIT CONFIGURATION MODE
MOV DX,02EH
MOV AX,0AAH
OUT DX,AL

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

@@ -0,0 +1,146 @@
Usually, i2c devices are controlled by a kernel driver. But it is also
possible to access all devices on an adapter from userspace, through
the /dev interface. You need to load module i2c-dev for this.
Each registered i2c adapter gets a number, counting from 0. You can
examine /sys/class/i2c-dev/ to see what number corresponds to which adapter.
I2C device files are character device files with major device number 89
and a minor device number corresponding to the number assigned as
explained above. They should be called "i2c-%d" (i2c-0, i2c-1, ...,
i2c-10, ...). All 256 minor device numbers are reserved for i2c.
C example
=========
So let's say you want to access an i2c adapter from a C program. The
first thing to do is `#include <linux/i2c.h>" and "#include <linux/i2c-dev.h>.
Yes, I know, you should never include kernel header files, but until glibc
knows about i2c, there is not much choice.
Now, you have to decide which adapter you want to access. You should
inspect /sys/class/i2c-dev/ to decide this. Adapter numbers are assigned
somewhat dynamically, so you can not even assume /dev/i2c-0 is the
first adapter.
Next thing, open the device file, as follows:
int file;
int adapter_nr = 2; /* probably dynamically determined */
char filename[20];
sprintf(filename,"/dev/i2c-%d",adapter_nr);
if ((file = open(filename,O_RDWR)) < 0) {
/* ERROR HANDLING; you can check errno to see what went wrong */
exit(1);
}
When you have opened the device, you must specify with what device
address you want to communicate:
int addr = 0x40; /* The I2C address */
if (ioctl(file,I2C_SLAVE,addr) < 0) {
/* ERROR HANDLING; you can check errno to see what went wrong */
exit(1);
}
Well, you are all set up now. You can now use SMBus commands or plain
I2C to communicate with your device. SMBus commands are preferred if
the device supports them. Both are illustrated below.
__u8 register = 0x10; /* Device register to access */
__s32 res;
char buf[10];
/* Using SMBus commands */
res = i2c_smbus_read_word_data(file,register);
if (res < 0) {
/* ERROR HANDLING: i2c transaction failed */
} else {
/* res contains the read word */
}
/* Using I2C Write, equivalent of
i2c_smbus_write_word_data(file,register,0x6543) */
buf[0] = register;
buf[1] = 0x43;
buf[2] = 0x65;
if ( write(file,buf,3) != 3) {
/* ERROR HANDLING: i2c transaction failed */
}
/* Using I2C Read, equivalent of i2c_smbus_read_byte(file) */
if (read(file,buf,1) != 1) {
/* ERROR HANDLING: i2c transaction failed */
} else {
/* buf[0] contains the read byte */
}
IMPORTANT: because of the use of inline functions, you *have* to use
'-O' or some variation when you compile your program!
Full interface description
==========================
The following IOCTLs are defined and fully supported
(see also i2c-dev.h and i2c.h):
ioctl(file,I2C_SLAVE,long addr)
Change slave address. The address is passed in the 7 lower bits of the
argument (except for 10 bit addresses, passed in the 10 lower bits in this
case).
ioctl(file,I2C_TENBIT,long select)
Selects ten bit addresses if select not equals 0, selects normal 7 bit
addresses if select equals 0. Default 0.
ioctl(file,I2C_PEC,long select)
Selects SMBus PEC (packet error checking) generation and verification
if select not equals 0, disables if select equals 0. Default 0.
Used only for SMBus transactions.
ioctl(file,I2C_FUNCS,unsigned long *funcs)
Gets the adapter functionality and puts it in *funcs.
ioctl(file,I2C_RDWR,struct i2c_ioctl_rdwr_data *msgset)
Do combined read/write transaction without stop in between.
The argument is a pointer to a struct i2c_ioctl_rdwr_data {
struct i2c_msg *msgs; /* ptr to array of simple messages */
int nmsgs; /* number of messages to exchange */
}
The msgs[] themselves contain further pointers into data buffers.
The function will write or read data to or from that buffers depending
on whether the I2C_M_RD flag is set in a particular message or not.
The slave address and whether to use ten bit address mode has to be
set in each message, overriding the values set with the above ioctl's.
Other values are NOT supported at this moment, except for I2C_SMBUS,
which you should never directly call; instead, use the access functions
below.
You can do plain i2c transactions by using read(2) and write(2) calls.
You do not need to pass the address byte; instead, set it through
ioctl I2C_SLAVE before you try to access the device.
You can do SMBus level transactions (see documentation file smbus-protocol
for details) through the following functions:
__s32 i2c_smbus_write_quick(int file, __u8 value);
__s32 i2c_smbus_read_byte(int file);
__s32 i2c_smbus_write_byte(int file, __u8 value);
__s32 i2c_smbus_read_byte_data(int file, __u8 command);
__s32 i2c_smbus_write_byte_data(int file, __u8 command, __u8 value);
__s32 i2c_smbus_read_word_data(int file, __u8 command);
__s32 i2c_smbus_write_word_data(int file, __u8 command, __u16 value);
__s32 i2c_smbus_process_call(int file, __u8 command, __u16 value);
__s32 i2c_smbus_read_block_data(int file, __u8 command, __u8 *values);
__s32 i2c_smbus_write_block_data(int file, __u8 command, __u8 length,
__u8 *values);
All these transactions return -1 on failure; you can read errno to see
what happened. The 'write' transactions return 0 on success; the
'read' transactions return the read value, except for read_block, which
returns the number of values read. The block buffers need not be longer
than 32 bytes.
The above functions are all macros, that resolve to calls to the
i2c_smbus_access function, that on its turn calls a specific ioctl
with the data in a specific format. Read the source code if you
want to know what happens behind the screens.

135
Documentation/i2c/functionality Normal file
View File

@@ -0,0 +1,135 @@
INTRODUCTION
------------
Because not every I2C or SMBus adapter implements everything in the
I2C specifications, a client can not trust that everything it needs
is implemented when it is given the option to attach to an adapter:
the client needs some way to check whether an adapter has the needed
functionality.
FUNCTIONALITY CONSTANTS
-----------------------
For the most up-to-date list of functionality constants, please check
<linux/i2c.h>!
I2C_FUNC_I2C Plain i2c-level commands (Pure SMBus
adapters typically can not do these)
I2C_FUNC_10BIT_ADDR Handles the 10-bit address extensions
I2C_FUNC_PROTOCOL_MANGLING Knows about the I2C_M_REV_DIR_ADDR,
I2C_M_REV_DIR_ADDR and I2C_M_REV_DIR_NOSTART
flags (which modify the i2c protocol!)
I2C_FUNC_SMBUS_QUICK Handles the SMBus write_quick command
I2C_FUNC_SMBUS_READ_BYTE Handles the SMBus read_byte command
I2C_FUNC_SMBUS_WRITE_BYTE Handles the SMBus write_byte command
I2C_FUNC_SMBUS_READ_BYTE_DATA Handles the SMBus read_byte_data command
I2C_FUNC_SMBUS_WRITE_BYTE_DATA Handles the SMBus write_byte_data command
I2C_FUNC_SMBUS_READ_WORD_DATA Handles the SMBus read_word_data command
I2C_FUNC_SMBUS_WRITE_WORD_DATA Handles the SMBus write_byte_data command
I2C_FUNC_SMBUS_PROC_CALL Handles the SMBus process_call command
I2C_FUNC_SMBUS_READ_BLOCK_DATA Handles the SMBus read_block_data command
I2C_FUNC_SMBUS_WRITE_BLOCK_DATA Handles the SMBus write_block_data command
I2C_FUNC_SMBUS_READ_I2C_BLOCK Handles the SMBus read_i2c_block_data command
I2C_FUNC_SMBUS_WRITE_I2C_BLOCK Handles the SMBus write_i2c_block_data command
A few combinations of the above flags are also defined for your convenience:
I2C_FUNC_SMBUS_BYTE Handles the SMBus read_byte
and write_byte commands
I2C_FUNC_SMBUS_BYTE_DATA Handles the SMBus read_byte_data
and write_byte_data commands
I2C_FUNC_SMBUS_WORD_DATA Handles the SMBus read_word_data
and write_word_data commands
I2C_FUNC_SMBUS_BLOCK_DATA Handles the SMBus read_block_data
and write_block_data commands
I2C_FUNC_SMBUS_I2C_BLOCK Handles the SMBus read_i2c_block_data
and write_i2c_block_data commands
I2C_FUNC_SMBUS_EMUL Handles all SMBus commands than can be
emulated by a real I2C adapter (using
the transparent emulation layer)
ALGORITHM/ADAPTER IMPLEMENTATION
--------------------------------
When you write a new algorithm driver, you will have to implement a
function callback `functionality', that gets an i2c_adapter structure
pointer as its only parameter:
struct i2c_algorithm {
/* Many other things of course; check <linux/i2c.h>! */
u32 (*functionality) (struct i2c_adapter *);
}
A typically implementation is given below, from i2c-algo-bit.c:
static u32 bit_func(struct i2c_adapter *adap)
{
return I2C_FUNC_SMBUS_EMUL | I2C_FUNC_10BIT_ADDR |
I2C_FUNC_PROTOCOL_MANGLING;
}
CLIENT CHECKING
---------------
Before a client tries to attach to an adapter, or even do tests to check
whether one of the devices it supports is present on an adapter, it should
check whether the needed functionality is present. There are two functions
defined which should be used instead of calling the functionality hook
in the algorithm structure directly:
/* Return the functionality mask */
extern u32 i2c_get_functionality (struct i2c_adapter *adap);
/* Return 1 if adapter supports everything we need, 0 if not. */
extern int i2c_check_functionality (struct i2c_adapter *adap, u32 func);
This is a typical way to use these functions (from the writing-clients
document):
int foo_detect_client(struct i2c_adapter *adapter, int address,
unsigned short flags, int kind)
{
/* Define needed variables */
/* As the very first action, we check whether the adapter has the
needed functionality: we need the SMBus read_word_data,
write_word_data and write_byte functions in this example. */
if (!i2c_check_functionality(adapter,I2C_FUNC_SMBUS_WORD_DATA |
I2C_FUNC_SMBUS_WRITE_BYTE))
goto ERROR0;
/* Now we can do the real detection */
ERROR0:
/* Return an error */
}
CHECKING THROUGH /DEV
---------------------
If you try to access an adapter from a userspace program, you will have
to use the /dev interface. You will still have to check whether the
functionality you need is supported, of course. This is done using
the I2C_FUNCS ioctl. An example, adapted from the lm_sensors i2c_detect
program, is below:
int file;
if (file = open("/dev/i2c-0",O_RDWR) < 0) {
/* Some kind of error handling */
exit(1);
}
if (ioctl(file,I2C_FUNCS,&funcs) < 0) {
/* Some kind of error handling */
exit(1);
}
if (! (funcs & I2C_FUNC_SMBUS_QUICK)) {
/* Oops, the needed functionality (SMBus write_quick function) is
not available! */
exit(1);
}
/* Now it is safe to use the SMBus write_quick command */

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.

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

@@ -0,0 +1,38 @@
MODULE: i2c-stub
DESCRIPTION:
This module is a very simple fake I2C/SMBus driver. It implements four
types of SMBus commands: write quick, (r/w) byte, (r/w) byte data, and
(r/w) word data.
No hardware is needed nor associated with this module. It will accept write
quick commands to all addresses; it will respond to the other commands (also
to all addresses) by reading from or writing to an array in memory. It will
also spam the kernel logs for every command it handles.
A pointer register with auto-increment is implemented for all byte
operations. This allows for continuous byte reads like those supported by
EEPROMs, among others.
The typical use-case is like this:
1. load this module
2. use i2cset (from lm_sensors project) to pre-load some data
3. load the target sensors chip driver module
4. observe its behavior in the kernel log
CAVEATS:
There are independent arrays for byte/data and word/data commands. Depending
on if/how a target driver mixes them, you'll need to be careful.
If your target driver polls some byte or word waiting for it to change, the
stub could lock it up. Use i2cset to unlock it.
If the hardware for your driver has banked registers (e.g. Winbond sensors
chips) this module will not work well - although it could be extended to
support that pretty easily.
If you spam it hard enough, printk can be lossy. This module really wants
something like relayfs.

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

@@ -0,0 +1,133 @@
Revision 4, 2004-03-30
Jean Delvare <khali@linux-fr.org>
Greg KH <greg@kroah.com>
This is a guide on how to convert I2C chip drivers from Linux 2.4 to
Linux 2.6. I have been using existing drivers (lm75, lm78) as examples.
Then I converted a driver myself (lm83) and updated this document.
There are two sets of points below. The first set concerns technical
changes. The second set concerns coding policy. Both are mandatory.
Although reading this guide will help you porting drivers, I suggest
you keep an eye on an already ported driver while porting your own
driver. This will help you a lot understanding what this guide
exactly means. Choose the chip driver that is the more similar to
yours for best results.
Technical changes:
* [Includes] Get rid of "version.h". Replace <linux/i2c-proc.h> with
<linux/i2c-sensor.h>. Includes typically look like that:
#include <linux/module.h>
#include <linux/init.h>
#include <linux/slab.h>
#include <linux/i2c.h>
#include <linux/i2c-sensor.h>
#include <linux/i2c-vid.h> /* if you need VRM support */
#include <asm/io.h> /* if you have I/O operations */
Please respect this inclusion order. Some extra headers may be
required for a given driver (e.g. "lm75.h").
* [Addresses] SENSORS_I2C_END becomes I2C_CLIENT_END, SENSORS_ISA_END
becomes I2C_CLIENT_ISA_END.
* [Client data] Get rid of sysctl_id. Try using standard names for
register values (for example, temp_os becomes temp_max). You're
still relatively free here, but you *have* to follow the standard
names for sysfs files (see the Sysctl section below).
* [Function prototypes] The detect functions loses its flags
parameter. Sysctl (e.g. lm75_temp) and miscellaneous functions
are off the list of prototypes. This usually leaves five
prototypes:
static int lm75_attach_adapter(struct i2c_adapter *adapter);
static int lm75_detect(struct i2c_adapter *adapter, int address,
int kind);
static void lm75_init_client(struct i2c_client *client);
static int lm75_detach_client(struct i2c_client *client);
static void lm75_update_client(struct i2c_client *client);
* [Sysctl] All sysctl stuff is of course gone (defines, ctl_table
and functions). Instead, you have to define show and set functions for
each sysfs file. Only define set for writable values. Take a look at an
existing 2.6 driver for details (lm78 for example). Don't forget
to define the attributes for each file (this is that step that
links callback functions). Use the file names specified in
Documentation/i2c/sysfs-interface for the individual files. Also
convert the units these files read and write to the specified ones.
If you need to add a new type of file, please discuss it on the
sensors mailing list <sensors@stimpy.netroedge.com> by providing a
patch to the Documentation/i2c/sysfs-interface file.
* [Attach] For I2C drivers, the attach function should make sure
that the adapter's class has I2C_CLASS_HWMON, using the
following construct:
if (!(adapter->class & I2C_CLASS_HWMON))
return 0;
ISA-only drivers of course don't need this.
* [Detect] As mentioned earlier, the flags parameter is gone.
The type_name and client_name strings are replaced by a single
name string, which will be filled with a lowercase, short string
(typically the driver name, e.g. "lm75").
In i2c-only drivers, drop the i2c_is_isa_adapter check, it's
useless.
The errorN labels are reduced to the number needed. If that number
is 2 (i2c-only drivers), it is advised that the labels are named
exit and exit_free. For i2c+isa drivers, labels should be named
ERROR0, ERROR1 and ERROR2. Don't forget to properly set err before
jumping to error labels. By the way, labels should be left-aligned.
Use memset to fill the client and data area with 0x00.
Use i2c_set_clientdata to set the client data (as opposed to
a direct access to client->data).
Use strlcpy instead of strcpy to copy the client name.
Replace the sysctl directory registration by calls to
device_create_file. Move the driver initialization before any
sysfs file creation.
Drop client->id.
* [Init] Limits must not be set by the driver (can be done later in
user-space). Chip should not be reset default (although a module
parameter may be used to force is), and initialization should be
limited to the strictly necessary steps.
* [Detach] Get rid of data, remove the call to
i2c_deregister_entry.
* [Update] Don't access client->data directly, use
i2c_get_clientdata(client) instead.
* [Interface] Init function should not print anything. Make sure
there is a MODULE_LICENSE() line, at the bottom of the file
(after MODULE_AUTHOR() and MODULE_DESCRIPTION(), in this order).
Coding policy:
* [Copyright] Use (C), not (c), for copyright.
* [Debug/log] Get rid of #ifdef DEBUG/#endif constructs whenever you
can. Calls to printk/pr_debug for debugging purposes are replaced
by calls to dev_dbg. Here is an example on how to call it (taken
from lm75_detect):
dev_dbg(&client->dev, "Starting lm75 update\n");
Replace other printk calls with the dev_info, dev_err or dev_warn
function, as appropriate.
* [Constants] Constants defines (registers, conversions, initial
values) should be aligned. This greatly improves readability.
Same goes for variables declarations. Alignments are achieved by the
means of tabs, not spaces. Remember that tabs are set to 8 in the
Linux kernel code.
* [Structure definition] The name field should be standardized. All
lowercase and as simple as the driver name itself (e.g. "lm75").
* [Layout] Avoid extra empty lines between comments and what they
comment. Respect the coding style (see Documentation/CodingStyle),
in particular when it comes to placing curly braces.
* [Comments] Make sure that no comment refers to a file that isn't
part of the Linux source tree (typically doc/chips/<chip name>),
and that remaining comments still match the code. Merging comment
lines when possible is encouraged.

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 read from a device, from a designated register that is
specified through the Comm byte.
S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A] P
SMBus Process Call
==================
This command selects a device register (through the Comm byte), sends
16 bits of data to it, and reads 16 bits of data in return.
S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A]
S Addr Rd [A] [DataLow] A [DataHigh] NA P
SMBus Block Read
================
This command reads a block of up to 32 bytes from a device, from a
designated register that is specified through the Comm byte. The amount
of data is specified by the device in the Count byte.
S Addr Wr [A] Comm [A]
S Addr Rd [A] [Count] A [Data] A [Data] A ... A [Data] NA P
SMBus Block Write
=================
The opposite of the Block Read command, this writes up to 32 bytes to
a device, to a designated register that is specified through the
Comm byte. The amount of data is specified in the Count byte.
S Addr Wr [A] Comm [A] Count [A] Data [A] Data [A] ... [A] Data [A] P
SMBus Block Process Call
========================
SMBus Block Process Call was introduced in Revision 2.0 of the specification.
This command selects a device register (through the Comm byte), sends
1 to 31 bytes of data to it, and reads 1 to 31 bytes of data in return.
S Addr Wr [A] Comm [A] Count [A] Data [A] ...
S Addr Rd [A] [Count] A [Data] ... A P
SMBus Host Notify
=================
This command is sent from a SMBus device acting as a master to the
SMBus host acting as a slave.
It is the same form as Write Word, with the command code replaced by the
alerting device's address.
[S] [HostAddr] [Wr] A [DevAddr] A [DataLow] A [DataHigh] A [P]
Packet Error Checking (PEC)
===========================
Packet Error Checking was introduced in Revision 1.1 of the specification.
PEC adds a CRC-8 error-checking byte to all transfers.
Address Resolution Protocol (ARP)
=================================
The Address Resolution Protocol was introduced in Revision 2.0 of
the specification. It is a higher-layer protocol which uses the
messages above.
ARP adds device enumeration and dynamic address assignment to
the protocol. All ARP communications use slave address 0x61 and
require PEC checksums.
I2C Block Transactions
======================
The following I2C block transactions are supported by the
SMBus layer and are described here for completeness.
I2C block transactions do not limit the number of bytes transferred
but the SMBus layer places a limit of 32 bytes.
I2C Block Read
==============
This command reads a block of bytes from a device, from a
designated register that is specified through the Comm byte.
S Addr Wr [A] Comm [A]
S Addr Rd [A] [Data] A [Data] A ... A [Data] NA P
I2C Block Read (2 Comm bytes)
=============================
This command reads a block of bytes from a device, from a
designated register that is specified through the two Comm bytes.
S Addr Wr [A] Comm1 [A] Comm2 [A]
S Addr Rd [A] [Data] A [Data] A ... A [Data] NA P
I2C Block Write
===============
The opposite of the Block Read command, this writes bytes to
a device, to a designated register that is specified through the
Comm byte. Note that command lengths of 0, 2, or more bytes are
supported as they are indistinguishable from data.
S Addr Wr [A] Comm [A] Data [A] Data [A] ... [A] Data [A] P

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)

274
Documentation/i2c/sysfs-interface Normal file
View File

@@ -0,0 +1,274 @@
Naming and data format standards for sysfs files
------------------------------------------------
The libsensors library offers an interface to the raw sensors data
through the sysfs interface. See libsensors documentation and source for
more further information. As of writing this document, libsensors
(from lm_sensors 2.8.3) is heavily chip-dependant. Adding or updating
support for any given chip requires modifying the library's code.
This is because libsensors was written for the procfs interface
older kernel modules were using, which wasn't standardized enough.
Recent versions of libsensors (from lm_sensors 2.8.2 and later) have
support for the sysfs interface, though.
The new sysfs interface was designed to be as chip-independant as
possible.
Note that motherboards vary widely in the connections to sensor chips.
There is no standard that ensures, for example, that the second
temperature sensor is connected to the CPU, or that the second fan is on
the CPU. Also, some values reported by the chips need some computation
before they make full sense. For example, most chips can only measure
voltages between 0 and +4V. Other voltages are scaled back into that
range using external resistors. Since the values of these resistors
can change from motherboard to motherboard, the conversions cannot be
hard coded into the driver and have to be done in user space.
For this reason, even if we aim at a chip-independant libsensors, it will
still require a configuration file (e.g. /etc/sensors.conf) for proper
values conversion, labeling of inputs and hiding of unused inputs.
An alternative method that some programs use is to access the sysfs
files directly. This document briefly describes the standards that the
drivers follow, so that an application program can scan for entries and
access this data in a simple and consistent way. That said, such programs
will have to implement conversion, labeling and hiding of inputs. For
this reason, it is still not recommended to bypass the library.
If you are developing a userspace application please send us feedback on
this standard.
Note that this standard isn't completely established yet, so it is subject
to changes, even important ones. One more reason to use the library instead
of accessing sysfs files directly.
Each chip gets its own directory in the sysfs /sys/devices tree. To
find all sensor chips, it is easier to follow the symlinks from
/sys/i2c/devices/
All sysfs values are fixed point numbers. To get the true value of some
of the values, you should divide by the specified value.
There is only one value per file, unlike the older /proc specification.
The common scheme for files naming is: <type><number>_<item>. Usual
types for sensor chips are "in" (voltage), "temp" (temperature) and
"fan" (fan). Usual items are "input" (measured value), "max" (high
threshold, "min" (low threshold). Numbering usually starts from 1,
except for voltages which start from 0 (because most data sheets use
this). A number is always used for elements that can be present more
than once, even if there is a single element of the given type on the
specific chip. Other files do not refer to a specific element, so
they have a simple name, and no number.
Alarms are direct indications read from the chips. The drivers do NOT
make comparisons of readings to thresholds. This allows violations
between readings to be caught and alarmed. The exact definition of an
alarm (for example, whether a threshold must be met or must be exceeded
to cause an alarm) is chip-dependent.
-------------------------------------------------------------------------
************
* Voltages *
************
in[0-8]_min Voltage min value.
Unit: millivolt
Read/Write
in[0-8]_max Voltage max value.
Unit: millivolt
Read/Write
in[0-8]_input Voltage input value.
Unit: millivolt
Read only
Actual voltage depends on the scaling resistors on the
motherboard, as recommended in the chip datasheet.
This varies by chip and by motherboard.
Because of this variation, values are generally NOT scaled
by the chip driver, and must be done by the application.
However, some drivers (notably lm87 and via686a)
do scale, with various degrees of success.
These drivers will output the actual voltage.
Typical usage:
in0_* CPU #1 voltage (not scaled)
in1_* CPU #2 voltage (not scaled)
in2_* 3.3V nominal (not scaled)
in3_* 5.0V nominal (scaled)
in4_* 12.0V nominal (scaled)
in5_* -12.0V nominal (scaled)
in6_* -5.0V nominal (scaled)
in7_* varies
in8_* varies
cpu[0-1]_vid CPU core reference voltage.
Unit: millivolt
Read only.
Not always correct.
vrm Voltage Regulator Module version number.
Read only.
Two digit number, first is major version, second is
minor version.
Affects the way the driver calculates the CPU core reference
voltage from the vid pins.
********
* Fans *
********
fan[1-3]_min Fan minimum value
Unit: revolution/min (RPM)
Read/Write.
fan[1-3]_input Fan input value.
Unit: revolution/min (RPM)
Read only.
fan[1-3]_div Fan divisor.
Integer value in powers of two (1, 2, 4, 8, 16, 32, 64, 128).
Some chips only support values 1, 2, 4 and 8.
Note that this is actually an internal clock divisor, which
affects the measurable speed range, not the read value.
*******
* PWM *
*******
pwm[1-3] Pulse width modulation fan control.
Integer value in the range 0 to 255
Read/Write
255 is max or 100%.
pwm[1-3]_enable
Switch PWM on and off.
Not always present even if fan*_pwm is.
0 to turn off
1 to turn on in manual mode
2 to turn on in automatic mode
Read/Write
pwm[1-*]_auto_channels_temp
Select which temperature channels affect this PWM output in
auto mode. Bitfield, 1 is temp1, 2 is temp2, 4 is temp3 etc...
Which values are possible depend on the chip used.
pwm[1-*]_auto_point[1-*]_pwm
pwm[1-*]_auto_point[1-*]_temp
pwm[1-*]_auto_point[1-*]_temp_hyst
Define the PWM vs temperature curve. Number of trip points is
chip-dependent. Use this for chips which associate trip points
to PWM output channels.
OR
temp[1-*]_auto_point[1-*]_pwm
temp[1-*]_auto_point[1-*]_temp
temp[1-*]_auto_point[1-*]_temp_hyst
Define the PWM vs temperature curve. Number of trip points is
chip-dependent. Use this for chips which associate trip points
to temperature channels.
****************
* Temperatures *
****************
temp[1-3]_type Sensor type selection.
Integers 1, 2, 3 or thermistor Beta value (3435)
Read/Write.
1: PII/Celeron Diode
2: 3904 transistor
3: thermal diode
Not all types are supported by all chips
temp[1-4]_max Temperature max value.
Unit: millidegree Celcius
Read/Write value.
temp[1-3]_min Temperature min value.
Unit: millidegree Celcius
Read/Write value.
temp[1-3]_max_hyst
Temperature hysteresis value for max limit.
Unit: millidegree Celcius
Must be reported as an absolute temperature, NOT a delta
from the max value.
Read/Write value.
temp[1-4]_input Temperature input value.
Unit: millidegree Celcius
Read only value.
temp[1-4]_crit Temperature critical value, typically greater than
corresponding temp_max values.
Unit: millidegree Celcius
Read/Write value.
temp[1-2]_crit_hyst
Temperature hysteresis value for critical limit.
Unit: millidegree Celcius
Must be reported as an absolute temperature, NOT a delta
from the critical value.
Read/Write value.
If there are multiple temperature sensors, temp1_* is
generally the sensor inside the chip itself,
reported as "motherboard temperature". temp2_* to
temp4_* are generally sensors external to the chip
itself, for example the thermal diode inside the CPU or
a thermistor nearby.
************
* Currents *
************
Note that no known chip provides current measurements as of writing,
so this part is theoretical, so to say.
curr[1-n]_max Current max value
Unit: milliampere
Read/Write.
curr[1-n]_min Current min value.
Unit: milliampere
Read/Write.
curr[1-n]_input Current input value
Unit: milliampere
Read only.
*********
* Other *
*********
alarms Alarm bitmask.
Read only.
Integer representation of one to four bytes.
A '1' bit means an alarm.
Chips should be programmed for 'comparator' mode so that
the alarm will 'come back' after you read the register
if it is still valid.
Generally a direct representation of a chip's internal
alarm registers; there is no standard for the position
of individual bits.
Bits are defined in kernel/include/sensors.h.
beep_enable Beep/interrupt enable
0 to disable.
1 to enable.
Read/Write
beep_mask Bitmask for beep.
Same format as 'alarms' with the same bit locations.
Read/Write
eeprom Raw EEPROM data in binary form.
Read only.

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.

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

@@ -0,0 +1,816 @@
This is a small guide for those who want to write kernel drivers for I2C
or SMBus devices.
To set up a driver, you need to do several things. Some are optional, and
some things can be done slightly or completely different. Use this as a
guide, not as a rule book!
General remarks
===============
Try to keep the kernel namespace as clean as possible. The best way to
do this is to use a unique prefix for all global symbols. This is
especially important for exported symbols, but it is a good idea to do
it for non-exported symbols too. We will use the prefix `foo_' in this
tutorial, and `FOO_' for preprocessor variables.
The driver structure
====================
Usually, you will implement a single driver structure, and instantiate
all clients from it. Remember, a driver structure contains general access
routines, a client structure specific information like the actual I2C
address.
static struct i2c_driver foo_driver = {
.owner = THIS_MODULE,
.name = "Foo version 2.3 driver",
.id = I2C_DRIVERID_FOO, /* from i2c-id.h, optional */
.flags = I2C_DF_NOTIFY,
.attach_adapter = &foo_attach_adapter,
.detach_client = &foo_detach_client,
.command = &foo_command /* may be NULL */
}
The name can be chosen freely, and may be upto 40 characters long. Please
use something descriptive here.
If used, the id should be a unique ID. The range 0xf000 to 0xffff is
reserved for local use, and you can use one of those until you start
distributing the driver, at which time you should contact the i2c authors
to get your own ID(s). Note that most of the time you don't need an ID
at all so you can just omit it.
Don't worry about the flags field; just put I2C_DF_NOTIFY into it. This
means that your driver will be notified when new adapters are found.
This is almost always what you want.
All other fields are for call-back functions which will be explained
below.
There use to be two additional fields in this structure, inc_use et dec_use,
for module usage count, but these fields were obsoleted and removed.
Extra client data
=================
The client structure has a special `data' field that can point to any
structure at all. You can use this to keep client-specific data. You
do not always need this, but especially for `sensors' drivers, it can
be very useful.
An example structure is below.
struct foo_data {
struct semaphore lock; /* For ISA access in `sensors' drivers. */
int sysctl_id; /* To keep the /proc directory entry for
`sensors' drivers. */
enum chips type; /* To keep the chips type for `sensors' drivers. */
/* Because the i2c bus is slow, it is often useful to cache the read
information of a chip for some time (for example, 1 or 2 seconds).
It depends of course on the device whether this is really worthwhile
or even sensible. */
struct semaphore update_lock; /* When we are reading lots of information,
another process should not update the
below information */
char valid; /* != 0 if the following fields are valid. */
unsigned long last_updated; /* In jiffies */
/* Add the read information here too */
};
Accessing the client
====================
Let's say we have a valid client structure. At some time, we will need
to gather information from the client, or write new information to the
client. How we will export this information to user-space is less
important at this moment (perhaps we do not need to do this at all for
some obscure clients). But we need generic reading and writing routines.
I have found it useful to define foo_read and foo_write function for this.
For some cases, it will be easier to call the i2c functions directly,
but many chips have some kind of register-value idea that can easily
be encapsulated. Also, some chips have both ISA and I2C interfaces, and
it useful to abstract from this (only for `sensors' drivers).
The below functions are simple examples, and should not be copied
literally.
int foo_read_value(struct i2c_client *client, u8 reg)
{
if (reg < 0x10) /* byte-sized register */
return i2c_smbus_read_byte_data(client,reg);
else /* word-sized register */
return i2c_smbus_read_word_data(client,reg);
}
int foo_write_value(struct i2c_client *client, u8 reg, u16 value)
{
if (reg == 0x10) /* Impossible to write - driver error! */ {
return -1;
else if (reg < 0x10) /* byte-sized register */
return i2c_smbus_write_byte_data(client,reg,value);
else /* word-sized register */
return i2c_smbus_write_word_data(client,reg,value);
}
For sensors code, you may have to cope with ISA registers too. Something
like the below often works. Note the locking!
int foo_read_value(struct i2c_client *client, u8 reg)
{
int res;
if (i2c_is_isa_client(client)) {
down(&(((struct foo_data *) (client->data)) -> lock));
outb_p(reg,client->addr + FOO_ADDR_REG_OFFSET);
res = inb_p(client->addr + FOO_DATA_REG_OFFSET);
up(&(((struct foo_data *) (client->data)) -> lock));
return res;
} else
return i2c_smbus_read_byte_data(client,reg);
}
Writing is done the same way.
Probing and attaching
=====================
Most i2c devices can be present on several i2c addresses; for some this
is determined in hardware (by soldering some chip pins to Vcc or Ground),
for others this can be changed in software (by writing to specific client
registers). Some devices are usually on a specific address, but not always;
and some are even more tricky. So you will probably need to scan several
i2c addresses for your clients, and do some sort of detection to see
whether it is actually a device supported by your driver.
To give the user a maximum of possibilities, some default module parameters
are defined to help determine what addresses are scanned. Several macros
are defined in i2c.h to help you support them, as well as a generic
detection algorithm.
You do not have to use this parameter interface; but don't try to use
function i2c_probe() (or i2c_detect()) if you don't.
NOTE: If you want to write a `sensors' driver, the interface is slightly
different! See below.
Probing classes (i2c)
---------------------
All parameters are given as lists of unsigned 16-bit integers. Lists are
terminated by I2C_CLIENT_END.
The following lists are used internally:
normal_i2c: filled in by the module writer.
A list of I2C addresses which should normally be examined.
normal_i2c_range: filled in by the module writer.
A list of pairs of I2C addresses, each pair being an inclusive range of
addresses which should normally be examined.
probe: insmod parameter.
A list of pairs. The first value is a bus number (-1 for any I2C bus),
the second is the address. These addresses are also probed, as if they
were in the 'normal' list.
probe_range: insmod parameter.
A list of triples. The first value is a bus number (-1 for any I2C bus),
the second and third are addresses. These form an inclusive range of
addresses that are also probed, as if they were in the 'normal' list.
ignore: insmod parameter.
A list of pairs. The first value is a bus number (-1 for any I2C bus),
the second is the I2C address. These addresses are never probed.
This parameter overrules 'normal' and 'probe', but not the 'force' lists.
ignore_range: insmod parameter.
A list of triples. The first value is a bus number (-1 for any I2C bus),
the second and third are addresses. These form an inclusive range of
I2C addresses that are never probed.
This parameter overrules 'normal' and 'probe', but not the 'force' lists.
force: insmod parameter.
A list of pairs. The first value is a bus number (-1 for any I2C bus),
the second is the I2C address. A device is blindly assumed to be on
the given address, no probing is done.
Fortunately, as a module writer, you just have to define the `normal'
and/or `normal_range' parameters. The complete declaration could look
like this:
/* Scan 0x20 to 0x2f, 0x37, and 0x40 to 0x4f */
static unsigned short normal_i2c[] = { 0x37,I2C_CLIENT_END };
static unsigned short normal_i2c_range[] = { 0x20, 0x2f, 0x40, 0x4f,
I2C_CLIENT_END };
/* Magic definition of all other variables and things */
I2C_CLIENT_INSMOD;
Note that you *have* to call the two defined variables `normal_i2c' and
`normal_i2c_range', without any prefix!
Probing classes (sensors)
-------------------------
If you write a `sensors' driver, you use a slightly different interface.
As well as I2C addresses, we have to cope with ISA addresses. Also, we
use a enum of chip types. Don't forget to include `sensors.h'.
The following lists are used internally. They are all lists of integers.
normal_i2c: filled in by the module writer. Terminated by SENSORS_I2C_END.
A list of I2C addresses which should normally be examined.
normal_i2c_range: filled in by the module writer. Terminated by
SENSORS_I2C_END
A list of pairs of I2C addresses, each pair being an inclusive range of
addresses which should normally be examined.
normal_isa: filled in by the module writer. Terminated by SENSORS_ISA_END.
A list of ISA addresses which should normally be examined.
normal_isa_range: filled in by the module writer. Terminated by
SENSORS_ISA_END
A list of triples. The first two elements are ISA addresses, being an
range of addresses which should normally be examined. The third is the
modulo parameter: only addresses which are 0 module this value relative
to the first address of the range are actually considered.
probe: insmod parameter. Initialize this list with SENSORS_I2C_END values.
A list of pairs. The first value is a bus number (SENSORS_ISA_BUS for
the ISA bus, -1 for any I2C bus), the second is the address. These
addresses are also probed, as if they were in the 'normal' list.
probe_range: insmod parameter. Initialize this list with SENSORS_I2C_END
values.
A list of triples. The first value is a bus number (SENSORS_ISA_BUS for
the ISA bus, -1 for any I2C bus), the second and third are addresses.
These form an inclusive range of addresses that are also probed, as
if they were in the 'normal' list.
ignore: insmod parameter. Initialize this list with SENSORS_I2C_END values.
A list of pairs. The first value is a bus number (SENSORS_ISA_BUS for
the ISA bus, -1 for any I2C bus), the second is the I2C address. These
addresses are never probed. This parameter overrules 'normal' and
'probe', but not the 'force' lists.
ignore_range: insmod parameter. Initialize this list with SENSORS_I2C_END
values.
A list of triples. The first value is a bus number (SENSORS_ISA_BUS for
the ISA bus, -1 for any I2C bus), the second and third are addresses.
These form an inclusive range of I2C addresses that are never probed.
This parameter overrules 'normal' and 'probe', but not the 'force' lists.
Also used is a list of pointers to sensors_force_data structures:
force_data: insmod parameters. A list, ending with an element of which
the force field is NULL.
Each element contains the type of chip and a list of pairs.
The first value is a bus number (SENSORS_ISA_BUS for the ISA bus,
-1 for any I2C bus), the second is the address.
These are automatically translated to insmod variables of the form
force_foo.
So we have a generic insmod variabled `force', and chip-specific variables
`force_CHIPNAME'.
Fortunately, as a module writer, you just have to define the `normal'
and/or `normal_range' parameters, and define what chip names are used.
The complete declaration could look like this:
/* Scan i2c addresses 0x20 to 0x2f, 0x37, and 0x40 to 0x4f
static unsigned short normal_i2c[] = {0x37,SENSORS_I2C_END};
static unsigned short normal_i2c_range[] = {0x20,0x2f,0x40,0x4f,
SENSORS_I2C_END};
/* Scan ISA address 0x290 */
static unsigned int normal_isa[] = {0x0290,SENSORS_ISA_END};
static unsigned int normal_isa_range[] = {SENSORS_ISA_END};
/* Define chips foo and bar, as well as all module parameters and things */
SENSORS_INSMOD_2(foo,bar);
If you have one chip, you use macro SENSORS_INSMOD_1(chip), if you have 2
you use macro SENSORS_INSMOD_2(chip1,chip2), etc. If you do not want to
bother with chip types, you can use SENSORS_INSMOD_0.
A enum is automatically defined as follows:
enum chips { any_chip, chip1, chip2, ... }
Attaching to an adapter
-----------------------
Whenever a new adapter is inserted, or for all adapters if the driver is
being registered, the callback attach_adapter() is called. Now is the
time to determine what devices are present on the adapter, and to register
a client for each of them.
The attach_adapter callback is really easy: we just call the generic
detection function. This function will scan the bus for us, using the
information as defined in the lists explained above. If a device is
detected at a specific address, another callback is called.
int foo_attach_adapter(struct i2c_adapter *adapter)
{
return i2c_probe(adapter,&addr_data,&foo_detect_client);
}
For `sensors' drivers, use the i2c_detect function instead:
int foo_attach_adapter(struct i2c_adapter *adapter)
{
return i2c_detect(adapter,&addr_data,&foo_detect_client);
}
Remember, structure `addr_data' is defined by the macros explained above,
so you do not have to define it yourself.
The i2c_probe or i2c_detect function will call the foo_detect_client
function only for those i2c addresses that actually have a device on
them (unless a `force' parameter was used). In addition, addresses that
are already in use (by some other registered client) are skipped.
The detect client function
--------------------------
The detect client function is called by i2c_probe or i2c_detect.
The `kind' parameter contains 0 if this call is due to a `force'
parameter, and -1 otherwise (for i2c_detect, it contains 0 if
this call is due to the generic `force' parameter, and the chip type
number if it is due to a specific `force' parameter).
Below, some things are only needed if this is a `sensors' driver. Those
parts are between /* SENSORS ONLY START */ and /* SENSORS ONLY END */
markers.
This function should only return an error (any value != 0) if there is
some reason why no more detection should be done anymore. If the
detection just fails for this address, return 0.
For now, you can ignore the `flags' parameter. It is there for future use.
int foo_detect_client(struct i2c_adapter *adapter, int address,
unsigned short flags, int kind)
{
int err = 0;
int i;
struct i2c_client *new_client;
struct foo_data *data;
const char *client_name = ""; /* For non-`sensors' drivers, put the real
name here! */
/* Let's see whether this adapter can support what we need.
Please substitute the things you need here!
For `sensors' drivers, add `! is_isa &&' to the if statement */
if (!i2c_check_functionality(adapter,I2C_FUNC_SMBUS_WORD_DATA |
I2C_FUNC_SMBUS_WRITE_BYTE))
goto ERROR0;
/* SENSORS ONLY START */
const char *type_name = "";
int is_isa = i2c_is_isa_adapter(adapter);
if (is_isa) {
/* If this client can't be on the ISA bus at all, we can stop now
(call `goto ERROR0'). But for kicks, we will assume it is all
right. */
/* Discard immediately if this ISA range is already used */
if (check_region(address,FOO_EXTENT))
goto ERROR0;
/* Probe whether there is anything on this address.
Some example code is below, but you will have to adapt this
for your own driver */
if (kind < 0) /* Only if no force parameter was used */ {
/* We may need long timeouts at least for some chips. */
#define REALLY_SLOW_IO
i = inb_p(address + 1);
if (inb_p(address + 2) != i)
goto ERROR0;
if (inb_p(address + 3) != i)
goto ERROR0;
if (inb_p(address + 7) != i)
goto ERROR0;
#undef REALLY_SLOW_IO
/* Let's just hope nothing breaks here */
i = inb_p(address + 5) & 0x7f;
outb_p(~i & 0x7f,address+5);
if ((inb_p(address + 5) & 0x7f) != (~i & 0x7f)) {
outb_p(i,address+5);
return 0;
}
}
}
/* SENSORS ONLY END */
/* OK. For now, we presume we have a valid client. We now create the
client structure, even though we cannot fill it completely yet.
But it allows us to access several i2c functions safely */
/* Note that we reserve some space for foo_data too. If you don't
need it, remove it. We do it here to help to lessen memory
fragmentation. */
if (! (new_client = kmalloc(sizeof(struct i2c_client) +
sizeof(struct foo_data),
GFP_KERNEL))) {
err = -ENOMEM;
goto ERROR0;
}
/* This is tricky, but it will set the data to the right value. */
client->data = new_client + 1;
data = (struct foo_data *) (client->data);
new_client->addr = address;
new_client->data = data;
new_client->adapter = adapter;
new_client->driver = &foo_driver;
new_client->flags = 0;
/* Now, we do the remaining detection. If no `force' parameter is used. */
/* First, the generic detection (if any), that is skipped if any force
parameter was used. */
if (kind < 0) {
/* The below is of course bogus */
if (foo_read(new_client,FOO_REG_GENERIC) != FOO_GENERIC_VALUE)
goto ERROR1;
}
/* SENSORS ONLY START */
/* Next, specific detection. This is especially important for `sensors'
devices. */
/* Determine the chip type. Not needed if a `force_CHIPTYPE' parameter
was used. */
if (kind <= 0) {
i = foo_read(new_client,FOO_REG_CHIPTYPE);
if (i == FOO_TYPE_1)
kind = chip1; /* As defined in the enum */
else if (i == FOO_TYPE_2)
kind = chip2;
else {
printk("foo: Ignoring 'force' parameter for unknown chip at "
"adapter %d, address 0x%02x\n",i2c_adapter_id(adapter),address);
goto ERROR1;
}
}
/* Now set the type and chip names */
if (kind == chip1) {
type_name = "chip1"; /* For /proc entry */
client_name = "CHIP 1";
} else if (kind == chip2) {
type_name = "chip2"; /* For /proc entry */
client_name = "CHIP 2";
}
/* Reserve the ISA region */
if (is_isa)
request_region(address,FOO_EXTENT,type_name);
/* SENSORS ONLY END */
/* Fill in the remaining client fields. */
strcpy(new_client->name,client_name);
/* SENSORS ONLY BEGIN */
data->type = kind;
/* SENSORS ONLY END */
data->valid = 0; /* Only if you use this field */
init_MUTEX(&data->update_lock); /* Only if you use this field */
/* Any other initializations in data must be done here too. */
/* Tell the i2c layer a new client has arrived */
if ((err = i2c_attach_client(new_client)))
goto ERROR3;
/* SENSORS ONLY BEGIN */
/* Register a new directory entry with module sensors. See below for
the `template' structure. */
if ((i = i2c_register_entry(new_client, type_name,
foo_dir_table_template,THIS_MODULE)) < 0) {
err = i;
goto ERROR4;
}
data->sysctl_id = i;
/* SENSORS ONLY END */
/* This function can write default values to the client registers, if
needed. */
foo_init_client(new_client);
return 0;
/* OK, this is not exactly good programming practice, usually. But it is
very code-efficient in this case. */
ERROR4:
i2c_detach_client(new_client);
ERROR3:
ERROR2:
/* SENSORS ONLY START */
if (is_isa)
release_region(address,FOO_EXTENT);
/* SENSORS ONLY END */
ERROR1:
kfree(new_client);
ERROR0:
return err;
}
Removing the client
===================
The detach_client call back function is called when a client should be
removed. It may actually fail, but only when panicking. This code is
much simpler than the attachment code, fortunately!
int foo_detach_client(struct i2c_client *client)
{
int err,i;
/* SENSORS ONLY START */
/* Deregister with the `i2c-proc' module. */
i2c_deregister_entry(((struct lm78_data *)(client->data))->sysctl_id);
/* SENSORS ONLY END */
/* Try to detach the client from i2c space */
if ((err = i2c_detach_client(client))) {
printk("foo.o: Client deregistration failed, client not detached.\n");
return err;
}
/* SENSORS ONLY START */
if i2c_is_isa_client(client)
release_region(client->addr,LM78_EXTENT);
/* SENSORS ONLY END */
kfree(client); /* Frees client data too, if allocated at the same time */
return 0;
}
Initializing the module or kernel
=================================
When the kernel is booted, or when your foo driver module is inserted,
you have to do some initializing. Fortunately, just attaching (registering)
the driver module is usually enough.
/* Keep track of how far we got in the initialization process. If several
things have to initialized, and we fail halfway, only those things
have to be cleaned up! */
static int __initdata foo_initialized = 0;
static int __init foo_init(void)
{
int res;
printk("foo version %s (%s)\n",FOO_VERSION,FOO_DATE);
if ((res = i2c_add_driver(&foo_driver))) {
printk("foo: Driver registration failed, module not inserted.\n");
foo_cleanup();
return res;
}
foo_initialized ++;
return 0;
}
void foo_cleanup(void)
{
if (foo_initialized == 1) {
if ((res = i2c_del_driver(&foo_driver))) {
printk("foo: Driver registration failed, module not removed.\n");
return;
}
foo_initialized --;
}
}
/* Substitute your own name and email address */
MODULE_AUTHOR("Frodo Looijaard <frodol@dds.nl>"
MODULE_DESCRIPTION("Driver for Barf Inc. Foo I2C devices");
module_init(foo_init);
module_exit(foo_cleanup);
Note that some functions are marked by `__init', and some data structures
by `__init_data'. Hose functions and structures can be removed after
kernel booting (or module loading) is completed.
Command function
================
A generic ioctl-like function call back is supported. You will seldom
need this. You may even set it to NULL.
/* No commands defined */
int foo_command(struct i2c_client *client, unsigned int cmd, void *arg)
{
return 0;
}
Sending and receiving
=====================
If you want to communicate with your device, there are several functions
to do this. You can find all of them in i2c.h.
If you can choose between plain i2c communication and SMBus level
communication, please use the last. All adapters understand SMBus level
commands, but only some of them understand plain i2c!
Plain i2c communication
-----------------------
extern int i2c_master_send(struct i2c_client *,const char* ,int);
extern int i2c_master_recv(struct i2c_client *,char* ,int);
These routines read and write some bytes from/to a client. The client
contains the i2c address, so you do not have to include it. The second
parameter contains the bytes the read/write, the third the length of the
buffer. Returned is the actual number of bytes read/written.
extern int i2c_transfer(struct i2c_adapter *adap, struct i2c_msg *msg,
int num);
This sends a series of messages. Each message can be a read or write,
and they can be mixed in any way. The transactions are combined: no
stop bit is sent between transaction. The i2c_msg structure contains
for each message the client address, the number of bytes of the message
and the message data itself.
You can read the file `i2c-protocol' for more information about the
actual i2c protocol.
SMBus communication
-------------------
extern s32 i2c_smbus_xfer (struct i2c_adapter * adapter, u16 addr,
unsigned short flags,
char read_write, u8 command, int size,
union i2c_smbus_data * data);
This is the generic SMBus function. All functions below are implemented
in terms of it. Never use this function directly!
extern s32 i2c_smbus_write_quick(struct i2c_client * client, u8 value);
extern s32 i2c_smbus_read_byte(struct i2c_client * client);
extern s32 i2c_smbus_write_byte(struct i2c_client * client, u8 value);
extern s32 i2c_smbus_read_byte_data(struct i2c_client * client, u8 command);
extern s32 i2c_smbus_write_byte_data(struct i2c_client * client,
u8 command, u8 value);
extern s32 i2c_smbus_read_word_data(struct i2c_client * client, u8 command);
extern s32 i2c_smbus_write_word_data(struct i2c_client * client,
u8 command, u16 value);
extern s32 i2c_smbus_write_block_data(struct i2c_client * client,
u8 command, u8 length,
u8 *values);
These ones were removed in Linux 2.6.10 because they had no users, but could
be added back later if needed:
extern s32 i2c_smbus_read_i2c_block_data(struct i2c_client * client,
u8 command, u8 *values);
extern s32 i2c_smbus_read_block_data(struct i2c_client * client,
u8 command, u8 *values);
extern s32 i2c_smbus_write_i2c_block_data(struct i2c_client * client,
u8 command, u8 length,
u8 *values);
extern s32 i2c_smbus_process_call(struct i2c_client * client,
u8 command, u16 value);
extern s32 i2c_smbus_block_process_call(struct i2c_client *client,
u8 command, u8 length,
u8 *values)
All these transactions return -1 on failure. The 'write' transactions
return 0 on success; the 'read' transactions return the read value, except
for read_block, which returns the number of values read. The block buffers
need not be longer than 32 bytes.
You can read the file `smbus-protocol' for more information about the
actual SMBus protocol.
General purpose routines
========================
Below all general purpose routines are listed, that were not mentioned
before.
/* This call returns a unique low identifier for each registered adapter,
* or -1 if the adapter was not registered.
*/
extern int i2c_adapter_id(struct i2c_adapter *adap);
The sensors sysctl/proc interface
=================================
This section only applies if you write `sensors' drivers.
Each sensors driver creates a directory in /proc/sys/dev/sensors for each
registered client. The directory is called something like foo-i2c-4-65.
The sensors module helps you to do this as easily as possible.
The template
------------
You will need to define a ctl_table template. This template will automatically
be copied to a newly allocated structure and filled in where necessary when
you call sensors_register_entry.
First, I will give an example definition.
static ctl_table foo_dir_table_template[] = {
{ FOO_SYSCTL_FUNC1, "func1", NULL, 0, 0644, NULL, &i2c_proc_real,
&i2c_sysctl_real,NULL,&foo_func },
{ FOO_SYSCTL_FUNC2, "func2", NULL, 0, 0644, NULL, &i2c_proc_real,
&i2c_sysctl_real,NULL,&foo_func },
{ FOO_SYSCTL_DATA, "data", NULL, 0, 0644, NULL, &i2c_proc_real,
&i2c_sysctl_real,NULL,&foo_data },
{ 0 }
};
In the above example, three entries are defined. They can either be
accessed through the /proc interface, in the /proc/sys/dev/sensors/*
directories, as files named func1, func2 and data, or alternatively
through the sysctl interface, in the appropriate table, with identifiers
FOO_SYSCTL_FUNC1, FOO_SYSCTL_FUNC2 and FOO_SYSCTL_DATA.
The third, sixth and ninth parameters should always be NULL, and the
fourth should always be 0. The fifth is the mode of the /proc file;
0644 is safe, as the file will be owned by root:root.
The seventh and eighth parameters should be &i2c_proc_real and
&i2c_sysctl_real if you want to export lists of reals (scaled
integers). You can also use your own function for them, as usual.
Finally, the last parameter is the call-back to gather the data
(see below) if you use the *_proc_real functions.
Gathering the data
------------------
The call back functions (foo_func and foo_data in the above example)
can be called in several ways; the operation parameter determines
what should be done:
* If operation == SENSORS_PROC_REAL_INFO, you must return the
magnitude (scaling) in nrels_mag;
* If operation == SENSORS_PROC_REAL_READ, you must read information
from the chip and return it in results. The number of integers
to display should be put in nrels_mag;
* If operation == SENSORS_PROC_REAL_WRITE, you must write the
supplied information to the chip. nrels_mag will contain the number
of integers, results the integers themselves.
The *_proc_real functions will display the elements as reals for the
/proc interface. If you set the magnitude to 2, and supply 345 for
SENSORS_PROC_REAL_READ, it would display 3.45; and if the user would
write 45.6 to the /proc file, it would be returned as 4560 for
SENSORS_PROC_REAL_WRITE. A magnitude may even be negative!
An example function:
/* FOO_FROM_REG and FOO_TO_REG translate between scaled values and
register values. Note the use of the read cache. */
void foo_in(struct i2c_client *client, int operation, int ctl_name,
int *nrels_mag, long *results)
{
struct foo_data *data = client->data;
int nr = ctl_name - FOO_SYSCTL_FUNC1; /* reduce to 0 upwards */
if (operation == SENSORS_PROC_REAL_INFO)
*nrels_mag = 2;
else if (operation == SENSORS_PROC_REAL_READ) {
/* Update the readings cache (if necessary) */
foo_update_client(client);
/* Get the readings from the cache */
results[0] = FOO_FROM_REG(data->foo_func_base[nr]);
results[1] = FOO_FROM_REG(data->foo_func_more[nr]);
results[2] = FOO_FROM_REG(data->foo_func_readonly[nr]);
*nrels_mag = 2;
} else if (operation == SENSORS_PROC_REAL_WRITE) {
if (*nrels_mag >= 1) {
/* Update the cache */
data->foo_base[nr] = FOO_TO_REG(results[0]);
/* Update the chip */
foo_write_value(client,FOO_REG_FUNC_BASE(nr),data->foo_base[nr]);
}
if (*nrels_mag >= 2) {
/* Update the cache */
data->foo_more[nr] = FOO_TO_REG(results[1]);
/* Update the chip */
foo_write_value(client,FOO_REG_FUNC_MORE(nr),data->foo_more[nr]);
}
}
}