Documentation/devicetree/bindings/pinctrl/pinmux-node.yaml

   1 # SPDX-License-Identifier: GPL-2.0-only
   2 %YAML 1.2
   3 ---
   4 $id: http://devicetree.org/schemas/pinctrl/pinmux-node.yaml#
   5 $schema: http://devicetree.org/meta-schemas/core.yaml#
   6
   7 title: Generic pin multiplexing node schema
   8
   9 maintainers:
  10   - Linus Walleij <linus.walleij@linaro.org>
  11
  12 description: |
  13   The contents of the pin configuration child nodes are defined by the binding
  14   for the individual pin controller device. The pin configuration nodes need not
  15   be direct children of the pin controller device; they may be grandchildren,
  16   for example. Whether this is legal, and whether there is any interaction
  17   between the child and intermediate parent nodes, is again defined entirely by
  18   the binding for the individual pin controller device.
  19
  20   While not required to be used, there are 3 generic forms of pin muxing nodes
  21   which pin controller devices can use.
  22
  23   pin multiplexing nodes:
  24
  25   Example:
  26
  27   state_0_node_a {
  28     uart0 {
  29       function = "uart0";
  30       groups = "u0rxtx", "u0rtscts";
  31     };
  32   };
  33   state_1_node_a {
  34     spi0 {
  35       function = "spi0";
  36       groups = "spi0pins";
  37     };
  38   };
  39   state_2_node_a {
  40     function = "i2c0";
  41     pins = "mfio29", "mfio30";
  42   };
  43
  44   Optionally an alternative binding can be used if more suitable depending on the
  45   pin controller hardware. For hardware where there is a large number of identical
  46   pin controller instances, naming each pin and function can easily become
  47   unmaintainable. This is especially the case if the same controller is used for
  48   different pins and functions depending on the SoC revision and packaging.
  49
  50   For cases like this, the pin controller driver may use pinctrl-pin-array helper
  51   binding with a hardware based index and a number of pin configuration values:
  52
  53   pincontroller {
  54     ... /* Standard DT properties for the device itself elided */
  55     #pinctrl-cells = <2>;
  56
  57     state_0_node_a {
  58       pinctrl-pin-array = <
  59         0 A_DELAY_PS(0) G_DELAY_PS(120)
  60         4 A_DELAY_PS(0) G_DELAY_PS(360)
  61         ...
  62         >;
  63     };
  64     ...
  65   };
  66
  67   Above #pinctrl-cells specifies the number of value cells in addition to the
  68   index of the registers. This is similar to the interrupts-extended binding with
  69   one exception. There is no need to specify the phandle for each entry as that
  70   is already known as the defined pins are always children of the pin controller
  71   node. Further having the phandle pointing to another pin controller would not
  72   currently work as the pinctrl framework uses named modes to group pins for each
  73   pin control device.
  74
  75   The index for pinctrl-pin-array must relate to the hardware for the pinctrl
  76   registers, and must not be a virtual index of pin instances. The reason for
  77   this is to avoid mapping of the index in the dts files and the pin controller
  78   driver as it can change.
  79
  80   For hardware where pin multiplexing configurations have to be specified for
  81   each single pin the number of required sub-nodes containing "pin" and
  82   "function" properties can quickly escalate and become hard to write and
  83   maintain.
  84
  85   For cases like this, the pin controller driver may use the pinmux helper
  86   property, where the pin identifier is provided with mux configuration settings
  87   in a pinmux group. A pinmux group consists of the pin identifier and mux
  88   settings represented as a single integer or an array of integers.
  89
  90   The pinmux property accepts an array of pinmux groups, each of them describing
  91   a single pin multiplexing configuration.
  92
  93   pincontroller {
  94     state_0_node_a {
  95       pinmux = <PINMUX_GROUP>, <PINMUX_GROUP>, ...;
  96     };
  97   };
  98
  99   Each individual pin controller driver bindings documentation shall specify
 100   how pin IDs and pin multiplexing configuration are defined and assembled
 101   together in a pinmux group.
 102
 103 properties:
 104   function:
 105     $ref: /schemas/types.yaml#/definitions/string
 106     description: The mux function to select
 107
 108   pins:
 109     oneOf:
 110       - $ref: /schemas/types.yaml#/definitions/uint32-array
 111       - $ref: /schemas/types.yaml#/definitions/string-array
 112     description:
 113       The list of pin identifiers that properties in the node apply to. The
 114       specific binding for the hardware defines whether the entries are integers
 115       or strings, and their meaning.
 116
 117   groups:
 118     $ref: /schemas/types.yaml#/definitions/string-array
 119     description:
 120       the group to apply the properties to, if the driver supports
 121       configuration of whole groups rather than individual pins (either
 122       this, "pins" or "pinmux" has to be specified)
 123
 124   pinmux:
 125     description:
 126       The list of numeric pin ids and their mux settings that properties in the
 127       node apply to (either this, "pins" or "groups" have to be specified)
 128     $ref: /schemas/types.yaml#/definitions/uint32-array
 129
 130   pinctrl-pin-array:
 131     $ref: /schemas/types.yaml#/definitions/uint32-array
 132
 133 additionalProperties: true