1.\"- 2.\" SPDX-License-Identifier: BSD-2-Clause 3.\" 4.\" Copyright (c) 2019 Ian Lepore <ian@freebsd.org> 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.Dd January 1, 2020 28.Dt IICMUX 4 29.Os 30.Sh NAME 31.Nm iicmux 32.Nd I2C bus mulitiplexer framework 33.Sh SYNOPSIS 34To compile this driver into the kernel, 35place the following line in your 36kernel configuration file: 37.Bd -ragged -offset indent 38.Cd "device iicmux" 39.Ed 40.Pp 41Alternatively, to load the driver as a 42module at boot time, place the following line in 43.Xr loader.conf 5 : 44.Bd -literal -offset indent 45iicmux_load="YES" 46.Ed 47.Pp 48Note that it is usually not necessary to explicitly load the 49driver module, as it will be loaded automatically along with 50the driver for the specific mux hardware in use. 51.Sh DESCRIPTION 52The 53.Nm 54framework provides support code to help implement drivers for various 55I2C bus multiplexer (mux) hardware. 56.Nm 57is not a standalone driver, 58it is a collection of support functions and driver methods which are 59used by individual mux hardware drivers. 60It will be loaded automatically when needed by a mux hardware driver. 61This manual page provides an overview of the I2C mux framework and its 62behavior. 63.Pp 64Generally speaking, an I2C mux is connected to an upstream I2C bus, and to 65one or more downstream I2C buses, and it can be commanded to connect 66any one of the downstream buses to the upstream bus. 67Some hardware may be able to connect multiple downstream buses at the 68same time, but that concept is not supported by 69.Nm . 70.Pp 71The 72.Nm 73framework operates automatically when I2C slave devices initiate I/O. 74It does not require (or even allow for) any external control to select 75the active downstream bus. 76.Pp 77When there is no I/O in progress, the mux is said to be in the 78.Dq idle 79state. 80Some mux hardware has the ability to disconnect all downstream buses 81when in an idle state. 82Other hardware must always have one of the downstream buses connected. 83Individual mux hardware drivers typically provide a way to select which 84downstream bus (if any) should be connected while in the idle state. 85In the absence of such configuration, whichever downstream bus was 86last used remains connected to the upstream bus. 87.Pp 88When an I2C slave device on a bus downstream of a mux initiates I/O, 89it first requests exclusive use of the bus by calling 90.Fn iicbus_request_bus . 91This request is communicated to the bus's parent, which is the 92.Nm 93framework 94mux driver. 95Once exclusive bus ownership is obtained, the mux driver 96connects the upstream I2C bus to the downstream bus which hosts the 97slave device that requested bus ownership. 98The mux hardware maintains that upstream-to-downstream connection until 99the slave device calls 100.Fn iicbus_release_bus . 101Before releasing ownership, the mux driver returns the mux hardware to 102the idle state. 103.Sh FDT CONFIGURATION 104On an 105.Xr fdt 4 106based system, an I2C mux device node is defined as a child node of its 107upstream I2C bus when the mux device is an I2C slave itself. 108It may be defined as a child node of any other bus or device in the 109system when it is not an I2C slave, in which case the 110.Va i2c-parent 111property indicates which upstream bus the mux is attached to. 112In either case, the children of the mux node are additional I2C buses, which 113will have one or more I2C slave devices described in their child nodes. 114.Pp 115Drivers using the 116.Nm 117framework conform to the standard 118.Bk -words 119.Li i2c/i2c-mux.txt 120.Ek 121bindings document. 122.Sh HINTS CONFIGURATION 123On a 124.Xr device.hints 5 125based system, these values are configurable for 126.Nm 127framework drivers : 128.Bl -tag -width indent 129.It Va hint.<driver>.<unit>.at 130The upstream 131.Xr iicbus 4 132the 133.Nm 134instance is attached to. 135.El 136.Pp 137When configured via hints, the driver automatically adds an iicbus 138instance for every downstream bus supported by the chip. 139There is currently no way to indicate used versus unused downstream buses. 140.Sh SEE ALSO 141.Xr iicbus 4 142.Sh HISTORY 143The 144.Nm 145framework first appeared in 146.Fx 13.0 . 147