2021-02-04 12:43:57 +00:00
|
|
|
/* SPDX-License-Identifier: GPL-2.0-only WITH Linux-syscall-note */
|
gpio: add a userspace chardev ABI for GPIOs
A new chardev that is to be used for userspace GPIO access is
added in this patch. It is intended to gradually replace the
horribly broken sysfs ABI.
Using a chardev has many upsides:
- All operations are per-gpiochip, which is the actual
device underlying the GPIOs, making us tie in to the
kernel device model properly.
- Hotpluggable GPIO controllers can come and go, as this
kind of problem has been know to userspace for character
devices since ages, and if a gpiochip handle is held in
userspace we know we will break something, whereas the
sysfs is stateless.
- The one-value-per-file rule of sysfs is really hard to
maintain when you want to twist more than one knob at a time,
for example have in-kernel APIs to switch several GPIO
lines at the same time, and this will be possible to do
with a single ioctl() from userspace, saving a lot of
context switching.
We also need to add a new bus type for GPIO. This is
necessary for example for userspace coldplug, where sysfs is
traversed to find the boot-time device nodes and create the
character devices in /dev.
This new chardev ABI is *non* *optional* and can be counted
on to be present in the future, emphasizing the preference
of this ABI.
The ABI only implements one single ioctl() to get the name
and number of GPIO lines of a chip. Even this is debatable:
see it as a minimal example for review. This ABI shall be
ruthlessly reviewed and etched in stone.
The old /sys/class/gpio is still optional to compile in,
but will be deprecated.
Unique device IDs are created using IDR, which is overkill
and insanely scalable, but also well tested.
Cc: Johan Hovold <johan@kernel.org>
Cc: Michael Welling <mwelling@ieee.org>
Cc: Markus Pargmann <mpa@pengutronix.de>
Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Cc: Arnd Bergmann <arnd@arndb.de>
Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
2015-10-21 13:29:53 +00:00
|
|
|
/*
|
|
|
|
* <linux/gpio.h> - userspace ABI for the GPIO character devices
|
|
|
|
*
|
gpio: userspace ABI for reading/writing GPIO lines
This adds a userspace ABI for reading and writing GPIO lines.
The mechanism returns an anonymous file handle to a request
to read/write n offsets from a gpiochip. This file handle
in turn accepts two ioctl()s: one that reads and one that
writes values to the selected lines.
- Handles can be requested as input/output, active low,
open drain, open source, however when you issue a request
for n lines with GPIO_GET_LINEHANDLE_IOCTL, they must all
have the same flags, i.e. all inputs or all outputs, all
open drain etc. If a granular control of the flags for
each line is desired, they need to be requested
individually, not in a batch.
- The GPIOHANDLE_GET_LINE_VALUES_IOCTL read ioctl() can be
issued also to output lines to verify that the hardware
is in the expected state.
- It reads and writes up to GPIOHANDLES_MAX lines at once,
utilizing the .set_multiple() call in the driver if
possible, making the call efficient if several lines
can be written with a single register update.
The limitation of GPIOHANDLES_MAX to 64 lines is done under
the assumption that we may expect hardware that can issue a
transaction updating 64 bits at an instant but unlikely
anything larger than that.
ChangeLog v2->v3:
- Use gpiod_get_value_cansleep() so we support also slowpath
GPIO drivers.
- Fix up the UAPI docs kerneldoc.
- Allocate the anonymous fd last, so that the release
function don't get called until that point of something
fails. After this point, skip the errorpath.
ChangeLog v1->v2:
- Handle ioctl_compat() properly based on a similar patch
to the other ioctl() handling code.
- Use _IOWR() as we pass pointers both in and out of the
ioctl()
- Use kmalloc() and kfree() for the linehandled, do not
try to be fancy with devm_* it doesn't work the way I
thought.
- Fix const-correctness on the linehandle name field.
Acked-by: Michael Welling <mwelling@ieee.org>
Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
2016-04-26 08:35:29 +00:00
|
|
|
* Copyright (C) 2016 Linus Walleij
|
gpio: add a userspace chardev ABI for GPIOs
A new chardev that is to be used for userspace GPIO access is
added in this patch. It is intended to gradually replace the
horribly broken sysfs ABI.
Using a chardev has many upsides:
- All operations are per-gpiochip, which is the actual
device underlying the GPIOs, making us tie in to the
kernel device model properly.
- Hotpluggable GPIO controllers can come and go, as this
kind of problem has been know to userspace for character
devices since ages, and if a gpiochip handle is held in
userspace we know we will break something, whereas the
sysfs is stateless.
- The one-value-per-file rule of sysfs is really hard to
maintain when you want to twist more than one knob at a time,
for example have in-kernel APIs to switch several GPIO
lines at the same time, and this will be possible to do
with a single ioctl() from userspace, saving a lot of
context switching.
We also need to add a new bus type for GPIO. This is
necessary for example for userspace coldplug, where sysfs is
traversed to find the boot-time device nodes and create the
character devices in /dev.
This new chardev ABI is *non* *optional* and can be counted
on to be present in the future, emphasizing the preference
of this ABI.
The ABI only implements one single ioctl() to get the name
and number of GPIO lines of a chip. Even this is debatable:
see it as a minimal example for review. This ABI shall be
ruthlessly reviewed and etched in stone.
The old /sys/class/gpio is still optional to compile in,
but will be deprecated.
Unique device IDs are created using IDR, which is overkill
and insanely scalable, but also well tested.
Cc: Johan Hovold <johan@kernel.org>
Cc: Michael Welling <mwelling@ieee.org>
Cc: Markus Pargmann <mpa@pengutronix.de>
Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Cc: Arnd Bergmann <arnd@arndb.de>
Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
2015-10-21 13:29:53 +00:00
|
|
|
*
|
|
|
|
* This program is free software; you can redistribute it and/or modify it
|
|
|
|
* under the terms of the GNU General Public License version 2 as published by
|
|
|
|
* the Free Software Foundation.
|
|
|
|
*/
|
|
|
|
#ifndef _UAPI_GPIO_H_
|
|
|
|
#define _UAPI_GPIO_H_
|
|
|
|
|
gpio: uapi: define uAPI v2
Add a new version of the uAPI to address existing 32/64-bit alignment
issues, add support for debounce and event sequence numbers, allow
requested lines with different configurations, and provide some future
proofing by adding padding reserved for future use.
The alignment issue relates to the gpioevent_data, which packs to different
sizes on 32-bit and 64-bit platforms. That creates problems for 32-bit apps
running on 64-bit kernels. uAPI v2 addresses that particular issue, and
the problem more generally, by adding pad fields that explicitly pad
structs out to 64-bit boundaries, so they will pack to the same size now,
and even if some of the reserved padding is used for __u64 fields in the
future.
The new structs have been analysed with pahole to ensure that they
are sized as expected and contain no implicit padding.
The lack of future proofing in v1 makes it impossible to, for example,
add the debounce feature that is included in v2.
The future proofing is addressed by providing configurable attributes in
line config and reserved padding in all structs for future features.
Specifically, the line request, config, info, info_changed and event
structs receive updated versions and new ioctls.
As the majority of the structs and ioctls were being replaced, it is
opportune to rework some of the other aspects of the uAPI:
v1 has three different flags fields, each with their own separate
bit definitions. In v2 that is collapsed to one - gpio_v2_line_flag.
The handle and event requests are merged into a single request, the line
request, as the two requests were mostly the same other than the edge
detection provided by event requests. As a byproduct, the v2 uAPI allows
for multiple lines producing edge events on the same line handle.
This is a new capability as v1 only supports a single line in an event
request.
As a consequence, there are now only two types of file handle to be
concerned with, the chip and the line, and it is clearer which ioctls
apply to which type of handle.
There is also some minor renaming of fields for consistency compared to
their v1 counterparts, e.g. offset rather than lineoffset or line_offset,
and consumer rather than consumer_label.
Additionally, v1 GPIOHANDLES_MAX becomes GPIO_V2_LINES_MAX in v2 for
clarity, and the gpiohandle_data __u8 array becomes a bitmap in
gpio_v2_line_values.
The v2 uAPI is mostly a reorganisation and extension of v1, so userspace
code, particularly libgpiod, should readily port to it.
Signed-off-by: Kent Gibson <warthog618@gmail.com>
Reviewed-by: Andy Shevchenko <andy.shevchenko@gmail.com>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
2020-09-28 00:27:51 +00:00
|
|
|
#include <linux/const.h>
|
gpio: add a userspace chardev ABI for GPIOs
A new chardev that is to be used for userspace GPIO access is
added in this patch. It is intended to gradually replace the
horribly broken sysfs ABI.
Using a chardev has many upsides:
- All operations are per-gpiochip, which is the actual
device underlying the GPIOs, making us tie in to the
kernel device model properly.
- Hotpluggable GPIO controllers can come and go, as this
kind of problem has been know to userspace for character
devices since ages, and if a gpiochip handle is held in
userspace we know we will break something, whereas the
sysfs is stateless.
- The one-value-per-file rule of sysfs is really hard to
maintain when you want to twist more than one knob at a time,
for example have in-kernel APIs to switch several GPIO
lines at the same time, and this will be possible to do
with a single ioctl() from userspace, saving a lot of
context switching.
We also need to add a new bus type for GPIO. This is
necessary for example for userspace coldplug, where sysfs is
traversed to find the boot-time device nodes and create the
character devices in /dev.
This new chardev ABI is *non* *optional* and can be counted
on to be present in the future, emphasizing the preference
of this ABI.
The ABI only implements one single ioctl() to get the name
and number of GPIO lines of a chip. Even this is debatable:
see it as a minimal example for review. This ABI shall be
ruthlessly reviewed and etched in stone.
The old /sys/class/gpio is still optional to compile in,
but will be deprecated.
Unique device IDs are created using IDR, which is overkill
and insanely scalable, but also well tested.
Cc: Johan Hovold <johan@kernel.org>
Cc: Michael Welling <mwelling@ieee.org>
Cc: Markus Pargmann <mpa@pengutronix.de>
Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Cc: Arnd Bergmann <arnd@arndb.de>
Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
2015-10-21 13:29:53 +00:00
|
|
|
#include <linux/ioctl.h>
|
|
|
|
#include <linux/types.h>
|
|
|
|
|
2020-09-28 00:27:50 +00:00
|
|
|
/*
|
|
|
|
* The maximum size of name and label arrays.
|
gpio: uapi: define uAPI v2
Add a new version of the uAPI to address existing 32/64-bit alignment
issues, add support for debounce and event sequence numbers, allow
requested lines with different configurations, and provide some future
proofing by adding padding reserved for future use.
The alignment issue relates to the gpioevent_data, which packs to different
sizes on 32-bit and 64-bit platforms. That creates problems for 32-bit apps
running on 64-bit kernels. uAPI v2 addresses that particular issue, and
the problem more generally, by adding pad fields that explicitly pad
structs out to 64-bit boundaries, so they will pack to the same size now,
and even if some of the reserved padding is used for __u64 fields in the
future.
The new structs have been analysed with pahole to ensure that they
are sized as expected and contain no implicit padding.
The lack of future proofing in v1 makes it impossible to, for example,
add the debounce feature that is included in v2.
The future proofing is addressed by providing configurable attributes in
line config and reserved padding in all structs for future features.
Specifically, the line request, config, info, info_changed and event
structs receive updated versions and new ioctls.
As the majority of the structs and ioctls were being replaced, it is
opportune to rework some of the other aspects of the uAPI:
v1 has three different flags fields, each with their own separate
bit definitions. In v2 that is collapsed to one - gpio_v2_line_flag.
The handle and event requests are merged into a single request, the line
request, as the two requests were mostly the same other than the edge
detection provided by event requests. As a byproduct, the v2 uAPI allows
for multiple lines producing edge events on the same line handle.
This is a new capability as v1 only supports a single line in an event
request.
As a consequence, there are now only two types of file handle to be
concerned with, the chip and the line, and it is clearer which ioctls
apply to which type of handle.
There is also some minor renaming of fields for consistency compared to
their v1 counterparts, e.g. offset rather than lineoffset or line_offset,
and consumer rather than consumer_label.
Additionally, v1 GPIOHANDLES_MAX becomes GPIO_V2_LINES_MAX in v2 for
clarity, and the gpiohandle_data __u8 array becomes a bitmap in
gpio_v2_line_values.
The v2 uAPI is mostly a reorganisation and extension of v1, so userspace
code, particularly libgpiod, should readily port to it.
Signed-off-by: Kent Gibson <warthog618@gmail.com>
Reviewed-by: Andy Shevchenko <andy.shevchenko@gmail.com>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
2020-09-28 00:27:51 +00:00
|
|
|
*
|
|
|
|
* Must be a multiple of 8 to ensure 32/64-bit alignment of structs.
|
2020-09-28 00:27:50 +00:00
|
|
|
*/
|
|
|
|
#define GPIO_MAX_NAME_SIZE 32
|
|
|
|
|
gpio: add a userspace chardev ABI for GPIOs
A new chardev that is to be used for userspace GPIO access is
added in this patch. It is intended to gradually replace the
horribly broken sysfs ABI.
Using a chardev has many upsides:
- All operations are per-gpiochip, which is the actual
device underlying the GPIOs, making us tie in to the
kernel device model properly.
- Hotpluggable GPIO controllers can come and go, as this
kind of problem has been know to userspace for character
devices since ages, and if a gpiochip handle is held in
userspace we know we will break something, whereas the
sysfs is stateless.
- The one-value-per-file rule of sysfs is really hard to
maintain when you want to twist more than one knob at a time,
for example have in-kernel APIs to switch several GPIO
lines at the same time, and this will be possible to do
with a single ioctl() from userspace, saving a lot of
context switching.
We also need to add a new bus type for GPIO. This is
necessary for example for userspace coldplug, where sysfs is
traversed to find the boot-time device nodes and create the
character devices in /dev.
This new chardev ABI is *non* *optional* and can be counted
on to be present in the future, emphasizing the preference
of this ABI.
The ABI only implements one single ioctl() to get the name
and number of GPIO lines of a chip. Even this is debatable:
see it as a minimal example for review. This ABI shall be
ruthlessly reviewed and etched in stone.
The old /sys/class/gpio is still optional to compile in,
but will be deprecated.
Unique device IDs are created using IDR, which is overkill
and insanely scalable, but also well tested.
Cc: Johan Hovold <johan@kernel.org>
Cc: Michael Welling <mwelling@ieee.org>
Cc: Markus Pargmann <mpa@pengutronix.de>
Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Cc: Arnd Bergmann <arnd@arndb.de>
Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
2015-10-21 13:29:53 +00:00
|
|
|
/**
|
|
|
|
* struct gpiochip_info - Information about a certain GPIO chip
|
2016-02-25 20:01:48 +00:00
|
|
|
* @name: the Linux kernel name of this GPIO chip
|
|
|
|
* @label: a functional name for this GPIO chip, such as a product
|
2020-10-05 07:03:29 +00:00
|
|
|
* number, may be empty (i.e. label[0] == '\0')
|
gpio: add a userspace chardev ABI for GPIOs
A new chardev that is to be used for userspace GPIO access is
added in this patch. It is intended to gradually replace the
horribly broken sysfs ABI.
Using a chardev has many upsides:
- All operations are per-gpiochip, which is the actual
device underlying the GPIOs, making us tie in to the
kernel device model properly.
- Hotpluggable GPIO controllers can come and go, as this
kind of problem has been know to userspace for character
devices since ages, and if a gpiochip handle is held in
userspace we know we will break something, whereas the
sysfs is stateless.
- The one-value-per-file rule of sysfs is really hard to
maintain when you want to twist more than one knob at a time,
for example have in-kernel APIs to switch several GPIO
lines at the same time, and this will be possible to do
with a single ioctl() from userspace, saving a lot of
context switching.
We also need to add a new bus type for GPIO. This is
necessary for example for userspace coldplug, where sysfs is
traversed to find the boot-time device nodes and create the
character devices in /dev.
This new chardev ABI is *non* *optional* and can be counted
on to be present in the future, emphasizing the preference
of this ABI.
The ABI only implements one single ioctl() to get the name
and number of GPIO lines of a chip. Even this is debatable:
see it as a minimal example for review. This ABI shall be
ruthlessly reviewed and etched in stone.
The old /sys/class/gpio is still optional to compile in,
but will be deprecated.
Unique device IDs are created using IDR, which is overkill
and insanely scalable, but also well tested.
Cc: Johan Hovold <johan@kernel.org>
Cc: Michael Welling <mwelling@ieee.org>
Cc: Markus Pargmann <mpa@pengutronix.de>
Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Cc: Arnd Bergmann <arnd@arndb.de>
Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
2015-10-21 13:29:53 +00:00
|
|
|
* @lines: number of GPIO lines on this chip
|
|
|
|
*/
|
|
|
|
struct gpiochip_info {
|
2020-09-28 00:27:50 +00:00
|
|
|
char name[GPIO_MAX_NAME_SIZE];
|
|
|
|
char label[GPIO_MAX_NAME_SIZE];
|
gpio: add a userspace chardev ABI for GPIOs
A new chardev that is to be used for userspace GPIO access is
added in this patch. It is intended to gradually replace the
horribly broken sysfs ABI.
Using a chardev has many upsides:
- All operations are per-gpiochip, which is the actual
device underlying the GPIOs, making us tie in to the
kernel device model properly.
- Hotpluggable GPIO controllers can come and go, as this
kind of problem has been know to userspace for character
devices since ages, and if a gpiochip handle is held in
userspace we know we will break something, whereas the
sysfs is stateless.
- The one-value-per-file rule of sysfs is really hard to
maintain when you want to twist more than one knob at a time,
for example have in-kernel APIs to switch several GPIO
lines at the same time, and this will be possible to do
with a single ioctl() from userspace, saving a lot of
context switching.
We also need to add a new bus type for GPIO. This is
necessary for example for userspace coldplug, where sysfs is
traversed to find the boot-time device nodes and create the
character devices in /dev.
This new chardev ABI is *non* *optional* and can be counted
on to be present in the future, emphasizing the preference
of this ABI.
The ABI only implements one single ioctl() to get the name
and number of GPIO lines of a chip. Even this is debatable:
see it as a minimal example for review. This ABI shall be
ruthlessly reviewed and etched in stone.
The old /sys/class/gpio is still optional to compile in,
but will be deprecated.
Unique device IDs are created using IDR, which is overkill
and insanely scalable, but also well tested.
Cc: Johan Hovold <johan@kernel.org>
Cc: Michael Welling <mwelling@ieee.org>
Cc: Markus Pargmann <mpa@pengutronix.de>
Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Cc: Arnd Bergmann <arnd@arndb.de>
Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
2015-10-21 13:29:53 +00:00
|
|
|
__u32 lines;
|
|
|
|
};
|
|
|
|
|
gpio: uapi: define uAPI v2
Add a new version of the uAPI to address existing 32/64-bit alignment
issues, add support for debounce and event sequence numbers, allow
requested lines with different configurations, and provide some future
proofing by adding padding reserved for future use.
The alignment issue relates to the gpioevent_data, which packs to different
sizes on 32-bit and 64-bit platforms. That creates problems for 32-bit apps
running on 64-bit kernels. uAPI v2 addresses that particular issue, and
the problem more generally, by adding pad fields that explicitly pad
structs out to 64-bit boundaries, so they will pack to the same size now,
and even if some of the reserved padding is used for __u64 fields in the
future.
The new structs have been analysed with pahole to ensure that they
are sized as expected and contain no implicit padding.
The lack of future proofing in v1 makes it impossible to, for example,
add the debounce feature that is included in v2.
The future proofing is addressed by providing configurable attributes in
line config and reserved padding in all structs for future features.
Specifically, the line request, config, info, info_changed and event
structs receive updated versions and new ioctls.
As the majority of the structs and ioctls were being replaced, it is
opportune to rework some of the other aspects of the uAPI:
v1 has three different flags fields, each with their own separate
bit definitions. In v2 that is collapsed to one - gpio_v2_line_flag.
The handle and event requests are merged into a single request, the line
request, as the two requests were mostly the same other than the edge
detection provided by event requests. As a byproduct, the v2 uAPI allows
for multiple lines producing edge events on the same line handle.
This is a new capability as v1 only supports a single line in an event
request.
As a consequence, there are now only two types of file handle to be
concerned with, the chip and the line, and it is clearer which ioctls
apply to which type of handle.
There is also some minor renaming of fields for consistency compared to
their v1 counterparts, e.g. offset rather than lineoffset or line_offset,
and consumer rather than consumer_label.
Additionally, v1 GPIOHANDLES_MAX becomes GPIO_V2_LINES_MAX in v2 for
clarity, and the gpiohandle_data __u8 array becomes a bitmap in
gpio_v2_line_values.
The v2 uAPI is mostly a reorganisation and extension of v1, so userspace
code, particularly libgpiod, should readily port to it.
Signed-off-by: Kent Gibson <warthog618@gmail.com>
Reviewed-by: Andy Shevchenko <andy.shevchenko@gmail.com>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
2020-09-28 00:27:51 +00:00
|
|
|
/*
|
|
|
|
* Maximum number of requested lines.
|
|
|
|
*
|
|
|
|
* Must be no greater than 64, as bitmaps are restricted here to 64-bits
|
|
|
|
* for simplicity, and a multiple of 2 to ensure 32/64-bit alignment of
|
|
|
|
* structs.
|
|
|
|
*/
|
|
|
|
#define GPIO_V2_LINES_MAX 64
|
|
|
|
|
|
|
|
/*
|
|
|
|
* The maximum number of configuration attributes associated with a line
|
|
|
|
* request.
|
|
|
|
*/
|
|
|
|
#define GPIO_V2_LINE_NUM_ATTRS_MAX 10
|
|
|
|
|
|
|
|
/**
|
|
|
|
* enum gpio_v2_line_flag - &struct gpio_v2_line_attribute.flags values
|
|
|
|
* @GPIO_V2_LINE_FLAG_USED: line is not available for request
|
|
|
|
* @GPIO_V2_LINE_FLAG_ACTIVE_LOW: line active state is physical low
|
|
|
|
* @GPIO_V2_LINE_FLAG_INPUT: line is an input
|
|
|
|
* @GPIO_V2_LINE_FLAG_OUTPUT: line is an output
|
|
|
|
* @GPIO_V2_LINE_FLAG_EDGE_RISING: line detects rising (inactive to active)
|
|
|
|
* edges
|
|
|
|
* @GPIO_V2_LINE_FLAG_EDGE_FALLING: line detects falling (active to
|
|
|
|
* inactive) edges
|
|
|
|
* @GPIO_V2_LINE_FLAG_OPEN_DRAIN: line is an open drain output
|
|
|
|
* @GPIO_V2_LINE_FLAG_OPEN_SOURCE: line is an open source output
|
|
|
|
* @GPIO_V2_LINE_FLAG_BIAS_PULL_UP: line has pull-up bias enabled
|
|
|
|
* @GPIO_V2_LINE_FLAG_BIAS_PULL_DOWN: line has pull-down bias enabled
|
|
|
|
* @GPIO_V2_LINE_FLAG_BIAS_DISABLED: line has bias disabled
|
2020-10-14 23:11:56 +00:00
|
|
|
* @GPIO_V2_LINE_FLAG_EVENT_CLOCK_REALTIME: line events contain REALTIME timestamps
|
2022-04-22 20:52:18 +00:00
|
|
|
* @GPIO_V2_LINE_FLAG_EVENT_CLOCK_HTE: line events contain timestamps from
|
|
|
|
* hardware timestamp engine
|
gpio: uapi: define uAPI v2
Add a new version of the uAPI to address existing 32/64-bit alignment
issues, add support for debounce and event sequence numbers, allow
requested lines with different configurations, and provide some future
proofing by adding padding reserved for future use.
The alignment issue relates to the gpioevent_data, which packs to different
sizes on 32-bit and 64-bit platforms. That creates problems for 32-bit apps
running on 64-bit kernels. uAPI v2 addresses that particular issue, and
the problem more generally, by adding pad fields that explicitly pad
structs out to 64-bit boundaries, so they will pack to the same size now,
and even if some of the reserved padding is used for __u64 fields in the
future.
The new structs have been analysed with pahole to ensure that they
are sized as expected and contain no implicit padding.
The lack of future proofing in v1 makes it impossible to, for example,
add the debounce feature that is included in v2.
The future proofing is addressed by providing configurable attributes in
line config and reserved padding in all structs for future features.
Specifically, the line request, config, info, info_changed and event
structs receive updated versions and new ioctls.
As the majority of the structs and ioctls were being replaced, it is
opportune to rework some of the other aspects of the uAPI:
v1 has three different flags fields, each with their own separate
bit definitions. In v2 that is collapsed to one - gpio_v2_line_flag.
The handle and event requests are merged into a single request, the line
request, as the two requests were mostly the same other than the edge
detection provided by event requests. As a byproduct, the v2 uAPI allows
for multiple lines producing edge events on the same line handle.
This is a new capability as v1 only supports a single line in an event
request.
As a consequence, there are now only two types of file handle to be
concerned with, the chip and the line, and it is clearer which ioctls
apply to which type of handle.
There is also some minor renaming of fields for consistency compared to
their v1 counterparts, e.g. offset rather than lineoffset or line_offset,
and consumer rather than consumer_label.
Additionally, v1 GPIOHANDLES_MAX becomes GPIO_V2_LINES_MAX in v2 for
clarity, and the gpiohandle_data __u8 array becomes a bitmap in
gpio_v2_line_values.
The v2 uAPI is mostly a reorganisation and extension of v1, so userspace
code, particularly libgpiod, should readily port to it.
Signed-off-by: Kent Gibson <warthog618@gmail.com>
Reviewed-by: Andy Shevchenko <andy.shevchenko@gmail.com>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
2020-09-28 00:27:51 +00:00
|
|
|
*/
|
|
|
|
enum gpio_v2_line_flag {
|
|
|
|
GPIO_V2_LINE_FLAG_USED = _BITULL(0),
|
|
|
|
GPIO_V2_LINE_FLAG_ACTIVE_LOW = _BITULL(1),
|
|
|
|
GPIO_V2_LINE_FLAG_INPUT = _BITULL(2),
|
|
|
|
GPIO_V2_LINE_FLAG_OUTPUT = _BITULL(3),
|
|
|
|
GPIO_V2_LINE_FLAG_EDGE_RISING = _BITULL(4),
|
|
|
|
GPIO_V2_LINE_FLAG_EDGE_FALLING = _BITULL(5),
|
|
|
|
GPIO_V2_LINE_FLAG_OPEN_DRAIN = _BITULL(6),
|
|
|
|
GPIO_V2_LINE_FLAG_OPEN_SOURCE = _BITULL(7),
|
|
|
|
GPIO_V2_LINE_FLAG_BIAS_PULL_UP = _BITULL(8),
|
|
|
|
GPIO_V2_LINE_FLAG_BIAS_PULL_DOWN = _BITULL(9),
|
|
|
|
GPIO_V2_LINE_FLAG_BIAS_DISABLED = _BITULL(10),
|
2020-10-14 23:11:56 +00:00
|
|
|
GPIO_V2_LINE_FLAG_EVENT_CLOCK_REALTIME = _BITULL(11),
|
2022-04-22 20:52:18 +00:00
|
|
|
GPIO_V2_LINE_FLAG_EVENT_CLOCK_HTE = _BITULL(12),
|
gpio: uapi: define uAPI v2
Add a new version of the uAPI to address existing 32/64-bit alignment
issues, add support for debounce and event sequence numbers, allow
requested lines with different configurations, and provide some future
proofing by adding padding reserved for future use.
The alignment issue relates to the gpioevent_data, which packs to different
sizes on 32-bit and 64-bit platforms. That creates problems for 32-bit apps
running on 64-bit kernels. uAPI v2 addresses that particular issue, and
the problem more generally, by adding pad fields that explicitly pad
structs out to 64-bit boundaries, so they will pack to the same size now,
and even if some of the reserved padding is used for __u64 fields in the
future.
The new structs have been analysed with pahole to ensure that they
are sized as expected and contain no implicit padding.
The lack of future proofing in v1 makes it impossible to, for example,
add the debounce feature that is included in v2.
The future proofing is addressed by providing configurable attributes in
line config and reserved padding in all structs for future features.
Specifically, the line request, config, info, info_changed and event
structs receive updated versions and new ioctls.
As the majority of the structs and ioctls were being replaced, it is
opportune to rework some of the other aspects of the uAPI:
v1 has three different flags fields, each with their own separate
bit definitions. In v2 that is collapsed to one - gpio_v2_line_flag.
The handle and event requests are merged into a single request, the line
request, as the two requests were mostly the same other than the edge
detection provided by event requests. As a byproduct, the v2 uAPI allows
for multiple lines producing edge events on the same line handle.
This is a new capability as v1 only supports a single line in an event
request.
As a consequence, there are now only two types of file handle to be
concerned with, the chip and the line, and it is clearer which ioctls
apply to which type of handle.
There is also some minor renaming of fields for consistency compared to
their v1 counterparts, e.g. offset rather than lineoffset or line_offset,
and consumer rather than consumer_label.
Additionally, v1 GPIOHANDLES_MAX becomes GPIO_V2_LINES_MAX in v2 for
clarity, and the gpiohandle_data __u8 array becomes a bitmap in
gpio_v2_line_values.
The v2 uAPI is mostly a reorganisation and extension of v1, so userspace
code, particularly libgpiod, should readily port to it.
Signed-off-by: Kent Gibson <warthog618@gmail.com>
Reviewed-by: Andy Shevchenko <andy.shevchenko@gmail.com>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
2020-09-28 00:27:51 +00:00
|
|
|
};
|
|
|
|
|
|
|
|
/**
|
|
|
|
* struct gpio_v2_line_values - Values of GPIO lines
|
|
|
|
* @bits: a bitmap containing the value of the lines, set to 1 for active
|
|
|
|
* and 0 for inactive.
|
|
|
|
* @mask: a bitmap identifying the lines to get or set, with each bit
|
|
|
|
* number corresponding to the index into &struct
|
|
|
|
* gpio_v2_line_request.offsets.
|
|
|
|
*/
|
|
|
|
struct gpio_v2_line_values {
|
|
|
|
__aligned_u64 bits;
|
|
|
|
__aligned_u64 mask;
|
|
|
|
};
|
|
|
|
|
|
|
|
/**
|
|
|
|
* enum gpio_v2_line_attr_id - &struct gpio_v2_line_attribute.id values
|
|
|
|
* identifying which field of the attribute union is in use.
|
|
|
|
* @GPIO_V2_LINE_ATTR_ID_FLAGS: flags field is in use
|
|
|
|
* @GPIO_V2_LINE_ATTR_ID_OUTPUT_VALUES: values field is in use
|
2020-10-05 07:03:26 +00:00
|
|
|
* @GPIO_V2_LINE_ATTR_ID_DEBOUNCE: debounce_period_us field is in use
|
gpio: uapi: define uAPI v2
Add a new version of the uAPI to address existing 32/64-bit alignment
issues, add support for debounce and event sequence numbers, allow
requested lines with different configurations, and provide some future
proofing by adding padding reserved for future use.
The alignment issue relates to the gpioevent_data, which packs to different
sizes on 32-bit and 64-bit platforms. That creates problems for 32-bit apps
running on 64-bit kernels. uAPI v2 addresses that particular issue, and
the problem more generally, by adding pad fields that explicitly pad
structs out to 64-bit boundaries, so they will pack to the same size now,
and even if some of the reserved padding is used for __u64 fields in the
future.
The new structs have been analysed with pahole to ensure that they
are sized as expected and contain no implicit padding.
The lack of future proofing in v1 makes it impossible to, for example,
add the debounce feature that is included in v2.
The future proofing is addressed by providing configurable attributes in
line config and reserved padding in all structs for future features.
Specifically, the line request, config, info, info_changed and event
structs receive updated versions and new ioctls.
As the majority of the structs and ioctls were being replaced, it is
opportune to rework some of the other aspects of the uAPI:
v1 has three different flags fields, each with their own separate
bit definitions. In v2 that is collapsed to one - gpio_v2_line_flag.
The handle and event requests are merged into a single request, the line
request, as the two requests were mostly the same other than the edge
detection provided by event requests. As a byproduct, the v2 uAPI allows
for multiple lines producing edge events on the same line handle.
This is a new capability as v1 only supports a single line in an event
request.
As a consequence, there are now only two types of file handle to be
concerned with, the chip and the line, and it is clearer which ioctls
apply to which type of handle.
There is also some minor renaming of fields for consistency compared to
their v1 counterparts, e.g. offset rather than lineoffset or line_offset,
and consumer rather than consumer_label.
Additionally, v1 GPIOHANDLES_MAX becomes GPIO_V2_LINES_MAX in v2 for
clarity, and the gpiohandle_data __u8 array becomes a bitmap in
gpio_v2_line_values.
The v2 uAPI is mostly a reorganisation and extension of v1, so userspace
code, particularly libgpiod, should readily port to it.
Signed-off-by: Kent Gibson <warthog618@gmail.com>
Reviewed-by: Andy Shevchenko <andy.shevchenko@gmail.com>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
2020-09-28 00:27:51 +00:00
|
|
|
*/
|
|
|
|
enum gpio_v2_line_attr_id {
|
|
|
|
GPIO_V2_LINE_ATTR_ID_FLAGS = 1,
|
|
|
|
GPIO_V2_LINE_ATTR_ID_OUTPUT_VALUES = 2,
|
|
|
|
GPIO_V2_LINE_ATTR_ID_DEBOUNCE = 3,
|
|
|
|
};
|
|
|
|
|
|
|
|
/**
|
|
|
|
* struct gpio_v2_line_attribute - a configurable attribute of a line
|
|
|
|
* @id: attribute identifier with value from &enum gpio_v2_line_attr_id
|
|
|
|
* @padding: reserved for future use and must be zero filled
|
2020-10-05 07:03:27 +00:00
|
|
|
* @flags: if id is %GPIO_V2_LINE_ATTR_ID_FLAGS, the flags for the GPIO
|
|
|
|
* line, with values from &enum gpio_v2_line_flag, such as
|
|
|
|
* %GPIO_V2_LINE_FLAG_ACTIVE_LOW, %GPIO_V2_LINE_FLAG_OUTPUT etc, added
|
gpio: uapi: define uAPI v2
Add a new version of the uAPI to address existing 32/64-bit alignment
issues, add support for debounce and event sequence numbers, allow
requested lines with different configurations, and provide some future
proofing by adding padding reserved for future use.
The alignment issue relates to the gpioevent_data, which packs to different
sizes on 32-bit and 64-bit platforms. That creates problems for 32-bit apps
running on 64-bit kernels. uAPI v2 addresses that particular issue, and
the problem more generally, by adding pad fields that explicitly pad
structs out to 64-bit boundaries, so they will pack to the same size now,
and even if some of the reserved padding is used for __u64 fields in the
future.
The new structs have been analysed with pahole to ensure that they
are sized as expected and contain no implicit padding.
The lack of future proofing in v1 makes it impossible to, for example,
add the debounce feature that is included in v2.
The future proofing is addressed by providing configurable attributes in
line config and reserved padding in all structs for future features.
Specifically, the line request, config, info, info_changed and event
structs receive updated versions and new ioctls.
As the majority of the structs and ioctls were being replaced, it is
opportune to rework some of the other aspects of the uAPI:
v1 has three different flags fields, each with their own separate
bit definitions. In v2 that is collapsed to one - gpio_v2_line_flag.
The handle and event requests are merged into a single request, the line
request, as the two requests were mostly the same other than the edge
detection provided by event requests. As a byproduct, the v2 uAPI allows
for multiple lines producing edge events on the same line handle.
This is a new capability as v1 only supports a single line in an event
request.
As a consequence, there are now only two types of file handle to be
concerned with, the chip and the line, and it is clearer which ioctls
apply to which type of handle.
There is also some minor renaming of fields for consistency compared to
their v1 counterparts, e.g. offset rather than lineoffset or line_offset,
and consumer rather than consumer_label.
Additionally, v1 GPIOHANDLES_MAX becomes GPIO_V2_LINES_MAX in v2 for
clarity, and the gpiohandle_data __u8 array becomes a bitmap in
gpio_v2_line_values.
The v2 uAPI is mostly a reorganisation and extension of v1, so userspace
code, particularly libgpiod, should readily port to it.
Signed-off-by: Kent Gibson <warthog618@gmail.com>
Reviewed-by: Andy Shevchenko <andy.shevchenko@gmail.com>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
2020-09-28 00:27:51 +00:00
|
|
|
* together. This overrides the default flags contained in the &struct
|
|
|
|
* gpio_v2_line_config for the associated line.
|
2020-10-05 07:03:27 +00:00
|
|
|
* @values: if id is %GPIO_V2_LINE_ATTR_ID_OUTPUT_VALUES, a bitmap
|
gpio: uapi: define uAPI v2
Add a new version of the uAPI to address existing 32/64-bit alignment
issues, add support for debounce and event sequence numbers, allow
requested lines with different configurations, and provide some future
proofing by adding padding reserved for future use.
The alignment issue relates to the gpioevent_data, which packs to different
sizes on 32-bit and 64-bit platforms. That creates problems for 32-bit apps
running on 64-bit kernels. uAPI v2 addresses that particular issue, and
the problem more generally, by adding pad fields that explicitly pad
structs out to 64-bit boundaries, so they will pack to the same size now,
and even if some of the reserved padding is used for __u64 fields in the
future.
The new structs have been analysed with pahole to ensure that they
are sized as expected and contain no implicit padding.
The lack of future proofing in v1 makes it impossible to, for example,
add the debounce feature that is included in v2.
The future proofing is addressed by providing configurable attributes in
line config and reserved padding in all structs for future features.
Specifically, the line request, config, info, info_changed and event
structs receive updated versions and new ioctls.
As the majority of the structs and ioctls were being replaced, it is
opportune to rework some of the other aspects of the uAPI:
v1 has three different flags fields, each with their own separate
bit definitions. In v2 that is collapsed to one - gpio_v2_line_flag.
The handle and event requests are merged into a single request, the line
request, as the two requests were mostly the same other than the edge
detection provided by event requests. As a byproduct, the v2 uAPI allows
for multiple lines producing edge events on the same line handle.
This is a new capability as v1 only supports a single line in an event
request.
As a consequence, there are now only two types of file handle to be
concerned with, the chip and the line, and it is clearer which ioctls
apply to which type of handle.
There is also some minor renaming of fields for consistency compared to
their v1 counterparts, e.g. offset rather than lineoffset or line_offset,
and consumer rather than consumer_label.
Additionally, v1 GPIOHANDLES_MAX becomes GPIO_V2_LINES_MAX in v2 for
clarity, and the gpiohandle_data __u8 array becomes a bitmap in
gpio_v2_line_values.
The v2 uAPI is mostly a reorganisation and extension of v1, so userspace
code, particularly libgpiod, should readily port to it.
Signed-off-by: Kent Gibson <warthog618@gmail.com>
Reviewed-by: Andy Shevchenko <andy.shevchenko@gmail.com>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
2020-09-28 00:27:51 +00:00
|
|
|
* containing the values to which the lines will be set, with each bit
|
|
|
|
* number corresponding to the index into &struct
|
|
|
|
* gpio_v2_line_request.offsets.
|
2020-10-05 07:03:27 +00:00
|
|
|
* @debounce_period_us: if id is %GPIO_V2_LINE_ATTR_ID_DEBOUNCE, the
|
|
|
|
* desired debounce period, in microseconds
|
gpio: uapi: define uAPI v2
Add a new version of the uAPI to address existing 32/64-bit alignment
issues, add support for debounce and event sequence numbers, allow
requested lines with different configurations, and provide some future
proofing by adding padding reserved for future use.
The alignment issue relates to the gpioevent_data, which packs to different
sizes on 32-bit and 64-bit platforms. That creates problems for 32-bit apps
running on 64-bit kernels. uAPI v2 addresses that particular issue, and
the problem more generally, by adding pad fields that explicitly pad
structs out to 64-bit boundaries, so they will pack to the same size now,
and even if some of the reserved padding is used for __u64 fields in the
future.
The new structs have been analysed with pahole to ensure that they
are sized as expected and contain no implicit padding.
The lack of future proofing in v1 makes it impossible to, for example,
add the debounce feature that is included in v2.
The future proofing is addressed by providing configurable attributes in
line config and reserved padding in all structs for future features.
Specifically, the line request, config, info, info_changed and event
structs receive updated versions and new ioctls.
As the majority of the structs and ioctls were being replaced, it is
opportune to rework some of the other aspects of the uAPI:
v1 has three different flags fields, each with their own separate
bit definitions. In v2 that is collapsed to one - gpio_v2_line_flag.
The handle and event requests are merged into a single request, the line
request, as the two requests were mostly the same other than the edge
detection provided by event requests. As a byproduct, the v2 uAPI allows
for multiple lines producing edge events on the same line handle.
This is a new capability as v1 only supports a single line in an event
request.
As a consequence, there are now only two types of file handle to be
concerned with, the chip and the line, and it is clearer which ioctls
apply to which type of handle.
There is also some minor renaming of fields for consistency compared to
their v1 counterparts, e.g. offset rather than lineoffset or line_offset,
and consumer rather than consumer_label.
Additionally, v1 GPIOHANDLES_MAX becomes GPIO_V2_LINES_MAX in v2 for
clarity, and the gpiohandle_data __u8 array becomes a bitmap in
gpio_v2_line_values.
The v2 uAPI is mostly a reorganisation and extension of v1, so userspace
code, particularly libgpiod, should readily port to it.
Signed-off-by: Kent Gibson <warthog618@gmail.com>
Reviewed-by: Andy Shevchenko <andy.shevchenko@gmail.com>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
2020-09-28 00:27:51 +00:00
|
|
|
*/
|
|
|
|
struct gpio_v2_line_attribute {
|
|
|
|
__u32 id;
|
|
|
|
__u32 padding;
|
|
|
|
union {
|
|
|
|
__aligned_u64 flags;
|
|
|
|
__aligned_u64 values;
|
|
|
|
__u32 debounce_period_us;
|
|
|
|
};
|
|
|
|
};
|
|
|
|
|
|
|
|
/**
|
|
|
|
* struct gpio_v2_line_config_attribute - a configuration attribute
|
|
|
|
* associated with one or more of the requested lines.
|
|
|
|
* @attr: the configurable attribute
|
|
|
|
* @mask: a 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_attribute {
|
|
|
|
struct gpio_v2_line_attribute attr;
|
|
|
|
__aligned_u64 mask;
|
|
|
|
};
|
|
|
|
|
|
|
|
/**
|
|
|
|
* struct gpio_v2_line_config - Configuration for GPIO lines
|
2020-10-05 07:03:27 +00:00
|
|
|
* @flags: flags for the GPIO lines, with values from &enum
|
|
|
|
* gpio_v2_line_flag, such as %GPIO_V2_LINE_FLAG_ACTIVE_LOW,
|
|
|
|
* %GPIO_V2_LINE_FLAG_OUTPUT etc, added together. This is the default for
|
gpio: uapi: define uAPI v2
Add a new version of the uAPI to address existing 32/64-bit alignment
issues, add support for debounce and event sequence numbers, allow
requested lines with different configurations, and provide some future
proofing by adding padding reserved for future use.
The alignment issue relates to the gpioevent_data, which packs to different
sizes on 32-bit and 64-bit platforms. That creates problems for 32-bit apps
running on 64-bit kernels. uAPI v2 addresses that particular issue, and
the problem more generally, by adding pad fields that explicitly pad
structs out to 64-bit boundaries, so they will pack to the same size now,
and even if some of the reserved padding is used for __u64 fields in the
future.
The new structs have been analysed with pahole to ensure that they
are sized as expected and contain no implicit padding.
The lack of future proofing in v1 makes it impossible to, for example,
add the debounce feature that is included in v2.
The future proofing is addressed by providing configurable attributes in
line config and reserved padding in all structs for future features.
Specifically, the line request, config, info, info_changed and event
structs receive updated versions and new ioctls.
As the majority of the structs and ioctls were being replaced, it is
opportune to rework some of the other aspects of the uAPI:
v1 has three different flags fields, each with their own separate
bit definitions. In v2 that is collapsed to one - gpio_v2_line_flag.
The handle and event requests are merged into a single request, the line
request, as the two requests were mostly the same other than the edge
detection provided by event requests. As a byproduct, the v2 uAPI allows
for multiple lines producing edge events on the same line handle.
This is a new capability as v1 only supports a single line in an event
request.
As a consequence, there are now only two types of file handle to be
concerned with, the chip and the line, and it is clearer which ioctls
apply to which type of handle.
There is also some minor renaming of fields for consistency compared to
their v1 counterparts, e.g. offset rather than lineoffset or line_offset,
and consumer rather than consumer_label.
Additionally, v1 GPIOHANDLES_MAX becomes GPIO_V2_LINES_MAX in v2 for
clarity, and the gpiohandle_data __u8 array becomes a bitmap in
gpio_v2_line_values.
The v2 uAPI is mostly a reorganisation and extension of v1, so userspace
code, particularly libgpiod, should readily port to it.
Signed-off-by: Kent Gibson <warthog618@gmail.com>
Reviewed-by: Andy Shevchenko <andy.shevchenko@gmail.com>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
2020-09-28 00:27:51 +00:00
|
|
|
* all requested lines but may be overridden for particular lines using
|
2020-10-05 07:03:27 +00:00
|
|
|
* @attrs.
|
|
|
|
* @num_attrs: the number of attributes in @attrs
|
gpio: uapi: define uAPI v2
Add a new version of the uAPI to address existing 32/64-bit alignment
issues, add support for debounce and event sequence numbers, allow
requested lines with different configurations, and provide some future
proofing by adding padding reserved for future use.
The alignment issue relates to the gpioevent_data, which packs to different
sizes on 32-bit and 64-bit platforms. That creates problems for 32-bit apps
running on 64-bit kernels. uAPI v2 addresses that particular issue, and
the problem more generally, by adding pad fields that explicitly pad
structs out to 64-bit boundaries, so they will pack to the same size now,
and even if some of the reserved padding is used for __u64 fields in the
future.
The new structs have been analysed with pahole to ensure that they
are sized as expected and contain no implicit padding.
The lack of future proofing in v1 makes it impossible to, for example,
add the debounce feature that is included in v2.
The future proofing is addressed by providing configurable attributes in
line config and reserved padding in all structs for future features.
Specifically, the line request, config, info, info_changed and event
structs receive updated versions and new ioctls.
As the majority of the structs and ioctls were being replaced, it is
opportune to rework some of the other aspects of the uAPI:
v1 has three different flags fields, each with their own separate
bit definitions. In v2 that is collapsed to one - gpio_v2_line_flag.
The handle and event requests are merged into a single request, the line
request, as the two requests were mostly the same other than the edge
detection provided by event requests. As a byproduct, the v2 uAPI allows
for multiple lines producing edge events on the same line handle.
This is a new capability as v1 only supports a single line in an event
request.
As a consequence, there are now only two types of file handle to be
concerned with, the chip and the line, and it is clearer which ioctls
apply to which type of handle.
There is also some minor renaming of fields for consistency compared to
their v1 counterparts, e.g. offset rather than lineoffset or line_offset,
and consumer rather than consumer_label.
Additionally, v1 GPIOHANDLES_MAX becomes GPIO_V2_LINES_MAX in v2 for
clarity, and the gpiohandle_data __u8 array becomes a bitmap in
gpio_v2_line_values.
The v2 uAPI is mostly a reorganisation and extension of v1, so userspace
code, particularly libgpiod, should readily port to it.
Signed-off-by: Kent Gibson <warthog618@gmail.com>
Reviewed-by: Andy Shevchenko <andy.shevchenko@gmail.com>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
2020-09-28 00:27:51 +00:00
|
|
|
* @padding: reserved for future use and must be zero filled
|
|
|
|
* @attrs: the 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_config {
|
|
|
|
__aligned_u64 flags;
|
|
|
|
__u32 num_attrs;
|
|
|
|
/* Pad to fill implicit padding and reserve space for future use. */
|
|
|
|
__u32 padding[5];
|
|
|
|
struct gpio_v2_line_config_attribute attrs[GPIO_V2_LINE_NUM_ATTRS_MAX];
|
|
|
|
};
|
|
|
|
|
|
|
|
/**
|
|
|
|
* struct gpio_v2_line_request - Information about a request for GPIO lines
|
|
|
|
* @offsets: an array of desired lines, specified by offset index for the
|
|
|
|
* associated GPIO chip
|
|
|
|
* @consumer: a desired consumer label for the selected GPIO lines such as
|
|
|
|
* "my-bitbanged-relay"
|
|
|
|
* @config: requested configuration for the lines.
|
|
|
|
* @num_lines: number of lines requested in this request, i.e. the number
|
2020-10-05 07:03:27 +00:00
|
|
|
* of valid fields in the %GPIO_V2_LINES_MAX sized arrays, set to 1 to
|
gpio: uapi: define uAPI v2
Add a new version of the uAPI to address existing 32/64-bit alignment
issues, add support for debounce and event sequence numbers, allow
requested lines with different configurations, and provide some future
proofing by adding padding reserved for future use.
The alignment issue relates to the gpioevent_data, which packs to different
sizes on 32-bit and 64-bit platforms. That creates problems for 32-bit apps
running on 64-bit kernels. uAPI v2 addresses that particular issue, and
the problem more generally, by adding pad fields that explicitly pad
structs out to 64-bit boundaries, so they will pack to the same size now,
and even if some of the reserved padding is used for __u64 fields in the
future.
The new structs have been analysed with pahole to ensure that they
are sized as expected and contain no implicit padding.
The lack of future proofing in v1 makes it impossible to, for example,
add the debounce feature that is included in v2.
The future proofing is addressed by providing configurable attributes in
line config and reserved padding in all structs for future features.
Specifically, the line request, config, info, info_changed and event
structs receive updated versions and new ioctls.
As the majority of the structs and ioctls were being replaced, it is
opportune to rework some of the other aspects of the uAPI:
v1 has three different flags fields, each with their own separate
bit definitions. In v2 that is collapsed to one - gpio_v2_line_flag.
The handle and event requests are merged into a single request, the line
request, as the two requests were mostly the same other than the edge
detection provided by event requests. As a byproduct, the v2 uAPI allows
for multiple lines producing edge events on the same line handle.
This is a new capability as v1 only supports a single line in an event
request.
As a consequence, there are now only two types of file handle to be
concerned with, the chip and the line, and it is clearer which ioctls
apply to which type of handle.
There is also some minor renaming of fields for consistency compared to
their v1 counterparts, e.g. offset rather than lineoffset or line_offset,
and consumer rather than consumer_label.
Additionally, v1 GPIOHANDLES_MAX becomes GPIO_V2_LINES_MAX in v2 for
clarity, and the gpiohandle_data __u8 array becomes a bitmap in
gpio_v2_line_values.
The v2 uAPI is mostly a reorganisation and extension of v1, so userspace
code, particularly libgpiod, should readily port to it.
Signed-off-by: Kent Gibson <warthog618@gmail.com>
Reviewed-by: Andy Shevchenko <andy.shevchenko@gmail.com>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
2020-09-28 00:27:51 +00:00
|
|
|
* request a single line
|
|
|
|
* @event_buffer_size: a 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
|
2020-10-05 07:03:27 +00:00
|
|
|
* of @num_lines * 16.
|
gpio: uapi: define uAPI v2
Add a new version of the uAPI to address existing 32/64-bit alignment
issues, add support for debounce and event sequence numbers, allow
requested lines with different configurations, and provide some future
proofing by adding padding reserved for future use.
The alignment issue relates to the gpioevent_data, which packs to different
sizes on 32-bit and 64-bit platforms. That creates problems for 32-bit apps
running on 64-bit kernels. uAPI v2 addresses that particular issue, and
the problem more generally, by adding pad fields that explicitly pad
structs out to 64-bit boundaries, so they will pack to the same size now,
and even if some of the reserved padding is used for __u64 fields in the
future.
The new structs have been analysed with pahole to ensure that they
are sized as expected and contain no implicit padding.
The lack of future proofing in v1 makes it impossible to, for example,
add the debounce feature that is included in v2.
The future proofing is addressed by providing configurable attributes in
line config and reserved padding in all structs for future features.
Specifically, the line request, config, info, info_changed and event
structs receive updated versions and new ioctls.
As the majority of the structs and ioctls were being replaced, it is
opportune to rework some of the other aspects of the uAPI:
v1 has three different flags fields, each with their own separate
bit definitions. In v2 that is collapsed to one - gpio_v2_line_flag.
The handle and event requests are merged into a single request, the line
request, as the two requests were mostly the same other than the edge
detection provided by event requests. As a byproduct, the v2 uAPI allows
for multiple lines producing edge events on the same line handle.
This is a new capability as v1 only supports a single line in an event
request.
As a consequence, there are now only two types of file handle to be
concerned with, the chip and the line, and it is clearer which ioctls
apply to which type of handle.
There is also some minor renaming of fields for consistency compared to
their v1 counterparts, e.g. offset rather than lineoffset or line_offset,
and consumer rather than consumer_label.
Additionally, v1 GPIOHANDLES_MAX becomes GPIO_V2_LINES_MAX in v2 for
clarity, and the gpiohandle_data __u8 array becomes a bitmap in
gpio_v2_line_values.
The v2 uAPI is mostly a reorganisation and extension of v1, so userspace
code, particularly libgpiod, should readily port to it.
Signed-off-by: Kent Gibson <warthog618@gmail.com>
Reviewed-by: Andy Shevchenko <andy.shevchenko@gmail.com>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
2020-09-28 00:27:51 +00:00
|
|
|
* @padding: reserved for future use and must be zero filled
|
|
|
|
* @fd: if successful this field will contain a valid anonymous file handle
|
2020-10-05 07:03:27 +00:00
|
|
|
* after a %GPIO_GET_LINE_IOCTL operation, zero or negative value means
|
gpio: uapi: define uAPI v2
Add a new version of the uAPI to address existing 32/64-bit alignment
issues, add support for debounce and event sequence numbers, allow
requested lines with different configurations, and provide some future
proofing by adding padding reserved for future use.
The alignment issue relates to the gpioevent_data, which packs to different
sizes on 32-bit and 64-bit platforms. That creates problems for 32-bit apps
running on 64-bit kernels. uAPI v2 addresses that particular issue, and
the problem more generally, by adding pad fields that explicitly pad
structs out to 64-bit boundaries, so they will pack to the same size now,
and even if some of the reserved padding is used for __u64 fields in the
future.
The new structs have been analysed with pahole to ensure that they
are sized as expected and contain no implicit padding.
The lack of future proofing in v1 makes it impossible to, for example,
add the debounce feature that is included in v2.
The future proofing is addressed by providing configurable attributes in
line config and reserved padding in all structs for future features.
Specifically, the line request, config, info, info_changed and event
structs receive updated versions and new ioctls.
As the majority of the structs and ioctls were being replaced, it is
opportune to rework some of the other aspects of the uAPI:
v1 has three different flags fields, each with their own separate
bit definitions. In v2 that is collapsed to one - gpio_v2_line_flag.
The handle and event requests are merged into a single request, the line
request, as the two requests were mostly the same other than the edge
detection provided by event requests. As a byproduct, the v2 uAPI allows
for multiple lines producing edge events on the same line handle.
This is a new capability as v1 only supports a single line in an event
request.
As a consequence, there are now only two types of file handle to be
concerned with, the chip and the line, and it is clearer which ioctls
apply to which type of handle.
There is also some minor renaming of fields for consistency compared to
their v1 counterparts, e.g. offset rather than lineoffset or line_offset,
and consumer rather than consumer_label.
Additionally, v1 GPIOHANDLES_MAX becomes GPIO_V2_LINES_MAX in v2 for
clarity, and the gpiohandle_data __u8 array becomes a bitmap in
gpio_v2_line_values.
The v2 uAPI is mostly a reorganisation and extension of v1, so userspace
code, particularly libgpiod, should readily port to it.
Signed-off-by: Kent Gibson <warthog618@gmail.com>
Reviewed-by: Andy Shevchenko <andy.shevchenko@gmail.com>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
2020-09-28 00:27:51 +00:00
|
|
|
* error
|
|
|
|
*/
|
|
|
|
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;
|
|
|
|
/* Pad to fill implicit padding and reserve space for future use. */
|
|
|
|
__u32 padding[5];
|
|
|
|
__s32 fd;
|
|
|
|
};
|
|
|
|
|
|
|
|
/**
|
|
|
|
* struct gpio_v2_line_info - Information about a certain GPIO line
|
|
|
|
* @name: the 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
|
2020-10-05 07:03:29 +00:00
|
|
|
* GPIO chip, may be empty (i.e. name[0] == '\0')
|
gpio: uapi: define uAPI v2
Add a new version of the uAPI to address existing 32/64-bit alignment
issues, add support for debounce and event sequence numbers, allow
requested lines with different configurations, and provide some future
proofing by adding padding reserved for future use.
The alignment issue relates to the gpioevent_data, which packs to different
sizes on 32-bit and 64-bit platforms. That creates problems for 32-bit apps
running on 64-bit kernels. uAPI v2 addresses that particular issue, and
the problem more generally, by adding pad fields that explicitly pad
structs out to 64-bit boundaries, so they will pack to the same size now,
and even if some of the reserved padding is used for __u64 fields in the
future.
The new structs have been analysed with pahole to ensure that they
are sized as expected and contain no implicit padding.
The lack of future proofing in v1 makes it impossible to, for example,
add the debounce feature that is included in v2.
The future proofing is addressed by providing configurable attributes in
line config and reserved padding in all structs for future features.
Specifically, the line request, config, info, info_changed and event
structs receive updated versions and new ioctls.
As the majority of the structs and ioctls were being replaced, it is
opportune to rework some of the other aspects of the uAPI:
v1 has three different flags fields, each with their own separate
bit definitions. In v2 that is collapsed to one - gpio_v2_line_flag.
The handle and event requests are merged into a single request, the line
request, as the two requests were mostly the same other than the edge
detection provided by event requests. As a byproduct, the v2 uAPI allows
for multiple lines producing edge events on the same line handle.
This is a new capability as v1 only supports a single line in an event
request.
As a consequence, there are now only two types of file handle to be
concerned with, the chip and the line, and it is clearer which ioctls
apply to which type of handle.
There is also some minor renaming of fields for consistency compared to
their v1 counterparts, e.g. offset rather than lineoffset or line_offset,
and consumer rather than consumer_label.
Additionally, v1 GPIOHANDLES_MAX becomes GPIO_V2_LINES_MAX in v2 for
clarity, and the gpiohandle_data __u8 array becomes a bitmap in
gpio_v2_line_values.
The v2 uAPI is mostly a reorganisation and extension of v1, so userspace
code, particularly libgpiod, should readily port to it.
Signed-off-by: Kent Gibson <warthog618@gmail.com>
Reviewed-by: Andy Shevchenko <andy.shevchenko@gmail.com>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
2020-09-28 00:27:51 +00:00
|
|
|
* @consumer: a 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
|
|
|
|
* @offset: the local offset on this GPIO chip, fill this in when
|
|
|
|
* requesting the line information from the kernel
|
2020-10-05 07:03:27 +00:00
|
|
|
* @num_attrs: the number of attributes in @attrs
|
2021-01-19 13:57:27 +00:00
|
|
|
* @flags: flags for this GPIO line, with values from &enum
|
2020-10-05 07:03:27 +00:00
|
|
|
* gpio_v2_line_flag, such as %GPIO_V2_LINE_FLAG_ACTIVE_LOW,
|
|
|
|
* %GPIO_V2_LINE_FLAG_OUTPUT etc, added together.
|
gpio: uapi: define uAPI v2
Add a new version of the uAPI to address existing 32/64-bit alignment
issues, add support for debounce and event sequence numbers, allow
requested lines with different configurations, and provide some future
proofing by adding padding reserved for future use.
The alignment issue relates to the gpioevent_data, which packs to different
sizes on 32-bit and 64-bit platforms. That creates problems for 32-bit apps
running on 64-bit kernels. uAPI v2 addresses that particular issue, and
the problem more generally, by adding pad fields that explicitly pad
structs out to 64-bit boundaries, so they will pack to the same size now,
and even if some of the reserved padding is used for __u64 fields in the
future.
The new structs have been analysed with pahole to ensure that they
are sized as expected and contain no implicit padding.
The lack of future proofing in v1 makes it impossible to, for example,
add the debounce feature that is included in v2.
The future proofing is addressed by providing configurable attributes in
line config and reserved padding in all structs for future features.
Specifically, the line request, config, info, info_changed and event
structs receive updated versions and new ioctls.
As the majority of the structs and ioctls were being replaced, it is
opportune to rework some of the other aspects of the uAPI:
v1 has three different flags fields, each with their own separate
bit definitions. In v2 that is collapsed to one - gpio_v2_line_flag.
The handle and event requests are merged into a single request, the line
request, as the two requests were mostly the same other than the edge
detection provided by event requests. As a byproduct, the v2 uAPI allows
for multiple lines producing edge events on the same line handle.
This is a new capability as v1 only supports a single line in an event
request.
As a consequence, there are now only two types of file handle to be
concerned with, the chip and the line, and it is clearer which ioctls
apply to which type of handle.
There is also some minor renaming of fields for consistency compared to
their v1 counterparts, e.g. offset rather than lineoffset or line_offset,
and consumer rather than consumer_label.
Additionally, v1 GPIOHANDLES_MAX becomes GPIO_V2_LINES_MAX in v2 for
clarity, and the gpiohandle_data __u8 array becomes a bitmap in
gpio_v2_line_values.
The v2 uAPI is mostly a reorganisation and extension of v1, so userspace
code, particularly libgpiod, should readily port to it.
Signed-off-by: Kent Gibson <warthog618@gmail.com>
Reviewed-by: Andy Shevchenko <andy.shevchenko@gmail.com>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
2020-09-28 00:27:51 +00:00
|
|
|
* @attrs: the configuration attributes associated with the line
|
|
|
|
* @padding: reserved for future use
|
|
|
|
*/
|
|
|
|
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];
|
|
|
|
/* Space reserved for future use. */
|
|
|
|
__u32 padding[4];
|
|
|
|
};
|
|
|
|
|
|
|
|
/**
|
|
|
|
* enum gpio_v2_line_changed_type - &struct gpio_v2_line_changed.event_type
|
|
|
|
* values
|
|
|
|
* @GPIO_V2_LINE_CHANGED_REQUESTED: line has been requested
|
|
|
|
* @GPIO_V2_LINE_CHANGED_RELEASED: line has been released
|
|
|
|
* @GPIO_V2_LINE_CHANGED_CONFIG: line has been reconfigured
|
|
|
|
*/
|
|
|
|
enum gpio_v2_line_changed_type {
|
|
|
|
GPIO_V2_LINE_CHANGED_REQUESTED = 1,
|
|
|
|
GPIO_V2_LINE_CHANGED_RELEASED = 2,
|
|
|
|
GPIO_V2_LINE_CHANGED_CONFIG = 3,
|
|
|
|
};
|
|
|
|
|
|
|
|
/**
|
|
|
|
* struct gpio_v2_line_info_changed - Information about a change in status
|
|
|
|
* of a GPIO line
|
|
|
|
* @info: updated line information
|
|
|
|
* @timestamp_ns: estimate of time of status change occurrence, in nanoseconds
|
2020-10-05 07:03:27 +00:00
|
|
|
* @event_type: the type of change with a value from &enum
|
gpio: uapi: define uAPI v2
Add a new version of the uAPI to address existing 32/64-bit alignment
issues, add support for debounce and event sequence numbers, allow
requested lines with different configurations, and provide some future
proofing by adding padding reserved for future use.
The alignment issue relates to the gpioevent_data, which packs to different
sizes on 32-bit and 64-bit platforms. That creates problems for 32-bit apps
running on 64-bit kernels. uAPI v2 addresses that particular issue, and
the problem more generally, by adding pad fields that explicitly pad
structs out to 64-bit boundaries, so they will pack to the same size now,
and even if some of the reserved padding is used for __u64 fields in the
future.
The new structs have been analysed with pahole to ensure that they
are sized as expected and contain no implicit padding.
The lack of future proofing in v1 makes it impossible to, for example,
add the debounce feature that is included in v2.
The future proofing is addressed by providing configurable attributes in
line config and reserved padding in all structs for future features.
Specifically, the line request, config, info, info_changed and event
structs receive updated versions and new ioctls.
As the majority of the structs and ioctls were being replaced, it is
opportune to rework some of the other aspects of the uAPI:
v1 has three different flags fields, each with their own separate
bit definitions. In v2 that is collapsed to one - gpio_v2_line_flag.
The handle and event requests are merged into a single request, the line
request, as the two requests were mostly the same other than the edge
detection provided by event requests. As a byproduct, the v2 uAPI allows
for multiple lines producing edge events on the same line handle.
This is a new capability as v1 only supports a single line in an event
request.
As a consequence, there are now only two types of file handle to be
concerned with, the chip and the line, and it is clearer which ioctls
apply to which type of handle.
There is also some minor renaming of fields for consistency compared to
their v1 counterparts, e.g. offset rather than lineoffset or line_offset,
and consumer rather than consumer_label.
Additionally, v1 GPIOHANDLES_MAX becomes GPIO_V2_LINES_MAX in v2 for
clarity, and the gpiohandle_data __u8 array becomes a bitmap in
gpio_v2_line_values.
The v2 uAPI is mostly a reorganisation and extension of v1, so userspace
code, particularly libgpiod, should readily port to it.
Signed-off-by: Kent Gibson <warthog618@gmail.com>
Reviewed-by: Andy Shevchenko <andy.shevchenko@gmail.com>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
2020-09-28 00:27:51 +00:00
|
|
|
* gpio_v2_line_changed_type
|
|
|
|
* @padding: reserved for future use
|
|
|
|
*/
|
|
|
|
struct gpio_v2_line_info_changed {
|
|
|
|
struct gpio_v2_line_info info;
|
|
|
|
__aligned_u64 timestamp_ns;
|
|
|
|
__u32 event_type;
|
|
|
|
/* Pad struct to 64-bit boundary and reserve space for future use. */
|
|
|
|
__u32 padding[5];
|
|
|
|
};
|
|
|
|
|
|
|
|
/**
|
|
|
|
* enum gpio_v2_line_event_id - &struct gpio_v2_line_event.id values
|
|
|
|
* @GPIO_V2_LINE_EVENT_RISING_EDGE: event triggered by a rising edge
|
|
|
|
* @GPIO_V2_LINE_EVENT_FALLING_EDGE: event triggered by a falling edge
|
|
|
|
*/
|
|
|
|
enum gpio_v2_line_event_id {
|
|
|
|
GPIO_V2_LINE_EVENT_RISING_EDGE = 1,
|
|
|
|
GPIO_V2_LINE_EVENT_FALLING_EDGE = 2,
|
|
|
|
};
|
|
|
|
|
|
|
|
/**
|
|
|
|
* struct gpio_v2_line_event - The actual event being pushed to userspace
|
|
|
|
* @timestamp_ns: best estimate of time of event occurrence, in nanoseconds.
|
2020-10-05 07:03:27 +00:00
|
|
|
* @id: event identifier with value from &enum gpio_v2_line_event_id
|
gpio: uapi: define uAPI v2
Add a new version of the uAPI to address existing 32/64-bit alignment
issues, add support for debounce and event sequence numbers, allow
requested lines with different configurations, and provide some future
proofing by adding padding reserved for future use.
The alignment issue relates to the gpioevent_data, which packs to different
sizes on 32-bit and 64-bit platforms. That creates problems for 32-bit apps
running on 64-bit kernels. uAPI v2 addresses that particular issue, and
the problem more generally, by adding pad fields that explicitly pad
structs out to 64-bit boundaries, so they will pack to the same size now,
and even if some of the reserved padding is used for __u64 fields in the
future.
The new structs have been analysed with pahole to ensure that they
are sized as expected and contain no implicit padding.
The lack of future proofing in v1 makes it impossible to, for example,
add the debounce feature that is included in v2.
The future proofing is addressed by providing configurable attributes in
line config and reserved padding in all structs for future features.
Specifically, the line request, config, info, info_changed and event
structs receive updated versions and new ioctls.
As the majority of the structs and ioctls were being replaced, it is
opportune to rework some of the other aspects of the uAPI:
v1 has three different flags fields, each with their own separate
bit definitions. In v2 that is collapsed to one - gpio_v2_line_flag.
The handle and event requests are merged into a single request, the line
request, as the two requests were mostly the same other than the edge
detection provided by event requests. As a byproduct, the v2 uAPI allows
for multiple lines producing edge events on the same line handle.
This is a new capability as v1 only supports a single line in an event
request.
As a consequence, there are now only two types of file handle to be
concerned with, the chip and the line, and it is clearer which ioctls
apply to which type of handle.
There is also some minor renaming of fields for consistency compared to
their v1 counterparts, e.g. offset rather than lineoffset or line_offset,
and consumer rather than consumer_label.
Additionally, v1 GPIOHANDLES_MAX becomes GPIO_V2_LINES_MAX in v2 for
clarity, and the gpiohandle_data __u8 array becomes a bitmap in
gpio_v2_line_values.
The v2 uAPI is mostly a reorganisation and extension of v1, so userspace
code, particularly libgpiod, should readily port to it.
Signed-off-by: Kent Gibson <warthog618@gmail.com>
Reviewed-by: Andy Shevchenko <andy.shevchenko@gmail.com>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
2020-09-28 00:27:51 +00:00
|
|
|
* @offset: the offset of the line that triggered the event
|
|
|
|
* @seqno: the sequence number for this event in the sequence of events for
|
|
|
|
* all the lines in this line request
|
|
|
|
* @line_seqno: the sequence number for this event in the sequence of
|
|
|
|
* events on this particular line
|
|
|
|
* @padding: reserved for future use
|
2020-10-14 23:11:56 +00:00
|
|
|
*
|
|
|
|
* 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.
|
gpio: uapi: define uAPI v2
Add a new version of the uAPI to address existing 32/64-bit alignment
issues, add support for debounce and event sequence numbers, allow
requested lines with different configurations, and provide some future
proofing by adding padding reserved for future use.
The alignment issue relates to the gpioevent_data, which packs to different
sizes on 32-bit and 64-bit platforms. That creates problems for 32-bit apps
running on 64-bit kernels. uAPI v2 addresses that particular issue, and
the problem more generally, by adding pad fields that explicitly pad
structs out to 64-bit boundaries, so they will pack to the same size now,
and even if some of the reserved padding is used for __u64 fields in the
future.
The new structs have been analysed with pahole to ensure that they
are sized as expected and contain no implicit padding.
The lack of future proofing in v1 makes it impossible to, for example,
add the debounce feature that is included in v2.
The future proofing is addressed by providing configurable attributes in
line config and reserved padding in all structs for future features.
Specifically, the line request, config, info, info_changed and event
structs receive updated versions and new ioctls.
As the majority of the structs and ioctls were being replaced, it is
opportune to rework some of the other aspects of the uAPI:
v1 has three different flags fields, each with their own separate
bit definitions. In v2 that is collapsed to one - gpio_v2_line_flag.
The handle and event requests are merged into a single request, the line
request, as the two requests were mostly the same other than the edge
detection provided by event requests. As a byproduct, the v2 uAPI allows
for multiple lines producing edge events on the same line handle.
This is a new capability as v1 only supports a single line in an event
request.
As a consequence, there are now only two types of file handle to be
concerned with, the chip and the line, and it is clearer which ioctls
apply to which type of handle.
There is also some minor renaming of fields for consistency compared to
their v1 counterparts, e.g. offset rather than lineoffset or line_offset,
and consumer rather than consumer_label.
Additionally, v1 GPIOHANDLES_MAX becomes GPIO_V2_LINES_MAX in v2 for
clarity, and the gpiohandle_data __u8 array becomes a bitmap in
gpio_v2_line_values.
The v2 uAPI is mostly a reorganisation and extension of v1, so userspace
code, particularly libgpiod, should readily port to it.
Signed-off-by: Kent Gibson <warthog618@gmail.com>
Reviewed-by: Andy Shevchenko <andy.shevchenko@gmail.com>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
2020-09-28 00:27:51 +00:00
|
|
|
*/
|
|
|
|
struct gpio_v2_line_event {
|
|
|
|
__aligned_u64 timestamp_ns;
|
|
|
|
__u32 id;
|
|
|
|
__u32 offset;
|
|
|
|
__u32 seqno;
|
|
|
|
__u32 line_seqno;
|
|
|
|
/* Space reserved for future use. */
|
|
|
|
__u32 padding[6];
|
|
|
|
};
|
|
|
|
|
|
|
|
/*
|
2020-10-05 07:03:28 +00:00
|
|
|
* ABI v1
|
2020-09-28 00:28:00 +00:00
|
|
|
*
|
|
|
|
* This version of the ABI is deprecated.
|
|
|
|
* Use the latest version of the ABI, defined above, instead.
|
gpio: uapi: define uAPI v2
Add a new version of the uAPI to address existing 32/64-bit alignment
issues, add support for debounce and event sequence numbers, allow
requested lines with different configurations, and provide some future
proofing by adding padding reserved for future use.
The alignment issue relates to the gpioevent_data, which packs to different
sizes on 32-bit and 64-bit platforms. That creates problems for 32-bit apps
running on 64-bit kernels. uAPI v2 addresses that particular issue, and
the problem more generally, by adding pad fields that explicitly pad
structs out to 64-bit boundaries, so they will pack to the same size now,
and even if some of the reserved padding is used for __u64 fields in the
future.
The new structs have been analysed with pahole to ensure that they
are sized as expected and contain no implicit padding.
The lack of future proofing in v1 makes it impossible to, for example,
add the debounce feature that is included in v2.
The future proofing is addressed by providing configurable attributes in
line config and reserved padding in all structs for future features.
Specifically, the line request, config, info, info_changed and event
structs receive updated versions and new ioctls.
As the majority of the structs and ioctls were being replaced, it is
opportune to rework some of the other aspects of the uAPI:
v1 has three different flags fields, each with their own separate
bit definitions. In v2 that is collapsed to one - gpio_v2_line_flag.
The handle and event requests are merged into a single request, the line
request, as the two requests were mostly the same other than the edge
detection provided by event requests. As a byproduct, the v2 uAPI allows
for multiple lines producing edge events on the same line handle.
This is a new capability as v1 only supports a single line in an event
request.
As a consequence, there are now only two types of file handle to be
concerned with, the chip and the line, and it is clearer which ioctls
apply to which type of handle.
There is also some minor renaming of fields for consistency compared to
their v1 counterparts, e.g. offset rather than lineoffset or line_offset,
and consumer rather than consumer_label.
Additionally, v1 GPIOHANDLES_MAX becomes GPIO_V2_LINES_MAX in v2 for
clarity, and the gpiohandle_data __u8 array becomes a bitmap in
gpio_v2_line_values.
The v2 uAPI is mostly a reorganisation and extension of v1, so userspace
code, particularly libgpiod, should readily port to it.
Signed-off-by: Kent Gibson <warthog618@gmail.com>
Reviewed-by: Andy Shevchenko <andy.shevchenko@gmail.com>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
2020-09-28 00:27:51 +00:00
|
|
|
*/
|
|
|
|
|
gpio: userspace ABI for reading/writing GPIO lines
This adds a userspace ABI for reading and writing GPIO lines.
The mechanism returns an anonymous file handle to a request
to read/write n offsets from a gpiochip. This file handle
in turn accepts two ioctl()s: one that reads and one that
writes values to the selected lines.
- Handles can be requested as input/output, active low,
open drain, open source, however when you issue a request
for n lines with GPIO_GET_LINEHANDLE_IOCTL, they must all
have the same flags, i.e. all inputs or all outputs, all
open drain etc. If a granular control of the flags for
each line is desired, they need to be requested
individually, not in a batch.
- The GPIOHANDLE_GET_LINE_VALUES_IOCTL read ioctl() can be
issued also to output lines to verify that the hardware
is in the expected state.
- It reads and writes up to GPIOHANDLES_MAX lines at once,
utilizing the .set_multiple() call in the driver if
possible, making the call efficient if several lines
can be written with a single register update.
The limitation of GPIOHANDLES_MAX to 64 lines is done under
the assumption that we may expect hardware that can issue a
transaction updating 64 bits at an instant but unlikely
anything larger than that.
ChangeLog v2->v3:
- Use gpiod_get_value_cansleep() so we support also slowpath
GPIO drivers.
- Fix up the UAPI docs kerneldoc.
- Allocate the anonymous fd last, so that the release
function don't get called until that point of something
fails. After this point, skip the errorpath.
ChangeLog v1->v2:
- Handle ioctl_compat() properly based on a similar patch
to the other ioctl() handling code.
- Use _IOWR() as we pass pointers both in and out of the
ioctl()
- Use kmalloc() and kfree() for the linehandled, do not
try to be fancy with devm_* it doesn't work the way I
thought.
- Fix const-correctness on the linehandle name field.
Acked-by: Michael Welling <mwelling@ieee.org>
Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
2016-04-26 08:35:29 +00:00
|
|
|
/* Informational flags */
|
|
|
|
#define GPIOLINE_FLAG_KERNEL (1UL << 0) /* Line used by the kernel */
|
2016-02-12 21:25:22 +00:00
|
|
|
#define GPIOLINE_FLAG_IS_OUT (1UL << 1)
|
|
|
|
#define GPIOLINE_FLAG_ACTIVE_LOW (1UL << 2)
|
|
|
|
#define GPIOLINE_FLAG_OPEN_DRAIN (1UL << 3)
|
|
|
|
#define GPIOLINE_FLAG_OPEN_SOURCE (1UL << 4)
|
2019-11-05 02:04:23 +00:00
|
|
|
#define GPIOLINE_FLAG_BIAS_PULL_UP (1UL << 5)
|
|
|
|
#define GPIOLINE_FLAG_BIAS_PULL_DOWN (1UL << 6)
|
2019-11-05 02:04:25 +00:00
|
|
|
#define GPIOLINE_FLAG_BIAS_DISABLE (1UL << 7)
|
2016-02-12 21:25:22 +00:00
|
|
|
|
|
|
|
/**
|
|
|
|
* struct gpioline_info - Information about a certain GPIO line
|
2016-02-25 20:01:48 +00:00
|
|
|
* @line_offset: the local offset on this GPIO device, fill this in when
|
|
|
|
* requesting the line information from the kernel
|
2016-02-12 21:25:22 +00:00
|
|
|
* @flags: various flags for this line
|
2016-02-25 20:01:48 +00:00
|
|
|
* @name: the 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
|
2020-10-05 07:03:29 +00:00
|
|
|
* chip, may be empty (i.e. name[0] == '\0')
|
2016-02-25 20:01:48 +00:00
|
|
|
* @consumer: a functional name for the consumer of this GPIO line as set by
|
2020-03-03 20:01:48 +00:00
|
|
|
* 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
|
2020-09-28 00:28:00 +00:00
|
|
|
*
|
2020-10-05 07:03:27 +00:00
|
|
|
* Note: This struct is part of ABI v1 and is deprecated.
|
|
|
|
* Use &struct gpio_v2_line_info instead.
|
2016-02-12 21:25:22 +00:00
|
|
|
*/
|
|
|
|
struct gpioline_info {
|
|
|
|
__u32 line_offset;
|
|
|
|
__u32 flags;
|
2020-09-28 00:27:50 +00:00
|
|
|
char name[GPIO_MAX_NAME_SIZE];
|
|
|
|
char consumer[GPIO_MAX_NAME_SIZE];
|
2016-02-12 21:25:22 +00:00
|
|
|
};
|
|
|
|
|
gpio: userspace ABI for reading/writing GPIO lines
This adds a userspace ABI for reading and writing GPIO lines.
The mechanism returns an anonymous file handle to a request
to read/write n offsets from a gpiochip. This file handle
in turn accepts two ioctl()s: one that reads and one that
writes values to the selected lines.
- Handles can be requested as input/output, active low,
open drain, open source, however when you issue a request
for n lines with GPIO_GET_LINEHANDLE_IOCTL, they must all
have the same flags, i.e. all inputs or all outputs, all
open drain etc. If a granular control of the flags for
each line is desired, they need to be requested
individually, not in a batch.
- The GPIOHANDLE_GET_LINE_VALUES_IOCTL read ioctl() can be
issued also to output lines to verify that the hardware
is in the expected state.
- It reads and writes up to GPIOHANDLES_MAX lines at once,
utilizing the .set_multiple() call in the driver if
possible, making the call efficient if several lines
can be written with a single register update.
The limitation of GPIOHANDLES_MAX to 64 lines is done under
the assumption that we may expect hardware that can issue a
transaction updating 64 bits at an instant but unlikely
anything larger than that.
ChangeLog v2->v3:
- Use gpiod_get_value_cansleep() so we support also slowpath
GPIO drivers.
- Fix up the UAPI docs kerneldoc.
- Allocate the anonymous fd last, so that the release
function don't get called until that point of something
fails. After this point, skip the errorpath.
ChangeLog v1->v2:
- Handle ioctl_compat() properly based on a similar patch
to the other ioctl() handling code.
- Use _IOWR() as we pass pointers both in and out of the
ioctl()
- Use kmalloc() and kfree() for the linehandled, do not
try to be fancy with devm_* it doesn't work the way I
thought.
- Fix const-correctness on the linehandle name field.
Acked-by: Michael Welling <mwelling@ieee.org>
Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
2016-04-26 08:35:29 +00:00
|
|
|
/* Maximum number of requested handles */
|
|
|
|
#define GPIOHANDLES_MAX 64
|
|
|
|
|
2019-11-22 14:19:21 +00:00
|
|
|
/* Possible line status change events */
|
|
|
|
enum {
|
|
|
|
GPIOLINE_CHANGED_REQUESTED = 1,
|
|
|
|
GPIOLINE_CHANGED_RELEASED,
|
|
|
|
GPIOLINE_CHANGED_CONFIG,
|
|
|
|
};
|
|
|
|
|
|
|
|
/**
|
|
|
|
* struct gpioline_info_changed - Information about a change in status
|
|
|
|
* of a GPIO line
|
|
|
|
* @info: updated line information
|
|
|
|
* @timestamp: estimate of time of status change occurrence, in nanoseconds
|
2020-10-05 07:03:27 +00:00
|
|
|
* @event_type: one of %GPIOLINE_CHANGED_REQUESTED,
|
|
|
|
* %GPIOLINE_CHANGED_RELEASED and %GPIOLINE_CHANGED_CONFIG
|
2020-10-05 07:03:25 +00:00
|
|
|
* @padding: reserved for future use
|
2019-11-22 14:19:21 +00:00
|
|
|
*
|
2020-10-05 07:03:27 +00:00
|
|
|
* The &struct gpioline_info embedded here has 32-bit alignment on its own,
|
2019-11-22 14:19:21 +00:00
|
|
|
* but it works fine with 64-bit alignment too. With its 72 byte size, we can
|
|
|
|
* guarantee there are no implicit holes between it and subsequent members.
|
|
|
|
* The 20-byte padding at the end makes sure we don't add any implicit padding
|
|
|
|
* at the end of the structure on 64-bit architectures.
|
2020-09-28 00:28:00 +00:00
|
|
|
*
|
2020-10-05 07:03:27 +00:00
|
|
|
* Note: This struct is part of ABI v1 and is deprecated.
|
|
|
|
* Use &struct gpio_v2_line_info_changed instead.
|
2019-11-22 14:19:21 +00:00
|
|
|
*/
|
|
|
|
struct gpioline_info_changed {
|
|
|
|
struct gpioline_info info;
|
|
|
|
__u64 timestamp;
|
|
|
|
__u32 event_type;
|
|
|
|
__u32 padding[5]; /* for future use */
|
|
|
|
};
|
|
|
|
|
2016-06-02 09:30:15 +00:00
|
|
|
/* Linerequest flags */
|
gpio: userspace ABI for reading/writing GPIO lines
This adds a userspace ABI for reading and writing GPIO lines.
The mechanism returns an anonymous file handle to a request
to read/write n offsets from a gpiochip. This file handle
in turn accepts two ioctl()s: one that reads and one that
writes values to the selected lines.
- Handles can be requested as input/output, active low,
open drain, open source, however when you issue a request
for n lines with GPIO_GET_LINEHANDLE_IOCTL, they must all
have the same flags, i.e. all inputs or all outputs, all
open drain etc. If a granular control of the flags for
each line is desired, they need to be requested
individually, not in a batch.
- The GPIOHANDLE_GET_LINE_VALUES_IOCTL read ioctl() can be
issued also to output lines to verify that the hardware
is in the expected state.
- It reads and writes up to GPIOHANDLES_MAX lines at once,
utilizing the .set_multiple() call in the driver if
possible, making the call efficient if several lines
can be written with a single register update.
The limitation of GPIOHANDLES_MAX to 64 lines is done under
the assumption that we may expect hardware that can issue a
transaction updating 64 bits at an instant but unlikely
anything larger than that.
ChangeLog v2->v3:
- Use gpiod_get_value_cansleep() so we support also slowpath
GPIO drivers.
- Fix up the UAPI docs kerneldoc.
- Allocate the anonymous fd last, so that the release
function don't get called until that point of something
fails. After this point, skip the errorpath.
ChangeLog v1->v2:
- Handle ioctl_compat() properly based on a similar patch
to the other ioctl() handling code.
- Use _IOWR() as we pass pointers both in and out of the
ioctl()
- Use kmalloc() and kfree() for the linehandled, do not
try to be fancy with devm_* it doesn't work the way I
thought.
- Fix const-correctness on the linehandle name field.
Acked-by: Michael Welling <mwelling@ieee.org>
Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
2016-04-26 08:35:29 +00:00
|
|
|
#define GPIOHANDLE_REQUEST_INPUT (1UL << 0)
|
|
|
|
#define GPIOHANDLE_REQUEST_OUTPUT (1UL << 1)
|
|
|
|
#define GPIOHANDLE_REQUEST_ACTIVE_LOW (1UL << 2)
|
|
|
|
#define GPIOHANDLE_REQUEST_OPEN_DRAIN (1UL << 3)
|
|
|
|
#define GPIOHANDLE_REQUEST_OPEN_SOURCE (1UL << 4)
|
2019-11-05 02:04:23 +00:00
|
|
|
#define GPIOHANDLE_REQUEST_BIAS_PULL_UP (1UL << 5)
|
|
|
|
#define GPIOHANDLE_REQUEST_BIAS_PULL_DOWN (1UL << 6)
|
2019-11-05 02:04:25 +00:00
|
|
|
#define GPIOHANDLE_REQUEST_BIAS_DISABLE (1UL << 7)
|
gpio: userspace ABI for reading/writing GPIO lines
This adds a userspace ABI for reading and writing GPIO lines.
The mechanism returns an anonymous file handle to a request
to read/write n offsets from a gpiochip. This file handle
in turn accepts two ioctl()s: one that reads and one that
writes values to the selected lines.
- Handles can be requested as input/output, active low,
open drain, open source, however when you issue a request
for n lines with GPIO_GET_LINEHANDLE_IOCTL, they must all
have the same flags, i.e. all inputs or all outputs, all
open drain etc. If a granular control of the flags for
each line is desired, they need to be requested
individually, not in a batch.
- The GPIOHANDLE_GET_LINE_VALUES_IOCTL read ioctl() can be
issued also to output lines to verify that the hardware
is in the expected state.
- It reads and writes up to GPIOHANDLES_MAX lines at once,
utilizing the .set_multiple() call in the driver if
possible, making the call efficient if several lines
can be written with a single register update.
The limitation of GPIOHANDLES_MAX to 64 lines is done under
the assumption that we may expect hardware that can issue a
transaction updating 64 bits at an instant but unlikely
anything larger than that.
ChangeLog v2->v3:
- Use gpiod_get_value_cansleep() so we support also slowpath
GPIO drivers.
- Fix up the UAPI docs kerneldoc.
- Allocate the anonymous fd last, so that the release
function don't get called until that point of something
fails. After this point, skip the errorpath.
ChangeLog v1->v2:
- Handle ioctl_compat() properly based on a similar patch
to the other ioctl() handling code.
- Use _IOWR() as we pass pointers both in and out of the
ioctl()
- Use kmalloc() and kfree() for the linehandled, do not
try to be fancy with devm_* it doesn't work the way I
thought.
- Fix const-correctness on the linehandle name field.
Acked-by: Michael Welling <mwelling@ieee.org>
Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
2016-04-26 08:35:29 +00:00
|
|
|
|
|
|
|
/**
|
|
|
|
* struct gpiohandle_request - Information about a GPIO handle request
|
2018-09-11 14:32:43 +00:00
|
|
|
* @lineoffsets: an array of desired lines, specified by offset index for the
|
gpio: userspace ABI for reading/writing GPIO lines
This adds a userspace ABI for reading and writing GPIO lines.
The mechanism returns an anonymous file handle to a request
to read/write n offsets from a gpiochip. This file handle
in turn accepts two ioctl()s: one that reads and one that
writes values to the selected lines.
- Handles can be requested as input/output, active low,
open drain, open source, however when you issue a request
for n lines with GPIO_GET_LINEHANDLE_IOCTL, they must all
have the same flags, i.e. all inputs or all outputs, all
open drain etc. If a granular control of the flags for
each line is desired, they need to be requested
individually, not in a batch.
- The GPIOHANDLE_GET_LINE_VALUES_IOCTL read ioctl() can be
issued also to output lines to verify that the hardware
is in the expected state.
- It reads and writes up to GPIOHANDLES_MAX lines at once,
utilizing the .set_multiple() call in the driver if
possible, making the call efficient if several lines
can be written with a single register update.
The limitation of GPIOHANDLES_MAX to 64 lines is done under
the assumption that we may expect hardware that can issue a
transaction updating 64 bits at an instant but unlikely
anything larger than that.
ChangeLog v2->v3:
- Use gpiod_get_value_cansleep() so we support also slowpath
GPIO drivers.
- Fix up the UAPI docs kerneldoc.
- Allocate the anonymous fd last, so that the release
function don't get called until that point of something
fails. After this point, skip the errorpath.
ChangeLog v1->v2:
- Handle ioctl_compat() properly based on a similar patch
to the other ioctl() handling code.
- Use _IOWR() as we pass pointers both in and out of the
ioctl()
- Use kmalloc() and kfree() for the linehandled, do not
try to be fancy with devm_* it doesn't work the way I
thought.
- Fix const-correctness on the linehandle name field.
Acked-by: Michael Welling <mwelling@ieee.org>
Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
2016-04-26 08:35:29 +00:00
|
|
|
* associated GPIO device
|
|
|
|
* @flags: desired flags for the desired GPIO lines, such as
|
2020-10-05 07:03:27 +00:00
|
|
|
* %GPIOHANDLE_REQUEST_OUTPUT, %GPIOHANDLE_REQUEST_ACTIVE_LOW etc, added
|
gpio: userspace ABI for reading/writing GPIO lines
This adds a userspace ABI for reading and writing GPIO lines.
The mechanism returns an anonymous file handle to a request
to read/write n offsets from a gpiochip. This file handle
in turn accepts two ioctl()s: one that reads and one that
writes values to the selected lines.
- Handles can be requested as input/output, active low,
open drain, open source, however when you issue a request
for n lines with GPIO_GET_LINEHANDLE_IOCTL, they must all
have the same flags, i.e. all inputs or all outputs, all
open drain etc. If a granular control of the flags for
each line is desired, they need to be requested
individually, not in a batch.
- The GPIOHANDLE_GET_LINE_VALUES_IOCTL read ioctl() can be
issued also to output lines to verify that the hardware
is in the expected state.
- It reads and writes up to GPIOHANDLES_MAX lines at once,
utilizing the .set_multiple() call in the driver if
possible, making the call efficient if several lines
can be written with a single register update.
The limitation of GPIOHANDLES_MAX to 64 lines is done under
the assumption that we may expect hardware that can issue a
transaction updating 64 bits at an instant but unlikely
anything larger than that.
ChangeLog v2->v3:
- Use gpiod_get_value_cansleep() so we support also slowpath
GPIO drivers.
- Fix up the UAPI docs kerneldoc.
- Allocate the anonymous fd last, so that the release
function don't get called until that point of something
fails. After this point, skip the errorpath.
ChangeLog v1->v2:
- Handle ioctl_compat() properly based on a similar patch
to the other ioctl() handling code.
- Use _IOWR() as we pass pointers both in and out of the
ioctl()
- Use kmalloc() and kfree() for the linehandled, do not
try to be fancy with devm_* it doesn't work the way I
thought.
- Fix const-correctness on the linehandle name field.
Acked-by: Michael Welling <mwelling@ieee.org>
Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
2016-04-26 08:35:29 +00:00
|
|
|
* together. Note that even if multiple lines are requested, the same flags
|
|
|
|
* must be applicable to all of them, if you want lines with individual
|
|
|
|
* flags set, request them one by one. It is possible to select
|
|
|
|
* a batch of input or output lines, but they must all have the same
|
|
|
|
* characteristics, i.e. all inputs or all outputs, all active low etc
|
2020-10-05 07:03:27 +00:00
|
|
|
* @default_values: if the %GPIOHANDLE_REQUEST_OUTPUT is set for a requested
|
gpio: userspace ABI for reading/writing GPIO lines
This adds a userspace ABI for reading and writing GPIO lines.
The mechanism returns an anonymous file handle to a request
to read/write n offsets from a gpiochip. This file handle
in turn accepts two ioctl()s: one that reads and one that
writes values to the selected lines.
- Handles can be requested as input/output, active low,
open drain, open source, however when you issue a request
for n lines with GPIO_GET_LINEHANDLE_IOCTL, they must all
have the same flags, i.e. all inputs or all outputs, all
open drain etc. If a granular control of the flags for
each line is desired, they need to be requested
individually, not in a batch.
- The GPIOHANDLE_GET_LINE_VALUES_IOCTL read ioctl() can be
issued also to output lines to verify that the hardware
is in the expected state.
- It reads and writes up to GPIOHANDLES_MAX lines at once,
utilizing the .set_multiple() call in the driver if
possible, making the call efficient if several lines
can be written with a single register update.
The limitation of GPIOHANDLES_MAX to 64 lines is done under
the assumption that we may expect hardware that can issue a
transaction updating 64 bits at an instant but unlikely
anything larger than that.
ChangeLog v2->v3:
- Use gpiod_get_value_cansleep() so we support also slowpath
GPIO drivers.
- Fix up the UAPI docs kerneldoc.
- Allocate the anonymous fd last, so that the release
function don't get called until that point of something
fails. After this point, skip the errorpath.
ChangeLog v1->v2:
- Handle ioctl_compat() properly based on a similar patch
to the other ioctl() handling code.
- Use _IOWR() as we pass pointers both in and out of the
ioctl()
- Use kmalloc() and kfree() for the linehandled, do not
try to be fancy with devm_* it doesn't work the way I
thought.
- Fix const-correctness on the linehandle name field.
Acked-by: Michael Welling <mwelling@ieee.org>
Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
2016-04-26 08:35:29 +00:00
|
|
|
* line, this specifies the default output value, should be 0 (low) or
|
|
|
|
* 1 (high), anything else than 0 or 1 will be interpreted as 1 (high)
|
|
|
|
* @consumer_label: a desired consumer label for the selected GPIO line(s)
|
|
|
|
* such as "my-bitbanged-relay"
|
|
|
|
* @lines: number of lines requested in this request, i.e. the number of
|
|
|
|
* valid fields in the above arrays, set to 1 to request a single line
|
|
|
|
* @fd: if successful this field will contain a valid anonymous file handle
|
2020-10-05 07:03:27 +00:00
|
|
|
* after a %GPIO_GET_LINEHANDLE_IOCTL operation, zero or negative value
|
gpio: userspace ABI for reading/writing GPIO lines
This adds a userspace ABI for reading and writing GPIO lines.
The mechanism returns an anonymous file handle to a request
to read/write n offsets from a gpiochip. This file handle
in turn accepts two ioctl()s: one that reads and one that
writes values to the selected lines.
- Handles can be requested as input/output, active low,
open drain, open source, however when you issue a request
for n lines with GPIO_GET_LINEHANDLE_IOCTL, they must all
have the same flags, i.e. all inputs or all outputs, all
open drain etc. If a granular control of the flags for
each line is desired, they need to be requested
individually, not in a batch.
- The GPIOHANDLE_GET_LINE_VALUES_IOCTL read ioctl() can be
issued also to output lines to verify that the hardware
is in the expected state.
- It reads and writes up to GPIOHANDLES_MAX lines at once,
utilizing the .set_multiple() call in the driver if
possible, making the call efficient if several lines
can be written with a single register update.
The limitation of GPIOHANDLES_MAX to 64 lines is done under
the assumption that we may expect hardware that can issue a
transaction updating 64 bits at an instant but unlikely
anything larger than that.
ChangeLog v2->v3:
- Use gpiod_get_value_cansleep() so we support also slowpath
GPIO drivers.
- Fix up the UAPI docs kerneldoc.
- Allocate the anonymous fd last, so that the release
function don't get called until that point of something
fails. After this point, skip the errorpath.
ChangeLog v1->v2:
- Handle ioctl_compat() properly based on a similar patch
to the other ioctl() handling code.
- Use _IOWR() as we pass pointers both in and out of the
ioctl()
- Use kmalloc() and kfree() for the linehandled, do not
try to be fancy with devm_* it doesn't work the way I
thought.
- Fix const-correctness on the linehandle name field.
Acked-by: Michael Welling <mwelling@ieee.org>
Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
2016-04-26 08:35:29 +00:00
|
|
|
* means error
|
2020-09-28 00:28:00 +00:00
|
|
|
*
|
2020-10-05 07:03:27 +00:00
|
|
|
* Note: This struct is part of ABI v1 and is deprecated.
|
|
|
|
* Use &struct gpio_v2_line_request instead.
|
gpio: userspace ABI for reading/writing GPIO lines
This adds a userspace ABI for reading and writing GPIO lines.
The mechanism returns an anonymous file handle to a request
to read/write n offsets from a gpiochip. This file handle
in turn accepts two ioctl()s: one that reads and one that
writes values to the selected lines.
- Handles can be requested as input/output, active low,
open drain, open source, however when you issue a request
for n lines with GPIO_GET_LINEHANDLE_IOCTL, they must all
have the same flags, i.e. all inputs or all outputs, all
open drain etc. If a granular control of the flags for
each line is desired, they need to be requested
individually, not in a batch.
- The GPIOHANDLE_GET_LINE_VALUES_IOCTL read ioctl() can be
issued also to output lines to verify that the hardware
is in the expected state.
- It reads and writes up to GPIOHANDLES_MAX lines at once,
utilizing the .set_multiple() call in the driver if
possible, making the call efficient if several lines
can be written with a single register update.
The limitation of GPIOHANDLES_MAX to 64 lines is done under
the assumption that we may expect hardware that can issue a
transaction updating 64 bits at an instant but unlikely
anything larger than that.
ChangeLog v2->v3:
- Use gpiod_get_value_cansleep() so we support also slowpath
GPIO drivers.
- Fix up the UAPI docs kerneldoc.
- Allocate the anonymous fd last, so that the release
function don't get called until that point of something
fails. After this point, skip the errorpath.
ChangeLog v1->v2:
- Handle ioctl_compat() properly based on a similar patch
to the other ioctl() handling code.
- Use _IOWR() as we pass pointers both in and out of the
ioctl()
- Use kmalloc() and kfree() for the linehandled, do not
try to be fancy with devm_* it doesn't work the way I
thought.
- Fix const-correctness on the linehandle name field.
Acked-by: Michael Welling <mwelling@ieee.org>
Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
2016-04-26 08:35:29 +00:00
|
|
|
*/
|
|
|
|
struct gpiohandle_request {
|
|
|
|
__u32 lineoffsets[GPIOHANDLES_MAX];
|
|
|
|
__u32 flags;
|
|
|
|
__u8 default_values[GPIOHANDLES_MAX];
|
2020-09-28 00:27:50 +00:00
|
|
|
char consumer_label[GPIO_MAX_NAME_SIZE];
|
gpio: userspace ABI for reading/writing GPIO lines
This adds a userspace ABI for reading and writing GPIO lines.
The mechanism returns an anonymous file handle to a request
to read/write n offsets from a gpiochip. This file handle
in turn accepts two ioctl()s: one that reads and one that
writes values to the selected lines.
- Handles can be requested as input/output, active low,
open drain, open source, however when you issue a request
for n lines with GPIO_GET_LINEHANDLE_IOCTL, they must all
have the same flags, i.e. all inputs or all outputs, all
open drain etc. If a granular control of the flags for
each line is desired, they need to be requested
individually, not in a batch.
- The GPIOHANDLE_GET_LINE_VALUES_IOCTL read ioctl() can be
issued also to output lines to verify that the hardware
is in the expected state.
- It reads and writes up to GPIOHANDLES_MAX lines at once,
utilizing the .set_multiple() call in the driver if
possible, making the call efficient if several lines
can be written with a single register update.
The limitation of GPIOHANDLES_MAX to 64 lines is done under
the assumption that we may expect hardware that can issue a
transaction updating 64 bits at an instant but unlikely
anything larger than that.
ChangeLog v2->v3:
- Use gpiod_get_value_cansleep() so we support also slowpath
GPIO drivers.
- Fix up the UAPI docs kerneldoc.
- Allocate the anonymous fd last, so that the release
function don't get called until that point of something
fails. After this point, skip the errorpath.
ChangeLog v1->v2:
- Handle ioctl_compat() properly based on a similar patch
to the other ioctl() handling code.
- Use _IOWR() as we pass pointers both in and out of the
ioctl()
- Use kmalloc() and kfree() for the linehandled, do not
try to be fancy with devm_* it doesn't work the way I
thought.
- Fix const-correctness on the linehandle name field.
Acked-by: Michael Welling <mwelling@ieee.org>
Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
2016-04-26 08:35:29 +00:00
|
|
|
__u32 lines;
|
|
|
|
int fd;
|
|
|
|
};
|
|
|
|
|
2019-11-05 02:04:29 +00:00
|
|
|
/**
|
|
|
|
* struct gpiohandle_config - Configuration for a GPIO handle request
|
|
|
|
* @flags: updated flags for the requested GPIO lines, such as
|
2020-10-05 07:03:27 +00:00
|
|
|
* %GPIOHANDLE_REQUEST_OUTPUT, %GPIOHANDLE_REQUEST_ACTIVE_LOW etc, added
|
2019-11-05 02:04:29 +00:00
|
|
|
* together
|
2020-10-05 07:03:27 +00:00
|
|
|
* @default_values: if the %GPIOHANDLE_REQUEST_OUTPUT is set in flags,
|
2019-11-05 02:04:29 +00:00
|
|
|
* this specifies the default output value, should be 0 (low) or
|
|
|
|
* 1 (high), anything else than 0 or 1 will be interpreted as 1 (high)
|
|
|
|
* @padding: reserved for future use and should be zero filled
|
2020-09-28 00:28:00 +00:00
|
|
|
*
|
2020-10-05 07:03:27 +00:00
|
|
|
* Note: This struct is part of ABI v1 and is deprecated.
|
|
|
|
* Use &struct gpio_v2_line_config instead.
|
2019-11-05 02:04:29 +00:00
|
|
|
*/
|
|
|
|
struct gpiohandle_config {
|
|
|
|
__u32 flags;
|
|
|
|
__u8 default_values[GPIOHANDLES_MAX];
|
|
|
|
__u32 padding[4]; /* padding for future use */
|
|
|
|
};
|
|
|
|
|
gpio: userspace ABI for reading/writing GPIO lines
This adds a userspace ABI for reading and writing GPIO lines.
The mechanism returns an anonymous file handle to a request
to read/write n offsets from a gpiochip. This file handle
in turn accepts two ioctl()s: one that reads and one that
writes values to the selected lines.
- Handles can be requested as input/output, active low,
open drain, open source, however when you issue a request
for n lines with GPIO_GET_LINEHANDLE_IOCTL, they must all
have the same flags, i.e. all inputs or all outputs, all
open drain etc. If a granular control of the flags for
each line is desired, they need to be requested
individually, not in a batch.
- The GPIOHANDLE_GET_LINE_VALUES_IOCTL read ioctl() can be
issued also to output lines to verify that the hardware
is in the expected state.
- It reads and writes up to GPIOHANDLES_MAX lines at once,
utilizing the .set_multiple() call in the driver if
possible, making the call efficient if several lines
can be written with a single register update.
The limitation of GPIOHANDLES_MAX to 64 lines is done under
the assumption that we may expect hardware that can issue a
transaction updating 64 bits at an instant but unlikely
anything larger than that.
ChangeLog v2->v3:
- Use gpiod_get_value_cansleep() so we support also slowpath
GPIO drivers.
- Fix up the UAPI docs kerneldoc.
- Allocate the anonymous fd last, so that the release
function don't get called until that point of something
fails. After this point, skip the errorpath.
ChangeLog v1->v2:
- Handle ioctl_compat() properly based on a similar patch
to the other ioctl() handling code.
- Use _IOWR() as we pass pointers both in and out of the
ioctl()
- Use kmalloc() and kfree() for the linehandled, do not
try to be fancy with devm_* it doesn't work the way I
thought.
- Fix const-correctness on the linehandle name field.
Acked-by: Michael Welling <mwelling@ieee.org>
Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
2016-04-26 08:35:29 +00:00
|
|
|
/**
|
|
|
|
* struct gpiohandle_data - Information of values on a GPIO handle
|
|
|
|
* @values: when getting the state of lines this contains the current
|
|
|
|
* state of a line, when setting the state of lines these should contain
|
|
|
|
* the desired target state
|
2020-09-28 00:28:00 +00:00
|
|
|
*
|
2020-10-05 07:03:27 +00:00
|
|
|
* Note: This struct is part of ABI v1 and is deprecated.
|
|
|
|
* Use &struct gpio_v2_line_values instead.
|
gpio: userspace ABI for reading/writing GPIO lines
This adds a userspace ABI for reading and writing GPIO lines.
The mechanism returns an anonymous file handle to a request
to read/write n offsets from a gpiochip. This file handle
in turn accepts two ioctl()s: one that reads and one that
writes values to the selected lines.
- Handles can be requested as input/output, active low,
open drain, open source, however when you issue a request
for n lines with GPIO_GET_LINEHANDLE_IOCTL, they must all
have the same flags, i.e. all inputs or all outputs, all
open drain etc. If a granular control of the flags for
each line is desired, they need to be requested
individually, not in a batch.
- The GPIOHANDLE_GET_LINE_VALUES_IOCTL read ioctl() can be
issued also to output lines to verify that the hardware
is in the expected state.
- It reads and writes up to GPIOHANDLES_MAX lines at once,
utilizing the .set_multiple() call in the driver if
possible, making the call efficient if several lines
can be written with a single register update.
The limitation of GPIOHANDLES_MAX to 64 lines is done under
the assumption that we may expect hardware that can issue a
transaction updating 64 bits at an instant but unlikely
anything larger than that.
ChangeLog v2->v3:
- Use gpiod_get_value_cansleep() so we support also slowpath
GPIO drivers.
- Fix up the UAPI docs kerneldoc.
- Allocate the anonymous fd last, so that the release
function don't get called until that point of something
fails. After this point, skip the errorpath.
ChangeLog v1->v2:
- Handle ioctl_compat() properly based on a similar patch
to the other ioctl() handling code.
- Use _IOWR() as we pass pointers both in and out of the
ioctl()
- Use kmalloc() and kfree() for the linehandled, do not
try to be fancy with devm_* it doesn't work the way I
thought.
- Fix const-correctness on the linehandle name field.
Acked-by: Michael Welling <mwelling@ieee.org>
Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
2016-04-26 08:35:29 +00:00
|
|
|
*/
|
|
|
|
struct gpiohandle_data {
|
|
|
|
__u8 values[GPIOHANDLES_MAX];
|
|
|
|
};
|
|
|
|
|
2016-06-02 09:30:15 +00:00
|
|
|
/* Eventrequest flags */
|
|
|
|
#define GPIOEVENT_REQUEST_RISING_EDGE (1UL << 0)
|
|
|
|
#define GPIOEVENT_REQUEST_FALLING_EDGE (1UL << 1)
|
|
|
|
#define GPIOEVENT_REQUEST_BOTH_EDGES ((1UL << 0) | (1UL << 1))
|
|
|
|
|
|
|
|
/**
|
|
|
|
* struct gpioevent_request - Information about a GPIO event request
|
|
|
|
* @lineoffset: the desired line to subscribe to events from, specified by
|
|
|
|
* offset index for the associated GPIO device
|
|
|
|
* @handleflags: desired handle flags for the desired GPIO line, such as
|
2020-10-05 07:03:27 +00:00
|
|
|
* %GPIOHANDLE_REQUEST_ACTIVE_LOW or %GPIOHANDLE_REQUEST_OPEN_DRAIN
|
2016-06-02 09:30:15 +00:00
|
|
|
* @eventflags: desired flags for the desired GPIO event line, such as
|
2020-10-05 07:03:27 +00:00
|
|
|
* %GPIOEVENT_REQUEST_RISING_EDGE or %GPIOEVENT_REQUEST_FALLING_EDGE
|
2016-06-02 09:30:15 +00:00
|
|
|
* @consumer_label: a desired consumer label for the selected GPIO line(s)
|
|
|
|
* such as "my-listener"
|
|
|
|
* @fd: if successful this field will contain a valid anonymous file handle
|
2020-10-05 07:03:27 +00:00
|
|
|
* after a %GPIO_GET_LINEEVENT_IOCTL operation, zero or negative value
|
2016-06-02 09:30:15 +00:00
|
|
|
* means error
|
2020-09-28 00:28:00 +00:00
|
|
|
*
|
2020-10-05 07:03:27 +00:00
|
|
|
* Note: This struct is part of ABI v1 and is deprecated.
|
|
|
|
* Use &struct gpio_v2_line_request instead.
|
2016-06-02 09:30:15 +00:00
|
|
|
*/
|
|
|
|
struct gpioevent_request {
|
|
|
|
__u32 lineoffset;
|
|
|
|
__u32 handleflags;
|
|
|
|
__u32 eventflags;
|
2020-09-28 00:27:50 +00:00
|
|
|
char consumer_label[GPIO_MAX_NAME_SIZE];
|
2016-06-02 09:30:15 +00:00
|
|
|
int fd;
|
|
|
|
};
|
|
|
|
|
2020-10-05 07:03:25 +00:00
|
|
|
/*
|
2016-06-02 09:30:15 +00:00
|
|
|
* GPIO event types
|
|
|
|
*/
|
|
|
|
#define GPIOEVENT_EVENT_RISING_EDGE 0x01
|
|
|
|
#define GPIOEVENT_EVENT_FALLING_EDGE 0x02
|
|
|
|
|
|
|
|
/**
|
|
|
|
* struct gpioevent_data - The actual event being pushed to userspace
|
|
|
|
* @timestamp: best estimate of time of event occurrence, in nanoseconds
|
|
|
|
* @id: event identifier
|
2020-09-28 00:28:00 +00:00
|
|
|
*
|
2020-10-05 07:03:27 +00:00
|
|
|
* Note: This struct is part of ABI v1 and is deprecated.
|
|
|
|
* Use &struct gpio_v2_line_event instead.
|
2016-06-02 09:30:15 +00:00
|
|
|
*/
|
|
|
|
struct gpioevent_data {
|
|
|
|
__u64 timestamp;
|
|
|
|
__u32 id;
|
|
|
|
};
|
|
|
|
|
gpio: uapi: define uAPI v2
Add a new version of the uAPI to address existing 32/64-bit alignment
issues, add support for debounce and event sequence numbers, allow
requested lines with different configurations, and provide some future
proofing by adding padding reserved for future use.
The alignment issue relates to the gpioevent_data, which packs to different
sizes on 32-bit and 64-bit platforms. That creates problems for 32-bit apps
running on 64-bit kernels. uAPI v2 addresses that particular issue, and
the problem more generally, by adding pad fields that explicitly pad
structs out to 64-bit boundaries, so they will pack to the same size now,
and even if some of the reserved padding is used for __u64 fields in the
future.
The new structs have been analysed with pahole to ensure that they
are sized as expected and contain no implicit padding.
The lack of future proofing in v1 makes it impossible to, for example,
add the debounce feature that is included in v2.
The future proofing is addressed by providing configurable attributes in
line config and reserved padding in all structs for future features.
Specifically, the line request, config, info, info_changed and event
structs receive updated versions and new ioctls.
As the majority of the structs and ioctls were being replaced, it is
opportune to rework some of the other aspects of the uAPI:
v1 has three different flags fields, each with their own separate
bit definitions. In v2 that is collapsed to one - gpio_v2_line_flag.
The handle and event requests are merged into a single request, the line
request, as the two requests were mostly the same other than the edge
detection provided by event requests. As a byproduct, the v2 uAPI allows
for multiple lines producing edge events on the same line handle.
This is a new capability as v1 only supports a single line in an event
request.
As a consequence, there are now only two types of file handle to be
concerned with, the chip and the line, and it is clearer which ioctls
apply to which type of handle.
There is also some minor renaming of fields for consistency compared to
their v1 counterparts, e.g. offset rather than lineoffset or line_offset,
and consumer rather than consumer_label.
Additionally, v1 GPIOHANDLES_MAX becomes GPIO_V2_LINES_MAX in v2 for
clarity, and the gpiohandle_data __u8 array becomes a bitmap in
gpio_v2_line_values.
The v2 uAPI is mostly a reorganisation and extension of v1, so userspace
code, particularly libgpiod, should readily port to it.
Signed-off-by: Kent Gibson <warthog618@gmail.com>
Reviewed-by: Andy Shevchenko <andy.shevchenko@gmail.com>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
2020-09-28 00:27:51 +00:00
|
|
|
/*
|
|
|
|
* v1 and v2 ioctl()s
|
|
|
|
*/
|
2016-06-02 09:30:15 +00:00
|
|
|
#define GPIO_GET_CHIPINFO_IOCTL _IOR(0xB4, 0x01, struct gpiochip_info)
|
gpio: uapi: define uAPI v2
Add a new version of the uAPI to address existing 32/64-bit alignment
issues, add support for debounce and event sequence numbers, allow
requested lines with different configurations, and provide some future
proofing by adding padding reserved for future use.
The alignment issue relates to the gpioevent_data, which packs to different
sizes on 32-bit and 64-bit platforms. That creates problems for 32-bit apps
running on 64-bit kernels. uAPI v2 addresses that particular issue, and
the problem more generally, by adding pad fields that explicitly pad
structs out to 64-bit boundaries, so they will pack to the same size now,
and even if some of the reserved padding is used for __u64 fields in the
future.
The new structs have been analysed with pahole to ensure that they
are sized as expected and contain no implicit padding.
The lack of future proofing in v1 makes it impossible to, for example,
add the debounce feature that is included in v2.
The future proofing is addressed by providing configurable attributes in
line config and reserved padding in all structs for future features.
Specifically, the line request, config, info, info_changed and event
structs receive updated versions and new ioctls.
As the majority of the structs and ioctls were being replaced, it is
opportune to rework some of the other aspects of the uAPI:
v1 has three different flags fields, each with their own separate
bit definitions. In v2 that is collapsed to one - gpio_v2_line_flag.
The handle and event requests are merged into a single request, the line
request, as the two requests were mostly the same other than the edge
detection provided by event requests. As a byproduct, the v2 uAPI allows
for multiple lines producing edge events on the same line handle.
This is a new capability as v1 only supports a single line in an event
request.
As a consequence, there are now only two types of file handle to be
concerned with, the chip and the line, and it is clearer which ioctls
apply to which type of handle.
There is also some minor renaming of fields for consistency compared to
their v1 counterparts, e.g. offset rather than lineoffset or line_offset,
and consumer rather than consumer_label.
Additionally, v1 GPIOHANDLES_MAX becomes GPIO_V2_LINES_MAX in v2 for
clarity, and the gpiohandle_data __u8 array becomes a bitmap in
gpio_v2_line_values.
The v2 uAPI is mostly a reorganisation and extension of v1, so userspace
code, particularly libgpiod, should readily port to it.
Signed-off-by: Kent Gibson <warthog618@gmail.com>
Reviewed-by: Andy Shevchenko <andy.shevchenko@gmail.com>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
2020-09-28 00:27:51 +00:00
|
|
|
#define GPIO_GET_LINEINFO_UNWATCH_IOCTL _IOWR(0xB4, 0x0C, __u32)
|
|
|
|
|
|
|
|
/*
|
|
|
|
* v2 ioctl()s
|
|
|
|
*/
|
|
|
|
#define GPIO_V2_GET_LINEINFO_IOCTL _IOWR(0xB4, 0x05, struct gpio_v2_line_info)
|
|
|
|
#define GPIO_V2_GET_LINEINFO_WATCH_IOCTL _IOWR(0xB4, 0x06, struct gpio_v2_line_info)
|
|
|
|
#define GPIO_V2_GET_LINE_IOCTL _IOWR(0xB4, 0x07, struct gpio_v2_line_request)
|
|
|
|
#define GPIO_V2_LINE_SET_CONFIG_IOCTL _IOWR(0xB4, 0x0D, struct gpio_v2_line_config)
|
|
|
|
#define GPIO_V2_LINE_GET_VALUES_IOCTL _IOWR(0xB4, 0x0E, struct gpio_v2_line_values)
|
|
|
|
#define GPIO_V2_LINE_SET_VALUES_IOCTL _IOWR(0xB4, 0x0F, struct gpio_v2_line_values)
|
|
|
|
|
|
|
|
/*
|
|
|
|
* v1 ioctl()s
|
2020-09-28 00:28:00 +00:00
|
|
|
*
|
|
|
|
* These ioctl()s are deprecated. Use the v2 equivalent instead.
|
gpio: uapi: define uAPI v2
Add a new version of the uAPI to address existing 32/64-bit alignment
issues, add support for debounce and event sequence numbers, allow
requested lines with different configurations, and provide some future
proofing by adding padding reserved for future use.
The alignment issue relates to the gpioevent_data, which packs to different
sizes on 32-bit and 64-bit platforms. That creates problems for 32-bit apps
running on 64-bit kernels. uAPI v2 addresses that particular issue, and
the problem more generally, by adding pad fields that explicitly pad
structs out to 64-bit boundaries, so they will pack to the same size now,
and even if some of the reserved padding is used for __u64 fields in the
future.
The new structs have been analysed with pahole to ensure that they
are sized as expected and contain no implicit padding.
The lack of future proofing in v1 makes it impossible to, for example,
add the debounce feature that is included in v2.
The future proofing is addressed by providing configurable attributes in
line config and reserved padding in all structs for future features.
Specifically, the line request, config, info, info_changed and event
structs receive updated versions and new ioctls.
As the majority of the structs and ioctls were being replaced, it is
opportune to rework some of the other aspects of the uAPI:
v1 has three different flags fields, each with their own separate
bit definitions. In v2 that is collapsed to one - gpio_v2_line_flag.
The handle and event requests are merged into a single request, the line
request, as the two requests were mostly the same other than the edge
detection provided by event requests. As a byproduct, the v2 uAPI allows
for multiple lines producing edge events on the same line handle.
This is a new capability as v1 only supports a single line in an event
request.
As a consequence, there are now only two types of file handle to be
concerned with, the chip and the line, and it is clearer which ioctls
apply to which type of handle.
There is also some minor renaming of fields for consistency compared to
their v1 counterparts, e.g. offset rather than lineoffset or line_offset,
and consumer rather than consumer_label.
Additionally, v1 GPIOHANDLES_MAX becomes GPIO_V2_LINES_MAX in v2 for
clarity, and the gpiohandle_data __u8 array becomes a bitmap in
gpio_v2_line_values.
The v2 uAPI is mostly a reorganisation and extension of v1, so userspace
code, particularly libgpiod, should readily port to it.
Signed-off-by: Kent Gibson <warthog618@gmail.com>
Reviewed-by: Andy Shevchenko <andy.shevchenko@gmail.com>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
2020-09-28 00:27:51 +00:00
|
|
|
*/
|
2016-06-02 09:30:15 +00:00
|
|
|
#define GPIO_GET_LINEINFO_IOCTL _IOWR(0xB4, 0x02, struct gpioline_info)
|
|
|
|
#define GPIO_GET_LINEHANDLE_IOCTL _IOWR(0xB4, 0x03, struct gpiohandle_request)
|
|
|
|
#define GPIO_GET_LINEEVENT_IOCTL _IOWR(0xB4, 0x04, struct gpioevent_request)
|
gpio: uapi: define uAPI v2
Add a new version of the uAPI to address existing 32/64-bit alignment
issues, add support for debounce and event sequence numbers, allow
requested lines with different configurations, and provide some future
proofing by adding padding reserved for future use.
The alignment issue relates to the gpioevent_data, which packs to different
sizes on 32-bit and 64-bit platforms. That creates problems for 32-bit apps
running on 64-bit kernels. uAPI v2 addresses that particular issue, and
the problem more generally, by adding pad fields that explicitly pad
structs out to 64-bit boundaries, so they will pack to the same size now,
and even if some of the reserved padding is used for __u64 fields in the
future.
The new structs have been analysed with pahole to ensure that they
are sized as expected and contain no implicit padding.
The lack of future proofing in v1 makes it impossible to, for example,
add the debounce feature that is included in v2.
The future proofing is addressed by providing configurable attributes in
line config and reserved padding in all structs for future features.
Specifically, the line request, config, info, info_changed and event
structs receive updated versions and new ioctls.
As the majority of the structs and ioctls were being replaced, it is
opportune to rework some of the other aspects of the uAPI:
v1 has three different flags fields, each with their own separate
bit definitions. In v2 that is collapsed to one - gpio_v2_line_flag.
The handle and event requests are merged into a single request, the line
request, as the two requests were mostly the same other than the edge
detection provided by event requests. As a byproduct, the v2 uAPI allows
for multiple lines producing edge events on the same line handle.
This is a new capability as v1 only supports a single line in an event
request.
As a consequence, there are now only two types of file handle to be
concerned with, the chip and the line, and it is clearer which ioctls
apply to which type of handle.
There is also some minor renaming of fields for consistency compared to
their v1 counterparts, e.g. offset rather than lineoffset or line_offset,
and consumer rather than consumer_label.
Additionally, v1 GPIOHANDLES_MAX becomes GPIO_V2_LINES_MAX in v2 for
clarity, and the gpiohandle_data __u8 array becomes a bitmap in
gpio_v2_line_values.
The v2 uAPI is mostly a reorganisation and extension of v1, so userspace
code, particularly libgpiod, should readily port to it.
Signed-off-by: Kent Gibson <warthog618@gmail.com>
Reviewed-by: Andy Shevchenko <andy.shevchenko@gmail.com>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
2020-09-28 00:27:51 +00:00
|
|
|
#define GPIOHANDLE_GET_LINE_VALUES_IOCTL _IOWR(0xB4, 0x08, struct gpiohandle_data)
|
|
|
|
#define GPIOHANDLE_SET_LINE_VALUES_IOCTL _IOWR(0xB4, 0x09, struct gpiohandle_data)
|
|
|
|
#define GPIOHANDLE_SET_CONFIG_IOCTL _IOWR(0xB4, 0x0A, struct gpiohandle_config)
|
|
|
|
#define GPIO_GET_LINEINFO_WATCH_IOCTL _IOWR(0xB4, 0x0B, struct gpioline_info)
|
2016-06-02 09:30:15 +00:00
|
|
|
|
gpio: add a userspace chardev ABI for GPIOs
A new chardev that is to be used for userspace GPIO access is
added in this patch. It is intended to gradually replace the
horribly broken sysfs ABI.
Using a chardev has many upsides:
- All operations are per-gpiochip, which is the actual
device underlying the GPIOs, making us tie in to the
kernel device model properly.
- Hotpluggable GPIO controllers can come and go, as this
kind of problem has been know to userspace for character
devices since ages, and if a gpiochip handle is held in
userspace we know we will break something, whereas the
sysfs is stateless.
- The one-value-per-file rule of sysfs is really hard to
maintain when you want to twist more than one knob at a time,
for example have in-kernel APIs to switch several GPIO
lines at the same time, and this will be possible to do
with a single ioctl() from userspace, saving a lot of
context switching.
We also need to add a new bus type for GPIO. This is
necessary for example for userspace coldplug, where sysfs is
traversed to find the boot-time device nodes and create the
character devices in /dev.
This new chardev ABI is *non* *optional* and can be counted
on to be present in the future, emphasizing the preference
of this ABI.
The ABI only implements one single ioctl() to get the name
and number of GPIO lines of a chip. Even this is debatable:
see it as a minimal example for review. This ABI shall be
ruthlessly reviewed and etched in stone.
The old /sys/class/gpio is still optional to compile in,
but will be deprecated.
Unique device IDs are created using IDR, which is overkill
and insanely scalable, but also well tested.
Cc: Johan Hovold <johan@kernel.org>
Cc: Michael Welling <mwelling@ieee.org>
Cc: Markus Pargmann <mpa@pengutronix.de>
Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Cc: Arnd Bergmann <arnd@arndb.de>
Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
2015-10-21 13:29:53 +00:00
|
|
|
#endif /* _UAPI_GPIO_H_ */
|