i2c: i2c probe() and remove() documented

Update Documentation/i2c to match previous patches updating probe()
and remove() logic.

Signed-off-by: David Brownell <dbrownell@users.sourceforge.net>
Signed-off-by: Jean Delvare <khali@linux-fr.org>
This commit is contained in:
David Brownell 2007-05-01 23:26:31 +02:00 committed by Jean Delvare
parent a1d9e6e49f
commit 4298cfc3eb
2 changed files with 92 additions and 19 deletions

View file

@ -4,17 +4,23 @@ I2C and SMBus
=============
I2C (pronounce: I squared C) is a protocol developed by Philips. It is a
slow two-wire protocol (10-400 kHz), but it suffices for many types of
devices.
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 a subset of the I2C protocol. Many
modern mainboards have a System Management Bus. There are a lot of
devices which can be connected to a SMBus; the most notable are modern
memory chips with EEPROM memories and chips for hardware monitoring.
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 just a special case of the generalized I2C bus, we
can simulate the SMBus protocol on plain I2C busses. The reverse is
regretfully impossible.
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
@ -29,6 +35,7 @@ When we talk about I2C, we use the following terms:
An Algorithm driver contains general code that can be used for a whole class
of I2C adapters. Each specific adapter driver depends on one algorithm
driver.
A Driver driver (yes, this sounds ridiculous, sorry) contains the general
code to access some type of device. Each detected device gets its own
data in the Client structure. Usually, Driver and Client are more closely
@ -40,6 +47,10 @@ a separate Adapter and Algorithm driver), and drivers for your I2C devices
in this package. See the lm_sensors project http://www.lm-sensors.nu
for device drivers.
At this time, Linux only operates I2C (or SMBus) in master mode; you can't
use these APIs to make a Linux system behave as a slave/device, either to
speak a custom protocol or to emulate some other device.
Included Bus Drivers
====================

View file

@ -1,5 +1,5 @@
This is a small guide for those who want to write kernel drivers for I2C
or SMBus devices.
or SMBus devices, using Linux as the protocol host/master (not slave).
To set up a driver, you need to do several things. Some are optional, and
some things can be done slightly or completely different. Use this as a
@ -29,8 +29,16 @@ static struct i2c_driver foo_driver = {
.driver = {
.name = "foo",
},
/* iff driver uses driver model ("new style") binding model: */
.probe = foo_probe,
.remove = foo_remove,
/* else, driver uses "legacy" binding model: */
.attach_adapter = foo_attach_adapter,
.detach_client = foo_detach_client,
/* these may be used regardless of the driver binding model */
.shutdown = foo_shutdown, /* optional */
.suspend = foo_suspend, /* optional */
.resume = foo_resume, /* optional */
@ -40,7 +48,8 @@ static struct i2c_driver foo_driver = {
The name field is the driver name, and must not contain spaces. It
should match the module name (if the driver can be compiled as a module),
although you can use MODULE_ALIAS (passing "foo" in this example) to add
another name for the module.
another name for the module. If the driver name doesn't match the module
name, the module won't be automatically loaded (hotplug/coldplug).
All other fields are for call-back functions which will be explained
below.
@ -141,6 +150,59 @@ Writing is done the same way.
Probing and attaching
=====================
The Linux I2C stack was originally written to support access to hardware
monitoring chips on PC motherboards, and thus it embeds some assumptions
that are more appropriate to SMBus (and PCs) than to I2C. One of these
assumptions is that most adapters and devices drivers support the SMBUS_QUICK
protocol to probe device presence. Another is that devices and their drivers
can be sufficiently configured using only such probe primitives.
As Linux and its I2C stack became more widely used in embedded systems
and complex components such as DVB adapters, those assumptions became more
problematic. Drivers for I2C devices that issue interrupts need more (and
different) configuration information, as do drivers handling chip variants
that can't be distinguished by protocol probing, or which need some board
specific information to operate correctly.
Accordingly, the I2C stack now has two models for associating I2C devices
with their drivers: the original "legacy" model, and a newer one that's
fully compatible with the Linux 2.6 driver model. These models do not mix,
since the "legacy" model requires drivers to create "i2c_client" device
objects after SMBus style probing, while the Linux driver model expects
drivers to be given such device objects in their probe() routines.
Standard Driver Model Binding ("New Style")
-------------------------------------------
System infrastructure, typically board-specific initialization code or
boot firmware, reports what I2C devices exist. For example, there may be
a table, in the kernel or from the boot loader, identifying I2C devices
and linking them to board-specific configuration information about IRQs
and other wiring artifacts, chip type, and so on. That could be used to
create i2c_client objects for each I2C device.
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);
static int foo_remove(struct i2c_client *client);
Remember that the i2c_driver does not create those client handles. The
handle may be used during foo_probe(). If foo_probe() reports success
(zero not a negative status code) it may save the handle and use it until
foo_remove() returns. That binding model is used by most Linux drivers.
Drivers match devices when i2c_client.driver_name and the driver name are
the same; this approach is used in several other busses that don't have
device typing support in the hardware. The driver and module name should
match, so hotplug/coldplug mechanisms will modprobe the driver.
Legacy Driver Binding Model
---------------------------
Most i2c devices can be present on several i2c addresses; for some this
is determined in hardware (by soldering some chip pins to Vcc or Ground),
for others this can be changed in software (by writing to specific client
@ -162,8 +224,8 @@ NOTE: If you want to write a `sensors' driver, the interface is slightly
Probing classes
---------------
Probing classes (Legacy model)
------------------------------
All parameters are given as lists of unsigned 16-bit integers. Lists are
terminated by I2C_CLIENT_END.
@ -210,8 +272,8 @@ Note that you *have* to call the defined variable `normal_i2c',
without any prefix!
Attaching to an adapter
-----------------------
Attaching to an adapter (Legacy model)
--------------------------------------
Whenever a new adapter is inserted, or for all adapters if the driver is
being registered, the callback attach_adapter() is called. Now is the
@ -237,8 +299,8 @@ them (unless a `force' parameter was used). In addition, addresses that
are already in use (by some other registered client) are skipped.
The detect client function
--------------------------
The detect client function (Legacy model)
-----------------------------------------
The detect client function is called by i2c_probe. The `kind' parameter
contains -1 for a probed detection, 0 for a forced detection, or a positive
@ -427,8 +489,8 @@ For now, you can ignore the `flags' parameter. It is there for future use.
}
Removing the client
===================
Removing the client (Legacy model)
==================================
The detach_client call back function is called when a client should be
removed. It may actually fail, but only when panicking. This code is