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:
GPIOs General Purpose I/Os are software controllable pins that exist
on various hardware devices. GPIOs are identified by a human-
readable name and a controller-specific numeric ID (which has
no relation to the hardware or datasheet's numbering of GPIOs,
these are used by the kernel to identify GPIOs). All 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.
Controllers
These are hardware devices that provide access to GPIOs.
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.
DPIOs Dedicated Purpose I/Os are devices which wrap up and constrain
a GPIO while allowing one to indicate that there are particular
semantics. Unlike a GPIO which has a full series of
attributes, a DPIO provides generic access to reading the
current input value and setting the output value, while
freezing all other attributes of the underlying GPIO. For more
background on DPIOs, how they work, and why the exist, please
see dpio(7).
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...]
List all of the GPIO controllers in the system and basic information
about them.
The following fields are supported:
CONTROLLER This is the name of the GPIO controller in the system.
NGPIOS The number of GPIOs that the controller supports. This
value will not change unless the controller driver
changes somehow.
NDPIOS The number of DPIOs that the controller currently
actively has. This value will change over time depending
on the creation and removal of DPIOs.
PROVIDER The /devices path to the kernel provider for this GPIO
controller.
PATH The /devices path to the GPIO controller minor node.
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 that are used to
constrain the list of GPIO controllers that are
printed. Each filter is the name of a GPIO controller
that matches the aforementioned CONTROLLER field.
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...]
List all of the GPIOs in the system across all controllers.
The following fields are supported:
CONTROLLER This is the name of the GPIO controller in the system.
GPIO This is the name of the GPIO provided by its controller.
GPIO names are not unique in the system and are scoped to
their controller.
ID The numeric ID of the GPIO. This is used as part of
getting and setting attributes as well as when defining
and undefining DPIOs.
The following options are supported:
-1 Exit non-zero if the list operation outputs more than one
item. This is generally used in conjunction with a
specific filter that would include both a controller and
a GPIO name.
-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 that are used to constrain the list
of GPIOs that are printed. Each filter may combine a
GPIO controller and a GPIO name. There are three
general forms:
controller This filter matches all GPIOs that are
present under the controller named by
controller.
*/gpio This filter matches all controllers, but
only prints GPIOs with the specified name
gpio.
controller/gpio
This is the intersection of the prior two
filters. This filter will only print if
both a GPIO's controller and its name
match the specified values.
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...]
The 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:
ATTR This is the name of the attribute. It is split into a
provider name and then a specific attribute name as all
attributes are generally scoped to their provider.
PERM This indicates the current permissions for manipulating
this attribute. This is treated as a two character field
with `r' standing for reading the value and `w' standing
for writing the value.
VALUE This is the current value of the attribute. It will
generally be rendered as a human-readable string when
appropriate so that way the value can be understood and
does not require understanding the underlying provider's
specific values.
POSSIBLE A list of all possible values that are supported for this
field. This allows one to know what they can possibly set
for this attribute. For some read-only attributes this
field may not have a value.
RAW This provides the underlying provider's value for this
attribute. For string based attributes, this is the same
as the VALUE field. For other attributes, such as those
which are uint32 values under the hood, these are the
hexadecimal form of the integer.
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 that are used to
constrain the list of GPIO attributes that are printed.
Each filter is the name of a GPIO attributes that
matches the aforementioned ATTR field.
gpioadm gpio attr set controller/gpio attr=value [attr=value...]
The 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...]
The dpio list subcommand lists all the DPIOs that have been created
from GPIOs in the system.
The following fields are supported:
DPIO This is the name of a DPIO. DPIO names are unique in the
system and a DPIO can be found in the filesystem at
/dev/dpio/<name>.
CAPS This is a list of capabilities that a DPIO supports,
which is a combination of what the underlying provider
supports and what a user requested when creating the
DPIO. The following are the current capabilities, though
this list may expand in the future:
read Indicates that the DPIO supports the various
read(2) family of functions. Reading a DPIO
returns the current value the DPIO sees on its pin
in the form of a 4 byte dpio_input_t. See dpio(7)
for more information.
write Indicates that the DPIO supports the various
write(2) family of functions. Writing a DPIO
changes the value that it is outputting on its
pin. Writes must always be a 4 byte dpio_output_t
value. See dpio(7) for more information.
poll This indicates that the DPIO can be polled for
changes to its input value via the 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.
FLAGS This is a series of different flags that describe
different aspects of the DPIOs behavior. The flags are
organized and printed a series of letters where a `-'
character denotes that a flag is not set and a letter
indicates that a flag is set. The currently defined
flags are:
K Indicates that the DPIO may only be used by the kernel
in a layered fashion (e.g. it must be opened by
ldi_open_by_name(9F) or a similar LDI call).
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 This is the name of the GPIO controller that the DPIO is
leveraging. When combined with the GPIONUM field, this
uniquely identifies the GPIO that powers the DPIO. This
name is the same as would show up in the controller list
subcommand.
GPIONUM This is the ID of the GPIO on the specified controller
that the DPIO has wrapped up and constrained.
gpioadm dpio define [-r] [-w] [-K] controller/gpio name
The dpio 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 The DPIO will be constrained such that only the kernel
can open it. See the description of the "K" flag above.
-r This allows the DPIO to be read and return the current
logical value that the pin sees. See the description of
the read capability above for more information.
-w This allows the DPIO's logical output value to be set or
disabled. See the description of the write capability
above for more information.
While 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/gpio
The dpio 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)
illumos September 17, 2022 illumos
NAME
gpioadm - gpio and dpio administration
SYNOPSIS
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
DESCRIPTION
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:
GPIOs General Purpose I/Os are software controllable pins that exist
on various hardware devices. GPIOs are identified by a human-
readable name and a controller-specific numeric ID (which has
no relation to the hardware or datasheet's numbering of GPIOs,
these are used by the kernel to identify GPIOs). All 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.
Controllers
These are hardware devices that provide access to GPIOs.
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.
DPIOs Dedicated Purpose I/Os are devices which wrap up and constrain
a GPIO while allowing one to indicate that there are particular
semantics. Unlike a GPIO which has a full series of
attributes, a DPIO provides generic access to reading the
current input value and setting the output value, while
freezing all other attributes of the underlying GPIO. For more
background on DPIOs, how they work, and why the exist, please
see dpio(7).
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.
Persistence
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.
SUBCOMMANDS
The following commands are supported by gpioadm:
gpioadm controller list [-H] [-o field[,...] [-p]] [filter...]
List all of the GPIO controllers in the system and basic information
about them.
The following fields are supported:
CONTROLLER This is the name of the GPIO controller in the system.
NGPIOS The number of GPIOs that the controller supports. This
value will not change unless the controller driver
changes somehow.
NDPIOS The number of DPIOs that the controller currently
actively has. This value will change over time depending
on the creation and removal of DPIOs.
PROVIDER The /devices path to the kernel provider for this GPIO
controller.
PATH The /devices path to the GPIO controller minor node.
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 that are used to
constrain the list of GPIO controllers that are
printed. Each filter is the name of a GPIO controller
that matches the aforementioned CONTROLLER field.
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...]
List all of the GPIOs in the system across all controllers.
The following fields are supported:
CONTROLLER This is the name of the GPIO controller in the system.
GPIO This is the name of the GPIO provided by its controller.
GPIO names are not unique in the system and are scoped to
their controller.
ID The numeric ID of the GPIO. This is used as part of
getting and setting attributes as well as when defining
and undefining DPIOs.
The following options are supported:
-1 Exit non-zero if the list operation outputs more than one
item. This is generally used in conjunction with a
specific filter that would include both a controller and
a GPIO name.
-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 that are used to constrain the list
of GPIOs that are printed. Each filter may combine a
GPIO controller and a GPIO name. There are three
general forms:
controller This filter matches all GPIOs that are
present under the controller named by
controller.
*/gpio This filter matches all controllers, but
only prints GPIOs with the specified name
gpio.
controller/gpio
This is the intersection of the prior two
filters. This filter will only print if
both a GPIO's controller and its name
match the specified values.
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...]
The 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:
ATTR This is the name of the attribute. It is split into a
provider name and then a specific attribute name as all
attributes are generally scoped to their provider.
PERM This indicates the current permissions for manipulating
this attribute. This is treated as a two character field
with `r' standing for reading the value and `w' standing
for writing the value.
VALUE This is the current value of the attribute. It will
generally be rendered as a human-readable string when
appropriate so that way the value can be understood and
does not require understanding the underlying provider's
specific values.
POSSIBLE A list of all possible values that are supported for this
field. This allows one to know what they can possibly set
for this attribute. For some read-only attributes this
field may not have a value.
RAW This provides the underlying provider's value for this
attribute. For string based attributes, this is the same
as the VALUE field. For other attributes, such as those
which are uint32 values under the hood, these are the
hexadecimal form of the integer.
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 that are used to
constrain the list of GPIO attributes that are printed.
Each filter is the name of a GPIO attributes that
matches the aforementioned ATTR field.
gpioadm gpio attr set controller/gpio attr=value [attr=value...]
The 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...]
The dpio list subcommand lists all the DPIOs that have been created
from GPIOs in the system.
The following fields are supported:
DPIO This is the name of a DPIO. DPIO names are unique in the
system and a DPIO can be found in the filesystem at
/dev/dpio/<name>.
CAPS This is a list of capabilities that a DPIO supports,
which is a combination of what the underlying provider
supports and what a user requested when creating the
DPIO. The following are the current capabilities, though
this list may expand in the future:
read Indicates that the DPIO supports the various
read(2) family of functions. Reading a DPIO
returns the current value the DPIO sees on its pin
in the form of a 4 byte dpio_input_t. See dpio(7)
for more information.
write Indicates that the DPIO supports the various
write(2) family of functions. Writing a DPIO
changes the value that it is outputting on its
pin. Writes must always be a 4 byte dpio_output_t
value. See dpio(7) for more information.
poll This indicates that the DPIO can be polled for
changes to its input value via the 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.
FLAGS This is a series of different flags that describe
different aspects of the DPIOs behavior. The flags are
organized and printed a series of letters where a `-'
character denotes that a flag is not set and a letter
indicates that a flag is set. The currently defined
flags are:
K Indicates that the DPIO may only be used by the kernel
in a layered fashion (e.g. it must be opened by
ldi_open_by_name(9F) or a similar LDI call).
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 This is the name of the GPIO controller that the DPIO is
leveraging. When combined with the GPIONUM field, this
uniquely identifies the GPIO that powers the DPIO. This
name is the same as would show up in the controller list
subcommand.
GPIONUM This is the ID of the GPIO on the specified controller
that the DPIO has wrapped up and constrained.
gpioadm dpio define [-r] [-w] [-K] controller/gpio name
The dpio 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 The DPIO will be constrained such that only the kernel
can open it. See the description of the "K" flag above.
-r This allows the DPIO to be read and return the current
logical value that the pin sees. See the description of
the read capability above for more information.
-w This allows the DPIO's logical output value to be set or
disabled. See the description of the write capability
above for more information.
While 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/gpio
The dpio 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.
EXIT STATUS
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.
EXAMPLES
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
INTERFACE STABILITY
The command line interface of gpioadm is Evolving. The output of
gpioadm is Not-An-Interface and may change at any time.
SEE ALSO
poll(2), read(2), write(2), port_get(3) C ofmt(3OFMT), dpio(7),
gpio(7), ldi_open_by_name(9F)
illumos September 17, 2022 illumos