pinctrl: pinconfigs: Add README file

Add documentation that describes how to create pinconfigs files.

Signed-off-by: Gerson Fernando Budke <[email protected]>

Author: nandojve

pinconfigs/README.md

@@ -0,0 +1,316 @@
+# Atmel SAM pin configurations
+
+This directory contains a set of files describing valid pin configurations for
+multiple Atmel Smart Arm MCUs (SAM) devices. This configuration files maps a
+pin to a peripheral signal which multiplex, at end, I/O lines pins. For example,
+`PWMH0` signal can be mapped to `PA0`, `PA11`, `PA23`, `PB0`, `PC18` or `PD20`
+for `SAM4E` SoC. These configurations can be used to generate valid pin
+mappings.
+
+Atmel SAM devices use three distinct controllers to configure signal
+multiplexing: PIO (SAM), GPIO (SAM4L) and PORT (SAM0). In general, all devices
+uses similar definitions where each pin has one or more associated alternate
+function. These alternate functions can be sometimes changed using especific
+system functionality. The struct created to map the alternate functions is
+shared between all controllers and was concepted to be more close possible to
+datasheet tables.
+
+In the following sections the expected file format is described.
+
+## Configuration
+
+All fields are common, independently of the pin controller, and all fields are
+mandatory.
+
+- `model`: Always defined as `atmel,sam`
+- `family`: Family name like: `sam4e`, `sam4l`, `d5x-e5x`
+- `map`: Define the macro that will be used to generate code for an specific
+  controller. Currently `SAM_PINMUX` is used for all cases.
+- `series`: The SoC series set
+- `revisions` (optional): The SoC die revision which exists for sam0 series.
+- `variants`: Each variant has a different set of valid pin combinations because
+  of a different number of pins.
+- `pins` (required): The pin map itself
+
+Example:
+
+The below `yaml` snip have all the common fields defined. It defines few
+aleatory pins to help understand the definition schema.
+
+```yaml
+# Pin codes:
+#
+# - 48      pins: g
+# - 64      pins: j
+# - 100     pins: n
+# - 120/128 pins: p (package exception)
+
+model: atmel,sam
+
+family: d5x-e5x
+
+map: SAM_PINMUX
+
+series: [d51, e51, e53, e54]
+
+revisions:
+  d51: a
+  e51: ab
+  d53: ab
+  d54: abcd
+
+variants:
+  - pincode: g
+    series: [d51, e51]
+  - pincode: j
+    series: [d51, e51, e53]
+  - pincode: n
+    series: [d51, e51, e53, e54]
+  - pincode: p
+    series: [d51, e54]
+    exception: y
+
+pins:
+  pc00:
+    pincodes: [n, p]
+    periph:
+      - [a, eic, extint0]
+      - [b, adc1, ain10]
+  pa24:
+    pincodes: [g, j, n, p]
+    periph:
+      - [a, eic, extint8]
+      - [c, sercom3, pad2]
+      - [d, sercom5, pad2]
+      - [e, tc5, wo0]
+      - [f, tc2, wo2]
+      - [g, pdec, qdi0]
+      - [h, usb, dm]
+      - [i, can0, tx, [d51, e53]]
+      - [n, ccl, in8]
+  pa25:
+    pincodes: [g, j, n, p]
+    periph:
+      - [a, eic, extint9]
+      - [c, sercom3, pad3]
+      - [d, sercom5, pad3]
+      - [e, tc5, wo1]
+      - [g, pdec, qdi1]
+      - [h, usb, dp]
+      - [i, can0, rx, [d51, e53]]
+      - [n, ccl, out2]
+  pa19:
+    pincodes: [g, j, n, p]
+    periph:
+      - [a, eic, extint3]
+      - [b, ptc, xy13]
+      - [c, sercom1, pad3]
+      - [d, sercom3, pad3]
+      - [e, tc3, wo1]
+      - [f, tcc1, wo3]
+      - [g, tcc0, wo7]
+      - [k, pcc, data3]
+      - [l, gmac, gtx1, [d51, e51]]
+      - [m, ac, cmp1]
+      - [n, ccl, out0]
+  pc16:
+    pincodes: [n, p]
+    periph:
+      - [a, eic, extint0]
+      - [c, sercom6, pad0]
+      - [d, sercom0, pad1]
+      - [f, tcc0, wo0]
+      - [g, pdec, qdi0]
+      - [l, gmac, gtx2, [d51, e51]]
+```
+
+The `series` key define a list of SoC models `[d51, e51, e53, e54]`. This list
+is used to generate file names and map peripherals.
+
+Some sam0 SoC have optimized pins in some revisions. To differentiate those a
+new mux table should be defined. The `revisions` help to identify correct
+pinctrl files by sufix.
+
+The `variants` key define a list of available packages by SoC series. This means
+that for `pincode: g`, which is 48 pins packages, there are valid combination
+of `samd51g` and `samde51g` pin mux. Note, some devices my present some
+chalenges like define a part number which uses same pin code with different
+pin counts. For that ones, we add `exception: y` property. The exception will
+add a `WARNING` message to uses in the auto generated file asking to user look
+datasheet. Any variation with exception must map all pins to allow users access
+functionality.
+
+The `pins` section is a vaiable length list of pin definitions. Each entry is
+a pin itself composed by one mandatory properties which is `pincodes` and many
+optional properties: `periph`, `extra`, `system`, `lpm`. The `pincode` instructs
+the engine to generate pin definitions only for those packages were pin is, in
+fact, available. The `periph` is the set of multiplexed peripheral signals. It
+is a variable length list where each entry is a list. Each peripheral list
+entry is composed of 4 fields, where the first 3 are mandatory. The peripheral
+list represents:
+ - `alternate function index`
+ - `peripheral [instance]`
+ - `signal`
+ - `SoC/pincode exclusion list` (optional)
+
+Additionaly some SoCs define special pin configuration. In the datasheet user
+can find a column named `extra` and another as `systems`. The syntax is the
+same as `periph`. The `lpm` is reserved for future use. Some SoCs may require
+special pin configuration to allow system consume less possible power.
+
+Example:
+
+At below `yaml` snip code defines `pc16` pin:
+
+```yaml
+  pc16:
+    pincodes: [n, p]
+    periph:
+      - [a, eic, extint0]
+      - [c, sercom6, pad0]
+      - [d, sercom0, pad1]
+      - [f, tcc0, wo0]
+      - [g, pdec, qdi0]
+      - [l, gmac, gtx2, [d51, e51]]
+```
+
+This means, that port `C` pin 16 is available for packages `n` and `p`. The
+alternate function available for these pin is that:
+ - at position `a` the `eic` controller have access to signal `extint0`
+ - at position `c` the signal `pad0` can be defined for `sercom6`
+ - at position `d` the signal `pad1` can be defined for `sercom0`
+ - at position `f` the `tcc0` can output signal `wo0`
+ - at position `g` the `pdec` uses `qdi0` as quadrature input 0.
+ - at position `l` the `gmac` define signal `gtx2` which won't be available for
+   SoC `d51` and `e51`.
+
+In this case, besides `n` and `p` packages tells to engine that pin `pc16` must
+be generated for the entire SoC series `d51, e51, e53, e54` the engine allows
+to deliberate exclude some signal combination.
+
+The exclusion list can have both SoC `series` and `pincodes`. This allow create
+less files and give better granularity. The next example shows how to drop `smc`
+functionality in the `SAM4E` SoC. In this case, only one series can accomodate
+all variations and the tunning is made using `pincode` at periph config.
+
+```yaml
+# Pin codes:
+#
+# - 100 pins: c
+# - 144 pins: e
+
+model: atmel,sam
+
+family: sam4e
+
+map: SAM_PINMUX
+
+series: [4eX]
+
+variants:
+  - pincode: c
+    series: [4eX]
+  - pincode: e
+    series: [4eX]
+
+pins:
+  pa0:
+    pincodes: [c, e]
+    periph:
+      - [a, pwm, pwmh0]
+      - [b, tc0, tioa0]
+      - [c, smc, a17, [c]]
+      - [d, supc, wkup0]
+```
+
+It is recommended use one filter at exclusion list. When necessary combine both
+`series` and `pincodes` the exclusion will operate first in the series and then
+will lookup by pincode.
+
+The next example shows how to specify `extra` function and `system` functions.
+
+```yaml
+  pb5:
+    pincodes: [c, e]
+    periph:
+      - [a, twi1, twck1]
+      - [b, pwm, pwml0]
+    extra:
+      - [x, supc, wkup13]
+    system:
+      - [s, jtag, tdo]
+      - [s, swd, traceswo]
+```
+
+## Auto Generated Code
+
+After define all pins the user should run `scripts/sampinctrl.py` script to
+auto generate Zephyr RTOS devicetree pinctrl definitions. See `scripts/README`
+for instructions how to do it.
+
+### Output Format
+
+The output format define constants to be used inside devitree pins definitions,
+see below snip of output:
+
+```c
+/*
+ * Autogenerated file
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <dt-bindings/pinctrl/atmel_sam_pinctrl.h>
+
+/*
+ * WARNING: this variant has package exception.
+ *
+ *   Read datasheet topics related to I/O Multiplexing and Considerations or
+ *   Peripheral Signal Multiplexing on I/O Lines for more information.
+ */
+
+/* pa0a_eic_extint0 */
+#define PA0A_EIC_EXTINT0 \
+	SAM_PINMUX(a, 0, a, periph)
+```
+
+The output format uses the compressed representation which of:
+ - port index (PIOx, GPIOx or PORTx)
+ - pin number
+ - alternate function index
+ - function (gpio, periph, extra, system, lpm)
+
+In this case `PA0A_EIC_EXTINT0` is at PORT `a` pin `0` using alternate
+function `a`, which selects pin for external interrupt controller `EIC`
+interrupt `extint0`.
+
+
+## Devicetree definitions
+
+The pinctrl devicetree entries follow current Zephyr RTOS conventions. See
+below example which define serial console for `atsame54_xpro` board.
+
+```devicetree
+#include <dt-bindings/pinctrl/same54p-pinctrl.h>
+
+&pinctrl {
+	sercom2_usart_default: sercom2_usart_default {
+		group1 {
+			pinmux = <PB25D_SERCOM2_PAD1>, <PB24D_SERCOM2_PAD0>;
+		};
+	};
+};
+
+&sercom2 {
+	status = "okay";
+	compatible = "atmel,sam0-uart";
+	current-speed = <115200>;
+	rxpo = <1>;
+	txpo = <0>;
+	#address-cells = <1>;
+	#size-cells = <0>;
+
+	pinctrl-0 = <&sercom2_usart_default>;
+	pinctrl-names = "default";
+};
+```