An i2c bus can be divided into segments which can be selectively connected
and disconnected from the main bus. This is usually done to enable using
multiple slave devices having the same address, by isolating the devices
onto separate bus segments, only one of which is connected to the main bus
at once.
There are several types of i2c bus muxes, which break down into two general
categories...
- Muxes which are themselves i2c slaves. These devices respond to i2c
commands on their upstream bus, and based on those commands, connect
various downstream buses to the upstream. In newbus terms, they are both
a child of an iicbus and the parent of one or more iicbus instances.
- Muxes which are not i2c devices themselves. Such devices are part of the
i2c bus electrically, but in newbus terms their parent is some other
bus. The association with the upstream bus must be established by
separate metadata (such as FDT data).
In both cases, the mux driver has one or more iicbus child instances
representing the downstream buses. The mux driver implements the iicbus_if
interface, as if it were an iichb host bridge/i2c controller driver. It
services the IO requests sent to it by forwarding them to the iicbus
instance representing the upstream bus, after electrically connecting the
upstream bus to the downstream bus that hosts the i2c slave device which
made the IO request.
The net effect is automatic mux switching which is transparent to slaves on
the downstream buses. They just do i2c IO they way they normally do, and the
bus is electrically connected for the duration of the IO and then idled when
it is complete.
The existing iicbus_if callback() method is enhanced so that the parameter
passed to it can be a struct which contains a device_t for the requesting
bus and slave devices. This change is done by adding a flag that indicates
the extra values are present, and making the flags field the first field of
a new args struct. If the flag is set, the iichb or mux driver can recast
the pointer-to-flags into a pointer-to-struct and access the extra
fields. Thus abi compatibility with older drivers is retained (but a mux
cannot exist on the bus with the older iicbus driver in use.)
A new set of core support routines exists in iicbus.c. This code will help
implement mux drivers for any type of mux hardware by supplying all the
boilerplate code that forwards IO requests upstream. It also has code for
parsing metadata and instantiating the child iicbus instances based on it.
Two new hardware mux drivers are added. The ltc430x driver supports the
LTC4305/4306 mux chips which are controlled via i2c commands. The
iic_gpiomux driver supports any mux hardware which is controlled by
manipulating the state of one or more gpio pins. Test Plan
Tested locally using a variety of mux'd bus configurations involving both
ltc4305 and a homebrew gpio-controlled mux. Tested configurations included
cascaded muxes (unlikely in the real world, but useful to prove that 'it all
just works' in terms of the automatic switching and upstream forwarding of
IO requests).
than effectively doing scatter/gather IO with a pair of iic_msgs that direct
the controller to do a single transfer with no bus STOP/START between the
two buffers. It turns out we have multiple i2c hardware drivers that don't
honor the NOSTOP and NOSTART flags; sometimes they just try to do the
transfers anyway, creating confusing failures or leading to corrupted data.
Errors are communicated between the i2c controller layer and upper layers
(iicbus and slave device drivers) using a set of IIC_Exxxxxx constants which
effectively define a private number space separate from (and having values
that conflict with) the system errno number space. Sometimes it is necessary
to report a plain old system error (especially EINTR) from the controller or
bus layer and have that value make it back across the syscall interface
intact.
I initially considered replicating a few "crucial" errno values with similar
names and new numbers, e.g., IIC_EINTR, IIC_ERESTART, etc. It seemed like
that had the potential to grow over time until many of the errno names were
duplicated into the IIC_Exxxxx space.
So instead, this defines a mechanism to "encode" an errno into the IIC_Exxxx
space by setting the high bit and putting the errno into the lower-order
bits; a new errno2iic() function does this. The existing iic2errno()
recognizes the encoded values and extracts the original errno out of the
encoded value. An interesting wrinkle occurs with the pseudo-error values
such as ERESTART -- they aleady have the high bit set, and turning it off
would be the wrong thing to do. Instead, iic2errno() recognizes that lots of
high bits are on (i.e., it's a negative number near to zero) and just
returns that value as-is.
Thus, existing drivers continue to work without needing any changes, and
there is now a way to return errno values from the lower layers. The first
use of that is in iicbus_poll() which does mtx_sleep() with the PCATCH flag,
and needs to return the errno from that up the call chain.
Differential Revision: https://reviews.freebsd.org/D20975
r348164 added code to iicbus_request_bus/iicbus_release_bus to automatically
call device_busy()/device_unbusy() as part of aquiring exclusive use of the
bus (so modules can't be unloaded while the bus is exclusively owned and/or
IO is in progress). That broke the ability to do i2c IO from a slave device
probe method, because the slave isn't attached yet, so calling device_busy()
triggers a sanity-check panic for trying to busy a non-attached device.
Now we check whether the device status is < DS_ATTACHING, and if so we busy
the iicbus rather than the slave device. I think this leaves a small window
where a module could be unloaded while probing is in progress. But I think
that's true of all devices, and probably should be fixed by introducing a
DS_PROBING state for devices, and handling that at various points in the
newbus code.
Since drm2 removal, there has not been any consumer of the feature in the
tree. I am also unaware of any out-of-tree consumer.
More importantly, the feature has been broken from the very start, both
before and after r306589, because the ivar was set on a device that does
not support it and it was read from another device that also does not
support it.
A bus-wide no-stop flag cannot be implemented as an ivar as iicbus
attaches as a child of various drivers. Implementing the ivar in each
and every I2C driver is just impractical.
If we ever want to implement this feature properly, then probably the
easiest way to do it would be via a flag in the softc of iicbus.
In fact, we might have to do that in the stable branches if we want to
fix the code for them.
Reported by: ian (long time ago)
MFC after: 1 month (maybe)
X-MFC-note: cannot just merge the change, must keep drm2 happy
Many i2c slave drivers are in modules that can be unloaded. If they detach
while IO is in progress the bus would be hung forever. Conversely,
lower-layer drivers (iicbus and the hardware driver) also live in modules
and other kinds of bad things happen if they get detached while IO is in
progress. Because device_busy() propagates up to parents, marking the slave
device busy while it owns the bus solves both kinds of problems that come
with detaching i2c devices while IO is in progress.
The recursive ownership support added in r321584 was unconditionally in
effect all the time -- whenever a given i2c slave device instance tried to
lock the i2c bus for exclusive use when it already owned the bus, the call
returned immediately without waiting. However, many i2c slave drivers use
bus ownership to enforce that only a single thread at a time can be using
the slave device. The recursive locking changes broke this use case.
Now there is a new flag, IIC_RECURSIVE, which can be mixed in with the
other flags passed to iicbus_acquire_bus() to allow drivers to indicate
when recursive locking is desired. Using the flag implies that the driver
is managing concurrent access to the device by different threads in some way.
This immediately fixes all existing i2c slave drivers except for the two
i2c RTC drivers which use the recursive locking feature; those will be
fixed in a followup commit.
Mainly focus on files that use BSD 2-Clause license, however the tool I
was using misidentified many licenses so this was mostly a manual - error
prone - task.
The Software Package Data Exchange (SPDX) group provides a specification
to make it easier for automated tools to detect and summarize well known
opensource licenses. We are gradually adopting the specification, noting
that the tags are considered only advisory and do not, in any way,
superceed or replace the license texts.
Usually it is sufficient to use iicbus_transfer_excl(), or one of the
higher-level convenience functions that use it, to reserve the bus for the
duration of each register access. Occasionally it is important that a
series of accesses or read-modify-write operations must be done without any
other intervening access to the device, to prevent corrupting state.
Without support for nested request/release, slave device drivers would have
to stop using high-level convenience functions and resort to working with
arrays of iic_msg structs just for a few operations (often involving
one-time device setup or infrequent configuration changes).
The changes here appear large from a glance at the diff, but in fact they're
nearly trivial, and the large diff is because of changes in indentation and
the re-wrapping of comments caused by that. One notable change is that
iicbus_release_bus() now ignores the IICBUS_CALLBACK(IIC_RELEASE_BUS) return
value. The old error handling left the bus in a kind of limbo state where
it was still owned at the iicbus layer, but drivers rarely check the return
of the release call, and it's unclear what they would do to recover from an
error return anyway. No existing low-level drivers return any kind of error
from IIC_RELEASE_BUS except one EINVAL for "you don't own the bus", to which
the right response is probably to carry on with the process of releasing the
reference to the bus anyway.
on i2c devices, where the "register" can be any length.
Many (perhaps most) common i2c devices are organized as a collection of
(usually 1-byte-wide) registers, and are accessed by first writing a 1-byte
register index/offset number, then by reading or writing the data.
Generally there is an auto-increment feature so the when multiple bytes
are read or written, multiple contiguous registers are accessed.
Most existing slave device drivers allocate an array of iic_msg structures,
fill in all the transfer info, and invoke iicbus_transfer(). These new
functions commonize all that and reduce register access to a simple call
with a few arguments.
nostop option is set, if a start was issued.
The nostop option doesn't mean "never issue a stop" it means "only issue
a stop after the last in a series of transfers". If the transfer ends
due to error, then that was the last transfer in the series, and a stop
is required.
Before this change, any error during a transfer when nostop is set would
effectively hang the bus, because sc->started would never get cleared,
and that caused all future calls to iicbus_start() to return an error
because it looked like the bus was already active. (Unrelated errors in
handling the nostop option, to be addressed separately, could lead to
this bus hang condition even on busses that don't set the nostop option.)
while holding exclusive ownership of the bus. This is the routine most
slave drivers should use unless they have a need to acquire and hold the
bus across a series of related operations that involves multiple transfers.
these functions are thin wrappers around calling the hardware-layer driver,
but some of them do sanity checks and return an error. Since the hardware
layer can only return IIC_Exxxxx status values, the iicbus helper functions
must also adhere to that, so that drivers at higher layers can assume that
any non-zero status value is an IIC_Exxxx value that provides details about
what happened at the hardware layer (sometimes those details are important
for certain slave drivers).
errno values that are at least vaguely equivelent. Also add a new status
value, IIC_ERESOURCE, to indicate a failure to acquire memory or other
required resources to complete a transaction.
The IIC_Exxxxxx values are supposed to communicate low-level details of the
i2c transaction status between the lowest-layer hardware driver and
higher-layer bus protocol and device drivers for slave devices on the bus.
Most of those slave drivers just return all status values from the lower
layers directly to their callers, resulting in crazy error reporting from a
user's point of view (things like timeouts being reported as "no such
process"). Now there's a helper function to make it easier to start
cleaning up all those drivers.
perform a stop operation on the bus if there was an error, otherwise the
bus will remain hung forever. Consistantly use 'if (error != 0)' style in
the function.
--Allow multiple open iic fds by storing addressing state in cdevpriv
--Fix, as much as possible, the baked-in race conditions in the iic
ioctl interface by requesting bus ownership on I2CSTART, releasing it on
I2CSTOP/I2CRSTCARD, and requiring bus ownership by the current cdevpriv
to use the I/O ioctls
--Reduce internal iic buffer size and remove 1K read/write limit by
iteratively calling iicbus_read/iicbus_write
--Eliminate dynamic allocation in I2CWRITE/I2CREAD
--Move handling of I2CRDWR to separate function and improve error handling
--Add new I2CSADDR ioctl to store address in current cdevpriv so that
I2CSTART is not needed for read(2)/write(2) to work
--Redesign iicbus_request_bus() and iicbus_release_bus():
--iicbus_request_bus() no longer falls through if the bus is already
owned by the requesting device. Multiple threads on the same device may
want exclusive access. Also, iicbus_release_bus() was never
device-recursive anyway.
--Previously, if IICBUS_CALLBACK failed in iicbus_release_bus(), but
the following iicbus_poll() call succeeded, IICBUS_CALLBACK would not be
issued again
--Do not hold iicbus mtx during IICBUS_CALLBACK call. There are
several drivers that may sleep in IICBUS_CALLBACK, if IIC_WAIT is passed.
--Do not loop in iicbus_request_bus if IICBUS_CALLBACK returns
EWOULDBLOCK; instead pass that to the caller so that it can retry if so
desired.
Differential Revision: https://reviews.freebsd.org/D2140
Reviewed by: imp, jhb, loos
Approved by: kib (mentor)
transfers to be default. It simplifies porting code which assumes
such settings.
Discussed with: avg, llos, nwhitehorn
Sponsored by: The FreeBSD Foundation
MFC after: 1 week
These realtek switch PHYs speak a variant of i2c with some slightly
modified handling.
From the submitter, slightly modified now that some further digging
has been done:
The I2C framework makes a assumption that the read/not-write bit of the first
byte (the address) indicates whether reads or writes are to follow.
The RTL8366 family uses the bus: after sending the address+read/not-write byte,
two register address bytes are sent, then the 16-bit register value is sent
or received. While the register write access can be performed as a 4-byte
write, the read access requires the read bit to be set, but the first two bytes
for the register address then need to be transmitted.
This patch maintains the i2c protocol behaviour but allows it to be relaxed
(for these kinds of switch PHYs, and whatever else Realtek may do with this
almost-but-not-quite i2c bus) - by setting the "strict" hint to 0.
The "strict" hint defaults to 1.
Submitted by: Stefan Bethke <stb@lassitu.de>
- Add an sx lock to the iic(4) driver to serialize open(), close(), read(),
and write and to protect sc_addr and sc_count in the softc.
- Use cdev->si_drv1 instead of using the minor number of the cdev to
lookup the softc via newbus in iic(4).
- Store the device_t in the softc to avoid a similar detour via minor
numbers in iic(4).
- Only add at most one instance of iic(4) and iicsmb(4) to each iicbus(4)
instance, and do it in the child driver.
- Add a mutex to the iicbus(4) softc to synchronize the request/release bus
stuff.
- Use __BUS_ACCESSOR() for IICBUS_ACCESSOR() instead of rolling our own.
- Add a mutex to the iicsmb(4) softc to protect softc state updated in the
interrupt handler.
- Remove Giant from all the smbus methods in iicsmb(4) now that all the
iicbus(4) backend is locked.
forcing all transfers to do the start read/write stop by hand. Some
smart bridges prefer this sort of operation, and this allows us to
support their features more easily. When bridges don't support it, we
fall back to using the old-style opertaions. Expand the ioctl
interface to expose this function. Unlike the old-style interface,
this interface is thread safe, even on old bridges.
device_add_child_ordered(). 'ivars' may now be set using the
device_set_ivars() function.
This makes it easier for us to change how arbitrary data structures are
associated with a device_t. Eventually we won't be modifying device_t
to add additional pointers for ivars, softc data etc.
Despite my best efforts I've probably forgotten something so let me know
if this breaks anything. I've been running with this change for months
and its been quite involved actually isolating all the changes from
the rest of the local changes in my tree.
Reviewed by: peter, dfr
devices dynamically. That means,
+ only one /dev/iic or /dev/smb device for each smb/iic bus to access
+ I2C/SMB device address must be given to any ioctl
+ new devices may be plugged and accessed after boot, which was
impossible previously (device addresses were hardcoded into
the kernel)
