Documentation: gpio: add chardev userspace API documentation

.. toctree::

    :maxdepth: 1

    Character Device Userspace API <../../userspace-api/gpio/chardev>

    gpio-aggregator

    sysfs

    gpio-mockup

.. SPDX-License-Identifier: GPL-2.0

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

GPIO Character Device Userspace API

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

This is latest version (v2) of the character device API, as defined in

``include/uapi/linux/gpio.h.``

First added in 5.10.

.. note::

   Do NOT abuse userspace APIs to control hardware that has proper kernel

   drivers. There may already be a driver for your use case, and an existing

   kernel driver is sure to provide a superior solution to bitbashing

   from userspace.

   Read Documentation/driver-api/gpio/drivers-on-gpio.rst to avoid reinventing

   kernel wheels in userspace.

   Similarly, for multi-function lines there may be other subsystems, such as

   Documentation/spi/index.rst, Documentation/i2c/index.rst,

   Documentation/driver-api/pwm.rst, Documentation/w1/index.rst etc, that

   provide suitable drivers and APIs for your hardware.

Basic examples using the character device API can be found in ``tools/gpio/*``.

The API is based around two major objects, the :ref:`gpio-v2-chip` and the

:ref:`gpio-v2-line-request`.

.. _gpio-v2-chip:

Chip

====

The Chip represents a single GPIO chip and is exposed to userspace using device

files of the form ``/dev/gpiochipX``.

Each chip supports a number of GPIO lines,

:c:type:`chip.lines<gpiochip_info>`. Lines on the chip are identified by an

``offset`` in the range from 0 to ``chip.lines - 1``, i.e. `[0,chip.lines)`.

Lines are requested from the chip using gpio-v2-get-line-ioctl.rst

and the resulting line request is used to access the GPIO chip's lines or

monitor the lines for edge events.

Within this documentation, the file descriptor returned by calling `open()`

on the GPIO device file is referred to as ``chip_fd``.

Operations

----------

The following operations may be performed on the chip:

.. toctree::

   :titlesonly:

   Get Line <gpio-v2-get-line-ioctl>

   Get Chip Info <gpio-get-chipinfo-ioctl>

   Get Line Info <gpio-v2-get-lineinfo-ioctl>

   Watch Line Info <gpio-v2-get-lineinfo-watch-ioctl>

   Unwatch Line Info <gpio-get-lineinfo-unwatch-ioctl>

   Read Line Info Changed Events <gpio-v2-lineinfo-changed-read>

.. _gpio-v2-line-request:

Line Request

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

Line requests are created by gpio-v2-get-line-ioctl.rst and provide

access to a set of requested lines.  The line request is exposed to userspace

via the anonymous file descriptor returned in

:c:type:`request.fd<gpio_v2_line_request>` by gpio-v2-get-line-ioctl.rst.

Within this documentation, the line request file descriptor is referred to

as ``req_fd``.

Operations

----------

The following operations may be performed on the line request:

.. toctree::

   :titlesonly:

   Get Line Values <gpio-v2-line-get-values-ioctl>

   Set Line Values <gpio-v2-line-set-values-ioctl>

   Read Line Edge Events <gpio-v2-line-event-read>

   Reconfigure Lines <gpio-v2-line-set-config-ioctl>

Types

=====

This section contains the structs and enums that are referenced by the API v2,

as defined in ``include/uapi/linux/gpio.h``.

.. kernel-doc:: include/uapi/linux/gpio.h

   :identifiers:

    gpio_v2_line_attr_id

    gpio_v2_line_attribute

    gpio_v2_line_changed_type

    gpio_v2_line_config

    gpio_v2_line_config_attribute

    gpio_v2_line_event

    gpio_v2_line_event_id

    gpio_v2_line_flag

    gpio_v2_line_info

    gpio_v2_line_info_changed

    gpio_v2_line_request

    gpio_v2_line_values

    gpiochip_info

.. toctree::

   :hidden:

   error-codes

.. SPDX-License-Identifier: GPL-2.0

.. _gpio_errors:

*******************

GPIO Error Codes

*******************

.. _gpio-errors:

.. tabularcolumns:: |p{2.5cm}|p{15.0cm}|

.. flat-table:: Common GPIO error codes

    :header-rows:  0

    :stub-columns: 0

    :widths: 1 16

    -  -  ``EAGAIN`` (aka ``EWOULDBLOCK``)

       -  The device was opened in non-blocking mode and a read can't

          be performed as there is no data available.

    -  -  ``EBADF``

       -  The file descriptor is not valid.

    -  -  ``EBUSY``

       -  The ioctl can't be handled because the device is busy. Typically

          returned when an ioctl attempts something that would require the

          usage of a resource that was already allocated. The ioctl must not

          be retried without performing another action to fix the problem

          first.

    -  -  ``EFAULT``

       -  There was a failure while copying data from/to userspace, probably

	  caused by an invalid pointer reference.

    -  -  ``EINVAL``

       -  One or more of the ioctl parameters are invalid or out of the

          allowed range. This is a widely used error code.

    -  -  ``ENODEV``

       -  Device not found or was removed.

    -  -  ``ENOMEM``

       -  There's not enough memory to handle the desired operation.

    -  -  ``EPERM``

       -  Permission denied. Typically returned in response to an attempt

          to perform an action incompatible with the current line

          configuration.

    -  -  ``EIO``

       -  I/O error. Typically returned when there are problems communicating

          with a hardware device or requesting features that hardware does not

          support. This could indicate broken or flaky hardware.

          It's a 'Something is wrong, I give up!' type of error.

    -  - ``ENXIO``

       -  No device corresponding to this device special file exists.

.. note::

  #. This list is not exhaustive; ioctls may return other error codes.

     Since errors may have side effects such as a driver reset,

     applications should abort on unexpected errors, or otherwise

     assume that the device is in a bad state.

  #. Request-specific error codes are listed in the individual

     requests descriptions.

.. SPDX-License-Identifier: GPL-2.0

.. _GPIO_GET_CHIPINFO_IOCTL:

***********************

GPIO_GET_CHIPINFO_IOCTL

***********************

Name

====

GPIO_GET_CHIPINFO_IOCTL - Get the publicly available information for a chip.

Synopsis

========

.. c:macro:: GPIO_GET_CHIPINFO_IOCTL

``int ioctl(int chip_fd, GPIO_GET_CHIPINFO_IOCTL, struct gpiochip_info *info)``

Arguments

=========

``chip_fd``

    The file descriptor of the GPIO character device returned by `open()`.

``info``

    The :c:type:`chip_info<gpiochip_info>` to be populated.

Description

===========

Gets the publicly available information for a particular GPIO chip.

Return Value

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

On success 0 and ``info`` is populated with the chip info.

On error -1 and the ``errno`` variable is set appropriately.

Common error codes are described in error-codes.rst.

.. SPDX-License-Identifier: GPL-2.0

.. _GPIO_GET_LINEINFO_UNWATCH_IOCTL:

*******************************

GPIO_GET_LINEINFO_UNWATCH_IOCTL

*******************************

Name

====

GPIO_GET_LINEINFO_UNWATCH_IOCTL - Disable watching a line for changes to its

requested state and configuration information.

Synopsis

========

.. c:macro:: GPIO_GET_LINEINFO_UNWATCH_IOCTL

``int ioctl(int chip_fd, GPIO_GET_LINEINFO_UNWATCH_IOCTL, u32 *offset)``

Arguments

=========

``chip_fd``

    The file descriptor of the GPIO character device returned by `open()`.

``offset``

    The offset of the line to no longer watch.

Description

===========

Remove the line from the list of lines being watched on this ``chip_fd``.

This is the opposite of gpio-v2-get-lineinfo-watch-ioctl.rst (v2) and

gpio-get-lineinfo-watch-ioctl.rst (v1).

Unwatching a line that is not watched is an error (**EBUSY**).

First added in 5.7.

Return Value

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

On success 0.

On error -1 and the ``errno`` variable is set appropriately.

Common error codes are described in error-codes.rst.