From cb5f47e56eec6c5cf0db0d8264b702a9ee9904f2 Mon Sep 17 00:00:00 2001 From: Michal Lenc Date: Thu, 6 Nov 2025 16:52:02 +0100 Subject: [PATCH] documentation: add GPIO character device driver entry This page describes GPIO character device driver and its API. Signed-off-by: Michal Lenc --- .../components/drivers/character/gpio.rst | 161 ++++++++++++++++++ .../components/drivers/character/index.rst | 1 + 2 files changed, 162 insertions(+) create mode 100644 Documentation/components/drivers/character/gpio.rst diff --git a/Documentation/components/drivers/character/gpio.rst b/Documentation/components/drivers/character/gpio.rst new file mode 100644 index 00000000000..1728b0f378b --- /dev/null +++ b/Documentation/components/drivers/character/gpio.rst @@ -0,0 +1,161 @@ +============ +GPIO Drivers +============ + +- ``include/nuttx/ioexpander/gpio.h``. All structures and APIs needed + to work with GPIO pins as drivers are provided in this header file. This + header file includes: + + #. Structures and interface descriptions needed to develop a + low-level, board-specific, GPIO driver. + #. To register the GPIO driver with a common GPIO character + driver. + #. Interfaces needed for interfacing user programs with the + common GPIO character driver. + +- ``drivers/ioexpander/gpio.c``. The implementation of the common GPIO + character driver. + +Application Programming Interface +================================= + +The Application Programming Interface is included in the application with +the following header file. + + +.. code-block:: c + + #include + +A GPIO pin is either an input pin or an output pin. + +One GPIO pin is registered as a POSIX character device file into ``/dev`` +namespace. It is necessary to open the device to get a file descriptor for +further operations. This can be done with standard POSIX ``open()`` call. +Only one pir per driver is supported by the peripheral. + +Standard POSIX ``read()`` and ``write()`` operations are not allowed for GPIO +based drivers. All interface is routed through IOCTL calls. Following commands +are supported: + + * :c:macro:`GPIOC_WRITE` + * :c:macro:`GPIOC_READ` + * :c:macro:`GPIOC_PINTYPE` + * :c:macro:`GPIOC_REGISTER` + * :c:macro:`GPIOC_UNREGISTER` + * :c:macro:`GPIOC_SETPINTYPE` + + +.. c:macro:: GPIOC_WRITE + +The ``GPIOC_WRITE`` command sets the value of an output GPIO. The argument +is either 0 (set low value) or 1 (set high value). It is possible to write +to output pins only. Typical use case is: + +.. code-block:: c + + bool value = true; + int ret = ioctl(fd, GPIOC_WRITE, value); + + +.. c:macro:: GPIOC_READ + +The ``GPIOC_READ`` command reads the value of a GPIO. The argument +is a pointer to a bool value to receive the result. The result is either 0 +(low value) or 1 (high value). It is possible to read from both input and +output pins. The currently set value is returned in case the pin is output +pin. Typical use case is: + +.. code-block:: c + + bool value; + int ret = ioctl(fd, GPIOC_READ, (unsigned long)(uintptr_t)&value); + +.. c:macro:: GPIOC_PINTYPE + +The ``GPIOC_PINTYPE`` command gets the type of GPIO pin. The argument +is a pointer to an instance of type :c:enum:`gpio_pintype_e`. + +.. code-block:: c + + enum gpio_pintype_e + { + GPIO_INPUT_PIN = 0, /* float */ + GPIO_INPUT_PIN_PULLUP, + GPIO_INPUT_PIN_PULLDOWN, + GPIO_OUTPUT_PIN, /* push-pull */ + GPIO_OUTPUT_PIN_OPENDRAIN, + GPIO_INTERRUPT_PIN, + GPIO_INTERRUPT_HIGH_PIN, + GPIO_INTERRUPT_LOW_PIN, + GPIO_INTERRUPT_RISING_PIN, + GPIO_INTERRUPT_FALLING_PIN, + GPIO_INTERRUPT_BOTH_PIN, + GPIO_INTERRUPT_PIN_WAKEUP, + GPIO_INTERRUPT_HIGH_PIN_WAKEUP, + GPIO_INTERRUPT_LOW_PIN_WAKEUP, + GPIO_INTERRUPT_RISING_PIN_WAKEUP, + GPIO_INTERRUPT_FALLING_PIN_WAKEUP, + GPIO_INTERRUPT_BOTH_PIN_WAKEUP, + GPIO_NPINTYPES + }; + +.. c:macro:: GPIOC_REGISTER + +The ``GPIOC_REGISTER`` command registers a pin to receive a signal whenever +there is an interrupt received on an input GPIO pin. This feature, of course, +depends upon interript GPIO support in the platform specific code. Please +refer to the documentation describing your target platform for futher +information. The argument is the pointer to :c:type:`sigevent` value, a signal +to be generated when the interrupt occurs. + +Typical use case is following: + +.. code-block:: c + + struct sigevent notify; + + notify.sigev_notify = SIGEV_SIGNAL; + notify.sigev_signo = SIGUSR1; + + int ret = ioctl(fd, GPIOC_REGISTER, (unsigned long)¬ify); + +.. c:macro:: GPIOC_UNREGISTER + +The ``GPIOC_UNREGISTER`` command unresigters a pin and stop receiving signals +for pin interrupt. + +.. c:macro:: GPIOC_SETPINTYPE + +The ``GPIOC_SETPINTYPE`` command can be used to change the GPIO pin type +(from input pin to output pin, changing interrupt edges and similar). The +types to set are listed in :c:enum:`gpio_pintype_e`. + +Application Example +~~~~~~~~~~~~~~~~~~~ + +An example application can be found in ``nuttx-apps`` repository under +path ``examples/gpio``. It is an example application that allows you +to read, write or configure GPIO pins. + +Configuration +============= + +This section describes GPIO driver configuration in ``Kconfig``. The reader +should refer to target documentation for target specific configuration. + +GPIO peripheral is enabled by ``CONFIG_DEV_GPIO``. Option +``CONFIG_DEV_NPOLLWAITERS`` is used to specify the maximum number of threads +that can be waiting on poll with default set to one. It is also possible +to register signals with the GPIO driver. The number of allowed signals +is configured with ``CONFIG_DEV_NSIGNALS``. + +IO Expander Device Drivers +========================== + +IO Expander device drivers are chips that provides more GPIO pins, usually +connected to the MCU with SPI or I2C bus. It is possible to register +individual GPIO pins of the expander as a separate pins if needed. This +option is enabled by ``CONFIG_GPIO_LOWER_HALF`` option. Please refer +to `ioexpander documentation `_ +for more description. diff --git a/Documentation/components/drivers/character/index.rst b/Documentation/components/drivers/character/index.rst index 6bf18ac0256..ab597a36a72 100644 --- a/Documentation/components/drivers/character/index.rst +++ b/Documentation/components/drivers/character/index.rst @@ -62,6 +62,7 @@ Character device drivers have these properties: crypto/index.rst eeprom.rst efuse.rst + gpio.rst i2s.rst input/index.rst ipcc.rst