| 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;
i2cadm provides the
ability to list them as well as get and set properties on specific
controllers.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.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.
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:
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:
0x72’.pca9548@0x72’.pca9454x0’.The following commands are supported by
i2cadm:
i2cadm controller
list [-H]
[-o field[,...]
[-p]] [filter...]The following fields are supported:
The following options are supported:
-H-o
field[,...]-p-o option is required to
specifically control which fields are included.The following operands are supported:
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...]The following fields are supported:
The following options are supported:
-H-o
field[,...]-p-o option is required to
specifically control which fields are included.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=valueTo 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...]i2cadm device
add command.
The following fields are supported:
The following options are supported:
-H-o
field[,...]-p-o option is required to
specifically control which fields are included.The following operands are supported:
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...]The following fields are supported:
i2cadm
device add.The following options are supported:
-H-o
field[,...]-p-o option is required to
specifically control which fields are included.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 addressThe following options are supported:
-c
compatcompatible’ 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:
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 (‘_’).
i2cadm device
remove pathi2cadm mux
list [-H]
[-o field[,...]
[-p]] [filter...]The following fields are supported:
The following options are supported:
-H-o
field[,...]-p-o option is required to
specifically control which fields are included.The following operands are supported:
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...]The following fields are supported:
The following options are supported:
-H-o
field[,...]-p-o option is required to
specifically control which fields are included.The following operands are supported:
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]] porti2cadm
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:
The following fields are supported:
The following options are supported:
-H-o
field[,...]-p-o option is required to
specifically control which fields are included.The following operands are required:
i2cadm io
[-m mode]
-d destination
[-a address]
[-c command]
[-w wlen]
[-r rlen]
[-o output]
data-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-c
command-m that requires a command to
be specified.-d
destination-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-r and -w must be
used and non-zero.-c.-c.-c.-c.-c. A read length must
be specified with -r. It will not be sent
on the wire, unlike a traditional SMBus block read.-c and a single data
operand must be specified.-c and a single data
operand must be specified.-c and a single data
operand must be specified.-c and a single data
operand must be specified.-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.-c and a single
positional data argument must be specified. Process call transmits
and then reads a u16.-o
output-r
rlen-w
wleni2cadm scan
[-d device]
[-H] [-o
field[,...] [-p]]
port-p and
-o options.
The table will use the following characters to indicate specific cases:
-d option was used and the address in question
wasn't listed.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:
-d
device-H-o
field[,...]-p-o option is required to
specifically control which fields are included.The following operands are required:
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:
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.
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.
| October 4, 2025 | OmniOS |