1Renesas RZ/A1 combined Pin and GPIO controller
2
3The Renesas SoCs of the RZ/A1 family feature a combined Pin and GPIO controller,
4named "Ports" in the hardware reference manual.
5Pin multiplexing and GPIO configuration is performed on a per-pin basis
6writing configuration values to per-port register sets.
7Each "port" features up to 16 pins, each of them configurable for GPIO
8function (port mode) or in alternate function mode.
9Up to 8 different alternate function modes exist for each single pin.
10
11Pin controller node
12-------------------
13
14Required 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
24Example:
25Pin controller node for RZ/A1H SoC (r7s72100)
26
27pinctrl: pin-controller@fcfe3000 {
28	compatible = "renesas,r7s72100-ports";
29
30	reg = <0xfcfe3000 0x4230>;
31};
32
33Sub-nodes
34---------
35
36The child nodes of the pin controller node describe a pin multiplexing
37function 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  };
224