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>hifive-unleashed-5.1
David Brownell
Jean Delvare
parent
a1d9e6e49f
commit
4298cfc3eb
|
|
@ -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
|
||||
====================
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in New Issue