GPIO Character Device Userspace API¶
This is latest version (v2) of the character device API, as defined in
include/uapi/linux/gpio.h.
First added in 5.10.
Note
Do NOT abuse userspace APIs to control hardware that has proper kernel drivers. There may already be a driver for your use case, and an existing kernel driver is sure to provide a superior solution to bitbashing from userspace.
Read Subsystem drivers using GPIO to avoid reinventing kernel wheels in userspace.
Similarly, for multi-function lines there may be other subsystems, such as Serial Peripheral Interface (SPI), I2C/SMBus Subsystem, Pulse Width Modulation (PWM) interface, 1-Wire Subsystem etc, that provide suitable drivers and APIs for your hardware.
Basic examples using the character device API can be found in tools/gpio/*.
The API is based around two major objects, the Chip and the Line Request.
Chip¶
The Chip represents a single GPIO chip and is exposed to userspace using device
files of the form /dev/gpiochipX.
Each chip supports a number of GPIO lines,
chip.lines. Lines on the chip are identified by an
offset in the range from 0 to chip.lines - 1, i.e. [0,chip.lines).
Lines are requested from the chip using GPIO_V2_GET_LINE_IOCTL and the resulting line request is used to access the GPIO chip’s lines or monitor the lines for edge events.
Within this documentation, the file descriptor returned by calling open()
on the GPIO device file is referred to as chip_fd.
Operations¶
The following operations may be performed on the chip:
Line Request¶
Line requests are created by GPIO_V2_GET_LINE_IOCTL and provide
access to a set of requested lines. The line request is exposed to userspace
via the anonymous file descriptor returned in
request.fd by GPIO_V2_GET_LINE_IOCTL.
Within this documentation, the line request file descriptor is referred to
as req_fd.
Operations¶
The following operations may be performed on the line request:
Types¶
This section contains the structs and enums that are referenced by the API v2,
as defined in include/uapi/linux/gpio.h.
-
struct gpiochip_info¶
Information about a certain GPIO chip
Definition:
struct gpiochip_info {
char name[GPIO_MAX_NAME_SIZE];
char label[GPIO_MAX_NAME_SIZE];
__u32 lines;
};
Members
namethe Linux kernel name of this GPIO chip
labela functional name for this GPIO chip, such as a product number, may be empty (i.e. label[0] == ‘0’)
linesnumber of GPIO lines on this chip
-
enum gpio_v2_line_flag¶
struct gpio_v2_line_attribute.flags values
Constants
GPIO_V2_LINE_FLAG_USEDline is not available for request
GPIO_V2_LINE_FLAG_ACTIVE_LOWline active state is physical low
GPIO_V2_LINE_FLAG_INPUTline is an input
GPIO_V2_LINE_FLAG_OUTPUTline is an output
GPIO_V2_LINE_FLAG_EDGE_RISINGline detects rising (inactive to active) edges
GPIO_V2_LINE_FLAG_EDGE_FALLINGline detects falling (active to inactive) edges
GPIO_V2_LINE_FLAG_OPEN_DRAINline is an open drain output
GPIO_V2_LINE_FLAG_OPEN_SOURCEline is an open source output
GPIO_V2_LINE_FLAG_BIAS_PULL_UPline has pull-up bias enabled
GPIO_V2_LINE_FLAG_BIAS_PULL_DOWNline has pull-down bias enabled
GPIO_V2_LINE_FLAG_BIAS_DISABLEDline has bias disabled
GPIO_V2_LINE_FLAG_EVENT_CLOCK_REALTIMEline events contain REALTIME timestamps
GPIO_V2_LINE_FLAG_EVENT_CLOCK_HTEline events contain timestamps from the hardware timestamping engine (HTE) subsystem
-
struct gpio_v2_line_values¶
Values of GPIO lines
Definition:
struct gpio_v2_line_values {
__aligned_u64 bits;
__aligned_u64 mask;
};
Members
bitsa bitmap containing the value of the lines, set to 1 for active and 0 for inactive
maska bitmap identifying the lines to get or set, with each bit number corresponding to the index into
struct gpio_v2_line_request.offsets
-
enum gpio_v2_line_attr_id¶
struct gpio_v2_line_attribute.id values identifying which field of the attribute union is in use.
Constants
GPIO_V2_LINE_ATTR_ID_FLAGSflags field is in use
GPIO_V2_LINE_ATTR_ID_OUTPUT_VALUESvalues field is in use
GPIO_V2_LINE_ATTR_ID_DEBOUNCEdebounce_period_us field is in use
-
struct gpio_v2_line_attribute¶
a configurable attribute of a line
Definition:
struct gpio_v2_line_attribute {
__u32 id;
__u32 padding;
union {
__aligned_u64 flags;
__aligned_u64 values;
__u32 debounce_period_us;
};
};
Members
idattribute identifier with value from
enum gpio_v2_line_attr_idpaddingreserved for future use and must be zero filled
{unnamed_union}anonymous
flagsif id is
GPIO_V2_LINE_ATTR_ID_FLAGS, the flags for the GPIO line, with values fromenum gpio_v2_line_flag, such asGPIO_V2_LINE_FLAG_ACTIVE_LOW,GPIO_V2_LINE_FLAG_OUTPUTetc, added together. This overrides the default flags contained in thestruct gpio_v2_line_configfor the associated line.valuesif id is
GPIO_V2_LINE_ATTR_ID_OUTPUT_VALUES, a bitmap containing the values to which the lines will be set, with each bit number corresponding to the index intostruct gpio_v2_line_request.offsetsdebounce_period_usif id is
GPIO_V2_LINE_ATTR_ID_DEBOUNCE, the desired debounce period, in microseconds
-
struct gpio_v2_line_config_attribute¶
a configuration attribute associated with one or more of the requested lines.
Definition:
struct gpio_v2_line_config_attribute {
struct gpio_v2_line_attribute attr;
__aligned_u64 mask;
};
Members
attrthe configurable attribute
maska bitmap identifying the lines to which the attribute applies, with each bit number corresponding to the index into
struct gpio_v2_line_request.offsets
-
struct gpio_v2_line_config¶
Configuration for GPIO lines
Definition:
struct gpio_v2_line_config {
__aligned_u64 flags;
__u32 num_attrs;
__u32 padding[5];
struct gpio_v2_line_config_attribute attrs[GPIO_V2_LINE_NUM_ATTRS_MAX];
};
Members
flagsflags for the GPIO lines, with values from
enum gpio_v2_line_flag, such asGPIO_V2_LINE_FLAG_ACTIVE_LOW,GPIO_V2_LINE_FLAG_OUTPUTetc, added together. This is the default for all requested lines but may be overridden for particular lines using attrs.num_attrsthe number of attributes in attrs
paddingreserved for future use and must be zero filled
attrsthe configuration attributes associated with the requested lines. Any attribute should only be associated with a particular line once. If an attribute is associated with a line multiple times then the first occurrence (i.e. lowest index) has precedence.
-
struct gpio_v2_line_request¶
Information about a request for GPIO lines
Definition:
struct gpio_v2_line_request {
__u32 offsets[GPIO_V2_LINES_MAX];
char consumer[GPIO_MAX_NAME_SIZE];
struct gpio_v2_line_config config;
__u32 num_lines;
__u32 event_buffer_size;
__u32 padding[5];
__s32 fd;
};
Members
offsetsan array of desired lines, specified by offset index for the associated GPIO chip
consumera desired consumer label for the selected GPIO lines such as “my-bitbanged-relay”
configrequested configuration for the lines
num_linesnumber of lines requested in this request, i.e. the number of valid fields in the
GPIO_V2_LINES_MAXsized arrays, set to 1 to request a single lineevent_buffer_sizea suggested minimum number of line events that the kernel should buffer. This is only relevant if edge detection is enabled in the configuration. Note that this is only a suggested value and the kernel may allocate a larger buffer or cap the size of the buffer. If this field is zero then the buffer size defaults to a minimum of num_lines * 16.
paddingreserved for future use and must be zero filled
fdafter a successful
GPIO_V2_GET_LINE_IOCTLoperation, contains a valid anonymous file descriptor representing the request
-
struct gpio_v2_line_info¶
Information about a certain GPIO line
Definition:
struct gpio_v2_line_info {
char name[GPIO_MAX_NAME_SIZE];
char consumer[GPIO_MAX_NAME_SIZE];
__u32 offset;
__u32 num_attrs;
__aligned_u64 flags;
struct gpio_v2_line_attribute attrs[GPIO_V2_LINE_NUM_ATTRS_MAX];
__u32 padding[4];
};
Members
namethe name of this GPIO line, such as the output pin of the line on the chip, a rail or a pin header name on a board, as specified by the GPIO chip, may be empty (i.e. name[0] == ‘0’)
consumera functional name for the consumer of this GPIO line as set by whatever is using it, will be empty if there is no current user but may also be empty if the consumer doesn’t set this up
offsetthe local offset on this GPIO chip, fill this in when requesting the line information from the kernel
num_attrsthe number of attributes in attrs
flagsflags for this GPIO line, with values from
enum gpio_v2_line_flag, such asGPIO_V2_LINE_FLAG_ACTIVE_LOW,GPIO_V2_LINE_FLAG_OUTPUTetc, added togetherattrsthe configuration attributes associated with the line
paddingreserved for future use
-
enum gpio_v2_line_changed_type¶
struct gpio_v2_line_changed.event_type values
Constants
GPIO_V2_LINE_CHANGED_REQUESTEDline has been requested
GPIO_V2_LINE_CHANGED_RELEASEDline has been released
GPIO_V2_LINE_CHANGED_CONFIGline has been reconfigured
-
struct gpio_v2_line_info_changed¶
Information about a change in status of a GPIO line
Definition:
struct gpio_v2_line_info_changed {
struct gpio_v2_line_info info;
__aligned_u64 timestamp_ns;
__u32 event_type;
__u32 padding[5];
};
Members
infoupdated line information
timestamp_nsestimate of time of status change occurrence, in nanoseconds
event_typethe type of change with a value from
enum gpio_v2_line_changed_typepaddingreserved for future use
-
enum gpio_v2_line_event_id¶
struct gpio_v2_line_event.id values
Constants
GPIO_V2_LINE_EVENT_RISING_EDGEevent triggered by a rising edge
GPIO_V2_LINE_EVENT_FALLING_EDGEevent triggered by a falling edge
-
struct gpio_v2_line_event¶
The actual event being pushed to userspace
Definition:
struct gpio_v2_line_event {
__aligned_u64 timestamp_ns;
__u32 id;
__u32 offset;
__u32 seqno;
__u32 line_seqno;
__u32 padding[6];
};
Members
timestamp_nsbest estimate of time of event occurrence, in nanoseconds
idevent identifier with value from
enum gpio_v2_line_event_idoffsetthe offset of the line that triggered the event
seqnothe sequence number for this event in the sequence of events for all the lines in this line request
line_seqnothe sequence number for this event in the sequence of events on this particular line
paddingreserved for future use
Description
By default the timestamp_ns is read from CLOCK_MONOTONIC and is
intended to allow the accurate measurement of the time between events.
It does not provide the wall-clock time.
If the GPIO_V2_LINE_FLAG_EVENT_CLOCK_REALTIME flag is set then the
timestamp_ns is read from CLOCK_REALTIME.
If the GPIO_V2_LINE_FLAG_EVENT_CLOCK_HTE flag is set then the
timestamp_ns is provided by the hardware timestamping engine (HTE)
subsystem.