# Copyright (c) 2020, Linaro Limited
# Copyright (c) 2021, Teslabs Engineering S.L.
# Copyright (c) 2021-2022, Gerson Fernando Budke <nandojve@gmail.com>
# SPDX-License-Identifier: Apache-2.0

description: |
  Atmel SAM Pinctrl container node

  The Atmel SAM pin controller is a singleton node responsible for controlling
  pin function selection and pin properties. For example, you can use this node
  to route USART0 RX to pin PA10 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.
      */

    /** include pre-defined combinations for the SoC variant used by the board */
    #include <dt-bindings/pinctrl/sam4sXc-pinctrl.h>

    &pinctrl {
      /* configuration for the usart0 "default" state */
      usart0_default: usart0_default {
        /* group 1 */
        group1 {
          /* configure PA6 as USART0 TX and PA8 as USART0 CTS */
          pinmux = <PA6A_USART0_TXD0>, <PA8A_USART0_CTS0>;
        };
        /* group 2 */
        group2 {
          /* configure PA5 as USART0 RX and PA7 as USART0 RTS */
          pinmux = <PA5A_USART0_RXD0>, <PA7A_USART0_RTS0>;
          /* both PA5 and PA7 have pull-up enabled */
          bias-pull-up;
        };
      };
    };

  The 'usart0_default' child node encodes the pin configurations for a
  particular state of a device; in this case, the default (that is, active)
  state.

  As shown, pin configurations are organized in groups within each child node.
  Each group can specify a list of pin function selections in the 'pinmux'
  property.

  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-pull-up: Enable pull-up resistor.
  - bias-pull-down: Enable pull-down resistor.
  - drive-open-drain: Open-drain drive mode.

  To link pin configurations 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"

    &usart0 {
          pinctrl-0 = <&usart0_default>;
          pinctrl-names = "default";
    };

compatible: "atmel,sam-pinctrl"

include: base.yaml

properties:
  "#address-cells":
    required: true
    const: 1
  "#size-cells":
    required: true
    const: 1

child-binding:
  description: |
    Each child node defines the configuration for a particular state.
  child-binding:
    description: |
      The grandchild nodes group pins that share the same pin configuration.

    include:
      - name: pincfg-node.yaml
        property-allowlist:
          - bias-pull-up
          - bias-pull-down
          - drive-open-drain

    properties:
      pinmux:
        required: true
        type: array
        description: |
          An array of pins sharing the same group properties. The pins should
          be defined using pre-defined macros or, alternatively, using the
          SAM_PINMUX utility macros depending on the pinmux model used by the
          SoC series.