GNU Linux-libre 4.19.264-gnu1
[releases.git] / Documentation / devicetree / bindings / pinctrl / samsung-pinctrl.txt
1 Samsung GPIO and Pin Mux/Config controller
2
3 Samsung's ARM based SoC's integrates a GPIO and Pin mux/config hardware
4 controller. It controls the input/output settings on the available pads/pins
5 and also provides ability to multiplex and configure the output of various
6 on-chip controllers onto these pads.
7
8 Required Properties:
9 - compatible: should be one of the following.
10   - "samsung,s3c2412-pinctrl": for S3C2412-compatible pin-controller,
11   - "samsung,s3c2416-pinctrl": for S3C2416-compatible pin-controller,
12   - "samsung,s3c2440-pinctrl": for S3C2440-compatible pin-controller,
13   - "samsung,s3c2450-pinctrl": for S3C2450-compatible pin-controller,
14   - "samsung,s3c64xx-pinctrl": for S3C64xx-compatible pin-controller,
15   - "samsung,s5pv210-pinctrl": for S5PV210-compatible pin-controller,
16   - "samsung,exynos3250-pinctrl": for Exynos3250 compatible pin-controller.
17   - "samsung,exynos4210-pinctrl": for Exynos4210 compatible pin-controller.
18   - "samsung,exynos4x12-pinctrl": for Exynos4x12 compatible pin-controller.
19   - "samsung,exynos5250-pinctrl": for Exynos5250 compatible pin-controller.
20   - "samsung,exynos5260-pinctrl": for Exynos5260 compatible pin-controller.
21   - "samsung,exynos5410-pinctrl": for Exynos5410 compatible pin-controller.
22   - "samsung,exynos5420-pinctrl": for Exynos5420 compatible pin-controller.
23   - "samsung,exynos5433-pinctrl": for Exynos5433 compatible pin-controller.
24   - "samsung,exynos7-pinctrl": for Exynos7 compatible pin-controller.
25
26 - reg: Base address of the pin controller hardware module and length of
27   the address space it occupies.
28
29   - reg: Second base address of the pin controller if the specific registers
30   of the pin controller are separated into the different base address.
31
32         Eg: GPF[1-5] of Exynos5433 are separated into the two base address.
33         - First base address is for GPAx and GPF[1-5] external interrupt
34           registers.
35         - Second base address is for GPF[1-5] pinctrl registers.
36
37         pinctrl_0: pinctrl@10580000 {
38                 compatible = "samsung,exynos5433-pinctrl";
39                 reg = <0x10580000 0x1a20>, <0x11090000 0x100>;
40
41                 wakeup-interrupt-controller {
42                         compatible = "samsung,exynos7-wakeup-eint";
43                         interrupts = <0 16 0>;
44                 };
45         };
46
47 - Pin banks as child nodes: Pin banks of the controller are represented by child
48   nodes of the controller node. Bank name is taken from name of the node. Each
49   bank node must contain following properties:
50
51   - gpio-controller: identifies the node as a gpio controller and pin bank.
52   - #gpio-cells: number of cells in GPIO specifier. Since the generic GPIO
53     binding is used, the amount of cells must be specified as 2. See the below
54     mentioned gpio binding representation for description of particular cells.
55
56         Eg: <&gpx2 6 0>
57         <[phandle of the gpio controller node]
58         [pin number within the gpio controller]
59         [flags]>
60
61         Values for gpio specifier:
62         - Pin number: is a value between 0 to 7.
63         - Flags: 0 - Active High
64                  1 - Active Low
65
66 - Pin mux/config groups as child nodes: The pin mux (selecting pin function
67   mode) and pin config (pull up/down, driver strength) settings are represented
68   as child nodes of the pin-controller node. There should be atleast one
69   child node and there is no limit on the count of these child nodes. It is
70   also possible for a child node to consist of several further child nodes
71   to allow grouping multiple pinctrl groups into one. The format of second
72   level child nodes is exactly the same as for first level ones and is
73   described below.
74
75   The child node should contain a list of pin(s) on which a particular pin
76   function selection or pin configuration (or both) have to applied. This
77   list of pins is specified using the property name "samsung,pins". There
78   should be atleast one pin specfied for this property and there is no upper
79   limit on the count of pins that can be specified. The pins are specified
80   using pin names which are derived from the hardware manual of the SoC. As
81   an example, the pins in GPA0 bank of the pin controller can be represented
82   as "gpa0-0", "gpa0-1", "gpa0-2" and so on. The names should be in lower case.
83   The format of the pin names should be (as per the hardware manual)
84   "[pin bank name]-[pin number within the bank]".
85
86   The pin function selection that should be applied on the pins listed in the
87   child node is specified using the "samsung,pin-function" property. The value
88   of this property that should be applied to each of the pins listed in the
89   "samsung,pins" property should be picked from the hardware manual of the SoC
90   for the specified pin group. This property is optional in the child node if
91   no specific function selection is desired for the pins listed in the child
92   node. The value of this property is used as-is to program the pin-controller
93   function selector register of the pin-bank.
94
95   The child node can also optionally specify one or more of the pin
96   configuration that should be applied on all the pins listed in the
97   "samsung,pins" property of the child node. The following pin configuration
98   properties are supported.
99
100   - samsung,pin-val: Initial value of pin output buffer.
101   - samsung,pin-pud: Pull up/down configuration.
102   - samsung,pin-drv: Drive strength configuration.
103   - samsung,pin-pud-pdn: Pull up/down configuration in power down mode.
104   - samsung,pin-drv-pdn: Drive strength configuration in power down mode.
105
106   The values specified by these config properties should be derived from the
107   hardware manual and these values are programmed as-is into the pin
108   pull up/down and driver strength register of the pin-controller.
109
110   Note: A child should include atleast a pin function selection property or
111   pin configuration property (one or more) or both.
112
113   The client nodes that require a particular pin function selection and/or
114   pin configuration should use the bindings listed in the "pinctrl-bindings.txt"
115   file.
116
117 External GPIO and Wakeup Interrupts:
118
119 The controller supports two types of external interrupts over gpio. The first
120 is the external gpio interrupt and second is the external wakeup interrupts.
121 The difference between the two is that the external wakeup interrupts can be
122 used as system wakeup events.
123
124 A. External GPIO Interrupts: For supporting external gpio interrupts, the
125    following properties should be specified in the pin-controller device node.
126
127    - interrupts: interrupt specifier for the controller. The format and value of
128      the interrupt specifier depends on the interrupt parent for the controller.
129
130    In addition, following properties must be present in node of every bank
131    of pins supporting GPIO interrupts:
132
133    - interrupt-controller: identifies the controller node as interrupt-parent.
134    - #interrupt-cells: the value of this property should be 2.
135      - First Cell: represents the external gpio interrupt number local to the
136        external gpio interrupt space of the controller.
137      - Second Cell: flags to identify the type of the interrupt
138        - 1 = rising edge triggered
139        - 2 = falling edge triggered
140        - 3 = rising and falling edge triggered
141        - 4 = high level triggered
142        - 8 = low level triggered
143
144 B. External Wakeup Interrupts: For supporting external wakeup interrupts, a
145    child node representing the external wakeup interrupt controller should be
146    included in the pin-controller device node.
147
148    Only one pin-controller device node can include external wakeup interrupts
149    child node (in other words, only one External Wakeup Interrupts
150    pin-controller is supported).
151
152    This child node should include following properties:
153
154    - compatible: identifies the type of the external wakeup interrupt controller
155      The possible values are:
156      - samsung,s3c2410-wakeup-eint: represents wakeup interrupt controller
157        found on Samsung S3C24xx SoCs except S3C2412 and S3C2413,
158      - samsung,s3c2412-wakeup-eint: represents wakeup interrupt controller
159        found on Samsung S3C2412 and S3C2413 SoCs,
160      - samsung,s3c64xx-wakeup-eint: represents wakeup interrupt controller
161        found on Samsung S3C64xx SoCs,
162      - samsung,s5pv210-wakeup-eint: represents wakeup interrupt controller
163        found on Samsung S5Pv210 SoCs,
164      - samsung,exynos4210-wakeup-eint: represents wakeup interrupt controller
165        found on Samsung Exynos4210 and S5PC110/S5PV210 SoCs.
166      - samsung,exynos7-wakeup-eint: represents wakeup interrupt controller
167        found on Samsung Exynos7 SoC.
168    - interrupts: interrupt used by multiplexed wakeup interrupts.
169
170    In addition, following properties must be present in node of every bank
171    of pins supporting wake-up interrupts:
172
173    - interrupt-controller: identifies the node as interrupt-parent.
174    - #interrupt-cells: the value of this property should be 2
175      - First Cell: represents the external wakeup interrupt number local to
176        the external wakeup interrupt space of the controller.
177      - Second Cell: flags to identify the type of the interrupt
178        - 1 = rising edge triggered
179        - 2 = falling edge triggered
180        - 3 = rising and falling edge triggered
181        - 4 = high level triggered
182        - 8 = low level triggered
183
184    Node of every bank of pins supporting direct wake-up interrupts (without
185    multiplexing) must contain following properties:
186
187    - interrupts: interrupts of the interrupt parent which are used for external
188      wakeup interrupts from pins of the bank, must contain interrupts for all
189      pins of the bank.
190
191 Aliases:
192
193 All the pin controller nodes should be represented in the aliases node using
194 the following format 'pinctrl{n}' where n is a unique number for the alias.
195
196 Aliases for controllers compatible with "samsung,exynos7-pinctrl":
197 - pinctrl0: pin controller of ALIVE block,
198 - pinctrl1: pin controller of BUS0 block,
199 - pinctrl2: pin controller of NFC block,
200 - pinctrl3: pin controller of TOUCH block,
201 - pinctrl4: pin controller of FF block,
202 - pinctrl5: pin controller of ESE block,
203 - pinctrl6: pin controller of FSYS0 block,
204 - pinctrl7: pin controller of FSYS1 block,
205 - pinctrl8: pin controller of BUS1 block,
206 - pinctrl9: pin controller of AUDIO block,
207
208 Example: A pin-controller node with pin banks:
209
210         pinctrl_0: pinctrl@11400000 {
211                 compatible = "samsung,exynos4210-pinctrl";
212                 reg = <0x11400000 0x1000>;
213                 interrupts = <0 47 0>;
214
215                 /* ... */
216
217                 /* Pin bank without external interrupts */
218                 gpy0: gpy0 {
219                         gpio-controller;
220                         #gpio-cells = <2>;
221                 };
222
223                 /* ... */
224
225                 /* Pin bank with external GPIO or muxed wake-up interrupts */
226                 gpj0: gpj0 {
227                         gpio-controller;
228                         #gpio-cells = <2>;
229
230                         interrupt-controller;
231                         #interrupt-cells = <2>;
232                 };
233
234                 /* ... */
235
236                 /* Pin bank with external direct wake-up interrupts */
237                 gpx0: gpx0 {
238                         gpio-controller;
239                         #gpio-cells = <2>;
240
241                         interrupt-controller;
242                         interrupt-parent = <&gic>;
243                         interrupts = <0 16 0>, <0 17 0>, <0 18 0>, <0 19 0>,
244                                      <0 20 0>, <0 21 0>, <0 22 0>, <0 23 0>;
245                         #interrupt-cells = <2>;
246                 };
247
248                 /* ... */
249         };
250
251 Example 1: A pin-controller node with pin groups.
252
253         #include <dt-bindings/pinctrl/samsung.h>
254
255         pinctrl_0: pinctrl@11400000 {
256                 compatible = "samsung,exynos4210-pinctrl";
257                 reg = <0x11400000 0x1000>;
258                 interrupts = <0 47 0>;
259
260                 /* ... */
261
262                 uart0_data: uart0-data {
263                         samsung,pins = "gpa0-0", "gpa0-1";
264                         samsung,pin-function = <EXYNOS_PIN_FUNC_2>;
265                         samsung,pin-pud = <EXYNOS_PIN_PULL_NONE>;
266                         samsung,pin-drv = <EXYNOS4_PIN_DRV_LV1>;
267                 };
268
269                 uart0_fctl: uart0-fctl {
270                         samsung,pins = "gpa0-2", "gpa0-3";
271                         samsung,pin-function = <EXYNOS_PIN_FUNC_2>;
272                         samsung,pin-pud = <EXYNOS_PIN_PULL_NONE>;
273                         samsung,pin-drv = <EXYNOS4_PIN_DRV_LV1>;
274                 };
275
276                 uart1_data: uart1-data {
277                         samsung,pins = "gpa0-4", "gpa0-5";
278                         samsung,pin-function = <EXYNOS_PIN_FUNC_2>;
279                         samsung,pin-pud = <EXYNOS_PIN_PULL_NONE>;
280                         samsung,pin-drv = <EXYNOS4_PIN_DRV_LV1>;
281                 };
282
283                 uart1_fctl: uart1-fctl {
284                         samsung,pins = "gpa0-6", "gpa0-7";
285                         samsung,pin-function = <EXYNOS_PIN_FUNC_2>;
286                         samsung,pin-pud = <EXYNOS_PIN_PULL_NONE>;
287                         samsung,pin-drv = <EXYNOS4_PIN_DRV_LV1>;
288                 };
289
290                 i2c2_bus: i2c2-bus {
291                         samsung,pins = "gpa0-6", "gpa0-7";
292                         samsung,pin-function = <EXYNOS_PIN_FUNC_3>;
293                         samsung,pin-pud = <EXYNOS_PIN_PULL_UP>;
294                         samsung,pin-drv = <EXYNOS4_PIN_DRV_LV1>;
295                 };
296
297                 sd4_bus8: sd4-bus-width8 {
298                         part-1 {
299                                 samsung,pins = "gpk0-3", "gpk0-4",
300                                                 "gpk0-5", "gpk0-6";
301                                 samsung,pin-function = <EXYNOS_PIN_FUNC_3>;
302                                 samsung,pin-pud = <EXYNOS_PIN_PULL_UP>;
303                                 samsung,pin-drv = <EXYNOS4_PIN_DRV_LV4>;
304                         };
305                         part-2 {
306                                 samsung,pins = "gpk1-3", "gpk1-4",
307                                                 "gpk1-5", "gpk1-6";
308                                 samsung,pin-function = <EXYNOS_PIN_FUNC_4>;
309                                 samsung,pin-pud = <EXYNOS_PIN_PULL_UP>;
310                                 samsung,pin-drv = <EXYNOS4_PIN_DRV_LV4>;
311                         };
312                 };
313         };
314
315 Example 2: A pin-controller node with external wakeup interrupt controller node.
316
317         pinctrl_1: pinctrl@11000000 {
318                 compatible = "samsung,exynos4210-pinctrl";
319                 reg = <0x11000000 0x1000>;
320                 interrupts = <0 46 0>
321
322                 /* ... */
323
324                 wakeup-interrupt-controller {
325                         compatible = "samsung,exynos4210-wakeup-eint";
326                         interrupt-parent = <&gic>;
327                         interrupts = <0 32 0>;
328                 };
329         };
330
331 Example 3: A uart client node that supports 'default' and 'flow-control' states.
332
333         uart@13800000 {
334                 compatible = "samsung,exynos4210-uart";
335                 reg = <0x13800000 0x100>;
336                 interrupts = <0 52 0>;
337                 pinctrl-names = "default", "flow-control;
338                 pinctrl-0 = <&uart0_data>;
339                 pinctrl-1 = <&uart0_data &uart0_fctl>;
340         };
341
342 Example 4: Set up the default pin state for uart controller.
343
344         static int s3c24xx_serial_probe(struct platform_device *pdev) {
345                 struct pinctrl *pinctrl;
346
347                 /* ... */
348
349                 pinctrl = devm_pinctrl_get_select_default(&pdev->dev);
350         }
351
352 Example 5: A display port client node that supports 'default' pinctrl state
353            and gpio binding.
354
355         display-port-controller {
356                 /* ... */
357
358                 samsung,hpd-gpio = <&gpx2 6 0>;
359                 pinctrl-names = "default";
360                 pinctrl-0 = <&dp_hpd>;
361         };
362
363 Example 6: Request the gpio for display port controller
364
365         static int exynos_dp_probe(struct platform_device *pdev)
366         {
367                 int hpd_gpio, ret;
368                 struct device *dev = &pdev->dev;
369                 struct device_node *dp_node = dev->of_node;
370
371                 /* ... */
372
373                 hpd_gpio = of_get_named_gpio(dp_node, "samsung,hpd-gpio", 0);
374
375                 /* ... */
376
377                 ret = devm_gpio_request_one(&pdev->dev, hpd_gpio, GPIOF_IN,
378                                             "hpd_gpio");
379                 /* ... */
380         }