share/man/man4/iicmux.4

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