MFC r356086, r356278, r356294, r356519, r356521-r356522, r356525-r356526

r356086:
Add comments to a couple i2c device lines in NOTES.

r356278:
Add support for i2c bus mux hardware.

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).

r356294:
Explicitly include sys/rman.h instead of relying on getting it via some
other header.

r356519:
Ensure any reserved gpio pins get released if an early exit is taken
from the attach function.

r356521:
Init sc->maxbus to -1, not 0. It represents the highest array index that
has a non-NULL child bus stored in it, so the "none" value can't be zero
since that's a valid array index. Also, when adding all possible buses
because there is no specific per-bus config, there's no need to reset
sc->maxbus on each loop iteration, it can be set once after the loop.

r356522:
Change some KASSERT to device_printf + return EINVAL. There's no need to
bring the whole kernel down due to a configuration error detected when a
module is loaded, it suffices to just not attach the device.

r356525:
Split the code to find and add iicbus children out to its own function.
Move the decision to take an early exit from that function after adding
children based on FDT data into the #ifdef FDT block, so that it doesn't
offend coverity's notion of how the code should be written. (What's the
point of compilers optimizing away dead code if static analyzers won't
let you use the feature in conjuction with an #ifdef block?)

Reported by: coverity via vangyzen@

r356526:
Remove some trailing whitespace; no functional changes.