Documentation/devicetree/bindings/pinctrl/renesas,rza1-pinctrl.txt

   1 Renesas RZ/A1 combined Pin and GPIO controller
   2
   3 The Renesas SoCs of the RZ/A1 family feature a combined Pin and GPIO controller,
   4 named "Ports" in the hardware reference manual.
   5 Pin multiplexing and GPIO configuration is performed on a per-pin basis
   6 writing configuration values to per-port register sets.
   7 Each "port" features up to 16 pins, each of them configurable for GPIO
   8 function (port mode) or in alternate function mode.
   9 Up to 8 different alternate function modes exist for each single pin.
  10
  11 Pin controller node
  12 -------------------
  13
  14 Required properties:
  15   - compatible: should be:
  16     - "renesas,r7s72100-ports": for RZ/A1H
  17     - "renesas,r7s72101-ports", "renesas,r7s72100-ports": for RZ/A1M
  18     - "renesas,r7s72102-ports": for RZ/A1L
  19
  20   - reg
  21     address base and length of the memory area where the pin controller
  22     hardware is mapped to.
  23
  24 Example:
  25 Pin controller node for RZ/A1H SoC (r7s72100)
  26
  27 pinctrl: pin-controller@fcfe3000 {
  28         compatible = "renesas,r7s72100-ports";
  29
  30         reg = <0xfcfe3000 0x4230>;
  31 };
  32
  33 Sub-nodes
  34 ---------
  35
  36 The child nodes of the pin controller node describe a pin multiplexing
  37 function or a GPIO controller alternatively.
  38
  39 - Pin multiplexing sub-nodes:
  40   A pin multiplexing sub-node describes how to configure a set of
  41   (or a single) pin in some desired alternate function mode.
  42   A single sub-node may define several pin configurations.
  43   A few alternate function require special pin configuration flags to be
  44   supplied along with the alternate function configuration number.
  45   The hardware reference manual specifies when a pin function requires
  46   "software IO driven" mode to be specified. To do so use the generic
  47   properties from the <include/linux/pinctrl/pinconf_generic.h> header file
  48   to instruct the pin controller to perform the desired pin configuration
  49   operation.
  50   Please refer to pinctrl-bindings.txt to get to know more on generic
  51   pin properties usage.
  52
  53   The allowed generic formats for a pin multiplexing sub-node are the
  54   following ones:
  55
  56   node-1 {
  57       pinmux = <PIN_ID_AND_MUX>, <PIN_ID_AND_MUX>, ... ;
  58       GENERIC_PINCONFIG;
  59   };
  60
  61   node-2 {
  62       sub-node-1 {
  63           pinmux = <PIN_ID_AND_MUX>, <PIN_ID_AND_MUX>, ... ;
  64           GENERIC_PINCONFIG;
  65       };
  66
  67       sub-node-2 {
  68           pinmux = <PIN_ID_AND_MUX>, <PIN_ID_AND_MUX>, ... ;
  69           GENERIC_PINCONFIG;
  70       };
  71
  72       ...
  73
  74       sub-node-n {
  75           pinmux = <PIN_ID_AND_MUX>, <PIN_ID_AND_MUX>, ... ;
  76           GENERIC_PINCONFIG;
  77       };
  78   };
  79
  80   Use the second format when pins part of the same logical group need to have
  81   different generic pin configuration flags applied.
  82
  83   Client sub-nodes shall refer to pin multiplexing sub-nodes using the phandle
  84   of the most external one.
  85
  86   Eg.
  87
  88   client-1 {
  89       ...
  90       pinctrl-0 = <&node-1>;
  91       ...
  92   };
  93
  94   client-2 {
  95       ...
  96       pinctrl-0 = <&node-2>;
  97       ...
  98   };
  99
 100   Required properties:
 101     - pinmux:
 102       integer array representing pin number and pin multiplexing configuration.
 103       When a pin has to be configured in alternate function mode, use this
 104       property to identify the pin by its global index, and provide its
 105       alternate function configuration number along with it.
 106       When multiple pins are required to be configured as part of the same
 107       alternate function they shall be specified as members of the same
 108       argument list of a single "pinmux" property.
 109       Helper macros to ease assembling the pin index from its position
 110       (port where it sits on and pin number) and alternate function identifier
 111       are provided by the pin controller header file at:
 112       <include/dt-bindings/pinctrl/r7s72100-pinctrl.h>
 113       Integers values in "pinmux" argument list are assembled as:
 114       ((PORT * 16 + PIN) | MUX_FUNC << 16)
 115
 116   Optional generic properties:
 117     - input-enable:
 118       enable input bufer for pins requiring software driven IO input
 119       operations.
 120     - output-high:
 121       enable output buffer for pins requiring software driven IO output
 122       operations. output-low can be used alternatively, as line value is
 123       ignored by the driver.
 124
 125   The hardware reference manual specifies when a pin has to be configured to
 126   work in bi-directional mode and when the IO direction has to be specified
 127   by software. Bi-directional pins are managed by the pin controller driver
 128   internally, while software driven IO direction has to be explicitly
 129   selected when multiple options are available.
 130
 131   Example:
 132   A serial communication interface with a TX output pin and an RX input pin.
 133
 134   &pinctrl {
 135         scif2_pins: serial2 {
 136                 pinmux = <RZA1_PINMUX(3, 0, 6)>, <RZA1_PINMUX(3, 2, 4)>;
 137         };
 138   };
 139
 140   Pin #0 on port #3 is configured as alternate function #6.
 141   Pin #2 on port #3 is configured as alternate function #4.
 142
 143   Example 2:
 144   I2c master: both SDA and SCL pins need bi-directional operations
 145
 146   &pinctrl {
 147         i2c2_pins: i2c2 {
 148                 pinmux = <RZA1_PINMUX(1, 4, 1)>, <RZA1_PINMUX(1, 5, 1)>;
 149         };
 150   };
 151
 152   Pin #4 on port #1 is configured as alternate function #1.
 153   Pin #5 on port #1 is configured as alternate function #1.
 154   Both need to work in bi-directional mode, the driver manages this internally.
 155
 156   Example 3:
 157   Multi-function timer input and output compare pins.
 158   Configure TIOC0A as software driven input and TIOC0B as software driven
 159   output.
 160
 161   &pinctrl {
 162         tioc0_pins: tioc0 {
 163                 tioc0_input_pins {
 164                         pinumx = <RZA1_PINMUX(4, 0, 2)>;
 165                         input-enable;
 166                 };
 167
 168                 tioc0_output_pins {
 169                         pinmux = <RZA1_PINMUX(4, 1, 1)>;
 170                         output-enable;
 171                 };
 172         };
 173   };
 174
 175   &tioc0 {
 176         ...
 177         pinctrl-0 = <&tioc0_pins>;
 178         ...
 179   };
 180
 181   Pin #0 on port #4 is configured as alternate function #2 with IO direction
 182   specified by software as input.
 183   Pin #1 on port #4 is configured as alternate function #1 with IO direction
 184   specified by software as output.
 185
 186 - GPIO controller sub-nodes:
 187   Each port of the r7s72100 pin controller hardware is itself a GPIO controller.
 188   Different SoCs have different numbers of available pins per port, but
 189   generally speaking, each of them can be configured in GPIO ("port") mode
 190   on this hardware.
 191   Describe GPIO controllers using sub-nodes with the following properties.
 192
 193   Required properties:
 194     - gpio-controller
 195       empty property as defined by the GPIO bindings documentation.
 196     - #gpio-cells
 197       number of cells required to identify and configure a GPIO.
 198       Shall be 2.
 199     - gpio-ranges
 200       Describes a GPIO controller specifying its specific pin base, the pin
 201       base in the global pin numbering space, and the number of controlled
 202       pins, as defined by the GPIO bindings documentation. Refer to
 203       Documentation/devicetree/bindings/gpio/gpio.txt file for a more detailed
 204       description.
 205
 206   Example:
 207   A GPIO controller node, controlling 16 pins indexed from 0.
 208   The GPIO controller base in the global pin indexing space is pin 48, thus
 209   pins [0 - 15] on this controller map to pins [48 - 63] in the global pin
 210   indexing space.
 211
 212   port3: gpio-3 {
 213         gpio-controller;
 214         #gpio-cells = <2>;
 215         gpio-ranges = <&pinctrl 0 48 16>;
 216   };
 217
 218   A device node willing to use pins controlled by this GPIO controller, shall
 219   refer to it as follows:
 220
 221   led1 {
 222         gpios = <&port3 10 GPIO_ACTIVE_LOW>;
 223   };