1# Describing pin configs #
2
3This document explains how to generate pin muxing definitions to support pin states for Espressif SoCs. Pin states are consumed by the `pinctrl` subsystem.
4
5It 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.
6
7## Supporting a new SoC ##
8
9When 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.
10
11Let us assume we are supporting `ESP32S2` for the first time. The following commands will do the job:
12
13```sh
14$ cd zephyr/port/pincfgs
15$ vim esp32s2.yml
16```
17
18## Filling `pincfg` files ##
19
20It is easier to explain through an example, for this purpose, let us take `ESP32`'s UART_0 to illustrate:
21
22```yaml
23uart0:
24  tx:
25    sigo: u0txd_out
26    gpio: [[0, 21], [26, 45]]
27  rx:
28    sigi: u0rxd_in
29    gpio: [[0, 21], [26, 46]]
30```
31
32Compare the following description of the required fields in a `{soc}.yaml` file with the above snippet. The bullet indentation follows the original file indentation.
33
34- **`{peripheral}`** (required): concatenation of the peripheral name and its instance number (respectively, `uart` and `0` from the snippet above).
35- **`{periph_sig}`** (required): freely-named field which depends on the target peripheral, `tx` and `rx` above are examples of `periph_sig`.
36    - **`sigo`** (optional): output signal, required if the pin is an output.
37    - **`sigi`** (optional): input signal, required if the pin is an output.
38    - **`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`).
39
40---
41**NOTES**
42
43- 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`).
44- Though the fields `sigi` and `sigo` are optional, at least one of them must be present in the target peripheral.
45- 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.
46- The fields enclosed in `{}` should be replaced by peripheral-specific names.
47- Mind the indentation.
48
49---
50
51## Generating pin muxing information ##
52
53From `zephyr`'s root folder, make sure the variable ZEPHYR_BASE is set
54
55```sh
56echo $ZEPHYR_BASE
57```
58
59If the command doesn't return the current working directory, set it with:
60
61```sh
62export ZEPHYR_BASE=$(pwd)
63```
64
65Run the script (here, using `ESP32-C6` as target):
66
67```sh
68$ ../modules/hal/espressif/zephyr/scripts/pinctrl/esp_genpinctrl.py -p ../modules/hal/espressif/zephyr/port/pincfgs/esp32c6.yml
69```
70
71The pin muxing definitions will be autogenerated and placed at `include/zephyr/dt-bindinds/pinctrl/{soc}-pinctrl.h`.
72
73Use those definitions on your pin states declarations.
74