pinctrl-bindings.txt 10 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289
  1. == Introduction ==
  2. Hardware modules that control pin multiplexing or configuration parameters
  3. such as pull-up/down, tri-state, drive-strength etc are designated as pin
  4. controllers. Each pin controller must be represented as a node in device tree,
  5. just like any other hardware module.
  6. Hardware modules whose signals are affected by pin configuration are
  7. designated client devices. Again, each client device must be represented as a
  8. node in device tree, just like any other hardware module.
  9. For a client device to operate correctly, certain pin controllers must
  10. set up certain specific pin configurations. Some client devices need a
  11. single static pin configuration, e.g. set up during initialization. Others
  12. need to reconfigure pins at run-time, for example to tri-state pins when the
  13. device is inactive. Hence, each client device can define a set of named
  14. states. The number and names of those states is defined by the client device's
  15. own binding.
  16. The common pinctrl bindings defined in this file provide an infrastructure
  17. for client device device tree nodes to map those state names to the pin
  18. configuration used by those states.
  19. Note that pin controllers themselves may also be client devices of themselves.
  20. For example, a pin controller may set up its own "active" state when the
  21. driver loads. This would allow representing a board's static pin configuration
  22. in a single place, rather than splitting it across multiple client device
  23. nodes. The decision to do this or not somewhat rests with the author of
  24. individual board device tree files, and any requirements imposed by the
  25. bindings for the individual client devices in use by that board, i.e. whether
  26. they require certain specific named states for dynamic pin configuration.
  27. == Pinctrl client devices ==
  28. For each client device individually, every pin state is assigned an integer
  29. ID. These numbers start at 0, and are contiguous. For each state ID, a unique
  30. property exists to define the pin configuration. Each state may also be
  31. assigned a name. When names are used, another property exists to map from
  32. those names to the integer IDs.
  33. Each client device's own binding determines the set of states that must be
  34. defined in its device tree node, and whether to define the set of state
  35. IDs that must be provided, or whether to define the set of state names that
  36. must be provided.
  37. Required properties:
  38. pinctrl-0: List of phandles, each pointing at a pin configuration
  39. node. These referenced pin configuration nodes must be child
  40. nodes of the pin controller that they configure. Multiple
  41. entries may exist in this list so that multiple pin
  42. controllers may be configured, or so that a state may be built
  43. from multiple nodes for a single pin controller, each
  44. contributing part of the overall configuration. See the next
  45. section of this document for details of the format of these
  46. pin configuration nodes.
  47. In some cases, it may be useful to define a state, but for it
  48. to be empty. This may be required when a common IP block is
  49. used in an SoC either without a pin controller, or where the
  50. pin controller does not affect the HW module in question. If
  51. the binding for that IP block requires certain pin states to
  52. exist, they must still be defined, but may be left empty.
  53. Optional properties:
  54. pinctrl-1: List of phandles, each pointing at a pin configuration
  55. node within a pin controller.
  56. ...
  57. pinctrl-n: List of phandles, each pointing at a pin configuration
  58. node within a pin controller.
  59. pinctrl-names: The list of names to assign states. List entry 0 defines the
  60. name for integer state ID 0, list entry 1 for state ID 1, and
  61. so on.
  62. For example:
  63. /* For a client device requiring named states */
  64. device {
  65. pinctrl-names = "active", "idle";
  66. pinctrl-0 = <&state_0_node_a>;
  67. pinctrl-1 = <&state_1_node_a &state_1_node_b>;
  68. };
  69. /* For the same device if using state IDs */
  70. device {
  71. pinctrl-0 = <&state_0_node_a>;
  72. pinctrl-1 = <&state_1_node_a &state_1_node_b>;
  73. };
  74. /*
  75. * For an IP block whose binding supports pin configuration,
  76. * but in use on an SoC that doesn't have any pin control hardware
  77. */
  78. device {
  79. pinctrl-names = "active", "idle";
  80. pinctrl-0 = <>;
  81. pinctrl-1 = <>;
  82. };
  83. == Pin controller devices ==
  84. Pin controller devices should contain the pin configuration nodes that client
  85. devices reference.
  86. For example:
  87. pincontroller {
  88. ... /* Standard DT properties for the device itself elided */
  89. state_0_node_a {
  90. ...
  91. };
  92. state_1_node_a {
  93. ...
  94. };
  95. state_1_node_b {
  96. ...
  97. };
  98. }
  99. The contents of each of those pin configuration child nodes is defined
  100. entirely by the binding for the individual pin controller device. There
  101. exists no common standard for this content. The pinctrl framework only
  102. provides generic helper bindings that the pin controller driver can use.
  103. The pin configuration nodes need not be direct children of the pin controller
  104. device; they may be grandchildren, for example. Whether this is legal, and
  105. whether there is any interaction between the child and intermediate parent
  106. nodes, is again defined entirely by the binding for the individual pin
  107. controller device.
  108. == Generic pin multiplexing node content ==
  109. pin multiplexing nodes:
  110. function - the mux function to select
  111. groups - the list of groups to select with this function
  112. (either this or "pins" must be specified)
  113. pins - the list of pins to select with this function (either
  114. this or "groups" must be specified)
  115. Example:
  116. state_0_node_a {
  117. uart0 {
  118. function = "uart0";
  119. groups = "u0rxtx", "u0rtscts";
  120. };
  121. };
  122. state_1_node_a {
  123. spi0 {
  124. function = "spi0";
  125. groups = "spi0pins";
  126. };
  127. };
  128. state_2_node_a {
  129. function = "i2c0";
  130. pins = "mfio29", "mfio30";
  131. };
  132. For hardware where pin multiplexing configurations have to be specified for
  133. each single pin the number of required sub-nodes containing "pin" and
  134. "function" properties can quickly escalate and become hard to write and
  135. maintain.
  136. For cases like this, the pin controller driver may use the pinmux helper
  137. property, where the pin identifier is provided with mux configuration settings
  138. in a pinmux group. A pinmux group consists of the pin identifier and mux
  139. settings represented as a single integer or an array of integers.
  140. The pinmux property accepts an array of pinmux groups, each of them describing
  141. a single pin multiplexing configuration.
  142. pincontroller {
  143. state_0_node_a {
  144. pinmux = <PINMUX_GROUP>, <PINMUX_GROUP>, ...;
  145. };
  146. };
  147. Each individual pin controller driver bindings documentation shall specify
  148. how pin IDs and pin multiplexing configuration are defined and assembled
  149. together in a pinmux group.
  150. == Generic pin configuration node content ==
  151. Many data items that are represented in a pin configuration node are common
  152. and generic. Pin control bindings should use the properties defined below
  153. where they are applicable; not all of these properties are relevant or useful
  154. for all hardware or binding structures. Each individual binding document
  155. should state which of these generic properties, if any, are used, and the
  156. structure of the DT nodes that contain these properties.
  157. Supported generic properties are:
  158. pins - the list of pins that properties in the node
  159. apply to (either this, "group" or "pinmux" has to be
  160. specified)
  161. group - the group to apply the properties to, if the driver
  162. supports configuration of whole groups rather than
  163. individual pins (either this, "pins" or "pinmux" has
  164. to be specified)
  165. pinmux - the list of numeric pin ids and their mux settings
  166. that properties in the node apply to (either this,
  167. "pins" or "groups" have to be specified)
  168. bias-disable - disable any pin bias
  169. bias-high-impedance - high impedance mode ("third-state", "floating")
  170. bias-bus-hold - latch weakly
  171. bias-pull-up - pull up the pin
  172. bias-pull-down - pull down the pin
  173. bias-pull-pin-default - use pin-default pull state
  174. drive-push-pull - drive actively high and low
  175. drive-open-drain - drive with open drain
  176. drive-open-source - drive with open source
  177. drive-strength - sink or source at most X mA
  178. drive-strength-microamp - sink or source at most X uA
  179. input-enable - enable input on pin (no effect on output, such as
  180. enabling an input buffer)
  181. input-disable - disable input on pin (no effect on output, such as
  182. disabling an input buffer)
  183. input-schmitt-enable - enable schmitt-trigger mode
  184. input-schmitt-disable - disable schmitt-trigger mode
  185. input-debounce - debounce mode with debound time X
  186. power-source - select between different power supplies
  187. low-power-enable - enable low power mode
  188. low-power-disable - disable low power mode
  189. output-disable - disable output on a pin (such as disable an output
  190. buffer)
  191. output-enable - enable output on a pin without actively driving it
  192. (such as enabling an output buffer)
  193. output-low - set the pin to output mode with low level
  194. output-high - set the pin to output mode with high level
  195. sleep-hardware-state - indicate this is sleep related state which will be programmed
  196. into the registers for the sleep state.
  197. slew-rate - set the slew rate
  198. skew-delay - this affects the expected clock skew on input pins
  199. and the delay before latching a value to an output
  200. pin. Typically indicates how many double-inverters are
  201. used to delay the signal.
  202. For example:
  203. state_0_node_a {
  204. cts_rxd {
  205. pins = "GPIO0_AJ5", "GPIO2_AH4"; /* CTS+RXD */
  206. bias-pull-up;
  207. };
  208. };
  209. state_1_node_a {
  210. rts_txd {
  211. pins = "GPIO1_AJ3", "GPIO3_AH3"; /* RTS+TXD */
  212. output-high;
  213. };
  214. };
  215. state_2_node_a {
  216. foo {
  217. group = "foo-group";
  218. bias-pull-up;
  219. };
  220. };
  221. state_3_node_a {
  222. mux {
  223. pinmux = <GPIOx_PINm_MUXn>, <GPIOx_PINj_MUXk)>;
  224. input-enable;
  225. };
  226. };
  227. Some of the generic properties take arguments. For those that do, the
  228. arguments are described below.
  229. - pins takes a list of pin names or IDs as a required argument. The specific
  230. binding for the hardware defines:
  231. - Whether the entries are integers or strings, and their meaning.
  232. - pinmux takes a list of pin IDs and mux settings as required argument. The
  233. specific bindings for the hardware defines:
  234. - How pin IDs and mux settings are defined and assembled together in a single
  235. integer or an array of integers.
  236. - bias-pull-up, -down and -pin-default take as optional argument on hardware
  237. supporting it the pull strength in Ohm. bias-disable will disable the pull.
  238. - drive-strength takes as argument the target strength in mA.
  239. - drive-strength-microamp takes as argument the target strength in uA.
  240. - input-debounce takes the debounce time in usec as argument
  241. or 0 to disable debouncing
  242. More in-depth documentation on these parameters can be found in
  243. <include/linux/pinctrl/pinconf-generic.h>