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