diff options
Diffstat (limited to 'Documentation/i2c')
| -rw-r--r-- | Documentation/i2c/busses/i2c-ali1535.rst (renamed from Documentation/i2c/busses/i2c-ali1535) | 13 | ||||
| -rw-r--r-- | Documentation/i2c/busses/i2c-ali1563.rst (renamed from Documentation/i2c/busses/i2c-ali1563) | 3 | ||||
| -rw-r--r-- | Documentation/i2c/busses/i2c-ali15x3.rst (renamed from Documentation/i2c/busses/i2c-ali15x3) | 64 | ||||
| -rw-r--r-- | Documentation/i2c/busses/i2c-amd-mp2 | 23 | ||||
| -rw-r--r-- | Documentation/i2c/busses/i2c-amd-mp2.rst | 25 | ||||
| -rw-r--r-- | Documentation/i2c/busses/i2c-amd756.rst (renamed from Documentation/i2c/busses/i2c-amd756) | 8 | ||||
| -rw-r--r-- | Documentation/i2c/busses/i2c-amd8111.rst (renamed from Documentation/i2c/busses/i2c-amd8111) | 14 | ||||
| -rw-r--r-- | Documentation/i2c/busses/i2c-diolan-u2c.rst (renamed from Documentation/i2c/busses/i2c-diolan-u2c) | 3 | ||||
| -rw-r--r-- | Documentation/i2c/busses/i2c-i801.rst (renamed from Documentation/i2c/busses/i2c-i801) | 34 | ||||
| -rw-r--r-- | Documentation/i2c/busses/i2c-ismt.rst (renamed from Documentation/i2c/busses/i2c-ismt) | 20 | ||||
| -rw-r--r-- | Documentation/i2c/busses/i2c-mlxcpld.rst (renamed from Documentation/i2c/busses/i2c-mlxcpld) | 6 | ||||
| -rw-r--r-- | Documentation/i2c/busses/i2c-nforce2.rst (renamed from Documentation/i2c/busses/i2c-nforce2) | 33 | ||||
| -rw-r--r-- | Documentation/i2c/busses/i2c-nvidia-gpu.rst (renamed from Documentation/i2c/busses/i2c-nvidia-gpu) | 6 | ||||
| -rw-r--r-- | Documentation/i2c/busses/i2c-ocores.rst (renamed from Documentation/i2c/busses/i2c-ocores) | 22 | ||||
| -rw-r--r-- | Documentation/i2c/busses/i2c-parport | 178 | ||||
| -rw-r--r-- | Documentation/i2c/busses/i2c-parport-light | 22 | ||||
| -rw-r--r-- | Documentation/i2c/busses/i2c-parport.rst | 190 | ||||
| -rw-r--r-- | Documentation/i2c/busses/i2c-pca-isa.rst (renamed from Documentation/i2c/busses/i2c-pca-isa) | 9 | ||||
| -rw-r--r-- | Documentation/i2c/busses/i2c-piix4.rst (renamed from Documentation/i2c/busses/i2c-piix4) | 18 | ||||
| -rw-r--r-- | Documentation/i2c/busses/i2c-sis5595.rst (renamed from Documentation/i2c/busses/i2c-sis5595) | 19 | ||||
| -rw-r--r-- | Documentation/i2c/busses/i2c-sis630 | 58 | ||||
| -rw-r--r-- | Documentation/i2c/busses/i2c-sis630.rst | 63 | ||||
| -rw-r--r-- | Documentation/i2c/busses/i2c-sis96x.rst (renamed from Documentation/i2c/busses/i2c-sis96x) | 31 | ||||
| -rw-r--r-- | Documentation/i2c/busses/i2c-taos-evm.rst (renamed from Documentation/i2c/busses/i2c-taos-evm) | 8 | ||||
| -rw-r--r-- | Documentation/i2c/busses/i2c-via.rst (renamed from Documentation/i2c/busses/i2c-via) | 28 | ||||
| -rw-r--r-- | Documentation/i2c/busses/i2c-viapro.rst (renamed from Documentation/i2c/busses/i2c-viapro) | 12 | ||||
| -rw-r--r-- | Documentation/i2c/busses/index.rst | 32 | ||||
| -rw-r--r-- | Documentation/i2c/busses/scx200_acb.rst (renamed from Documentation/i2c/busses/scx200_acb) | 9 | ||||
| -rw-r--r-- | Documentation/i2c/dev-interface.rst (renamed from Documentation/i2c/dev-interface) | 122 | ||||
| -rw-r--r-- | Documentation/i2c/dma-considerations.rst (renamed from Documentation/i2c/DMA-considerations) | 2 | ||||
| -rw-r--r-- | Documentation/i2c/fault-codes.rst (renamed from Documentation/i2c/fault-codes) | 5 | ||||
| -rw-r--r-- | Documentation/i2c/functionality.rst (renamed from Documentation/i2c/functionality) | 22 | ||||
| -rw-r--r-- | Documentation/i2c/gpio-fault-injection.rst (renamed from Documentation/i2c/gpio-fault-injection) | 12 | ||||
| -rw-r--r-- | Documentation/i2c/i2c-protocol.rst (renamed from Documentation/i2c/i2c-protocol) | 59 | ||||
| -rw-r--r-- | Documentation/i2c/i2c-stub.rst (renamed from Documentation/i2c/i2c-stub) | 20 | ||||
| -rw-r--r-- | Documentation/i2c/i2c-topology.rst (renamed from Documentation/i2c/i2c-topology) | 128 | ||||
| -rw-r--r-- | Documentation/i2c/i2c.svg | 1341 | ||||
| -rw-r--r-- | Documentation/i2c/index.rst | 73 | ||||
| -rw-r--r-- | Documentation/i2c/instantiating-devices.rst (renamed from Documentation/i2c/instantiating-devices) | 164 | ||||
| -rw-r--r-- | Documentation/i2c/muxes/i2c-mux-gpio.rst (renamed from Documentation/i2c/muxes/i2c-mux-gpio) | 26 | ||||
| -rw-r--r-- | Documentation/i2c/old-module-parameters | 44 | ||||
| -rw-r--r-- | Documentation/i2c/old-module-parameters.rst | 54 | ||||
| -rw-r--r-- | Documentation/i2c/slave-eeprom-backend.rst (renamed from Documentation/i2c/slave-eeprom-backend) | 4 | ||||
| -rw-r--r-- | Documentation/i2c/slave-interface.rst (renamed from Documentation/i2c/slave-interface) | 37 | ||||
| -rw-r--r-- | Documentation/i2c/smbus-protocol.rst (renamed from Documentation/i2c/smbus-protocol) | 181 | ||||
| -rw-r--r-- | Documentation/i2c/summary | 43 | ||||
| -rw-r--r-- | Documentation/i2c/summary.rst | 59 | ||||
| -rw-r--r-- | Documentation/i2c/ten-bit-addresses.rst (renamed from Documentation/i2c/ten-bit-addresses) | 5 | ||||
| -rw-r--r-- | Documentation/i2c/upgrading-clients.rst (renamed from Documentation/i2c/upgrading-clients) | 204 | ||||
| -rw-r--r-- | Documentation/i2c/writing-clients.rst (renamed from Documentation/i2c/writing-clients) | 128 |
50 files changed, 2697 insertions, 987 deletions
diff --git a/Documentation/i2c/busses/i2c-ali1535 b/Documentation/i2c/busses/i2c-ali1535.rst index 5d46342e486a..6941064730dc 100644 --- a/Documentation/i2c/busses/i2c-ali1535 +++ b/Documentation/i2c/busses/i2c-ali1535.rst @@ -1,16 +1,19 @@ +========================= Kernel driver i2c-ali1535 +========================= Supported adapters: * Acer Labs, Inc. ALI 1535 (south bridge) + Datasheet: Now under NDA http://www.ali.com.tw/ Authors: - Frodo Looijaard <frodol@dds.nl>, - Philip Edelbrock <phil@netroedge.com>, - Mark D. Studebaker <mdsxyz123@yahoo.com>, - Dan Eaton <dan.eaton@rocketlogix.com>, - Stephen Rousset<stephen.rousset@rocketlogix.com> + - 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 ----------- diff --git a/Documentation/i2c/busses/i2c-ali1563 b/Documentation/i2c/busses/i2c-ali1563.rst index 41b1a077e4c7..eec32c3ba92a 100644 --- a/Documentation/i2c/busses/i2c-ali1563 +++ b/Documentation/i2c/busses/i2c-ali1563.rst @@ -1,7 +1,10 @@ +========================= Kernel driver i2c-ali1563 +========================= Supported adapters: * Acer Labs, Inc. ALI 1563 (south bridge) + Datasheet: Now under NDA http://www.ali.com.tw/ diff --git a/Documentation/i2c/busses/i2c-ali15x3 b/Documentation/i2c/busses/i2c-ali15x3.rst index 42888d8ac124..d4c1a2a419cb 100644 --- a/Documentation/i2c/busses/i2c-ali15x3 +++ b/Documentation/i2c/busses/i2c-ali15x3.rst @@ -1,20 +1,23 @@ +========================= Kernel driver i2c-ali15x3 +========================= Supported adapters: * Acer Labs, Inc. ALI 1533 and 1543C (south bridge) + Datasheet: Now under NDA http://www.ali.com.tw/ Authors: - Frodo Looijaard <frodol@dds.nl>, - Philip Edelbrock <phil@netroedge.com>, - Mark D. Studebaker <mdsxyz123@yahoo.com> + - 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 + Initialize the base address of the i2c controller Notes @@ -25,7 +28,9 @@ 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' +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). @@ -38,47 +43,53 @@ 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 + 100MHz CPU Front Side bus * "Aladdin V" includes the M1541 Socket 7 North bridge with AGP and 100MHz - CPU Front Side bus + 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 + - 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. + 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: +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. +.. 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). @@ -109,4 +120,3 @@ There may be electrical problems on this board. On the P5A, the W83781D sensor chip is on both the ISA and SMBus. Therefore the SMBus hangs can generally be avoided by accessing the W83781D on the ISA bus only. - diff --git a/Documentation/i2c/busses/i2c-amd-mp2 b/Documentation/i2c/busses/i2c-amd-mp2 deleted file mode 100644 index 6571487171f4..000000000000 --- a/Documentation/i2c/busses/i2c-amd-mp2 +++ /dev/null @@ -1,23 +0,0 @@ -Kernel driver i2c-amd-mp2 - -Supported adapters: - * AMD MP2 PCIe interface - -Datasheet: not publicly available. - -Authors: - Shyam Sundar S K <Shyam-sundar.S-k@amd.com> - Nehal Shah <nehal-bakulchandra.shah@amd.com> - Elie Morisse <syniurge@gmail.com> - -Description ------------ - -The MP2 is an ARM processor programmed as an I2C controller and communicating -with the x86 host through PCI. - -If you see something like this: - -03:00.7 MP2 I2C controller: Advanced Micro Devices, Inc. [AMD] Device 15e6 - -in your 'lspci -v', then this driver is for your device. diff --git a/Documentation/i2c/busses/i2c-amd-mp2.rst b/Documentation/i2c/busses/i2c-amd-mp2.rst new file mode 100644 index 000000000000..ebc2fa899325 --- /dev/null +++ b/Documentation/i2c/busses/i2c-amd-mp2.rst @@ -0,0 +1,25 @@ +========================= +Kernel driver i2c-amd-mp2 +========================= + +Supported adapters: + * AMD MP2 PCIe interface + +Datasheet: not publicly available. + +Authors: + - Shyam Sundar S K <Shyam-sundar.S-k@amd.com> + - Nehal Shah <nehal-bakulchandra.shah@amd.com> + - Elie Morisse <syniurge@gmail.com> + +Description +----------- + +The MP2 is an ARM processor programmed as an I2C controller and communicating +with the x86 host through PCI. + +If you see something like this:: + + 03:00.7 MP2 I2C controller: Advanced Micro Devices, Inc. [AMD] Device 15e6 + +in your ``lspci -v``, then this driver is for your device. diff --git a/Documentation/i2c/busses/i2c-amd756 b/Documentation/i2c/busses/i2c-amd756.rst index 67f30874d0bf..bc93f392a4fc 100644 --- a/Documentation/i2c/busses/i2c-amd756 +++ b/Documentation/i2c/busses/i2c-amd756.rst @@ -1,18 +1,22 @@ +======================== 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> + - Frodo Looijaard <frodol@dds.nl>, + - Philip Edelbrock <phil@netroedge.com> Description ----------- diff --git a/Documentation/i2c/busses/i2c-amd8111 b/Documentation/i2c/busses/i2c-amd8111.rst index 460dd6635fd2..d08bf0a7f0ac 100644 --- a/Documentation/i2c/busses/i2c-amd8111 +++ b/Documentation/i2c/busses/i2c-amd8111.rst @@ -1,4 +1,6 @@ +========================= Kernel driver i2c-adm8111 +========================= Supported adapters: * AMD-8111 SMBus 2.0 PCI interface @@ -13,14 +15,14 @@ Author: Vojtech Pavlik <vojtech@suse.cz> Description ----------- -If you see something like this: +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] + 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. +in your ``lspci -v``, then this driver is for your chipset. Process Call Support -------------------- diff --git a/Documentation/i2c/busses/i2c-diolan-u2c b/Documentation/i2c/busses/i2c-diolan-u2c.rst index 0d6018c316c7..c18cbdcdf73c 100644 --- a/Documentation/i2c/busses/i2c-diolan-u2c +++ b/Documentation/i2c/busses/i2c-diolan-u2c.rst @@ -1,7 +1,10 @@ +============================ Kernel driver i2c-diolan-u2c +============================ Supported adapters: * Diolan U2C-12 I2C-USB adapter + Documentation: http://www.diolan.com/i2c/u2c12.html diff --git a/Documentation/i2c/busses/i2c-i801 b/Documentation/i2c/busses/i2c-i801.rst index f426c13c63a9..b83da0e94184 100644 --- a/Documentation/i2c/busses/i2c-i801 +++ b/Documentation/i2c/busses/i2c-i801.rst @@ -1,4 +1,7 @@ +====================== Kernel driver i2c-i801 +====================== + Supported adapters: * Intel 82801AA and 82801AB (ICH and ICH0 - part of the @@ -39,28 +42,34 @@ Supported adapters: * Intel Comet Lake (PCH) * Intel Elkhart Lake (PCH) * Intel Tiger Lake (PCH) + * Intel Jasper Lake (SOC) + Datasheets: Publicly available at the Intel website On Intel Patsburg and later chipsets, both the normal host SMBus controller and the additional 'Integrated Device Function' controllers are supported. -Authors: - Mark Studebaker <mdsxyz123@yahoo.com> - Jean Delvare <jdelvare@suse.de> +Authors: + - Mark Studebaker <mdsxyz123@yahoo.com> + - Jean Delvare <jdelvare@suse.de> Module Parameters ----------------- * disable_features (bit vector) + Disable selected features normally supported by the device. This makes it possible to work around possible driver or hardware bugs if the feature in question doesn't work as intended for whatever reason. Bit values: + + ==== ========================================= 0x01 disable SMBus PEC 0x02 disable the block buffer 0x08 disable the I2C block read functionality 0x10 don't use interrupts 0x20 disable SMBus Host Notify + ==== ========================================= Description @@ -73,7 +82,7 @@ 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: +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) @@ -139,14 +148,14 @@ and you think there's something interesting on the SMBus (e.g. a hardware monitoring chip), you need to add your board to the list. The motherboard is identified using the subvendor and subdevice IDs of the -host bridge PCI device. Get yours with "lspci -n -v -s 00:00.0": +host bridge PCI device. Get yours with ``lspci -n -v -s 00:00.0``:: -00:00.0 Class 0600: 8086:2570 (rev 02) - Subsystem: 1043:80f2 - Flags: bus master, fast devsel, latency 0 - Memory at fc000000 (32-bit, prefetchable) [size=32M] - Capabilities: [e4] #09 [2106] - Capabilities: [a0] AGP version 3.0 + 00:00.0 Class 0600: 8086:2570 (rev 02) + Subsystem: 1043:80f2 + Flags: bus master, fast devsel, latency 0 + Memory at fc000000 (32-bit, prefetchable) [size=32M] + Capabilities: [e4] #09 [2106] + Capabilities: [a0] AGP version 3.0 Here the host bridge ID is 2570 (82865G/PE/P), the subvendor ID is 1043 (Asus) and the subdevice ID is 80f2 (P4P800-X). You can find the symbolic @@ -165,7 +174,8 @@ kernel. It's very convenient if you just want to check if there's anything interesting on your hidden ICH SMBus. -********************** +---------------------------------------------------------------------------- + The lm_sensors project gratefully acknowledges the support of Texas Instruments in the initial development of this driver. diff --git a/Documentation/i2c/busses/i2c-ismt b/Documentation/i2c/busses/i2c-ismt.rst index 737355822c0b..8e74919a3fdf 100644 --- a/Documentation/i2c/busses/i2c-ismt +++ b/Documentation/i2c/busses/i2c-ismt.rst @@ -1,4 +1,7 @@ +====================== Kernel driver i2c-ismt +====================== + Supported adapters: * Intel S12xx series SOCs @@ -11,16 +14,21 @@ Module Parameters ----------------- * bus_speed (unsigned int) + Allows changing of the bus speed. Normally, the bus speed is set by the BIOS and never needs to be changed. However, some SMBus analyzers are too slow for monitoring the bus during debug, thus the need for this module parameter. Specify the bus speed in kHz. + Available bus frequency settings: - 0 no change - 80 kHz - 100 kHz - 400 kHz - 1000 kHz + + ==== ========= + 0 no change + 80 kHz + 100 kHz + 400 kHz + 1000 kHz + ==== ========= Description @@ -30,7 +38,7 @@ The S12xx series of SOCs have a pair of integrated SMBus 2.0 controllers targeted primarily at the microserver and storage markets. The S12xx series contain a pair of PCI functions. An output of lspci will show -something similar to the following: +something similar to the following:: 00:13.0 System peripheral: Intel Corporation Centerton SMBus 2.0 Controller 0 00:13.1 System peripheral: Intel Corporation Centerton SMBus 2.0 Controller 1 diff --git a/Documentation/i2c/busses/i2c-mlxcpld b/Documentation/i2c/busses/i2c-mlxcpld.rst index 925904aa9b57..9a0b2916aa71 100644 --- a/Documentation/i2c/busses/i2c-mlxcpld +++ b/Documentation/i2c/busses/i2c-mlxcpld.rst @@ -1,9 +1,12 @@ +================== Driver i2c-mlxcpld +================== Author: Michael Shych <michaelsh@mellanox.com> This is the Mellanox I2C controller logic, implemented in Lattice CPLD device. + Device supports: - Master mode. - One physical bus. @@ -20,6 +23,8 @@ The next transaction types are supported: - Write Byte/Block. Registers: + +=============== === ======================================================================= CPBLTY 0x0 - capability reg. Bits [6:5] - transaction length. b01 - 72B is supported, 36B in other case. @@ -49,3 +54,4 @@ DATAx 0xa - 0x54 - 68 bytes data buffer regs. For read transactions address is sent in a separate transaction and specified in the four first bytes (DATA0 - DATA3). Data is read starting from DATA0. +=============== === ======================================================================= diff --git a/Documentation/i2c/busses/i2c-nforce2 b/Documentation/i2c/busses/i2c-nforce2.rst index 9698c396b830..83181445268f 100644 --- a/Documentation/i2c/busses/i2c-nforce2 +++ b/Documentation/i2c/busses/i2c-nforce2.rst @@ -1,10 +1,12 @@ +========================= 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 + * nForce2 MCP 10de:0064 + * nForce2 Ultra 400 MCP 10de:0084 + * nForce3 Pro150 MCP 10de:00D4 + * nForce3 250Gb MCP 10de:00E4 * nForce4 MCP 10de:0052 * nForce4 MCP-04 10de:0034 * nForce MCP51 10de:0264 @@ -16,26 +18,27 @@ Supported adapters: * nForce MCP78S 10de:0752 * nForce MCP79 10de:0AA2 -Datasheet: not publicly available, but seems to be similar to the +Datasheet: + not publicly available, but seems to be similar to the AMD-8111 SMBus 2.0 adapter. Authors: - Hans-Frieder Vogt <hfvogt@gmx.net>, - Thomas Leibold <thomas@plx.com>, - Patrick Dreker <patrick@dreker.de> - + - Hans-Frieder Vogt <hfvogt@gmx.net>, + - Thomas Leibold <thomas@plx.com>, + - Patrick Dreker <patrick@dreker.de> + Description ----------- i2c-nforce2 is a driver for the SMBuses included in the nVidia nForce2 MCP. -If your 'lspci -v' listing shows something like the following, +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> + 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. diff --git a/Documentation/i2c/busses/i2c-nvidia-gpu b/Documentation/i2c/busses/i2c-nvidia-gpu.rst index 31884d2b2eb5..38fb8a4c8756 100644 --- a/Documentation/i2c/busses/i2c-nvidia-gpu +++ b/Documentation/i2c/busses/i2c-nvidia-gpu.rst @@ -1,4 +1,6 @@ +============================ Kernel driver i2c-nvidia-gpu +============================ Datasheet: not publicly available. @@ -11,8 +13,8 @@ Description i2c-nvidia-gpu is a driver for I2C controller included in NVIDIA Turing and later GPUs and it is used to communicate with Type-C controller on GPUs. -If your 'lspci -v' listing shows something like the following, +If your ``lspci -v`` listing shows something like the following:: -01:00.3 Serial bus controller [0c80]: NVIDIA Corporation Device 1ad9 (rev a1) + 01:00.3 Serial bus controller [0c80]: NVIDIA Corporation Device 1ad9 (rev a1) then this driver should support the I2C controller of your GPU. diff --git a/Documentation/i2c/busses/i2c-ocores b/Documentation/i2c/busses/i2c-ocores.rst index 9caaf7df1b2f..f5e175f2a2a6 100644 --- a/Documentation/i2c/busses/i2c-ocores +++ b/Documentation/i2c/busses/i2c-ocores.rst @@ -1,4 +1,6 @@ +======================== Kernel driver i2c-ocores +======================== Supported adapters: * OpenCores.org I2C controller by Richard Herveille (see datasheet link) @@ -23,9 +25,9 @@ distance between registers and the input clock speed. There is also a possibility to attach a list of i2c_board_info which the i2c-ocores driver will add to the bus upon creation. -E.G. something like: +E.G. something like:: -static struct resource ocores_resources[] = { + static struct resource ocores_resources[] = { [0] = { .start = MYI2C_BASEADDR, .end = MYI2C_BASEADDR + 8, @@ -36,10 +38,10 @@ static struct resource ocores_resources[] = { .end = MYI2C_IRQ, .flags = IORESOURCE_IRQ, }, -}; + }; -/* optional board info */ -struct i2c_board_info ocores_i2c_board_info[] = { + /* optional board info */ + struct i2c_board_info ocores_i2c_board_info[] = { { I2C_BOARD_INFO("tsc2003", 0x48), .platform_data = &tsc2003_platform_data, @@ -49,20 +51,20 @@ struct i2c_board_info ocores_i2c_board_info[] = { I2C_BOARD_INFO("adv7180", 0x42 >> 1), .irq = ADV_IRQ } -}; + }; -static struct ocores_i2c_platform_data myi2c_data = { + static struct ocores_i2c_platform_data myi2c_data = { .regstep = 2, /* two bytes between registers */ .clock_khz = 50000, /* input clock of 50MHz */ .devices = ocores_i2c_board_info, /* optional table of devices */ .num_devices = ARRAY_SIZE(ocores_i2c_board_info), /* table size */ -}; + }; -static struct platform_device myi2c = { + static struct platform_device myi2c = { .name = "ocores-i2c", .dev = { .platform_data = &myi2c_data, }, .num_resources = ARRAY_SIZE(ocores_resources), .resource = ocores_resources, -}; + }; diff --git a/Documentation/i2c/busses/i2c-parport b/Documentation/i2c/busses/i2c-parport deleted file mode 100644 index c3dbb3bfd814..000000000000 --- a/Documentation/i2c/busses/i2c-parport +++ /dev/null @@ -1,178 +0,0 @@ -Kernel driver i2c-parport - -Author: Jean Delvare <jdelvare@suse.de> - -This is a unified driver for several i2c-over-parallel-port adapters, -such as the ones made by Philips, Velleman or ELV. This driver is -meant as a replacement for the older, individual drivers: - * i2c-philips-par - * i2c-elv - * i2c-velleman - * video/i2c-parport (NOT the same as this one, dedicated to home brew - teletext adapters) - -It currently supports the following devices: - * (type=0) Philips adapter - * (type=1) home brew teletext adapter - * (type=2) Velleman K8000 adapter - * (type=3) ELV adapter - * (type=4) Analog Devices ADM1032 evaluation board - * (type=5) Analog Devices evaluation boards: ADM1025, ADM1030, ADM1031 - * (type=6) Barco LPT->DVI (K5800236) adapter - * (type=7) One For All JP1 parallel port adapter - * (type=8) VCT-jig - -These devices use different pinout configurations, so you have to tell -the driver what you have, using the type module parameter. There is no -way to autodetect the devices. Support for different pinout configurations -can be easily added when needed. - -Earlier kernels defaulted to type=0 (Philips). But now, if the type -parameter is missing, the driver will simply fail to initialize. - -SMBus alert support is available on adapters which have this line properly -connected to the parallel port's interrupt pin. - - -Building your own adapter -------------------------- - -If you want to build you own i2c-over-parallel-port adapter, here is -a sample electronics schema (credits go to Sylvain Munaut): - -Device PC -Side ___________________Vdd (+) Side - | | | - --- --- --- - | | | | | | - |R| |R| |R| - | | | | | | - --- --- --- - | | | - | | /| | -SCL ----------x--------o |-----------x------------------- pin 2 - | \| | | - | | | - | |\ | | -SDA ----------x----x---| o---x--------------------------- pin 13 - | |/ | - | | - | /| | - ---------o |----------------x-------------- pin 3 - \| | | - | | - --- --- - | | | | - |R| |R| - | | | | - --- --- - | | - ### ### - GND GND - -Remarks: - - This is the exact pinout and electronics used on the Analog Devices - evaluation boards. - /| - - All inverters -o |- must be 74HC05, they must be open collector output. - \| - - All resitors are 10k. - - Pins 18-25 of the parallel port connected to GND. - - Pins 4-9 (D2-D7) could be used as VDD is the driver drives them high. - The ADM1032 evaluation board uses D4-D7. Beware that the amount of - current you can draw from the parallel port is limited. Also note that - all connected lines MUST BE driven at the same state, else you'll short - circuit the output buffers! So plugging the I2C adapter after loading - the i2c-parport module might be a good safety since data line state - prior to init may be unknown. - - This is 5V! - - Obviously you cannot read SCL (so it's not really standard-compliant). - Pretty easy to add, just copy the SDA part and use another input pin. - That would give (ELV compatible pinout): - - -Device PC -Side ______________________________Vdd (+) Side - | | | | - --- --- --- --- - | | | | | | | | - |R| |R| |R| |R| - | | | | | | | | - --- --- --- --- - | | | | - | | |\ | | -SCL ----------x--------x--| o---x------------------------ pin 15 - | | |/ | - | | | - | | /| | - | ---o |-------------x-------------- pin 2 - | \| | | - | | | - | | | - | |\ | | -SDA ---------------x---x--| o--------x------------------- pin 10 - | |/ | - | | - | /| | - ---o |------------------x--------- pin 3 - \| | | - | | - --- --- - | | | | - |R| |R| - | | | | - --- --- - | | - ### ### - GND GND - - -If possible, you should use the same pinout configuration as existing -adapters do, so you won't even have to change the code. - - -Similar (but different) drivers -------------------------------- - -This driver is NOT the same as the i2c-pport driver found in the i2c -package. The i2c-pport driver makes use of modern parallel port features so -that you don't need additional electronics. It has other restrictions -however, and was not ported to Linux 2.6 (yet). - -This driver is also NOT the same as the i2c-pcf-epp driver found in the -lm_sensors package. The i2c-pcf-epp driver doesn't use the parallel port as -an I2C bus directly. Instead, it uses it to control an external I2C bus -master. That driver was not ported to Linux 2.6 (yet) either. - - -Legacy documentation for Velleman adapter ------------------------------------------ - -Useful links: -Velleman http://www.velleman.be/ -Velleman K8000 Howto http://howto.htlw16.ac.at/k8000-howto.html - -The project has lead to new libs for the Velleman K8000 and K8005: - LIBK8000 v1.99.1 and LIBK8005 v0.21 -With these libs, you can control the K8000 interface card and the K8005 -stepper motor card with the simple commands which are in the original -Velleman software, like SetIOchannel, ReadADchannel, SendStepCCWFull and -many more, using /dev/velleman. - http://home.wanadoo.nl/hihihi/libk8000.htm - http://home.wanadoo.nl/hihihi/libk8005.htm - http://struyve.mine.nu:8080/index.php?block=k8000 - http://sourceforge.net/projects/libk8005/ - - -One For All JP1 parallel port adapter -------------------------------------- - -The JP1 project revolves around a set of remote controls which expose -the I2C bus their internal configuration EEPROM lives on via a 6 pin -jumper in the battery compartment. More details can be found at: - -http://www.hifi-remote.com/jp1/ - -Details of the simple parallel port hardware can be found at: - -http://www.hifi-remote.com/jp1/hardware.shtml diff --git a/Documentation/i2c/busses/i2c-parport-light b/Documentation/i2c/busses/i2c-parport-light deleted file mode 100644 index 7071b8ba0af4..000000000000 --- a/Documentation/i2c/busses/i2c-parport-light +++ /dev/null @@ -1,22 +0,0 @@ -Kernel driver i2c-parport-light - -Author: Jean Delvare <jdelvare@suse.de> - -This driver is a light version of i2c-parport. It doesn't depend -on the parport driver, and uses direct I/O access instead. This might be -preferred on embedded systems where wasting memory for the clean but heavy -parport handling is not an option. The drawback is a reduced portability -and the impossibility to daisy-chain other parallel port devices. - -Please see i2c-parport for documentation. - -Module parameters: - -* type: type of adapter (see i2c-parport or modinfo) - -* base: base I/O address - Default is 0x378 which is fairly common for parallel ports, at least on PC. - -* irq: optional IRQ - This must be passed if you want SMBus alert support, assuming your adapter - actually supports this. diff --git a/Documentation/i2c/busses/i2c-parport.rst b/Documentation/i2c/busses/i2c-parport.rst new file mode 100644 index 000000000000..a9b4e8133700 --- /dev/null +++ b/Documentation/i2c/busses/i2c-parport.rst @@ -0,0 +1,190 @@ +========================= +Kernel driver i2c-parport +========================= + +Author: Jean Delvare <jdelvare@suse.de> + +This is a unified driver for several i2c-over-parallel-port adapters, +such as the ones made by Philips, Velleman or ELV. This driver is +meant as a replacement for the older, individual drivers: + + * i2c-philips-par + * i2c-elv + * i2c-velleman + * video/i2c-parport + (NOT the same as this one, dedicated to home brew teletext adapters) + +It currently supports the following devices: + + * (type=0) Philips adapter + * (type=1) home brew teletext adapter + * (type=2) Velleman K8000 adapter + * (type=3) ELV adapter + * (type=4) Analog Devices ADM1032 evaluation board + * (type=5) Analog Devices evaluation boards: ADM1025, ADM1030, ADM1031 + * (type=6) Barco LPT->DVI (K5800236) adapter + * (type=7) One For All JP1 parallel port adapter + * (type=8) VCT-jig + +These devices use different pinout configurations, so you have to tell +the driver what you have, using the type module parameter. There is no +way to autodetect the devices. Support for different pinout configurations +can be easily added when needed. + +Earlier kernels defaulted to type=0 (Philips). But now, if the type +parameter is missing, the driver will simply fail to initialize. + +SMBus alert support is available on adapters which have this line properly +connected to the parallel port's interrupt pin. + + +Building your own adapter +------------------------- + +If you want to build you own i2c-over-parallel-port adapter, here is +a sample electronics schema (credits go to Sylvain Munaut):: + + Device PC + Side ___________________Vdd (+) Side + | | | + --- --- --- + | | | | | | + |R| |R| |R| + | | | | | | + --- --- --- + | | | + | | /| | + SCL ----------x--------o |-----------x------------------- pin 2 + | \| | | + | | | + | |\ | | + SDA ----------x----x---| o---x--------------------------- pin 13 + | |/ | + | | + | /| | + ---------o |----------------x-------------- pin 3 + \| | | + | | + --- --- + | | | | + |R| |R| + | | | | + --- --- + | | + ### ### + GND GND + +Remarks: + - This is the exact pinout and electronics used on the Analog Devices + evaluation boards. + - All inverters:: + + /| + -o |- + \| + + must be 74HC05, they must be open collector output. + - All resitors are 10k. + - Pins 18-25 of the parallel port connected to GND. + - Pins 4-9 (D2-D7) could be used as VDD is the driver drives them high. + The ADM1032 evaluation board uses D4-D7. Beware that the amount of + current you can draw from the parallel port is limited. Also note that + all connected lines MUST BE driven at the same state, else you'll short + circuit the output buffers! So plugging the I2C adapter after loading + the i2c-parport module might be a good safety since data line state + prior to init may be unknown. + - This is 5V! + - Obviously you cannot read SCL (so it's not really standard-compliant). + Pretty easy to add, just copy the SDA part and use another input pin. + That would give (ELV compatible pinout):: + + + Device PC + Side ______________________________Vdd (+) Side + | | | | + --- --- --- --- + | | | | | | | | + |R| |R| |R| |R| + | | | | | | | | + --- --- --- --- + | | | | + | | |\ | | + SCL ----------x--------x--| o---x------------------------ pin 15 + | | |/ | + | | | + | | /| | + | ---o |-------------x-------------- pin 2 + | \| | | + | | | + | | | + | |\ | | + SDA ---------------x---x--| o--------x------------------- pin 10 + | |/ | + | | + | /| | + ---o |------------------x--------- pin 3 + \| | | + | | + --- --- + | | | | + |R| |R| + | | | | + --- --- + | | + ### ### + GND GND + + +If possible, you should use the same pinout configuration as existing +adapters do, so you won't even have to change the code. + + +Similar (but different) drivers +------------------------------- + +This driver is NOT the same as the i2c-pport driver found in the i2c +package. The i2c-pport driver makes use of modern parallel port features so +that you don't need additional electronics. It has other restrictions +however, and was not ported to Linux 2.6 (yet). + +This driver is also NOT the same as the i2c-pcf-epp driver found in the +lm_sensors package. The i2c-pcf-epp driver doesn't use the parallel port as +an I2C bus directly. Instead, it uses it to control an external I2C bus +master. That driver was not ported to Linux 2.6 (yet) either. + + +Legacy documentation for Velleman adapter +----------------------------------------- + +Useful links: + +- Velleman http://www.velleman.be/ +- Velleman K8000 Howto http://howto.htlw16.ac.at/k8000-howto.html + +The project has lead to new libs for the Velleman K8000 and K8005: + + LIBK8000 v1.99.1 and LIBK8005 v0.21 + +With these libs, you can control the K8000 interface card and the K8005 +stepper motor card with the simple commands which are in the original +Velleman software, like SetIOchannel, ReadADchannel, SendStepCCWFull and +many more, using /dev/velleman. + + - http://home.wanadoo.nl/hihihi/libk8000.htm + - http://home.wanadoo.nl/hihihi/libk8005.htm + - http://struyve.mine.nu:8080/index.php?block=k8000 + - http://sourceforge.net/projects/libk8005/ + + +One For All JP1 parallel port adapter +------------------------------------- + +The JP1 project revolves around a set of remote controls which expose +the I2C bus their internal configuration EEPROM lives on via a 6 pin +jumper in the battery compartment. More details can be found at: + +http://www.hifi-remote.com/jp1/ + +Details of the simple parallel port hardware can be found at: + +http://www.hifi-remote.com/jp1/hardware.shtml diff --git a/Documentation/i2c/busses/i2c-pca-isa b/Documentation/i2c/busses/i2c-pca-isa.rst index b044e5265488..a254010c8055 100644 --- a/Documentation/i2c/busses/i2c-pca-isa +++ b/Documentation/i2c/busses/i2c-pca-isa.rst @@ -1,6 +1,9 @@ +========================= Kernel driver i2c-pca-isa +========================= Supported adapters: + This driver supports ISA boards using the Philips PCA 9564 Parallel bus to I2C bus controller @@ -10,11 +13,11 @@ Module Parameters ----------------- * base int - I/O base address + I/O base address * irq int - IRQ interrupt + IRQ interrupt * clock int - Clock rate as described in table 1 of PCA9564 datasheet + Clock rate as described in table 1 of PCA9564 datasheet Description ----------- diff --git a/Documentation/i2c/busses/i2c-piix4 b/Documentation/i2c/busses/i2c-piix4.rst index 2703bc3acad0..cc9000259223 100644 --- a/Documentation/i2c/busses/i2c-piix4 +++ b/Documentation/i2c/busses/i2c-piix4.rst @@ -1,4 +1,6 @@ +======================= Kernel driver i2c-piix4 +======================= Supported adapters: * Intel 82371AB PIIX4 and PIIX4E @@ -20,9 +22,9 @@ Supported adapters: * 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> +Authors: + - Frodo Looijaard <frodol@dds.nl> + - Philip Edelbrock <phil@netroedge.com> Module Parameters @@ -39,16 +41,16 @@ 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 +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: +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 + 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 @@ -91,7 +93,7 @@ the SMI mode. device is located at 00:0f.0. 2) Now you just need to change the value in 0xD2 register. Get it first with command: lspci -xxx -s 00:0f.0 - If the value is 0x3 then you need to change it to 0x1 + If the value is 0x3 then you need to change it to 0x1: setpci -s 00:0f.0 d2.b=1 Please note that you don't need to do that in all cases, just when the SMBus is diff --git a/Documentation/i2c/busses/i2c-sis5595 b/Documentation/i2c/busses/i2c-sis5595.rst index ecd21fb49a8f..b85630c84a96 100644 --- a/Documentation/i2c/busses/i2c-sis5595 +++ b/Documentation/i2c/busses/i2c-sis5595.rst @@ -1,9 +1,11 @@ +========================= Kernel driver i2c-sis5595 +========================= Authors: - Frodo Looijaard <frodol@dds.nl>, - Mark D. Studebaker <mdsxyz123@yahoo.com>, - Philip Edelbrock <phil@netroedge.com> + - Frodo Looijaard <frodol@dds.nl>, + - Mark D. Studebaker <mdsxyz123@yahoo.com>, + - Philip Edelbrock <phil@netroedge.com> Supported adapters: * Silicon Integrated Systems Corp. SiS5595 Southbridge @@ -11,14 +13,19 @@ Supported adapters: 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 @@ -36,15 +43,18 @@ Note: all have mfr. ID 0x1039. 735 0008 0735 745 0008 0745 746 0008 0746 + ============= ====== ================ Module Parameters ----------------- -* force_addr=0xaddr Set the I/O base address. Useful for boards +================== ===================================================== +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 ----------- @@ -56,4 +66,3 @@ WARNING: If you are trying to access the integrated sensors on the SiS5595 chip, you want the sis5595 driver for those, not this driver. This driver is a BUS driver, not a CHIP driver. A BUS driver is used by other CHIP drivers to access chips on the bus. - diff --git a/Documentation/i2c/busses/i2c-sis630 b/Documentation/i2c/busses/i2c-sis630 deleted file mode 100644 index ee7943631074..000000000000 --- a/Documentation/i2c/busses/i2c-sis630 +++ /dev/null @@ -1,58 +0,0 @@ -Kernel driver i2c-sis630 - -Supported adapters: - * Silicon Integrated Systems Corp (SiS) - 630 chipset (Datasheet: available at http://www.sfr-fresh.com/linux) - 730 chipset - 964 chipset - * Possible other SiS chipsets ? - -Author: Alexander Malysh <amalysh@web.de> - Amaury Decrême <amaury.decreme@gmail.com> - SiS964 support - -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). - SIS630/730 chip only. - - -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 - -or like this: - -00:00.0 Host bridge: Silicon Integrated Systems [SiS] 760/M760 Host (rev 02) -00:02.0 ISA bridge: Silicon Integrated Systems [SiS] SiS964 [MuTIOL Media IO] - LPC Controller (rev 36) - -in your 'lspci' output , then this driver is for your chipset. - -Thank You ---------- -Philip Edelbrock <phil@netroedge.com> -- testing SiS730 support -Mark M. Hoffman <mhoffman@lightlink.com> -- bug fixes - -To anyone else which I forgot here ;), thanks! - diff --git a/Documentation/i2c/busses/i2c-sis630.rst b/Documentation/i2c/busses/i2c-sis630.rst new file mode 100644 index 000000000000..9fcd74b18781 --- /dev/null +++ b/Documentation/i2c/busses/i2c-sis630.rst @@ -0,0 +1,63 @@ +======================== +Kernel driver i2c-sis630 +======================== + +Supported adapters: + * Silicon Integrated Systems Corp (SiS) + 630 chipset (Datasheet: available at http://www.sfr-fresh.com/linux) + 730 chipset + 964 chipset + * Possible other SiS chipsets ? + +Author: + - Alexander Malysh <amalysh@web.de> + - Amaury Decrême <amaury.decreme@gmail.com> - SiS964 support + +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). + SIS630/730 chip only. +================== ===================================================== + + +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 + +or like this:: + + 00:00.0 Host bridge: Silicon Integrated Systems [SiS] 760/M760 Host (rev 02) + 00:02.0 ISA bridge: Silicon Integrated Systems [SiS] SiS964 [MuTIOL Media IO] + LPC Controller (rev 36) + +in your ``lspci`` output , then this driver is for your chipset. + +Thank You +--------- +Philip Edelbrock <phil@netroedge.com> +- testing SiS730 support +Mark M. Hoffman <mhoffman@lightlink.com> +- bug fixes + +To anyone else which I forgot here ;), thanks! diff --git a/Documentation/i2c/busses/i2c-sis96x b/Documentation/i2c/busses/i2c-sis96x.rst index 0b979f3252a4..437cc1d89588 100644 --- a/Documentation/i2c/busses/i2c-sis96x +++ b/Documentation/i2c/busses/i2c-sis96x.rst @@ -1,13 +1,18 @@ +======================== 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) + 961, 962, 963(L) Author: Mark M. Hoffman <mhoffman@lightlink.com> @@ -21,17 +26,17 @@ 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: +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 + 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... +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 + 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) @@ -50,7 +55,7 @@ TO DOs ------ * The driver does not support SMBus block reads/writes; I may add them if a -scenario is found where they're needed. + scenario is found where they're needed. Thank You @@ -58,16 +63,20 @@ Thank You Mark D. Studebaker <mdsxyz123@yahoo.com> - design hints and bug fixes + Alexander Maylsh <amalysh@web.de> - ditto, plus an important datasheet... almost the one I really wanted + Hans-Günter Lütke Uphues <hg_lu@t-online.de> - patch for SiS735 + Robert Zwerus <arzie@dds.nl> - testing for SiS645DX + Kianusch Sayah Karadji <kianusch@sk-tech.net> - patch for SiS645DX/962 + Ken Healy - patch for SiS655 To anyone else who has written w/ feedback, thanks! - diff --git a/Documentation/i2c/busses/i2c-taos-evm b/Documentation/i2c/busses/i2c-taos-evm.rst index 60299555dcf0..f342e313ee3d 100644 --- a/Documentation/i2c/busses/i2c-taos-evm +++ b/Documentation/i2c/busses/i2c-taos-evm.rst @@ -1,4 +1,6 @@ +========================== Kernel driver i2c-taos-evm +========================== Author: Jean Delvare <jdelvare@suse.de> @@ -23,10 +25,10 @@ Using this driver In order to use this driver, you'll need the serport driver, and the inputattach tool, which is part of the input-utils package. The following commands will tell the kernel that you have a TAOS EVM on the first -serial port: +serial port:: -# modprobe serport -# inputattach --taos-evm /dev/ttyS0 + # modprobe serport + # inputattach --taos-evm /dev/ttyS0 Technical details diff --git a/Documentation/i2c/busses/i2c-via b/Documentation/i2c/busses/i2c-via.rst index 343870661ac3..846aa17d80a2 100644 --- a/Documentation/i2c/busses/i2c-via +++ b/Documentation/i2c/busses/i2c-via.rst @@ -1,4 +1,6 @@ +===================== Kernel driver i2c-via +===================== Supported adapters: * VIA Technologies, InC. VT82C586B @@ -12,23 +14,27 @@ 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 + - MVP3, VP3, VP2/97, VPX/97 - others with South bridge VT82C586B -Your lspci listing must show this : +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. +Problems? +--------- - Q: No error messages, but still i2c doesn't seem to work. + Q: + You have VT82C586B on the motherboard, but not in the listing. - A: This can happen. This driver uses the pins VIA recommends in their + A: + Go to your BIOS setup, section PCI devices or similar. + Turn USB support on, and try again. + + Q: + No error messages, but still i2c doesn't seem to work. + + A: + This can happen. This driver uses the pins VIA recommends in their datasheets, but there are several ways the motherboard manufacturer can actually wire the lines. - diff --git a/Documentation/i2c/busses/i2c-viapro b/Documentation/i2c/busses/i2c-viapro.rst index ab64ce21c254..1762f0cf93d0 100644 --- a/Documentation/i2c/busses/i2c-viapro +++ b/Documentation/i2c/busses/i2c-viapro.rst @@ -1,4 +1,6 @@ +======================== Kernel driver i2c-viapro +======================== Supported adapters: * VIA Technologies, Inc. VT82C596A/B @@ -26,9 +28,9 @@ Supported adapters: Datasheet: available on http://linux.via.com.tw Authors: - Kyösti Mälkki <kmalkki@cc.hut.fi>, - Mark D. Studebaker <mdsxyz123@yahoo.com>, - Jean Delvare <jdelvare@suse.de> + - Kyösti Mälkki <kmalkki@cc.hut.fi>, + - Mark D. Studebaker <mdsxyz123@yahoo.com>, + - Jean Delvare <jdelvare@suse.de> Module Parameters ----------------- @@ -44,8 +46,9 @@ Description i2c-viapro is a true SMBus host driver for motherboards with one of the supported VIA south bridges. -Your lspci -n listing must show one of these : +Your ``lspci -n`` listing must show one of these : + ================ ====================== device 1106:3050 (VT82C596A function 3) device 1106:3051 (VT82C596B function 3) device 1106:3057 (VT82C686 function 4) @@ -61,6 +64,7 @@ Your lspci -n listing must show one of these : device 1106:8353 (VX800/VX820) device 1106:8409 (VX855/VX875) device 1106:8410 (VX900) + ================ ====================== If none of these show up, you should look in the BIOS for settings like enable ACPI / SMBus or even USB. diff --git a/Documentation/i2c/busses/index.rst b/Documentation/i2c/busses/index.rst new file mode 100644 index 000000000000..5e4077b08d86 --- /dev/null +++ b/Documentation/i2c/busses/index.rst @@ -0,0 +1,32 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=============== +I2C Bus Drivers +=============== + +.. toctree:: + :maxdepth: 1 + + i2c-ali1535 + i2c-ali1563 + i2c-ali15x3 + i2c-amd756 + i2c-amd8111 + i2c-amd-mp2 + i2c-diolan-u2c + i2c-i801 + i2c-ismt + i2c-mlxcpld + i2c-nforce2 + i2c-nvidia-gpu + i2c-ocores + i2c-parport + i2c-pca-isa + i2c-piix4 + i2c-sis5595 + i2c-sis630 + i2c-sis96x + i2c-taos-evm + i2c-viapro + i2c-via + scx200_acb diff --git a/Documentation/i2c/busses/scx200_acb b/Documentation/i2c/busses/scx200_acb.rst index ce83c871fe95..8dc7c352508c 100644 --- a/Documentation/i2c/busses/scx200_acb +++ b/Documentation/i2c/busses/scx200_acb.rst @@ -1,4 +1,6 @@ +======================== Kernel driver scx200_acb +======================== Author: Christer Weinigel <wingel@nano-system.com> @@ -25,8 +27,11 @@ Device-specific notes The SC1100 WRAP boards are known to use base addresses 0x810 and 0x820. If the scx200_acb driver is built into the kernel, add the following -parameter to your boot command line: +parameter to your boot command line:: + scx200_acb.base=0x810,0x820 + If the scx200_acb driver is built as a module, add the following line to -a configuration file in /etc/modprobe.d/ instead: +a configuration file in /etc/modprobe.d/ instead:: + options scx200_acb base=0x810,0x820 diff --git a/Documentation/i2c/dev-interface b/Documentation/i2c/dev-interface.rst index fbed645ccd75..bdb247f2f11a 100644 --- a/Documentation/i2c/dev-interface +++ b/Documentation/i2c/dev-interface.rst @@ -1,24 +1,28 @@ -Usually, i2c devices are controlled by a kernel driver. But it is also +============================================ +Implementing I2C device drivers in userspace +============================================ + +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 +Each registered I2C adapter gets a number, counting from 0. You can examine /sys/class/i2c-dev/ to see what number corresponds to which adapter. Alternatively, you can run "i2cdetect -l" to obtain a formatted list of all -i2c adapters present on your system at a given time. i2cdetect is part of +I2C adapters present on your system at a given time. i2cdetect is part of the i2c-tools package. I2C device files are character device files with major device number 89 and a minor device number corresponding to the number assigned as explained above. They should be called "i2c-%d" (i2c-0, i2c-1, ..., -i2c-10, ...). All 256 minor device numbers are reserved for i2c. +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. -First, you need to include these two headers: +So let's say you want to access an I2C adapter from a C program. +First, you need to include these two headers:: #include <linux/i2c-dev.h> #include <i2c/smbus.h> @@ -28,7 +32,7 @@ inspect /sys/class/i2c-dev/ or run "i2cdetect -l" to decide this. Adapter numbers are assigned somewhat dynamically, so you can not assume much about them. They can even change from one boot to the next. -Next thing, open the device file, as follows: +Next thing, open the device file, as follows:: int file; int adapter_nr = 2; /* probably dynamically determined */ @@ -42,7 +46,7 @@ Next thing, open the device file, as follows: } When you have opened the device, you must specify with what device -address you want to communicate: +address you want to communicate:: int addr = 0x40; /* The I2C address */ @@ -53,7 +57,7 @@ address you want to communicate: 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. +the device supports them. Both are illustrated below:: __u8 reg = 0x10; /* Device register to access */ __s32 res; @@ -62,7 +66,7 @@ the device supports them. Both are illustrated below. /* Using SMBus commands */ res = i2c_smbus_read_word_data(file, reg); if (res < 0) { - /* ERROR HANDLING: i2c transaction failed */ + /* ERROR HANDLING: I2C transaction failed */ } else { /* res contains the read word */ } @@ -75,12 +79,12 @@ the device supports them. Both are illustrated below. buf[1] = 0x43; buf[2] = 0x65; if (write(file, buf, 3) != 3) { - /* ERROR HANDLING: i2c transaction failed */ + /* 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 */ + /* ERROR HANDLING: I2C transaction failed */ } else { /* buf[0] contains the read byte */ } @@ -100,35 +104,35 @@ Full interface description The following IOCTLs are defined: -ioctl(file, I2C_SLAVE, long addr) +``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) +``ioctl(file, I2C_TENBIT, long select)`` Selects ten bit addresses if select not equals 0, selects normal 7 bit addresses if select equals 0. Default 0. This request is only valid if the adapter has I2C_FUNC_10BIT_ADDR. -ioctl(file, I2C_PEC, long select) +``ioctl(file, I2C_PEC, long select)`` Selects SMBus PEC (packet error checking) generation and verification if select not equals 0, disables if select equals 0. Default 0. Used only for SMBus transactions. This request only has an effect if the the adapter has I2C_FUNC_SMBUS_PEC; it is still safe if not, it just doesn't have any effect. -ioctl(file, I2C_FUNCS, unsigned long *funcs) - Gets the adapter functionality and puts it in *funcs. +``ioctl(file, I2C_FUNCS, unsigned long *funcs)`` + Gets the adapter functionality and puts it in ``*funcs``. -ioctl(file, I2C_RDWR, struct i2c_rdwr_ioctl_data *msgset) +``ioctl(file, I2C_RDWR, struct i2c_rdwr_ioctl_data *msgset)`` Do combined read/write transaction without stop in between. Only valid if the adapter has I2C_FUNC_I2C. The argument is - a pointer to a + a pointer to a:: - struct i2c_rdwr_ioctl_data { + struct i2c_rdwr_ioctl_data { struct i2c_msg *msgs; /* ptr to array of simple messages */ int nmsgs; /* number of messages to exchange */ - } + } The msgs[] themselves contain further pointers into data buffers. The function will write or read data to or from that buffers depending @@ -136,16 +140,17 @@ ioctl(file, I2C_RDWR, struct i2c_rdwr_ioctl_data *msgset) The slave address and whether to use ten bit address mode has to be set in each message, overriding the values set with the above ioctl's. -ioctl(file, I2C_SMBUS, struct i2c_smbus_ioctl_data *args) - If possible, use the provided i2c_smbus_* methods described below instead +``ioctl(file, I2C_SMBUS, struct i2c_smbus_ioctl_data *args)`` + If possible, use the provided ``i2c_smbus_*`` methods described below instead of issuing direct ioctls. -You can do plain i2c transactions by using read(2) and write(2) calls. +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: +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); @@ -157,6 +162,7 @@ for details) through the following functions: __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 @@ -174,39 +180,39 @@ Implementation details For the interested, here's the code flow which happens inside the kernel when you use the /dev interface to I2C: -1* Your program opens /dev/i2c-N and calls ioctl() on it, as described in -section "C example" above. - -2* These open() and ioctl() calls are handled by the i2c-dev kernel -driver: see i2c-dev.c:i2cdev_open() and i2c-dev.c:i2cdev_ioctl(), -respectively. You can think of i2c-dev as a generic I2C chip driver -that can be programmed from user-space. - -3* Some ioctl() calls are for administrative tasks and are handled by -i2c-dev directly. Examples include I2C_SLAVE (set the address of the -device you want to access) and I2C_PEC (enable or disable SMBus error -checking on future transactions.) - -4* Other ioctl() calls are converted to in-kernel function calls by -i2c-dev. Examples include I2C_FUNCS, which queries the I2C adapter -functionality using i2c.h:i2c_get_functionality(), and I2C_SMBUS, which -performs an SMBus transaction using i2c-core-smbus.c:i2c_smbus_xfer(). - -The i2c-dev driver is responsible for checking all the parameters that -come from user-space for validity. After this point, there is no -difference between these calls that came from user-space through i2c-dev -and calls that would have been performed by kernel I2C chip drivers -directly. This means that I2C bus drivers don't need to implement -anything special to support access from user-space. - -5* These i2c.h functions are wrappers to the actual implementation of -your I2C bus driver. Each adapter must declare callback functions -implementing these standard calls. i2c.h:i2c_get_functionality() calls -i2c_adapter.algo->functionality(), while -i2c-core-smbus.c:i2c_smbus_xfer() calls either -adapter.algo->smbus_xfer() if it is implemented, or if not, -i2c-core-smbus.c:i2c_smbus_xfer_emulated() which in turn calls -i2c_adapter.algo->master_xfer(). +1) Your program opens /dev/i2c-N and calls ioctl() on it, as described in + section "C example" above. + +2) These open() and ioctl() calls are handled by the i2c-dev kernel + driver: see i2c-dev.c:i2cdev_open() and i2c-dev.c:i2cdev_ioctl(), + respectively. You can think of i2c-dev as a generic I2C chip driver + that can be programmed from user-space. + +3) Some ioctl() calls are for administrative tasks and are handled by + i2c-dev directly. Examples include I2C_SLAVE (set the address of the + device you want to access) and I2C_PEC (enable or disable SMBus error + checking on future transactions.) + +4) Other ioctl() calls are converted to in-kernel function calls by + i2c-dev. Examples include I2C_FUNCS, which queries the I2C adapter + functionality using i2c.h:i2c_get_functionality(), and I2C_SMBUS, which + performs an SMBus transaction using i2c-core-smbus.c:i2c_smbus_xfer(). + + The i2c-dev driver is responsible for checking all the parameters that + come from user-space for validity. After this point, there is no + difference between these calls that came from user-space through i2c-dev + and calls that would have been performed by kernel I2C chip drivers + directly. This means that I2C bus drivers don't need to implement + anything special to support access from user-space. + +5) These i2c.h functions are wrappers to the actual implementation of + your I2C bus driver. Each adapter must declare callback functions + implementing these standard calls. i2c.h:i2c_get_functionality() calls + i2c_adapter.algo->functionality(), while + i2c-core-smbus.c:i2c_smbus_xfer() calls either + adapter.algo->smbus_xfer() if it is implemented, or if not, + i2c-core-smbus.c:i2c_smbus_xfer_emulated() which in turn calls + i2c_adapter.algo->master_xfer(). After your I2C bus driver has processed these requests, execution runs up the call chain, with almost no processing done, except by i2c-dev to diff --git a/Documentation/i2c/DMA-considerations b/Documentation/i2c/dma-considerations.rst index 203002054120..142d52ce9ebb 100644 --- a/Documentation/i2c/DMA-considerations +++ b/Documentation/i2c/dma-considerations.rst @@ -2,7 +2,7 @@ Linux I2C and DMA ================= -Given that i2c is a low-speed bus, over which the majority of messages +Given that I2C is a low-speed bus, over which the majority of messages transferred are small, it is not considered a prime user of DMA access. At this time of writing, only 10% of I2C bus master drivers have DMA support implemented. And the vast majority of transactions are so small that setting up diff --git a/Documentation/i2c/fault-codes b/Documentation/i2c/fault-codes.rst index 0cee0fc545b4..80b14e718b52 100644 --- a/Documentation/i2c/fault-codes +++ b/Documentation/i2c/fault-codes.rst @@ -1,3 +1,7 @@ +===================== +I2C/SMBUS Fault Codes +===================== + This is a summary of the most important conventions for use of fault codes in the I2C/SMBus stack. @@ -125,4 +129,3 @@ ETIMEDOUT when a slave stretches clocks too far. I2C has no such timeouts, but it's normal for I2C adapters to impose some arbitrary limits (much longer than SMBus!) too. - diff --git a/Documentation/i2c/functionality b/Documentation/i2c/functionality.rst index 4aae8ed15873..377507c56162 100644 --- a/Documentation/i2c/functionality +++ b/Documentation/i2c/functionality.rst @@ -1,11 +1,15 @@ +======================= +I2C/SMBus Functionality +======================= + INTRODUCTION ------------ -Because not every I2C or SMBus adapter implements everything in the +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. FUNCTIONALITY CONSTANTS @@ -14,6 +18,7 @@ FUNCTIONALITY CONSTANTS For the most up-to-date list of functionality constants, please check <uapi/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 @@ -33,9 +38,11 @@ For the most up-to-date list of functionality constants, please check 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 @@ -49,6 +56,7 @@ A few combinations of the above flags are also defined for your convenience: I2C_FUNC_SMBUS_EMUL Handles all SMBus commands that can be emulated by a real I2C adapter (using the transparent emulation layer) + ========================= ====================================== In kernel versions prior to 3.5 I2C_FUNC_NOSTART was implemented as part of I2C_FUNC_PROTOCOL_MANGLING. @@ -58,11 +66,11 @@ ADAPTER IMPLEMENTATION ---------------------- When you write a new adapter driver, you will have to implement a -function callback `functionality'. Typical implementations are given +function callback ``functionality``. Typical implementations are given below. A typical SMBus-only adapter would list all the SMBus transactions it -supports. This example comes from the i2c-piix4 driver: +supports. This example comes from the i2c-piix4 driver:: static u32 piix4_func(struct i2c_adapter *adapter) { @@ -72,7 +80,7 @@ supports. This example comes from the i2c-piix4 driver: } A typical full-I2C adapter would use the following (from the i2c-pxa -driver): +driver):: static u32 i2c_pxa_functionality(struct i2c_adapter *adap) { @@ -94,7 +102,7 @@ CLIENT CHECKING Before a client tries to attach to an adapter, or even do tests to check whether one of the devices it supports is present on an adapter, it should check whether the needed functionality is present. The typical way to do -this is (from the lm75 driver): +this is (from the lm75 driver):: static int lm75_detect(...) { @@ -129,7 +137,7 @@ If you try to access an adapter from a userspace program, you will have to use the /dev interface. You will still have to check whether the functionality you need is supported, of course. This is done using the I2C_FUNCS ioctl. An example, adapted from the i2cdetect program, is -below: +below:: int file; if (file = open("/dev/i2c-0", O_RDWR) < 0) { diff --git a/Documentation/i2c/gpio-fault-injection b/Documentation/i2c/gpio-fault-injection.rst index c87f416d53dd..9dca6ec7d266 100644 --- a/Documentation/i2c/gpio-fault-injection +++ b/Documentation/i2c/gpio-fault-injection.rst @@ -104,10 +104,10 @@ There doesn't need to be a device at this address because arbitration lost should be detected beforehand. Also note, that SCL going down is monitored using interrupts, so the interrupt latency might cause the first bits to be not corrupted. A good starting point for using this fault injector on an otherwise -idle bus is: +idle bus is:: -# echo 200 > lose_arbitration & -# i2cget -y <bus_to_test> 0x3f + # echo 200 > lose_arbitration & + # i2cget -y <bus_to_test> 0x3f Panic during transfer ===================== @@ -127,10 +127,10 @@ The calling process will then sleep and wait for the next bus clock. The process is interruptible, though. Start of a transfer is detected by waiting for SCL going down by the master -under test. A good starting point for using this fault injector is: +under test. A good starting point for using this fault injector is:: -# echo 0 > inject_panic & -# i2cget -y <bus_to_test> <some_address> + # echo 0 > inject_panic & + # i2cget -y <bus_to_test> <some_address> Note that there doesn't need to be a device listening to the address you are using. Results may vary depending on that, though. diff --git a/Documentation/i2c/i2c-protocol b/Documentation/i2c/i2c-protocol.rst index ff6d6cee6c7e..b2092f8f815d 100644 --- a/Documentation/i2c/i2c-protocol +++ b/Documentation/i2c/i2c-protocol.rst @@ -1,47 +1,54 @@ -This document describes the i2c protocol. Or will, when it is finished :-) +================ +The I2C Protocol +================ + +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 +=============== ============================================================= +S Start condition +P Stop condition +Rd/Wr (1 bit) Read/Write bit. Rd equals 1, Wr equals 0. +A, NA (1 bit) Acknowledge (ACK) and Not Acknowledge (NACK) 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 +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 +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. +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. +[..] Data sent by I2C device, as opposed to data sent by the + host adapter. +=============== ============================================================= Simple send transaction -====================== +======================= -This corresponds to i2c_master_send. +Implemented by i2c_master_send():: S Addr Wr [A] Data [A] Data [A] ... [A] Data [A] P Simple receive transaction -=========================== +========================== -This corresponds to i2c_master_recv +Implemented by i2c_master_recv():: S Addr Rd [A] [Data] A [Data] A ... A [Data] NA P Combined transactions -==================== +===================== -This corresponds to i2c_transfer +Implemented by 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: +They are just like the above transactions, but instead of a stop +condition P a start condition 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 @@ -50,7 +57,7 @@ Modified transactions ===================== The following modifications to the I2C protocol can also be generated by -setting these flags for i2c messages. With the exception of I2C_M_NOSTART, they +setting these flags for I2C messages. With the exception of I2C_M_NOSTART, they are usually only needed to work around device issues: I2C_M_IGNORE_NAK: @@ -65,11 +72,14 @@ I2C_M_NO_RD_ACK: 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: + 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. + we do not generate Addr, but we do generate the start condition S. + This will probably confuse all other clients on your bus, so don't + try this. This is often used to gather transmits from multiple data buffers in system memory into something that appears as a single transfer to the @@ -79,7 +89,8 @@ I2C_M_NOSTART: 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: + flag. For example:: + S Addr Rd [A] Data [A] Data [A] ... [A] Data [A] P I2C_M_STOP: diff --git a/Documentation/i2c/i2c-stub b/Documentation/i2c/i2c-stub.rst index a16924fbd289..a6fc6916d6bc 100644 --- a/Documentation/i2c/i2c-stub +++ b/Documentation/i2c/i2c-stub.rst @@ -1,6 +1,9 @@ -MODULE: i2c-stub +======== +i2c-stub +======== -DESCRIPTION: +Description +=========== This module is a very simple fake I2C/SMBus driver. It implements six types of SMBus commands: write quick, (r/w) byte, (r/w) byte data, (r/w) @@ -28,6 +31,7 @@ SMBus block operations. Writes can be partial. Block read commands always return the number of bytes selected with the largest write so far. The typical use-case is like this: + 1. load this module 2. use i2cset (from the i2c-tools project) to pre-load some data 3. load the target chip driver module @@ -36,7 +40,8 @@ The typical use-case is like this: There's a script named i2c-stub-from-dump in the i2c-tools package which can load register values automatically from a chip dump. -PARAMETERS: +Parameters +========== int chip_addr[10]: The SMBus addresses to emulate chips at. @@ -47,18 +52,15 @@ unsigned long functionality: value 0x1f0000 would only enable the quick, byte and byte data commands. -u8 bank_reg[10] -u8 bank_mask[10] -u8 bank_start[10] -u8 bank_end[10]: +u8 bank_reg[10], u8 bank_mask[10], u8 bank_start[10], u8 bank_end[10]: Optional bank settings. They tell which bits in which register select the active bank, as well as the range of banked registers. -CAVEATS: +Caveats +======= If your target driver polls some byte or word waiting for it to change, the stub could lock it up. Use i2cset to unlock it. If you spam it hard enough, printk can be lossy. This module really wants something like relayfs. - diff --git a/Documentation/i2c/i2c-topology b/Documentation/i2c/i2c-topology.rst index f74d78b53d4d..7cb53819778e 100644 --- a/Documentation/i2c/i2c-topology +++ b/Documentation/i2c/i2c-topology.rst @@ -1,8 +1,9 @@ -I2C topology -============ +================================ +I2C muxes and complex topologies +================================ -There are a couple of reasons for building more complex i2c topologies -than a straight-forward i2c bus with one adapter and one or more devices. +There are a couple of reasons for building more complex I2C topologies +than a straight-forward I2C bus with one adapter and one or more devices. 1. A mux may be needed on the bus to prevent address collisions. @@ -10,19 +11,20 @@ than a straight-forward i2c bus with one adapter and one or more devices. may be needed to determine if it is ok to access the bus. 3. A device (particularly RF tuners) may want to avoid the digital noise - from the i2c bus, at least most of the time, and sits behind a gate + from the I2C bus, at least most of the time, and sits behind a gate that has to be operated before the device can be accessed. Etc +=== -These constructs are represented as i2c adapter trees by Linux, where +These constructs are represented as I2C adapter trees by Linux, where each adapter has a parent adapter (except the root adapter) and zero or more child adapters. The root adapter is the actual adapter that issues -i2c transfers, and all adapters with a parent are part of an "i2c-mux" +I2C transfers, and all adapters with a parent are part of an "i2c-mux" object (quoted, since it can also be an arbitrator or a gate). Depending of the particular mux driver, something happens when there is -an i2c transfer on one of its child adapters. The mux driver can +an I2C transfer on one of its child adapters. The mux driver can obviously operate a mux, but it can also do arbitration with an external bus master or open a gate. The mux driver has two operations for this, select and deselect. select is called before the transfer and (the @@ -32,16 +34,18 @@ optional) deselect is called after the transfer. Locking ======= -There are two variants of locking available to i2c muxes, they can be +There are two variants of locking available to I2C muxes, they can be mux-locked or parent-locked muxes. As is evident from below, it can be useful to know if a mux is mux-locked or if it is parent-locked. The following list was correct at the time of writing: -In drivers/i2c/muxes/ +In drivers/i2c/muxes/: + +====================== ============================================= i2c-arb-gpio-challenge Parent-locked i2c-mux-gpio Normally parent-locked, mux-locked iff all involved gpio pins are controlled by the - same i2c root adapter that they mux. + same I2C root adapter that they mux. i2c-mux-gpmux Normally parent-locked, mux-locked iff specified in device-tree. i2c-mux-ltc4306 Mux-locked @@ -50,20 +54,27 @@ i2c-mux-pca9541 Parent-locked i2c-mux-pca954x Parent-locked i2c-mux-pinctrl Normally parent-locked, mux-locked iff all involved pinctrl devices are controlled - by the same i2c root adapter that they mux. + by the same I2C root adapter that they mux. i2c-mux-reg Parent-locked +====================== ============================================= + +In drivers/iio/: -In drivers/iio/ +====================== ============================================= gyro/mpu3050 Mux-locked imu/inv_mpu6050/ Mux-locked +====================== ============================================= -In drivers/media/ +In drivers/media/: + +======================= ============================================= dvb-frontends/lgdt3306a Mux-locked dvb-frontends/m88ds3103 Parent-locked dvb-frontends/rtl2830 Parent-locked dvb-frontends/rtl2832 Mux-locked dvb-frontends/si2168 Mux-locked usb/cx231xx/ Parent-locked +======================= ============================================= Mux-locked muxes @@ -72,12 +83,13 @@ Mux-locked muxes Mux-locked muxes does not lock the entire parent adapter during the full select-transfer-deselect transaction, only the muxes on the parent adapter are locked. Mux-locked muxes are mostly interesting if the -select and/or deselect operations must use i2c transfers to complete +select and/or deselect operations must use I2C transfers to complete their tasks. Since the parent adapter is not fully locked during the -full transaction, unrelated i2c transfers may interleave the different +full transaction, unrelated I2C transfers may interleave the different stages of the transaction. This has the benefit that the mux driver may be easier and cleaner to implement, but it has some caveats. +==== ===================================================================== ML1. If you build a topology with a mux-locked mux being the parent of a parent-locked mux, this might break the expectation from the parent-locked mux that the root adapter is locked during the @@ -97,19 +109,23 @@ ML2. It is not safe to build arbitrary topologies with two (or more) ML3. A mux-locked mux cannot be used by a driver for auto-closing gates/muxes, i.e. something that closes automatically after a given - number (one, in most cases) of i2c transfers. Unrelated i2c transfers + number (one, in most cases) of I2C transfers. Unrelated I2C transfers may creep in and close prematurely. -ML4. If any non-i2c operation in the mux driver changes the i2c mux state, +ML4. If any non-I2C operation in the mux driver changes the I2C mux state, the driver has to lock the root adapter during that operation. Otherwise garbage may appear on the bus as seen from devices - behind the mux, when an unrelated i2c transfer is in flight during - the non-i2c mux-changing operation. + behind the mux, when an unrelated I2C transfer is in flight during + the non-I2C mux-changing operation. +==== ===================================================================== Mux-locked Example ------------------ + +:: + .----------. .--------. .--------. | mux- |-----| dev D1 | | root |--+--| locked | '--------' @@ -121,14 +137,14 @@ Mux-locked Example When there is an access to D1, this happens: - 1. Someone issues an i2c-transfer to D1. + 1. Someone issues an I2C transfer to D1. 2. M1 locks muxes on its parent (the root adapter in this case). 3. M1 calls ->select to ready the mux. - 4. M1 (presumably) does some i2c-transfers as part of its select. - These transfers are normal i2c-transfers that locks the parent + 4. M1 (presumably) does some I2C transfers as part of its select. + These transfers are normal I2C transfers that locks the parent adapter. - 5. M1 feeds the i2c-transfer from step 1 to its parent adapter as a - normal i2c-transfer that locks the parent adapter. + 5. M1 feeds the I2C transfer from step 1 to its parent adapter as a + normal I2C transfer that locks the parent adapter. 6. M1 calls ->deselect, if it has one. 7. Same rules as in step 4, but for ->deselect. 8. M1 unlocks muxes on its parent. @@ -143,29 +159,33 @@ Parent-locked muxes Parent-locked muxes lock the parent adapter during the full select- transfer-deselect transaction. The implication is that the mux driver -has to ensure that any and all i2c transfers through that parent -adapter during the transaction are unlocked i2c transfers (using e.g. +has to ensure that any and all I2C transfers through that parent +adapter during the transaction are unlocked I2C transfers (using e.g. __i2c_transfer), or a deadlock will follow. There are a couple of caveats. +==== ==================================================================== PL1. If you build a topology with a parent-locked mux being the child of another mux, this might break a possible assumption from the child mux that the root adapter is unused between its select op and the actual transfer (e.g. if the child mux is auto-closing - and the parent mux issus i2c-transfers as part of its select). + and the parent mux issues I2C transfers as part of its select). This is especially the case if the parent mux is mux-locked, but it may also happen if the parent mux is parent-locked. PL2. If select/deselect calls out to other subsystems such as gpio, - pinctrl, regmap or iio, it is essential that any i2c transfers + pinctrl, regmap or iio, it is essential that any I2C transfers caused by these subsystems are unlocked. This can be convoluted to accomplish, maybe even impossible if an acceptably clean solution is sought. +==== ==================================================================== Parent-locked Example --------------------- +:: + .----------. .--------. .--------. | parent- |-----| dev D1 | | root |--+--| locked | '--------' @@ -177,20 +197,20 @@ Parent-locked Example When there is an access to D1, this happens: - 1. Someone issues an i2c-transfer to D1. - 2. M1 locks muxes on its parent (the root adapter in this case). - 3. M1 locks its parent adapter. - 4. M1 calls ->select to ready the mux. - 5. If M1 does any i2c-transfers (on this root adapter) as part of - its select, those transfers must be unlocked i2c-transfers so - that they do not deadlock the root adapter. - 6. M1 feeds the i2c-transfer from step 1 to the root adapter as an - unlocked i2c-transfer, so that it does not deadlock the parent - adapter. - 7. M1 calls ->deselect, if it has one. - 8. Same rules as in step 5, but for ->deselect. - 9. M1 unlocks its parent adapter. -10. M1 unlocks muxes on its parent. + 1. Someone issues an I2C transfer to D1. + 2. M1 locks muxes on its parent (the root adapter in this case). + 3. M1 locks its parent adapter. + 4. M1 calls ->select to ready the mux. + 5. If M1 does any I2C transfers (on this root adapter) as part of + its select, those transfers must be unlocked I2C transfers so + that they do not deadlock the root adapter. + 6. M1 feeds the I2C transfer from step 1 to the root adapter as an + unlocked I2C transfer, so that it does not deadlock the parent + adapter. + 7. M1 calls ->deselect, if it has one. + 8. Same rules as in step 5, but for ->deselect. + 9. M1 unlocks its parent adapter. + 10. M1 unlocks muxes on its parent. This means that accesses to both D2 and D3 are locked out for the full @@ -203,7 +223,7 @@ Complex Examples Parent-locked mux as parent of parent-locked mux ------------------------------------------------ -This is a useful topology, but it can be bad. +This is a useful topology, but it can be bad:: .----------. .----------. .--------. .--------. | parent- |-----| parent- |-----| dev D1 | @@ -220,14 +240,14 @@ and specifically when M2 requests its parent to lock, M1 passes the buck to the root adapter). This topology is bad if M2 is an auto-closing mux and M1->select -issues any unlocked i2c transfers on the root adapter that may leak +issues any unlocked I2C transfers on the root adapter that may leak through and be seen by the M2 adapter, thus closing M2 prematurely. Mux-locked mux as parent of mux-locked mux ------------------------------------------ -This is a good topology. +This is a good topology:: .----------. .----------. .--------. .--------. | mux- |-----| mux- |-----| dev D1 | @@ -248,7 +268,7 @@ are still possibly interleaved. Mux-locked mux as parent of parent-locked mux --------------------------------------------- -This is probably a bad topology. +This is probably a bad topology:: .----------. .----------. .--------. .--------. | mux- |-----| parent- |-----| dev D1 | @@ -266,14 +286,14 @@ point. This kind of topology is generally not suitable and should probably be avoided. The reason is that M2 probably assumes that there will -be no i2c transfers during its calls to ->select and ->deselect, and +be no I2C transfers during its calls to ->select and ->deselect, and if there are, any such transfers might appear on the slave side of M2 -as partial i2c transfers, i.e. garbage or worse. This might cause +as partial I2C transfers, i.e. garbage or worse. This might cause device lockups and/or other problems. The topology is especially troublesome if M2 is an auto-closing mux. In that case, any interleaved accesses to D4 might close M2 -prematurely, as might any i2c-transfers part of M1->select. +prematurely, as might any I2C transfers part of M1->select. But if M2 is not making the above stated assumption, and if M2 is not auto-closing, the topology is fine. @@ -282,7 +302,7 @@ auto-closing, the topology is fine. Parent-locked mux as parent of mux-locked mux --------------------------------------------- -This is a good topology. +This is a good topology:: .----------. .----------. .--------. .--------. | parent- |-----| mux- |-----| dev D1 | @@ -306,7 +326,7 @@ adapter is locked directly. Two mux-locked sibling muxes ---------------------------- -This is a good topology. +This is a good topology:: .--------. .----------. .--| dev D1 | @@ -330,7 +350,7 @@ accesses to D5 may be interleaved at any time. Two parent-locked sibling muxes ------------------------------- -This is a good topology. +This is a good topology:: .--------. .----------. .--| dev D1 | @@ -354,7 +374,7 @@ out. Mux-locked and parent-locked sibling muxes ------------------------------------------ -This is a good topology. +This is a good topology:: .--------. .----------. .--| dev D1 | diff --git a/Documentation/i2c/i2c.svg b/Documentation/i2c/i2c.svg new file mode 100644 index 000000000000..5979405ad1c3 --- /dev/null +++ b/Documentation/i2c/i2c.svg @@ -0,0 +1,1341 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> + +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + sodipodi:docname="i2c.svg" + inkscape:version="0.92.3 (2405546, 2018-03-11)" + version="1.1" + id="svg2" + viewBox="0 0 813.34215 261.01596" + height="73.664505mm" + width="229.54323mm"> + <defs + id="defs4"> + <marker + inkscape:stockid="DotM" + orient="auto" + refY="0" + refX="0" + id="marker8861" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path8859" + d="m -2.5,-1 c 0,2.76 -2.24,5 -5,5 -2.76,0 -5,-2.24 -5,-5 0,-2.76 2.24,-5 5,-5 2.76,0 5,2.24 5,5 z" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(0.4,0,0,0.4,2.96,0.4)" /> + </marker> + <marker + inkscape:isstock="true" + style="overflow:visible" + id="marker6165" + refX="0" + refY="0" + orient="auto" + inkscape:stockid="DotM" + inkscape:collect="always"> + <path + transform="matrix(0.4,0,0,0.4,2.96,0.4)" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + d="m -2.5,-1 c 0,2.76 -2.24,5 -5,5 -2.76,0 -5,-2.24 -5,-5 0,-2.76 2.24,-5 5,-5 2.76,0 5,2.24 5,5 z" + id="path6163" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:isstock="true" + style="overflow:visible" + id="marker2713" + refX="0" + refY="0" + orient="auto" + inkscape:stockid="DotM"> + <path + transform="matrix(0.4,0,0,0.4,2.96,0.4)" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + d="m -2.5,-1 c 0,2.76 -2.24,5 -5,5 -2.76,0 -5,-2.24 -5,-5 0,-2.76 2.24,-5 5,-5 2.76,0 5,2.24 5,5 z" + id="path2711" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="DotM" + orient="auto" + refY="0" + refX="0" + id="DotM" + style="overflow:visible" + inkscape:isstock="true" + inkscape:collect="always"> + <path + id="path1795" + d="m -2.5,-1 c 0,2.76 -2.24,5 -5,5 -2.76,0 -5,-2.24 -5,-5 0,-2.76 2.24,-5 5,-5 2.76,0 5,2.24 5,5 z" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(0.4,0,0,0.4,2.96,0.4)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:isstock="true" + style="overflow:visible" + id="marker6389" + refX="0" + refY="0" + orient="auto" + inkscape:stockid="Arrow2Mend"> + <path + transform="scale(-0.6)" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + id="path6387" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="TriangleOutM" + orient="auto" + refY="0" + refX="0" + id="TriangleOutM" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path4107" + d="M 5.77,0 -2.88,5 V -5 Z" + style="fill:#008000;fill-opacity:1;fill-rule:evenodd;stroke:#008000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="scale(0.4)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="TriangleOutL" + orient="auto" + refY="0" + refX="0" + id="marker5333" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path5335" + d="M 5.77,0 -2.88,5 V -5 Z" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="scale(0.8)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="TriangleOutL" + orient="auto" + refY="0" + refX="0" + id="TriangleOutL" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path5049" + d="M 5.77,0 -2.88,5 V -5 Z" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="scale(0.8)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="DotS" + orient="auto" + refY="0" + refX="0" + id="DotS" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path9326" + d="m -2.5,-1 c 0,2.76 -2.24,5 -5,5 -2.76,0 -5,-2.24 -5,-5 0,-2.76 2.24,-5 5,-5 2.76,0 5,2.24 5,5 z" + style="fill:#404040;fill-opacity:1;fill-rule:evenodd;stroke:#404040;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(0.2,0,0,0.2,1.48,0.2)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow2Mstart" + orient="auto" + refY="0" + refX="0" + id="Arrow2Mstart" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path9283" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(0.6)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="marker9095" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path9097" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(-0.6)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="marker8935" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path8937" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(-0.6)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="marker8781" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path8783" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(-0.6)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow2Lend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Lend" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path4700" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="matrix(-1.1,0,0,-1.1,-1.1,0)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="EmptyTriangleOutL" + orient="auto" + refY="0" + refX="0" + id="EmptyTriangleOutL" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path4502" + d="M 5.77,0 -2.88,5 V -5 Z" + style="fill:#ffffff;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(0.8,0,0,0.8,-4.8,0)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="EmptyTriangleOutL" + orient="auto" + refY="0" + refX="0" + id="EmptyTriangleOutL-4" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path4502-7" + d="M 5.77,0 -2.88,5 V -5 Z" + style="fill:#ffffff;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(0.8,0,0,0.8,-4.8,0)" /> + </marker> + <marker + inkscape:stockid="EmptyTriangleOutL" + orient="auto" + refY="0" + refX="0" + id="EmptyTriangleOutL-4-4" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path4502-7-5" + d="M 5.77,0 -2.88,5 V -5 Z" + style="fill:#ffffff;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(0.8,0,0,0.8,-4.8,0)" /> + </marker> + <marker + inkscape:stockid="EmptyTriangleOutL" + orient="auto" + refY="0" + refX="0" + id="EmptyTriangleOutL-7" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path4502-5" + d="M 5.77,0 -2.88,5 V -5 Z" + style="fill:#ffffff;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(0.8,0,0,0.8,-4.8,0)" /> + </marker> + <marker + inkscape:stockid="EmptyTriangleOutL" + orient="auto" + refY="0" + refX="0" + id="EmptyTriangleOutL-6" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path4502-2" + d="M 5.77,0 -2.88,5 V -5 Z" + style="fill:#ffffff;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(0.8,0,0,0.8,-4.8,0)" /> + </marker> + <marker + inkscape:stockid="EmptyTriangleOutL" + orient="auto" + refY="0" + refX="0" + id="EmptyTriangleOutL-78" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path4502-57" + d="M 5.77,0 -2.88,5 V -5 Z" + style="fill:#ffffff;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(0.8,0,0,0.8,-4.8,0)" /> + </marker> + <marker + inkscape:stockid="EmptyTriangleOutL" + orient="auto" + refY="0" + refX="0" + id="EmptyTriangleOutL-1" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path4502-8" + d="M 5.77,0 -2.88,5 V -5 Z" + style="fill:#ffffff;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(0.8,0,0,0.8,-4.8,0)" /> + </marker> + <marker + inkscape:stockid="EmptyTriangleOutL" + orient="auto" + refY="0" + refX="0" + id="EmptyTriangleOutL-9" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path4502-75" + d="M 5.77,0 -2.88,5 V -5 Z" + style="fill:#ffffff;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(0.8,0,0,0.8,-4.8,0)" /> + </marker> + <marker + inkscape:stockid="EmptyTriangleOutL" + orient="auto" + refY="0" + refX="0" + id="EmptyTriangleOutL-78-2" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path4502-57-6" + d="M 5.77,0 -2.88,5 V -5 Z" + style="fill:#ffffff;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(0.8,0,0,0.8,-4.8,0)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Mend-3" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path4369-6" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(-0.6)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Mend-3-5" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path4369-6-3" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(-0.6)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Mend-3-5-6" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path4369-6-3-2" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(-0.6)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Mend-3-5-6-1" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path4369-6-3-2-2" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(-0.6)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Mend-3-5-7" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path4369-6-3-0" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(-0.6)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Mend-3-9" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path4369-6-36" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(-0.6)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Mend-31" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path4369-9" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(-0.6)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Mend-3-5-7-5" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path4369-6-3-0-4" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(-0.6)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Mend-3-9-6" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path4369-6-36-5" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(-0.6)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Mend-3-5-7-3" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path4369-6-3-0-5" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(-0.6)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="marker9095-3" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path9097-1" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(-0.6)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="marker9095-3-7" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path9097-1-8" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(-0.6)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="marker9095-1-5" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path9097-2-0" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(-0.6)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="marker9095-1-5-6" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path9097-2-0-1" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(-0.6)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="marker9095-1-5-6-6" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path9097-2-0-1-3" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(-0.6)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="marker9095-1-5-2" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path9097-2-0-0" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(-0.6)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="marker9095-1-5-6-5" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path9097-2-0-1-5" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(-0.6)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="marker9095-1-5-4" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path9097-2-0-7" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(-0.6)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="marker9095-1-5-6-5-9" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path9097-2-0-1-5-3" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(-0.6)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="marker9095-1-5-6-5-4" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path9097-2-0-1-5-5" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(-0.6)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="marker9095-1-5-6-5-4-4" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path9097-2-0-1-5-5-3" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(-0.6)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="marker9095-1-5-6-5-4-4-9" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path9097-2-0-1-5-5-3-2" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(-0.6)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="marker9095-1-5-6-5-4-4-6" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path9097-2-0-1-5-5-3-8" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(-0.6)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="marker9095-1-5-6-5-4-4-2" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path9097-2-0-1-5-5-3-7" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(-0.6)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="marker9095-1-5-3" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path9097-2-0-6" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(-0.6)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="marker9095-1-5-6-5-4-4-6-5" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path9097-2-0-1-5-5-3-8-3" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(-0.6)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="marker9095-1-5-27" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path9097-2-0-09" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(-0.6)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="marker9095-1-5-27-6" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path9097-2-0-09-2" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(-0.6)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="marker9095-1-5-27-0" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path9097-2-0-09-23" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(-0.6)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="marker9095-1-9" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path9097-2-7" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(-0.6)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="marker9095-1-5-4-6" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path9097-2-0-7-7" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(-0.6)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="marker9095-1-5-4-6-3" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path9097-2-0-7-7-5" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(-0.6)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="marker9095-1-5-4-6-2" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path9097-2-0-7-7-9" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(-0.6)" /> + </marker> + <marker + inkscape:stockid="TriangleOutM" + orient="auto" + refY="0" + refX="0" + id="TriangleOutM-2" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path4107-7" + d="M 5.77,0 -2.88,5 V -5 Z" + style="fill:#008000;fill-opacity:1;fill-rule:evenodd;stroke:#008000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="scale(0.4)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mstart" + orient="auto" + refY="0" + refX="0" + id="Arrow2Mstart-9" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path9283-3" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(0.6)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="marker9095-1-5-4-6-6" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path9097-2-0-7-7-0" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(-0.6)" /> + </marker> + <marker + inkscape:stockid="DotM" + orient="auto" + refY="0" + refX="0" + id="DotM-3" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path1795-7" + d="m -2.5,-1 c 0,2.76 -2.24,5 -5,5 -2.76,0 -5,-2.24 -5,-5 0,-2.76 2.24,-5 5,-5 2.76,0 5,2.24 5,5 z" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(0.4,0,0,0.4,2.96,0.4)" /> + </marker> + <marker + inkscape:isstock="true" + style="overflow:visible" + id="marker2713-9" + refX="0" + refY="0" + orient="auto" + inkscape:stockid="DotM"> + <path + inkscape:connector-curvature="0" + transform="matrix(0.4,0,0,0.4,2.96,0.4)" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + d="m -2.5,-1 c 0,2.76 -2.24,5 -5,5 -2.76,0 -5,-2.24 -5,-5 0,-2.76 2.24,-5 5,-5 2.76,0 5,2.24 5,5 z" + id="path2711-2" /> + </marker> + <marker + inkscape:stockid="DotM" + orient="auto" + refY="0" + refX="0" + id="DotM-2" + style="overflow:visible" + inkscape:isstock="true" + inkscape:collect="always"> + <path + inkscape:connector-curvature="0" + id="path1795-8" + d="m -2.5,-1 c 0,2.76 -2.24,5 -5,5 -2.76,0 -5,-2.24 -5,-5 0,-2.76 2.24,-5 5,-5 2.76,0 5,2.24 5,5 z" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(0.4,0,0,0.4,2.96,0.4)" /> + </marker> + <marker + inkscape:isstock="true" + style="overflow:visible" + id="marker2713-3" + refX="0" + refY="0" + orient="auto" + inkscape:stockid="DotM"> + <path + inkscape:connector-curvature="0" + transform="matrix(0.4,0,0,0.4,2.96,0.4)" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + d="m -2.5,-1 c 0,2.76 -2.24,5 -5,5 -2.76,0 -5,-2.24 -5,-5 0,-2.76 2.24,-5 5,-5 2.76,0 5,2.24 5,5 z" + id="path2711-6" /> + </marker> + <marker + inkscape:stockid="DotM" + orient="auto" + refY="0" + refX="0" + id="DotM-1" + style="overflow:visible" + inkscape:isstock="true" + inkscape:collect="always"> + <path + inkscape:connector-curvature="0" + id="path1795-2" + d="m -2.5,-1 c 0,2.76 -2.24,5 -5,5 -2.76,0 -5,-2.24 -5,-5 0,-2.76 2.24,-5 5,-5 2.76,0 5,2.24 5,5 z" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(0.4,0,0,0.4,2.96,0.4)" /> + </marker> + <marker + inkscape:isstock="true" + style="overflow:visible" + id="marker2713-94" + refX="0" + refY="0" + orient="auto" + inkscape:stockid="DotM"> + <path + inkscape:connector-curvature="0" + transform="matrix(0.4,0,0,0.4,2.96,0.4)" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + d="m -2.5,-1 c 0,2.76 -2.24,5 -5,5 -2.76,0 -5,-2.24 -5,-5 0,-2.76 2.24,-5 5,-5 2.76,0 5,2.24 5,5 z" + id="path2711-7" /> + </marker> + <marker + inkscape:stockid="DotM" + orient="auto" + refY="0" + refX="0" + id="DotM-8" + style="overflow:visible" + inkscape:isstock="true" + inkscape:collect="always"> + <path + inkscape:connector-curvature="0" + id="path1795-4" + d="m -2.5,-1 c 0,2.76 -2.24,5 -5,5 -2.76,0 -5,-2.24 -5,-5 0,-2.76 2.24,-5 5,-5 2.76,0 5,2.24 5,5 z" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(0.4,0,0,0.4,2.96,0.4)" /> + </marker> + <marker + inkscape:isstock="true" + style="overflow:visible" + id="marker2713-36" + refX="0" + refY="0" + orient="auto" + inkscape:stockid="DotM"> + <path + inkscape:connector-curvature="0" + transform="matrix(0.4,0,0,0.4,2.96,0.4)" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + d="m -2.5,-1 c 0,2.76 -2.24,5 -5,5 -2.76,0 -5,-2.24 -5,-5 0,-2.76 2.24,-5 5,-5 2.76,0 5,2.24 5,5 z" + id="path2711-1" /> + </marker> + <marker + inkscape:isstock="true" + style="overflow:visible" + id="marker6165-5" + refX="0" + refY="0" + orient="auto" + inkscape:stockid="DotM"> + <path + transform="matrix(0.4,0,0,0.4,2.96,0.4)" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + d="m -2.5,-1 c 0,2.76 -2.24,5 -5,5 -2.76,0 -5,-2.24 -5,-5 0,-2.76 2.24,-5 5,-5 2.76,0 5,2.24 5,5 z" + id="path6163-5" + inkscape:connector-curvature="0" /> + </marker> + </defs> + <sodipodi:namedview + showguides="true" + inkscape:window-maximized="1" + inkscape:window-y="0" + inkscape:window-x="0" + inkscape:window-height="1015" + inkscape:window-width="1920" + showgrid="true" + inkscape:current-layer="layer1" + inkscape:document-units="px" + inkscape:cy="214.66765" + inkscape:cx="-167.56857" + inkscape:zoom="0.70710678" + inkscape:pageshadow="2" + inkscape:pageopacity="0.0" + borderopacity="1.0" + bordercolor="#666666" + pagecolor="#ffffff" + id="base" + inkscape:snap-to-guides="true" + inkscape:snap-grids="true" + inkscape:snap-bbox="false" + inkscape:object-nodes="true" + fit-margin-top="5" + fit-margin-left="5" + fit-margin-right="5" + fit-margin-bottom="5"> + <inkscape:grid + type="xygrid" + id="grid4451" + originx="-93.377219" + originy="-347.2523" /> + </sodipodi:namedview> + <metadata + id="metadata7"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + <dc:title></dc:title> + <dc:creator> + <cc:Agent> + <dc:title>Luca Ceresoli</dc:title> + </cc:Agent> + </dc:creator> + <dc:date>2020</dc:date> + <cc:license + rdf:resource="http://creativecommons.org/licenses/by-sa/4.0/" /> + </cc:Work> + <cc:License + rdf:about="http://creativecommons.org/licenses/by-sa/4.0/"> + <cc:permits + rdf:resource="http://creativecommons.org/ns#Reproduction" /> + <cc:permits + rdf:resource="http://creativecommons.org/ns#Distribution" /> + <cc:requires + rdf:resource="http://creativecommons.org/ns#Notice" /> + <cc:requires + rdf:resource="http://creativecommons.org/ns#Attribution" /> + <cc:permits + rdf:resource="http://creativecommons.org/ns#DerivativeWorks" /> + <cc:requires + rdf:resource="http://creativecommons.org/ns#ShareAlike" /> + </cc:License> + </rdf:RDF> + </metadata> + <g + inkscape:label="Livello 1" + inkscape:groupmode="layer" + id="layer1" + transform="translate(-93.377215,-444.09395)"> + <rect + style="opacity:1;fill:#ffb9b9;fill-opacity:1;stroke:#f00000;stroke-width:2.8125;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + id="rect4424-3-2-9-7" + width="112.5" + height="113.75008" + x="112.5" + y="471.11221" + rx="0" + ry="0" /> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="167.5354" + y="521.46259" + id="text4349"><tspan + sodipodi:role="line" + x="167.5354" + y="521.46259" + style="font-size:25px;line-height:1.25;font-family:sans-serif;text-align:center;text-anchor:middle" + id="tspan1273">I2C</tspan><tspan + sodipodi:role="line" + x="167.5354" + y="552.71259" + style="font-size:25px;line-height:1.25;font-family:sans-serif;text-align:center;text-anchor:middle" + id="tspan1285">Master</tspan></text> + <rect + style="color:#000000;clip-rule:nonzero;display:inline;overflow:visible;visibility:visible;opacity:1;isolation:auto;mix-blend-mode:normal;color-interpolation:sRGB;color-interpolation-filters:linearRGB;solid-color:#000000;solid-opacity:1;fill:#b9ffb9;fill-opacity:1;fill-rule:nonzero;stroke:#006400;stroke-width:2.8125;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;color-rendering:auto;image-rendering:auto;shape-rendering:auto;text-rendering:auto;enable-background:accumulate" + id="rect4424-3-2-9-7-3-3-5-3" + width="112.49998" + height="112.50001" + x="262.5" + y="471.11218" + rx="0" + ry="0" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.99968767;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + d="m 112.50002,639.86223 c 712.50002,0 712.50002,0 712.50002,0" + id="path4655-9-3-65-5-6" + inkscape:connector-curvature="0" /> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:12px;line-height:0%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="318.59131" + y="520.83752" + id="text4349-26"><tspan + sodipodi:role="line" + x="318.59131" + y="520.83752" + style="font-size:25.00000191px;line-height:1.25;font-family:sans-serif;text-align:center;text-anchor:middle;stroke-width:1px" + id="tspan1273-8">I2C</tspan><tspan + sodipodi:role="line" + x="318.59131" + y="552.08752" + style="font-size:25.00000191px;line-height:1.25;font-family:sans-serif;text-align:center;text-anchor:middle;stroke-width:1px" + id="tspan1287">Slave</tspan></text> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.99968767;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + d="m 112.49995,677.36223 c 712.50005,0 712.50005,0 712.50005,0" + id="path4655-9-3-65-5-6-2" + inkscape:connector-curvature="0" /> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:12px;line-height:0%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="861.07312" + y="687.03937" + id="text4349-7"><tspan + sodipodi:role="line" + x="861.07312" + y="687.03937" + style="font-size:25.00000191px;line-height:1.25;font-family:sans-serif;text-align:center;writing-mode:lr-tb;direction:ltr;text-anchor:middle;stroke-width:1px" + id="tspan1285-9">SCL</tspan></text> + <flowRoot + xml:space="preserve" + id="flowRoot1627" + style="font-style:normal;font-weight:normal;font-size:40px;line-height:125%;font-family:Sans;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"><flowRegion + id="flowRegion1629"><rect + id="rect1631" + width="220" + height="120" + x="140" + y="-126.29921" /></flowRegion><flowPara + id="flowPara1633" /></flowRoot> <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:12px;line-height:0%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="863.31921" + y="648.96735" + id="text4349-7-3"><tspan + sodipodi:role="line" + x="863.31921" + y="648.96735" + style="font-size:25.00000191px;line-height:1.25;font-family:sans-serif;text-align:center;text-anchor:middle;stroke-width:1px" + id="tspan1285-9-6">SDA</tspan></text> + <rect + style="color:#000000;clip-rule:nonzero;display:inline;overflow:visible;visibility:visible;opacity:1;isolation:auto;mix-blend-mode:normal;color-interpolation:sRGB;color-interpolation-filters:linearRGB;solid-color:#000000;solid-opacity:1;vector-effect:none;fill:#b9ffb9;fill-opacity:1;fill-rule:nonzero;stroke:#006400;stroke-width:2.8125;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;color-rendering:auto;image-rendering:auto;shape-rendering:auto;text-rendering:auto;enable-background:accumulate" + id="rect4424-3-2-9-7-3-3-5-3-0" + width="112.49998" + height="112.50002" + x="412.5" + y="471.11215" + rx="0" + ry="0" /> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:12px;line-height:0%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="468.59131" + y="520.83746" + id="text4349-26-6"><tspan + sodipodi:role="line" + x="468.59131" + y="520.83746" + style="font-size:25.00000191px;line-height:1.25;font-family:sans-serif;text-align:center;text-anchor:middle;stroke-width:1px" + id="tspan1273-8-2">I2C</tspan><tspan + sodipodi:role="line" + x="468.59131" + y="552.08746" + style="font-size:25.00000191px;line-height:1.25;font-family:sans-serif;text-align:center;text-anchor:middle;stroke-width:1px" + id="tspan1287-6">Slave</tspan></text> + <rect + style="color:#000000;clip-rule:nonzero;display:inline;overflow:visible;visibility:visible;opacity:1;isolation:auto;mix-blend-mode:normal;color-interpolation:sRGB;color-interpolation-filters:linearRGB;solid-color:#000000;solid-opacity:1;vector-effect:none;fill:#b9ffb9;fill-opacity:1;fill-rule:nonzero;stroke:#006400;stroke-width:2.8125;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;color-rendering:auto;image-rendering:auto;shape-rendering:auto;text-rendering:auto;enable-background:accumulate" + id="rect4424-3-2-9-7-3-3-5-3-1" + width="112.49998" + height="112.50002" + x="562.5" + y="471.11215" + rx="0" + ry="0" /> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:12px;line-height:0%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="618.59131" + y="520.83746" + id="text4349-26-8"><tspan + sodipodi:role="line" + x="618.59131" + y="520.83746" + style="font-size:25.00000191px;line-height:1.25;font-family:sans-serif;text-align:center;text-anchor:middle;stroke-width:1px" + id="tspan1273-8-7">I2C</tspan><tspan + sodipodi:role="line" + x="618.59131" + y="552.08746" + style="font-size:25.00000191px;line-height:1.25;font-family:sans-serif;text-align:center;text-anchor:middle;stroke-width:1px" + id="tspan1287-9">Slave</tspan></text> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.99968743;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#DotM)" + d="m 150,583.61221 v 93.75" + id="path4655-9-3-65-5-6-20" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="opacity:1;vector-effect:none;fill:none;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.99968743;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;marker-end:url(#marker2713)" + d="m 187.5,583.61221 v 56.25" + id="path4655-9-3-65-5-6-20-2" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.99968743;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#DotM-2)" + d="m 300,583.61221 v 93.75" + id="path4655-9-3-65-5-6-20-9" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="opacity:1;vector-effect:none;fill:none;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.99968743;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;marker-end:url(#marker2713-9)" + d="m 337.5,583.61221 v 56.25" + id="path4655-9-3-65-5-6-20-2-7" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.99968743;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#DotM-1)" + d="m 450,583.61221 v 93.75" + id="path4655-9-3-65-5-6-20-93" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="opacity:1;vector-effect:none;fill:none;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.99968743;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;marker-end:url(#marker2713-3)" + d="m 487.5,583.61221 v 56.25" + id="path4655-9-3-65-5-6-20-2-1" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.99968743;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#DotM-8)" + d="m 600,583.61221 v 93.75" + id="path4655-9-3-65-5-6-20-5" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="opacity:1;vector-effect:none;fill:none;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.99968743;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;marker-end:url(#marker2713-94)" + d="m 637.5,583.61221 v 56.25" + id="path4655-9-3-65-5-6-20-2-0" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="opacity:1;vector-effect:none;fill:none;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.99968743;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;marker-start:url(#marker6165);marker-end:url(#marker6165)" + d="m 750,471.11221 v 28.125 l 9.375,9.375 -18.74999,18.75 18.74999,18.75 -18.74999,18.75 18.74999,18.75 -9.375,9.375 v 28.125 0 0 56.25" + id="path6135" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cccccccccccc" /> + <path + style="opacity:1;vector-effect:none;fill:none;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.99968743;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;marker-start:url(#marker8861);marker-end:url(#marker6165-5)" + d="m 787.49999,471.11221 v 28.125 l 9.375,9.375 -18.74999,18.75 18.74999,18.75 -18.74999,18.75 18.74999,18.75 -9.375,9.375 v 28.125 0 0 18.75001" + id="path6135-4" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cccccccccccc" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.99968719;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + d="m 712.5,471.11221 c 112.49999,0 112.49999,0 112.49999,0" + id="path4655-9-3-65-5-6-7" + inkscape:connector-curvature="0" /> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;font-size:12px;line-height:0%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="859.94275" + y="480.03558" + id="text4349-7-3-6"><tspan + sodipodi:role="line" + x="859.94275" + y="480.03558" + style="font-size:25.00000191px;line-height:1.25;font-family:sans-serif;text-align:center;text-anchor:middle;stroke-width:1px" + id="tspan1285-9-6-5">V<tspan + style="font-size:64.99999762%;baseline-shift:sub" + id="tspan9307">DD</tspan></tspan></text> + </g> +</svg> diff --git a/Documentation/i2c/index.rst b/Documentation/i2c/index.rst new file mode 100644 index 000000000000..fee4744475df --- /dev/null +++ b/Documentation/i2c/index.rst @@ -0,0 +1,73 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=================== +I2C/SMBus Subsystem +=================== + +Introduction +============ + +.. toctree:: + :maxdepth: 1 + + summary + i2c-protocol + smbus-protocol + instantiating-devices + busses/index + i2c-topology + muxes/i2c-mux-gpio + +Writing device drivers +====================== + +.. toctree:: + :maxdepth: 1 + + writing-clients + dev-interface + dma-considerations + fault-codes + functionality + +Debugging +========= + +.. toctree:: + :maxdepth: 1 + + gpio-fault-injection + i2c-stub + +Slave I2C +========= + +.. toctree:: + :maxdepth: 1 + + slave-interface + slave-eeprom-backend + +Advanced topics +=============== + +.. toctree:: + :maxdepth: 1 + + ten-bit-addresses + +Legacy documentation +==================== + +.. toctree:: + :maxdepth: 1 + + upgrading-clients + old-module-parameters + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/i2c/instantiating-devices b/Documentation/i2c/instantiating-devices.rst index 345e9ea8281a..e558e0a77e0c 100644 --- a/Documentation/i2c/instantiating-devices +++ b/Documentation/i2c/instantiating-devices.rst @@ -1,3 +1,4 @@ +============================== How to instantiate I2C devices ============================== @@ -8,56 +9,29 @@ reason, the kernel code must instantiate I2C devices explicitly. There are several ways to achieve this, depending on the context and requirements. -Method 1a: Declare the I2C devices by bus number ------------------------------------------------- +Method 1: Declare the I2C devices statically +-------------------------------------------- This method is appropriate when the I2C bus is a system bus as is the case -for many embedded systems. On such systems, each I2C bus has a number -which is known in advance. It is thus possible to pre-declare the I2C -devices which live on this bus. This is done with an array of struct -i2c_board_info which is registered by calling i2c_register_board_info(). - -Example (from omap2 h4): - -static struct i2c_board_info h4_i2c_board_info[] __initdata = { - { - I2C_BOARD_INFO("isp1301_omap", 0x2d), - .irq = OMAP_GPIO_IRQ(125), - }, - { /* EEPROM on mainboard */ - I2C_BOARD_INFO("24c01", 0x52), - .platform_data = &m24c01, - }, - { /* EEPROM on cpu card */ - I2C_BOARD_INFO("24c01", 0x57), - .platform_data = &m24c01, - }, -}; +for many embedded systems. On such systems, each I2C bus has a number which +is known in advance. It is thus possible to pre-declare the I2C devices +which live on this bus. -static void __init omap_h4_init(void) -{ - (...) - i2c_register_board_info(1, h4_i2c_board_info, - ARRAY_SIZE(h4_i2c_board_info)); - (...) -} +This information is provided to the kernel in a different way on different +architectures: device tree, ACPI or board files. -The above code declares 3 devices on I2C bus 1, including their respective -addresses and custom data needed by their drivers. When the I2C bus in -question is registered, the I2C devices will be instantiated automatically -by i2c-core. - -The devices will be automatically unbound and destroyed when the I2C bus -they sit on goes away (if ever.) +When the I2C bus in question is registered, the I2C devices will be +instantiated automatically by i2c-core. The devices will be automatically +unbound and destroyed when the I2C bus they sit on goes away (if ever). -Method 1b: Declare the I2C devices via devicetree -------------------------------------------------- +Declare the I2C devices via devicetree +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -This method has the same implications as method 1a. The declaration of I2C -devices is here done via devicetree as subnodes of the master controller. +On platforms using devicetree, the declaration of I2C devices is done in +subnodes of the master controller. -Example: +Example:: i2c1: i2c@400a0000 { /* ... master properties skipped ... */ @@ -81,11 +55,49 @@ additional properties which might be needed to set up the device, please refer to its devicetree documentation in Documentation/devicetree/bindings/. -Method 1c: Declare the I2C devices via ACPI -------------------------------------------- +Declare the I2C devices via ACPI +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ACPI can also describe I2C devices. There is special documentation for this -which is currently located at Documentation/firmware-guide/acpi/enumeration.rst. +which is currently located at :doc:`../firmware-guide/acpi/enumeration`. + + +Declare the I2C devices in board files +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In many embedded architectures, devicetree has replaced the old hardware +description based on board files, but the latter are still used in old +code. Instantiating I2C devices via board files is done with an array of +struct i2c_board_info which is registered by calling +i2c_register_board_info(). + +Example (from omap2 h4):: + + static struct i2c_board_info h4_i2c_board_info[] __initdata = { + { + I2C_BOARD_INFO("isp1301_omap", 0x2d), + .irq = OMAP_GPIO_IRQ(125), + }, + { /* EEPROM on mainboard */ + I2C_BOARD_INFO("24c01", 0x52), + .platform_data = &m24c01, + }, + { /* EEPROM on cpu card */ + I2C_BOARD_INFO("24c01", 0x57), + .platform_data = &m24c01, + }, + }; + + static void __init omap_h4_init(void) + { + (...) + i2c_register_board_info(1, h4_i2c_board_info, + ARRAY_SIZE(h4_i2c_board_info)); + (...) + } + +The above code declares 3 devices on I2C bus 1, including their respective +addresses and custom data needed by their drivers. Method 2: Instantiate the devices explicitly @@ -97,22 +109,22 @@ tuner, a video decoder, an audio decoder, etc. usually connected to the main chip by the means of an I2C bus. You won't know the number of the I2C bus in advance, so the method 1 described above can't be used. Instead, you can instantiate your I2C devices explicitly. This is done by filling -a struct i2c_board_info and calling i2c_new_device(). +a struct i2c_board_info and calling i2c_new_client_device(). -Example (from the sfe4001 network driver): +Example (from the sfe4001 network driver):: -static struct i2c_board_info sfe4001_hwmon_info = { + static struct i2c_board_info sfe4001_hwmon_info = { I2C_BOARD_INFO("max6647", 0x4e), -}; + }; -int sfe4001_init(struct efx_nic *efx) -{ + int sfe4001_init(struct efx_nic *efx) + { (...) efx->board_info.hwmon_client = - i2c_new_device(&efx->i2c_adap, &sfe4001_hwmon_info); + i2c_new_client_device(&efx->i2c_adap, &sfe4001_hwmon_info); (...) -} + } The above code instantiates 1 I2C device on the I2C bus which is on the network adapter in question. @@ -122,14 +134,14 @@ present or not (for example for an optional feature which is not present on cheap variants of a board but you have no way to tell them apart), or it may have different addresses from one board to the next (manufacturer changing its design without notice). In this case, you can call -i2c_new_probed_device() instead of i2c_new_device(). +i2c_new_scanned_device() instead of i2c_new_client_device(). -Example (from the nxp OHCI driver): +Example (from the nxp OHCI driver):: -static const unsigned short normal_i2c[] = { 0x2c, 0x2d, I2C_CLIENT_END }; + static const unsigned short normal_i2c[] = { 0x2c, 0x2d, I2C_CLIENT_END }; -static int usb_hcd_nxp_probe(struct platform_device *pdev) -{ + static int usb_hcd_nxp_probe(struct platform_device *pdev) + { (...) struct i2c_adapter *i2c_adap; struct i2c_board_info i2c_info; @@ -138,11 +150,11 @@ static int usb_hcd_nxp_probe(struct platform_device *pdev) i2c_adap = i2c_get_adapter(2); memset(&i2c_info, 0, sizeof(struct i2c_board_info)); strscpy(i2c_info.type, "isp1301_nxp", sizeof(i2c_info.type)); - isp1301_i2c_client = i2c_new_probed_device(i2c_adap, &i2c_info, - normal_i2c, NULL); + isp1301_i2c_client = i2c_new_scanned_device(i2c_adap, &i2c_info, + normal_i2c, NULL); i2c_put_adapter(i2c_adap); (...) -} + } The above code instantiates up to 1 I2C device on the I2C bus which is on the OHCI adapter in question. It first tries at address 0x2c, if nothing @@ -151,15 +163,15 @@ simply gives up. The driver which instantiated the I2C device is responsible for destroying it on cleanup. This is done by calling i2c_unregister_device() on the -pointer that was earlier returned by i2c_new_device() or -i2c_new_probed_device(). +pointer that was earlier returned by i2c_new_client_device() or +i2c_new_scanned_device(). Method 3: Probe an I2C bus for certain devices ---------------------------------------------- Sometimes you do not have enough information about an I2C device, not even -to call i2c_new_probed_device(). The typical case is hardware monitoring +to call i2c_new_scanned_device(). The typical case is hardware monitoring chips on PC mainboards. There are several dozen models, which can live at 25 different addresses. Given the huge number of mainboards out there, it is next to impossible to build an exhaustive list of the hardware @@ -172,6 +184,7 @@ explicitly. Instead, i2c-core will probe for such devices as soon as their drivers are loaded, and if any is found, an I2C device will be instantiated automatically. In order to prevent any misbehavior of this mechanism, the following restrictions apply: + * The I2C device driver must implement the detect() method, which identifies a supported device by reading from arbitrary registers. * Only buses which are likely to have a supported device and agree to be @@ -186,9 +199,10 @@ destroyed automatically when the driver which detected them is removed, or when the underlying I2C bus is itself destroyed, whichever happens first. -Those of you familiar with the i2c subsystem of 2.4 kernels and early 2.6 +Those of you familiar with the I2C subsystem of 2.4 kernels and early 2.6 kernels will find out that this method 3 is essentially similar to what was done there. Two significant differences are: + * Probing is only one way to instantiate I2C devices now, while it was the only way back then. Where possible, methods 1 and 2 should be preferred. Method 3 should only be used when there is no other way, as it can have @@ -211,24 +225,26 @@ In general, the kernel should know which I2C devices are connected and what addresses they live at. However, in certain cases, it does not, so a sysfs interface was added to let the user provide the information. This interface is made of 2 attribute files which are created in every I2C bus -directory: new_device and delete_device. Both files are write only and you -must write the right parameters to them in order to properly instantiate, -respectively delete, an I2C device. +directory: ``new_device`` and ``delete_device``. Both files are write +only and you must write the right parameters to them in order to properly +instantiate, respectively delete, an I2C device. -File new_device takes 2 parameters: the name of the I2C device (a string) -and the address of the I2C device (a number, typically expressed in -hexadecimal starting with 0x, but can also be expressed in decimal.) +File ``new_device`` takes 2 parameters: the name of the I2C device (a +string) and the address of the I2C device (a number, typically expressed +in hexadecimal starting with 0x, but can also be expressed in decimal.) -File delete_device takes a single parameter: the address of the I2C +File ``delete_device`` takes a single parameter: the address of the I2C device. As no two devices can live at the same address on a given I2C segment, the address is sufficient to uniquely identify the device to be deleted. -Example: -# echo eeprom 0x50 > /sys/bus/i2c/devices/i2c-3/new_device +Example:: + + # echo eeprom 0x50 > /sys/bus/i2c/devices/i2c-3/new_device While this interface should only be used when in-kernel device declaration can't be done, there is a variety of cases where it can be helpful: + * The I2C driver usually detects devices (method 3 above) but the bus segment your device lives on doesn't have the proper class bit set and thus detection doesn't trigger. diff --git a/Documentation/i2c/muxes/i2c-mux-gpio b/Documentation/i2c/muxes/i2c-mux-gpio.rst index 893ecdfe6e43..7d27444035c3 100644 --- a/Documentation/i2c/muxes/i2c-mux-gpio +++ b/Documentation/i2c/muxes/i2c-mux-gpio.rst @@ -1,4 +1,6 @@ +========================== Kernel driver i2c-mux-gpio +========================== Author: Peter Korsgaard <peter.korsgaard@barco.com> @@ -8,7 +10,7 @@ Description i2c-mux-gpio is an i2c mux driver providing access to I2C bus segments from a master I2C bus and a hardware MUX controlled through GPIO pins. -E.G.: +E.G.:: ---------- ---------- Bus segment 1 - - - - - | | SCL/SDA | |-------------- | | @@ -33,20 +35,20 @@ bus, the number of bus segments to create and the GPIO pins used to control it. See include/linux/platform_data/i2c-mux-gpio.h for details. E.G. something like this for a MUX providing 4 bus segments -controlled through 3 GPIO pins: +controlled through 3 GPIO pins:: -#include <linux/platform_data/i2c-mux-gpio.h> -#include <linux/platform_device.h> + #include <linux/platform_data/i2c-mux-gpio.h> + #include <linux/platform_device.h> -static const unsigned myboard_gpiomux_gpios[] = { + static const unsigned myboard_gpiomux_gpios[] = { AT91_PIN_PC26, AT91_PIN_PC25, AT91_PIN_PC24 -}; + }; -static const unsigned myboard_gpiomux_values[] = { + static const unsigned myboard_gpiomux_values[] = { 0, 1, 2, 3 -}; + }; -static struct i2c_mux_gpio_platform_data myboard_i2cmux_data = { + static struct i2c_mux_gpio_platform_data myboard_i2cmux_data = { .parent = 1, .base_nr = 2, /* optional */ .values = myboard_gpiomux_values, @@ -54,15 +56,15 @@ static struct i2c_mux_gpio_platform_data myboard_i2cmux_data = { .gpios = myboard_gpiomux_gpios, .n_gpios = ARRAY_SIZE(myboard_gpiomux_gpios), .idle = 4, /* optional */ -}; + }; -static struct platform_device myboard_i2cmux = { + static struct platform_device myboard_i2cmux = { .name = "i2c-mux-gpio", .id = 0, .dev = { .platform_data = &myboard_i2cmux_data, }, -}; + }; If you don't know the absolute GPIO pin numbers at registration time, you can instead provide a chip name (.chip_name) and relative GPIO pin diff --git a/Documentation/i2c/old-module-parameters b/Documentation/i2c/old-module-parameters deleted file mode 100644 index 8e2b629d533c..000000000000 --- a/Documentation/i2c/old-module-parameters +++ /dev/null @@ -1,44 +0,0 @@ -I2C device driver binding control from user-space -================================================= - -Up to kernel 2.6.32, many i2c drivers used helper macros provided by -<linux/i2c.h> which created standard module parameters to let the user -control how the driver would probe i2c buses and attach to devices. These -parameters were known as "probe" (to let the driver probe for an extra -address), "force" (to forcibly attach the driver to a given device) and -"ignore" (to prevent a driver from probing a given address). - -With the conversion of the i2c subsystem to the standard device driver -binding model, it became clear that these per-module parameters were no -longer needed, and that a centralized implementation was possible. The new, -sysfs-based interface is described in the documentation file -"instantiating-devices", section "Method 4: Instantiate from user-space". - -Below is a mapping from the old module parameters to the new interface. - -Attaching a driver to an I2C device ------------------------------------ - -Old method (module parameters): -# modprobe <driver> probe=1,0x2d -# modprobe <driver> force=1,0x2d -# modprobe <driver> force_<device>=1,0x2d - -New method (sysfs interface): -# echo <device> 0x2d > /sys/bus/i2c/devices/i2c-1/new_device - -Preventing a driver from attaching to an I2C device ---------------------------------------------------- - -Old method (module parameters): -# modprobe <driver> ignore=1,0x2f - -New method (sysfs interface): -# echo dummy 0x2f > /sys/bus/i2c/devices/i2c-1/new_device -# modprobe <driver> - -Of course, it is important to instantiate the "dummy" device before loading -the driver. The dummy device will be handled by i2c-core itself, preventing -other drivers from binding to it later on. If there is a real device at the -problematic address, and you want another driver to bind to it, then simply -pass the name of the device in question instead of "dummy". diff --git a/Documentation/i2c/old-module-parameters.rst b/Documentation/i2c/old-module-parameters.rst new file mode 100644 index 000000000000..38e55829dee8 --- /dev/null +++ b/Documentation/i2c/old-module-parameters.rst @@ -0,0 +1,54 @@ +================================================================ +I2C device driver binding control from user-space in old kernels +================================================================ + +.. NOTE:: + Note: this section is only relevant if you are handling some old code + found in kernel 2.6. If you work with more recent kernels, you can + safely skip this section. + +Up to kernel 2.6.32, many I2C drivers used helper macros provided by +<linux/i2c.h> which created standard module parameters to let the user +control how the driver would probe I2C buses and attach to devices. These +parameters were known as ``probe`` (to let the driver probe for an extra +address), ``force`` (to forcibly attach the driver to a given device) and +``ignore`` (to prevent a driver from probing a given address). + +With the conversion of the I2C subsystem to the standard device driver +binding model, it became clear that these per-module parameters were no +longer needed, and that a centralized implementation was possible. The new, +sysfs-based interface is described in :doc:`instantiating-devices`, section +"Method 4: Instantiate from user-space". + +Below is a mapping from the old module parameters to the new interface. + +Attaching a driver to an I2C device +----------------------------------- + +Old method (module parameters):: + + # modprobe <driver> probe=1,0x2d + # modprobe <driver> force=1,0x2d + # modprobe <driver> force_<device>=1,0x2d + +New method (sysfs interface):: + + # echo <device> 0x2d > /sys/bus/i2c/devices/i2c-1/new_device + +Preventing a driver from attaching to an I2C device +--------------------------------------------------- + +Old method (module parameters):: + + # modprobe <driver> ignore=1,0x2f + +New method (sysfs interface):: + + # echo dummy 0x2f > /sys/bus/i2c/devices/i2c-1/new_device + # modprobe <driver> + +Of course, it is important to instantiate the ``dummy`` device before loading +the driver. The dummy device will be handled by i2c-core itself, preventing +other drivers from binding to it later on. If there is a real device at the +problematic address, and you want another driver to bind to it, then simply +pass the name of the device in question instead of ``dummy``. diff --git a/Documentation/i2c/slave-eeprom-backend b/Documentation/i2c/slave-eeprom-backend.rst index 04f8d8a9b817..0b8cd83698e0 100644 --- a/Documentation/i2c/slave-eeprom-backend +++ b/Documentation/i2c/slave-eeprom-backend.rst @@ -1,3 +1,4 @@ +============================== Linux I2C slave eeprom backend ============================== @@ -5,10 +6,9 @@ by Wolfram Sang <wsa@sang-engineering.com> in 2014-15 This is a proof-of-concept backend which acts like an EEPROM on the connected I2C bus. The memory contents can be modified from userspace via this file -located in sysfs: +located in sysfs:: /sys/bus/i2c/devices/<device-directory>/slave-eeprom As of 2015, Linux doesn't support poll on binary sysfs files, so there is no notification when another master changed the content. - diff --git a/Documentation/i2c/slave-interface b/Documentation/i2c/slave-interface.rst index 7e2a228f21bc..82ea3e1d6fe4 100644 --- a/Documentation/i2c/slave-interface +++ b/Documentation/i2c/slave-interface.rst @@ -1,3 +1,4 @@ +===================================== Linux I2C slave interface description ===================================== @@ -12,7 +13,7 @@ EEPROM, the Linux I2C slave can access the content via sysfs and handle data as needed. The backend driver and the I2C bus driver communicate via events. Here is a small graph visualizing the data flow and the means by which data is transported. The dotted line marks only one example. The backend could also -use a character device, be in-kernel only, or something completely different: +use a character device, be in-kernel only, or something completely different:: e.g. sysfs I2C slave events I/O registers @@ -35,7 +36,7 @@ them as described in the document 'instantiating-devices'. The only difference is that i2c slave backends have their own address space. So, you have to add 0x1000 to the address you would originally request. An example for instantiating the slave-eeprom driver from userspace at the 7 bit address 0x64 -on bus 1: +on bus 1:: # echo slave-24c02 0x1064 > /sys/bus/i2c/devices/i2c-1/new_device @@ -54,11 +55,11 @@ drivers and writing backends will be given. I2C slave events ---------------- -The bus driver sends an event to the backend using the following function: +The bus driver sends an event to the backend using the following function:: ret = i2c_slave_event(client, event, &val) -'client' describes the i2c slave device. 'event' is one of the special event +'client' describes the I2C slave device. 'event' is one of the special event types described hereafter. 'val' holds an u8 value for the data byte to be read/written and is thus bidirectional. The pointer to val must always be provided even if val is not used for an event, i.e. don't use NULL here. 'ret' @@ -69,8 +70,9 @@ Event types: * I2C_SLAVE_WRITE_REQUESTED (mandatory) -'val': unused -'ret': always 0 + 'val': unused + + 'ret': always 0 Another I2C master wants to write data to us. This event should be sent once our own address and the write bit was detected. The data did not arrive yet, so @@ -79,8 +81,9 @@ to be done, though. * I2C_SLAVE_READ_REQUESTED (mandatory) -'val': backend returns first byte to be sent -'ret': always 0 + 'val': backend returns first byte to be sent + + 'ret': always 0 Another I2C master wants to read data from us. This event should be sent once our own address and the read bit was detected. After returning, the bus driver @@ -88,8 +91,9 @@ should transmit the first byte. * I2C_SLAVE_WRITE_RECEIVED (mandatory) -'val': bus driver delivers received byte -'ret': 0 if the byte should be acked, some errno if the byte should be nacked + 'val': bus driver delivers received byte + + 'ret': 0 if the byte should be acked, some errno if the byte should be nacked Another I2C master has sent a byte to us which needs to be set in 'val'. If 'ret' is zero, the bus driver should ack this byte. If 'ret' is an errno, then the byte @@ -97,8 +101,9 @@ should be nacked. * I2C_SLAVE_READ_PROCESSED (mandatory) -'val': backend returns next byte to be sent -'ret': always 0 + 'val': backend returns next byte to be sent + + 'ret': always 0 The bus driver requests the next byte to be sent to another I2C master in 'val'. Important: This does not mean that the previous byte has been acked, it @@ -111,8 +116,9 @@ your backend, though. * I2C_SLAVE_STOP (mandatory) -'val': unused -'ret': always 0 + 'val': unused + + 'ret': always 0 A stop condition was received. This can happen anytime and the backend should reset its state machine for I2C transfers to be able to receive new requests. @@ -137,7 +143,7 @@ Bus driver support If you want to add slave support to the bus driver: * implement calls to register/unregister the slave and add those to the - struct i2c_algorithm. When registering, you probably need to set the i2c + struct i2c_algorithm. When registering, you probably need to set the I2C slave address and enable slave specific interrupts. If you use runtime pm, you should use pm_runtime_get_sync() because your device usually needs to be powered on always to be able to detect its slave address. When unregistering, @@ -190,4 +196,3 @@ this time of writing. Some points to keep in mind when using buffers: * A master can send STOP at any time. For partially transferred buffers, this means additional code to handle this exception. Such code tends to be error-prone. - diff --git a/Documentation/i2c/smbus-protocol b/Documentation/i2c/smbus-protocol.rst index 092d474f5843..c122ed239f7f 100644 --- a/Documentation/i2c/smbus-protocol +++ b/Documentation/i2c/smbus-protocol.rst @@ -1,5 +1,6 @@ -SMBus Protocol Summary -====================== +================== +The SMBus Protocol +================== The following is a summary of the SMBus protocol. It applies to all revisions of the protocol (1.0, 1.1, and 2.0). @@ -26,150 +27,177 @@ a different protocol operation entirely. Each transaction type corresponds to a functionality flag. Before calling a transaction function, a device driver should always check (just once) for the corresponding functionality flag to ensure that the underlying I2C -adapter supports the transaction in question. See -<file:Documentation/i2c/functionality> for the details. +adapter supports the transaction in question. See :doc:`functionality` for +the details. 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 +=============== ============================================================= +S Start condition +P Stop condition +Rd/Wr (1 bit) Read/Write bit. Rd equals 1, Wr equals 0. +A, NA (1 bit) Acknowledge (ACK) and Not Acknowledge (NACK) 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 +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 +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. +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. +[..] Data sent by I2C device, as opposed to data sent by the host + adapter. +=============== ============================================================= SMBus Quick Command =================== -This sends a single bit to the device, at the place of the Rd/Wr bit. +This sends a single bit to the device, at the place of the Rd/Wr bit:: -A Addr Rd/Wr [A] P + A Addr Rd/Wr [A] P Functionality flag: I2C_FUNC_SMBUS_QUICK -SMBus Receive Byte: i2c_smbus_read_byte() -========================================== +SMBus Receive Byte +================== + +Implemented by i2c_smbus_read_byte() This reads a single byte from a device, without specifying a device register. Some devices are so simple that this interface is enough; for others, it is a shorthand if you want to read the same register as in -the previous SMBus command. +the previous SMBus command:: -S Addr Rd [A] [Data] NA P + S Addr Rd [A] [Data] NA P Functionality flag: I2C_FUNC_SMBUS_READ_BYTE -SMBus Send Byte: i2c_smbus_write_byte() -======================================== +SMBus Send Byte +=============== + +Implemented by i2c_smbus_write_byte() This operation is the reverse of Receive Byte: it sends a single byte to a device. See Receive Byte for more information. -S Addr Wr [A] Data [A] P +:: + + S Addr Wr [A] Data [A] P Functionality flag: I2C_FUNC_SMBUS_WRITE_BYTE -SMBus Read Byte: i2c_smbus_read_byte_data() -============================================ +SMBus Read Byte +=============== + +Implemented by i2c_smbus_read_byte_data() This reads a single byte from a device, from a designated register. -The register is specified through the Comm byte. +The register is specified through the Comm byte:: -S Addr Wr [A] Comm [A] S Addr Rd [A] [Data] NA P + S Addr Wr [A] Comm [A] S Addr Rd [A] [Data] NA P Functionality flag: I2C_FUNC_SMBUS_READ_BYTE_DATA -SMBus Read Word: i2c_smbus_read_word_data() -============================================ +SMBus Read Word +=============== + +Implemented by i2c_smbus_read_word_data() This operation is very like Read Byte; again, data is read from a device, from a designated register that is specified through the Comm -byte. But this time, the data is a complete word (16 bits). +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 + S Addr Wr [A] Comm [A] S Addr Rd [A] [DataLow] A [DataHigh] NA P Functionality flag: I2C_FUNC_SMBUS_READ_WORD_DATA -Note the convenience function i2c_smbus_read_word_swapped is +Note the convenience function i2c_smbus_read_word_swapped() is available for reads where the two data bytes are the other way around (not SMBus compliant, but very popular.) -SMBus Write Byte: i2c_smbus_write_byte_data() -============================================== +SMBus Write Byte +================ + +Implemented by i2c_smbus_write_byte_data() This writes a single byte to a device, to a designated register. The register is specified through the Comm byte. This is the opposite of the Read Byte operation. -S Addr Wr [A] Comm [A] Data [A] P +:: + + S Addr Wr [A] Comm [A] Data [A] P Functionality flag: I2C_FUNC_SMBUS_WRITE_BYTE_DATA -SMBus Write Word: i2c_smbus_write_word_data() -============================================== +SMBus Write Word +================ + +Implemented by i2c_smbus_write_word_data() This is the opposite of the Read Word operation. 16 bits -of data is written to a device, to the designated register that is -specified through the Comm byte. +of data are written to a device, to the designated register that is +specified through the Comm byte:: -S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A] P + S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A] P Functionality flag: I2C_FUNC_SMBUS_WRITE_WORD_DATA -Note the convenience function i2c_smbus_write_word_swapped is +Note the convenience function i2c_smbus_write_word_swapped() is available for writes where the two data bytes are the other way around (not SMBus compliant, but very popular.) -SMBus Process Call: -=================== +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. +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 + S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A] + S Addr Rd [A] [DataLow] A [DataHigh] NA P Functionality flag: I2C_FUNC_SMBUS_PROC_CALL -SMBus Block Read: i2c_smbus_read_block_data() -============================================== +SMBus Block Read +================ + +Implemented by i2c_smbus_read_block_data() -This command reads a block of up to 32 bytes from a device, from a +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 +:: + + S Addr Wr [A] Comm [A] + S Addr Rd [A] [Count] A [Data] A [Data] A ... A [Data] NA P Functionality flag: I2C_FUNC_SMBUS_READ_BLOCK_DATA -SMBus Block Write: i2c_smbus_write_block_data() -================================================ +SMBus Block Write +================= + +Implemented by i2c_smbus_write_block_data() -The opposite of the Block Read command, this writes up to 32 bytes to +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 +:: + + S Addr Wr [A] Comm [A] Count [A] Data [A] Data [A] ... [A] Data [A] P Functionality flag: I2C_FUNC_SMBUS_WRITE_BLOCK_DATA @@ -181,10 +209,10 @@ SMBus Block Write - Block Read Process Call was introduced in Revision 2.0 of the specification. This command selects a device register (through the Comm byte), sends -1 to 31 bytes of data to it, and reads 1 to 31 bytes of data in return. +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 + S Addr Wr [A] Comm [A] Count [A] Data [A] ... + S Addr Rd [A] [Count] A [Data] ... A P Functionality flag: I2C_FUNC_SMBUS_BLOCK_PROC_CALL @@ -197,9 +225,12 @@ 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] +:: + + [S] [HostAddr] [Wr] A [DevAddr] A [DataLow] A [DataHigh] A [P] This is implemented in the following way in the Linux kernel: + * I2C bus drivers which support SMBus Host Notify should report I2C_FUNC_SMBUS_HOST_NOTIFY. * I2C bus drivers trigger SMBus Host Notify by a call to @@ -241,6 +272,7 @@ single interrupt pin on the SMBus master, while still allowing the master to know which slave triggered the interrupt. This is implemented the following way in the Linux kernel: + * I2C bus drivers which support SMBus alert should call i2c_setup_smbus_alert() to setup SMBus alert support. * I2C drivers for devices which can trigger SMBus alerts should implement @@ -250,34 +282,41 @@ This is implemented the following way in the Linux kernel: I2C Block Transactions ====================== -The following I2C block transactions are supported by the -SMBus layer and are described here for completeness. -They are *NOT* defined by the SMBus specification. +The following I2C block transactions are similar to the SMBus Block Read +and Write operations, except these do not have a Count byte. They are +supported by the SMBus layer and are described here for completeness, but +they are *NOT* defined by the SMBus specification. I2C block transactions do not limit the number of bytes transferred but the SMBus layer places a limit of 32 bytes. -I2C Block Read: i2c_smbus_read_i2c_block_data() -================================================ +I2C Block Read +============== + +Implemented by i2c_smbus_read_i2c_block_data() -This command reads a block of bytes from a device, from a -designated register that is specified through the Comm byte. +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 + S Addr Wr [A] Comm [A] + S Addr Rd [A] [Data] A [Data] A ... A [Data] NA P Functionality flag: I2C_FUNC_SMBUS_READ_I2C_BLOCK -I2C Block Write: i2c_smbus_write_i2c_block_data() -================================================== +I2C Block Write +=============== -The opposite of the Block Read command, this writes bytes to +Implemented by i2c_smbus_write_i2c_block_data() + +The opposite of the Block Read command, this writes bytes to a device, to a designated register that is specified through the Comm byte. Note that command lengths of 0, 2, or more bytes are supported as they are indistinguishable from data. -S Addr Wr [A] Comm [A] Data [A] Data [A] ... [A] Data [A] P +:: + + S Addr Wr [A] Comm [A] Data [A] Data [A] ... [A] Data [A] P Functionality flag: I2C_FUNC_SMBUS_WRITE_I2C_BLOCK diff --git a/Documentation/i2c/summary b/Documentation/i2c/summary deleted file mode 100644 index 809541ab352f..000000000000 --- a/Documentation/i2c/summary +++ /dev/null @@ -1,43 +0,0 @@ -I2C and SMBus -============= - -I2C (pronounce: I squared C) is a protocol developed by Philips. It is a -slow two-wire protocol (variable speed, up to 400 kHz), with a high speed -extension (3.4 MHz). It provides an inexpensive bus for connecting many -types of devices with infrequent or low bandwidth communications needs. -I2C is widely used with embedded systems. Some systems use variants that -don't meet branding requirements, and so are not advertised as being I2C. - -SMBus (System Management Bus) is based on the I2C protocol, and is mostly -a subset of I2C protocols and signaling. Many I2C devices will work on an -SMBus, but some SMBus protocols add semantics beyond what is required to -achieve I2C branding. Modern PC mainboards rely on SMBus. The most common -devices connected through SMBus are RAM modules configured using I2C EEPROMs, -and hardware monitoring chips. - -Because the SMBus is mostly a subset of the generalized I2C bus, we can -use its protocols on many I2C systems. However, there are systems that don't -meet both SMBus and I2C electrical constraints; and others which can't -implement all the common SMBus protocol semantics or messages. - - -Terminology -=========== - -When we talk about I2C, we use the following terms: - Bus -> Algorithm - Adapter - Device -> Driver - Client - -An Algorithm driver contains general code that can be used for a whole class -of I2C adapters. Each specific adapter driver either depends on one algorithm -driver, or includes its own implementation. - -A Driver driver (yes, this sounds ridiculous, sorry) contains the general -code to access some type of device. Each detected device gets its own -data in the Client structure. Usually, Driver and Client are more closely -integrated than Algorithm and Adapter. - -For a given configuration, you will need a driver for your I2C bus, and -drivers for your I2C devices (usually one driver for each device). diff --git a/Documentation/i2c/summary.rst b/Documentation/i2c/summary.rst new file mode 100644 index 000000000000..ce7230025b33 --- /dev/null +++ b/Documentation/i2c/summary.rst @@ -0,0 +1,59 @@ +============================= +Introduction to I2C and SMBus +============================= + +I²C (pronounce: I squared C and written I2C in the kernel documentation) is +a protocol developed by Philips. It is a slow two-wire protocol (variable +speed, up to 400 kHz), with a high speed extension (3.4 MHz). It provides +an inexpensive bus for connecting many types of devices with infrequent or +low bandwidth communications needs. I2C is widely used with embedded +systems. Some systems use variants that don't meet branding requirements, +and so are not advertised as being I2C but come under different names, +e.g. TWI (Two Wire Interface), IIC. + +The official I2C specification is the `"I2C-bus specification and user +manual" (UM10204) <https://www.nxp.com/docs/en/user-guide/UM10204.pdf>`_ +published by NXP Semiconductors. + +SMBus (System Management Bus) is based on the I2C protocol, and is mostly +a subset of I2C protocols and signaling. Many I2C devices will work on an +SMBus, but some SMBus protocols add semantics beyond what is required to +achieve I2C branding. Modern PC mainboards rely on SMBus. The most common +devices connected through SMBus are RAM modules configured using I2C EEPROMs, +and hardware monitoring chips. + +Because the SMBus is mostly a subset of the generalized I2C bus, we can +use its protocols on many I2C systems. However, there are systems that don't +meet both SMBus and I2C electrical constraints; and others which can't +implement all the common SMBus protocol semantics or messages. + + +Terminology +=========== + +Using the terminology from the official documentation, the I2C bus connects +one or more *master* chips and one or more *slave* chips. + +.. kernel-figure:: i2c.svg + :alt: Simple I2C bus with one master and 3 slaves + + Simple I2C bus + +A **master** chip is a node that starts communications with slaves. In the +Linux kernel implementation it is called an **adapter** or bus. Adapter +drivers are in the ``drivers/i2c/busses/`` subdirectory. + +An **algorithm** contains general code that can be used to implement a +whole class of I2C adapters. Each specific adapter driver either depends on +an algorithm driver in the ``drivers/i2c/algos/`` subdirectory, or includes +its own implementation. + +A **slave** chip is a node that responds to communications when addressed +by the master. In Linux it is called a **client**. Client drivers are kept +in a directory specific to the feature they provide, for example +``drivers/media/gpio/`` for GPIO expanders and ``drivers/media/i2c/`` for +video-related chips. + +For the example configuration in figure, you will need a driver for your +I2C adapter, and drivers for your I2C devices (usually one driver for each +device). diff --git a/Documentation/i2c/ten-bit-addresses b/Documentation/i2c/ten-bit-addresses.rst index 7b2d11e53a49..5c765aff16d5 100644 --- a/Documentation/i2c/ten-bit-addresses +++ b/Documentation/i2c/ten-bit-addresses.rst @@ -1,3 +1,7 @@ +===================== +I2C Ten-bit Addresses +===================== + 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 @@ -12,6 +16,7 @@ See the I2C specification for the details. The current 10 bit address support is minimal. It should work, however you can expect some problems along the way: + * Not all bus drivers support 10-bit addresses. Some don't because the hardware doesn't support them (SMBus doesn't require 10-bit address support for example), some don't because nobody bothered adding the diff --git a/Documentation/i2c/upgrading-clients b/Documentation/i2c/upgrading-clients.rst index 96392cc5b5c7..27d29032c138 100644 --- a/Documentation/i2c/upgrading-clients +++ b/Documentation/i2c/upgrading-clients.rst @@ -1,3 +1,4 @@ +================================================= Upgrading I2C Drivers to the new 2.6 Driver Model ================================================= @@ -13,21 +14,22 @@ the old to the new new binding methods. Example old-style driver ------------------------ +:: -struct example_state { + struct example_state { struct i2c_client client; .... -}; + }; -static struct i2c_driver example_driver; + static struct i2c_driver example_driver; -static unsigned short ignore[] = { I2C_CLIENT_END }; -static unsigned short normal_addr[] = { OUR_ADDR, I2C_CLIENT_END }; + static unsigned short ignore[] = { I2C_CLIENT_END }; + static unsigned short normal_addr[] = { OUR_ADDR, I2C_CLIENT_END }; -I2C_CLIENT_INSMOD; + I2C_CLIENT_INSMOD; -static int example_attach(struct i2c_adapter *adap, int addr, int kind) -{ + static int example_attach(struct i2c_adapter *adap, int addr, int kind) + { struct example_state *state; struct device *dev = &adap->dev; /* to use for dev_ reports */ int ret; @@ -59,31 +61,31 @@ static int example_attach(struct i2c_adapter *adap, int addr, int kind) dev_info(dev, "example client created\n"); return 0; -} + } -static int example_detach(struct i2c_client *client) -{ + static int example_detach(struct i2c_client *client) + { struct example_state *state = i2c_get_clientdata(client); i2c_detach_client(client); kfree(state); return 0; -} + } -static int example_attach_adapter(struct i2c_adapter *adap) -{ + static int example_attach_adapter(struct i2c_adapter *adap) + { return i2c_probe(adap, &addr_data, example_attach); -} + } -static struct i2c_driver example_driver = { - .driver = { + static struct i2c_driver example_driver = { + .driver = { .owner = THIS_MODULE, .name = "example", .pm = &example_pm_ops, }, .attach_adapter = example_attach_adapter, .detach_client = example_detach, -}; + }; Updating the client @@ -93,38 +95,38 @@ The new style binding model will check against a list of supported devices and their associated address supplied by the code registering the busses. This means that the driver .attach_adapter and .detach_client methods can be removed, along with the addr_data, -as follows: +as follows:: -- static struct i2c_driver example_driver; + - static struct i2c_driver example_driver; -- static unsigned short ignore[] = { I2C_CLIENT_END }; -- static unsigned short normal_addr[] = { OUR_ADDR, I2C_CLIENT_END }; + - static unsigned short ignore[] = { I2C_CLIENT_END }; + - static unsigned short normal_addr[] = { OUR_ADDR, I2C_CLIENT_END }; -- I2C_CLIENT_INSMOD; + - I2C_CLIENT_INSMOD; -- static int example_attach_adapter(struct i2c_adapter *adap) -- { -- return i2c_probe(adap, &addr_data, example_attach); -- } + - static int example_attach_adapter(struct i2c_adapter *adap) + - { + - return i2c_probe(adap, &addr_data, example_attach); + - } - static struct i2c_driver example_driver = { -- .attach_adapter = example_attach_adapter, -- .detach_client = example_detach, - } + static struct i2c_driver example_driver = { + - .attach_adapter = example_attach_adapter, + - .detach_client = example_detach, + } -Add the probe and remove methods to the i2c_driver, as so: +Add the probe and remove methods to the i2c_driver, as so:: - static struct i2c_driver example_driver = { -+ .probe = example_probe, -+ .remove = example_remove, - } + static struct i2c_driver example_driver = { + + .probe = example_probe, + + .remove = example_remove, + } Change the example_attach method to accept the new parameters -which include the i2c_client that it will be working with: +which include the i2c_client that it will be working with:: -- static int example_attach(struct i2c_adapter *adap, int addr, int kind) -+ static int example_probe(struct i2c_client *client, -+ const struct i2c_device_id *id) + - static int example_attach(struct i2c_adapter *adap, int addr, int kind) + + static int example_probe(struct i2c_client *client, + + const struct i2c_device_id *id) Change the name of example_attach to example_probe to align it with the i2c_driver entry names. The rest of the probe routine will now need to be @@ -132,57 +134,59 @@ changed as the i2c_client has already been setup for use. The necessary client fields have already been setup before the probe function is called, so the following client setup -can be removed: +can be removed:: -- example->client.addr = addr; -- example->client.flags = 0; -- example->client.adapter = adap; -- -- strscpy(client->i2c_client.name, "example", sizeof(client->i2c_client.name)); + - example->client.addr = addr; + - example->client.flags = 0; + - example->client.adapter = adap; + - + - strscpy(client->i2c_client.name, "example", sizeof(client->i2c_client.name)); -The i2c_set_clientdata is now: +The i2c_set_clientdata is now:: -- i2c_set_clientdata(&state->client, state); -+ i2c_set_clientdata(client, state); + - i2c_set_clientdata(&state->client, state); + + i2c_set_clientdata(client, state); The call to i2c_attach_client is no longer needed, if the probe routine exits successfully, then the driver will be automatically -attached by the core. Change the probe routine as so: +attached by the core. Change the probe routine as so:: -- ret = i2c_attach_client(&state->i2c_client); -- if (ret < 0) { -- dev_err(dev, "failed to attach client\n"); -- kfree(state); -- return ret; -- } + - ret = i2c_attach_client(&state->i2c_client); + - if (ret < 0) { + - dev_err(dev, "failed to attach client\n"); + - kfree(state); + - return ret; + - } Remove the storage of 'struct i2c_client' from the 'struct example_state' as we are provided with the i2c_client in our example_probe. Instead we store a pointer to it for when it is needed. -struct example_state { -- struct i2c_client client; -+ struct i2c_client *client; +:: + + struct example_state { + - struct i2c_client client; + + struct i2c_client *client; -the new i2c client as so: +the new i2c client as so:: -- struct device *dev = &adap->dev; /* to use for dev_ reports */ -+ struct device *dev = &i2c_client->dev; /* to use for dev_ reports */ + - struct device *dev = &adap->dev; /* to use for dev_ reports */ + + struct device *dev = &i2c_client->dev; /* to use for dev_ reports */ And remove the change after our client is attached, as the driver no -longer needs to register a new client structure with the core: +longer needs to register a new client structure with the core:: -- dev = &state->i2c_client.dev; + - dev = &state->i2c_client.dev; In the probe routine, ensure that the new state has the client stored -in it: +in it:: -static int example_probe(struct i2c_client *i2c_client, + static int example_probe(struct i2c_client *i2c_client, const struct i2c_device_id *id) -{ + { struct example_state *state; - struct device *dev = &i2c_client->dev; + struct device *dev = &i2c_client->dev; int ret; state = kzalloc(sizeof(struct example_state), GFP_KERNEL); @@ -191,48 +195,50 @@ static int example_probe(struct i2c_client *i2c_client, return -ENOMEM; } -+ state->client = i2c_client; + + state->client = i2c_client; Update the detach method, by changing the name to _remove and to delete the i2c_detach_client call. It is possible that you can also remove the ret variable as it is not needed for any of the core functions. -- static int example_detach(struct i2c_client *client) -+ static int example_remove(struct i2c_client *client) -{ +:: + + - static int example_detach(struct i2c_client *client) + + static int example_remove(struct i2c_client *client) + { struct example_state *state = i2c_get_clientdata(client); -- i2c_detach_client(client); + - i2c_detach_client(client); And finally ensure that we have the correct ID table for the i2c-core -and other utilities: +and other utilities:: -+ struct i2c_device_id example_idtable[] = { -+ { "example", 0 }, -+ { } -+}; -+ -+MODULE_DEVICE_TABLE(i2c, example_idtable); + + struct i2c_device_id example_idtable[] = { + + { "example", 0 }, + + { } + +}; + + + +MODULE_DEVICE_TABLE(i2c, example_idtable); -static struct i2c_driver example_driver = { - .driver = { + static struct i2c_driver example_driver = { + .driver = { .owner = THIS_MODULE, .name = "example", }, -+ .id_table = example_ids, + + .id_table = example_ids, -Our driver should now look like this: +Our driver should now look like this:: -struct example_state { + struct example_state { struct i2c_client *client; .... -}; + }; -static int example_probe(struct i2c_client *client, - const struct i2c_device_id *id) -{ + static int example_probe(struct i2c_client *client, + const struct i2c_device_id *id) + { struct example_state *state; struct device *dev = &client->dev; @@ -250,25 +256,25 @@ static int example_probe(struct i2c_client *client, dev_info(dev, "example client created\n"); return 0; -} + } -static int example_remove(struct i2c_client *client) -{ + static int example_remove(struct i2c_client *client) + { struct example_state *state = i2c_get_clientdata(client); kfree(state); return 0; -} + } -static struct i2c_device_id example_idtable[] = { + static struct i2c_device_id example_idtable[] = { { "example", 0 }, { } -}; + }; -MODULE_DEVICE_TABLE(i2c, example_idtable); + MODULE_DEVICE_TABLE(i2c, example_idtable); -static struct i2c_driver example_driver = { - .driver = { + static struct i2c_driver example_driver = { + .driver = { .owner = THIS_MODULE, .name = "example", .pm = &example_pm_ops, @@ -276,4 +282,4 @@ static struct i2c_driver example_driver = { .id_table = example_idtable, .probe = example_probe, .remove = example_remove, -}; + }; diff --git a/Documentation/i2c/writing-clients b/Documentation/i2c/writing-clients.rst index a755b141fa4a..978cc8210bf3 100644 --- a/Documentation/i2c/writing-clients +++ b/Documentation/i2c/writing-clients.rst @@ -1,3 +1,7 @@ +=============================== +Implementing I2C device drivers +=============================== + This is a small guide for those who want to write kernel drivers for I2C or SMBus devices, using Linux as the protocol host/master (not slave). @@ -12,7 +16,7 @@ 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 +it for non-exported symbols too. We will use the prefix ``foo_`` in this tutorial. @@ -25,15 +29,17 @@ routines, and should be zero-initialized except for fields with data you provide. A client structure holds device-specific information like the driver model device node, and its I2C address. -static struct i2c_device_id foo_idtable[] = { +:: + + static struct i2c_device_id foo_idtable[] = { { "foo", my_id_for_foo }, { "bar", my_id_for_bar }, { } -}; + }; -MODULE_DEVICE_TABLE(i2c, foo_idtable); + MODULE_DEVICE_TABLE(i2c, foo_idtable); -static struct i2c_driver foo_driver = { + static struct i2c_driver foo_driver = { .driver = { .name = "foo", .pm = &foo_pm_ops, /* optional */ @@ -49,7 +55,7 @@ static struct i2c_driver foo_driver = { .shutdown = foo_shutdown, /* optional */ .command = foo_command, /* optional, deprecated */ -} + } The name field is the driver name, and must not contain spaces. It should match the module name (if the driver can be compiled as a module), @@ -64,16 +70,18 @@ below. Extra client data ================= -Each client structure has a special `data' field that can point to any +Each client structure has a special ``data`` field that can point to any structure at all. You should use this to keep device-specific data. +:: + /* store the value */ void i2c_set_clientdata(struct i2c_client *client, void *data); /* retrieve the value */ void *i2c_get_clientdata(const struct i2c_client *client); -Note that starting with kernel 2.6.34, you don't have to set the `data' field +Note that starting with kernel 2.6.34, you don't have to set the ``data`` field to NULL in remove() or if probe() failed anymore. The i2c-core does this automatically on these occasions. Those are also the only times the core will touch this field. @@ -87,30 +95,30 @@ to gather information from the client, or write new information to the client. I have found it useful to define foo_read and foo_write functions for this. -For some cases, it will be easier to call the i2c functions directly, +For some cases, it will be easier to call the I2C functions directly, but many chips have some kind of register-value idea that can easily be encapsulated. The below functions are simple examples, and should not be copied -literally. +literally:: -int foo_read_value(struct i2c_client *client, u8 reg) -{ + 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) -{ + int foo_write_value(struct i2c_client *client, u8 reg, u16 value) + { if (reg == 0x10) /* Impossible to write - driver error! */ return -EINVAL; else if (reg < 0x10) /* byte-sized register */ return i2c_smbus_write_byte_data(client, reg, value); else /* word-sized register */ return i2c_smbus_write_word_data(client, reg, value); -} + } Probing and attaching @@ -145,6 +153,8 @@ I2C device drivers using this binding model work just like any other kind of driver in Linux: they provide a probe() method to bind to those devices, and a remove() method to unbind. +:: + static int foo_probe(struct i2c_client *client, const struct i2c_device_id *id); static int foo_remove(struct i2c_client *client); @@ -165,8 +175,8 @@ Device Creation If you know for a fact that an I2C device is connected to a given I2C bus, you can instantiate that device by simply filling an i2c_board_info structure with the device address and driver name, and calling -i2c_new_device(). This will create the device, then the driver core will -take care of finding the right driver and will call its probe() method. +i2c_new_client_device(). This will create the device, then the driver core +will take care of finding the right driver and will call its probe() method. If a driver supports different device types, you can specify the type you want using the type field. You can also specify an IRQ and platform data if needed. @@ -175,15 +185,15 @@ Sometimes you know that a device is connected to a given I2C bus, but you don't know the exact address it uses. This happens on TV adapters for example, where the same driver supports dozens of slightly different models, and I2C device addresses change from one model to the next. In -that case, you can use the i2c_new_probed_device() variant, which is -similar to i2c_new_device(), except that it takes an additional list of -possible I2C addresses to probe. A device is created for the first +that case, you can use the i2c_new_scanned_device() variant, which is +similar to i2c_new_client_device(), except that it takes an additional list +of possible I2C addresses to probe. A device is created for the first responsive address in the list. If you expect more than one device to be -present in the address range, simply call i2c_new_probed_device() that +present in the address range, simply call i2c_new_scanned_device() that many times. -The call to i2c_new_device() or i2c_new_probed_device() typically happens -in the I2C bus driver. You may want to save the returned i2c_client +The call to i2c_new_client_device() or i2c_new_scanned_device() typically +happens in the I2C bus driver. You may want to save the returned i2c_client reference for later use. @@ -226,11 +236,11 @@ possible. Device Deletion --------------- -Each I2C device which has been created using i2c_new_device() or -i2c_new_probed_device() can be unregistered by calling +Each I2C device which has been created using i2c_new_client_device() +or i2c_new_scanned_device() can be unregistered by calling i2c_unregister_device(). If you don't call it explicitly, it will be -called automatically before the underlying I2C bus itself is removed, as a -device can't survive its parent in the device driver model. +called automatically before the underlying I2C bus itself is removed, +as a device can't survive its parent in the device driver model. Initializing the driver @@ -240,37 +250,41 @@ When the kernel is booted, or when your foo driver module is inserted, you have to do some initializing. Fortunately, just registering the driver module is usually enough. -static int __init foo_init(void) -{ +:: + + static int __init foo_init(void) + { return i2c_add_driver(&foo_driver); -} -module_init(foo_init); + } + module_init(foo_init); -static void __exit foo_cleanup(void) -{ + static void __exit foo_cleanup(void) + { i2c_del_driver(&foo_driver); -} -module_exit(foo_cleanup); + } + module_exit(foo_cleanup); -The module_i2c_driver() macro can be used to reduce above code. + The module_i2c_driver() macro can be used to reduce above code. -module_i2c_driver(foo_driver); + module_i2c_driver(foo_driver); -Note that some functions are marked by `__init'. These functions can +Note that some functions are marked by ``__init``. These functions can be removed after kernel booting (or module loading) is completed. -Likewise, functions marked by `__exit' are dropped by the compiler when +Likewise, functions marked by ``__exit`` are dropped by the compiler when the code is built into the kernel, as they would never be called. Driver Information ================== -/* Substitute your own name and email address */ -MODULE_AUTHOR("Frodo Looijaard <frodol@dds.nl>" -MODULE_DESCRIPTION("Driver for Barf Inc. Foo I2C devices"); +:: -/* a few non-GPL license types are also allowed */ -MODULE_LICENSE("GPL"); + /* Substitute your own name and email address */ + MODULE_AUTHOR("Frodo Looijaard <frodol@dds.nl>" + MODULE_DESCRIPTION("Driver for Barf Inc. Foo I2C devices"); + + /* a few non-GPL license types are also allowed */ + MODULE_LICENSE("GPL"); Power Management @@ -323,33 +337,39 @@ commands, but only some of them understand plain I2C! Plain I2C communication ----------------------- +:: + int i2c_master_send(struct i2c_client *client, const char *buf, int count); int i2c_master_recv(struct i2c_client *client, char *buf, int count); These routines read and write some bytes from/to a client. The client -contains the i2c address, so you do not have to include it. The second +contains the I2C address, so you do not have to include it. The second parameter contains the bytes to read/write, the third the number of bytes to read/write (must be less than the length of the buffer, also should be less than 64k since msg.len is u16.) Returned is the actual number of bytes read/written. +:: + int i2c_transfer(struct i2c_adapter *adap, struct i2c_msg *msg, int num); This sends a series of messages. Each message can be a read or write, and they can be mixed in any way. The transactions are combined: no -stop bit is sent between transaction. The i2c_msg structure contains -for each message the client address, the number of bytes of the message -and the message data itself. +stop condition is issued 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 +You can read the file ``i2c-protocol`` for more information about the actual I2C protocol. SMBus communication ------------------- +:: + s32 i2c_smbus_xfer(struct i2c_adapter *adapter, u16 addr, unsigned short flags, char read_write, u8 command, int size, union i2c_smbus_data *data); @@ -357,6 +377,8 @@ SMBus communication This is the generic SMBus function. All functions below are implemented in terms of it. Never use this function directly! +:: + s32 i2c_smbus_read_byte(struct i2c_client *client); s32 i2c_smbus_write_byte(struct i2c_client *client, u8 value); s32 i2c_smbus_read_byte_data(struct i2c_client *client, u8 command); @@ -376,7 +398,7 @@ in terms of it. Never use this function directly! const u8 *values); These ones were removed from i2c-core because they had no users, but could -be added back later if needed: +be added back later if needed:: s32 i2c_smbus_write_quick(struct i2c_client *client, u8 value); s32 i2c_smbus_process_call(struct i2c_client *client, @@ -389,7 +411,7 @@ transactions return 0 on success; the 'read' transactions return the read value, except for block transactions, which return the number of values read. The block buffers need not be longer than 32 bytes. -You can read the file `smbus-protocol' for more information about the +You can read the file ``smbus-protocol`` for more information about the actual SMBus protocol. @@ -397,7 +419,7 @@ General purpose routines ======================== Below all general purpose routines are listed, that were not mentioned -before. +before:: /* Return the adapter number for a specific adapter */ int i2c_adapter_id(struct i2c_adapter *adap); |
