1# Atmel SAM/SAM0 pin configurations 2 3This directory contains a set of files describing valid pin configurations for 4multiple Atmel Smart Arm MCUs (SAM) devices. This configuration files maps a 5pin to a peripheral signal which multiplex, at end, I/O lines pins. For example, 6`PWMH0` signal can be mapped to `PA0`, `PA11`, `PA23`, `PB0`, `PC18` or `PD20` 7for `SAM4E` SoC. These configurations can be used to generate valid pin 8mappings. 9 10Atmel SAM devices use three distinct controllers to configure signal 11multiplexing: PIO (SAM), GPIO (SAM4L) and PORT (SAM0). In general, all devices 12uses similar definitions where each pin has one or more associated alternate 13function. These alternate functions can be sometimes changed using especific 14system functionality. The struct created to map the alternate functions is 15shared between all controllers and was concepted to be more close possible to 16datasheet tables. 17 18In the following sections the expected file format is described. 19 20## Configuration 21 22All fields are common, independently of the pin controller, and all fields are 23mandatory. 24 25- `model`: Always defined as `atmel,sam` 26- `family`: Family name like: `sam4e`, `sam4l`, `d5x-e5x` 27- `map`: Define the macro that will be used to generate code for an specific 28 controller. Currently `SAM_PINMUX` is used for all cases. 29- `series`: The SoC series set 30- `revisions` (optional): The SoC die revision which exists for sam0 series. 31- `variants`: Each variant has a different set of valid pin combinations because 32 of a different number of pins. 33- `pins` (required): The pin map itself 34 35Example: 36 37The below `yaml` snip have all the common fields defined. It defines few 38aleatory pins to help understand the definition schema. 39 40```yaml 41# Pin codes: 42# 43# - 48 pins: g 44# - 64 pins: j 45# - 100 pins: n 46# - 120/128 pins: p (package exception) 47 48model: atmel,sam 49 50family: d5x-e5x 51 52map: SAM_PINMUX 53 54series: [d51, e51, e53, e54] 55 56revisions: 57 d51: a 58 e51: ab 59 d53: ab 60 d54: abcd 61 62variants: 63 - pincode: g 64 series: [d51, e51] 65 - pincode: j 66 series: [d51, e51, e53] 67 - pincode: n 68 series: [d51, e51, e53, e54] 69 - pincode: p 70 series: [d51, e54] 71 exception: y 72 73pins: 74 pc00: 75 pincodes: [n, p] 76 periph: 77 - [a, eic, extint0] 78 - [b, adc1, ain10] 79 pa24: 80 pincodes: [g, j, n, p] 81 periph: 82 - [a, eic, extint8] 83 - [c, sercom3, pad2] 84 - [d, sercom5, pad2] 85 - [e, tc5, wo0] 86 - [f, tc2, wo2] 87 - [g, pdec, qdi0] 88 - [h, usb, dm] 89 - [i, can0, tx, [d51, e53]] 90 - [n, ccl, in8] 91 pa25: 92 pincodes: [g, j, n, p] 93 periph: 94 - [a, eic, extint9] 95 - [c, sercom3, pad3] 96 - [d, sercom5, pad3] 97 - [e, tc5, wo1] 98 - [g, pdec, qdi1] 99 - [h, usb, dp] 100 - [i, can0, rx, [d51, e53]] 101 - [n, ccl, out2] 102 pa19: 103 pincodes: [g, j, n, p] 104 periph: 105 - [a, eic, extint3] 106 - [b, ptc, xy13] 107 - [c, sercom1, pad3] 108 - [d, sercom3, pad3] 109 - [e, tc3, wo1] 110 - [f, tcc1, wo3] 111 - [g, tcc0, wo7] 112 - [k, pcc, data3] 113 - [l, gmac, gtx1, [d51, e51]] 114 - [m, ac, cmp1] 115 - [n, ccl, out0] 116 pc16: 117 pincodes: [n, p] 118 periph: 119 - [a, eic, extint0] 120 - [c, sercom6, pad0] 121 - [d, sercom0, pad1] 122 - [f, tcc0, wo0] 123 - [g, pdec, qdi0] 124 - [l, gmac, gtx2, [d51, e51]] 125``` 126 127The `series` key define a list of SoC models `[d51, e51, e53, e54]`. This list 128is used to generate file names and map peripherals. 129 130Some sam0 SoC have optimized pins in some revisions. To differentiate those a 131new mux table should be defined. The `revisions` help to identify correct 132pinctrl files by sufix. 133 134The `variants` key define a list of available packages by SoC series. This means 135that for `pincode: g`, which is 48 pins packages, there are valid combination 136of `samd51g` and `samde51g` pin mux. Note, some devices my present some 137chalenges like define a part number which uses same pin code with different 138pin counts. For that ones, we add `exception: y` property. The exception will 139add a `WARNING` message to uses in the auto generated file asking to user look 140datasheet. Any variation with exception must map all pins to allow users access 141functionality. 142 143The `pins` section is a vaiable length list of pin definitions. Each entry is 144a pin itself composed by one mandatory properties which is `pincodes` and many 145optional properties: `periph`, `extra`, `system`, `lpm`. The `pincode` instructs 146the engine to generate pin definitions only for those packages were pin is, in 147fact, available. The `periph` is the set of multiplexed peripheral signals. It 148is a variable length list where each entry is a list. Each peripheral list 149entry is composed of 4 fields, where the first 3 are mandatory. The peripheral 150list represents: 151 - `alternate function index` 152 - `peripheral [instance]` 153 - `signal` 154 - `SoC/pincode exclusion list` (optional) 155 156Additionaly some SoCs define special pin configuration. In the datasheet user 157can find a column named `extra` and another as `systems`. The syntax is the 158same as `periph`. The `lpm` is reserved for future use. Some SoCs may require 159special pin configuration to allow system consume less possible power. 160 161Example: 162 163At below `yaml` snip code defines `pc16` pin: 164 165```yaml 166 pc16: 167 pincodes: [n, p] 168 periph: 169 - [a, eic, extint0] 170 - [c, sercom6, pad0] 171 - [d, sercom0, pad1] 172 - [f, tcc0, wo0] 173 - [g, pdec, qdi0] 174 - [l, gmac, gtx2, [d51, e51]] 175``` 176 177This means, that port `C` pin 16 is available for packages `n` and `p`. The 178alternate function available for these pin is that: 179 - at position `a` the `eic` controller have access to signal `extint0` 180 - at position `c` the signal `pad0` can be defined for `sercom6` 181 - at position `d` the signal `pad1` can be defined for `sercom0` 182 - at position `f` the `tcc0` can output signal `wo0` 183 - at position `g` the `pdec` uses `qdi0` as quadrature input 0. 184 - at position `l` the `gmac` define signal `gtx2` which won't be available for 185 SoC `d51` and `e51`. 186 187In this case, besides `n` and `p` packages tells to engine that pin `pc16` must 188be generated for the entire SoC series `d51, e51, e53, e54` the engine allows 189to deliberate exclude some signal combination. 190 191The exclusion list can have both SoC `series` and `pincodes`. This allow create 192less files and give better granularity. The next example shows how to drop `smc` 193functionality in the `SAM4E` SoC. In this case, only one series can accomodate 194all variations and the tunning is made using `pincode` at periph config. 195 196```yaml 197# Pin codes: 198# 199# - 100 pins: c 200# - 144 pins: e 201 202model: atmel,sam 203 204family: sam4e 205 206map: SAM_PINMUX 207 208series: [4eX] 209 210variants: 211 - pincode: c 212 series: [4eX] 213 - pincode: e 214 series: [4eX] 215 216pins: 217 pa0: 218 pincodes: [c, e] 219 periph: 220 - [a, pwm, pwmh0] 221 - [b, tc0, tioa0] 222 - [c, smc, a17, [c]] 223 - [d, supc, wkup0] 224``` 225 226It is recommended use one filter at exclusion list. When necessary combine both 227`series` and `pincodes` the exclusion will operate first in the series and then 228will lookup by pincode. 229 230The next example shows how to specify `extra` function and `system` functions. 231 232```yaml 233 pb5: 234 pincodes: [c, e] 235 periph: 236 - [a, twi1, twck1] 237 - [b, pwm, pwml0] 238 extra: 239 - [x, supc, wkup13] 240 system: 241 - [s, jtag, tdo] 242 - [s, swd, traceswo] 243``` 244 245## Auto Generated Code 246 247After define all pins the user should run `scripts/sampinctrl.py` script to 248auto generate Zephyr RTOS devicetree pinctrl definitions. See `scripts/README` 249for instructions how to do it. 250 251### Output Format 252 253The output format define constants to be used inside devitree pins definitions, 254see below snip of output: 255 256```c 257/* 258 * Autogenerated file 259 * 260 * SPDX-License-Identifier: Apache-2.0 261 */ 262 263#include <dt-bindings/pinctrl/atmel_sam_pinctrl.h> 264 265/* 266 * WARNING: this variant has package exception. 267 * 268 * Read datasheet topics related to I/O Multiplexing and Considerations or 269 * Peripheral Signal Multiplexing on I/O Lines for more information. 270 */ 271 272/* pa0a_eic_extint0 */ 273#define PA0A_EIC_EXTINT0 \ 274 SAM_PINMUX(a, 0, a, periph) 275``` 276 277The output format uses the compressed representation which of: 278 - port index (PIOx, GPIOx or PORTx) 279 - pin number 280 - alternate function index 281 - function (gpio, periph, extra, system, lpm) 282 283In this case `PA0A_EIC_EXTINT0` is at PORT `a` pin `0` using alternate 284function `a`, which selects pin for external interrupt controller `EIC` 285interrupt `extint0`. 286 287 288## Devicetree definitions 289 290The pinctrl devicetree entries follow current Zephyr RTOS conventions. See 291below example which define serial console for `atsame54_xpro` board. 292 293```devicetree 294#include <dt-bindings/pinctrl/same54p-pinctrl.h> 295 296&pinctrl { 297 sercom2_usart_default: sercom2_usart_default { 298 group1 { 299 pinmux = <PB25D_SERCOM2_PAD1>, <PB24D_SERCOM2_PAD0>; 300 }; 301 }; 302}; 303 304&sercom2 { 305 status = "okay"; 306 compatible = "atmel,sam0-uart"; 307 current-speed = <115200>; 308 rxpo = <1>; 309 txpo = <0>; 310 #address-cells = <1>; 311 #size-cells = <0>; 312 313 pinctrl-0 = <&sercom2_usart_default>; 314 pinctrl-names = "default"; 315}; 316``` 317
