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