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)
