Documentation: gpio: Move gpiod_* consumer documentation to driver-api

==================================

GPIO Descriptor Consumer Interface

GPIO Descriptor Consumer Interface

==================================

==================================

  be met with console warnings that may be perceived as intimidating.

  be met with console warnings that may be perceived as intimidating.

All the functions that work with the descriptor-based GPIO interface are

All the functions that work with the descriptor-based GPIO interface are

prefixed with gpiod_. The gpio_ prefix is used for the legacy interface. No

prefixed with ``gpiod_``. The ``gpio_`` prefix is used for the legacy

other function in the kernel should use these prefixes. The use of the legacy

interface. No other function in the kernel should use these prefixes. The use

functions is strongly discouraged, new code should use <linux/gpio/consumer.h>

of the legacy functions is strongly discouraged, new code should use

and descriptors exclusively.

<linux/gpio/consumer.h> and descriptors exclusively.

Obtaining and Disposing GPIOs

Obtaining and Disposing GPIOs

non-forgeable handler that must be obtained through a call to one of the

non-forgeable handler that must be obtained through a call to one of the

gpiod_get() functions. Like many other kernel subsystems, gpiod_get() takes the

gpiod_get() functions. Like many other kernel subsystems, gpiod_get() takes the

device that will use the GPIO and the function the requested GPIO is supposed to

device that will use the GPIO and the function the requested GPIO is supposed to

fulfill:

fulfill::

	struct gpio_desc *gpiod_get(struct device *dev, const char *con_id,

	struct gpio_desc *gpiod_get(struct device *dev, const char *con_id,

				    enum gpiod_flags flags)

				    enum gpiod_flags flags)

If a function is implemented by using several GPIOs together (e.g. a simple LED

If a function is implemented by using several GPIOs together (e.g. a simple LED

device that displays digits), an additional index argument can be specified:

device that displays digits), an additional index argument can be specified::

	struct gpio_desc *gpiod_get_index(struct device *dev,

	struct gpio_desc *gpiod_get_index(struct device *dev,

					  const char *con_id, unsigned int idx,

					  const char *con_id, unsigned int idx,

errors and an absence of GPIO for optional GPIO parameters. For the common

errors and an absence of GPIO for optional GPIO parameters. For the common

pattern where a GPIO is optional, the gpiod_get_optional() and

pattern where a GPIO is optional, the gpiod_get_optional() and

gpiod_get_index_optional() functions can be used. These functions return NULL

gpiod_get_index_optional() functions can be used. These functions return NULL

instead of -ENOENT if no GPIO has been assigned to the requested function:

instead of -ENOENT if no GPIO has been assigned to the requested function::

	struct gpio_desc *gpiod_get_optional(struct device *dev,

	struct gpio_desc *gpiod_get_optional(struct device *dev,

					     const char *con_id,

					     const char *con_id,

-ENOSYS return codes.  System integrators should however be careful to enable

-ENOSYS return codes.  System integrators should however be careful to enable

gpiolib on systems that need it.

gpiolib on systems that need it.

For a function using multiple GPIOs all of those can be obtained with one call:

For a function using multiple GPIOs all of those can be obtained with one call::

	struct gpio_descs *gpiod_get_array(struct device *dev,

	struct gpio_descs *gpiod_get_array(struct device *dev,

					   const char *con_id,

					   const char *con_id,

					   enum gpiod_flags flags)

					   enum gpiod_flags flags)

This function returns a struct gpio_descs which contains an array of

This function returns a struct gpio_descs which contains an array of

descriptors:

descriptors::

	struct gpio_descs {

	struct gpio_descs {

		unsigned int ndescs;

		unsigned int ndescs;

	}

	}

The following function returns NULL instead of -ENOENT if no GPIOs have been

The following function returns NULL instead of -ENOENT if no GPIOs have been

assigned to the requested function:

assigned to the requested function::

	struct gpio_descs *gpiod_get_array_optional(struct device *dev,

	struct gpio_descs *gpiod_get_array_optional(struct device *dev,

						    const char *con_id,

						    const char *con_id,

						    enum gpiod_flags flags)

						    enum gpiod_flags flags)

Device-managed variants of these functions are also defined:

Device-managed variants of these functions are also defined::

	struct gpio_desc *devm_gpiod_get(struct device *dev, const char *con_id,

	struct gpio_desc *devm_gpiod_get(struct device *dev, const char *con_id,

					 enum gpiod_flags flags)

					 enum gpiod_flags flags)

							 const char *con_id,

							 const char *con_id,

							 enum gpiod_flags flags)

							 enum gpiod_flags flags)

A GPIO descriptor can be disposed of using the gpiod_put() function:

A GPIO descriptor can be disposed of using the gpiod_put() function::

	void gpiod_put(struct gpio_desc *desc)

	void gpiod_put(struct gpio_desc *desc)

For an array of GPIOs this function can be used:

For an array of GPIOs this function can be used::

	void gpiod_put_array(struct gpio_descs *descs)

	void gpiod_put_array(struct gpio_descs *descs)

It is also not allowed to individually release descriptors (using gpiod_put())

It is also not allowed to individually release descriptors (using gpiod_put())

from an array acquired with gpiod_get_array().

from an array acquired with gpiod_get_array().

The device-managed variants are, unsurprisingly:

The device-managed variants are, unsurprisingly::

	void devm_gpiod_put(struct device *dev, struct gpio_desc *desc)

	void devm_gpiod_put(struct device *dev, struct gpio_desc *desc)

-----------------

-----------------

The first thing a driver must do with a GPIO is setting its direction. If no

The first thing a driver must do with a GPIO is setting its direction. If no

direction-setting flags have been given to gpiod_get*(), this is done by

direction-setting flags have been given to gpiod_get*(), this is done by

invoking one of the gpiod_direction_*() functions:

invoking one of the gpiod_direction_*() functions::

	int gpiod_direction_input(struct gpio_desc *desc)

	int gpiod_direction_input(struct gpio_desc *desc)

	int gpiod_direction_output(struct gpio_desc *desc, int value)

	int gpiod_direction_output(struct gpio_desc *desc, int value)

For output GPIOs, the value provided becomes the initial output value. This

For output GPIOs, the value provided becomes the initial output value. This

helps avoid signal glitching during system startup.

helps avoid signal glitching during system startup.

A driver can also query the current direction of a GPIO:

A driver can also query the current direction of a GPIO::

	int gpiod_get_direction(const struct gpio_desc *desc)

	int gpiod_get_direction(const struct gpio_desc *desc)

don't need to sleep, and can safely be done from inside hard (non-threaded) IRQ

don't need to sleep, and can safely be done from inside hard (non-threaded) IRQ

handlers and similar contexts.

handlers and similar contexts.

Use the following calls to access GPIOs from an atomic context:

Use the following calls to access GPIOs from an atomic context::

	int gpiod_get_value(const struct gpio_desc *desc);

	int gpiod_get_value(const struct gpio_desc *desc);

	void gpiod_set_value(struct gpio_desc *desc, int value);

	void gpiod_set_value(struct gpio_desc *desc, int value);

sleeping, which can't be done from inside IRQ handlers.

sleeping, which can't be done from inside IRQ handlers.

Platforms that support this type of GPIO distinguish them from other GPIOs by

Platforms that support this type of GPIO distinguish them from other GPIOs by

returning nonzero from this call:

returning nonzero from this call::

	int gpiod_cansleep(const struct gpio_desc *desc)

	int gpiod_cansleep(const struct gpio_desc *desc)

To access such GPIOs, a different set of accessors is defined:

To access such GPIOs, a different set of accessors is defined::

	int gpiod_get_value_cansleep(const struct gpio_desc *desc)

	int gpiod_get_value_cansleep(const struct gpio_desc *desc)

	void gpiod_set_value_cansleep(struct gpio_desc *desc, int value)

	void gpiod_set_value_cansleep(struct gpio_desc *desc, int value)

gpiod_set_(array)_value_xxx() passes "asserted" ("1"), the physical line level

gpiod_set_(array)_value_xxx() passes "asserted" ("1"), the physical line level

will be driven low.

will be driven low.

To summarize:

To summarize::

  Function (example)                 line property          physical line

  Function (example)                 line property          physical line

  gpiod_set_raw_value(desc, 0);      don't care             low

  gpiod_set_raw_value(desc, 0);      don't care             low

  gpiod_set_value(desc, 0);          open source            high impedance

  gpiod_set_value(desc, 0);          open source            high impedance

  gpiod_set_value(desc, 1);          open source            high

  gpiod_set_value(desc, 1);          open source            high

It is possible to override these semantics using the *set_raw/'get_raw functions

It is possible to override these semantics using the set_raw/get_raw functions

but it should be avoided as much as possible, especially by system-agnostic drivers

but it should be avoided as much as possible, especially by system-agnostic drivers

which should not need to care about the actual physical line level and worry about

which should not need to care about the actual physical line level and worry about

the logical value instead.

the logical value instead.

line.

line.

The following set of calls ignore the active-low or open drain property of a GPIO and

The following set of calls ignore the active-low or open drain property of a GPIO and

work on the raw line value:

work on the raw line value::

	int gpiod_get_raw_value(const struct gpio_desc *desc)

	int gpiod_get_raw_value(const struct gpio_desc *desc)

	void gpiod_set_raw_value(struct gpio_desc *desc, int value)

	void gpiod_set_raw_value(struct gpio_desc *desc, int value)

	void gpiod_set_raw_value_cansleep(struct gpio_desc *desc, int value)

	void gpiod_set_raw_value_cansleep(struct gpio_desc *desc, int value)

	int gpiod_direction_output_raw(struct gpio_desc *desc, int value)

	int gpiod_direction_output_raw(struct gpio_desc *desc, int value)

The active low state of a GPIO can also be queried using the following call:

The active low state of a GPIO can also be queried using the following call::

	int gpiod_is_active_low(const struct gpio_desc *desc)

	int gpiod_is_active_low(const struct gpio_desc *desc)

Access multiple GPIOs with a single function call

Access multiple GPIOs with a single function call

-------------------------------------------------

-------------------------------------------------

The following functions get or set the values of an array of GPIOs:

The following functions get or set the values of an array of GPIOs::

	int gpiod_get_array_value(unsigned int array_size,

	int gpiod_get_array_value(unsigned int array_size,

				  struct gpio_desc **desc_array,

				  struct gpio_desc **desc_array,

The descriptor array can be obtained using the gpiod_get_array() function

The descriptor array can be obtained using the gpiod_get_array() function

or one of its variants. If the group of descriptors returned by that function

or one of its variants. If the group of descriptors returned by that function

matches the desired group of GPIOs, those GPIOs can be accessed by simply using

matches the desired group of GPIOs, those GPIOs can be accessed by simply using

the struct gpio_descs returned by gpiod_get_array():

the struct gpio_descs returned by gpiod_get_array()::

	struct gpio_descs *my_gpio_descs = gpiod_get_array(...);

	struct gpio_descs *my_gpio_descs = gpiod_get_array(...);

	gpiod_set_array_value(my_gpio_descs->ndescs, my_gpio_descs->desc,

	gpiod_set_array_value(my_gpio_descs->ndescs, my_gpio_descs->desc,

GPIOs mapped to IRQs

GPIOs mapped to IRQs

--------------------

--------------------

GPIO lines can quite often be used as IRQs. You can get the IRQ number

GPIO lines can quite often be used as IRQs. You can get the IRQ number

corresponding to a given GPIO using the following call:

corresponding to a given GPIO using the following call::

	int gpiod_to_irq(const struct gpio_desc *desc)

	int gpiod_to_irq(const struct gpio_desc *desc)

Many kernel subsystems still handle GPIOs using the legacy integer-based

Many kernel subsystems still handle GPIOs using the legacy integer-based

interface. Although it is strongly encouraged to upgrade them to the safer

interface. Although it is strongly encouraged to upgrade them to the safer

descriptor-based API, the following two functions allow you to convert a GPIO

descriptor-based API, the following two functions allow you to convert a GPIO

descriptor into the GPIO integer namespace and vice-versa:

descriptor into the GPIO integer namespace and vice-versa::

	int desc_to_gpio(const struct gpio_desc *desc)

	int desc_to_gpio(const struct gpio_desc *desc)

	struct gpio_desc *gpio_to_desc(unsigned gpio)

	struct gpio_desc *gpio_to_desc(unsigned gpio)

   intro

   intro

   driver

   driver

   consumer

   legacy

   legacy

Core

Core

00-INDEX

00-INDEX

	- This file

	- This file

consumer.txt

	- How to obtain and use GPIOs in a driver

drivers-on-gpio.txt:

drivers-on-gpio.txt:

	- Drivers in other subsystems that can use GPIO to provide more

	- Drivers in other subsystems that can use GPIO to provide more

	  complex functionality.

	  complex functionality.