1/* SPDX-License-Identifier: GPL-2.0+ */ 2/* 3 * Copyright (C) 2015 Masahiro Yamada <yamada.masahiro@com> 4 */ 5 6#ifndef __PINCTRL_H 7#define __PINCTRL_H 8 9#define PINNAME_SIZE 10 10#define PINMUX_SIZE 40 11 12/** 13 * struct pinconf_param - pin config parameters 14 * @property: Property name in DT nodes 15 * @param: ID for this config parameter 16 * @default_value: default value for this config parameter used in case 17 * no value is specified in DT nodes 18 */ 19struct pinconf_param { 20 const char * const property; 21 unsigned int param; 22 u32 default_value; 23}; 24 25/** 26 * struct pinctrl_ops - pin control operations, to be implemented by 27 * pin controller drivers. 28 * 29 * set_state() is the only mandatory operation. You can implement your pinctrl 30 * driver with its own @set_state. In this case, the other callbacks are not 31 * required. Otherwise, generic pinctrl framework is also available; use 32 * pinctrl_generic_set_state for @set_state, and implement other operations 33 * depending on your necessity. 34 */ 35struct pinctrl_ops { 36 /** 37 * @get_pins_count: Get the number of selectable pins 38 * 39 * @dev: Pinctrl device to use 40 * 41 * This function is necessary to parse the "pins" property in DTS. 42 * 43 * @Return: 44 * number of selectable named pins available in this driver 45 */ 46 int (*get_pins_count)(struct udevice *dev); 47 48 /** 49 * @get_pin_name: Get the name of a pin 50 * 51 * @dev: Pinctrl device of the pin 52 * 53 * @selector: The pin selector 54 * 55 * This function is called by the core to figure out which pin it will 56 * do operations to. This function is necessary to parse the "pins" 57 * property in DTS. 58 * 59 * @Return: const pointer to the name of the pin 60 */ 61 const char *(*get_pin_name)(struct udevice *dev, unsigned selector); 62 63 /** 64 * @get_groups_count: Get the number of selectable groups 65 * 66 * @dev: Pinctrl device to use 67 * 68 * This function is necessary to parse the "groups" property in DTS. 69 * 70 * @Return: 71 * number of selectable named groups available in the driver 72 */ 73 int (*get_groups_count)(struct udevice *dev); 74 75 /** 76 * @get_group_name: Get the name of a group 77 * 78 * @dev: Pinctrl device of the group 79 * 80 * @selector: The group selector 81 * 82 * This function is called by the core to figure out which group it 83 * will do operations to. This function is necessary to parse the 84 * "groups" property in DTS. 85 * 86 * @Return: Pointer to the name of the group 87 */ 88 const char *(*get_group_name)(struct udevice *dev, unsigned selector); 89 90 /** 91 * @get_functions_count: Get the number of selectable functions 92 * 93 * @dev: Pinctrl device to use 94 * 95 * This function is necessary for pin-muxing. 96 * 97 * @Return: 98 * number of selectable named functions available in this driver 99 */ 100 int (*get_functions_count)(struct udevice *dev); 101 102 /** 103 * @get_function_name: Get the name of a function 104 * 105 * @dev: Pinmux device of the function 106 * 107 * @selector: The function selector 108 * 109 * This function is called by the core to figure out which mux setting 110 * it will map a certain device to. This function is necessary for 111 * pin-muxing. 112 * 113 * @Return: 114 * Pointer to the function name of the muxing selector 115 */ 116 const char *(*get_function_name)(struct udevice *dev, 117 unsigned selector); 118 119 /** 120 * @pinmux_set: Mux a pin to a function 121 * 122 * @dev: Pinctrl device to use 123 * 124 * @pin_selector: The pin selector 125 * 126 * @func_selector: The func selector 127 * 128 * On simple controllers one of @pin_selector or @func_selector may be 129 * ignored. This function is necessary for pin-muxing against a single 130 * pin. 131 * 132 * @Return: 0 if OK, or negative error code on failure 133 */ 134 int (*pinmux_set)(struct udevice *dev, unsigned pin_selector, 135 unsigned func_selector); 136 137 /** 138 * @pinmux_group_set: Mux a group of pins to a function 139 * 140 * @dev: Pinctrl device to use 141 * 142 * @group_selector: The group selector 143 * 144 * @func_selector: The func selector 145 * 146 * On simple controllers one of @group_selector or @func_selector may be 147 * ignored. This function is necessary for pin-muxing against a group of 148 * pins. 149 * 150 * @Return: 0 if OK, or negative error code on failure 151 */ 152 int (*pinmux_group_set)(struct udevice *dev, unsigned group_selector, 153 unsigned func_selector); 154 155 /** 156 * @pinmux_property_set: Enable a pinmux group 157 * 158 * @dev: Pinctrl device to use 159 * 160 * @pinmux_group: A u32 representing the pin identifier and mux 161 * settings. The exact format of a pinmux group is left 162 * up to the driver. 163 * 164 * Mux a single pin to a single function based on a driver-specific 165 * pinmux group. This function is necessary for parsing the "pinmux" 166 * property in DTS, and for pin-muxing against a pinmux group. 167 * 168 * @Return: 169 * Pin selector for the muxed pin if OK, or negative error code on 170 * failure 171 */ 172 int (*pinmux_property_set)(struct udevice *dev, u32 pinmux_group); 173 174 /** 175 * @pinconf_num_params: 176 * Number of driver-specific parameters to be parsed from device 177 * trees. This member is necessary for pin configuration. 178 */ 179 unsigned int pinconf_num_params; 180 181 /** 182 * @pinconf_params: 183 * List of driver-specific parameters to be parsed from the device 184 * tree. This member is necessary for pin configuration. 185 */ 186 const struct pinconf_param *pinconf_params; 187 188 /** 189 * @pinconf_set: Configure an individual pin with a parameter 190 * 191 * @dev: Pinctrl device to use 192 * 193 * @pin_selector: The pin selector 194 * 195 * @param: An &enum pin_config_param from @pinconf_params 196 * 197 * @argument: The argument to this param from the device tree, or 198 * @pinconf_params.default_value 199 * 200 * This function is necessary for pin configuration against a single 201 * pin. 202 * 203 * @Return: 0 if OK, or negative error code on failure 204 */ 205 int (*pinconf_set)(struct udevice *dev, unsigned pin_selector, 206 unsigned param, unsigned argument); 207 208 /** 209 * @pinconf_group_set: Configure all pins in a group with a parameter 210 * 211 * @dev: Pinctrl device to use 212 * 213 * @pin_selector: The group selector 214 * 215 * @param: A &enum pin_config_param from 216 * @pinconf_params 217 * 218 * @argument: The argument to this param from the device tree, or 219 * @pinconf_params.default_value 220 * 221 * This function is necessary for pin configuration against a group of 222 * pins. 223 * 224 * @Return: 0 if OK, or negative error code on failure 225 */ 226 int (*pinconf_group_set)(struct udevice *dev, unsigned group_selector, 227 unsigned param, unsigned argument); 228 229 /** 230 * @set_state: Configure a pinctrl device 231 * 232 * @dev: Pinctrl device to use 233 * 234 * @config: Pseudo device pointing a config node 235 * 236 * This function is required to be implemented by all pinctrl drivers. 237 * Drivers may set this member to pinctrl_generic_set_state(), which 238 * will call other functions in &struct pinctrl_ops to parse 239 * @config. 240 * 241 * @Return: 0 if OK, or negative error code on failure 242 */ 243 int (*set_state)(struct udevice *dev, struct udevice *config); 244 245 /** 246 * @set_state_simple: Configure a pinctrl device 247 * 248 * @dev: Pinctrl device to use 249 * 250 * @config: Pseudo-device pointing a config node 251 * 252 * This function is usually a simpler version of set_state(). Only the 253 * first pinctrl device on the system is supported by this function. 254 * 255 * @Return: 0 if OK, or negative error code on failure 256 */ 257 int (*set_state_simple)(struct udevice *dev, struct udevice *periph); 258 259 /** 260 * @request: Request a particular pinctrl function 261 * 262 * @dev: Device to adjust (%UCLASS_PINCTRL) 263 * 264 * @func: Function number (driver-specific) 265 * 266 * This activates the selected function. 267 * 268 * @Return: 0 if OK, or negative error code on failure 269 */ 270 int (*request)(struct udevice *dev, int func, int flags); 271 272 /** 273 * @get_periph_id: Get the peripheral ID for a device 274 * 275 * @dev: Pinctrl device to use for decoding 276 * 277 * @periph: Device to check 278 * 279 * This generally looks at the peripheral's device tree node to work 280 * out the peripheral ID. The return value is normally interpreted as 281 * &enum periph_id. so long as this is defined by the platform (which it 282 * should be). 283 * 284 * @Return: 285 * Peripheral ID of @periph, or %-ENOENT on error 286 */ 287 int (*get_periph_id)(struct udevice *dev, struct udevice *periph); 288 289 /** 290 * @get_gpio_mux: Get the mux value for a particular GPIO 291 * 292 * @dev: Pinctrl device to use 293 * 294 * @banknum: GPIO bank number 295 * 296 * @index: GPIO index within the bank 297 * 298 * This allows the raw mux value for a GPIO to be obtained. It is 299 * useful for displaying the function being used by that GPIO, such 300 * as with the 'gpio' command. This function is internal to the GPIO 301 * subsystem and should not be used by generic code. Typically it is 302 * used by a GPIO driver with knowledge of the SoC pinctrl setup. 303 * 304 * @Return: 305 * Mux value (SoC-specific, e.g. 0 for input, 1 for output) 306 */ 307 int (*get_gpio_mux)(struct udevice *dev, int banknum, int index); 308 309 /** 310 * @get_pin_muxing: Show pin muxing 311 * 312 * @dev: Pinctrl device to use 313 * 314 * @selector: Pin selector 315 * 316 * @buf: Buffer to fill with pin muxing description 317 * 318 * @size: Size of @buf 319 * 320 * This allows to display the muxing of a given pin. It's useful for 321 * debug purposes to know if a pin is configured as GPIO or as an 322 * alternate function and which one. Typically it is used by a PINCTRL 323 * driver with knowledge of the SoC pinctrl setup. 324 * 325 * @Return: 0 if OK, or negative error code on failure 326 */ 327 int (*get_pin_muxing)(struct udevice *dev, unsigned int selector, 328 char *buf, int size); 329 330 /** 331 * @gpio_request_enable: Request and enable GPIO on a certain pin. 332 * 333 * @dev: Pinctrl device to use 334 * 335 * @selector: Pin selector 336 * 337 * Implement this only if you can mux every pin individually as GPIO. 338 * The affected GPIO range is passed along with an offset(pin number) 339 * into that specific GPIO range - function selectors and pin groups are 340 * orthogonal to this, the core will however make sure the pins do not 341 * collide. 342 * 343 * @Return: 344 * 0 if OK, or negative error code on failure 345 */ 346 int (*gpio_request_enable)(struct udevice *dev, unsigned int selector); 347 348 /** 349 * @gpio_disable_free: Free up GPIO muxing on a certain pin. 350 * 351 * @dev: Pinctrl device to use 352 * 353 * @selector: Pin selector 354 * 355 * This function is the reverse of @gpio_request_enable. 356 * 357 * @Return: 0 if OK, or negative error code on failure 358 */ 359 int (*gpio_disable_free)(struct udevice *dev, unsigned int selector); 360}; 361 362#define pinctrl_get_ops(dev) ((struct pinctrl_ops *)(dev)->driver->ops) 363 364/** 365 * enum pin_config_param - Generic pin configuration parameters 366 * 367 * @PIN_CONFIG_BIAS_BUS_HOLD: The pin will be set to weakly latch so that it 368 * weakly drives the last value on a tristate bus, also known as a "bus 369 * holder", "bus keeper" or "repeater". This allows another device on the 370 * bus to change the value by driving the bus high or low and switching to 371 * tristate. The argument is ignored. 372 * @PIN_CONFIG_BIAS_DISABLE: Disable any pin bias on the pin, a 373 * transition from say pull-up to pull-down implies that you disable 374 * pull-up in the process, this setting disables all biasing. 375 * @PIN_CONFIG_BIAS_HIGH_IMPEDANCE: The pin will be set to a high impedance 376 * mode, also know as "third-state" (tristate) or "high-Z" or "floating". 377 * On output pins this effectively disconnects the pin, which is useful 378 * if for example some other pin is going to drive the signal connected 379 * to it for a while. Pins used for input are usually always high 380 * impedance. 381 * @PIN_CONFIG_BIAS_PULL_DOWN: The pin will be pulled down (usually with high 382 * impedance to GROUND). If the argument is != 0 pull-down is enabled, 383 * if it is 0, pull-down is total, i.e. the pin is connected to GROUND. 384 * @PIN_CONFIG_BIAS_PULL_PIN_DEFAULT: The pin will be pulled up or down based 385 * on embedded knowledge of the controller hardware, like current mux 386 * function. The pull direction and possibly strength too will normally 387 * be decided completely inside the hardware block and not be readable 388 * from the kernel side. 389 * If the argument is != 0 pull up/down is enabled, if it is 0, the 390 * configuration is ignored. The proper way to disable it is to use 391 * @PIN_CONFIG_BIAS_DISABLE. 392 * @PIN_CONFIG_BIAS_PULL_UP: The pin will be pulled up (usually with high 393 * impedance to VDD). If the argument is != 0 pull-up is enabled, 394 * if it is 0, pull-up is total, i.e. the pin is connected to VDD. 395 * @PIN_CONFIG_DRIVE_OPEN_DRAIN: The pin will be driven with open drain (open 396 * collector) which means it is usually wired with other output ports 397 * which are then pulled up with an external resistor. Setting this 398 * config will enable open drain mode, the argument is ignored. 399 * @PIN_CONFIG_DRIVE_OPEN_SOURCE: The pin will be driven with open source 400 * (open emitter). Setting this config will enable open source mode, the 401 * argument is ignored. 402 * @PIN_CONFIG_DRIVE_PUSH_PULL: The pin will be driven actively high and 403 * low, this is the most typical case and is typically achieved with two 404 * active transistors on the output. Setting this config will enable 405 * push-pull mode, the argument is ignored. 406 * @PIN_CONFIG_DRIVE_STRENGTH: The pin will sink or source at most the current 407 * passed as argument. The argument is in mA. 408 * @PIN_CONFIG_DRIVE_STRENGTH_UA: The pin will sink or source at most the 409 * current passed as argument. The argument is in uA. 410 * @PIN_CONFIG_INPUT_DEBOUNCE: This will configure the pin to debounce mode, 411 * which means it will wait for signals to settle when reading inputs. The 412 * argument gives the debounce time in usecs. Setting the 413 * argument to zero turns debouncing off. 414 * @PIN_CONFIG_INPUT_ENABLE: Enable the pin's input. Note that this does not 415 * affect the pin's ability to drive output. 1 enables input, 0 disables 416 * input. 417 * @PIN_CONFIG_INPUT_SCHMITT: This will configure an input pin to run in 418 * schmitt-trigger mode. If the schmitt-trigger has adjustable hysteresis, 419 * the threshold value is given on a custom format as argument when 420 * setting pins to this mode. 421 * @PIN_CONFIG_INPUT_SCHMITT_ENABLE: Control schmitt-trigger mode on the pin. 422 * If the argument != 0, schmitt-trigger mode is enabled. If it's 0, 423 * schmitt-trigger mode is disabled. 424 * @PIN_CONFIG_LOW_POWER_MODE: This will configure the pin for low power 425 * operation, if several modes of operation are supported these can be 426 * passed in the argument on a custom form, else just use argument 1 427 * to indicate low power mode, argument 0 turns low power mode off. 428 * @PIN_CONFIG_OUTPUT_ENABLE: This will enable the pin's output mode 429 * without driving a value there. For most platforms this reduces to 430 * enable the output buffers and then let the pin controller current 431 * configuration (eg. the currently selected mux function) drive values on 432 * the line. Use argument 1 to enable output mode, argument 0 to disable 433 * it. 434 * @PIN_CONFIG_OUTPUT: This will configure the pin as an output and drive a 435 * value on the line. Use argument 1 to indicate high level, argument 0 to 436 * indicate low level. (Please see Documentation/driver-api/pinctl.rst, 437 * section "GPIO mode pitfalls" for a discussion around this parameter.) 438 * @PIN_CONFIG_POWER_SOURCE: If the pin can select between different power 439 * supplies, the argument to this parameter (on a custom format) tells 440 * the driver which alternative power source to use. 441 * @PIN_CONFIG_SLEEP_HARDWARE_STATE: Indicate this is sleep related state. 442 * @PIN_CONFIG_SLEW_RATE: If the pin can select slew rate, the argument to 443 * this parameter (on a custom format) tells the driver which alternative 444 * slew rate to use. 445 * @PIN_CONFIG_SKEW_DELAY: If the pin has programmable skew rate (on inputs) 446 * or latch delay (on outputs) this parameter (in a custom format) 447 * specifies the clock skew or latch delay. It typically controls how 448 * many double inverters are put in front of the line. 449 * @PIN_CONFIG_END: This is the last enumerator for pin configurations, if 450 * you need to pass in custom configurations to the pin controller, use 451 * PIN_CONFIG_END+1 as the base offset. 452 * @PIN_CONFIG_MAX: This is the maximum configuration value that can be 453 * presented using the packed format. 454 */ 455enum pin_config_param { 456 PIN_CONFIG_BIAS_BUS_HOLD, 457 PIN_CONFIG_BIAS_DISABLE, 458 PIN_CONFIG_BIAS_HIGH_IMPEDANCE, 459 PIN_CONFIG_BIAS_PULL_DOWN, 460 PIN_CONFIG_BIAS_PULL_PIN_DEFAULT, 461 PIN_CONFIG_BIAS_PULL_UP, 462 PIN_CONFIG_DRIVE_OPEN_DRAIN, 463 PIN_CONFIG_DRIVE_OPEN_SOURCE, 464 PIN_CONFIG_DRIVE_PUSH_PULL, 465 PIN_CONFIG_DRIVE_STRENGTH, 466 PIN_CONFIG_DRIVE_STRENGTH_UA, 467 PIN_CONFIG_INPUT_DEBOUNCE, 468 PIN_CONFIG_INPUT_ENABLE, 469 PIN_CONFIG_INPUT_SCHMITT, 470 PIN_CONFIG_INPUT_SCHMITT_ENABLE, 471 PIN_CONFIG_LOW_POWER_MODE, 472 PIN_CONFIG_OUTPUT_ENABLE, 473 PIN_CONFIG_OUTPUT, 474 PIN_CONFIG_POWER_SOURCE, 475 PIN_CONFIG_SLEEP_HARDWARE_STATE, 476 PIN_CONFIG_SLEW_RATE, 477 PIN_CONFIG_SKEW_DELAY, 478 PIN_CONFIG_END = 0x7F, 479 PIN_CONFIG_MAX = 0xFF, 480}; 481 482#if CONFIG_IS_ENABLED(PINCTRL_GENERIC) 483/** 484 * pinctrl_generic_set_state() - Generic set_state operation 485 * @pctldev: Pinctrl device to use 486 * @config: Config device (pseudo device), pointing a config node in DTS 487 * 488 * Parse the DT node of @config and its children and handle generic properties 489 * such as "pins", "groups", "functions", and pin configuration parameters. 490 * 491 * Return: 0 on success, or negative error code on failure 492 */ 493int pinctrl_generic_set_state(struct udevice *pctldev, struct udevice *config); 494#else 495static inline int pinctrl_generic_set_state(struct udevice *pctldev, 496 struct udevice *config) 497{ 498 return -EINVAL; 499} 500#endif 501 502#if CONFIG_IS_ENABLED(PINCTRL) 503/** 504 * pinctrl_select_state() - Set a device to a given state 505 * @dev: Peripheral device 506 * @statename: State name, like "default" 507 * 508 * Return: 0 on success, or negative error code on failure 509 */ 510int pinctrl_select_state(struct udevice *dev, const char *statename); 511#else 512static inline int pinctrl_select_state(struct udevice *dev, 513 const char *statename) 514{ 515 return -EINVAL; 516} 517#endif 518 519/** 520 * pinctrl_request() - Request a particular pinctrl function 521 * @dev: Pinctrl device to use 522 * @func: Function number (driver-specific) 523 * @flags: Flags (driver-specific) 524 * 525 * Return: 0 if OK, or negative error code on failure 526 */ 527int pinctrl_request(struct udevice *dev, int func, int flags); 528 529/** 530 * pinctrl_request_noflags() - Request a particular pinctrl function 531 * @dev: Pinctrl device to use 532 * @func: Function number (driver-specific) 533 * 534 * This is similar to pinctrl_request() but uses 0 for @flags. 535 * 536 * Return: 0 if OK, or negative error code on failure 537 */ 538int pinctrl_request_noflags(struct udevice *dev, int func); 539 540/** 541 * pinctrl_get_periph_id() - Get the peripheral ID for a device 542 * @dev: Pinctrl device to use for decoding 543 * @periph: Device to check 544 * 545 * This generally looks at the peripheral's device tree node to work out the 546 * peripheral ID. The return value is normally interpreted as enum periph_id. 547 * so long as this is defined by the platform (which it should be). 548 * 549 * Return: Peripheral ID of @periph, or -ENOENT on error 550 */ 551int pinctrl_get_periph_id(struct udevice *dev, struct udevice *periph); 552 553/** 554 * pinctrl_get_gpio_mux() - get the mux value for a particular GPIO 555 * @dev: Pinctrl device to use 556 * @banknum: GPIO bank number 557 * @index: GPIO index within the bank 558 * 559 * This allows the raw mux value for a GPIO to be obtained. It is 560 * useful for displaying the function being used by that GPIO, such 561 * as with the 'gpio' command. This function is internal to the GPIO 562 * subsystem and should not be used by generic code. Typically it is 563 * used by a GPIO driver with knowledge of the SoC pinctrl setup. 564 * 565 * Return: Mux value (SoC-specific, e.g. 0 for input, 1 for output) 566*/ 567int pinctrl_get_gpio_mux(struct udevice *dev, int banknum, int index); 568 569/** 570 * pinctrl_get_pin_muxing() - Returns the muxing description 571 * @dev: Pinctrl device to use 572 * @selector: Pin index within pin-controller 573 * @buf: Pin's muxing description 574 * @size: Pin's muxing description length 575 * 576 * This allows to display the muxing description of the given pin for 577 * debug purpose 578 * 579 * Return: 0 if OK, or negative error code on failure 580 */ 581int pinctrl_get_pin_muxing(struct udevice *dev, int selector, char *buf, 582 int size); 583 584/** 585 * pinctrl_get_pins_count() - Display pin-controller pins number 586 * @dev: Pinctrl device to use 587 * 588 * This allows to know the number of pins owned by a given pin-controller 589 * 590 * Return: Number of pins if OK, or negative error code on failure 591 */ 592int pinctrl_get_pins_count(struct udevice *dev); 593 594/** 595 * pinctrl_get_pin_name() - Returns the pin's name 596 * @dev: Pinctrl device to use 597 * @selector: Pin index within pin-controller 598 * @buf: Buffer to fill with the name of the pin 599 * @size: Size of @buf 600 * 601 * This allows to display the pin's name for debug purpose 602 * 603 * Return: 0 if OK, or negative error code on failure 604 */ 605int pinctrl_get_pin_name(struct udevice *dev, int selector, char *buf, 606 int size); 607 608/** 609 * pinctrl_gpio_request() - Request a single pin to be used as GPIO 610 * @dev: GPIO peripheral device 611 * @offset: GPIO pin offset from the GPIO controller 612 * 613 * Return: 0 on success, or negative error code on failure 614 */ 615int pinctrl_gpio_request(struct udevice *dev, unsigned offset); 616 617/** 618 * pinctrl_gpio_free() - Free a single pin used as GPIO 619 * @dev: GPIO peripheral device 620 * @offset: GPIO pin offset from the GPIO controller 621 * 622 * Return: 0 on success, or negative error code on failure 623 */ 624int pinctrl_gpio_free(struct udevice *dev, unsigned offset); 625 626#endif /* __PINCTRL_H */ 627