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 20:29:53 +07: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 15:35:29 +07: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 20:29:53 +07: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_
|
|
|
|
|
|
|
|
|
|
#include <linux/ioctl.h>
|
|
|
|
|
#include <linux/types.h>
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* struct gpiochip_info - Information about a certain GPIO chip
|
2016-02-26 03:01:48 +07:00
|
|
|
* @name: the Linux kernel name of this GPIO chip
|
|
|
|
|
* @label: a functional name for this GPIO chip, such as a product
|
|
|
|
|
* number, may be NULL
|
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 20:29:53 +07:00
|
|
|
* @lines: number of GPIO lines on this chip
|
|
|
|
|
*/
|
|
|
|
|
struct gpiochip_info {
|
|
|
|
|
char name[32];
|
2016-02-12 20:48:23 +07:00
|
|
|
char label[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 20:29:53 +07:00
|
|
|
__u32 lines;
|
|
|
|
|
};
|
|
|
|
|
|
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 15:35:29 +07:00
|
|
|
/* Informational flags */
|
|
|
|
|
#define GPIOLINE_FLAG_KERNEL (1UL << 0) /* Line used by the kernel */
|
2016-02-13 04:25:22 +07: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)
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* struct gpioline_info - Information about a certain GPIO line
|
2016-02-26 03:01:48 +07:00
|
|
|
* @line_offset: the local offset on this GPIO device, fill this in when
|
|
|
|
|
* requesting the line information from the kernel
|
2016-02-13 04:25:22 +07:00
|
|
|
* @flags: various flags for this line
|
2016-02-26 03:01:48 +07: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
|
|
|
|
|
* chip, may be NULL
|
|
|
|
|
* @consumer: a functional name for the consumer of this GPIO line as set by
|
|
|
|
|
* whatever is using it, will be NULL if there is no current user but may
|
|
|
|
|
* also be NULL if the consumer doesn't set this up
|
2016-02-13 04:25:22 +07:00
|
|
|
*/
|
|
|
|
|
struct gpioline_info {
|
|
|
|
|
__u32 line_offset;
|
|
|
|
|
__u32 flags;
|
|
|
|
|
char name[32];
|
2016-02-26 03:01:48 +07:00
|
|
|
char consumer[32];
|
2016-02-13 04:25:22 +07: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 15:35:29 +07:00
|
|
|
/* Maximum number of requested handles */
|
|
|
|
|
#define GPIOHANDLES_MAX 64
|
|
|
|
|
|
|
|
|
|
/* Request flags */
|
|
|
|
|
#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)
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* struct gpiohandle_request - Information about a GPIO handle request
|
|
|
|
|
* @lineoffsets: an array desired lines, specified by offset index for the
|
|
|
|
|
* associated GPIO device
|
|
|
|
|
* @flags: desired flags for the desired GPIO lines, such as
|
|
|
|
|
* GPIOHANDLE_REQUEST_OUTPUT, GPIOHANDLE_REQUEST_ACTIVE_LOW etc, OR:ed
|
|
|
|
|
* 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
|
|
|
|
|
* @default_values: if the GPIOHANDLE_REQUEST_OUTPUT is set for a requested
|
|
|
|
|
* 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
|
|
|
|
|
* after a GPIO_GET_LINEHANDLE_IOCTL operation, zero or negative value
|
|
|
|
|
* means error
|
|
|
|
|
*/
|
|
|
|
|
struct gpiohandle_request {
|
|
|
|
|
__u32 lineoffsets[GPIOHANDLES_MAX];
|
|
|
|
|
__u32 flags;
|
|
|
|
|
__u8 default_values[GPIOHANDLES_MAX];
|
|
|
|
|
char consumer_label[32];
|
|
|
|
|
__u32 lines;
|
|
|
|
|
int fd;
|
|
|
|
|
};
|
|
|
|
|
|
2016-03-10 15:48:06 +07:00
|
|
|
#define GPIO_GET_CHIPINFO_IOCTL _IOR(0xB4, 0x01, struct gpiochip_info)
|
|
|
|
|
#define GPIO_GET_LINEINFO_IOCTL _IOWR(0xB4, 0x02, struct gpioline_info)
|
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 15:35:29 +07:00
|
|
|
#define GPIO_GET_LINEHANDLE_IOCTL _IOWR(0xB4, 0x03, struct gpiohandle_request)
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* 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
|
|
|
|
|
*/
|
|
|
|
|
struct gpiohandle_data {
|
|
|
|
|
__u8 values[GPIOHANDLES_MAX];
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
#define GPIOHANDLE_GET_LINE_VALUES_IOCTL _IOWR(0xB4, 0x08, struct gpiohandle_data)
|
|
|
|
|
#define GPIOHANDLE_SET_LINE_VALUES_IOCTL _IOWR(0xB4, 0x09, struct gpiohandle_data)
|
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 20:29:53 +07:00
|
|
|
|
|
|
|
|
#endif /* _UAPI_GPIO_H_ */
|