Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.txt

   1 * STM32 GPIO and Pin Mux/Config controller
   2
   3 STMicroelectronics's STM32 MCUs intregrate a GPIO and Pin mux/config hardware
   4 controller. It controls the input/output settings on the available pins and
   5 also provides ability to multiplex and configure the output of various on-chip
   6 controllers onto these pads.
   7
   8 Pin controller node:
   9 Required properies:
  10  - compatible: value should be one of the following:
  11    "st,stm32f429-pinctrl"
  12    "st,stm32f469-pinctrl"
  13    "st,stm32f746-pinctrl"
  14    "st,stm32h743-pinctrl"
  15    "st,stm32mp157-pinctrl"
  16    "st,stm32mp157-z-pinctrl"
  17  - #address-cells: The value of this property must be 1
  18  - #size-cells  : The value of this property must be 1
  19  - ranges       : defines mapping between pin controller node (parent) to
  20    gpio-bank node (children).
  21  - pins-are-numbered: Specify the subnodes are using numbered pinmux to
  22    specify pins.
  23
  24 GPIO controller/bank node:
  25 Required properties:
  26  - gpio-controller : Indicates this device is a GPIO controller
  27  - #gpio-cells    : Should be two.
  28                         The first cell is the pin number
  29                         The second one is the polarity:
  30                                 - 0 for active high
  31                                 - 1 for active low
  32  - reg            : The gpio address range, relative to the pinctrl range
  33  - clocks         : clock that drives this bank
  34  - st,bank-name   : Should be a name string for this bank as specified in
  35    the datasheet
  36
  37 Optional properties:
  38  - reset:         : Reference to the reset controller
  39  - interrupt-parent: phandle of the interrupt parent to which the external
  40    GPIO interrupts are forwarded to.
  41  - st,syscfg: Should be phandle/offset pair. The phandle to the syscon node
  42    which includes IRQ mux selection register, and the offset of the IRQ mux
  43    selection register.
  44  - gpio-ranges: Define a dedicated mapping between a pin-controller and
  45    a gpio controller. Format is <&phandle a b c> with:
  46         -(phandle): phandle of pin-controller.
  47         -(a): gpio base offset in range.
  48         -(b): pin base offset in range.
  49         -(c): gpio count in range
  50    This entry has to be used either if there are holes inside a bank:
  51         GPIOB0/B1/B2/B14/B15 (see example 2)
  52    or if banks are not contiguous:
  53         GPIOA/B/C/E...
  54    NOTE: If "gpio-ranges" is used for a gpio controller, all gpio-controller
  55    have to use a "gpio-ranges" entry.
  56    More details in Documentation/devicetree/bindings/gpio/gpio.txt.
  57
  58 Example 1:
  59 #include <dt-bindings/pinctrl/stm32f429-pinfunc.h>
  60 ...
  61
  62         pin-controller {
  63                 #address-cells = <1>;
  64                 #size-cells = <1>;
  65                 compatible = "st,stm32f429-pinctrl";
  66                 ranges = <0 0x40020000 0x3000>;
  67                 pins-are-numbered;
  68
  69                 gpioa: gpio@40020000 {
  70                         gpio-controller;
  71                         #gpio-cells = <2>;
  72                         reg = <0x0 0x400>;
  73                         resets = <&reset_ahb1 0>;
  74                         st,bank-name = "GPIOA";
  75                 };
  76                 ...
  77                 pin-functions nodes follow...
  78         };
  79
  80 Example 2:
  81 #include <dt-bindings/pinctrl/stm32f429-pinfunc.h>
  82 ...
  83
  84         pinctrl: pin-controller {
  85                 #address-cells = <1>;
  86                 #size-cells = <1>;
  87                 compatible = "st,stm32f429-pinctrl";
  88                 ranges = <0 0x40020000 0x3000>;
  89                 pins-are-numbered;
  90
  91                 gpioa: gpio@40020000 {
  92                         gpio-controller;
  93                         #gpio-cells = <2>;
  94                         reg = <0x0 0x400>;
  95                         resets = <&reset_ahb1 0>;
  96                         st,bank-name = "GPIOA";
  97                         gpio-ranges = <&pinctrl 0 0 16>;
  98                 };
  99
 100                 gpiob: gpio@40020400 {
 101                         gpio-controller;
 102                         #gpio-cells = <2>;
 103                         reg = <0x0 0x400>;
 104                         resets = <&reset_ahb1 0>;
 105                         st,bank-name = "GPIOB";
 106                         ngpios = 4;
 107                         gpio-ranges = <&pinctrl 0 16 3>,
 108                                       <&pinctrl 14 30 2>;
 109                 };
 110
 111
 112                 ...
 113                 pin-functions nodes follow...
 114         };
 115
 116
 117 Contents of function subnode node:
 118 ----------------------------------
 119 Subnode format
 120 A pinctrl node should contain at least one subnode representing the
 121 pinctrl group available on the machine. Each subnode will list the
 122 pins it needs, and how they should be configured, with regard to muxer
 123 configuration, pullups, drive, output high/low and output speed.
 124
 125     node {
 126         pinmux = <PIN_NUMBER_PINMUX>;
 127         GENERIC_PINCONFIG;
 128     };
 129
 130 Required properties:
 131 - pinmux: integer array, represents gpio pin number and mux setting.
 132   Supported pin number and mux varies for different SoCs, and are defined in
 133   dt-bindings/pinctrl/<soc>-pinfunc.h directly.
 134   These defines are calculated as:
 135     ((port * 16 + line) << 8) | function
 136   With:
 137     - port: The gpio port index (PA = 0, PB = 1, ..., PK = 11)
 138     - line: The line offset within the port (PA0 = 0, PA1 = 1, ..., PA15 = 15)
 139     - function: The function number, can be:
 140       * 0 : GPIO
 141       * 1 : Alternate Function 0
 142       * 2 : Alternate Function 1
 143       * 3 : Alternate Function 2
 144       * ...
 145       * 16 : Alternate Function 15
 146       * 17 : Analog
 147
 148   To simplify the usage, macro is available to generate "pinmux" field.
 149   This macro is available here:
 150     - include/dt-bindings/pinctrl/stm32-pinfunc.h
 151
 152   Some examples of using macro:
 153     /* GPIO A9 set as alernate function 2 */
 154     ... {
 155                 pinmux = <STM32_PINMUX('A', 9, AF2)>;
 156     };
 157     /* GPIO A9 set as GPIO  */
 158     ... {
 159                 pinmux = <STM32_PINMUX('A', 9, GPIO)>;
 160     };
 161     /* GPIO A9 set as analog */
 162     ... {
 163                 pinmux = <STM32_PINMUX('A', 9, ANALOG)>;
 164     };
 165
 166 Optional properties:
 167 - GENERIC_PINCONFIG: is the generic pinconfig options to use.
 168   Available options are:
 169    - bias-disable,
 170    - bias-pull-down,
 171    - bias-pull-up,
 172    - drive-push-pull,
 173    - drive-open-drain,
 174    - output-low
 175    - output-high
 176    - slew-rate = <x>, with x being:
 177        < 0 > : Low speed
 178        < 1 > : Medium speed
 179        < 2 > : Fast speed
 180        < 3 > : High speed
 181
 182 Example:
 183
 184 pin-controller {
 185 ...
 186         usart1_pins_a: usart1@0 {
 187                 pins1 {
 188                         pinmux = <STM32_PINMUX('A', 9, AF7)>;
 189                         bias-disable;
 190                         drive-push-pull;
 191                         slew-rate = <0>;
 192                 };
 193                 pins2 {
 194                         pinmux = <STM32_PINMUX('A', 10, AF7)>;
 195                         bias-disable;
 196                 };
 197         };
 198 };
 199
 200 &usart1 {
 201         pinctrl-0 = <&usart1_pins_a>;
 202         pinctrl-names = "default";
 203 };