[i2c] [patch 3/5] i2c probe() and remove(), documented at last
Jean Delvare
khali at linux-fr.org
Fri Mar 2 18:40:41 CET 2007
Hi David,
On Thu, 15 Feb 2007 00:44:23 -0800, David Brownell wrote:
> Update Documentation/i2c to match previous patch updating probe()
> and remove() logic.
>
> Signed-off-by: David Brownell <dbrownell at users.sourceforge.net>
>
> ---
> Documentation/i2c/smbus-protocol | 9 +++-
> Documentation/i2c/summary | 30 ++++++++++-----
> Documentation/i2c/writing-clients | 74 +++++++++++++++++++++++++++++++++-----
> 3 files changed, 91 insertions(+), 22 deletions(-)
>
> Index: i2c/Documentation/i2c/writing-clients
> ===================================================================
> --- i2c.orig/Documentation/i2c/writing-clients 2007-02-14 23:59:29.000000000 -0800
> +++ i2c/Documentation/i2c/writing-clients 2007-02-15 00:00:07.000000000 -0800
> @@ -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 */
> @@ -141,6 +149,54 @@ 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 bus adapter drivers support the SMBUS_QUICK primitive
> +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
> +to 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.
> +
> + int foo_probe(struct i2c_client *client);
> + int foo_remove(struct i2c_client *client);
> +
> +Remember that the i2c_driver does not create those client handles; and
> +those handles may only be used after a successful probe() but before
> +any remove() has been called. That's the same binding model as almost
> +any other device driver in Linux.
Thanks for this really good explanation of the current situation :)
> +
> +
> +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 +218,8 @@ NOTE: If you want to write a `sensors' d
>
>
>
> -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 +266,8 @@ Note that you *have* to call the defined
> 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 +293,8 @@ them (unless a `force' parameter was use
> 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 +483,8 @@ For now, you can ignore the `flags' para
> }
>
>
> -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
> Index: i2c/Documentation/i2c/summary
> ===================================================================
> --- i2c.orig/Documentation/i2c/summary 2007-02-14 23:59:29.000000000 -0800
> +++ i2c/Documentation/i2c/summary 2007-02-15 00:00:07.000000000 -0800
> @@ -4,17 +4,22 @@ 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 (up to 400 kHz), with a highspeed extension (3.4 MHz),
high-speed
> +which provides an inexpensive (two pins!) bus for connecting many types of
> +devices with infrequent or low bandwidth communications requirements. It
> +is widely used with embedded systems.
> +
> +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 are I2C-incompatible. Modern PC mainboards
Actually all SMBus protocols are I2C-compatible (see below.)
> +rely on SMBus. The most common devices connected through SMBus are RAM
> +modules configured using I2C EEPROMs, and hardware monitoring chips.
> +
> +Because the SMBus is mostly a subset of the generalized I2C bus, we can
> +use its protocols on many I2C systems. However, there are systems that don't
> +meet both SMBus and I2C electrical constraints; and others which can't
> +implement all the SMBus protocol messages.
>
Extra blank line.
> -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.
> -
> -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.
>
>
> Terminology
> @@ -29,6 +34,7 @@ When we talk about I2C, we use the follo
> 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 +46,10 @@ a separate Adapter and Algorithm driver)
> 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
> ====================
> Index: i2c/Documentation/i2c/smbus-protocol
> ===================================================================
> --- i2c.orig/Documentation/i2c/smbus-protocol 2007-02-14 23:59:29.000000000 -0800
> +++ i2c/Documentation/i2c/smbus-protocol 2007-02-15 00:00:07.000000000 -0800
> @@ -6,12 +6,15 @@ Certain protocol features which are not
> this package are briefly described at the end of this document.
>
> Some adapters understand only the SMBus (System Management Bus) protocol,
> -which is a subset from the I2C protocol. Fortunately, many devices use
> -only the same subset, which makes it possible to put them on an SMBus.
> +which largely overlaps the I2C protocol. SMBus has some mechanisms that
> +I2C doesn't, like SMBUS_QUICK; and vice versa. The electrical constraints
> +are also different. Conveniently, many I2C devices use a subset of the I2C
> +protocols and signaling which is SMBus-compatible.
The SMBus protocol is really a subset of the I2C protocol. What SMBus
calls "Quick Command" is a perfectly valid I2C transaction, even though
you keep saying otherwise. Whether all I2C bus masters support it or
not is an entirely different matter, and whether or not I2C chips
support it or not is yet a different matter.
As a matter of fact:
* EEPROMS are I2C chips, and most of them ack the "SMBus quick
command" (zero-length message) just fine.
* I have an ADM1032 sensor chip on a bit-banged I2C bus, I can detect
it just fine using the SMBus quick command.
> +
> If you write a driver for some I2C device, please try to use the SMBus
> commands if at all possible (if the device uses only that subset of the
> I2C protocol). This makes it possible to use the device driver on both
> -SMBus adapters and I2C adapters (the SMBus command set is automatically
> +SMBus adapters and I2C adapters (most SMBus commands are automatically
The original sentence is true, so I won't change it.
> translated to I2C on I2C adapters, but plain I2C commands can not be
> handled at all on most pure SMBus adapters).
Thanks,
--
Jean Delvare
More information about the i2c
mailing list