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.\" $FreeBSD$ 28.\" 29.Dd January 1, 2020 30.Dt IICMUX 4 31.Os 32.Sh NAME 33.Nm iicmux 34.Nd I2C bus mulitiplexer framework 35.Sh SYNOPSIS 36To compile this driver into the kernel, 37place the following line in your 38kernel configuration file: 39.Bd -ragged -offset indent 40.Cd "device iicmux" 41.Ed 42.Pp 43Alternatively, to load the driver as a 44module at boot time, place the following line in 45.Xr loader.conf 5 : 46.Bd -literal -offset indent 47iicmux_load="YES" 48.Ed 49.Pp 50Note that it is usually not necessary to explicitly load the 51driver module, as it will be loaded automatically along with 52the driver for the specific mux hardware in use. 53.Sh DESCRIPTION 54The 55.Nm 56framework provides support code to help implement drivers for various 57I2C bus multiplexer (mux) hardware. 58.Nm 59is not a standalone driver, 60it is a collection of support functions and driver methods which are 61used by individual mux hardware drivers. 62It will be loaded automatically when needed by a mux hardware driver. 63This manual page provides an overview of the I2C mux framework and its 64behavior. 65.Pp 66Generally speaking, an I2C mux is connected to an upstream I2C bus, and to 67one or more downstream I2C buses, and it can be commanded to connect 68any one of the downstream buses to the upstream bus. 69Some hardware may be able to connect multiple downstream buses at the 70same time, but that concept is not supported by 71.Nm . 72.Pp 73The 74.Nm 75framework operates automatically when I2C slave devices initiate I/O. 76It does not require (or even allow for) any external control to select 77the active downstream bus. 78.Pp 79When there is no I/O in progress, the mux is said to be in the 80.Dq idle 81state. 82Some mux hardware has the ability to disconnect all downstream buses 83when in an idle state. 84Other hardware must always have one of the downstream buses connected. 85Individual mux hardware drivers typically provide a way to select which 86downstream bus (if any) should be connected while in the idle state. 87In the absence of such configuration, whichever downstream bus was 88last used remains connected to the upstream bus. 89.Pp 90When an I2C slave device on a bus downstream of a mux initiates I/O, 91it first requests exclusive use of the bus by calling 92.Fn iicbus_request_bus . 93This request is communicated to the bus's parent, which is the 94.Nm 95framework 96mux driver. 97Once exclusive bus ownership is obtained, the mux driver 98connects the upstream I2C bus to the downstream bus which hosts the 99slave device that requested bus ownership. 100The mux hardware maintains that upstream-to-downstream connection until 101the slave device calls 102.Fn iicbus_release_bus . 103Before releasing ownership, the mux driver returns the mux hardware to 104the idle state. 105.Sh FDT CONFIGURATION 106On an 107.Xr fdt 4 108based system, an I2C mux device node is defined as a child node of its 109upstream I2C bus when the mux device is an I2C slave itself. 110It may be defined as a child node of any other bus or device in the 111system when it is not an I2C slave, in which case the 112.Va i2c-parent 113property indicates which upstream bus the mux is attached to. 114In either case, the children of the mux node are additional I2C buses, which 115will have one or more I2C slave devices described in their child nodes. 116.Pp 117Drivers using the 118.Nm 119framework conform to the standard 120.Bk -words 121.Li i2c/i2c-mux.txt 122.Ek 123bindings document. 124.Sh HINTS CONFIGURATION 125On a 126.Xr device.hints 5 127based system, these values are configurable for 128.Nm 129framework drivers : 130.Bl -tag -width indent 131.It Va hint.<driver>.<unit>.at 132The upstream 133.Xr iicbus 4 134the 135.Nm 136instance is attached to. 137.El 138.Pp 139When configured via hints, the driver automatically adds an iicbus 140instance for every downstream bus supported by the chip. 141There is currently no way to indicate used versus unused downstream buses. 142.Sh SEE ALSO 143.Xr iicbus 4 144.Sh HISTORY 145The 146.Nm 147framework first appeared in 148.Fx 13.0 . 149