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