pinctrl.h 18 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444
  1. /* SPDX-License-Identifier: GPL-2.0+ */
  2. /*
  3. * Copyright (C) 2015 Masahiro Yamada <yamada.masahiro@socionext.com>
  4. */
  5. #ifndef __PINCTRL_H
  6. #define __PINCTRL_H
  7. #define PINNAME_SIZE 10
  8. #define PINMUX_SIZE 40
  9. /**
  10. * struct pinconf_param - pin config parameters
  11. *
  12. * @property: property name in DT nodes
  13. * @param: ID for this config parameter
  14. * @default_value: default value for this config parameter used in case
  15. * no value is specified in DT nodes
  16. */
  17. struct pinconf_param {
  18. const char * const property;
  19. unsigned int param;
  20. u32 default_value;
  21. };
  22. /**
  23. * struct pinctrl_ops - pin control operations, to be implemented by
  24. * pin controller drivers.
  25. *
  26. * The @set_state is the only mandatory operation. You can implement your
  27. * pinctrl driver with its own @set_state. In this case, the other callbacks
  28. * are not required. Otherwise, generic pinctrl framework is also available;
  29. * use pinctrl_generic_set_state for @set_state, and implement other operations
  30. * depending on your necessity.
  31. *
  32. * @get_pins_count: return number of selectable named pins available
  33. * in this driver. (necessary to parse "pins" property in DTS)
  34. * @get_pin_name: return the pin name of the pin selector,
  35. * called by the core to figure out which pin it shall do
  36. * operations to. (necessary to parse "pins" property in DTS)
  37. * @get_groups_count: return number of selectable named groups available
  38. * in this driver. (necessary to parse "groups" property in DTS)
  39. * @get_group_name: return the group name of the group selector,
  40. * called by the core to figure out which pin group it shall do
  41. * operations to. (necessary to parse "groups" property in DTS)
  42. * @get_functions_count: return number of selectable named functions available
  43. * in this driver. (necessary for pin-muxing)
  44. * @get_function_name: return the function name of the muxing selector,
  45. * called by the core to figure out which mux setting it shall map a
  46. * certain device to. (necessary for pin-muxing)
  47. * @pinmux_set: enable a certain muxing function with a certain pin.
  48. * The @func_selector selects a certain function whereas @pin_selector
  49. * selects a certain pin to be used. On simple controllers one of them
  50. * may be ignored. (necessary for pin-muxing against a single pin)
  51. * @pinmux_group_set: enable a certain muxing function with a certain pin
  52. * group. The @func_selector selects a certain function whereas
  53. * @group_selector selects a certain set of pins to be used. On simple
  54. * controllers one of them may be ignored.
  55. * (necessary for pin-muxing against a pin group)
  56. * @pinconf_num_params: number of driver-specific parameters to be parsed
  57. * from device trees (necessary for pin-configuration)
  58. * @pinconf_params: list of driver_specific parameters to be parsed from
  59. * device trees (necessary for pin-configuration)
  60. * @pinconf_set: configure an individual pin with a given parameter.
  61. * (necessary for pin-configuration against a single pin)
  62. * @pinconf_group_set: configure all pins in a group with a given parameter.
  63. * (necessary for pin-configuration against a pin group)
  64. * @set_state: do pinctrl operations specified by @config, a pseudo device
  65. * pointing a config node. (necessary for pinctrl_full)
  66. * @set_state_simple: do needed pinctrl operations for a peripherl @periph.
  67. * (necessary for pinctrl_simple)
  68. * @get_pin_muxing: display the muxing of a given pin.
  69. * @gpio_request_enable: requests and enables GPIO on a certain pin.
  70. * Implement this only if you can mux every pin individually as GPIO. The
  71. * affected GPIO range is passed along with an offset(pin number) into that
  72. * specific GPIO range - function selectors and pin groups are orthogonal
  73. * to this, the core will however make sure the pins do not collide.
  74. * @gpio_disable_free: free up GPIO muxing on a certain pin, the reverse of
  75. * @gpio_request_enable
  76. */
  77. struct pinctrl_ops {
  78. int (*get_pins_count)(struct udevice *dev);
  79. const char *(*get_pin_name)(struct udevice *dev, unsigned selector);
  80. int (*get_groups_count)(struct udevice *dev);
  81. const char *(*get_group_name)(struct udevice *dev, unsigned selector);
  82. int (*get_functions_count)(struct udevice *dev);
  83. const char *(*get_function_name)(struct udevice *dev,
  84. unsigned selector);
  85. int (*pinmux_set)(struct udevice *dev, unsigned pin_selector,
  86. unsigned func_selector);
  87. int (*pinmux_group_set)(struct udevice *dev, unsigned group_selector,
  88. unsigned func_selector);
  89. unsigned int pinconf_num_params;
  90. const struct pinconf_param *pinconf_params;
  91. int (*pinconf_set)(struct udevice *dev, unsigned pin_selector,
  92. unsigned param, unsigned argument);
  93. int (*pinconf_group_set)(struct udevice *dev, unsigned group_selector,
  94. unsigned param, unsigned argument);
  95. int (*set_state)(struct udevice *dev, struct udevice *config);
  96. /* for pinctrl-simple */
  97. int (*set_state_simple)(struct udevice *dev, struct udevice *periph);
  98. /**
  99. * request() - Request a particular pinctrl function
  100. *
  101. * This activates the selected function.
  102. *
  103. * @dev: Device to adjust (UCLASS_PINCTRL)
  104. * @func: Function number (driver-specific)
  105. * @return 0 if OK, -ve on error
  106. */
  107. int (*request)(struct udevice *dev, int func, int flags);
  108. /**
  109. * get_periph_id() - get the peripheral ID for a device
  110. *
  111. * This generally looks at the peripheral's device tree node to work
  112. * out the peripheral ID. The return value is normally interpreted as
  113. * enum periph_id. so long as this is defined by the platform (which it
  114. * should be).
  115. *
  116. * @dev: Pinctrl device to use for decoding
  117. * @periph: Device to check
  118. * @return peripheral ID of @periph, or -ENOENT on error
  119. */
  120. int (*get_periph_id)(struct udevice *dev, struct udevice *periph);
  121. /**
  122. * get_gpio_mux() - get the mux value for a particular GPIO
  123. *
  124. * This allows the raw mux value for a GPIO to be obtained. It is
  125. * useful for displaying the function being used by that GPIO, such
  126. * as with the 'gpio' command. This function is internal to the GPIO
  127. * subsystem and should not be used by generic code. Typically it is
  128. * used by a GPIO driver with knowledge of the SoC pinctrl setup.
  129. *
  130. * @dev: Pinctrl device to use
  131. * @banknum: GPIO bank number
  132. * @index: GPIO index within the bank
  133. * @return mux value (SoC-specific, e.g. 0 for input, 1 for output)
  134. */
  135. int (*get_gpio_mux)(struct udevice *dev, int banknum, int index);
  136. /**
  137. * get_pin_muxing() - show pin muxing
  138. *
  139. * This allows to display the muxing of a given pin. It's useful for
  140. * debug purpose to know if a pin is configured as GPIO or as an
  141. * alternate function and which one.
  142. * Typically it is used by a PINCTRL driver with knowledge of the SoC
  143. * pinctrl setup.
  144. *
  145. * @dev: Pinctrl device to use
  146. * @selector: Pin selector
  147. * @buf Pin's muxing description
  148. * @size Pin's muxing description length
  149. * return 0 if OK, -ve on error
  150. */
  151. int (*get_pin_muxing)(struct udevice *dev, unsigned int selector,
  152. char *buf, int size);
  153. /**
  154. * gpio_request_enable: requests and enables GPIO on a certain pin.
  155. *
  156. * @dev: Pinctrl device to use
  157. * @selector: Pin selector
  158. * return 0 if OK, -ve on error
  159. */
  160. int (*gpio_request_enable)(struct udevice *dev, unsigned int selector);
  161. /**
  162. * gpio_disable_free: free up GPIO muxing on a certain pin.
  163. *
  164. * @dev: Pinctrl device to use
  165. * @selector: Pin selector
  166. * return 0 if OK, -ve on error
  167. */
  168. int (*gpio_disable_free)(struct udevice *dev, unsigned int selector);
  169. };
  170. #define pinctrl_get_ops(dev) ((struct pinctrl_ops *)(dev)->driver->ops)
  171. /**
  172. * Generic pin configuration paramters
  173. *
  174. * enum pin_config_param - possible pin configuration parameters
  175. * @PIN_CONFIG_BIAS_BUS_HOLD: the pin will be set to weakly latch so that it
  176. * weakly drives the last value on a tristate bus, also known as a "bus
  177. * holder", "bus keeper" or "repeater". This allows another device on the
  178. * bus to change the value by driving the bus high or low and switching to
  179. * tristate. The argument is ignored.
  180. * @PIN_CONFIG_BIAS_DISABLE: disable any pin bias on the pin, a
  181. * transition from say pull-up to pull-down implies that you disable
  182. * pull-up in the process, this setting disables all biasing.
  183. * @PIN_CONFIG_BIAS_HIGH_IMPEDANCE: the pin will be set to a high impedance
  184. * mode, also know as "third-state" (tristate) or "high-Z" or "floating".
  185. * On output pins this effectively disconnects the pin, which is useful
  186. * if for example some other pin is going to drive the signal connected
  187. * to it for a while. Pins used for input are usually always high
  188. * impedance.
  189. * @PIN_CONFIG_BIAS_PULL_DOWN: the pin will be pulled down (usually with high
  190. * impedance to GROUND). If the argument is != 0 pull-down is enabled,
  191. * if it is 0, pull-down is total, i.e. the pin is connected to GROUND.
  192. * @PIN_CONFIG_BIAS_PULL_PIN_DEFAULT: the pin will be pulled up or down based
  193. * on embedded knowledge of the controller hardware, like current mux
  194. * function. The pull direction and possibly strength too will normally
  195. * be decided completely inside the hardware block and not be readable
  196. * from the kernel side.
  197. * If the argument is != 0 pull up/down is enabled, if it is 0, the
  198. * configuration is ignored. The proper way to disable it is to use
  199. * @PIN_CONFIG_BIAS_DISABLE.
  200. * @PIN_CONFIG_BIAS_PULL_UP: the pin will be pulled up (usually with high
  201. * impedance to VDD). If the argument is != 0 pull-up is enabled,
  202. * if it is 0, pull-up is total, i.e. the pin is connected to VDD.
  203. * @PIN_CONFIG_DRIVE_OPEN_DRAIN: the pin will be driven with open drain (open
  204. * collector) which means it is usually wired with other output ports
  205. * which are then pulled up with an external resistor. Setting this
  206. * config will enable open drain mode, the argument is ignored.
  207. * @PIN_CONFIG_DRIVE_OPEN_SOURCE: the pin will be driven with open source
  208. * (open emitter). Setting this config will enable open source mode, the
  209. * argument is ignored.
  210. * @PIN_CONFIG_DRIVE_PUSH_PULL: the pin will be driven actively high and
  211. * low, this is the most typical case and is typically achieved with two
  212. * active transistors on the output. Setting this config will enable
  213. * push-pull mode, the argument is ignored.
  214. * @PIN_CONFIG_DRIVE_STRENGTH: the pin will sink or source at most the current
  215. * passed as argument. The argument is in mA.
  216. * @PIN_CONFIG_DRIVE_STRENGTH_UA: the pin will sink or source at most the current
  217. * passed as argument. The argument is in uA.
  218. * @PIN_CONFIG_INPUT_DEBOUNCE: this will configure the pin to debounce mode,
  219. * which means it will wait for signals to settle when reading inputs. The
  220. * argument gives the debounce time in usecs. Setting the
  221. * argument to zero turns debouncing off.
  222. * @PIN_CONFIG_INPUT_ENABLE: enable the pin's input. Note that this does not
  223. * affect the pin's ability to drive output. 1 enables input, 0 disables
  224. * input.
  225. * @PIN_CONFIG_INPUT_SCHMITT: this will configure an input pin to run in
  226. * schmitt-trigger mode. If the schmitt-trigger has adjustable hysteresis,
  227. * the threshold value is given on a custom format as argument when
  228. * setting pins to this mode.
  229. * @PIN_CONFIG_INPUT_SCHMITT_ENABLE: control schmitt-trigger mode on the pin.
  230. * If the argument != 0, schmitt-trigger mode is enabled. If it's 0,
  231. * schmitt-trigger mode is disabled.
  232. * @PIN_CONFIG_LOW_POWER_MODE: this will configure the pin for low power
  233. * operation, if several modes of operation are supported these can be
  234. * passed in the argument on a custom form, else just use argument 1
  235. * to indicate low power mode, argument 0 turns low power mode off.
  236. * @PIN_CONFIG_OUTPUT_ENABLE: this will enable the pin's output mode
  237. * without driving a value there. For most platforms this reduces to
  238. * enable the output buffers and then let the pin controller current
  239. * configuration (eg. the currently selected mux function) drive values on
  240. * the line. Use argument 1 to enable output mode, argument 0 to disable
  241. * it.
  242. * @PIN_CONFIG_OUTPUT: this will configure the pin as an output and drive a
  243. * value on the line. Use argument 1 to indicate high level, argument 0 to
  244. * indicate low level. (Please see Documentation/driver-api/pinctl.rst,
  245. * section "GPIO mode pitfalls" for a discussion around this parameter.)
  246. * @PIN_CONFIG_POWER_SOURCE: if the pin can select between different power
  247. * supplies, the argument to this parameter (on a custom format) tells
  248. * the driver which alternative power source to use.
  249. * @PIN_CONFIG_SLEEP_HARDWARE_STATE: indicate this is sleep related state.
  250. * @PIN_CONFIG_SLEW_RATE: if the pin can select slew rate, the argument to
  251. * this parameter (on a custom format) tells the driver which alternative
  252. * slew rate to use.
  253. * @PIN_CONFIG_SKEW_DELAY: if the pin has programmable skew rate (on inputs)
  254. * or latch delay (on outputs) this parameter (in a custom format)
  255. * specifies the clock skew or latch delay. It typically controls how
  256. * many double inverters are put in front of the line.
  257. * @PIN_CONFIG_END: this is the last enumerator for pin configurations, if
  258. * you need to pass in custom configurations to the pin controller, use
  259. * PIN_CONFIG_END+1 as the base offset.
  260. * @PIN_CONFIG_MAX: this is the maximum configuration value that can be
  261. * presented using the packed format.
  262. */
  263. enum pin_config_param {
  264. PIN_CONFIG_BIAS_BUS_HOLD,
  265. PIN_CONFIG_BIAS_DISABLE,
  266. PIN_CONFIG_BIAS_HIGH_IMPEDANCE,
  267. PIN_CONFIG_BIAS_PULL_DOWN,
  268. PIN_CONFIG_BIAS_PULL_PIN_DEFAULT,
  269. PIN_CONFIG_BIAS_PULL_UP,
  270. PIN_CONFIG_DRIVE_OPEN_DRAIN,
  271. PIN_CONFIG_DRIVE_OPEN_SOURCE,
  272. PIN_CONFIG_DRIVE_PUSH_PULL,
  273. PIN_CONFIG_DRIVE_STRENGTH,
  274. PIN_CONFIG_DRIVE_STRENGTH_UA,
  275. PIN_CONFIG_INPUT_DEBOUNCE,
  276. PIN_CONFIG_INPUT_ENABLE,
  277. PIN_CONFIG_INPUT_SCHMITT,
  278. PIN_CONFIG_INPUT_SCHMITT_ENABLE,
  279. PIN_CONFIG_LOW_POWER_MODE,
  280. PIN_CONFIG_OUTPUT_ENABLE,
  281. PIN_CONFIG_OUTPUT,
  282. PIN_CONFIG_POWER_SOURCE,
  283. PIN_CONFIG_SLEEP_HARDWARE_STATE,
  284. PIN_CONFIG_SLEW_RATE,
  285. PIN_CONFIG_SKEW_DELAY,
  286. PIN_CONFIG_END = 0x7F,
  287. PIN_CONFIG_MAX = 0xFF,
  288. };
  289. #if CONFIG_IS_ENABLED(PINCTRL_GENERIC)
  290. /**
  291. * pinctrl_generic_set_state() - generic set_state operation
  292. * Parse the DT node of @config and its children and handle generic properties
  293. * such as "pins", "groups", "functions", and pin configuration parameters.
  294. *
  295. * @pctldev: pinctrl device
  296. * @config: config device (pseudo device), pointing a config node in DTS
  297. * @return: 0 on success, or negative error code on failure
  298. */
  299. int pinctrl_generic_set_state(struct udevice *pctldev, struct udevice *config);
  300. #else
  301. static inline int pinctrl_generic_set_state(struct udevice *pctldev,
  302. struct udevice *config)
  303. {
  304. return -EINVAL;
  305. }
  306. #endif
  307. #if CONFIG_IS_ENABLED(PINCTRL)
  308. /**
  309. * pinctrl_select_state() - set a device to a given state
  310. *
  311. * @dev: peripheral device
  312. * @statename: state name, like "default"
  313. * @return: 0 on success, or negative error code on failure
  314. */
  315. int pinctrl_select_state(struct udevice *dev, const char *statename);
  316. #else
  317. static inline int pinctrl_select_state(struct udevice *dev,
  318. const char *statename)
  319. {
  320. return -EINVAL;
  321. }
  322. #endif
  323. /**
  324. * pinctrl_request() - Request a particular pinctrl function
  325. *
  326. * @dev: Device to check (UCLASS_PINCTRL)
  327. * @func: Function number (driver-specific)
  328. * @flags: Flags (driver-specific)
  329. * @return 0 if OK, -ve on error
  330. */
  331. int pinctrl_request(struct udevice *dev, int func, int flags);
  332. /**
  333. * pinctrl_request_noflags() - Request a particular pinctrl function
  334. *
  335. * This is similar to pinctrl_request() but uses 0 for @flags.
  336. *
  337. * @dev: Device to check (UCLASS_PINCTRL)
  338. * @func: Function number (driver-specific)
  339. * @return 0 if OK, -ve on error
  340. */
  341. int pinctrl_request_noflags(struct udevice *dev, int func);
  342. /**
  343. * pinctrl_get_periph_id() - get the peripheral ID for a device
  344. *
  345. * This generally looks at the peripheral's device tree node to work out the
  346. * peripheral ID. The return value is normally interpreted as enum periph_id.
  347. * so long as this is defined by the platform (which it should be).
  348. *
  349. * @dev: Pinctrl device to use for decoding
  350. * @periph: Device to check
  351. * @return peripheral ID of @periph, or -ENOENT on error
  352. */
  353. int pinctrl_get_periph_id(struct udevice *dev, struct udevice *periph);
  354. /**
  355. * pinctrl_get_gpio_mux() - get the mux value for a particular GPIO
  356. *
  357. * This allows the raw mux value for a GPIO to be obtained. It is
  358. * useful for displaying the function being used by that GPIO, such
  359. * as with the 'gpio' command. This function is internal to the GPIO
  360. * subsystem and should not be used by generic code. Typically it is
  361. * used by a GPIO driver with knowledge of the SoC pinctrl setup.
  362. *
  363. * @dev: Pinctrl device to use
  364. * @banknum: GPIO bank number
  365. * @index: GPIO index within the bank
  366. * @return mux value (SoC-specific, e.g. 0 for input, 1 for output)
  367. */
  368. int pinctrl_get_gpio_mux(struct udevice *dev, int banknum, int index);
  369. /**
  370. * pinctrl_get_pin_muxing() - Returns the muxing description
  371. *
  372. * This allows to display the muxing description of the given pin for
  373. * debug purpose
  374. *
  375. * @dev: Pinctrl device to use
  376. * @selector Pin index within pin-controller
  377. * @buf Pin's muxing description
  378. * @size Pin's muxing description length
  379. * @return 0 if OK, -ve on error
  380. */
  381. int pinctrl_get_pin_muxing(struct udevice *dev, int selector, char *buf,
  382. int size);
  383. /**
  384. * pinctrl_get_pins_count() - display pin-controller pins number
  385. *
  386. * This allows to know the number of pins owned by a given pin-controller
  387. *
  388. * @dev: Pinctrl device to use
  389. * @return pins number if OK, -ve on error
  390. */
  391. int pinctrl_get_pins_count(struct udevice *dev);
  392. /**
  393. * pinctrl_get_pin_name() - Returns the pin's name
  394. *
  395. * This allows to display the pin's name for debug purpose
  396. *
  397. * @dev: Pinctrl device to use
  398. * @selector Pin index within pin-controller
  399. * @buf Pin's name
  400. * @return 0 if OK, -ve on error
  401. */
  402. int pinctrl_get_pin_name(struct udevice *dev, int selector, char *buf,
  403. int size);
  404. /**
  405. * pinctrl_gpio_request() - request a single pin to be used as GPIO
  406. *
  407. * @dev: GPIO peripheral device
  408. * @offset: the GPIO pin offset from the GPIO controller
  409. * @return: 0 on success, or negative error code on failure
  410. */
  411. int pinctrl_gpio_request(struct udevice *dev, unsigned offset);
  412. /**
  413. * pinctrl_gpio_free() - free a single pin used as GPIO
  414. *
  415. * @dev: GPIO peripheral device
  416. * @offset: the GPIO pin offset from the GPIO controller
  417. * @return: 0 on success, or negative error code on failure
  418. */
  419. int pinctrl_gpio_free(struct udevice *dev, unsigned offset);
  420. #endif /* __PINCTRL_H */