docs: gpio: Add GPIO docs

Add more complete documentation page for GPIO

Signed-off-by: Benjamin Cabé <[email protected]>

Author: kartben

doc/hardware/peripherals/gpio.rst

@@ -1,18 +1,148 @@
 .. _gpio_api:
 
-
 General-Purpose Input/Output (GPIO)
 ###################################
 
 Overview
 ********
 
+The GPIO API provides a generic method to interact with General Purpose Input/Output (GPIO)
+pins. It allows applications to configure pins as inputs or outputs, read and write
+their state, and manage interrupts. Key features include:
+
+**Pin Configuration**
+  Configure pins as input, output, or disconnected.
+  Support for internal pull-up/pull-down resistors and drive strength configuration.
+
+**Data Access**
+  Read input values and write output values.
+
+**Interrupts**
+  Configure interrupts on pin state changes (rising edge, falling edge,
+  level low, level high) and register callbacks to handle these interrupts.
+
+**Devicetree Integration**
+  GPIOs are typically defined in the Devicetree, allowing
+  drivers and applications to reference them in a hardware-agnostic way using
+  :c:struct:`gpio_dt_spec`.
+
+Devicetree Configuration
+************************
+
+GPIO controllers are defined in the Devicetree as nodes with the ``gpio-controller`` property.
+The ``#gpio-cells`` property typically specifies that 2 cells are used to describe a GPIO: the pin
+number and the flags.
+
+Example of a GPIO controller definition:
+
+.. code-block:: devicetree
+
+   gpio0: gpio@40022000 {
+       compatible = "ti,cc13xx-cc26xx-gpio";
+       reg = <0x40022000 0x400>;
+       interrupts = <0 0>;
+       gpio-controller;
+       #gpio-cells = <2>;
+   };
+
+Example of referencing a GPIO:
+
+.. code-block:: devicetree
+
+   leds {
+       compatible = "gpio-leds";
+       led0: led_0 {
+           gpios = <&gpio0 25 GPIO_ACTIVE_HIGH>;
+           label = "Green LED";
+       };
+   };
+
+Basic Operation
+***************
+
+GPIO operations are usually performed on a :c:struct:`gpio_dt_spec` structure, which is a container
+for the GPIO pin information specified in the Devicetree.
+
+This structure is typically populated using :c:macro:`GPIO_DT_SPEC_GET` macro (or any of its
+variants).
+
+.. code-block:: c
+   :caption: Populating a gpio_dt_spec structure for a GPIO pin defined as alias ``led0``
+
+   #define LED0_NODE DT_ALIAS(led0)
+   static const struct gpio_dt_spec led = GPIO_DT_SPEC_GET(LED0_NODE, gpios);
+
+The :c:struct:`gpio_dt_spec` structure can then be used to perform GPIO operations.
+
+.. code-block:: c
+   :caption: Configuring a GPIO pin (``led`` from the previous snippet) as output and setting it
+             to its active level
+
+   int ret;
+
+   ret = gpio_pin_configure_dt(&led, GPIO_OUTPUT_ACTIVE);
+   if (ret < 0) {
+       return ret;
+   }
+
+   ret = gpio_pin_set_dt(&led, 1);
+   if (ret < 0) {
+       return ret;
+   }
+
+Refer to :zephyr:code-sample:`blinky` for a complete example of basic operations on GPIOs using the
+:c:struct:`gpio_dt_spec` structure.
+
+GPIO operations can also be performed directly on a GPIO controller device, in which case you will
+use the GPIO API functions that take a device pointer as an argument. For example
+:c:func:`gpio_pin_configure` instead of :c:func:`gpio_pin_configure_dt`.
+
+GPIO Hogs
+*********
+
+GPIO hogs provide a mechanism to automatically configure GPIO pins during system initialization.
+This is useful for pins that need to be set to a specific state (e.g., reset lines, power enables)
+and don't require runtime control by an application.
+
+Hogs are defined in the Devicetree as children of a GPIO controller node.
+
+- The ``gpio-hog`` property marks the node as a hog.
+- The ``gpios`` property specifies the pin and its active state.
+- One of ``input``, ``output-low``, or ``output-high`` properties specifies the configuration.
+
+Example Devicetree overlay:
+
+.. code-block:: devicetree
+
+   &gpio0 {
+       hog1 {
+           gpio-hog;
+           gpios = <1 GPIO_ACTIVE_LOW>;
+           output-high;
+       };
+
+       hog2 {
+           gpio-hog;
+           gpios = <2 GPIO_ACTIVE_HIGH>;
+           output-low;
+       };
+   };
+
+If you need runtime control of a pin configured as a hog beyond the initial state being
+automatically set during system initialization, you may consider using the :ref:`regulator_api`
+instead, with a :dtcompatible:`regulator-fixed` Devicetree node.
+
 Configuration Options
 *********************
 
-Related configuration options:
+Main configuration options:
 
 * :kconfig:option:`CONFIG_GPIO`
+* :kconfig:option:`CONFIG_GPIO_SHELL`
+* :kconfig:option:`CONFIG_GPIO_GET_DIRECTION`
+* :kconfig:option:`CONFIG_GPIO_GET_CONFIG`
+* :kconfig:option:`CONFIG_GPIO_HOGS`
+* :kconfig:option:`CONFIG_GPIO_ENABLE_DISABLE_INTERRUPT`
 
 API Reference
 *************