# Copyright (c) 2021 Nordic Semiconductor ASA
# SPDX-License-Identifier: Apache-2.0

description: |
    The nRF pin controller is a singleton node responsible for controlling
    pin function selection and pin properties. For example, you can use this
    node to route UART0 RX to pin P0.1 and enable the pull-up resistor on the
    pin.

    The node has the 'pinctrl' node label set in your SoC's devicetree,
    so you can modify it like this:

      &pinctrl {
              /* your modifications go here */
      };

    All device pin configurations should be placed in child nodes of the
    'pinctrl' node, as shown in this example:

      /* You can put this in places like a board-pinctrl.dtsi file in
       * your board directory, or a devicetree overlay in your application.
       */
      &pinctrl {
        /* configuration for uart0 device, default state */
        uart0_default: uart0_default {
          /* group 1 ('group1' name is arbitrary) */
          group1 {
            /* configure P0.1 as UART_TX and P0.2 as UART_RTS */
            psels = <NRF_PSEL(UART_TX, 0, 1)>, <NRF_PSEL(UART_RTS, 0, 2)>;
          };
          /* group 2 */
          group2 {
            /* configure P0.3 as UART_RX and P0.4 as UART_CTS */
            psels = <NRF_PSEL(UART_RX, 0, 3)>, <NRF_PSEL(UART_CTS, 0, 4)>;
            /* both P0.3 and P0.4 are configured with pull-up */
            bias-pull-up;
          };
        };
      };

    The 'uart0_default' child node encodes the pin configurations for a
    particular state of a device; in this case, the default (that is, active)
    state. You would specify the low-power configuration for the same device
    in a separate child node.

    As shown, pin configurations are organized in groups within each child node.
    Each group can specify a list of pin function selections in the 'psels'
    property. The NRF_PSEL macro is used to specify a pin function selection.
    If a pin needs to be explicitly disconnected, there is also the
    NRF_PSEL_DISCONNECTED macro.
    Available pin functions can be found in the
    include/zephyr/dt-bindings/pinctrl/nrf-pinctrl.h header file.

    A group can also specify shared pin properties common to all the specified
    pins, such as the 'bias-pull-up' property in group 2. Here is a list of
    supported standard pin properties:

    - bias-disable: Disable pull-up/down (default behavior, not required).
    - bias-pull-up: Enable pull-up resistor.
    - bias-pull-down: Enable pull-down resistor.
    - low-power-enable: Configure pin as an input with input buffer
      disconnected.

    Note that bias options are mutually exclusive.

    To link this pin configuration with a device, use a pinctrl-N property
    for some number N, like this example you could place in your board's DTS
    file:

       #include "board-pinctrl.dtsi"

       &uart0 {
             pinctrl-0 = <&uart0_default>;
             pinctrl-names = "default";
       };

compatible: "nordic,nrf-pinctrl"

include: base.yaml

child-binding:
  description: |
    nRF pin controller pin configuration state nodes.
  child-binding:
    description: |
      nRF pin controller pin configuration group.

    include:
      - name: pincfg-node.yaml
        property-allowlist:
          - bias-disable
          - bias-pull-down
          - bias-pull-up
          - low-power-enable

    properties:
      psels:
        required: true
        type: array
        description: |
          An array of pins sharing the same group properties. The pins should
          be defined using the NRF_PSEL utility macro that encodes the port,
          pin and function. NRF_PSEL_DISCONNECTED is also available to explicitly
          disconnect a pin.

      nordic,drive-mode:
        type: int
        default: 0
        description: |
          Pin output drive mode. Available drive modes are pre-defined in
          nrf-pinctrl.h. Note that extra modes may not be available on certain
          devices. Defaults to standard mode for 0 and 1 (NRF_DRIVE_S0S1), the
          SoC default, except for the "nordic,nrf-twi" and "nordic,nrf-twim"
          nodes where NRF_DRIVE_S0S1 is always overridden with NRF_DRIVE_S0D1
          (standard '0', disconnect '1').

      nordic,invert:
        type: boolean
        description: |
          Invert pin polarity (set the active state to low).
          Only valid for PWM channel output pins.