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 variable 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`, `wakeup`. The `pincode` 146instructs the engine to generate pin definitions only for those packages were 147pin is, in fact, available. The `periph` is the set of multiplexed peripheral 148signals. It is a variable length list where each entry is a list. Each peripheral 149list entry 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 156Additionally 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. The 160special `wakeup` pin definition configure the pin to be used to wake-up the 161core power supply, see Supply Controller SUPC for more details. 162 163Example: 164 165At below `yaml` snip code defines `pc16` pin: 166 167```yaml 168 pc16: 169 pincodes: [n, p] 170 periph: 171 - [a, eic, extint0] 172 - [c, sercom6, pad0] 173 - [d, sercom0, pad1] 174 - [f, tcc0, wo0] 175 - [g, pdec, qdi0] 176 - [l, gmac, gtx2, [d51, e51]] 177``` 178 179This means, that port `C` pin 16 is available for packages `n` and `p`. The 180alternate function available for these pin is that: 181 - at position `a` the `eic` controller have access to signal `extint0` 182 - at position `c` the signal `pad0` can be defined for `sercom6` 183 - at position `d` the signal `pad1` can be defined for `sercom0` 184 - at position `f` the `tcc0` can output signal `wo0` 185 - at position `g` the `pdec` uses `qdi0` as quadrature input 0. 186 - at position `l` the `gmac` define signal `gtx2` which won't be available for 187 SoC `d51` and `e51`. 188 189In this case, besides `n` and `p` packages tells to engine that pin `pc16` must 190be generated for the entire SoC series `d51, e51, e53, e54` the engine allows 191to deliberate exclude some signal combination. 192 193The exclusion list can have both SoC `series` and `pincodes`. This allow create 194less files and give better granularity. The next example shows how to drop `smc` 195functionality in the `SAM4E` SoC. In this case, only one series can accomodate 196all variations and the tunning is made using `pincode` at periph config. 197 198```yaml 199# Pin codes: 200# 201# - 100 pins: c 202# - 144 pins: e 203 204model: atmel,sam 205 206family: sam4e 207 208map: SAM_PINMUX 209 210series: [4eX] 211 212variants: 213 - pincode: c 214 series: [4eX] 215 - pincode: e 216 series: [4eX] 217 218pins: 219 pa0: 220 pincodes: [c, e] 221 periph: 222 - [a, pwm, pwmh0] 223 - [b, tc0, tioa0] 224 - [c, smc, a17, [c]] 225``` 226 227It is recommended use one filter at exclusion list. When necessary combine both 228`series` and `pincodes` the exclusion will operate first in the series and then 229will lookup by pincode. 230 231The next example shows how to specify `extra`, `wakeup` and `system` functions. 232 233```yaml 234 pb5: 235 pincodes: [c, e] 236 periph: 237 - [a, twi1, twck1] 238 - [b, pwm, pwml0] 239 extra: 240 - [x, adc, ad3] 241 wakeup: 242 - [x, supc, wkup13] 243 system: 244 - [s, jtag, tdo] 245 - [s, swd, traceswo] 246``` 247 248## Auto Generated Code 249 250After define all pins the user should run `scripts/sampinctrl.py` script to 251auto generate Zephyr RTOS devicetree pinctrl definitions. See `scripts/README` 252for instructions how to do it. 253 254### Output Format 255 256The output format define constants to be used inside devitree pins definitions, 257see below snip of output: 258 259```c 260/* 261 * Autogenerated file 262 * 263 * SPDX-License-Identifier: Apache-2.0 264 */ 265 266#include <dt-bindings/pinctrl/atmel_sam_pinctrl.h> 267 268/* 269 * WARNING: this variant has package exception. 270 * 271 * Read datasheet topics related to I/O Multiplexing and Considerations or 272 * Peripheral Signal Multiplexing on I/O Lines for more information. 273 */ 274 275/* pa0a_eic_extint0 */ 276#define PA0A_EIC_EXTINT0 \ 277 SAM_PINMUX(a, 0, a, periph) 278``` 279 280The output format uses the compressed representation which of: 281 - port index (PIOx, GPIOx or PORTx) 282 - pin number 283 - alternate function index 284 - function (gpio, periph, extra, system, lpm) 285 286In this case `PA0A_EIC_EXTINT0` is at PORT `a` pin `0` using alternate 287function `a`, which selects pin for external interrupt controller `EIC` 288interrupt `extint0`. 289 290 291## Devicetree definitions 292 293The pinctrl devicetree entries follow current Zephyr RTOS conventions. See 294below example which define serial console for `atsame54_xpro` board. 295 296```devicetree 297#include <dt-bindings/pinctrl/same54p-pinctrl.h> 298 299&pinctrl { 300 sercom2_usart_default: sercom2_usart_default { 301 group1 { 302 pinmux = <PB25D_SERCOM2_PAD1>, <PB24D_SERCOM2_PAD0>; 303 }; 304 }; 305}; 306 307&sercom2 { 308 status = "okay"; 309 compatible = "atmel,sam0-uart"; 310 current-speed = <115200>; 311 rxpo = <1>; 312 txpo = <0>; 313 #address-cells = <1>; 314 #size-cells = <0>; 315 316 pinctrl-0 = <&sercom2_usart_default>; 317 pinctrl-names = "default"; 318}; 319``` 320
