1# Copyright (c) 2021 Nordic Semiconductor ASA
2# SPDX-License-Identifier: Apache-2.0
3
4description: |
5    The nRF pin controller is a singleton node responsible for controlling
6    pin function selection and pin properties. For example, you can use this
7    node to route UART0 RX to pin P0.1 and enable the pull-up resistor on the
8    pin.
9
10    The node has the 'pinctrl' node label set in your SoC's devicetree,
11    so you can modify it like this:
12
13      &pinctrl {
14              /* your modifications go here */
15      };
16
17    All device pin configurations should be placed in child nodes of the
18    'pinctrl' node, as shown in this example:
19
20      /* You can put this in places like a board-pinctrl.dtsi file in
21       * your board directory, or a devicetree overlay in your application.
22       */
23      &pinctrl {
24        /* configuration for uart0 device, default state */
25        uart0_default: uart0_default {
26          /* group 1 ('group1' name is arbitrary) */
27          group1 {
28            /* configure P0.1 as UART_TX and P0.2 as UART_RTS */
29            psels = <NRF_PSEL(UART_TX, 0, 1)>, <NRF_PSEL(UART_RTS, 0, 2)>;
30          };
31          /* group 2 */
32          group2 {
33            /* configure P0.3 as UART_RX and P0.4 as UART_CTS */
34            psels = <NRF_PSEL(UART_RX, 0, 3)>, <NRF_PSEL(UART_CTS, 0, 4)>;
35            /* both P0.3 and P0.4 are configured with pull-up */
36            bias-pull-up;
37          };
38        };
39      };
40
41    The 'uart0_default' child node encodes the pin configurations for a
42    particular state of a device; in this case, the default (that is, active)
43    state. You would specify the low-power configuration for the same device
44    in a separate child node.
45
46    As shown, pin configurations are organized in groups within each child node.
47    Each group can specify a list of pin function selections in the 'psels'
48    property. The NRF_PSEL macro is used to specify a pin function selection.
49    If a pin needs to be explicitly disconnected, there is also the
50    NRF_PSEL_DISCONNECTED macro.
51    Available pin functions can be found in the
52    include/zephyr/dt-bindings/pinctrl/nrf-pinctrl.h header file.
53
54    A group can also specify shared pin properties common to all the specified
55    pins, such as the 'bias-pull-up' property in group 2. Here is a list of
56    supported standard pin properties:
57
58    - bias-disable: Disable pull-up/down (default behavior, not required).
59    - bias-pull-up: Enable pull-up resistor.
60    - bias-pull-down: Enable pull-down resistor.
61    - low-power-enable: Configure pin as an input with input buffer
62      disconnected.
63
64    Note that bias options are mutually exclusive.
65
66    To link this pin configuration with a device, use a pinctrl-N property
67    for some number N, like this example you could place in your board's DTS
68    file:
69
70       #include "board-pinctrl.dtsi"
71
72       &uart0 {
73             pinctrl-0 = <&uart0_default>;
74             pinctrl-names = "default";
75       };
76
77compatible: "nordic,nrf-pinctrl"
78
79include: base.yaml
80
81child-binding:
82  description: |
83    nRF pin controller pin configuration state nodes.
84  child-binding:
85    description: |
86      nRF pin controller pin configuration group.
87
88    include:
89      - name: pincfg-node.yaml
90        property-allowlist:
91          - bias-disable
92          - bias-pull-down
93          - bias-pull-up
94          - low-power-enable
95
96    properties:
97      psels:
98        required: true
99        type: array
100        description: |
101          An array of pins sharing the same group properties. The pins should
102          be defined using the NRF_PSEL utility macro that encodes the port,
103          pin and function. NRF_PSEL_DISCONNECTED is also available to explicitly
104          disconnect a pin.
105
106      nordic,drive-mode:
107        type: int
108        default: 0
109        description: |
110          Pin output drive mode. Available drive modes are pre-defined in
111          nrf-pinctrl.h. Note that extra modes may not be available on certain
112          devices. Defaults to standard mode for 0 and 1 (NRF_DRIVE_S0S1), the
113          SoC default, except for the "nordic,nrf-twi" and "nordic,nrf-twim"
114          nodes where NRF_DRIVE_S0S1 is always overridden with NRF_DRIVE_S0D1
115          (standard '0', disconnect '1').
116
117      nordic,invert:
118        type: boolean
119        description: |
120          Invert pin polarity (set the active state to low).
121          Only valid for PWM channel output pins.
122