# Describing pin configs #

This document explains how to generate pin muxing definitions to support pin states for Espressif SoCs. Pin states are consumed by the `pinctrl` subsystem.

It is initially meant to be a reference to `hal_espressif` contributors only, though the outcomes of this work can be overlayed by Zephyr RTOS users basing its applications on our SoCs.

## Supporting a new SoC ##

When supporting a new SoC, create a _yaml_ file under `zephyr/port/pincfgs` named with the lowercased SoC name (e.g., `esp32.yml` for `ESP32`). Pin muxing information will be derived from this file to support pin states description.

Let us assume we are supporting `ESP32S2` for the first time. The following commands will do the job:

```sh
$ cd zephyr/port/pincfgs
$ vim esp32s2.yml
```

## Filling `pincfg` files ##

It is easier to explain through an example, for this purpose, let us take `ESP32`'s UART_0 to illustrate:

```yaml
uart0:
  tx:
    sigo: u0txd_out
    gpio: [[0, 21], [26, 45]]
  rx:
    sigi: u0rxd_in
    gpio: [[0, 21], [26, 46]]
```

Compare the following description of the required fields in a `{soc}.yaml` file with the above snippet. The bullet indentation follows the original file indentation.

- **`{peripheral}`** (required): concatenation of the peripheral name and its instance number (respectively, `uart` and `0` from the snippet above).
- **`{periph_sig}`** (required): freely-named field which depends on the target peripheral, `tx` and `rx` above are examples of `periph_sig`.
    - **`sigo`** (optional): output signal, required if the pin is an output.
    - **`sigi`** (optional): input signal, required if the pin is an output.
    - **`gpio`** (required): array composed of __integers__ and/or __2-sized arrays of integers__. Integer elements represent a pin number (e.g., `1` means `GPIO1`) while a 2-sized array represents a pin number range (e.g., `[0, 21]` means `GPIO0`, `GPIO1`, ... , `GPIO21`).

---
**NOTES**

- The values for the fields `sigi` and `sigo` must be borrowed from `include/zephyr/dt-bindings/pinctrl/{soc}-gpio-sigmap.h` file. Drop the `ESP_` prefix and lowercase the result (e.g., `ESP_U0TXD_OUT` becomes `u0txd_out`).
- Though the fields `sigi` and `sigo` are optional, at least one of them must be present in the target peripheral.
- If the `gpio` field is formed by either only one pin number or only one pin number range, in any case, enclosing in `[]` is still required, remember, the script expects an array. Failing to do so, may lead to unintended states generation. For example, `[0, 19]` is **not** the same as `[[0, 19]]`. The last generates a pin range information, while the former generates for `GPIO0` and `GPIO19` only.
- The fields enclosed in `{}` should be replaced by peripheral-specific names.
- Mind the indentation.

---

## Generating pin muxing information ##

From `zephyr`'s root folder, make sure the variable ZEPHYR_BASE is set

```sh
echo $ZEPHYR_BASE
```

If the command doesn't return the current working directory, set it with:

```sh
export ZEPHYR_BASE=$(pwd)
```

Run the script (here, using `ESP32-C6` as target):

```sh
$ ../modules/hal/espressif/zephyr/scripts/pinctrl/esp_genpinctrl.py -p ../modules/hal/espressif/zephyr/port/pincfgs/esp32c6.yml
```

The pin muxing definitions will be autogenerated and placed at `include/zephyr/dt-bindinds/pinctrl/{soc}-pinctrl.h`.

Use those definitions on your pin states declarations.