1# Copyright (c) 2020, Linaro Limited
2# Copyright (c) 2021-2022, Gerson Fernando Budke
3# SPDX-License-Identifier: Apache-2.0
4
5description: |
6  Atmel SAM0 Pinctrl container node
7
8  The Atmel SAM0 pin controller is a singleton node responsible for controlling
9  pin function selection and pin properties. For example, you can use this node
10  to route SERCOM0 as UART were RX to pin PAD1 and enable the pull-up resistor
11  on the pin.
12
13  The node has the 'pinctrl' node label set in your SoC's devicetree, so you can
14  modify it like this:
15
16    &pinctrl {
17            /* your modifications go here */
18    };
19
20  All device pin configurations should be placed in child nodes of the 'pinctrl'
21  node, as shown in this example:
22
23    /** You can put this in places like a <board>-pinctrl.dtsi file in
24      * your board directory, or a devicetree overlay in your application.
25      */
26
27    /** include pre-defined combinations for the SoC variant used by the board */
28    #include <dt-bindings/pinctrl/samr21g-pinctrl.h>
29
30    &pinctrl {
31      /* configuration for the usart0 "default" state */
32      sercom0_uart_default: sercom0_uart_default {
33        /* group 1 */
34        group1 {
35          /* configure PA6 as USART0 TX and PA8 as USART0 CTS */
36          pinmux = <PA5D_SERCOM0_PAD1>, <PA6D_SERCOM0_PAD2>;
37        };
38        /* group 2 */
39        group2 {
40          /* configure PA5 as USART0 RX and PA7 as USART0 RTS */
41          pinmux = <PA4D_SERCOM0_PAD0>, <PA7D_SERCOM0_PAD3>;
42          /* both PA5 and PA7 have pull-up enabled */
43          bias-pull-up;
44        };
45      };
46    };
47
48  The 'usart0_default' child node encodes the pin configurations for a
49  particular state of a device; in this case, the default (that is, active)
50  state.
51
52  As shown, pin configurations are organized in groups within each child node.
53  Each group can specify a list of pin function selections in the 'pinmux'
54  property.
55
56  A group can also specify shared pin properties common to all the specified
57  pins, such as the 'bias-pull-up' property in group 2. Here is a list of
58  supported standard pin properties:
59
60  - bias-pull-up: Enable pull-up resistor.
61  - bias-pull-down: Enable pull-down resistor.
62  - drive-strength: Increase sink current.
63  - input-enable: Enable input on pin.
64  - output-enable: Enable output on a pin without actively driving it.
65
66  To link pin configurations with a device, use a pinctrl-N property for some
67  number N, like this example you could place in your board's DTS file:
68
69    #include "board-pinctrl.dtsi"
70
71    &usart0 {
72          pinctrl-0 = <&usart0_default>;
73          pinctrl-names = "default";
74    };
75
76compatible: "atmel,sam0-pinctrl"
77
78include: base.yaml
79
80properties:
81  "#address-cells":
82    required: true
83    const: 1
84  "#size-cells":
85    required: true
86    const: 1
87
88child-binding:
89  description: |
90    Each child node defines the configuration for a particular state.
91  child-binding:
92    description: |
93      The grandchild nodes group pins that share the same pin configuration.
94
95    include:
96      - name: pincfg-node.yaml
97        property-allowlist:
98          - bias-pull-up
99          - bias-pull-down
100          - drive-strength
101          - input-enable
102          - output-enable
103
104    properties:
105      pinmux:
106        required: true
107        type: array
108        description: |
109          An array of pins sharing the same group properties. The pins should
110          be defined using pre-defined macros or, alternatively, using the
111          SAM_PINMUX utility macros depending on the pinmux model used by the
112          SoC series.
113      drive-strength:
114        enum:
115          - 0
116          - 1
117        default: 0
118        description: |
119          The drive strength controls the output driver strength of an I/O pin
120          configured as an output.
121            0: Pin drive strength is set to normal drive strength.
122            1: Pin drive strength is set to stronger drive strength.
123