I2CADM(8) Maintenance Commands and Procedures I2CADM(8)
i2cadm - I2C administration
i2cadm controller list [-H] [-o field[,...] [-p]] [filter...]
i2cadm controller prop get [-H] [-o field[,...] [-p]] controller
[filter...]
i2cadm controller prop set controller property=value
i2cadm device list [-H] [-o field[,...] [-p]] [filter...]
i2cadm device addrs [-H] [-o field[,...] [-p]] [filter...]
i2cadm device add [-c compat] port name address
i2cadm device remove path
i2cadm mux list [-H] [-o field[,...] [-p]] [filter...]
i2cadm port list [-H] [-o field[,...] [-p]] [filter...]
i2cadm port map [-H] [-o field[,...] [-p]] port
i2cadm io [-m mode] -d destination [-a address] [-c command] [-w wlen]
[-r rlen] [-o output] data
i2cadm scan [-d device] [-H] [-o field[,...] [-p]] port
The i2cadm utility is used to enumerate and manipulate I2C and SMBus
controllers, devices, ports, and multiplexors.
There are four top-level objects in i2cadm;
Controllers
These are hardware device that can perform I2C or SMBus
operations that target devices on the bus. i2cadm provides the
ability to list them as well as get and set properties on
specific controllers.
Devices
Device represent targets on the I2C bus which provide some
functionality at a given address. Devices run the gamut
including functions like EEPROMs, sensors, GPIO controllers,
voltage regulators, and more. Many devices will have a
corresponding device driver that provides functionality through
a standard system mechanism, but there is no requirement for a
driver.
Ports A port is a logical point on an I2C bus under which one or more
devices can be found. I2C ports are found directly under
controllers and multiplexors. I2C ports under a controller
represent the start of a unique I2C bus and addresses that are
used are specific to that bus. i2cadm provides the ability to
list ports and print information about the addresses that are
in use on the port directly or downstream of it.
Multiplexors
Multiplexors provide a means of isolating segments of an I2C
bus from one another, which is generally used to avoid
overlapping I2C addresses. A multiplexor provides a fixed
number of ports and the system will transparently activate and
deactivate ports based on I/O requests and their targets. At
most one port will ever be active on a multiplexor at any given
time. i2cadm provides the ability to discover and list
multiplexors.
All listing operations leverage the standard illumos output format
library (ofmt(3OFMT)) allowing the selection of specific output fields,
the omission of the header (-H), and a parsable mode intended for
programmatic consumption (-p). When requesting parsable output, the
colon (":") character is used as a delimiter between fields and any
delimiters that would appear in an output field will be escaped with a
backslash character ("\").
Getting information about I2C devices, controllers, ports, and muxes
requires that a process have the {PRIV_SYS_DEVICES} privilege.
I2C Paths
All of the different entities that can be found on an I2C bus are
described through a path that indicates the route through the bus to
get to an entity. Consider the following I2C devices:
+------------+
| dwi2c4 |
| 1 port |
| controller |
+------------+ +------+
| | lm75 |
+---------->| 0x48 |
| +------+
v
+------------+
| pca9548 |
| 0x72 |
| 8 port mux |
+------------+
|
* ... port 0, 1-7 not pictured
|
v
+------------+
| pca9545 |
| 0x72 |
| 4 port mux |
+------------+
|
* ... port 2, 0-1,3 not pictured
|
v
+---------+
| at24c02 |
| 0x57 |
| EEPROM |
+---------+
The following are what different paths refer to for this:
dwi2c4 This refers to the controller itself.
dwi2c4/0 This refers to the primary port under
a controller. This could be used for
performing device scans, I/O, or
manually adding or removing devices.
dwi2c4/0/0x48 This refers to the LM75 temperature
sensor that is directly attached to
the controller's port.
dwi2c4/0/0x72 This string refers to the 8-port mux
directly under the controller's port.
dwi2c4/0/0x72/0/0x70/2/0x57 This is a complex string that refers
to the AT24C02 EEPROM. Along the way
are all of the devices and ports that
are used to get to it. A more
verbose form of this path would be
dwi2c4/0/pca9548@0x72/0/pca9545@0x70/2/at24c02@0x57.
When constructing paths, controllers are always referred to by their
name and instance. Ports are always referred to by their name, which
is usually a number based upon the datasheet. Devices can be referred
to in three ways at their point in the tree. Using the first mux as an
example:
1. Using the device's primary I2C address: `0x72'.
2. Using the device's name and primary address: `pca9548@0x72'.
3. Using the device's driver name and instance: `pca9454x0'.
The following commands are supported by i2cadm:
i2cadm controller list [-H] [-o field[,...] [-p]] [filter...]
List all of the I2C controllers in the system and provide basic
information about them.
The following fields are supported:
NAME This is the name of the I2C controller in the system. All
I2C paths will start with a controller name.
TYPE This is the primary type of the controller, but is not
indicative of all I/O that they can perform. An SMBus
controller may support directly performing I2C. The valid
controller types are:
i2c An I2C controller.
i3c An I3C controller.
smbus An SMBus controller.
SPEED A string that describe the speed that the bus is operating
at, along with some of the physical capabilities. The
valid speed values are:
standard Standard speed operates the bus at 100 kHz.
fast Fast speed operates the bus at 400 kHz.
fast-plus Fast-plus speed operates the bus at 1 MHz.
high High-speed operate the bus at 3.4 MHz.
ultra Ultra-fast speed operate the bus at 5 MHz.
NPORTS The number of ports that are under the controller.
DRIVER The name of the driver for the controller.
INSTANCE The name of the device driver instance for the controller.
PROVIDER The /devices path to the kernel provider for this
controller.
The following options are supported:
-H Omit the column header when printing output.
-o field[,...]
A comma-delineated list of fields to output, selected
from the ones above.
-p Displays the output in a machine-parsable format. When
requesting parsable output, the -o option is required to
specifically control which fields are included.
The following operands are supported:
filter One or more filters may be specified which are used to
constrain the list of controllers that are printed.
Each filter may either match the name of a controller
or driver.
If any filter is specified and does not match, then
that is treated as an error.
Because these are filters, they do not control the
order that items are printed out, only what is printed
out.
i2cadm controller prop get [-H] [-o field[,...] [-p]] controller
[filter...]
List all properties, their values, and corresponding metadata on the
specific controller controller.
The following fields are supported:
PROPERTY The name of the property.
PERM Indicates whether the property is readable or both readable
and writable.
VALUE The current value of the property.
DEFAULT The default value for the property on the specific instance
of the controller. This is the value the system will start
with assuming no tuning has been performed. Some
properties may not have a default value.
POSSIBLE A list of possible values that the property might take.
This may be a series of numeric ranges or a list of
specific values. Some properties may not have a set of
possible values.
TYPE Indicates the type of the property. The system has the
following I2C property types:
u32 Indicates that the property is a 32-bit unsigned
value.
bit32 Indicates that the property is a 32-bit unsigned
bitfield. The presence or absence of each bit
indicates a specific feature or property.
CONTROLLER
The name of the controller the property is being retrieved
from.
ID The system's numeric identifier for the property.
The following options are supported:
-H Omit the column header when printing output.
-o field[,...]
A comma-delineated list of fields to output, selected
from the ones above.
-p Displays the output in a machine-parsable format. When
requesting parsable output, the -o option is required to
specifically control which fields are included.
The following operands are supported:
filter One or more filters may be specified which are used to
constrain the list of properties that are printed.
Each filter must match the name of a property. For a
list of properties, see the PROPERTIES section.
If any filter is specified and does not match, then
that is treated as an error.
Because these are filters, they do not control the
order that items are printed out, only what is printed
out.
i2cadm controller prop set controller property=value
Set the value of a single named property on the controller,
controller, to the indicated value. value will be parsed based upon
the specific property and its type. Properties which are translated
into strings, can be specified as either an integer value or the
corresponding string.
To see the list of properties on a controller use i2cadm controller
prop get. For a list of all properties, see the PROPERTIES section.
i2cadm device list [-H] [-o field[,...] [-p]] [filter...]
Lists basic information about all devices known to the system across
all controllers. These are devices that have been discovered through
a platform-specific means or explicitly added by an administrator
through the i2cadm device add command.
The following fields are supported:
NAME The name of the device. This corresponds to the device
tree's node name.
ADDR The primary I2C address that this device has. This
corresponds to the device tree's reg[0] entry.
INSTANCE The driver instance of the device, if any.
PATH The I2C path of the device.
The following options are supported:
-H Omit the column header when printing output.
-o field[,...]
A comma-delineated list of fields to output, selected
from the ones above.
-p Displays the output in a machine-parsable format. When
requesting parsable output, the -o option is required to
specifically control which fields are included.
The following operands are supported:
filter One or more filters may be specified which are used to
constrain the list of properties that are printed.
Each filter may match a device's primary address, a
device name, a driver name, a driver instance, or a
portion of the device's I2C path.
If any filter is specified and does not match, then
that is treated as an error.
Because these are filters, they do not control the
order that items are printed out, only what is printed
out.
i2cadm device addrs [-H] [-o field[,...] [-p]] [filter...]
Print the I2C addresses and their sources for device's in the system.
A device's address may come from the platform or it may be an
additional address that the driver itself claims and is either unique
to that device or shared amongst all instance of a particular driver.
The following fields are supported:
PATH The I2C path of the device.
TYPE The type of the address. This is either 7-bit or 10-bit.
ADDR The address in question on the device.
SOURCE Indicates how the device was assigned the address. One of
the following values:
platform This address came from information provided by the
platform. This includes firmware sources or
addresses assigned as part of an operator calling
i2cadm device add.
claimed This addresses was claimed exclusively by the
device driver. For example, several EEPROMs
require multiple I2C addresses to cover their
entire memory map, but only the base address is
often provided by the platform.
shared This address was claimed by a device driver and is
permitted to be used across all instances of the
device driver.
The following options are supported:
-H Omit the column header when printing output.
-o field[,...]
A comma-delineated list of fields to output, selected
from the ones above.
-p Displays the output in a machine-parsable format. When
requesting parsable output, the -o option is required to
specifically control which fields are included.
The following operands are supported:
filter One or more filters may be specified which are used to
constrain the list of properties that are printed.
Each filter may match a device's particular address, a
device name, a driver name, a driver instance, or a
portion of the device's I2C path.
If any filter is specified and does not match, then
that is treated as an error.
Because these are filters, they do not control the
order that items are printed out, only what is printed
out.
i2cadm device add [-c compat] port name address
Add a new device to the system. The system will attempt to attach a
driver to this device; however, even if there is no driver for the
device, it can be created regardless.
The following options are supported:
-c compat Add the specified compatibility entry compat to the newly
created device node's `compatible' property. When the
system considers device drivers to attach to an I2C
device it will search for matches against the device's
`compatible' property and then attempt to match the
device's name.
This property may be specified multiple times in order to
add multiple entries. The order is meaningful and will
reflect the order specified on the command line. The
matching algorithm walks the list in order and terminates
on the first found match. More specific entries should
be specified first.
The following operands are supported:
port Specifies the I2C path to the port that the device will
be created under. This may be either a port on a
controller or a port under a multiplexor. Device's
under a mux are allowed to have conflicting addresses
with devices on other ports of a given mux. The mux
will be implicitly activated when performing I/O to the
device.
name The name of the new device. This generally should
match something about the device itself such as the
part number.
Device name's may be at most 31 characters. The first
character must be an upper or lower case letter. The
remaining characters may be upper or lower case
letters, numbers, or one of the following punctuation
characters: the comma (`,'), the period (`.'), the
hyphen (`-'), the plus sign (`+'), and the underscore
(`_').
address The address to assign to the device. Only 7-bit
addresses are permitted. The string will be parsed
according to the specified base. It is recommended to
specify addresses in hexadecimal with the leading "0x".
i2cadm device remove path
Attempts to remove the specified device indicated by the I2C path
path. This may fail if the device is actively being used.
i2cadm mux list [-H] [-o field[,...] [-p]] [filter...]
List all multiplexors known to the system.
The following fields are supported:
DEVICE The name of the I2C device that implements the multiplexor.
NPORTS The number of ports on the multiplexor.
NAME The name of the multiplexor itself.
INSTANCE The device driver instance that powers the multiplexor.
PATH The I2C path of the multiplexor.
The following options are supported:
-H Omit the column header when printing output.
-o field[,...]
A comma-delineated list of fields to output, selected
from the ones above.
-p Displays the output in a machine-parsable format. When
requesting parsable output, the -o option is required to
specifically control which fields are included.
The following operands are supported:
filter One or more filters may be specified which are used to
constrain the list of multiplexors that are printed.
Each filter may either match the multiplexor name, its
device's name, or its device's driver.
If any filter is specified and does not match, then
that is treated as an error.
Because these are filters, they do not control the
order that items are printed out, only what is printed
out.
i2cadm port list [-H] [-o field[,...] [-p]] [filter...]
List all ports known to the system.
The following fields are supported:
PATH The I2C path of the port.
TYPE Indicates the type of port. One of the following values:
controller The port belongs to a controller.
multiplexor The port belongs to a mux.
NAME The name of the port. Port names generally follow the
datasheet and are either 0-based or 1-based.
PORTNO The 0-based system assigned ID for this port.
NDEVS The number of devices that are directly under this port.
This does not include devices that are under subsequent ports
like a multiplexor.
TDEVS The total number of devices that are under this port,
including all multiplexors.
The following options are supported:
-H Omit the column header when printing output.
-o field[,...]
A comma-delineated list of fields to output, selected
from the ones above.
-p Displays the output in a machine-parsable format. When
requesting parsable output, the -o option is required to
specifically control which fields are included.
The following operands are supported:
filter One or more filters may be specified which are used to
constrain the list of ports that are printed. Each
filter may either match the port's name, its type, or
its I2C path.
If any filter is specified and does not match, then
that is treated as an error.
Because these are filters, they do not control the
order that items are printed out, only what is printed
out.
i2cadm port map [-H] [-o field[,...] [-p]] port
Prints a map of how addresses are used directly under the specified
port port by devices known to the system. This does not perform I/O
to scan for addresses that could be used but are unknown to the
system, instead use i2cadm scan for that. By default, the command
will output a human-oriented table organized into rows with 16
columns each. For machine parsable stable, output use the -p and -o
options.
The table will use the following characters to indicate specific
cases:
L Indicates that the address corresponds to a device this port.
v Indicates that the address is used downstream of this port by
a device under a mux port. The address in question could not
be assigned to another device because of this.
S Indicates that this address is being treated as a shared
address across multiple instances of a device driver. A list
of shared addresses and the corresponding major numbers and
drivers will be printed following the table.
- Indicates that this address is not in use.
E An unexpected error occurred.
The following fields are supported:
ADDR The I2C address in question. The address is printed in
decimal.
COUNT The number of devices that are using this address in the
port.
TYPE The type of address. One of the following values:
local Indicates that this address is in use by a device
directly on the port.
downstream Indicates that this address is in use by a device
downstream of the port.
shared Indicates that the address is being actively
shared by one or more instances of a given device
driver.
none Indicates that this address is not in use.
error Indicates that information about this addrses is
not available because an error occurred.
MAJOR For shared addresses, indicates the major number of the
driver that is sharing the address.
DRIVER For shared addresses, indicates the name of the device driver
that is sharing the address.
The following options are supported:
-H Omit the column header when printing output.
-o field[,...]
A comma-delineated list of fields to output, selected
from the ones above.
-p Displays the output in a machine-parsable format. When
requesting parsable output, the -o option is required to
specifically control which fields are included.
The following operands are required:
port The I2C path of the port to print information about.
i2cadm io [-m mode] -d destination [-a address] [-c command] [-w wlen]
[-r rlen] [-o output] data
Perform arbitrary I/O to a specific device or address on the I2C bus.
This will perform a single transaction based on the type specified by
the mode argument, which defaults to I2C. Transmitted data will be
taken from the positional arguments and received data will be output
in a hexdump if -o is not specified.
Care should be taken when performing I/O to arbitrary devices. If a
kernel device driver is attached this can potentially confuse the
driver. If the device is modified, this can potentially lead to an
unbootable or unsable system. For example, modifying the EERPOM on a
DRAM device could lead to DRAM training failures. The following
options are supported:
-a address A string that indicates the numeric 7-bit address to send
the I/O to.
-c command An SMBus command to send. This option is only valid when
using an SMBus mode with -m that requires a command to be
specified.
-d destination
An I2C path that indicates where the I/O should target.
If this is a port, then an address must be specified with
the -a option. If the path includes mux ports, they will
be implicitly activated as part of performing this
operation. If the path ends at a device, the device's
primary address (reg[0]) will be used.
-m mode Specifies the type of I/O request that should be sent.
The following types are supported:
i2c Perform a general I2C transaction. One
or both of -r and -w must be used and
non-zero.
quick-read Perform an SMBus quick read. No data
arguments may be specified or are
required.
quick-write Perform an SMBus quick write. No data
arguments may be specified or are
required.
recv-u8 Receive a single byte. No data
arguments may be specified or are
required.
read-u8 Perform the SMBus read byte operation.
An SMBus command must be specified with
-c.
read-u16 Perform the SMBus read word operation.
An SMBus command must be specified with
-c.
read-u32 Perform the SMBus read u32 operation.
An SMBus command must be specified with
-c.
read-u64 Perform the SMBus read u64 operation.
An SMBus command must be specified with
-c.
read-block-i2c Perform an SMBus I2C block read
operation. An SMBus command must be
specified with -c. A read length must
be specified with -r. It will not be
sent on the wire, unlike a traditional
SMBus block read.
send-u8 Transmit a single byte.
write-u8 Perform the SMBus write byte operation.
An SMBus command must be specified with
-c and a single data operand must be
specified.
write-u16 Perform the SMBus write word operation.
An SMBus command must be specified with
-c and a single data operand must be
specified.
write-u32 Perform the SMBus write u32 operation.
An SMBus command must be specified with
-c and a single data operand must be
specified.
write-u64 Perform the SMBus write u64 operation.
An SMBus command must be specified with
-c and a single data operand must be
specified.
write-block Perform an SMBus write block operation.
SMBus block write with command and
length An SMBus command must be
specified with -c and the number of byte
to write must be specified with -w.
Both the command and the write length
will be sent on the wire. There must be
a single-byte positional argument for
each byte indicated with -w.
write-block-i2c Operates as per write-block above, but
the byte length is not sent on the wire.
call Performs the SMBus process call
operation. An SMBus command must be
specified with -c and a single
positional data argument must be
specified. Process call transmits and
then reads a u16.
-o output Send received binary data to the file output rather than
performing a hexadecimal dump to standard out.
-r rlen Specifies the number of bytes that should be read from
the device.
-w wlen Specifies the number of bytes that should be transmitted
to the device. There must be one positional argument for
each byte that should be transmitted.
i2cadm scan [-d device] [-H] [-o field[,...] [-p]] port
Scan the specified I2C port for devices. This works by attempting to
perform I/O to every non-reserved address on the bus. If the port
belongs to a mux, then all of the appropriate mux segments will be
enabled prior to performing the scan. The command will output a
human-oriented table by default organized into rows with 16 columns
each. For machine parsable, stable output use the -p and -o options.
The table will use the following characters to indicate specific
cases:
@ Indicates that a device was found at the address.
- Indicates that no device was found at the address.
S Indicates that the address was skipped as the -d option was
used and the address in question wasn't listed.
R Indicates that the address is considered reserved and
therefore was not scanned.
X Indicates that a time out occurred.
Err Indicates that an error occurred. Following the table, a
list of address-specific errors will be printed.
Unfortunately, the only way to determine if a device is there is by
attempting to do I/O to it. The scan defaults to performing a single
byte read. Note, there is no safe way to scan for devices and it is
quite possible for system damage to occur from scanning!
The following fields are supported when using machine parsable
output:
ADDR The I2C address that was scanned, printed in hexadecimal.
RESULT A string that describes the result. Valid strings include:
"found", "missing", "reserved", "timeout", "error", and
"skipped".
ERROR A string that includes information about the error that
occurred. This is only valid if the RESULT field is error.
The following options are supported:
-d device Restrict the scan to the specified I2C address. This may
be specified multiple times to only scan a subset of
devices.
-H Omit the column header when printing output.
-o field[,...]
A comma-delineated list of fields to output, selected
from the ones above.
-p Displays the output in a machine-parsable format. When
requesting parsable output, the -o option is required to
specifically control which fields are included.
The following operands are required:
port An I2C path that terminates at a port. If the port is
downstream of a multiplexor, all of the segments
required to send to that port will be enabled, allowing
the results to be included in the scan. Otherwise,
multiplexors will be disabled during the scan.
The system supports a number of named I2C properties. Properties are
consider either read-only or read-write. Some properties may be read-
write on one controller and then read-only or possibly even unsupported
on another controller. Whether a property is supported, is writable,
and the valid values a property can take will vary from one controller
to another.
There are some properties which control timing parameters on the I2C
bus. These properties often have a single instance for each speed that
the I2C bus can operate at. This allows for one to set the tuning
properties to the correct value before changing the speed without
impacting the current operation.
Properties have a specific type which is either the u32 or bit32 which
are 32-bit integers that represent a single value or a bitfield where
each bit conveys its own meaning respectively. A few properties such
as speed, type, and smbus-ops have well known string values that
correspond to fields. By default the tools print the stable human-
readable strings for these. Properties with these are called out in
the property table.
The following properties are supported:
speed Describes the frequency of the bus. This is a u32
that is translated to the following string values:
standard 100 kHz standard operation.
fast 400 kHz fast-mode operation.
fast-plus 1 MHz fast-mode plus operation.
high 3.4 MHz high-speed operation.
ultra 5 MHz ultra-fast operation.
ports A u32 property that indicates the number of ports
under the controller. This property is always read-
only and generally will be 1.
type Describes the type of controller. This is always
read-only u32 property that is translated to the
following string values:
i2c Indicates that this is an I2C controller.
i3c Indicates that this is an I3C controller.
smbus Indicates that this is an SMBus controller.
Some controllers can support more than one I/O
command request. For example, all I3C controllers
support operating as an I2C controller. Similarly
some SMBus controllers support first-class I2C
operation. This property only indicates the primary
mode of the controller.
smbus-ops Describes the set of SMBus operations that the
controller supports. This is a read-only bit32
property that is translated to the following string
values:
quick The controller supports the SMBus
quick read and write operation.
send-byte The controller supports the SMBus
send byte operation.
recv-byte The controller supports the SMBus
receive byte operation.
write-byte The controller supports the SMBus
write byte operation.
read-byte The controller supports the SMBus
read byte operation.
write-word The controller supports the SMBus
write word (16-bit) operation.
read-word The controller supports the SMBus
read word (16-bit) operation.
process-call The controller supports the SMBus
process call operation which
transmits a 16-bit value and then
reads back a 16-bit value.
write-block The controller supports the SMBus
write block operation which
transmits the SMBus command, the
byte length, and all the bytes.
read-block The controller supports the SMBus
read block operation which reads a
variable number of bytes that are
indicated by the target.
host-notify The controller supports sending out
the host notification command. This
is generally only used for SMBus
targets and not controllers.
block-call The controller supports the SMBus
block call operation which transmits
and then receives a variable number
of bytes.
write-u32 The controller supports the SMBus
write 32-bit operation.
read-u32 The controller supports the SMBus
read 32-bit operation.
write-u64 The controller supports the SMBus
write 64-bit operation.
read-u64 The controller supports the SMBus
read 64-bit operation.
write-i2c-block The controller supports a variant of
the write block operation that is
compatible with I2C by not
transmitting the number of bytes
that the controller will send.
read-i2c-block The controller supports a variant of
the read block operation that is
compatible with I2C by explicitly
reading a fixed number of bytes.
The number of bytes is not
transmitted on the wire.
i2c-max-read This is a read-only u32 property that indicates the
largest I2C read the controller can receive in one
operation.
i2c-max-write This is a read-only u32 property that indicates the
largest I2C write the controller can transmit in one
operation.
smbus-max-block This is a read-only u32 property that indicates the
largest SMBus block operation the controller can
perform.
clock-Thigh-std This property indicates the high period of the I2C
clock. It is a u32 property that is counted in terms
of clock cycles. This property only applies when the
bus is operating at standard speed.
clock-Tlow-std This property indicates the low period of the I2C
clock. It is a u32 property that is counted in terms
of clock cycles. This property only applies when the
bus is operating at standard speed.
clock-Thigh-fast This property indicates the high period of the I2C
clock. It is a u32 property that is counted in terms
of clock cycles. This property only applies when the
bus is operating at fast-mode and fast-mode plus
speeds.
clock-Tlow-fast This property indicates the low period of the I2C
clock. It is a u32 property that is counted in terms
of clock cycles. This property only applies when the
bus is operating at fast-mode and fast-mode plus
speeds.
clock-Thigh-high This property indicates the high period of the I2C
clock. It is a u32 property that is counted in terms
of clock cycles. This property only applies when the
bus is operating at fast-mode and high speed.
clock-Tlow-high This property indicates the low period of the I2C
clock. It is a u32 property that is counted in terms
of clock cycles. This property only applies when the
bus is operating at fast-mode and high speed.
The i2cadm utility exits 0 on success. If an error occurs, it exits 1,
and provides additional details about the underlying cause of the
error. If there was an invalid or missing command line options, then
i2cadm exits 2.
When performing a listing operation, if no items are listed or if a
filter is specified but is not matched, then these conditions are all
treated as errors and i2cadm exits 1.
Example 1 Listing Controllers
This example shows how to discover I2C and SMBus controllers in the
system.
# i2cadm controller list
NAME TYPE SPEED NPORTS PROVIDER
ismt0 smbus standard 1 /pci@0,0/pci8086,7270@f/i2cnex@ismt0
pchsmbus0 smbus standard 1 /pci@0,0/pci8086,7270@1f,
4/i2cnex@pchsmbus0
The controller information can be changed by requesting specific fields
or adding a filter:
# i2cadm controller list -o name,speed ismt
NAME SPEED
ismt0 standard
Example 2 Listing Devices
This example shows how to discover the I2C devices that the system
knows about.
# i2cadm device list
NAME ADDR INSTANCE PATH
at24c32 0x50 at24c0 ismt0/0/0x50
pca9548 0x72 pca954x0 pchsmbus0/0/0x72
pca9548 0x73 pca954x1 pchsmbus0/0/0x73
pca9548 0x74 pca954x2 pchsmbus0/0/0x74
pca9548 0x75 pca954x3 pchsmbus0/0/0x75
pca9548 0x76 pca954x4 pchsmbus0/0/0x76
tmp431 0x4c tmp43x0 pchsmbus0/0/0x72/6/0x4c
lm75 0x48 lm7x0 pchsmbus0/0/0x73/1/0x48
lm75 0x49 lm7x1 pchsmbus0/0/0x73/1/0x49
lm75 0x4a lm7x2 pchsmbus0/0/0x73/1/0x4a
lm75 0x4b lm7x3 pchsmbus0/0/0x73/1/0x4b
lm75 0x4c lm7x4 pchsmbus0/0/0x73/1/0x4c
lm75 0x4d lm7x5 pchsmbus0/0/0x73/1/0x4d
lm75 0x4e lm7x6 pchsmbus0/0/0x73/1/0x4e
lm75 0x4f lm7x7 pchsmbus0/0/0x73/1/0x4f
One can also print out a subset of devices in a parsable form:
# i2cadm device list -Hpo name,path lm75
lm75:pchsmbus0/0/0x73/1/0x48
lm75:pchsmbus0/0/0x73/1/0x49
lm75:pchsmbus0/0/0x73/1/0x4a
lm75:pchsmbus0/0/0x73/1/0x4b
lm75:pchsmbus0/0/0x73/1/0x4c
lm75:pchsmbus0/0/0x73/1/0x4d
lm75:pchsmbus0/0/0x73/1/0x4e
lm75:pchsmbus0/0/0x73/1/0x4f
Example 3 Adding a Device
This example shows how we would add an AT24C32 EEPROM that is at
address 0x50.
# i2cadm device add ismt0/0 at24c32 0x50
# i2cadm device list at24c32
NAME ADDR INSTANCE PATH
at24c32 0x50 at24c0 ismt0/0/0x50
Let's say we now wanted to add a TMP431 with 7-bit address address 0x4c
that is under port 6 of an 8-port PCA9548 at 0x72:
# i2cadm mux list pca954x0
DEVICE NPORTS NAME INSTANCE PATH
pca9548 8 pca954x0 pca954x0 pchsmbus0/0/0x72
# i2cadm device add pchsmbus0/0/0x72/6 tmp431 0x4c
# i2cadm device list tmp431
NAME ADDR INSTANCE PATH
tmp431 0x4c tmp43x0 pchsmbus0/0/0x72/6/0x4c
Example 4 Scanning an I2C bus
This shows
# i2cadm scan pchsmbus0/0
Device scan on pchsmbus0/0:
- = No Device @ = Device Found
R = Reserved S = Skipped
X = Timed Out Err = Error
ADDR 0x0 0x1 0x2 0x3 0x4 0x5 0x6 0x7 0x8 0x9 0xa 0xb 0xc 0xd 0xe 0xf
0x00 R R R R R R R R - - - - - - - -
0x10 - - - - - - - - - - - - - - - -
0x20 - - - - - - - - - - - - - - - -
0x30 - - - - - - - - - - - - - - - -
0x40 - - - - @ - - - - - - - - - - -
0x50 - - - - - - - - - - - - - - - -
0x60 - - - - - - - - @ - - - - - - -
0x70 - - @ @ @ @ @ - R R R R R R R R
To instead scan on a port of a given mux, you would change the path to
indicate that. For example:
# i2cadm scan pchsmbus0/0/0x72/6
Device scan on pchsmbus0/0/0x72/6:
- = No Device @ = Device Found
R = Reserved S = Skipped
X = Timed Out Err = Error
ADDR 0x0 0x1 0x2 0x3 0x4 0x5 0x6 0x7 0x8 0x9 0xa 0xb 0xc 0xd 0xe 0xf
0x00 R R R R R R R R - - - - - - - -
0x10 - - - - - - - - - - - - - - - -
0x20 - - - - - - - - - - - - - - - -
0x30 - - - - - - - - - - - - - - - -
0x40 - - - - @ - - - - - - - @ - - -
0x50 - - - - - - - - - - - - - - - -
0x60 - - - - - - - - @ - - - - - - -
0x70 - - @ @ @ @ @ - R R R R R R R R
Example 5 Printing a Port Address Map
The following shows how to see a list of addresses that are in use on a
given port according to the system. This may not be every device that
is present on the bus as the system may not have been told about them.
# i2cadm port map pchsmbus0/0
Address map for pchsmbus0/0:
- = No Device L = Local Device
S = Shared v = Downstream
E = Error
ADDR 0x0 0x1 0x2 0x3 0x4 0x5 0x6 0x7 0x8 0x9 0xa 0xb 0xc 0xd 0xe 0xf
0x00 - - - - - - - - - - - - - - - -
0x10 - - - - - - - - - - - - - - - -
0x20 - - - - - - - - - - - - - - - -
0x30 - - - - - - - - - - - - - - - -
0x40 - - - - - - - - 1v 1v 1v 1v 2v 1v 1v 1v
0x50 - - - - - - - - - - - - - - - -
0x60 - - - - - - - - - - - - - - - -
0x70 - - L L L L L - - - - - - - - -
In this case there are a number of downstream devices on this port that
are below the muxes. If we then ask for the map of everything on a
given mux port that most of those are on we'd instead see:
# i2cadm port map pchsmbus0/0/0x73/1
Address map for pchsmbus0/0/0x73/1:
- = No Device L = Local Device
S = Shared v = Downstream
E = Error
ADDR 0x0 0x1 0x2 0x3 0x4 0x5 0x6 0x7 0x8 0x9 0xa 0xb 0xc 0xd 0xe 0xf
0x00 - - - - - - - - - - - - - - - -
0x10 - - - - - - - - - - - - - - - -
0x20 - - - - - - - - - - - - - - - -
0x30 - - - - - - - - - - - - - - - -
0x40 - - - - - - - - L L L L L L L L
0x50 - - - - - - - - - - - - - - - -
0x60 - - - - - - - - - - - - - - - -
0x70 - - - - - - - - - - - - - - - -
The command line interface of i2cadm is Evolving. The output of i2cadm
is Not-An-Interface and may change at any time.
ofmt(3OFMT)
illumos October 4, 2025 illumos
NAME
i2cadm - I2C administration
SYNOPSIS
i2cadm controller list [-H] [-o field[,...] [-p]] [filter...]
i2cadm controller prop get [-H] [-o field[,...] [-p]] controller
[filter...]
i2cadm controller prop set controller property=value
i2cadm device list [-H] [-o field[,...] [-p]] [filter...]
i2cadm device addrs [-H] [-o field[,...] [-p]] [filter...]
i2cadm device add [-c compat] port name address
i2cadm device remove path
i2cadm mux list [-H] [-o field[,...] [-p]] [filter...]
i2cadm port list [-H] [-o field[,...] [-p]] [filter...]
i2cadm port map [-H] [-o field[,...] [-p]] port
i2cadm io [-m mode] -d destination [-a address] [-c command] [-w wlen]
[-r rlen] [-o output] data
i2cadm scan [-d device] [-H] [-o field[,...] [-p]] port
DESCRIPTION
The i2cadm utility is used to enumerate and manipulate I2C and SMBus
controllers, devices, ports, and multiplexors.
There are four top-level objects in i2cadm;
Controllers
These are hardware device that can perform I2C or SMBus
operations that target devices on the bus. i2cadm provides the
ability to list them as well as get and set properties on
specific controllers.
Devices
Device represent targets on the I2C bus which provide some
functionality at a given address. Devices run the gamut
including functions like EEPROMs, sensors, GPIO controllers,
voltage regulators, and more. Many devices will have a
corresponding device driver that provides functionality through
a standard system mechanism, but there is no requirement for a
driver.
Ports A port is a logical point on an I2C bus under which one or more
devices can be found. I2C ports are found directly under
controllers and multiplexors. I2C ports under a controller
represent the start of a unique I2C bus and addresses that are
used are specific to that bus. i2cadm provides the ability to
list ports and print information about the addresses that are
in use on the port directly or downstream of it.
Multiplexors
Multiplexors provide a means of isolating segments of an I2C
bus from one another, which is generally used to avoid
overlapping I2C addresses. A multiplexor provides a fixed
number of ports and the system will transparently activate and
deactivate ports based on I/O requests and their targets. At
most one port will ever be active on a multiplexor at any given
time. i2cadm provides the ability to discover and list
multiplexors.
All listing operations leverage the standard illumos output format
library (ofmt(3OFMT)) allowing the selection of specific output fields,
the omission of the header (-H), and a parsable mode intended for
programmatic consumption (-p). When requesting parsable output, the
colon (":") character is used as a delimiter between fields and any
delimiters that would appear in an output field will be escaped with a
backslash character ("\").
Getting information about I2C devices, controllers, ports, and muxes
requires that a process have the {PRIV_SYS_DEVICES} privilege.
I2C Paths
All of the different entities that can be found on an I2C bus are
described through a path that indicates the route through the bus to
get to an entity. Consider the following I2C devices:
+------------+
| dwi2c4 |
| 1 port |
| controller |
+------------+ +------+
| | lm75 |
+---------->| 0x48 |
| +------+
v
+------------+
| pca9548 |
| 0x72 |
| 8 port mux |
+------------+
|
* ... port 0, 1-7 not pictured
|
v
+------------+
| pca9545 |
| 0x72 |
| 4 port mux |
+------------+
|
* ... port 2, 0-1,3 not pictured
|
v
+---------+
| at24c02 |
| 0x57 |
| EEPROM |
+---------+
The following are what different paths refer to for this:
dwi2c4 This refers to the controller itself.
dwi2c4/0 This refers to the primary port under
a controller. This could be used for
performing device scans, I/O, or
manually adding or removing devices.
dwi2c4/0/0x48 This refers to the LM75 temperature
sensor that is directly attached to
the controller's port.
dwi2c4/0/0x72 This string refers to the 8-port mux
directly under the controller's port.
dwi2c4/0/0x72/0/0x70/2/0x57 This is a complex string that refers
to the AT24C02 EEPROM. Along the way
are all of the devices and ports that
are used to get to it. A more
verbose form of this path would be
dwi2c4/0/pca9548@0x72/0/pca9545@0x70/2/at24c02@0x57.
When constructing paths, controllers are always referred to by their
name and instance. Ports are always referred to by their name, which
is usually a number based upon the datasheet. Devices can be referred
to in three ways at their point in the tree. Using the first mux as an
example:
1. Using the device's primary I2C address: `0x72'.
2. Using the device's name and primary address: `pca9548@0x72'.
3. Using the device's driver name and instance: `pca9454x0'.
SUBCOMMANDS
The following commands are supported by i2cadm:
i2cadm controller list [-H] [-o field[,...] [-p]] [filter...]
List all of the I2C controllers in the system and provide basic
information about them.
The following fields are supported:
NAME This is the name of the I2C controller in the system. All
I2C paths will start with a controller name.
TYPE This is the primary type of the controller, but is not
indicative of all I/O that they can perform. An SMBus
controller may support directly performing I2C. The valid
controller types are:
i2c An I2C controller.
i3c An I3C controller.
smbus An SMBus controller.
SPEED A string that describe the speed that the bus is operating
at, along with some of the physical capabilities. The
valid speed values are:
standard Standard speed operates the bus at 100 kHz.
fast Fast speed operates the bus at 400 kHz.
fast-plus Fast-plus speed operates the bus at 1 MHz.
high High-speed operate the bus at 3.4 MHz.
ultra Ultra-fast speed operate the bus at 5 MHz.
NPORTS The number of ports that are under the controller.
DRIVER The name of the driver for the controller.
INSTANCE The name of the device driver instance for the controller.
PROVIDER The /devices path to the kernel provider for this
controller.
The following options are supported:
-H Omit the column header when printing output.
-o field[,...]
A comma-delineated list of fields to output, selected
from the ones above.
-p Displays the output in a machine-parsable format. When
requesting parsable output, the -o option is required to
specifically control which fields are included.
The following operands are supported:
filter One or more filters may be specified which are used to
constrain the list of controllers that are printed.
Each filter may either match the name of a controller
or driver.
If any filter is specified and does not match, then
that is treated as an error.
Because these are filters, they do not control the
order that items are printed out, only what is printed
out.
i2cadm controller prop get [-H] [-o field[,...] [-p]] controller
[filter...]
List all properties, their values, and corresponding metadata on the
specific controller controller.
The following fields are supported:
PROPERTY The name of the property.
PERM Indicates whether the property is readable or both readable
and writable.
VALUE The current value of the property.
DEFAULT The default value for the property on the specific instance
of the controller. This is the value the system will start
with assuming no tuning has been performed. Some
properties may not have a default value.
POSSIBLE A list of possible values that the property might take.
This may be a series of numeric ranges or a list of
specific values. Some properties may not have a set of
possible values.
TYPE Indicates the type of the property. The system has the
following I2C property types:
u32 Indicates that the property is a 32-bit unsigned
value.
bit32 Indicates that the property is a 32-bit unsigned
bitfield. The presence or absence of each bit
indicates a specific feature or property.
CONTROLLER
The name of the controller the property is being retrieved
from.
ID The system's numeric identifier for the property.
The following options are supported:
-H Omit the column header when printing output.
-o field[,...]
A comma-delineated list of fields to output, selected
from the ones above.
-p Displays the output in a machine-parsable format. When
requesting parsable output, the -o option is required to
specifically control which fields are included.
The following operands are supported:
filter One or more filters may be specified which are used to
constrain the list of properties that are printed.
Each filter must match the name of a property. For a
list of properties, see the PROPERTIES section.
If any filter is specified and does not match, then
that is treated as an error.
Because these are filters, they do not control the
order that items are printed out, only what is printed
out.
i2cadm controller prop set controller property=value
Set the value of a single named property on the controller,
controller, to the indicated value. value will be parsed based upon
the specific property and its type. Properties which are translated
into strings, can be specified as either an integer value or the
corresponding string.
To see the list of properties on a controller use i2cadm controller
prop get. For a list of all properties, see the PROPERTIES section.
i2cadm device list [-H] [-o field[,...] [-p]] [filter...]
Lists basic information about all devices known to the system across
all controllers. These are devices that have been discovered through
a platform-specific means or explicitly added by an administrator
through the i2cadm device add command.
The following fields are supported:
NAME The name of the device. This corresponds to the device
tree's node name.
ADDR The primary I2C address that this device has. This
corresponds to the device tree's reg[0] entry.
INSTANCE The driver instance of the device, if any.
PATH The I2C path of the device.
The following options are supported:
-H Omit the column header when printing output.
-o field[,...]
A comma-delineated list of fields to output, selected
from the ones above.
-p Displays the output in a machine-parsable format. When
requesting parsable output, the -o option is required to
specifically control which fields are included.
The following operands are supported:
filter One or more filters may be specified which are used to
constrain the list of properties that are printed.
Each filter may match a device's primary address, a
device name, a driver name, a driver instance, or a
portion of the device's I2C path.
If any filter is specified and does not match, then
that is treated as an error.
Because these are filters, they do not control the
order that items are printed out, only what is printed
out.
i2cadm device addrs [-H] [-o field[,...] [-p]] [filter...]
Print the I2C addresses and their sources for device's in the system.
A device's address may come from the platform or it may be an
additional address that the driver itself claims and is either unique
to that device or shared amongst all instance of a particular driver.
The following fields are supported:
PATH The I2C path of the device.
TYPE The type of the address. This is either 7-bit or 10-bit.
ADDR The address in question on the device.
SOURCE Indicates how the device was assigned the address. One of
the following values:
platform This address came from information provided by the
platform. This includes firmware sources or
addresses assigned as part of an operator calling
i2cadm device add.
claimed This addresses was claimed exclusively by the
device driver. For example, several EEPROMs
require multiple I2C addresses to cover their
entire memory map, but only the base address is
often provided by the platform.
shared This address was claimed by a device driver and is
permitted to be used across all instances of the
device driver.
The following options are supported:
-H Omit the column header when printing output.
-o field[,...]
A comma-delineated list of fields to output, selected
from the ones above.
-p Displays the output in a machine-parsable format. When
requesting parsable output, the -o option is required to
specifically control which fields are included.
The following operands are supported:
filter One or more filters may be specified which are used to
constrain the list of properties that are printed.
Each filter may match a device's particular address, a
device name, a driver name, a driver instance, or a
portion of the device's I2C path.
If any filter is specified and does not match, then
that is treated as an error.
Because these are filters, they do not control the
order that items are printed out, only what is printed
out.
i2cadm device add [-c compat] port name address
Add a new device to the system. The system will attempt to attach a
driver to this device; however, even if there is no driver for the
device, it can be created regardless.
The following options are supported:
-c compat Add the specified compatibility entry compat to the newly
created device node's `compatible' property. When the
system considers device drivers to attach to an I2C
device it will search for matches against the device's
`compatible' property and then attempt to match the
device's name.
This property may be specified multiple times in order to
add multiple entries. The order is meaningful and will
reflect the order specified on the command line. The
matching algorithm walks the list in order and terminates
on the first found match. More specific entries should
be specified first.
The following operands are supported:
port Specifies the I2C path to the port that the device will
be created under. This may be either a port on a
controller or a port under a multiplexor. Device's
under a mux are allowed to have conflicting addresses
with devices on other ports of a given mux. The mux
will be implicitly activated when performing I/O to the
device.
name The name of the new device. This generally should
match something about the device itself such as the
part number.
Device name's may be at most 31 characters. The first
character must be an upper or lower case letter. The
remaining characters may be upper or lower case
letters, numbers, or one of the following punctuation
characters: the comma (`,'), the period (`.'), the
hyphen (`-'), the plus sign (`+'), and the underscore
(`_').
address The address to assign to the device. Only 7-bit
addresses are permitted. The string will be parsed
according to the specified base. It is recommended to
specify addresses in hexadecimal with the leading "0x".
i2cadm device remove path
Attempts to remove the specified device indicated by the I2C path
path. This may fail if the device is actively being used.
i2cadm mux list [-H] [-o field[,...] [-p]] [filter...]
List all multiplexors known to the system.
The following fields are supported:
DEVICE The name of the I2C device that implements the multiplexor.
NPORTS The number of ports on the multiplexor.
NAME The name of the multiplexor itself.
INSTANCE The device driver instance that powers the multiplexor.
PATH The I2C path of the multiplexor.
The following options are supported:
-H Omit the column header when printing output.
-o field[,...]
A comma-delineated list of fields to output, selected
from the ones above.
-p Displays the output in a machine-parsable format. When
requesting parsable output, the -o option is required to
specifically control which fields are included.
The following operands are supported:
filter One or more filters may be specified which are used to
constrain the list of multiplexors that are printed.
Each filter may either match the multiplexor name, its
device's name, or its device's driver.
If any filter is specified and does not match, then
that is treated as an error.
Because these are filters, they do not control the
order that items are printed out, only what is printed
out.
i2cadm port list [-H] [-o field[,...] [-p]] [filter...]
List all ports known to the system.
The following fields are supported:
PATH The I2C path of the port.
TYPE Indicates the type of port. One of the following values:
controller The port belongs to a controller.
multiplexor The port belongs to a mux.
NAME The name of the port. Port names generally follow the
datasheet and are either 0-based or 1-based.
PORTNO The 0-based system assigned ID for this port.
NDEVS The number of devices that are directly under this port.
This does not include devices that are under subsequent ports
like a multiplexor.
TDEVS The total number of devices that are under this port,
including all multiplexors.
The following options are supported:
-H Omit the column header when printing output.
-o field[,...]
A comma-delineated list of fields to output, selected
from the ones above.
-p Displays the output in a machine-parsable format. When
requesting parsable output, the -o option is required to
specifically control which fields are included.
The following operands are supported:
filter One or more filters may be specified which are used to
constrain the list of ports that are printed. Each
filter may either match the port's name, its type, or
its I2C path.
If any filter is specified and does not match, then
that is treated as an error.
Because these are filters, they do not control the
order that items are printed out, only what is printed
out.
i2cadm port map [-H] [-o field[,...] [-p]] port
Prints a map of how addresses are used directly under the specified
port port by devices known to the system. This does not perform I/O
to scan for addresses that could be used but are unknown to the
system, instead use i2cadm scan for that. By default, the command
will output a human-oriented table organized into rows with 16
columns each. For machine parsable stable, output use the -p and -o
options.
The table will use the following characters to indicate specific
cases:
L Indicates that the address corresponds to a device this port.
v Indicates that the address is used downstream of this port by
a device under a mux port. The address in question could not
be assigned to another device because of this.
S Indicates that this address is being treated as a shared
address across multiple instances of a device driver. A list
of shared addresses and the corresponding major numbers and
drivers will be printed following the table.
- Indicates that this address is not in use.
E An unexpected error occurred.
The following fields are supported:
ADDR The I2C address in question. The address is printed in
decimal.
COUNT The number of devices that are using this address in the
port.
TYPE The type of address. One of the following values:
local Indicates that this address is in use by a device
directly on the port.
downstream Indicates that this address is in use by a device
downstream of the port.
shared Indicates that the address is being actively
shared by one or more instances of a given device
driver.
none Indicates that this address is not in use.
error Indicates that information about this addrses is
not available because an error occurred.
MAJOR For shared addresses, indicates the major number of the
driver that is sharing the address.
DRIVER For shared addresses, indicates the name of the device driver
that is sharing the address.
The following options are supported:
-H Omit the column header when printing output.
-o field[,...]
A comma-delineated list of fields to output, selected
from the ones above.
-p Displays the output in a machine-parsable format. When
requesting parsable output, the -o option is required to
specifically control which fields are included.
The following operands are required:
port The I2C path of the port to print information about.
i2cadm io [-m mode] -d destination [-a address] [-c command] [-w wlen]
[-r rlen] [-o output] data
Perform arbitrary I/O to a specific device or address on the I2C bus.
This will perform a single transaction based on the type specified by
the mode argument, which defaults to I2C. Transmitted data will be
taken from the positional arguments and received data will be output
in a hexdump if -o is not specified.
Care should be taken when performing I/O to arbitrary devices. If a
kernel device driver is attached this can potentially confuse the
driver. If the device is modified, this can potentially lead to an
unbootable or unsable system. For example, modifying the EERPOM on a
DRAM device could lead to DRAM training failures. The following
options are supported:
-a address A string that indicates the numeric 7-bit address to send
the I/O to.
-c command An SMBus command to send. This option is only valid when
using an SMBus mode with -m that requires a command to be
specified.
-d destination
An I2C path that indicates where the I/O should target.
If this is a port, then an address must be specified with
the -a option. If the path includes mux ports, they will
be implicitly activated as part of performing this
operation. If the path ends at a device, the device's
primary address (reg[0]) will be used.
-m mode Specifies the type of I/O request that should be sent.
The following types are supported:
i2c Perform a general I2C transaction. One
or both of -r and -w must be used and
non-zero.
quick-read Perform an SMBus quick read. No data
arguments may be specified or are
required.
quick-write Perform an SMBus quick write. No data
arguments may be specified or are
required.
recv-u8 Receive a single byte. No data
arguments may be specified or are
required.
read-u8 Perform the SMBus read byte operation.
An SMBus command must be specified with
-c.
read-u16 Perform the SMBus read word operation.
An SMBus command must be specified with
-c.
read-u32 Perform the SMBus read u32 operation.
An SMBus command must be specified with
-c.
read-u64 Perform the SMBus read u64 operation.
An SMBus command must be specified with
-c.
read-block-i2c Perform an SMBus I2C block read
operation. An SMBus command must be
specified with -c. A read length must
be specified with -r. It will not be
sent on the wire, unlike a traditional
SMBus block read.
send-u8 Transmit a single byte.
write-u8 Perform the SMBus write byte operation.
An SMBus command must be specified with
-c and a single data operand must be
specified.
write-u16 Perform the SMBus write word operation.
An SMBus command must be specified with
-c and a single data operand must be
specified.
write-u32 Perform the SMBus write u32 operation.
An SMBus command must be specified with
-c and a single data operand must be
specified.
write-u64 Perform the SMBus write u64 operation.
An SMBus command must be specified with
-c and a single data operand must be
specified.
write-block Perform an SMBus write block operation.
SMBus block write with command and
length An SMBus command must be
specified with -c and the number of byte
to write must be specified with -w.
Both the command and the write length
will be sent on the wire. There must be
a single-byte positional argument for
each byte indicated with -w.
write-block-i2c Operates as per write-block above, but
the byte length is not sent on the wire.
call Performs the SMBus process call
operation. An SMBus command must be
specified with -c and a single
positional data argument must be
specified. Process call transmits and
then reads a u16.
-o output Send received binary data to the file output rather than
performing a hexadecimal dump to standard out.
-r rlen Specifies the number of bytes that should be read from
the device.
-w wlen Specifies the number of bytes that should be transmitted
to the device. There must be one positional argument for
each byte that should be transmitted.
i2cadm scan [-d device] [-H] [-o field[,...] [-p]] port
Scan the specified I2C port for devices. This works by attempting to
perform I/O to every non-reserved address on the bus. If the port
belongs to a mux, then all of the appropriate mux segments will be
enabled prior to performing the scan. The command will output a
human-oriented table by default organized into rows with 16 columns
each. For machine parsable, stable output use the -p and -o options.
The table will use the following characters to indicate specific
cases:
@ Indicates that a device was found at the address.
- Indicates that no device was found at the address.
S Indicates that the address was skipped as the -d option was
used and the address in question wasn't listed.
R Indicates that the address is considered reserved and
therefore was not scanned.
X Indicates that a time out occurred.
Err Indicates that an error occurred. Following the table, a
list of address-specific errors will be printed.
Unfortunately, the only way to determine if a device is there is by
attempting to do I/O to it. The scan defaults to performing a single
byte read. Note, there is no safe way to scan for devices and it is
quite possible for system damage to occur from scanning!
The following fields are supported when using machine parsable
output:
ADDR The I2C address that was scanned, printed in hexadecimal.
RESULT A string that describes the result. Valid strings include:
"found", "missing", "reserved", "timeout", "error", and
"skipped".
ERROR A string that includes information about the error that
occurred. This is only valid if the RESULT field is error.
The following options are supported:
-d device Restrict the scan to the specified I2C address. This may
be specified multiple times to only scan a subset of
devices.
-H Omit the column header when printing output.
-o field[,...]
A comma-delineated list of fields to output, selected
from the ones above.
-p Displays the output in a machine-parsable format. When
requesting parsable output, the -o option is required to
specifically control which fields are included.
The following operands are required:
port An I2C path that terminates at a port. If the port is
downstream of a multiplexor, all of the segments
required to send to that port will be enabled, allowing
the results to be included in the scan. Otherwise,
multiplexors will be disabled during the scan.
PROPERTIES
The system supports a number of named I2C properties. Properties are
consider either read-only or read-write. Some properties may be read-
write on one controller and then read-only or possibly even unsupported
on another controller. Whether a property is supported, is writable,
and the valid values a property can take will vary from one controller
to another.
There are some properties which control timing parameters on the I2C
bus. These properties often have a single instance for each speed that
the I2C bus can operate at. This allows for one to set the tuning
properties to the correct value before changing the speed without
impacting the current operation.
Properties have a specific type which is either the u32 or bit32 which
are 32-bit integers that represent a single value or a bitfield where
each bit conveys its own meaning respectively. A few properties such
as speed, type, and smbus-ops have well known string values that
correspond to fields. By default the tools print the stable human-
readable strings for these. Properties with these are called out in
the property table.
The following properties are supported:
speed Describes the frequency of the bus. This is a u32
that is translated to the following string values:
standard 100 kHz standard operation.
fast 400 kHz fast-mode operation.
fast-plus 1 MHz fast-mode plus operation.
high 3.4 MHz high-speed operation.
ultra 5 MHz ultra-fast operation.
ports A u32 property that indicates the number of ports
under the controller. This property is always read-
only and generally will be 1.
type Describes the type of controller. This is always
read-only u32 property that is translated to the
following string values:
i2c Indicates that this is an I2C controller.
i3c Indicates that this is an I3C controller.
smbus Indicates that this is an SMBus controller.
Some controllers can support more than one I/O
command request. For example, all I3C controllers
support operating as an I2C controller. Similarly
some SMBus controllers support first-class I2C
operation. This property only indicates the primary
mode of the controller.
smbus-ops Describes the set of SMBus operations that the
controller supports. This is a read-only bit32
property that is translated to the following string
values:
quick The controller supports the SMBus
quick read and write operation.
send-byte The controller supports the SMBus
send byte operation.
recv-byte The controller supports the SMBus
receive byte operation.
write-byte The controller supports the SMBus
write byte operation.
read-byte The controller supports the SMBus
read byte operation.
write-word The controller supports the SMBus
write word (16-bit) operation.
read-word The controller supports the SMBus
read word (16-bit) operation.
process-call The controller supports the SMBus
process call operation which
transmits a 16-bit value and then
reads back a 16-bit value.
write-block The controller supports the SMBus
write block operation which
transmits the SMBus command, the
byte length, and all the bytes.
read-block The controller supports the SMBus
read block operation which reads a
variable number of bytes that are
indicated by the target.
host-notify The controller supports sending out
the host notification command. This
is generally only used for SMBus
targets and not controllers.
block-call The controller supports the SMBus
block call operation which transmits
and then receives a variable number
of bytes.
write-u32 The controller supports the SMBus
write 32-bit operation.
read-u32 The controller supports the SMBus
read 32-bit operation.
write-u64 The controller supports the SMBus
write 64-bit operation.
read-u64 The controller supports the SMBus
read 64-bit operation.
write-i2c-block The controller supports a variant of
the write block operation that is
compatible with I2C by not
transmitting the number of bytes
that the controller will send.
read-i2c-block The controller supports a variant of
the read block operation that is
compatible with I2C by explicitly
reading a fixed number of bytes.
The number of bytes is not
transmitted on the wire.
i2c-max-read This is a read-only u32 property that indicates the
largest I2C read the controller can receive in one
operation.
i2c-max-write This is a read-only u32 property that indicates the
largest I2C write the controller can transmit in one
operation.
smbus-max-block This is a read-only u32 property that indicates the
largest SMBus block operation the controller can
perform.
clock-Thigh-std This property indicates the high period of the I2C
clock. It is a u32 property that is counted in terms
of clock cycles. This property only applies when the
bus is operating at standard speed.
clock-Tlow-std This property indicates the low period of the I2C
clock. It is a u32 property that is counted in terms
of clock cycles. This property only applies when the
bus is operating at standard speed.
clock-Thigh-fast This property indicates the high period of the I2C
clock. It is a u32 property that is counted in terms
of clock cycles. This property only applies when the
bus is operating at fast-mode and fast-mode plus
speeds.
clock-Tlow-fast This property indicates the low period of the I2C
clock. It is a u32 property that is counted in terms
of clock cycles. This property only applies when the
bus is operating at fast-mode and fast-mode plus
speeds.
clock-Thigh-high This property indicates the high period of the I2C
clock. It is a u32 property that is counted in terms
of clock cycles. This property only applies when the
bus is operating at fast-mode and high speed.
clock-Tlow-high This property indicates the low period of the I2C
clock. It is a u32 property that is counted in terms
of clock cycles. This property only applies when the
bus is operating at fast-mode and high speed.
EXIT STATUS
The i2cadm utility exits 0 on success. If an error occurs, it exits 1,
and provides additional details about the underlying cause of the
error. If there was an invalid or missing command line options, then
i2cadm exits 2.
When performing a listing operation, if no items are listed or if a
filter is specified but is not matched, then these conditions are all
treated as errors and i2cadm exits 1.
EXAMPLES
Example 1 Listing Controllers
This example shows how to discover I2C and SMBus controllers in the
system.
# i2cadm controller list
NAME TYPE SPEED NPORTS PROVIDER
ismt0 smbus standard 1 /pci@0,0/pci8086,7270@f/i2cnex@ismt0
pchsmbus0 smbus standard 1 /pci@0,0/pci8086,7270@1f,
4/i2cnex@pchsmbus0
The controller information can be changed by requesting specific fields
or adding a filter:
# i2cadm controller list -o name,speed ismt
NAME SPEED
ismt0 standard
Example 2 Listing Devices
This example shows how to discover the I2C devices that the system
knows about.
# i2cadm device list
NAME ADDR INSTANCE PATH
at24c32 0x50 at24c0 ismt0/0/0x50
pca9548 0x72 pca954x0 pchsmbus0/0/0x72
pca9548 0x73 pca954x1 pchsmbus0/0/0x73
pca9548 0x74 pca954x2 pchsmbus0/0/0x74
pca9548 0x75 pca954x3 pchsmbus0/0/0x75
pca9548 0x76 pca954x4 pchsmbus0/0/0x76
tmp431 0x4c tmp43x0 pchsmbus0/0/0x72/6/0x4c
lm75 0x48 lm7x0 pchsmbus0/0/0x73/1/0x48
lm75 0x49 lm7x1 pchsmbus0/0/0x73/1/0x49
lm75 0x4a lm7x2 pchsmbus0/0/0x73/1/0x4a
lm75 0x4b lm7x3 pchsmbus0/0/0x73/1/0x4b
lm75 0x4c lm7x4 pchsmbus0/0/0x73/1/0x4c
lm75 0x4d lm7x5 pchsmbus0/0/0x73/1/0x4d
lm75 0x4e lm7x6 pchsmbus0/0/0x73/1/0x4e
lm75 0x4f lm7x7 pchsmbus0/0/0x73/1/0x4f
One can also print out a subset of devices in a parsable form:
# i2cadm device list -Hpo name,path lm75
lm75:pchsmbus0/0/0x73/1/0x48
lm75:pchsmbus0/0/0x73/1/0x49
lm75:pchsmbus0/0/0x73/1/0x4a
lm75:pchsmbus0/0/0x73/1/0x4b
lm75:pchsmbus0/0/0x73/1/0x4c
lm75:pchsmbus0/0/0x73/1/0x4d
lm75:pchsmbus0/0/0x73/1/0x4e
lm75:pchsmbus0/0/0x73/1/0x4f
Example 3 Adding a Device
This example shows how we would add an AT24C32 EEPROM that is at
address 0x50.
# i2cadm device add ismt0/0 at24c32 0x50
# i2cadm device list at24c32
NAME ADDR INSTANCE PATH
at24c32 0x50 at24c0 ismt0/0/0x50
Let's say we now wanted to add a TMP431 with 7-bit address address 0x4c
that is under port 6 of an 8-port PCA9548 at 0x72:
# i2cadm mux list pca954x0
DEVICE NPORTS NAME INSTANCE PATH
pca9548 8 pca954x0 pca954x0 pchsmbus0/0/0x72
# i2cadm device add pchsmbus0/0/0x72/6 tmp431 0x4c
# i2cadm device list tmp431
NAME ADDR INSTANCE PATH
tmp431 0x4c tmp43x0 pchsmbus0/0/0x72/6/0x4c
Example 4 Scanning an I2C bus
This shows
# i2cadm scan pchsmbus0/0
Device scan on pchsmbus0/0:
- = No Device @ = Device Found
R = Reserved S = Skipped
X = Timed Out Err = Error
ADDR 0x0 0x1 0x2 0x3 0x4 0x5 0x6 0x7 0x8 0x9 0xa 0xb 0xc 0xd 0xe 0xf
0x00 R R R R R R R R - - - - - - - -
0x10 - - - - - - - - - - - - - - - -
0x20 - - - - - - - - - - - - - - - -
0x30 - - - - - - - - - - - - - - - -
0x40 - - - - @ - - - - - - - - - - -
0x50 - - - - - - - - - - - - - - - -
0x60 - - - - - - - - @ - - - - - - -
0x70 - - @ @ @ @ @ - R R R R R R R R
To instead scan on a port of a given mux, you would change the path to
indicate that. For example:
# i2cadm scan pchsmbus0/0/0x72/6
Device scan on pchsmbus0/0/0x72/6:
- = No Device @ = Device Found
R = Reserved S = Skipped
X = Timed Out Err = Error
ADDR 0x0 0x1 0x2 0x3 0x4 0x5 0x6 0x7 0x8 0x9 0xa 0xb 0xc 0xd 0xe 0xf
0x00 R R R R R R R R - - - - - - - -
0x10 - - - - - - - - - - - - - - - -
0x20 - - - - - - - - - - - - - - - -
0x30 - - - - - - - - - - - - - - - -
0x40 - - - - @ - - - - - - - @ - - -
0x50 - - - - - - - - - - - - - - - -
0x60 - - - - - - - - @ - - - - - - -
0x70 - - @ @ @ @ @ - R R R R R R R R
Example 5 Printing a Port Address Map
The following shows how to see a list of addresses that are in use on a
given port according to the system. This may not be every device that
is present on the bus as the system may not have been told about them.
# i2cadm port map pchsmbus0/0
Address map for pchsmbus0/0:
- = No Device L = Local Device
S = Shared v = Downstream
E = Error
ADDR 0x0 0x1 0x2 0x3 0x4 0x5 0x6 0x7 0x8 0x9 0xa 0xb 0xc 0xd 0xe 0xf
0x00 - - - - - - - - - - - - - - - -
0x10 - - - - - - - - - - - - - - - -
0x20 - - - - - - - - - - - - - - - -
0x30 - - - - - - - - - - - - - - - -
0x40 - - - - - - - - 1v 1v 1v 1v 2v 1v 1v 1v
0x50 - - - - - - - - - - - - - - - -
0x60 - - - - - - - - - - - - - - - -
0x70 - - L L L L L - - - - - - - - -
In this case there are a number of downstream devices on this port that
are below the muxes. If we then ask for the map of everything on a
given mux port that most of those are on we'd instead see:
# i2cadm port map pchsmbus0/0/0x73/1
Address map for pchsmbus0/0/0x73/1:
- = No Device L = Local Device
S = Shared v = Downstream
E = Error
ADDR 0x0 0x1 0x2 0x3 0x4 0x5 0x6 0x7 0x8 0x9 0xa 0xb 0xc 0xd 0xe 0xf
0x00 - - - - - - - - - - - - - - - -
0x10 - - - - - - - - - - - - - - - -
0x20 - - - - - - - - - - - - - - - -
0x30 - - - - - - - - - - - - - - - -
0x40 - - - - - - - - L L L L L L L L
0x50 - - - - - - - - - - - - - - - -
0x60 - - - - - - - - - - - - - - - -
0x70 - - - - - - - - - - - - - - - -
INTERFACE STABILITY
The command line interface of i2cadm is Evolving. The output of i2cadm
is Not-An-Interface and may change at any time.
SEE ALSO
ofmt(3OFMT)
illumos October 4, 2025 illumos