gpio: uapi: clarify default_values being logical

The documentation for default_values mentions high/low which can be
confusing, particularly when the ACTIVE_LOW flag is set.

Replace high/low with active/inactive to clarify that the values are
logical not physical.

Similarly, clarify the interpretation of values in struct gpiohandle_data.

Signed-off-by: Kent Gibson <warthog618@gmail.com>
Reviewed-by: Andy Shevchenko <andy.shevchenko@gmail.com>
Acked-by: Linus Walleij <linus.walleij@linaro.org>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

gpio: uapi: clarify using v2 rather than v1

The documentation contains notes like
This struct is part of ABI v1 and is deprecated.
Use struct gpio_v2_line_info instead.

This could be interpreted to mean the structs can be directly
substituted in v1 calls. Clarify that the user should use the
corresponding v2 ioctl() and structs.

Signed-off-by: Kent Gibson <warthog618@gmail.com>
Reviewed-by: Andy Shevchenko <andy@kernel.org>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

gpio: uapi: document possible values of gpioevent_data.id

Clarify the possible values of event id, rather than requiring the
reader to infer.

Signed-off-by: Kent Gibson <warthog618@gmail.com>
Reviewed-by: Andy Shevchenko <andy@kernel.org>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

gpio: uapi: drop trailing period from one sentence descriptions

Make documentation more consistent by using trailing periods only for
multi-sentence field descriptions, not single sentence descriptions.

Signed-off-by: Kent Gibson <warthog618@gmail.com>
Reviewed-by: Andy Shevchenko <andy@kernel.org>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

gpio: uapi: clarify hte references

The full name of the HTE subsystem is "hardware timestamping engine",
so correct references and highlight that this refers to the HTE
subsystem.

Extend the description of struct gpio_v2_line_event to clarify that
the timestamp_ns is sourced from the HTE if the
GPIO_V2_LINE_FLAG_EVENT_CLOCK_HTE is set.

Signed-off-by: Kent Gibson <warthog618@gmail.com>
Reviewed-by: Andy Shevchenko <andy@kernel.org>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

gpio: uapi: improve description of fd fields

Only a successful operation modifies fd fields, but the current
documentation wording could be taken to imply that a positive fd
value after an ioctl() returns indicates a success.

Reword documentation to clarify that the fd is only valid after a
successful operation.

Signed-off-by: Kent Gibson <warthog618@gmail.com>
Reviewed-by: Andy Shevchenko <andy@kernel.org>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

gpiolib: cdev: Add hardware timestamp clock type

This patch adds new clock type for the GPIO controller which can
timestamp gpio lines in using hardware means. To expose such
functionalities to the userspace, code has been added where
during line create or set config API calls, it checks for new
clock type and if requested, calls HTE API. During line change
event, the HTE subsystem pushes timestamp data to userspace
through gpiolib-cdev.

Signed-off-by: Dipen Patel <dipenp@nvidia.com>
Acked-by: Linus Walleij <linus.walleij@linaro.org>
Reported-by: kernel test robot <lkp@intel.com>
Reported-by: Dan Carpenter <dan.carpenter@oracle.com>
Signed-off-by: Thierry Reding <treding@nvidia.com>

gpio: uapi: use the preferred SPDX license identifier

GPL-2.0 license identifier is deprecated. User-space projects that want
to include the kernel header with their source-code will be unable to
become fully REUSE compliant due to the reuse tool complaining about
deprecated licenses. Change the SPDX identifier to GPL-2.0-only.

Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>

gpio: uapi: fix line info flags description

The description of the flags field of the struct gpio_v2_line_info
mentions "the GPIO lines" while the info only applies to an individual
GPIO line. This was accidentally changed from "the GPIO line" during
formatting improvements.

Reword to "this GPIO line" to clarify and to be consistent with other
struct gpio_v2_line_info fields.

Fixes: 2cc522d3931b ("gpio: uapi: kernel-doc formatting improvements")
Signed-off-by: Kent Gibson <warthog618@gmail.com>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>

gpiolib: cdev: allow edge event timestamps to be configured as REALTIME

Using CLOCK_REALTIME as the source for event timestamps is crucial for
some specific applications, particularly those requiring timetamps
relative to a PTP clock, so provide an option to switch the event
timestamp source from the default CLOCK_MONOTONIC to CLOCK_REALTIME.

Note that CLOCK_REALTIME was the default source clock for GPIO until
Linux 5.7 when it was changed to CLOCK_MONOTONIC due to issues with the
shifting of the realtime clock.
Providing this option maintains the CLOCK_MONOTONIC as the default,
while also providing a path forward for those dependent on the pre-5.7
behaviour.

Suggested-by: Jack Winch <sunt.un.morcov@gmail.com>
Signed-off-by: Kent Gibson <warthog618@gmail.com>
Link: https://lore.kernel.org/r/20201014231158.34117-2-warthog618@gmail.com
Signed-off-by: Linus Walleij <linus.walleij@linaro.org>

gpio: uapi: clarify the meaning of 'empty' char arrays

Clarify that a char array containing a string is considered 'empty' if
the first character is the null terminator. The remaining characters
are not relevant to this determination.

Signed-off-by: Kent Gibson <warthog618@gmail.com>
Reviewed-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
Reviewed-by: Andy Shevchenko <andy.shevchenko@gmail.com>
Link: https://lore.kernel.org/r/20201005070329.21055-6-warthog618@gmail.com
Signed-off-by: Linus Walleij <linus.walleij@linaro.org>

gpio: uapi: remove whitespace

Remove leading whitespace in ABI v1 comment.

Signed-off-by: Kent Gibson <warthog618@gmail.com>
Reviewed-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
Reviewed-by: Andy Shevchenko <andy.shevchenko@gmail.com>
Link: https://lore.kernel.org/r/20201005070329.21055-5-warthog618@gmail.com
Signed-off-by: Linus Walleij <linus.walleij@linaro.org>

gpio: uapi: kernel-doc formatting improvements

Add kernel-doc formatting to all references to structs, enums, fields
and constants, and move deprecation warnings into the Note section of
the deprecated struct.

Replace 'OR:ed' with 'added', as the former looks odd.

Signed-off-by: Kent Gibson <warthog618@gmail.com>
Reviewed-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
Reviewed-by: Andy Shevchenko <andy.shevchenko@gmail.com>
Link: https://lore.kernel.org/r/20201005070329.21055-4-warthog618@gmail.com
Signed-off-by: Linus Walleij <linus.walleij@linaro.org>

gpio: uapi: comment consistency

Make debounce_period_us field documentation consistent with other fields
in the union.

Signed-off-by: Kent Gibson <warthog618@gmail.com>
Reviewed-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
Reviewed-by: Andy Shevchenko <andy.shevchenko@gmail.com>
Link: https://lore.kernel.org/r/20201005070329.21055-3-warthog618@gmail.com
Signed-off-by: Linus Walleij <linus.walleij@linaro.org>

gpio: uapi: fix kernel-doc warnings

Fix kernel-doc warnings, specifically gpioline_info_changed.padding is
not documented and 'GPIO event types' describes defines, which are not
documented by kernel-doc.

Signed-off-by: Kent Gibson <warthog618@gmail.com>
Reviewed-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
Reviewed-by: Andy Shevchenko <andy.shevchenko@gmail.com>
Link: https://lore.kernel.org/r/20201005070329.21055-2-warthog618@gmail.com
Signed-off-by: Linus Walleij <linus.walleij@linaro.org>

gpio: uapi: document uAPI v1 as deprecated

Update uAPI documentation to deprecate v1 structs and ioctls.

Signed-off-by: Kent Gibson <warthog618@gmail.com>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>

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>

gpio: uapi: define GPIO_MAX_NAME_SIZE for array sizes

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 <warthog618@gmail.com>
Reviewed-by: Andy Shevchenko <andy.shevchenko@gmail.com>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>

gpio: uapi: fix misplaced comment line

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 <warthog618@gmail.com>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>

gpio: uapi: Improve phrasing around arrays representing empty strings

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

Signed-off-by: Jonathan Neuschäfer <j.neuschaefer@gmx.net>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>

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

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 <bgolaszewski@baylibre.com>
Reviewed-by: Linus Walleij <linus.walleij@linaro.org>

gpio: add new SET_CONFIG ioctl() to gpio chardev

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 <bgolaszewski@baylibre.com>

Signed-off-by: Kent Gibson <warthog618@gmail.com>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>

gpiolib: add support for disabling line bias

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 <warthog618@gmail.com>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>

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

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 <drew@pdp7.com>
[Kent: added BIAS to GPIO flag names and restrict application to input
lines]
Signed-off-by: Kent Gibson <warthog618@gmail.com>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>

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

This reverts commit 8c550e94b8835170593169a45b5ba30d3fc72a70.

This was prematurely applied and we need to back it out to merge
a better version of the development track for this feature.

Signed-off-by: Linus Walleij <linus.walleij@linaro.org>

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

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 <drew@pdp7.com>
Link: https://lore.kernel.org/r/20190921102522.8970-1-drew@pdp7.com
Signed-off-by: Linus Walleij <linus.walleij@linaro.org>

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

Signed-off-by: Geert Uytterhoeven <geert+renesas@glider.be>
Signed-off-by: Linus Walleij <linus.walleij@linaro.org>

License cleanup: add SPDX license identifier to uapi header files with a license

Many user space API headers have licensing information, which is either
incomplete, badly formatted or just a shorthand for referring to the
license under which the file is supposed to be. This makes it hard for
compliance tools to determine the correct license.

Update these files with an SPDX license identifier. The identifier was
chosen based on the license information in the file.

GPL/LGPL licensed headers get the matching GPL/LGPL SPDX license
identifier with the added 'WITH Linux-syscall-note' exception, which is
the officially assigned exception identifier for the kernel syscall
exception:

NOTE! This copyright does *not* cover user programs that use kernel
services by normal system calls - this is merely considered normal use
of the kernel, and does *not* fall under the heading of "derived work".

This exception makes it possible to include GPL headers into non GPL
code, without confusing license compliance tools.

Headers which have either explicit dual licensing or are just licensed
under a non GPL license are updated with the corresponding SPDX
identifier and the GPLv2 with syscall exception identifier. The format
is:
((GPL-2.0 WITH Linux-syscall-note) OR SPDX-ID-OF-OTHER-LICENSE)

SPDX license identifiers are a legally binding shorthand, which can be
used instead of the full boiler plate text. The update does not remove
existing license information as this has to be done on a case by case
basis and the copyright holders might have to be consulted. This will
happen in a separate step.

This patch is based on work done by Thomas Gleixner and Kate Stewart and
Philippe Ombredanne. See the previous patch in this series for the
methodology of how this patch was researched.

Reviewed-by: Kate Stewart <kstewart@linuxfoundation.org>
Reviewed-by: Philippe Ombredanne <pombredanne@nexb.com>
Reviewed-by: Thomas Gleixner <tglx@linutronix.de>
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>

gpio: userspace ABI for reading GPIO line events

This adds an ABI for listening to events on GPIO lines.
The mechanism returns an anonymous file handle to a request
to listen to a specific offset on a specific gpiochip.
To fetch the stream of events from the file handle, userspace
simply reads an event.

- Events can be requested with the same flags as ordinary
handles, i.e. open drain or open source. An ioctl() call
GPIO_GET_LINEEVENT_IOCTL is issued indicating the desired
line.

- Events can be requested for falling edge events, rising
edge events, or both.

- All events are timestamped using the kernel real time
nanosecond timestamp (the same as is used by IIO).

- The supplied consumer label will appear in "lsgpio"
listings of the lines, and in /proc/interrupts as the
mechanism will request an interrupt from the gpio chip.

- Events are not supported on gpiochips that do not serve
interrupts (no legal .to_irq() call). The event interrupt
is threaded to avoid any realtime problems.

- It is possible to also directly read the current value
of the registered GPIO line by issuing the same
GPIOHANDLE_GET_LINE_VALUES_IOCTL as used by the
line handles. Setting the value is not supported: we
do not listen to events on output lines.

This ABI is strongly influenced by Industrial I/O and surpasses
the old sysfs ABI by providing proper precision timestamps,
making it possible to set flags like open drain, and put
consumer names on the GPIO lines.

Signed-off-by: Linus Walleij <linus.walleij@linaro.org>

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>

gpio: uapi: use 0xB4 as ioctl() major

The previous 'o' is in conflict and not very orderly assigned.
We want to select an ioctl() major that does not conflict with
the existining ones.

Add the new reserved major (0xB4) to Documentation/ioctl/ioctl-number.txt

Fixes: 3c702e9987e2 ("gpio: add a userspace chardev ABI for GPIOs")
Suggested-by: Arnd Bergmann <arnd@arndb.de>
Signed-off-by: Linus Walleij <linus.walleij@linaro.org>

gpio: present the consumer of a line to userspace

I named the field representing the current user of GPIO line as
"label" but this is too vague and ambiguous. Before anyone gets
confused, rename it to "consumer" and indicate clearly in the
documentation that this is a string set by the user of the line.

Also clean up leftovers in the documentation.

Signed-off-by: Linus Walleij <linus.walleij@linaro.org>

gpio: add userspace ABI for GPIO line information

This adds a GPIO line ABI for getting name, label and a few select
flags from the kernel.

This hides the kernel internals and only tells userspace what it
may need to know: the different in-kernel consumers are masked
behind the flag "kernel" and that is all userspace needs to know.

However electric characteristics like active low, open drain etc
are reflected to userspace, as this is important information.

We provide information on all lines on all chips, later on we will
likely add a flag for the chardev consumer so we can filter and
display only the lines userspace actually uses in e.g. lsgpio,
but then we first need an ABI for userspace to grab and use
(get/set/select direction) a GPIO line.

Sample output from "lsgpio" on ux500:

GPIO chip: gpiochip7, "8011e000.gpio", 32 GPIO lines
line 0: unnamed unlabeled
line 1: unnamed unlabeled
(...)
line 25: unnamed "SFH7741 Proximity Sensor" [kernel output open-drain]
line 26: unnamed unlabeled
(...)

Tested-by: Michael Welling <mwelling@ieee.org>
Signed-off-by: Linus Walleij <linus.walleij@linaro.org>

gpio: store reflect the label to userspace

The gpio_chip label is useful for userspace to understand what
kind of GPIO chip it is dealing with. Let's store a copy of this
label in the gpio_device, add it to the struct passed to userspace
for GPIO_GET_CHIPINFO_IOCTL and modify lsgpio to show it.

Signed-off-by: Linus Walleij <linus.walleij@linaro.org>

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>