linux-toradex.git/include/uapi/linux/gpio.h, branch v5.10-rc3

gpio: uapi: document uAPI v1 as deprecated

2020-09-30T08:57:08+00:00

Update uAPI documentation to deprecate v1 structs and ioctls.

Signed-off-by: Kent Gibson 
Signed-off-by: Bartosz Golaszewski

gpio: uapi: define uAPI v2

2020-09-30T08:56:38+00:00

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 
Reviewed-by: Andy Shevchenko 
Signed-off-by: Bartosz Golaszewski

gpio: uapi: define GPIO_MAX_NAME_SIZE for array sizes

2020-09-30T08:56:34+00:00

Replace constant array sizes with a macro constant to clarify the source
of array sizes, provide a place to document any constraints on the size,
and to simplify array sizing in userspace if constructing structs
from their composite fields.

Signed-off-by: Kent Gibson 
Reviewed-by: Andy Shevchenko 
Signed-off-by: Bartosz Golaszewski

gpio: uapi: fix misplaced comment line

2020-07-12T08:22:01+00:00

The second line of the description for event_type is before the first.
Move it to after the first line.

Signed-off-by: Kent Gibson 
Signed-off-by: Bartosz Golaszewski

gpio: uapi: Improve phrasing around arrays representing empty strings

2020-03-25T08:50:44+00:00

Character arrays can be considered empty strings (if they are
immediately terminated), but they cannot be NULL.

Signed-off-by: Jonathan Neuschäfer 
Signed-off-by: Bartosz Golaszewski

gpiolib: add new ioctl() for monitoring changes in line info

2020-02-12T11:05:47+00:00

Currently there is no way for user-space to be informed about changes
in status of GPIO lines e.g. when someone else requests the line or its
config changes. We can only periodically re-read the line-info. This
is fine for simple one-off user-space tools, but any daemon that provides
a centralized access to GPIO chips would benefit hugely from an event
driven line info synchronization.

This patch adds a new ioctl() that allows user-space processes to reuse
the file descriptor associated with the character device for watching
any changes in line properties. Every such event contains the updated
line information.

Currently the events are generated on three types of status changes: when
a line is requested, when it's released and when its config is changed.
The first two are self-explanatory. For the third one: this will only
happen when another user-space process calls the new SET_CONFIG ioctl()
as any changes that can happen from within the kernel (i.e.
set_transitory() or set_debounce()) are of no interest to user-space.

Signed-off-by: Bartosz Golaszewski 
Reviewed-by: Linus Walleij

gpio: add new SET_CONFIG ioctl() to gpio chardev

2019-11-12T15:30:31+00:00

Add the GPIOHANDLE_SET_CONFIG_IOCTL to the gpio chardev.
The ioctl allows some of the configuration of a requested handle to be
changed without having to release the line.
The primary use case is the changing of direction for bi-directional
lines.

Based on initial work by Bartosz Golaszewski 

Signed-off-by: Kent Gibson 
Signed-off-by: Bartosz Golaszewski

gpiolib: add support for disabling line bias

2019-11-12T15:30:30+00:00

Allow pull up/down bias to be disabled, allowing the line to float
or to be biased only by external circuitry.
Use case is for where the bias has been applied previously, either
by default or by the user, but that setting may conflict with the
current use of the line.

Signed-off-by: Kent Gibson 
Signed-off-by: Bartosz Golaszewski

gpio: expose pull-up/pull-down line flags to userspace

2019-11-12T15:30:30+00:00

Add pull-up/pull-down flags to the gpio line get and
set ioctl() calls.  Use cases include a push button
that does not have an external resistor.

Addition use cases described by Limor Fried (ladyada) of
Adafruit in this PR for Adafruit_Blinka Python lib:
https://github.com/adafruit/Adafruit_Blinka/pull/59

Signed-off-by: Drew Fustini 
[Kent: added BIAS to GPIO flag names and restrict application to input
lines]
Signed-off-by: Kent Gibson 
Signed-off-by: Bartosz Golaszewski

gpio: uapi: Grammar s/array/array of/

2018-09-13T08:46:24+00:00

Signed-off-by: Geert Uytterhoeven 
Signed-off-by: Linus Walleij