| GPIOADM(8) | Maintenance Commands and Procedures | GPIOADM(8) |
gpioadm — gpio and
dpio administration
gpioadm |
controller list
[-H] [-o
field[,...] [-p]]
[filter...] |
gpioadm |
gpio list
[-H] [-1]
[-o field[,...]
[-p]] [filter...] |
gpioadm |
gpio attr
get [-H]
[-o field[,...]
[-p]] controller/gpio
[filter...] |
gpioadm |
gpio attr
set controller/gpio
attr=value
[attr=value...] |
gpioadm |
dpio list
[-H] [-o
field[,...] [-p]]
[filter...] |
gpioadm |
dpio define
[-r] [-w]
[-K] controller/gpio
name |
gpioadm |
dpio undefine
controller/gpio |
The gpioadm utility is used to enumerate
and manipulate the general purpose and dedicated purpose I/Os (GPIO and
DPIO) and their controllers that are present in the system. For more
background on the GPIO and DPIO subsystem, please see
gpio(7).
There are three top-level objects in
gpioadm:
gpioadm operations allow a GPIO to be
named either by its human-readable name or its controller-specific ID.
gpioadm will always attempt to resolve a string as
a GPIO's name first and will only attempt to parse it as a GPIO's ID if
there is no GPIO with that name.
GPIOs themselves contain a series of attributes which vary based on the controller. An attribute itself may be read-only or read-write and controls one aspect of the GPIO. For example, there are attributes for things such as the name of the device, which pin it corresponds to on the package, what the current input and output values are, whether there are pull-up or pull-down resistors enabled, and much more.
GPIOs support the discovery and manipulation
of their attributes through the attr
get and attr
set subcommands. Manipulating attributes can
potentially
damage your system. Documentation of specific attributes, may
potentially be found in provider-specific driver manual pages in section
4D.
gpioadm provides the ability to list and get basic
information about these controllers. Controllers are not manipulated
directly but are indirectly used when getting information about and
manipulating GPIOs and DPIOs.Specifically, gpioadm supports the
creation of DPIOs from a GPIO using the dpio
define subcommand and release a GPIO from being
a DPIO through the dpio
undefine subcommand.
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 GPIOs, DPIOs, and controllers currently
requires that a process have the {PRIV_SYS_DEVICES}
privilege.
Currently there is no persistence across reboots of any changes that are made to GPIO attributes. Similarly, any DPIOs that are created and manipulated only last until the next reboot of the system.
The following commands are supported by
gpioadm:
gpioadm 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.
gpioadm gpio
list [-H]
[-1] [-o
field[,...] [-p]]
[filter...]The following fields are supported:
The following options are supported:
-1-H-o
field[,...]-p-o option is required to
specifically control which fields are included.Like with other filters, this does not control the order
that matches are printed in and gpioadm will
error if not all filters are used. The filters can be combined with
the -1 option to guarantee that only a
single GPIO is matched.
gpioadm gpio
attr get
[-H] [-o
field[,...] [-p]]
controller/gpio [filter...]gpio attr
get subcommand is used to display all of the
attributes of a single GPIO that is specified by
controller/gpio. The
controller part of that is the name of the
controller. The gpio part is either the name or ID
of the GPIO.
For each of a single GPIO's attributes, the name of the attribute, its current value, what permissions exist for its value, and then what values are possible to st for it are displayed. Filters can be used to limit which attributes are displayed.
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.gpioadm gpio
attr set
controller/gpio attr=value
[attr=value...]gpio attr
set subcommand is used to set one or more
attributes of the GPIO that is named by
controller/gpio. The
controller part of that is the name of the
controller. The gpio part is either the name or ID
of the GPIO.
All attributes that are specified are given to the hardware to apply at once which generally means that either all of them should be applied or none of them will be. This allows a change from one atomic state to another without worrying about how to construct an attribute by attribute path from one state to the next, which may not be safe.
Attributes and values are separated with the equals character
(“=”). attr should be the full name
of an attribute. value is the value to set.
gpioadm will automatically convert the
human-readable strings that describe values into the appropriate
underlying provider-specific form. To see which values are valid, look
at the POSSIBLE column when getting the
attributes.
gpioadm dpio
list [-H]
[-o field[,...]
[-p]] [filter...]dpio list subcommand
lists all the DPIOs that have been created from GPIOs in the system.
The following fields are supported:
POLLIN event with
functions such as poll(2),
port_create(3C), and
others. In addition, the timestamp of when the last change was
detected can be retrieved via a device-specific
ioctl(2). This capability
will not show up if the read capability is not present. See
dpio(7) for more
information.Users of this field should not assume that the number of flags is fixed. When additional flag are added, they will be appended to the current set, ensuring that the order does not change. The appearance of additional characters in the string is what allows callers to know that a new flag is present and gives software and humans the ability to distinguish changes.
controller
list subcommand.gpioadm dpio
define [-r]
[-w] [-K]
controller/gpio namedpio define subcommand
creates a new DPIO named name from the specified
GPIO controller/gpio. A DPIO's name may be up to 31
characters. The first character must be alphanumeric, after which,
hyphens, underscores, periods, and plus signs are also allowed
(‘-’, ‘_’, ‘.’,
‘+’). Once created, a new character device will be present
at /dev/dpio/<name> and the GPIOs attributes
will be frozen other than those that are allowed for the DPIO to operate.
After that point, the gpio
attr set command will
always fail until the DPIO is removed.
The following options are supported, which modify the behavior of what the DPIO is allowed to do:
-K-r-wWhile it may seem weird, it is allowed to create a DPIO and
not specify either of -r or
-w. Such a DPIO will simply remain in its fixed
state. For example, if its attributes have it set up to drive a
particular output value (or none at all for an open-drain based pin)
then that will remain constant throughout the life of the DPIO.
gpioadm dpio
undefine controller/gpiodpio undefine
subcommand releases the corresponding DPIO that was named by its GPIO
controller and specific GPIO. If the DPIO is currently in use, this will
fail. Once successfully completed, the /dev entry
/dev/dpio/<name> will be removed and the
GPIOs attributes will be unfrozen, allowing them to be manipulated again
with the gpio attr
set subcommand.The gpioadm 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 gpioadm exits 2.
When listing controllers, GPIOs, DPIOs, or attributes, if none are
listed or if a filter is specified but is not matched, then these conditions
are all treated as errors and gpioadm exits 1.
Example 1 Discovering Controllers
This example shows how you discover what controllers exist.
# gpioadm controller list CONTROLLER NGPIOS NDPIOS PROVIDER gpio_sim0 6 0 /pseudo/gpio_sim@0 gpio_sim1 6 0 /pseudo/gpio_sim@1 gpio_sim2 6 0 /pseudo/gpio_sim@2
The controller information can be changed by changing the fields or adding a filter. For example:
# gpioadm controller list -o controller,ngpios,path gpio_sim2 CONTROLLER NGPIOS PATH gpio_sim2 6 /pseudo/kgpio@0:gpio_sim2
Example 2 Listing GPIOs avialable on the system.
This example allows you to discover which GPIOs exist on the system and which controllers that they belong to. First this shows listing all the GPIOs and then limiting the request to GPIOs on a specific controller.
# gpioadm gpio list CONTROLLER GPIO ID gpio_sim0 1v8 0 gpio_sim0 3v3 1 gpio_sim0 12V 2 gpio_sim0 54V 3 gpio_sim0 periodic-500ms 4 gpio_sim0 open-drain 5 gpio_sim1 1v8 0 gpio_sim1 3v3 1 gpio_sim1 12V 2 gpio_sim1 54V 3 gpio_sim1 periodic-500ms 4 gpio_sim1 open-drain 5 gpio_sim2 1v8 0 gpio_sim2 3v3 1 gpio_sim2 12V 2 gpio_sim2 54V 3 gpio_sim2 periodic-500ms 4 gpio_sim2 open-drain 5
Next, to limit them, additional arguments may be passed as filters. This will specify everything on the controller gpio_sim1 and a specific GPIO on gpio_sim2. A reminder that the filters are based on names.
# gpioadm gpio list gpio_sim1 gpio_sim2/periodic-500ms CONTROLLER GPIO ID gpio_sim1 1v8 0 gpio_sim1 3v3 1 gpio_sim1 12V 2 gpio_sim1 54V 3 gpio_sim1 periodic-500ms 4 gpio_sim1 open-drain 5 gpio_sim2 periodic-500ms 4
Example 3 Looking up a single GPIO by name and getting its attributes.
These two commands could also be chained together through the use of a subshell.
# gpioadm gpio list -1 -p -o id gpio_sim1/3v3
1
# gpioadm gpio attr get gpio_sim1/1
ATTR PERM VALUE POSSIBLE
name r- 3v3 --
sim:output rw disabled disabled,low,high
sim:input r- low low,high
sim:pull rw down
disabled,down,up,up|down
sim:voltage r- 3.3V 3.3V
sim:speed rw low low,medium,high,
very-high
Example 4 Setting GPIO attributes
Multiple GPIO attributes can be set at the same time. They all will take effect at the same time. This example shows setting and then getting those same properties:
# gpioadm gpio attr set gpio_sim1/1 sim:pull=up sim:speed=high
# gpioadm gpio attr get gpio_sim1/1 sim:pull sim:speed
ATTR PERM VALUE POSSIBLE
sim:pull rw up
disabled,down,up,up|down
sim:speed rw high low,medium,high,
very-high
Example 5 Creating a DPIO
This example shows the creation of a DPIO from a GPIO.
# gpioadm dpio define -r -w gpio_sim2/2 example5 # $ ls /dev/dpio/example5 /dev/dpio/example5 # gpioadm dpio list DPIO CAPS FLAGS CONTROLLER GPIONUM example5 read,write - gpio_sim2 2
Example 6 Removing a DPIO
This example removes the DPIO that we created in the prior example. If the system has other DPIOs than the output of the final command will be different.
# gpioadm dpio undefine gpio_sim2/2 # ls /dev/dpio/example5 /dev/dpio/example5: No such file or directory # gpioadm dpio list gpioadm: no DPIOs found
The command line interface of gpioadm is
Evolving.
The output of gpioadm is
Not-An-Interface
and may change at any time.
poll(2), read(2), write(2), port_get(3) C ofmt(3OFMT), dpio(7), gpio(7), ldi_open_by_name(9F)
| September 17, 2022 | OmniOS |