dts/bindings/pinctrl/sifli,sf32lb52x-pinmux.yaml

# Copyright (c) 2025 Core Devices LLC
# SPDX-License-Identifier: Apache-2.0

description: |
    SF32LB52x Pin multiplexer and pin configuration controller (HPSYS_PINMUX)

    Singleton node responsible for controlling pin function selection and pin
    properties. For example, you can use this node to route USART1 RX to pin
    PA19 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 <zephyr/dt-bindings/pinctrl/sf32lb52x.h>

      &pinctrl {
        /* configuration for the usart1 "default" state */
        usart1_default: usart1_default {
          /* group 1 */
          group1 {
            /* configure PA19 as USART1 TX and PA20 as USART1 CTS */
            pinmux = <USART1_TX_PA19>, <USART1_CTS_PA20>;
            /* both PA19 and PA20 have input buffer enabled */
            input-enable;
          };
          /* group 2 */
          group2 {
            /* configure PA21 as USART1 RX and PA22 as USART1 RTS */
            pinmux = <USART1_RX_PA21>, <USART0_RTS_PA22>;
            /* both PA20 and PA21 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.
    - input-enable: Enable input buffer.
    - input-schmitt-enable: Enable Schmitt trigger.
    - slew-rate: 0 (slow, default), 1 (fast).
    - drive-strength: 2, 4 (default), 8, or 12 mA.

    Note that drive and bias options are mutually exclusive.

    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"

       &usart1 {
             pinctrl-0 = <&usart1_default>;
             pinctrl-names = "default";
       };

compatible: "sifli,sf32lb52x-pinmux"

include: [base.yaml, sifli-sf32lb-cfg.yaml]

properties:
  reg:
    required: true

  reg-names:
    required: true

  clocks:
    required: true

  sifli,cfg:
    required: true

  "#sifli,pinmux-cells":
    type: int
    const: 2

sifli,pinmux-cells:
  - port
  - offset

child-binding:
  child-binding:
    include:
      - name: pincfg-node.yaml
        property-allowlist:
          - bias-pull-down
          - bias-pull-up
          - input-enable
          - input-schmitt-enable
          - slew-rate
          - drive-strength

    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
          SF32_PINMUX utility macro.

      slew-rate:
        default: 0
        enum:
          - 0
          - 1

      drive-strength:
        default: 4
        enum:
          - 2
          - 4
          - 8
          - 12