aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/i2c
diff options
context:
space:
mode:
authorDavid S. Miller <davem@davemloft.net>2008-07-18 05:39:39 -0400
committerDavid S. Miller <davem@davemloft.net>2008-07-18 05:39:39 -0400
commit49997d75152b3d23c53b0fa730599f2f74c92c65 (patch)
tree46e93126170d02cfec9505172e545732c1b69656 /Documentation/i2c
parenta0c80b80e0fb48129e4e9d6a9ede914f9ff1850d (diff)
parent5b664cb235e97afbf34db9c4d77f08ebd725335e (diff)
Merge branch 'master' of master.kernel.org:/pub/scm/linux/kernel/git/torvalds/linux-2.6
Conflicts: Documentation/powerpc/booting-without-of.txt drivers/atm/Makefile drivers/net/fs_enet/fs_enet-main.c drivers/pci/pci-acpi.c net/8021q/vlan.c net/iucv/iucv.c
Diffstat (limited to 'Documentation/i2c')
-rw-r--r--Documentation/i2c/busses/i2c-i81047
-rw-r--r--Documentation/i2c/busses/i2c-prosavage23
-rw-r--r--Documentation/i2c/busses/i2c-savage426
-rw-r--r--Documentation/i2c/chips/max68752
-rw-r--r--Documentation/i2c/chips/pca953910
-rw-r--r--Documentation/i2c/chips/pcf857412
-rw-r--r--Documentation/i2c/chips/pcf85759
-rw-r--r--Documentation/i2c/fault-codes127
-rw-r--r--Documentation/i2c/smbus-protocol4
-rw-r--r--Documentation/i2c/writing-clients51
10 files changed, 187 insertions, 124 deletions
diff --git a/Documentation/i2c/busses/i2c-i810 b/Documentation/i2c/busses/i2c-i810
deleted file mode 100644
index 778210ee1583..000000000000
--- a/Documentation/i2c/busses/i2c-i810
+++ /dev/null
@@ -1,47 +0,0 @@
1Kernel driver i2c-i810
2
3Supported adapters:
4 * Intel 82810, 82810-DC100, 82810E, and 82815 (GMCH)
5 * Intel 82845G (GMCH)
6
7Authors:
8 Frodo Looijaard <frodol@dds.nl>,
9 Philip Edelbrock <phil@netroedge.com>,
10 Kyösti Mälkki <kmalkki@cc.hut.fi>,
11 Ralph Metzler <rjkm@thp.uni-koeln.de>,
12 Mark D. Studebaker <mdsxyz123@yahoo.com>
13
14Main contact: Mark Studebaker <mdsxyz123@yahoo.com>
15
16Description
17-----------
18
19WARNING: If you have an '810' or '815' motherboard, your standard I2C
20temperature sensors are most likely on the 801's I2C bus. You want the
21i2c-i801 driver for those, not this driver.
22
23Now for the i2c-i810...
24
25The GMCH chip contains two I2C interfaces.
26
27The first interface is used for DDC (Data Display Channel) which is a
28serial channel through the VGA monitor connector to a DDC-compliant
29monitor. This interface is defined by the Video Electronics Standards
30Association (VESA). The standards are available for purchase at
31http://www.vesa.org .
32
33The second interface is a general-purpose I2C bus. It may be connected to a
34TV-out chip such as the BT869 or possibly to a digital flat-panel display.
35
36Features
37--------
38
39Both busses use the i2c-algo-bit driver for 'bit banging'
40and support for specific transactions is provided by i2c-algo-bit.
41
42Issues
43------
44
45If you enable bus testing in i2c-algo-bit (insmod i2c-algo-bit bit_test=1),
46the test may fail; if so, the i2c-i810 driver won't be inserted. However,
47we think this has been fixed.
diff --git a/Documentation/i2c/busses/i2c-prosavage b/Documentation/i2c/busses/i2c-prosavage
deleted file mode 100644
index 703687902511..000000000000
--- a/Documentation/i2c/busses/i2c-prosavage
+++ /dev/null
@@ -1,23 +0,0 @@
1Kernel driver i2c-prosavage
2
3Supported adapters:
4
5 S3/VIA KM266/VT8375 aka ProSavage8
6 S3/VIA KM133/VT8365 aka Savage4
7
8Author: Henk Vergonet <henk@god.dyndns.org>
9
10Description
11-----------
12
13The Savage4 chips contain two I2C interfaces (aka a I2C 'master' or
14'host').
15
16The first interface is used for DDC (Data Display Channel) which is a
17serial channel through the VGA monitor connector to a DDC-compliant
18monitor. This interface is defined by the Video Electronics Standards
19Association (VESA). The standards are available for purchase at
20http://www.vesa.org . The second interface is a general-purpose I2C bus.
21
22Usefull for gaining access to the TV Encoder chips.
23
diff --git a/Documentation/i2c/busses/i2c-savage4 b/Documentation/i2c/busses/i2c-savage4
deleted file mode 100644
index 6ecceab618d3..000000000000
--- a/Documentation/i2c/busses/i2c-savage4
+++ /dev/null
@@ -1,26 +0,0 @@
1Kernel driver i2c-savage4
2
3Supported adapters:
4 * Savage4
5 * Savage2000
6
7Authors:
8 Alexander Wold <awold@bigfoot.com>,
9 Mark D. Studebaker <mdsxyz123@yahoo.com>
10
11Description
12-----------
13
14The Savage4 chips contain two I2C interfaces (aka a I2C 'master'
15or 'host').
16
17The first interface is used for DDC (Data Display Channel) which is a
18serial channel through the VGA monitor connector to a DDC-compliant
19monitor. This interface is defined by the Video Electronics Standards
20Association (VESA). The standards are available for purchase at
21http://www.vesa.org . The DDC bus is not yet supported because its register
22is not directly memory-mapped.
23
24The second interface is a general-purpose I2C bus. This is the only
25interface supported by the driver at the moment.
26
diff --git a/Documentation/i2c/chips/max6875 b/Documentation/i2c/chips/max6875
index a0cd8af2f408..10ca43cd1a72 100644
--- a/Documentation/i2c/chips/max6875
+++ b/Documentation/i2c/chips/max6875
@@ -49,7 +49,7 @@ $ modprobe max6875 force=0,0x50
49 49
50The MAX6874/MAX6875 ignores address bit 0, so this driver attaches to multiple 50The MAX6874/MAX6875 ignores address bit 0, so this driver attaches to multiple
51addresses. For example, for address 0x50, it also reserves 0x51. 51addresses. For example, for address 0x50, it also reserves 0x51.
52The even-address instance is called 'max6875', the odd one is 'max6875 subclient'. 52The even-address instance is called 'max6875', the odd one is 'dummy'.
53 53
54 54
55Programming the chip using i2c-dev 55Programming the chip using i2c-dev
diff --git a/Documentation/i2c/chips/pca9539 b/Documentation/i2c/chips/pca9539
index 1d81c530c4a5..6aff890088b1 100644
--- a/Documentation/i2c/chips/pca9539
+++ b/Documentation/i2c/chips/pca9539
@@ -7,7 +7,7 @@ drivers/gpio/pca9539.c instead.
7Supported chips: 7Supported chips:
8 * Philips PCA9539 8 * Philips PCA9539
9 Prefix: 'pca9539' 9 Prefix: 'pca9539'
10 Addresses scanned: 0x74 - 0x77 10 Addresses scanned: none
11 Datasheet: 11 Datasheet:
12 http://www.semiconductors.philips.com/acrobat/datasheets/PCA9539_2.pdf 12 http://www.semiconductors.philips.com/acrobat/datasheets/PCA9539_2.pdf
13 13
@@ -23,6 +23,14 @@ The input sense can also be inverted.
23The 16 lines are split between two bytes. 23The 16 lines are split between two bytes.
24 24
25 25
26Detection
27---------
28
29The PCA9539 is difficult to detect and not commonly found in PC machines,
30so you have to pass the I2C bus and address of the installed PCA9539
31devices explicitly to the driver at load time via the force=... parameter.
32
33
26Sysfs entries 34Sysfs entries
27------------- 35-------------
28 36
diff --git a/Documentation/i2c/chips/pcf8574 b/Documentation/i2c/chips/pcf8574
index 5c1ad1376b62..235815c075ff 100644
--- a/Documentation/i2c/chips/pcf8574
+++ b/Documentation/i2c/chips/pcf8574
@@ -4,13 +4,13 @@ Kernel driver pcf8574
4Supported chips: 4Supported chips:
5 * Philips PCF8574 5 * Philips PCF8574
6 Prefix: 'pcf8574' 6 Prefix: 'pcf8574'
7 Addresses scanned: I2C 0x20 - 0x27 7 Addresses scanned: none
8 Datasheet: Publicly available at the Philips Semiconductors website 8 Datasheet: Publicly available at the Philips Semiconductors website
9 http://www.semiconductors.philips.com/pip/PCF8574P.html 9 http://www.semiconductors.philips.com/pip/PCF8574P.html
10 10
11 * Philips PCF8574A 11 * Philips PCF8574A
12 Prefix: 'pcf8574a' 12 Prefix: 'pcf8574a'
13 Addresses scanned: I2C 0x38 - 0x3f 13 Addresses scanned: none
14 Datasheet: Publicly available at the Philips Semiconductors website 14 Datasheet: Publicly available at the Philips Semiconductors website
15 http://www.semiconductors.philips.com/pip/PCF8574P.html 15 http://www.semiconductors.philips.com/pip/PCF8574P.html
16 16
@@ -38,12 +38,10 @@ For more informations see the datasheet.
38Accessing PCF8574(A) via /sys interface 38Accessing PCF8574(A) via /sys interface
39------------------------------------- 39-------------------------------------
40 40
41! Be careful !
42The PCF8574(A) is plainly impossible to detect ! Stupid chip. 41The PCF8574(A) is plainly impossible to detect ! Stupid chip.
43So every chip with address in the interval [20..27] and [38..3f] are 42So, you have to pass the I2C bus and address of the installed PCF857A
44detected as PCF8574(A). If you have other chips in this address 43and PCF8574A devices explicitly to the driver at load time via the
45range, the workaround is to load this module after the one 44force=... parameter.
46for your others chips.
47 45
48On detection (i.e. insmod, modprobe et al.), directories are being 46On detection (i.e. insmod, modprobe et al.), directories are being
49created for each detected PCF8574(A): 47created for each detected PCF8574(A):
diff --git a/Documentation/i2c/chips/pcf8575 b/Documentation/i2c/chips/pcf8575
index 25f5698a61cf..40b268eb276f 100644
--- a/Documentation/i2c/chips/pcf8575
+++ b/Documentation/i2c/chips/pcf8575
@@ -40,12 +40,9 @@ Detection
40--------- 40---------
41 41
42There is no method known to detect whether a chip on a given I2C address is 42There is no method known to detect whether a chip on a given I2C address is
43a PCF8575 or whether it is any other I2C device. So there are two alternatives 43a PCF8575 or whether it is any other I2C device, so you have to pass the I2C
44to let the driver find the installed PCF8575 devices: 44bus and address of the installed PCF8575 devices explicitly to the driver at
45- Load this driver after any other I2C driver for I2C devices with addresses 45load time via the force=... parameter.
46 in the range 0x20 .. 0x27.
47- Pass the I2C bus and address of the installed PCF8575 devices explicitly to
48 the driver at load time via the probe=... or force=... parameters.
49 46
50/sys interface 47/sys interface
51-------------- 48--------------
diff --git a/Documentation/i2c/fault-codes b/Documentation/i2c/fault-codes
new file mode 100644
index 000000000000..045765c0b9b5
--- /dev/null
+++ b/Documentation/i2c/fault-codes
@@ -0,0 +1,127 @@
1This is a summary of the most important conventions for use of fault
2codes in the I2C/SMBus stack.
3
4
5A "Fault" is not always an "Error"
6----------------------------------
7Not all fault reports imply errors; "page faults" should be a familiar
8example. Software often retries idempotent operations after transient
9faults. There may be fancier recovery schemes that are appropriate in
10some cases, such as re-initializing (and maybe resetting). After such
11recovery, triggered by a fault report, there is no error.
12
13In a similar way, sometimes a "fault" code just reports one defined
14result for an operation ... it doesn't indicate that anything is wrong
15at all, just that the outcome wasn't on the "golden path".
16
17In short, your I2C driver code may need to know these codes in order
18to respond correctly. Other code may need to rely on YOUR code reporting
19the right fault code, so that it can (in turn) behave correctly.
20
21
22I2C and SMBus fault codes
23-------------------------
24These are returned as negative numbers from most calls, with zero or
25some positive number indicating a non-fault return. The specific
26numbers associated with these symbols differ between architectures,
27though most Linux systems use <asm-generic/errno*.h> numbering.
28
29Note that the descriptions here are not exhaustive. There are other
30codes that may be returned, and other cases where these codes should
31be returned. However, drivers should not return other codes for these
32cases (unless the hardware doesn't provide unique fault reports).
33
34Also, codes returned by adapter probe methods follow rules which are
35specific to their host bus (such as PCI, or the platform bus).
36
37
38EAGAIN
39 Returned by I2C adapters when they lose arbitration in master
40 transmit mode: some other master was transmitting different
41 data at the same time.
42
43 Also returned when trying to invoke an I2C operation in an
44 atomic context, when some task is already using that I2C bus
45 to execute some other operation.
46
47EBADMSG
48 Returned by SMBus logic when an invalid Packet Error Code byte
49 is received. This code is a CRC covering all bytes in the
50 transaction, and is sent before the terminating STOP. This
51 fault is only reported on read transactions; the SMBus slave
52 may have a way to report PEC mismatches on writes from the
53 host. Note that even if PECs are in use, you should not rely
54 on these as the only way to detect incorrect data transfers.
55
56EBUSY
57 Returned by SMBus adapters when the bus was busy for longer
58 than allowed. This usually indicates some device (maybe the
59 SMBus adapter) needs some fault recovery (such as resetting),
60 or that the reset was attempted but failed.
61
62EINVAL
63 This rather vague error means an invalid parameter has been
64 detected before any I/O operation was started. Use a more
65 specific fault code when you can.
66
67 One example would be a driver trying an SMBus Block Write
68 with block size outside the range of 1-32 bytes.
69
70EIO
71 This rather vague error means something went wrong when
72 performing an I/O operation. Use a more specific fault
73 code when you can.
74
75ENODEV
76 Returned by driver probe() methods. This is a bit more
77 specific than ENXIO, implying the problem isn't with the
78 address, but with the device found there. Driver probes
79 may verify the device returns *correct* responses, and
80 return this as appropriate. (The driver core will warn
81 about probe faults other than ENXIO and ENODEV.)
82
83ENOMEM
84 Returned by any component that can't allocate memory when
85 it needs to do so.
86
87ENXIO
88 Returned by I2C adapters to indicate that the address phase
89 of a transfer didn't get an ACK. While it might just mean
90 an I2C device was temporarily not responding, usually it
91 means there's nothing listening at that address.
92
93 Returned by driver probe() methods to indicate that they
94 found no device to bind to. (ENODEV may also be used.)
95
96EOPNOTSUPP
97 Returned by an adapter when asked to perform an operation
98 that it doesn't, or can't, support.
99
100 For example, this would be returned when an adapter that
101 doesn't support SMBus block transfers is asked to execute
102 one. In that case, the driver making that request should
103 have verified that functionality was supported before it
104 made that block transfer request.
105
106 Similarly, if an I2C adapter can't execute all legal I2C
107 messages, it should return this when asked to perform a
108 transaction it can't. (These limitations can't be seen in
109 the adapter's functionality mask, since the assumption is
110 that if an adapter supports I2C it supports all of I2C.)
111
112EPROTO
113 Returned when slave does not conform to the relevant I2C
114 or SMBus (or chip-specific) protocol specifications. One
115 case is when the length of an SMBus block data response
116 (from the SMBus slave) is outside the range 1-32 bytes.
117
118ETIMEDOUT
119 This is returned by drivers when an operation took too much
120 time, and was aborted before it completed.
121
122 SMBus adapters may return it when an operation took more
123 time than allowed by the SMBus specification; for example,
124 when a slave stretches clocks too far. I2C has no such
125 timeouts, but it's normal for I2C adapters to impose some
126 arbitrary limits (much longer than SMBus!) too.
127
diff --git a/Documentation/i2c/smbus-protocol b/Documentation/i2c/smbus-protocol
index 03f08fb491cc..24bfb65da17d 100644
--- a/Documentation/i2c/smbus-protocol
+++ b/Documentation/i2c/smbus-protocol
@@ -42,8 +42,8 @@ Count (8 bits): A data byte containing the length of a block operation.
42[..]: Data sent by I2C device, as opposed to data sent by the host adapter. 42[..]: Data sent by I2C device, as opposed to data sent by the host adapter.
43 43
44 44
45SMBus Quick Command: i2c_smbus_write_quick() 45SMBus Quick Command
46============================================= 46===================
47 47
48This sends a single bit to the device, at the place of the Rd/Wr bit. 48This sends a single bit to the device, at the place of the Rd/Wr bit.
49 49
diff --git a/Documentation/i2c/writing-clients b/Documentation/i2c/writing-clients
index d4cd4126d1ad..6b61b3a2e90b 100644
--- a/Documentation/i2c/writing-clients
+++ b/Documentation/i2c/writing-clients
@@ -44,6 +44,10 @@ static struct i2c_driver foo_driver = {
44 .id_table = foo_ids, 44 .id_table = foo_ids,
45 .probe = foo_probe, 45 .probe = foo_probe,
46 .remove = foo_remove, 46 .remove = foo_remove,
47 /* if device autodetection is needed: */
48 .class = I2C_CLASS_SOMETHING,
49 .detect = foo_detect,
50 .address_data = &addr_data,
47 51
48 /* else, driver uses "legacy" binding model: */ 52 /* else, driver uses "legacy" binding model: */
49 .attach_adapter = foo_attach_adapter, 53 .attach_adapter = foo_attach_adapter,
@@ -217,6 +221,31 @@ in the I2C bus driver. You may want to save the returned i2c_client
217reference for later use. 221reference for later use.
218 222
219 223
224Device Detection (Standard driver model)
225----------------------------------------
226
227Sometimes you do not know in advance which I2C devices are connected to
228a given I2C bus. This is for example the case of hardware monitoring
229devices on a PC's SMBus. In that case, you may want to let your driver
230detect supported devices automatically. This is how the legacy model
231was working, and is now available as an extension to the standard
232driver model (so that we can finally get rid of the legacy model.)
233
234You simply have to define a detect callback which will attempt to
235identify supported devices (returning 0 for supported ones and -ENODEV
236for unsupported ones), a list of addresses to probe, and a device type
237(or class) so that only I2C buses which may have that type of device
238connected (and not otherwise enumerated) will be probed. The i2c
239core will then call you back as needed and will instantiate a device
240for you for every successful detection.
241
242Note that this mechanism is purely optional and not suitable for all
243devices. You need some reliable way to identify the supported devices
244(typically using device-specific, dedicated identification registers),
245otherwise misdetections are likely to occur and things can get wrong
246quickly.
247
248
220Device Deletion (Standard driver model) 249Device Deletion (Standard driver model)
221--------------------------------------- 250---------------------------------------
222 251
@@ -569,7 +598,6 @@ SMBus communication
569 in terms of it. Never use this function directly! 598 in terms of it. Never use this function directly!
570 599
571 600
572 extern s32 i2c_smbus_write_quick(struct i2c_client * client, u8 value);
573 extern s32 i2c_smbus_read_byte(struct i2c_client * client); 601 extern s32 i2c_smbus_read_byte(struct i2c_client * client);
574 extern s32 i2c_smbus_write_byte(struct i2c_client * client, u8 value); 602 extern s32 i2c_smbus_write_byte(struct i2c_client * client, u8 value);
575 extern s32 i2c_smbus_read_byte_data(struct i2c_client * client, u8 command); 603 extern s32 i2c_smbus_read_byte_data(struct i2c_client * client, u8 command);
@@ -578,30 +606,31 @@ SMBus communication
578 extern s32 i2c_smbus_read_word_data(struct i2c_client * client, u8 command); 606 extern s32 i2c_smbus_read_word_data(struct i2c_client * client, u8 command);
579 extern s32 i2c_smbus_write_word_data(struct i2c_client * client, 607 extern s32 i2c_smbus_write_word_data(struct i2c_client * client,
580 u8 command, u16 value); 608 u8 command, u16 value);
609 extern s32 i2c_smbus_read_block_data(struct i2c_client * client,
610 u8 command, u8 *values);
581 extern s32 i2c_smbus_write_block_data(struct i2c_client * client, 611 extern s32 i2c_smbus_write_block_data(struct i2c_client * client,
582 u8 command, u8 length, 612 u8 command, u8 length,
583 u8 *values); 613 u8 *values);
584 extern s32 i2c_smbus_read_i2c_block_data(struct i2c_client * client, 614 extern s32 i2c_smbus_read_i2c_block_data(struct i2c_client * client,
585 u8 command, u8 length, u8 *values); 615 u8 command, u8 length, u8 *values);
586
587These ones were removed in Linux 2.6.10 because they had no users, but could
588be added back later if needed:
589
590 extern s32 i2c_smbus_read_block_data(struct i2c_client * client,
591 u8 command, u8 *values);
592 extern s32 i2c_smbus_write_i2c_block_data(struct i2c_client * client, 616 extern s32 i2c_smbus_write_i2c_block_data(struct i2c_client * client,
593 u8 command, u8 length, 617 u8 command, u8 length,
594 u8 *values); 618 u8 *values);
619
620These ones were removed from i2c-core because they had no users, but could
621be added back later if needed:
622
623 extern s32 i2c_smbus_write_quick(struct i2c_client * client, u8 value);
595 extern s32 i2c_smbus_process_call(struct i2c_client * client, 624 extern s32 i2c_smbus_process_call(struct i2c_client * client,
596 u8 command, u16 value); 625 u8 command, u16 value);
597 extern s32 i2c_smbus_block_process_call(struct i2c_client *client, 626 extern s32 i2c_smbus_block_process_call(struct i2c_client *client,
598 u8 command, u8 length, 627 u8 command, u8 length,
599 u8 *values) 628 u8 *values)
600 629
601All these transactions return -1 on failure. The 'write' transactions 630All these transactions return a negative errno value on failure. The 'write'
602return 0 on success; the 'read' transactions return the read value, except 631transactions return 0 on success; the 'read' transactions return the read
603for read_block, which returns the number of values read. The block buffers 632value, except for block transactions, which return the number of values
604need not be longer than 32 bytes. 633read. The block buffers need not be longer than 32 bytes.
605 634
606You can read the file `smbus-protocol' for more information about the 635You can read the file `smbus-protocol' for more information about the
607actual SMBus protocol. 636actual SMBus protocol.