Commit 16b2bb7f authored by Kent Gibson's avatar Kent Gibson Committed by Bartosz Golaszewski
Browse files

Documentation: gpio: add chardev v1 userspace API documentation 



Add documentation for v1 of the GPIO character device userspace API
to the obsolete section of both the admin-guide and userspace-api
books.

Signed-off-by: default avatarKent Gibson <warthog618@gmail.com>
Signed-off-by: default avatarBartosz Golaszewski <bartosz.golaszewski@linaro.org>
parent e10b6417

Documentation/admin-guide/gpio/obsolete.rst

+1 −0
Original line number Diff line number Diff line
@@ -7,5 +7,6 @@ Obsolete GPIO APIs 
.. toctree::

    :maxdepth: 1



    Character Device Userspace API (v1) <../../userspace-api/gpio/chardev_v1>

    Sysfs Interface <../../userspace-api/gpio/sysfs>

Documentation/userspace-api/gpio/chardev_v1.rst

0 → 100644
+131 −0
Original line number Diff line number Diff line 
.. SPDX-License-Identifier: GPL-2.0



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

GPIO Character Device Userspace API (v1)

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



.. warning::

   This API is obsoleted by chardev.rst (v2).



   New developments should use the v2 API, and existing developments are

   encouraged to migrate as soon as possible, as this API will be removed

   in the future. The v2 API is a functional superset of the v1 API so any

   v1 call can be directly translated to a v2 equivalent.



   This interface will continue to be maintained for the migration period,

   but new features will only be added to the new API.



First added in 4.8.



The API is based around three major objects, the :ref:`gpio-v1-chip`, the

:ref:`gpio-v1-line-handle`, and the :ref:`gpio-v1-line-event`.



Where "line event" is used in this document it refers to the request that can

monitor a line for edge events, not the edge events themselves.



.. _gpio-v1-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 either gpio-get-linehandle-ioctl.rst

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

gpio-get-lineevent-ioctl.rst and the resulting line event is used to monitor

a GPIO line 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 Handle <gpio-get-linehandle-ioctl>

   Get Line Event <gpio-get-lineevent-ioctl>

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

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

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

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

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



.. _gpio-v1-line-handle:



Line Handle

===========



Line handles are created by gpio-get-linehandle-ioctl.rst and provide

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

via the anonymous file descriptor returned  in

:c:type:`request.fd<gpiohandle_request>` by gpio-get-linehandle-ioctl.rst.



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

as ``handle_fd``.



Operations

----------



The following operations may be performed on the line handle:



.. toctree::

   :titlesonly:



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

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

   Reconfigure Lines <gpio-handle-set-config-ioctl>



.. _gpio-v1-line-event:



Line Event

==========



Line events are created by gpio-get-lineevent-ioctl.rst and provide

access to a requested line.  The line event is exposed to userspace

via the anonymous file descriptor returned  in

:c:type:`request.fd<gpioevent_request>` by gpio-get-lineevent-ioctl.rst.



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

as ``event_fd``.



Operations

----------



The following operations may be performed on the line event:



.. toctree::

   :titlesonly:



   Get Line Value <gpio-handle-get-line-values-ioctl>

   Read Line Edge Events <gpio-lineevent-data-read>



Types

=====



This section contains the structs that are referenced by the ABI v1.



The :c:type:`struct gpiochip_info<gpiochip_info>` is common to ABI v1 and v2.



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

   :identifiers:

    gpioevent_data

    gpioevent_request

    gpiohandle_config

    gpiohandle_data

    gpiohandle_request

    gpioline_info

    gpioline_info_changed



.. toctree::

   :hidden:



   error-codes

Documentation/userspace-api/gpio/gpio-get-lineevent-ioctl.rst

0 → 100644
+78 −0
Original line number Diff line number Diff line 
.. SPDX-License-Identifier: GPL-2.0



.. _GPIO_GET_LINEEVENT_IOCTL:



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

GPIO_GET_LINEEVENT_IOCTL

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



.. warning::

    This ioctl is part of chardev_v1.rst and is obsoleted by

    gpio-v2-get-line-ioctl.rst.



Name

====



GPIO_GET_LINEEVENT_IOCTL - Request a line with edge detection from the kernel.



Synopsis

========



.. c:macro:: GPIO_GET_LINEEVENT_IOCTL



``int ioctl(int chip_fd, GPIO_GET_LINEEVENT_IOCTL, struct gpioevent_request *request)``



Arguments

=========



``chip_fd``

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



``request``

    The :c:type:`event_request<gpioevent_request>` specifying the line

    to request and its configuration.



Description

===========



Request a line with edge detection from the kernel.



On success, the requesting process is granted exclusive access to the line

value and may receive events when edges are detected on the line, as

described in gpio-lineevent-data-read.rst.



The state of a line is guaranteed to remain as requested until the returned

file descriptor is closed. Once the file descriptor is closed, the state of

the line becomes uncontrolled from the userspace perspective, and may revert

to its default state.



Requesting a line already in use is an error (**EBUSY**).



Closing the ``chip_fd`` has no effect on existing line events.



Configuration Rules

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



The following configuration rules apply:



The line event is requested as an input, so no flags specific to output lines,

``GPIOHANDLE_REQUEST_OUTPUT``, ``GPIOHANDLE_REQUEST_OPEN_DRAIN``, or

``GPIOHANDLE_REQUEST_OPEN_SOURCE``, may be set.



Only one bias flag, ``GPIOHANDLE_REQUEST_BIAS_xxx``, may be set.

If no bias flags are set then the bias configuration is not changed.



The edge flags, ``GPIOEVENT_REQUEST_RISING_EDGE`` and

``GPIOEVENT_REQUEST_FALLING_EDGE``, may be combined to detect both rising

and falling edges.



Requesting an invalid configuration is an error (**EINVAL**).



Return Value

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



On success 0 and the :c:type:`request.fd<gpioevent_request>` contains the file

descriptor for the request.



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

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

Documentation/userspace-api/gpio/gpio-get-linehandle-ioctl.rst

0 → 100644
+86 −0
Original line number Diff line number Diff line 
.. SPDX-License-Identifier: GPL-2.0



.. _GPIO_GET_LINEHANDLE_IOCTL:



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

GPIO_GET_LINEHANDLE_IOCTL

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



.. warning::

    This ioctl is part of chardev_v1.rst and is obsoleted by

    gpio-v2-get-line-ioctl.rst.



Name

====



GPIO_GET_LINEHANDLE_IOCTL - Request a line or lines from the kernel.



Synopsis

========



.. c:macro:: GPIO_GET_LINEHANDLE_IOCTL



``int ioctl(int chip_fd, GPIO_GET_LINEHANDLE_IOCTL, struct gpiohandle_request *request)``



Arguments

=========



``chip_fd``

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



``request``

    The :c:type:`handle_request<gpiohandle_request>` specifying the lines to

    request and their configuration.



Description

===========



Request a line or lines from the kernel.



While multiple lines may be requested, the same configuration applies to all

lines in the request.



On success, the requesting process is granted exclusive access to the line

value and write access to the line configuration.



The state of a line, including the value of output lines, is guaranteed to

remain as requested until the returned file descriptor is closed. Once the

file descriptor is closed, the state of the line becomes uncontrolled from

the userspace perspective, and may revert to its default state.



Requesting a line already in use is an error (**EBUSY**).



Closing the ``chip_fd`` has no effect on existing line handles.



.. _gpio-get-linehandle-config-rules:



Configuration Rules

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



The following configuration rules apply:



The direction flags, ``GPIOHANDLE_REQUEST_INPUT`` and

``GPIOHANDLE_REQUEST_OUTPUT``, cannot be combined. If neither are set then the

only other flag that may be set is ``GPIOHANDLE_REQUEST_ACTIVE_LOW`` and the

line is requested "as-is" to allow reading of the line value without altering

the electrical configuration.



The drive flags, ``GPIOHANDLE_REQUEST_OPEN_xxx``, require the

``GPIOHANDLE_REQUEST_OUTPUT`` to be set.

Only one drive flag may be set.

If none are set then the line is assumed push-pull.



Only one bias flag, ``GPIOHANDLE_REQUEST_BIAS_xxx``, may be set, and

it requires a direction flag to also be set.

If no bias flags are set then the bias configuration is not changed.



Requesting an invalid configuration is an error (**EINVAL**).



Return Value

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



On success 0 and the :c:type:`request.fd<gpiohandle_request>` contains the

file descriptor for the request.



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

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

Documentation/userspace-api/gpio/gpio-get-lineinfo-ioctl.rst

0 → 100644
+54 −0
Original line number Diff line number Diff line 
.. SPDX-License-Identifier: GPL-2.0



.. _GPIO_GET_LINEINFO_IOCTL:



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

GPIO_GET_LINEINFO_IOCTL

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



.. warning::

    This ioctl is part of chardev_v1.rst and is obsoleted by

    gpio-v2-get-lineinfo-ioctl.rst.



Name

====



GPIO_GET_LINEINFO_IOCTL - Get the publicly available information for a line.



Synopsis

========



.. c:macro:: GPIO_GET_LINEINFO_IOCTL



``int ioctl(int chip_fd, GPIO_GET_LINEINFO_IOCTL, struct gpioline_info *info)``



Arguments

=========



``chip_fd``

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



``info``

    The :c:type:`line_info<gpioline_info>` to be populated, with the

    ``offset`` field set to indicate the line to be collected.



Description

===========



Get the publicly available information for a line.



This information is available independent of whether the line is in use.



.. note::

    The line info does not include the line value.



    The line must be requested using gpio-get-linehandle-ioctl.rst or

    gpio-get-lineevent-ioctl.rst to access its value.



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.