xref: /freebsd/share/man/man4/iicbus.4 (revision 0fca6ea1d4eea4c934cfff25ac9ee8ad6fe95583)
1.\" Copyright (c) 1998, Nicolas Souchu
2.\" All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\"    notice, this list of conditions and the following disclaimer in the
11.\"    documentation and/or other materials provided with the distribution.
12.\"
13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
23.\" SUCH DAMAGE.
24.\"
25.Dd March 7, 2021
26.Dt IICBUS 4
27.Os
28.Sh NAME
29.Nm iicbus
30.Nd I2C bus system
31.Sh SYNOPSIS
32.Cd "device iicbus"
33.Cd "device iicbb"
34.Pp
35.Cd "device iic"
36.Cd "device ic"
37.Cd "device iicsmb"
38.Sh DESCRIPTION
39The
40.Em iicbus
41system provides a uniform, modular and architecture-independent
42system for the implementation of drivers to control various I2C devices
43and to utilize different I2C controllers.
44.Sh I2C
45I2C is an acronym for Inter Integrated Circuit bus.
46The I2C bus was developed
47in the early 1980's by Philips semiconductors.
48Its purpose was to provide an
49easy way to connect a CPU to peripheral chips in a TV-set.
50.Pp
51The BUS physically consists of 2 active wires and a ground connection.
52The active wires, SDA and SCL, are both bidirectional.
53Where SDA is the
54Serial DAta line and SCL is the Serial CLock line.
55.Pp
56Every component hooked up to the bus has its own unique address whether it
57is a CPU, LCD driver, memory, or complex function chip.
58Each of these chips
59can act as a receiver and/or transmitter depending on its functionality.
60Obviously an LCD driver is only a receiver, while a memory or I/O chip can
61both be transmitter and receiver.
62Furthermore there may be one or
63more BUS MASTERs.
64.Pp
65The BUS MASTER is the chip issuing the commands on the BUS.
66In the I2C protocol
67specification it is stated that the IC that initiates a data transfer on the
68bus is considered the BUS MASTER.
69At that time all the others are regarded to
70as the BUS SLAVEs.
71As mentioned before, the IC bus is a Multi-MASTER BUS.
72This means that more than one IC capable of initiating data transfer can be
73connected to it.
74.Sh DEVICES
75Some I2C device drivers are available:
76.Pp
77.Bl -column "Device drivers" -compact
78.It Em Devices Ta Em Description
79.It Sy iic Ta "general i/o operation"
80.It Sy ic Ta "network IP interface"
81.It Sy iicsmb Ta "I2C to SMB software bridge"
82.El
83.Sh INTERFACES
84The I2C protocol may be implemented by hardware or software.
85Software
86interfaces rely on very simple hardware, usually two lines
87twiddled by 2 registers.
88Hardware interfaces are more intelligent and receive
898-bit characters they write to the bus according to the I2C protocol.
90.Pp
91I2C interfaces may act on the bus as slave devices, allowing spontaneous
92bidirectional communications, thanks to the multi-master capabilities of the
93I2C protocol.
94.Pp
95Some I2C interfaces are available:
96.Pp
97.Bl -column "Interface drivers" -compact
98.It Em Interface Ta Em Description
99.It Sy pcf Ta "Philips PCF8584 master/slave interface"
100.It Sy iicbb Ta "generic bit-banging master-only driver"
101.It Sy lpbb Ta "parallel port specific bit-banging interface"
102.El
103.Sh BUS FREQUENCY CONFIGURATION
104The operating frequency of an I2C bus may be fixed or configurable.
105The bus may be used as part of some larger standard interface, and that
106interface specification may require a fixed frequency.
107The driver for that hardware would not honor an attempt to configure a
108different speed.
109A general purpose I2C bus, such as those found in many embedded systems,
110will often support multiple bus frequencies.
111.Pp
112When a system supports multiple I2C buses, a different frequency can
113be configured for each bus by number, represented by the
114.Va %d
115in the variable names below.
116Buses can be configured using any combination of device hints,
117Flattened Device Tree (FDT) data, tunables set via
118.Xr loader 8 ,
119or at runtime using
120.Xr sysctl 8 .
121When configuration is supplied using more than one method, FDT and
122hint data will be overridden by a tunable, which can be overridden by
123.Xr sysctl 8 .
124.Ss Device Hints
125Set
126.Va hint.iicbus.%d.frequency
127to the frequency in Hz, on systems that use device hints to configure
128I2C devices.
129The hint is also honored by systems that use FDT data if
130no frequency is configured using FDT.
131.Ss Flattened Device Tree Data
132Configure the I2C bus speed using the FDT standard
133.Va clock-frequency
134property of the node describing the I2C controller hardware.
135.Ss Sysctl and Tunable
136Set
137.Va dev.iicbus.%d.frequency
138in
139.Xr loader.conf 5 .
140The same variable can be changed at any time with
141.Xr sysctl 8 .
142Reset the bus using
143.Xr i2c 8
144or the
145.Xr iic 4
146.Va I2CRSTCARD
147ioctl to make the change take effect.
148.Sh SEE ALSO
149.Xr fdt 4 ,
150.Xr iic 4 ,
151.Xr iicbb 4 ,
152.Xr lpbb 4 ,
153.Xr pcf 4 ,
154.Xr i2c 8
155.Sh HISTORY
156The
157.Nm
158manual page first appeared in
159.Fx 3.0 .
160.Sh AUTHORS
161This
162manual page was written by
163.An Nicolas Souchu .
164