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