code:
Kernel driver zl6100
====================

Supported chips:

  * Renesas / Intersil / Zilker Labs ZL2004

    Prefix: 'zl2004'

    Addresses scanned: -

    Datasheet: https://www.renesas.com/us/en/document/dst/zl2004-datasheet.pdf

  * Renesas / Intersil / Zilker Labs ZL2005

    Prefix: 'zl2005'

    Addresses scanned: -

    Datasheet: https://www.renesas.com/us/en/document/dst/zl2005-datasheet.pdf

  * Renesas / Intersil / Zilker Labs ZL2006

    Prefix: 'zl2006'

    Addresses scanned: -

    Datasheet: https://www.renesas.com/us/en/document/dst/zl2006-datasheet.pdf

  * Renesas / Intersil / Zilker Labs ZL2008

    Prefix: 'zl2008'

    Addresses scanned: -

    Datasheet: https://www.renesas.com/us/en/document/dst/zl2008-datasheet.pdf

  * Renesas / Intersil / Zilker Labs ZL2105

    Prefix: 'zl2105'

    Addresses scanned: -

    Datasheet: https://www.renesas.com/us/en/document/dst/zl2105-datasheet.pdf

  * Renesas / Intersil / Zilker Labs ZL2106

    Prefix: 'zl2106'

    Addresses scanned: -

    Datasheet: https://www.renesas.com/us/en/document/dst/zl2106-datasheet.pdf

  * Renesas / Intersil / Zilker Labs ZL6100

    Prefix: 'zl6100'

    Addresses scanned: -

    Datasheet: https://www.renesas.com/us/en/document/dst/zl6100-datasheet.pdf

  * Renesas / Intersil / Zilker Labs ZL6105

    Prefix: 'zl6105'

    Addresses scanned: -

    Datasheet: https://www.renesas.com/us/en/document/dst/zl6105-datasheet.pdf

  * Renesas / Intersil / Zilker Labs ZL8802

    Prefix: 'zl8802'

    Addresses scanned: -

    Datasheet: https://www.renesas.com/us/en/document/dst/zl8802-datasheet

  * Renesas / Intersil / Zilker Labs ZL9101M

    Prefix: 'zl9101'

    Addresses scanned: -

    Datasheet: https://www.renesas.com/us/en/document/dst/zl9101m-datasheet

  * Renesas / Intersil / Zilker Labs ZL9117M

    Prefix: 'zl9117'

    Addresses scanned: -

    Datasheet: https://www.renesas.com/us/en/document/dst/zl9117m-datasheet

  * Renesas / Intersil / Zilker Labs ZLS1003, ZLS4009

    Prefix: 'zls1003', zls4009

    Addresses scanned: -

    Datasheet: Not published

  * Flex BMR450, BMR451

    Prefix: 'bmr450', 'bmr451'

    Addresses scanned: -

    Datasheet:

https://flexpowermodules.com/resources/fpm-techspec-bmr450-digital-pol-regulators-20a

  * Flex BMR462, BMR463, BMR464

    Prefixes: 'bmr462', 'bmr463', 'bmr464'

    Addresses scanned: -

    Datasheet: https://flexpowermodules.com/resources/fpm-techspec-bmr462

  * Flex BMR465, BMR467

    Prefixes: 'bmr465', 'bmr467'

    Addresses scanned: -

    Datasheet: https://flexpowermodules.com/resources/fpm-techspec-bmr465-digital-pol

  * Flex BMR466

    Prefixes: 'bmr466'

    Addresses scanned: -

    Datasheet: https://flexpowermodules.com/resources/fpm-techspec-bmr466-8x12

  * Flex BMR469

    Prefixes: 'bmr469'

    Addresses scanned: -

    Datasheet: https://flexpowermodules.com/resources/fpm-techspec-bmr4696001

Author: Guenter Roeck <linux@roeck-us.net>

Description
-----------

This driver supports hardware monitoring for Renesas / Intersil / Zilker Labs
ZL6100 and compatible digital DC-DC controllers.

The driver is a client driver to the core PMBus driver. Please see
Documentation/hwmon/pmbus.rst and Documentation.hwmon/pmbus-core for details
on PMBus client drivers.

Usage Notes
-----------

This driver does not auto-detect devices. You will have to instantiate the
devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
details.

.. warning::

  Do not access chip registers using the i2cdump command, and do not use
  any of the i2ctools commands on a command register used to save and restore
  configuration data (0x11, 0x12, 0x15, 0x16, and 0xf4). The chips supported by
  this driver interpret any access to those command registers (including read
  commands) as request to execute the command in question. Unless write accesses
  to those registers are protected, this may result in power loss, board resets,
  and/or Flash corruption. Worst case, your board may turn into a brick.

Platform data support
---------------------

The driver supports standard PMBus driver platform data.

Module parameters
-----------------

delay
-----

Renesas/Intersil/Zilker Labs DC-DC controllers require a minimum interval
between I2C bus accesses. According to Intersil, the minimum interval is 2 ms,
though 1 ms appears to be sufficient and has not caused any problems in testing.
The problem is known to affect all currently supported chips. For manual override,
the driver provides a writeable module parameter, 'delay', which can be used
to set the interval to a value between 0 and 65,535 microseconds.

Sysfs entries
-------------

The following attributes are supported. Limits are read-write; all other
attributes are read-only.

======================= ========================================================
in1_label		"vin"
in1_input		Measured input voltage.
in1_min			Minimum input voltage.
in1_max			Maximum input voltage.
in1_lcrit		Critical minimum input voltage.
in1_crit		Critical maximum input voltage.
in1_min_alarm		Input voltage low alarm.
in1_max_alarm		Input voltage high alarm.
in1_lcrit_alarm		Input voltage critical low alarm.
in1_crit_alarm		Input voltage critical high alarm.

in2_label		"vmon"
in2_input		Measured voltage on VMON (ZL2004) or VDRV (ZL9101M,
			ZL9117M) pin. Reported voltage is 16x the voltage on the
			pin (adjusted internally by the chip).
in2_lcrit		Critical minimum VMON/VDRV Voltage.
in2_crit		Critical maximum VMON/VDRV voltage.
in2_lcrit_alarm		VMON/VDRV voltage critical low alarm.
in2_crit_alarm		VMON/VDRV voltage critical high alarm.

			vmon attributes are supported on ZL2004, ZL8802,
			ZL9101M, ZL9117M and ZLS4009 only.

inX_label		"vout[12]"
inX_input		Measured output voltage.
inX_lcrit		Critical minimum output Voltage.
inX_crit		Critical maximum output voltage.
inX_lcrit_alarm		Critical output voltage critical low alarm.
inX_crit_alarm		Critical output voltage critical high alarm.

			X is 3 for ZL2004, ZL9101M, and ZL9117M,
			3, 4 for ZL8802 and 2 otherwise.

curr1_label		"iin"
curr1_input		Measured input current.

			iin attributes are supported on ZL8802 only

currY_label		"iout[12]"
currY_input		Measured output current.
currY_lcrit		Critical minimum output current.
currY_crit		Critical maximum output current.
currY_lcrit_alarm	Output current critical low alarm.
currY_crit_alarm	Output current critical high alarm.

			Y is 2, 3 for ZL8802, 1 otherwise

temp[12]_input		Measured temperature.
temp[12]_min		Minimum temperature.
temp[12]_max		Maximum temperature.
temp[12]_lcrit		Critical low temperature.
temp[12]_crit		Critical high temperature.
temp[12]_min_alarm	Chip temperature low alarm.
temp[12]_max_alarm	Chip temperature high alarm.
temp[12]_lcrit_alarm	Chip temperature critical low alarm.
temp[12]_crit_alarm	Chip temperature critical high alarm.
======================= ========================================================


code:
=========================
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>

Description
-----------

This is the driver for the SMB Host controller on Acer Labs Inc. (ALI)
M1535 South Bridge.

The M1535 is a South bridge for portable systems. It is very similar to the
M15x3 South bridges also produced by Acer Labs Inc.  Some of the registers
within the part have moved and some have been redefined slightly.
Additionally, the sequencing of the SMBus transactions has been modified to
be more consistent with the sequencing recommended by the manufacturer and
observed through testing.  These changes are reflected in this driver and
can be identified by comparing this driver to the i2c-ali15x3 driver. For
an overview of these chips see http://www.acerlabs.com

The SMB controller is part of the M7101 device, which is an ACPI-compliant
Power Management Unit (PMU).

The whole M7101 device has to be enabled for the SMB to work. You can't
just enable the SMB alone. The SMB and the ACPI have separate I/O spaces.
We make sure that the SMB is enabled. We leave the ACPI alone.

Features
--------

This driver controls the SMB Host only. This driver does not use
interrupts.

repo_name: angery/linux


code:
=========================
Kernel driver i2c-ali1563
=========================

Supported adapters:
  * Acer Labs, Inc. ALI 1563 (south bridge)

    Datasheet: Now under NDA
	http://www.ali.com.tw/

Author: Patrick Mochel <mochel@digitalimplant.org>

Description
-----------

This is the driver for the SMB Host controller on Acer Labs Inc. (ALI)
M1563 South Bridge.

For an overview of these chips see http://www.acerlabs.com

The M1563 southbridge is deceptively similar to the M1533, with a few
notable exceptions. One of those happens to be the fact they upgraded the
i2c core to be SMBus 2.0 compliant, and happens to be almost identical to
the i2c controller found in the Intel 801 south bridges.

Features
--------

This driver controls the SMB Host only. This driver does not use
interrupts.


code:
=========================
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>

Module Parameters
-----------------

* force_addr: int
    Initialize the base address of the i2c controller

Notes
-----

The force_addr parameter is useful for boards that don't set the address in
the BIOS. Does not do a PCI force; the device must still be present in
lspci. Don't use this unless the driver complains that the base address is
not set.

Example::

    modprobe i2c-ali15x3 force_addr=0xe800

SMBus periodically hangs on ASUS P5A motherboards and can only be cleared
by a power cycle. Cause unknown (see Issues below).

Description
-----------

This is the driver for the SMB Host controller on Acer Labs Inc. (ALI)
M1541 and M1543C South Bridges.

The M1543C is a South bridge for desktop systems.

The M1541 is a South bridge for portable systems.

They are part of the following ALI chipsets:

 * "Aladdin Pro 2" includes the M1621 Slot 1 North bridge with AGP and
   100MHz CPU Front Side bus
 * "Aladdin V" includes the M1541 Socket 7 North bridge with AGP and 100MHz
   CPU Front Side bus

   Some Aladdin V motherboards:
	- Asus P5A
	- Atrend ATC-5220
	- BCM/GVC VP1541
	- Biostar M5ALA
	- Gigabyte GA-5AX (Generally doesn't work because the BIOS doesn't
	  enable the 7101 device!)
	- Iwill XA100 Plus
	- Micronics C200
	- Microstar (MSI) MS-5169

  * "Aladdin IV" includes the M1541 Socket 7 North bridge
    with host bus up to 83.3 MHz.

For an overview of these chips see http://www.acerlabs.com. At this time the
full data sheets on the web site are password protected, however if you
contact the ALI office in San Jose they may give you the password.

The M1533/M1543C devices appear as FOUR separate devices on the PCI bus. An
output of lspci will show something similar to the following::

  00:02.0 USB Controller: Acer Laboratories Inc. M5237 (rev 03)
  00:03.0 Bridge: Acer Laboratories Inc. M7101      <= THIS IS THE ONE WE NEED
  00:07.0 ISA bridge: Acer Laboratories Inc. M1533 (rev c3)
  00:0f.0 IDE interface: Acer Laboratories Inc. M5229 (rev c1)

.. important::

   If you have a M1533 or M1543C on the board and you get
   "ali15x3: Error: Can't detect ali15x3!"
   then run lspci.

   If you see the 1533 and 5229 devices but NOT the 7101 device,
   then you must enable ACPI, the PMU, SMB, or something similar
   in the BIOS.

   The driver won't work if it can't find the M7101 device.

The SMB controller is part of the M7101 device, which is an ACPI-compliant
Power Management Unit (PMU).

The whole M7101 device has to be enabled for the SMB to work. You can't
just enable the SMB alone. The SMB and the ACPI have separate I/O spaces.
We make sure that the SMB is enabled. We leave the ACPI alone.

Features
--------

This driver controls the SMB Host only. The SMB Slave
controller on the M15X3 is not enabled. This driver does not use
interrupts.

Issues
------

This driver requests the I/O space for only the SMB
registers. It doesn't use the ACPI region.

On the ASUS P5A motherboard, there are several reports that
the SMBus will hang and this can only be resolved by
powering off the computer. It appears to be worse when the board
gets hot, for example under heavy CPU load, or in the summer.
There may be electrical problems on this board.
On the P5A, the W83781D sensor chip is on both the ISA and
SMBus. Therefore the SMBus hangs can generally be avoided
by accessing the W83781D on the ISA bus only.


code:
=========================
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.


code:
========================
Kernel driver i2c-amd756
========================

Supported adapters:
  * AMD 756
  * AMD 766
  * AMD 768
  * AMD 8111

    Datasheets: Publicly available on AMD website

  * nVidia nForce

    Datasheet: Unavailable

Authors:
	- Frodo Looijaard <frodol@dds.nl>,
	- Philip Edelbrock <phil@netroedge.com>

Description
-----------

This driver supports the AMD 756, 766, 768 and 8111 Peripheral Bus
Controllers, and the nVidia nForce.

Note that for the 8111, there are two SMBus adapters. The SMBus 1.0 adapter
is supported by this driver, and the SMBus 2.0 adapter is supported by the
i2c-amd8111 driver.


code:
=========================
Kernel driver i2c-adm8111
=========================

Supported adapters:
    * AMD-8111 SMBus 2.0 PCI interface

Datasheets:
	AMD datasheet not yet available, but almost everything can be found
	in the publicly available ACPI 2.0 specification, which the adapter
	follows.

Author: Vojtech Pavlik <vojtech@suse.cz>

Description
-----------

If you see something like this::

  00:07.2 SMBus: Advanced Micro Devices [AMD] AMD-8111 SMBus 2.0 (rev 02)
          Subsystem: Advanced Micro Devices [AMD] AMD-8111 SMBus 2.0
          Flags: medium devsel, IRQ 19
          I/O ports at d400 [size=32]

in your ``lspci -v``, then this driver is for your chipset.

Process Call Support
--------------------

Supported.

SMBus 2.0 Support
-----------------

Supported. Both PEC and block process call support is implemented. Slave
mode or host notification are not yet implemented.

Notes
-----

Note that for the 8111, there are two SMBus adapters. The SMBus 2.0 adapter
is supported by this driver, and the SMBus 1.0 adapter is supported by the
i2c-amd756 driver.


code:
============================
Kernel driver i2c-diolan-u2c
============================

Supported adapters:
  * Diolan U2C-12 I2C-USB adapter

    Documentation:
	http://www.diolan.com/i2c/u2c12.html

Author: Guenter Roeck <linux@roeck-us.net>

Description
-----------

This is the driver for the Diolan U2C-12 USB-I2C adapter.

The Diolan U2C-12 I2C-USB Adapter provides a low cost solution to connect
a computer to I2C slave devices using a USB interface. It also supports
connectivity to SPI devices.

This driver only supports the I2C interface of U2C-12. The driver does not use
interrupts.

Module parameters
-----------------

* frequency: I2C bus frequency


code:
======================
Kernel driver i2c-i801
======================

Supported adapters:
  * Intel 82801AA and 82801AB (ICH and ICH0 - part of the
    '810' and '810E' chipsets)
  * Intel 82801BA (ICH2 - part of the '815E' chipset)
  * Intel 82801CA/CAM (ICH3)
  * Intel 82801DB (ICH4) (HW PEC supported)
  * Intel 82801EB/ER (ICH5) (HW PEC supported)
  * Intel 6300ESB
  * Intel 82801FB/FR/FW/FRW (ICH6)
  * Intel 82801G (ICH7)
  * Intel 631xESB/632xESB (ESB2)
  * Intel 82801H (ICH8)
  * Intel 82801I (ICH9)
  * Intel EP80579 (Tolapai)
  * Intel 82801JI (ICH10)
  * Intel 5/3400 Series (PCH)
  * Intel 6 Series (PCH)
  * Intel Patsburg (PCH)
  * Intel DH89xxCC (PCH)
  * Intel Panther Point (PCH)
  * Intel Lynx Point (PCH)
  * Intel Avoton (SOC)
  * Intel Wellsburg (PCH)
  * Intel Coleto Creek (PCH)
  * Intel Wildcat Point (PCH)
  * Intel BayTrail (SOC)
  * Intel Braswell (SOC)
  * Intel Sunrise Point (PCH)
  * Intel Kaby Lake (PCH)
  * Intel DNV (SOC)
  * Intel Broxton (SOC)
  * Intel Lewisburg (PCH)
  * Intel Gemini Lake (SOC)
  * Intel Cannon Lake (PCH)
  * Intel Cedar Fork (PCH)
  * Intel Ice Lake (PCH)
  * Intel Comet Lake (PCH)
  * Intel Elkhart Lake (PCH)
  * Intel Tiger Lake (PCH)
  * Intel Jasper Lake (SOC)
  * Intel Emmitsburg (PCH)
  * Intel Alder Lake (PCH)
  * Intel Raptor Lake (PCH)
  * Intel Meteor 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>

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

The ICH (properly known as the 82801AA), ICH0 (82801AB), ICH2 (82801BA),
ICH3 (82801CA/CAM) and later devices (PCH) are Intel chips that are a part of
Intel's '810' chipset for Celeron-based PCs, '810E' chipset for
Pentium-based PCs, '815E' chipset, and others.

The ICH chips contain at least SEVEN separate PCI functions in TWO logical
PCI devices. An output of lspci will show something similar to the
following::

  00:1e.0 PCI bridge: Intel Corporation: Unknown device 2418 (rev 01)
  00:1f.0 ISA bridge: Intel Corporation: Unknown device 2410 (rev 01)
  00:1f.1 IDE interface: Intel Corporation: Unknown device 2411 (rev 01)
  00:1f.2 USB Controller: Intel Corporation: Unknown device 2412 (rev 01)
  00:1f.3 Unknown class [0c05]: Intel Corporation: Unknown device 2413 (rev 01)

The SMBus controller is function 3 in device 1f. Class 0c05 is SMBus Serial
Controller.

The ICH chips are quite similar to Intel's PIIX4 chip, at least in the
SMBus controller.

Process Call Support
--------------------

Block process call is supported on the 82801EB (ICH5) and later chips.

I2C Block Read Support
----------------------

I2C block read is supported on the 82801EB (ICH5) and later chips.

SMBus 2.0 Support
-----------------

The 82801DB (ICH4) and later chips support several SMBus 2.0 features.

Interrupt Support
-----------------

PCI interrupt support is supported on the 82801EB (ICH5) and later chips.

Hidden ICH SMBus
----------------

If your system has an Intel ICH south bridge, but you do NOT see the
SMBus device at 00:1f.3 in lspci, and you can't figure out any way in the
BIOS to enable it, it means it has been hidden by the BIOS code. Asus is
well known for first doing this on their P4B motherboard, and many other
boards after that. Some vendor machines are affected as well.

The first thing to try is the "i2c-scmi" ACPI driver. It could be that the
SMBus was hidden on purpose because it'll be driven by ACPI. If the
i2c-scmi driver works for you, just forget about the i2c-i801 driver and
don't try to unhide the ICH SMBus. Even if i2c-scmi doesn't work, you
better make sure that the SMBus isn't used by the ACPI code. Try loading
the "fan" and "thermal" drivers, and check in /sys/class/thermal. If you
find a thermal zone with type "acpitz", it's likely that the ACPI is
accessing the SMBus and it's safer not to unhide it. Only once you are
certain that ACPI isn't using the SMBus, you can attempt to unhide it.

In order to unhide the SMBus, we need to change the value of a PCI
register before the kernel enumerates the PCI devices. This is done in
drivers/pci/quirks.c, where all affected boards must be listed (see
function asus_hides_smbus_hostbridge.) If the SMBus device is missing,
and you think there's something interesting on the SMBus (e.g. a
hardware monitoring chip), you need to add your board to the list.

The motherboard is identified using the subvendor and subdevice IDs of the
host bridge PCI device. Get yours with ``lspci -n -v -s 00:00.0``::

  00:00.0 Class 0600: 8086:2570 (rev 02)
          Subsystem: 1043:80f2
          Flags: bus master, fast devsel, latency 0
          Memory at fc000000 (32-bit, prefetchable) [size=32M]
          Capabilities: [e4] #09 [2106]
          Capabilities: [a0] AGP version 3.0

Here the host bridge ID is 2570 (82865G/PE/P), the subvendor ID is 1043
(Asus) and the subdevice ID is 80f2 (P4P800-X). You can find the symbolic
names for the bridge ID and the subvendor ID in include/linux/pci_ids.h,
and then add a case for your subdevice ID at the right place in
drivers/pci/quirks.c. Then please give it very good testing, to make sure
that the unhidden SMBus doesn't conflict with e.g. ACPI.

If it works, proves useful (i.e. there are usable chips on the SMBus)
and seems safe, please submit a patch for inclusion into the kernel.

Note: There's a useful script in lm_sensors 2.10.2 and later, named
unhide_ICH_SMBus (in prog/hotplug), which uses the fakephp driver to
temporarily unhide the SMBus without having to patch and recompile your
kernel. It's very convenient if you just want to check if there's
anything interesting on your hidden ICH SMBus.

----------------------------------------------------------------------------

The lm_sensors project gratefully acknowledges the support of Texas
Instruments in the initial development of this driver.

The lm_sensors project gratefully acknowledges the support of Intel in the
development of SMBus 2.0 / ICH4 features of this driver.


code:
======================
Kernel driver i2c-ismt
======================

Supported adapters:
  * Intel S12xx series SOCs

Authors:
	Bill Brown <bill.e.brown@intel.com>

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

Description
-----------

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

  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


code:
==================
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.
 - Polling mode.

This controller is equipped within the next Mellanox systems:
"msx6710", "msx6720", "msb7700", "msn2700", "msx1410", "msn2410", "msb7800",
"msn2740", "msn2100".

The next transaction types are supported:
 - Receive Byte/Block.
 - Send Byte/Block.
 - Read Byte/Block.
 - Write Byte/Block.

Registers:

=============== === =======================================================================
CPBLTY		0x0 - capability reg.
			Bits [6:5] - transaction length. b01 - 72B is supported,
			36B in other case.
			Bit 7 - SMBus block read support.
CTRL		0x1 - control reg.
			Resets all the registers.
HALF_CYC	0x4 - cycle reg.
			Configure the width of I2C SCL half clock cycle (in 4 LPC_CLK
			units).
I2C_HOLD	0x5 - hold reg.
			OE (output enable) is delayed by value set to this register
			(in LPC_CLK units)
CMD			0x6 - command reg.
			Bit 0, 0 = write, 1 = read.
			Bits [7:1] - the 7bit Address of the I2C device.
			It should be written last as it triggers an I2C transaction.
NUM_DATA	0x7 - data size reg.
			Number of data bytes to write in read transaction
NUM_ADDR	0x8 - address reg.
			Number of address bytes to write in read transaction.
STATUS		0x9 - status reg.
			Bit 0 - transaction is completed.
			Bit 4 - ACK/NACK.
DATAx		0xa - 0x54  - 68 bytes data buffer regs.
			For write transaction address is specified in four first bytes
			(DATA1 - DATA4), data starting from DATA4.
			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.
=============== === =======================================================================


code:
=========================
Kernel driver i2c-nforce2
=========================

Supported adapters:
  * nForce2 MCP                10de:0064
  * nForce2 Ultra 400 MCP      10de:0084
  * nForce3 Pro150 MCP         10de:00D4
  * nForce3 250Gb MCP          10de:00E4
  * nForce4 MCP                10de:0052
  * nForce4 MCP-04             10de:0034
  * nForce MCP51               10de:0264
  * nForce MCP55               10de:0368
  * nForce MCP61               10de:03EB
  * nForce MCP65               10de:0446
  * nForce MCP67               10de:0542
  * nForce MCP73               10de:07D8
  * nForce MCP78S              10de:0752
  * nForce MCP79               10de:0AA2

Datasheet:
           not publicly available, but seems to be similar to the
           AMD-8111 SMBus 2.0 adapter.

Authors:
	- Hans-Frieder Vogt <hfvogt@gmx.net>,
	- Thomas Leibold <thomas@plx.com>,
        - Patrick Dreker <patrick@dreker.de>

Description
-----------

i2c-nforce2 is a driver for the SMBuses included in the nVidia nForce2 MCP.

If your ``lspci -v`` listing shows something like the following::

  00:01.1 SMBus: nVidia Corporation: Unknown device 0064 (rev a2)
          Subsystem: Asustek Computer, Inc.: Unknown device 0c11
          Flags: 66Mhz, fast devsel, IRQ 5
          I/O ports at c000 [size=32]
          Capabilities: <available only to root>

then this driver should support the SMBuses of your motherboard.

Notes
-----

The SMBus adapter in the nForce2 chipset seems to be very similar to the
SMBus 2.0 adapter in the AMD-8111 south bridge. However, I could only get
the driver to work with direct I/O access, which is different to the EC
interface of the AMD-8111. Tested on Asus A7N8X. The ACPI DSDT table of the
Asus A7N8X lists two SMBuses, both of which are supported by this driver.


code:
============================
Kernel driver i2c-nvidia-gpu
============================

Datasheet: not publicly available.

Authors:
	Ajay Gupta <ajayg@nvidia.com>

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

  01:00.3 Serial bus controller [0c80]: NVIDIA Corporation Device 1ad9 (rev a1)

then this driver should support the I2C controller of your GPU.


code:
========================
Kernel driver i2c-ocores
========================

Supported adapters:
  * OpenCores.org I2C controller by Richard Herveille (see datasheet link)
    https://opencores.org/project/i2c/overview

Author: Peter Korsgaard <peter@korsgaard.com>

Description
-----------

i2c-ocores is an i2c bus driver for the OpenCores.org I2C controller
IP core by Richard Herveille.

Usage
-----

i2c-ocores uses the platform bus, so you need to provide a struct
platform_device with the base address and interrupt number. The
dev.platform_data of the device should also point to a struct
ocores_i2c_platform_data (see linux/platform_data/i2c-ocores.h) describing the
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::

  static struct resource ocores_resources[] = {
	[0] = {
		.start	= MYI2C_BASEADDR,
		.end	= MYI2C_BASEADDR + 8,
		.flags	= IORESOURCE_MEM,
	},
	[1] = {
		.start	= MYI2C_IRQ,
		.end	= MYI2C_IRQ,
		.flags	= IORESOURCE_IRQ,
	},
  };

  /* optional board info */
  struct i2c_board_info ocores_i2c_board_info[] = {
	{
		I2C_BOARD_INFO("tsc2003", 0x48),
		.platform_data = &tsc2003_platform_data,
		.irq = TSC_IRQ
	},
	{
		I2C_BOARD_INFO("adv7180", 0x42 >> 1),
		.irq = ADV_IRQ
	}
  };

  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 = {
	.name			= "ocores-i2c",
	.dev = {
		.platform_data	= &myi2c_data,
	},
	.num_resources		= ARRAY_SIZE(ocores_resources),
	.resource		= ocores_resources,
  };


code:
=========================
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


code:
=========================
Kernel driver i2c-pca-isa
=========================

Supported adapters:

This driver supports ISA boards using the Philips PCA 9564
Parallel bus to I2C bus controller

Author: Ian Campbell <icampbell@arcom.com>, Arcom Control Systems

Module Parameters
-----------------

* base int
    I/O base address
* irq int
    IRQ interrupt
* clock int
    Clock rate as described in table 1 of PCA9564 datasheet

Description
-----------

This driver supports ISA boards using the Philips PCA 9564
Parallel bus to I2C bus controller


code:
=======================
Kernel driver i2c-piix4
=======================

Supported adapters:
  * Intel 82371AB PIIX4 and PIIX4E
  * Intel 82443MX (440MX)
    Datasheet: Publicly available at the Intel website
  * ServerWorks OSB4, CSB5, CSB6, HT-1000 and HT-1100 southbridges
    Datasheet: Only available via NDA from ServerWorks
  * ATI IXP200, IXP300, IXP400, SB600, SB700 and SB800 southbridges
    Datasheet: Not publicly available
    SB700 register reference available at:
    http://support.amd.com/us/Embedded_TechDocs/43009_sb7xx_rrg_pub_1.00.pdf
  * AMD SP5100 (SB700 derivative found on some server mainboards)
    Datasheet: Publicly available at the AMD website
    http://support.amd.com/us/Embedded_TechDocs/44413.pdf
  * AMD Hudson-2, ML, CZ
    Datasheet: Not publicly available
  * Hygon CZ
    Datasheet: Not publicly available
  * Standard Microsystems (SMSC) SLC90E66 (Victory66) southbridge
    Datasheet: Publicly available at the SMSC website http://www.smsc.com

Authors:
	- Frodo Looijaard <frodol@dds.nl>
	- Philip Edelbrock <phil@netroedge.com>

Module Parameters
-----------------

* force: int
  Forcibly enable the PIIX4. DANGEROUS!
* force_addr: int
  Forcibly enable the PIIX4 at the given address. EXTREMELY DANGEROUS!

Description
-----------

The PIIX4 (properly known as the 82371AB) is an Intel chip with a lot of
functionality. Among other things, it implements the PCI bus. One of its
minor functions is implementing a System Management Bus. This is a true
SMBus - you can not access it on I2C levels. The good news is that it
natively understands SMBus commands and you do not have to worry about
timing problems. The bad news is that non-SMBus devices connected to it can
confuse it mightily. Yes, this is known to happen...

Do ``lspci -v`` and see whether it contains an entry like this::

  0000:00:02.3 Bridge: Intel Corp. 82371AB/EB/MB PIIX4 ACPI (rev 02)
	       Flags: medium devsel, IRQ 9

Bus and device numbers may differ, but the function number must be
identical (like many PCI devices, the PIIX4 incorporates a number of
different 'functions', which can be considered as separate devices). If you
find such an entry, you have a PIIX4 SMBus controller.

On some computers (most notably, some Dells), the SMBus is disabled by
default. If you use the insmod parameter 'force=1', the kernel module will
try to enable it. THIS IS VERY DANGEROUS! If the BIOS did not set up a
correct address for this module, you could get in big trouble (read:
crashes, data corruption, etc.). Try this only as a last resort (try BIOS
updates first, for example), and backup first! An even more dangerous
option is 'force_addr=<IOPORT>'. This will not only enable the PIIX4 like
'force' does, but it will also set a new base I/O port address. The SMBus
parts of the PIIX4 needs a range of 8 of these addresses to function
correctly. If these addresses are already reserved by some other device,
you will get into big trouble! DON'T USE THIS IF YOU ARE NOT VERY SURE
ABOUT WHAT YOU ARE DOING!

The PIIX4E is just an new version of the PIIX4; it is supported as well.
The PIIX/PIIX3 does not implement an SMBus or I2C bus, so you can't use
this driver on those mainboards.

The ServerWorks Southbridges, the Intel 440MX, and the Victory66 are
identical to the PIIX4 in I2C/SMBus support.

The AMD SB700, SB800, SP5100 and Hudson-2 chipsets implement two
PIIX4-compatible SMBus controllers. If your BIOS initializes the
secondary controller, it will be detected by this driver as
an "Auxiliary SMBus Host Controller".

If you own Force CPCI735 motherboard or other OSB4 based systems you may need
to change the SMBus Interrupt Select register so the SMBus controller uses
the SMI mode.

1) Use ``lspci`` command and locate the PCI device with the SMBus controller:
   00:0f.0 ISA bridge: ServerWorks OSB4 South Bridge (rev 4f)
   The line may vary for different chipsets. Please consult the driver source
   for all possible PCI ids (and ``lspci -n`` to match them). Let's assume the
   device is located at 00:0f.0.
2) Now you just need to change the value in 0xD2 register. Get it first with
   command: ``lspci -xxx -s 00:0f.0``
   If the value is 0x3 then you need to change it to 0x1:
   ``setpci  -s 00:0f.0 d2.b=1``

Please note that you don't need to do that in all cases, just when the SMBus is
not working properly.

Hardware-specific issues
------------------------

This driver will refuse to load on IBM systems with an Intel PIIX4 SMBus.
Some of these machines have an RFID EEPROM (24RF08) connected to the SMBus,
which can easily get corrupted due to a state machine bug. These are mostly
Thinkpad laptops, but desktop systems may also be affected. We have no list
of all affected systems, so the only safe solution was to prevent access to
the SMBus on all IBM systems (detected using DMI data.)


code:
========================
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!


code:
========================
Kernel driver i2c-sis96x
========================

Replaces 2.4.x i2c-sis645

Supported adapters:

  * Silicon Integrated Systems Corp (SiS)

    Any combination of these host bridges:
	645, 645DX (aka 646), 648, 650, 651, 655, 735, 745, 746

    and these south bridges:
	961, 962, 963(L)

Author: Mark M. Hoffman <mhoffman@lightlink.com>

Description
-----------

This SMBus only driver is known to work on motherboards with the above
named chipset combinations. The driver was developed without benefit of a
proper datasheet from SiS. The SMBus registers are assumed compatible with
those of the SiS630, although they are located in a completely different
place. Thanks to Alexander Malysh <amalysh@web.de> for providing the
SiS630 datasheet (and  driver).

The command ``lspci`` as root should produce something like these lines::

  00:00.0 Host bridge: Silicon Integrated Systems [SiS]: Unknown device 0645
  00:02.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513
  00:02.1 SMBus: Silicon Integrated Systems [SiS]: Unknown device 0016

or perhaps this::

  00:00.0 Host bridge: Silicon Integrated Systems [SiS]: Unknown device 0645
  00:02.0 ISA bridge: Silicon Integrated Systems [SiS]: Unknown device 0961
  00:02.1 SMBus: Silicon Integrated Systems [SiS]: Unknown device 0016

(kernel versions later than 2.4.18 may fill in the "Unknown"s)

If you can't see it please look on quirk_sis_96x_smbus
(drivers/pci/quirks.c) (also if southbridge detection fails)

I suspect that this driver could be made to work for the following SiS
chipsets as well: 635, and 635T. If anyone owns a board with those chips
AND is willing to risk crashing & burning an otherwise well-behaved kernel
in the name of progress... please contact me at <mhoffman@lightlink.com> or
via the linux-i2c mailing list: <linux-i2c@vger.kernel.org>.  Please send bug
reports and/or success stories as well.

TO DOs
------

* The driver does not support SMBus block reads/writes; I may add them if a
  scenario is found where they're needed.

Thank You
---------

Mark D. Studebaker <mdsxyz123@yahoo.com>
 - design hints and bug fixes

Alexander Maylsh <amalysh@web.de>
 - ditto, plus an important datasheet... almost the one I really wanted

Hans-Günter Lütke Uphues <hg_lu@t-online.de>
 - patch for SiS735

Robert Zwerus <arzie@dds.nl>
 - testing for SiS645DX

Kianusch Sayah Karadji <kianusch@sk-tech.net>
 - patch for SiS645DX/962

Ken Healy
 - patch for SiS655

To anyone else who has written w/ feedback, thanks!


code:
==========================
Kernel driver i2c-taos-evm
==========================

Author: Jean Delvare <jdelvare@suse.de>

This is a driver for the evaluation modules for TAOS I2C/SMBus chips.
The modules include an SMBus master with limited capabilities, which can
be controlled over the serial port. Virtually all evaluation modules
are supported, but a few lines of code need to be added for each new
module to instantiate the right I2C chip on the bus. Obviously, a driver
for the chip in question is also needed.

Currently supported devices are:

* TAOS TSL2550 EVM

For additional information on TAOS products, please see
  http://www.taosinc.com/

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

  # modprobe serport
  # inputattach --taos-evm /dev/ttyS0

Technical details
-----------------

Only 4 SMBus transaction types are supported by the TAOS evaluation
modules:
* Receive Byte
* Send Byte
* Read Byte
* Write Byte

The communication protocol is text-based and pretty simple. It is
described in a PDF document on the CD which comes with the evaluation
module. The communication is rather slow, because the serial port has
to operate at 1200 bps. However, I don't think this is a big concern in
practice, as these modules are meant for evaluation and testing only.


code:
=====================
Kernel driver i2c-via
=====================

Supported adapters:
  * VIA Technologies, InC. VT82C586B
    Datasheet: Publicly available at the VIA website

Author: Kyösti Mälkki <kmalkki@cc.hut.fi>

Description
-----------

i2c-via is an i2c bus driver for motherboards with VIA chipset.

The following VIA pci chipsets are supported:
 - MVP3, VP3, VP2/97, VPX/97
 - others with South bridge VT82C586B

Your ``lspci`` listing must show this ::

 Bridge: VIA Technologies, Inc. VT82C586B ACPI (rev 10)

Problems?
---------

 Q:
    You have VT82C586B on the motherboard, but not in the listing.

 A:
    Go to your BIOS setup, section PCI devices or similar.
    Turn USB support on, and try again.

 Q:
    No error messages, but still i2c doesn't seem to work.

 A:
    This can happen. This driver uses the pins VIA recommends in their
    datasheets, but there are several ways the motherboard manufacturer
    can actually wire the lines.


code:
========================
Kernel driver i2c-viapro
========================

Supported adapters:
  * VIA Technologies, Inc. VT82C596A/B
    Datasheet: Sometimes available at the VIA website

  * VIA Technologies, Inc. VT82C686A/B
    Datasheet: Sometimes available at the VIA website

  * VIA Technologies, Inc. VT8231, VT8233, VT8233A
    Datasheet: available on request from VIA

  * VIA Technologies, Inc. VT8235, VT8237R, VT8237A, VT8237S, VT8251
    Datasheet: available on request and under NDA from VIA

  * VIA Technologies, Inc. CX700
    Datasheet: available on request and under NDA from VIA

  * VIA Technologies, Inc. VX800/VX820
    Datasheet: available on http://linux.via.com.tw

  * VIA Technologies, Inc. VX855/VX875
    Datasheet: available on http://linux.via.com.tw

  * VIA Technologies, Inc. VX900
    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>

Module Parameters
-----------------

* force: int
  Forcibly enable the SMBus controller. DANGEROUS!
* force_addr: int
  Forcibly enable the SMBus at the given address. EXTREMELY DANGEROUS!

Description
-----------

i2c-viapro is a true SMBus host driver for motherboards with one of the
supported VIA south bridges.

Your ``lspci -n`` listing must show one of these :

 ================   ======================
 device 1106:3050   (VT82C596A function 3)
 device 1106:3051   (VT82C596B function 3)
 device 1106:3057   (VT82C686 function 4)
 device 1106:3074   (VT8233)
 device 1106:3147   (VT8233A)
 device 1106:8235   (VT8231 function 4)
 device 1106:3177   (VT8235)
 device 1106:3227   (VT8237R)
 device 1106:3337   (VT8237A)
 device 1106:3372   (VT8237S)
 device 1106:3287   (VT8251)
 device 1106:8324   (CX700)
 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.

Except for the oldest chips (VT82C596A/B, VT82C686A and most probably
VT8231), this driver supports I2C block transactions. Such transactions
are mainly useful to read from and write to EEPROMs.

The CX700/VX800/VX820 additionally appears to support SMBus PEC, although
this driver doesn't implement it yet.


code:
.. 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


code:
========================
Kernel driver scx200_acb
========================

Author: Christer Weinigel <wingel@nano-system.com>

The driver supersedes the older, never merged driver named i2c-nscacb.

Module Parameters
-----------------

* base: up to 4 ints
  Base addresses for the ACCESS.bus controllers on SCx200 and SC1100 devices

  By default the driver uses two base addresses 0x820 and 0x840.
  If you want only one base address, specify the second as 0 so as to
  override this default.

Description
-----------

Enable the use of the ACCESS.bus controller on the Geode SCx200 and
SC1100 processors and the CS5535 and CS5536 Geode companion devices.

Device-specific notes
---------------------

The SC1100 WRAP boards are known to use base addresses 0x810 and 0x820.
If the scx200_acb driver is built into the kernel, add the following
parameter to your boot command line::

  scx200_acb.base=0x810,0x820

If the scx200_acb driver is built as a module, add the following line to
a configuration file in /etc/modprobe.d/ instead::

  options scx200_acb base=0x810,0x820


code:
============================================
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
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
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.

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

  #include <linux/i2c-dev.h>
  #include <i2c/smbus.h>

Now, you have to decide which adapter you want to access. You should
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::

  int file;
  int adapter_nr = 2; /* probably dynamically determined */
  char filename[20];

  snprintf(filename, 19, "/dev/i2c-%d", adapter_nr);
  file = open(filename, O_RDWR);
  if (file < 0) {
    /* ERROR HANDLING; you can check errno to see what went wrong */
    exit(1);
  }

When you have opened the device, you must specify with what device
address you want to communicate::

  int addr = 0x40; /* The I2C address */

  if (ioctl(file, I2C_SLAVE, addr) < 0) {
    /* ERROR HANDLING; you can check errno to see what went wrong */
    exit(1);
  }

Well, you are all set up now. You can now use SMBus commands or plain
I2C to communicate with your device. SMBus commands are preferred if
the device supports them. Both are illustrated below::

  __u8 reg = 0x10; /* Device register to access */
  __s32 res;
  char buf[10];

  /* Using SMBus commands */
  res = i2c_smbus_read_word_data(file, reg);
  if (res < 0) {
    /* ERROR HANDLING: I2C transaction failed */
  } else {
    /* res contains the read word */
  }

  /*
   * Using I2C Write, equivalent of
   * i2c_smbus_write_word_data(file, reg, 0x6543)
   */
  buf[0] = reg;
  buf[1] = 0x43;
  buf[2] = 0x65;
  if (write(file, buf, 3) != 3) {
    /* ERROR HANDLING: I2C transaction failed */
  }

  /* Using I2C Read, equivalent of i2c_smbus_read_byte(file) */
  if (read(file, buf, 1) != 1) {
    /* ERROR HANDLING: I2C transaction failed */
  } else {
    /* buf[0] contains the read byte */
  }

Note that only a subset of the I2C and SMBus protocols can be achieved by
the means of read() and write() calls. In particular, so-called combined
transactions (mixing read and write messages in the same transaction)
aren't supported. For this reason, this interface is almost never used by
user-space programs.

IMPORTANT: because of the use of inline functions, you *have* to use
'-O' or some variation when you compile your program!

Full interface description
==========================

The following IOCTLs are defined:

``ioctl(file, I2C_SLAVE, long addr)``
  Change slave address. The address is passed in the 7 lower bits of the
  argument (except for 10 bit addresses, passed in the 10 lower bits in this
  case).

``ioctl(file, I2C_TENBIT, long select)``
  Selects ten bit addresses if select not equals 0, selects normal 7 bit
  addresses if select equals 0. Default 0.  This request is only valid
  if the adapter has I2C_FUNC_10BIT_ADDR.

``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_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::

    struct i2c_rdwr_ioctl_data {
      struct i2c_msg *msgs;  /* ptr to array of simple messages */
      int nmsgs;             /* number of messages to exchange */
    }

  The msgs[] themselves contain further pointers into data buffers.
  The function will write or read data to or from that buffers depending
  on whether the I2C_M_RD flag is set in a particular message or not.
  The slave address and whether to use ten bit address mode has to be
  set in each message, overriding the values set with the above ioctl's.

``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 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.rst
for details) through the following functions::

  __s32 i2c_smbus_write_quick(int file, __u8 value);
  __s32 i2c_smbus_read_byte(int file);
  __s32 i2c_smbus_write_byte(int file, __u8 value);
  __s32 i2c_smbus_read_byte_data(int file, __u8 command);
  __s32 i2c_smbus_write_byte_data(int file, __u8 command, __u8 value);
  __s32 i2c_smbus_read_word_data(int file, __u8 command);
  __s32 i2c_smbus_write_word_data(int file, __u8 command, __u16 value);
  __s32 i2c_smbus_process_call(int file, __u8 command, __u16 value);
  __s32 i2c_smbus_block_process_call(int file, __u8 command, __u8 length,
                                     __u8 *values);
  __s32 i2c_smbus_read_block_data(int file, __u8 command, __u8 *values);
  __s32 i2c_smbus_write_block_data(int file, __u8 command, __u8 length,
                                   __u8 *values);

All these transactions return -1 on failure; you can read errno to see
what happened. The 'write' transactions return 0 on success; the
'read' transactions return the read value, except for read_block, which
returns the number of values read. The block buffers need not be longer
than 32 bytes.

The above functions are made available by linking against the libi2c library,
which is provided by the i2c-tools project.  See:
https://git.kernel.org/pub/scm/utils/i2c-tools/i2c-tools.git/.

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().

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
package the returned data, if any, in suitable format for the ioctl.


code:
=================
Linux I2C and DMA
=================

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
DMA for it will likely add more overhead than a plain PIO transfer.

Therefore, it is *not* mandatory that the buffer of an I2C message is DMA safe.
It does not seem reasonable to apply additional burdens when the feature is so
rarely used. However, it is recommended to use a DMA-safe buffer if your
message size is likely applicable for DMA. Most drivers have this threshold
around 8 bytes (as of today, this is mostly an educated guess, however). For
any message of 16 byte or larger, it is probably a really good idea. Please
note that other subsystems you use might add requirements. E.g., if your
I2C bus master driver is using USB as a bridge, then you need to have DMA
safe buffers always, because USB requires it.

Clients
-------

For clients, if you use a DMA safe buffer in i2c_msg, set the I2C_M_DMA_SAFE
flag with it. Then, the I2C core and drivers know they can safely operate DMA
on it. Note that using this flag is optional. I2C host drivers which are not
updated to use this flag will work like before. And like before, they risk
using an unsafe DMA buffer. To improve this situation, using I2C_M_DMA_SAFE in
more and more clients and host drivers is the planned way forward. Note also
that setting this flag makes only sense in kernel space. User space data is
copied into kernel space anyhow. The I2C core makes sure the destination
buffers in kernel space are always DMA capable. Also, when the core emulates
SMBus transactions via I2C, the buffers for block transfers are DMA safe. Users
of i2c_master_send() and i2c_master_recv() functions can now use DMA safe
variants (i2c_master_send_dmasafe() and i2c_master_recv_dmasafe()) once they
know their buffers are DMA safe. Users of i2c_transfer() must set the
I2C_M_DMA_SAFE flag manually.

Masters
-------

Bus master drivers wishing to implement safe DMA can use helper functions from
the I2C core. One gives you a DMA-safe buffer for a given i2c_msg as long as a
certain threshold is met::

	dma_buf = i2c_get_dma_safe_msg_buf(msg, threshold_in_byte);

If a buffer is returned, it is either msg->buf for the I2C_M_DMA_SAFE case or a
bounce buffer. But you don't need to care about that detail, just use the
returned buffer. If NULL is returned, the threshold was not met or a bounce
buffer could not be allocated. Fall back to PIO in that case.

In any case, a buffer obtained from above needs to be released. Another helper
function ensures a potentially used bounce buffer is freed::

	i2c_put_dma_safe_msg_buf(dma_buf, msg, xferred);

The last argument 'xferred' controls if the buffer is synced back to the
message or not. No syncing is needed in cases setting up DMA had an error and
there was no data transferred.

The bounce buffer handling from the core is generic and simple. It will always
allocate a new bounce buffer. If you want a more sophisticated handling (e.g.
reusing pre-allocated buffers), you are free to implement your own.

Please also check the in-kernel documentation for details. The i2c-sh_mobile
driver can be used as a reference example how to use the above helpers.

Final note: If you plan to use DMA with I2C (or with anything else, actually)
make sure you have CONFIG_DMA_API_DEBUG enabled during development. It can help
you find various issues which can be complex to debug otherwise.


code:
=====================
I2C/SMBUS Fault Codes
=====================

This is a summary of the most important conventions for use of fault
codes in the I2C/SMBus stack.

A "Fault" is not always an "Error"
----------------------------------
Not all fault reports imply errors; "page faults" should be a familiar
example.  Software often retries idempotent operations after transient
faults.  There may be fancier recovery schemes that are appropriate in
some cases, such as re-initializing (and maybe resetting).  After such
recovery, triggered by a fault report, there is no error.

In a similar way, sometimes a "fault" code just reports one defined
result for an operation ... it doesn't indicate that anything is wrong
at all, just that the outcome wasn't on the "golden path".

In short, your I2C driver code may need to know these codes in order
to respond correctly.  Other code may need to rely on YOUR code reporting
the right fault code, so that it can (in turn) behave correctly.

I2C and SMBus fault codes
-------------------------
These are returned as negative numbers from most calls, with zero or
some positive number indicating a non-fault return.  The specific
numbers associated with these symbols differ between architectures,
though most Linux systems use <asm-generic/errno*.h> numbering.

Note that the descriptions here are not exhaustive.  There are other
codes that may be returned, and other cases where these codes should
be returned.  However, drivers should not return other codes for these
cases (unless the hardware doesn't provide unique fault reports).

Also, codes returned by adapter probe methods follow rules which are
specific to their host bus (such as PCI, or the platform bus).

EAGAIN
	Returned by I2C adapters when they lose arbitration in master
	transmit mode:  some other master was transmitting different
	data at the same time.

	Also returned when trying to invoke an I2C operation in an
	atomic context, when some task is already using that I2C bus
	to execute some other operation.

EBADMSG
	Returned by SMBus logic when an invalid Packet Error Code byte
	is received.  This code is a CRC covering all bytes in the
	transaction, and is sent before the terminating STOP.  This
	fault is only reported on read transactions; the SMBus slave
	may have a way to report PEC mismatches on writes from the
	host.  Note that even if PECs are in use, you should not rely
	on these as the only way to detect incorrect data transfers.

EBUSY
	Returned by SMBus adapters when the bus was busy for longer
	than allowed.  This usually indicates some device (maybe the
	SMBus adapter) needs some fault recovery (such as resetting),
	or that the reset was attempted but failed.

EINVAL
	This rather vague error means an invalid parameter has been
	detected before any I/O operation was started.  Use a more
	specific fault code when you can.

EIO
	This rather vague error means something went wrong when
	performing an I/O operation.  Use a more specific fault
	code when you can.

ENODEV
	Returned by driver probe() methods.  This is a bit more
	specific than ENXIO, implying the problem isn't with the
	address, but with the device found there.  Driver probes
	may verify the device returns *correct* responses, and
	return this as appropriate.  (The driver core will warn
	about probe faults other than ENXIO and ENODEV.)

ENOMEM
	Returned by any component that can't allocate memory when
	it needs to do so.

ENXIO
	Returned by I2C adapters to indicate that the address phase
	of a transfer didn't get an ACK.  While it might just mean
	an I2C device was temporarily not responding, usually it
	means there's nothing listening at that address.

	Returned by driver probe() methods to indicate that they
	found no device to bind to.  (ENODEV may also be used.)

EOPNOTSUPP
	Returned by an adapter when asked to perform an operation
	that it doesn't, or can't, support.

	For example, this would be returned when an adapter that
	doesn't support SMBus block transfers is asked to execute
	one.  In that case, the driver making that request should
	have verified that functionality was supported before it
	made that block transfer request.

	Similarly, if an I2C adapter can't execute all legal I2C
	messages, it should return this when asked to perform a
	transaction it can't.  (These limitations can't be seen in
	the adapter's functionality mask, since the assumption is
	that if an adapter supports I2C it supports all of I2C.)

EPROTO
	Returned when slave does not conform to the relevant I2C
	or SMBus (or chip-specific) protocol specifications.  One
	case is when the length of an SMBus block data response
	(from the SMBus slave) is outside the range 1-32 bytes.

ESHUTDOWN
	Returned when a transfer was requested using an adapter
	which is already suspended.

ETIMEDOUT
	This is returned by drivers when an operation took too much
	time, and was aborted before it completed.

	SMBus adapters may return it when an operation took more
	time than allowed by the SMBus specification; for example,
	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.


code:
=======================
I2C/SMBus Functionality
=======================

INTRODUCTION
------------

Because not every I2C or SMBus adapter implements everything in the
I2C specifications, a client can not trust that everything it needs
is implemented when it is given the option to attach to an adapter:
the client needs some way to check whether an adapter has the needed
functionality.

FUNCTIONALITY CONSTANTS
-----------------------

For the most up-to-date list of functionality constants, please check
<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
  I2C_FUNC_PROTOCOL_MANGLING      Knows about the I2C_M_IGNORE_NAK,
                                  I2C_M_REV_DIR_ADDR and I2C_M_NO_RD_ACK
                                  flags (which modify the I2C protocol!)
  I2C_FUNC_NOSTART                Can skip repeated start sequence
  I2C_FUNC_SMBUS_QUICK            Handles the SMBus write_quick command
  I2C_FUNC_SMBUS_READ_BYTE        Handles the SMBus read_byte command
  I2C_FUNC_SMBUS_WRITE_BYTE       Handles the SMBus write_byte command
  I2C_FUNC_SMBUS_READ_BYTE_DATA   Handles the SMBus read_byte_data command
  I2C_FUNC_SMBUS_WRITE_BYTE_DATA  Handles the SMBus write_byte_data command
  I2C_FUNC_SMBUS_READ_WORD_DATA   Handles the SMBus read_word_data command
  I2C_FUNC_SMBUS_WRITE_WORD_DATA  Handles the SMBus write_byte_data command
  I2C_FUNC_SMBUS_PROC_CALL        Handles the SMBus process_call command
  I2C_FUNC_SMBUS_READ_BLOCK_DATA  Handles the SMBus read_block_data command
  I2C_FUNC_SMBUS_WRITE_BLOCK_DATA Handles the SMBus write_block_data command
  I2C_FUNC_SMBUS_READ_I2C_BLOCK   Handles the SMBus read_i2c_block_data command
  I2C_FUNC_SMBUS_WRITE_I2C_BLOCK  Handles the SMBus write_i2c_block_data command
  =============================== ==============================================

A few combinations of the above flags are also defined for your convenience:

  =========================       ======================================
  I2C_FUNC_SMBUS_BYTE             Handles the SMBus read_byte
                                  and write_byte commands
  I2C_FUNC_SMBUS_BYTE_DATA        Handles the SMBus read_byte_data
                                  and write_byte_data commands
  I2C_FUNC_SMBUS_WORD_DATA        Handles the SMBus read_word_data
                                  and write_word_data commands
  I2C_FUNC_SMBUS_BLOCK_DATA       Handles the SMBus read_block_data
                                  and write_block_data commands
  I2C_FUNC_SMBUS_I2C_BLOCK        Handles the SMBus read_i2c_block_data
                                  and write_i2c_block_data commands
  I2C_FUNC_SMBUS_EMUL             Handles all SMBus commands 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.

ADAPTER IMPLEMENTATION
----------------------

When you write a new adapter driver, you will have to implement a
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::

  static u32 piix4_func(struct i2c_adapter *adapter)
  {
	return I2C_FUNC_SMBUS_QUICK | I2C_FUNC_SMBUS_BYTE |
	       I2C_FUNC_SMBUS_BYTE_DATA | I2C_FUNC_SMBUS_WORD_DATA |
	       I2C_FUNC_SMBUS_BLOCK_DATA;
  }

A typical full-I2C adapter would use the following (from the i2c-pxa
driver)::

  static u32 i2c_pxa_functionality(struct i2c_adapter *adap)
  {
	return I2C_FUNC_I2C | I2C_FUNC_SMBUS_EMUL;
  }

I2C_FUNC_SMBUS_EMUL includes all the SMBus transactions (with the
addition of I2C block transactions) which i2c-core can emulate using
I2C_FUNC_I2C without any help from the adapter driver. The idea is
to let the client drivers check for the support of SMBus functions
without having to care whether the said functions are implemented in
hardware by the adapter, or emulated in software by i2c-core on top
of an I2C adapter.

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

  static int lm75_detect(...)
  {
	(...)
	if (!i2c_check_functionality(adapter, I2C_FUNC_SMBUS_BYTE_DATA |
				     I2C_FUNC_SMBUS_WORD_DATA))
		goto exit;
	(...)
  }

Here, the lm75 driver checks if the adapter can do both SMBus byte data
and SMBus word data transactions. If not, then the driver won't work on
this adapter and there's no point in going on. If the check above is
successful, then the driver knows that it can call the following
functions: i2c_smbus_read_byte_data(), i2c_smbus_write_byte_data(),
i2c_smbus_read_word_data() and i2c_smbus_write_word_data(). As a rule of
thumb, the functionality constants you test for with
i2c_check_functionality() should match exactly the i2c_smbus_* functions
which you driver is calling.

Note that the check above doesn't tell whether the functionalities are
implemented in hardware by the underlying adapter or emulated in
software by i2c-core. Client drivers don't have to care about this, as
i2c-core will transparently implement SMBus transactions on top of I2C
adapters.

CHECKING THROUGH /DEV
---------------------

If you try to access an adapter from a userspace program, you will have
to use the /dev interface. You will still have to check whether the
functionality you need is supported, of course. This is done using
the I2C_FUNCS ioctl. An example, adapted from the i2cdetect program, is
below::

  int file;
  if (file = open("/dev/i2c-0", O_RDWR) < 0) {
	/* Some kind of error handling */
	exit(1);
  }
  if (ioctl(file, I2C_FUNCS, &funcs) < 0) {
	/* Some kind of error handling */
	exit(1);
  }
  if (!(funcs & I2C_FUNC_SMBUS_QUICK)) {
	/* Oops, the needed functionality (SMBus write_quick function) is
           not available! */
	exit(1);
  }
  /* Now it is safe to use the SMBus write_quick command */


code:
=========================
Linux I2C fault injection
=========================

The GPIO based I2C bus master driver can be configured to provide fault
injection capabilities. It is then meant to be connected to another I2C bus
which is driven by the I2C bus master driver under test. The GPIO fault
injection driver can create special states on the bus which the other I2C bus
master driver should handle gracefully.

Once the Kconfig option I2C_GPIO_FAULT_INJECTOR is enabled, there will be an
'i2c-fault-injector' subdirectory in the Kernel debugfs filesystem, usually
mounted at /sys/kernel/debug. There will be a separate subdirectory per GPIO
driven I2C bus. Each subdirectory will contain files to trigger the fault
injection. They will be described now along with their intended use-cases.

Wire states
===========

"scl"
-----

By reading this file, you get the current state of SCL. By writing, you can
change its state to either force it low or to release it again. So, by using
"echo 0 > scl" you force SCL low and thus, no communication will be possible
because the bus master under test will not be able to clock. It should detect
the condition of SCL being unresponsive and report an error to the upper
layers.

"sda"
-----

By reading this file, you get the current state of SDA. By writing, you can
change its state to either force it low or to release it again. So, by using
"echo 0 > sda" you force SDA low and thus, data cannot be transmitted. The bus
master under test should detect this condition and trigger a bus recovery (see
I2C specification version 4, section 3.1.16) using the helpers of the Linux I2C
core (see 'struct bus_recovery_info'). However, the bus recovery will not
succeed because SDA is still pinned low until you manually release it again
with "echo 1 > sda". A test with an automatic release can be done with the
"incomplete transfers" class of fault injectors.

Incomplete transfers
====================

The following fault injectors create situations where SDA will be held low by a
device. Bus recovery should be able to fix these situations. But please note:
there are I2C client devices which detect a stuck SDA on their side and release
it on their own after a few milliseconds. Also, there might be an external
device deglitching and monitoring the I2C bus. It could also detect a stuck SDA
and will init a bus recovery on its own. If you want to implement bus recovery
in a bus master driver, make sure you checked your hardware setup for such
devices before. And always verify with a scope or logic analyzer!

"incomplete_address_phase"
--------------------------

This file is write only and you need to write the address of an existing I2C
client device to it. Then, a read transfer to this device will be started, but
it will stop at the ACK phase after the address of the client has been
transmitted. Because the device will ACK its presence, this results in SDA
being pulled low by the device while SCL is high. So, similar to the "sda" file
above, the bus master under test should detect this condition and try a bus
recovery. This time, however, it should succeed and the device should release
SDA after toggling SCL.

"incomplete_write_byte"
-----------------------

Similar to above, this file is write only and you need to write the address of
an existing I2C client device to it.

The injector will again stop at one ACK phase, so the device will keep SDA low
because it acknowledges data. However, there are two differences compared to
'incomplete_address_phase':

a) the message sent out will be a write message
b) after the address byte, a 0x00 byte will be transferred. Then, stop at ACK.

This is a highly delicate state, the device is set up to write any data to
register 0x00 (if it has registers) when further clock pulses happen on SCL.
This is why bus recovery (up to 9 clock pulses) must either check SDA or send
additional STOP conditions to ensure the bus has been released. Otherwise
random data will be written to a device!

Lost arbitration
================

Here, we want to simulate the condition where the master under test loses the
bus arbitration against another master in a multi-master setup.

"lose_arbitration"
------------------

This file is write only and you need to write the duration of the arbitration
intereference (in µs, maximum is 100ms). The calling process will then sleep
and wait for the next bus clock. The process is interruptible, though.

Arbitration lost is achieved by waiting for SCL going down by the master under
test and then pulling SDA low for some time. So, the I2C address sent out
should be corrupted and that should be detected properly. That means that the
address sent out should have a lot of '1' bits to be able to detect corruption.
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::

  # echo 200 > lose_arbitration &
  # i2cget -y <bus_to_test> 0x3f

Panic during transfer
=====================

This fault injector will create a Kernel panic once the master under test
started a transfer. This usually means that the state machine of the bus master
driver will be ungracefully interrupted and the bus may end up in an unusual
state. Use this to check if your shutdown/reboot/boot code can handle this
scenario.

"inject_panic"
--------------

This file is write only and you need to write the delay between the detected
start of a transmission and the induced Kernel panic (in µs, maximum is 100ms).
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::

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


code:
================
The I2C Protocol
================

This document is an overview of the basic I2C transactions and the kernel
APIs to perform them.

Key to symbols
==============

=============== =============================================================
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 to
                get a 10 bit I2C address.
Data  (8 bits)  A plain data byte.

[..]            Data sent by I2C device, as opposed to data sent by the
                host adapter.
=============== =============================================================

Simple send transaction
=======================

Implemented by i2c_master_send()::

  S Addr Wr [A] Data [A] Data [A] ... [A] Data [A] P

Simple receive transaction
==========================

Implemented by i2c_master_recv()::

  S Addr Rd [A] [Data] A [Data] A ... A [Data] NA P

Combined transactions
=====================

Implemented by i2c_transfer().

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

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
are usually only needed to work around device issues:

I2C_M_IGNORE_NAK:
    Normally message is interrupted immediately if there is [NA] from the
    client. Setting this flag treats any [NA] as [A], and all of
    message is sent.
    These messages may still fail to SCL lo->hi timeout.

I2C_M_NO_RD_ACK:
    In a read message, master A/NA bit is skipped.

I2C_M_NOSTART:
    In a combined transaction, no 'S Addr Wr/Rd [A]' is generated at some
    point. For example, setting I2C_M_NOSTART on the second partial message
    generates something like::

      S Addr Rd [A] [Data] NA Data [A] P

    If you set the I2C_M_NOSTART variable for the first partial message,
    we do not generate Addr, but we do generate the 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
    I2C device but may also be used between direction changes by some
    rare devices.

I2C_M_REV_DIR_ADDR:
    This toggles the Rd/Wr flag. That is, if you want to do a write, but
    need to emit an Rd instead of a Wr, or vice versa, you set this
    flag. For example::

      S Addr Rd [A] Data [A] Data [A] ... [A] Data [A] P

I2C_M_STOP:
    Force a stop condition (P) after the message. Some I2C related protocols
    like SCCB require that. Normally, you really don't want to get interrupted
    between the messages of one transfer.


code:
========
i2c-stub
========

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)
word data, (r/w) I2C block data, and (r/w) SMBus block data.

You need to provide chip addresses as a module parameter when loading this
driver, which will then only react to SMBus commands to these addresses.

No hardware is needed nor associated with this module.  It will accept write
quick commands to the specified addresses; it will respond to the other
commands (also to the specified addresses) by reading from or writing to
arrays in memory.  It will also spam the kernel logs for every command it
handles.

A pointer register with auto-increment is implemented for all byte
operations.  This allows for continuous byte reads like those supported by
EEPROMs, among others.

SMBus block command support is disabled by default, and must be enabled
explicitly by setting the respective bits (0x03000000) in the functionality
module parameter.

SMBus block commands must be written to configure an SMBus command for
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
	4. observe its behavior in the kernel log

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

int chip_addr[10]:
	The SMBus addresses to emulate chips at.

unsigned long functionality:
	Functionality override, to disable some commands. See I2C_FUNC_*
	constants in <linux/i2c.h> for the suitable values. For example,
	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]:
	Optional bank settings. They tell which bits in which register
	select the active bank, as well as the range of banked registers.

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.