.. include:: ../substitutions.rst

GPIO
====

General-Purpose Input/Output (GPIO) pins can be configured as either inputs or outputs. Many signals of the |product| SOM can be used as GPIOs through multiplexing. The |soc-caps| processor features three independent GPIO modules.


GPIO Signal Names and Chip Mapping
----------------------------------

GPIOn_x is a generic name used to describe a GPIO signal, where n represents the specific GPIO module and x represents one of the input/output signals associated with the module. Usually you find these names in the schematics and in comments in our device trees in the muxing section.


The |soc-caps| provides three GPIO modules:

  * GPIO0
  * GPIO1
  * MCU_GPIO0

In addition, the TPS65219 PMIC (U6) on the |product| provides three GPIOs, and the |product-cb| provides two TCAL6416 16-bit I2C GPIO expanders (see `GPIO Expanders`_). Linux represents all of these as gpiochips. You can list them using the `gpiodetect` command:

.. jinja::
   :file: ../templates/interfaceguides/gpio-gpiodetect.jinja

The second column shows the hardware address of each GPIO module. In the device tree, these GPIOs are accessed using node labels:

.. jinja::
   :file: ../templates/interfaceguides/gpio-labels.jinja

.. note:: GPIO chip numbers may change between system boots. For consistent numbering, configure udev rules.


GPIO Expanders
--------------

The |product-cb| has two TCAL6416 GPIO expanders, U58 on I2C0 (address 0x21) and U72 on I2C1 (address 0x21). Their lines are named in the device tree, so libgpiod tools can refer to them by name (for example ``gpioget X_RTC_nINT``).

.. list-table:: GPIO Expander Line Names
   :header-rows: 1

   * - Line
     - Expander 1 (U58, I2C0, 0x21)
     - Expander 2 (U72, I2C1, 0x21)
   * - 0
     - VCONN_nFAULT
     - CAN1_STBY
   * - 1
     - X_CSI1_CTRL1
     - CAN2_STBY
   * - 2
     - X_CSI1_CTRL3
     - CAN3_STBY
   * - 3
     - X_CSI1_CTRL4
     - X_KEY-E_nALERT
   * - 4
     - USB-C_nINT/AUDIO_AC
     - X_KEY-M_nALERT
   * - 5
     - X_CSI2_CTRL1
     - X_SDIO_nWAKE
   * - 6
     - X_CSI2_CTRL3
     - X_SDIO_nRESET
   * - 7
     - X_CSI2_CTRL4
     - HDMI_EN
   * - 8
     - CLK_EN_AV
     - X_RTC_nINT
   * - 9
     - X_W_nDISABLE1
     - LVDS1_BL_EN
   * - 10
     - X_W_nDISABLE2
     - SFP_TX_FAULT
   * - 11
     - X_PCIE1_nWAKE
     - SFP_TX_DISABLE
   * - 12
     - X_PCIE2_nWAKE
     - SFP_MOD_ABS
   * - 13
     - X_UART1_nWAKE
     - SFP_RS0
   * - 14
     - UART1_BT_RS_SEL
     - SFP_RX_LOSS
   * - 15
     - UART1_RS232_485_SEL
     - SFP_RS1

.. note:: CAN1_STBY is used by the CAN transceiver driver and is not available from userspace.


Active GPIO Signals
-------------------

The following command shows GPIO signals that are currently allocated by kernel drivers. These GPIOs are already in use and attempting to access them with gpioget or gpioset will result in a "Device or resource busy" error.

See the allocated GPIO signals by running:

.. jinja::
   :file: ../templates/interfaceguides/gpio-debug-out.jinja


Using GPIOs
-----------

To access GPIOs from userspace applications, use the libgpiod library. This library provides tools for interacting with Linux GPIO devices. Here are some common usage examples:

* List all available GPIO chips:

.. jinja::
   :file: ../templates/interfaceguides/gpio-gpiodetect.jinja

* Display detailed GPIO chip information (names, consumers, direction, active state, and flags):

.. code-block:: console
   :substitutions:

   |target-prompt| gpioinfo -c gpiochip2

* Read the value of a GPIO (e.g GPIO 36 from chip2):

.. code-block:: console
   :substitutions:

   |target-prompt| gpioget -c gpiochip2 36

* Set the value of GPIO 36 on chip2 to 0 and exit tool:

.. code-block:: console
   :substitutions:

   |target-prompt| gpioset -z -c gpiochip2 36=0

.. note:: Interacting with a Signal as GPIO requires a proper muxing. The signal needs to be muxed in mux mode 7 (GPIO).

GPIOs via sysfs
---------------

.. warning::
   Accessing GPIOs via sysfs is deprecated. We strongly encourage using libgpiod instead.

Sysfs GPIO access is no longer enabled by default. To enable it, enable `CONFIG_EXPERT` & `CONFIG_GPIO_SYSFS` in the kernel configuration.


Using LEDs
----------

The |product-cb| features an RGB LED (D31) driven by an NXP PCA9633 LED controller (U55) on I2C1 (address 0x62).

.. note::
   The PCA9633 LED driver (``CONFIG_LEDS_PCA963X``) is not enabled in the |release-name| kernel, so the RGB LED cannot be controlled from Linux in this release.

.. jinja::
   :file: ../templates/interfaceguides/gpio-led-button-image.jinja