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