1 /* SPDX-License-Identifier: GPL-2.0 */ 2 #ifndef __LINUX_GPIO_DRIVER_H 3 #define __LINUX_GPIO_DRIVER_H 4 5 #include <linux/device.h> 6 #include <linux/types.h> 7 #include <linux/irq.h> 8 #include <linux/irqchip/chained_irq.h> 9 #include <linux/irqdomain.h> 10 #include <linux/lockdep.h> 11 #include <linux/pinctrl/pinctrl.h> 12 #include <linux/pinctrl/pinconf-generic.h> 13 14 struct gpio_desc; 15 struct of_phandle_args; 16 struct device_node; 17 struct seq_file; 18 struct gpio_device; 19 struct module; 20 21 #ifdef CONFIG_GPIOLIB 22 23 #ifdef CONFIG_GPIOLIB_IRQCHIP 24 /** 25 * struct gpio_irq_chip - GPIO interrupt controller 26 */ 27 struct gpio_irq_chip { 28 /** 29 * @chip: 30 * 31 * GPIO IRQ chip implementation, provided by GPIO driver. 32 */ 33 struct irq_chip *chip; 34 35 /** 36 * @domain: 37 * 38 * Interrupt translation domain; responsible for mapping between GPIO 39 * hwirq number and Linux IRQ number. 40 */ 41 struct irq_domain *domain; 42 43 /** 44 * @domain_ops: 45 * 46 * Table of interrupt domain operations for this IRQ chip. 47 */ 48 const struct irq_domain_ops *domain_ops; 49 50 /** 51 * @handler: 52 * 53 * The IRQ handler to use (often a predefined IRQ core function) for 54 * GPIO IRQs, provided by GPIO driver. 55 */ 56 irq_flow_handler_t handler; 57 58 /** 59 * @default_type: 60 * 61 * Default IRQ triggering type applied during GPIO driver 62 * initialization, provided by GPIO driver. 63 */ 64 unsigned int default_type; 65 66 /** 67 * @lock_key: 68 * 69 * Per GPIO IRQ chip lockdep class. 70 */ 71 struct lock_class_key *lock_key; 72 73 /** 74 * @parent_handler: 75 * 76 * The interrupt handler for the GPIO chip's parent interrupts, may be 77 * NULL if the parent interrupts are nested rather than cascaded. 78 */ 79 irq_flow_handler_t parent_handler; 80 81 /** 82 * @parent_handler_data: 83 * 84 * Data associated, and passed to, the handler for the parent 85 * interrupt. 86 */ 87 void *parent_handler_data; 88 89 /** 90 * @num_parents: 91 * 92 * The number of interrupt parents of a GPIO chip. 93 */ 94 unsigned int num_parents; 95 96 /** 97 * @parents: 98 * 99 * A list of interrupt parents of a GPIO chip. This is owned by the 100 * driver, so the core will only reference this list, not modify it. 101 */ 102 unsigned int *parents; 103 104 /** 105 * @map: 106 * 107 * A list of interrupt parents for each line of a GPIO chip. 108 */ 109 unsigned int *map; 110 111 /** 112 * @threaded: 113 * 114 * True if set the interrupt handling uses nested threads. 115 */ 116 bool threaded; 117 118 /** 119 * @need_valid_mask: 120 * 121 * If set core allocates @valid_mask with all bits set to one. 122 */ 123 bool need_valid_mask; 124 125 /** 126 * @valid_mask: 127 * 128 * If not %NULL holds bitmask of GPIOs which are valid to be included 129 * in IRQ domain of the chip. 130 */ 131 unsigned long *valid_mask; 132 133 /** 134 * @first: 135 * 136 * Required for static IRQ allocation. If set, irq_domain_add_simple() 137 * will allocate and map all IRQs during initialization. 138 */ 139 unsigned int first; 140 }; 141 142 static inline struct gpio_irq_chip *to_gpio_irq_chip(struct irq_chip *chip) 143 { 144 return container_of(chip, struct gpio_irq_chip, chip); 145 } 146 #endif 147 148 /** 149 * struct gpio_chip - abstract a GPIO controller 150 * @label: a functional name for the GPIO device, such as a part 151 * number or the name of the SoC IP-block implementing it. 152 * @gpiodev: the internal state holder, opaque struct 153 * @parent: optional parent device providing the GPIOs 154 * @owner: helps prevent removal of modules exporting active GPIOs 155 * @request: optional hook for chip-specific activation, such as 156 * enabling module power and clock; may sleep 157 * @free: optional hook for chip-specific deactivation, such as 158 * disabling module power and clock; may sleep 159 * @get_direction: returns direction for signal "offset", 0=out, 1=in, 160 * (same as GPIOF_DIR_XXX), or negative error 161 * @direction_input: configures signal "offset" as input, or returns error 162 * @direction_output: configures signal "offset" as output, or returns error 163 * @get: returns value for signal "offset", 0=low, 1=high, or negative error 164 * @get_multiple: reads values for multiple signals defined by "mask" and 165 * stores them in "bits", returns 0 on success or negative error 166 * @set: assigns output value for signal "offset" 167 * @set_multiple: assigns output values for multiple signals defined by "mask" 168 * @set_config: optional hook for all kinds of settings. Uses the same 169 * packed config format as generic pinconf. 170 * @to_irq: optional hook supporting non-static gpio_to_irq() mappings; 171 * implementation may not sleep 172 * @dbg_show: optional routine to show contents in debugfs; default code 173 * will be used when this is omitted, but custom code can show extra 174 * state (such as pullup/pulldown configuration). 175 * @base: identifies the first GPIO number handled by this chip; 176 * or, if negative during registration, requests dynamic ID allocation. 177 * DEPRECATION: providing anything non-negative and nailing the base 178 * offset of GPIO chips is deprecated. Please pass -1 as base to 179 * let gpiolib select the chip base in all possible cases. We want to 180 * get rid of the static GPIO number space in the long run. 181 * @ngpio: the number of GPIOs handled by this controller; the last GPIO 182 * handled is (base + ngpio - 1). 183 * @names: if set, must be an array of strings to use as alternative 184 * names for the GPIOs in this chip. Any entry in the array 185 * may be NULL if there is no alias for the GPIO, however the 186 * array must be @ngpio entries long. A name can include a single printk 187 * format specifier for an unsigned int. It is substituted by the actual 188 * number of the gpio. 189 * @can_sleep: flag must be set iff get()/set() methods sleep, as they 190 * must while accessing GPIO expander chips over I2C or SPI. This 191 * implies that if the chip supports IRQs, these IRQs need to be threaded 192 * as the chip access may sleep when e.g. reading out the IRQ status 193 * registers. 194 * @read_reg: reader function for generic GPIO 195 * @write_reg: writer function for generic GPIO 196 * @be_bits: if the generic GPIO has big endian bit order (bit 31 is representing 197 * line 0, bit 30 is line 1 ... bit 0 is line 31) this is set to true by the 198 * generic GPIO core. It is for internal housekeeping only. 199 * @reg_dat: data (in) register for generic GPIO 200 * @reg_set: output set register (out=high) for generic GPIO 201 * @reg_clr: output clear register (out=low) for generic GPIO 202 * @reg_dir: direction setting register for generic GPIO 203 * @bgpio_bits: number of register bits used for a generic GPIO i.e. 204 * <register width> * 8 205 * @bgpio_lock: used to lock chip->bgpio_data. Also, this is needed to keep 206 * shadowed and real data registers writes together. 207 * @bgpio_data: shadowed data register for generic GPIO to clear/set bits 208 * safely. 209 * @bgpio_dir: shadowed direction register for generic GPIO to clear/set 210 * direction safely. 211 * 212 * A gpio_chip can help platforms abstract various sources of GPIOs so 213 * they can all be accessed through a common programing interface. 214 * Example sources would be SOC controllers, FPGAs, multifunction 215 * chips, dedicated GPIO expanders, and so on. 216 * 217 * Each chip controls a number of signals, identified in method calls 218 * by "offset" values in the range 0..(@ngpio - 1). When those signals 219 * are referenced through calls like gpio_get_value(gpio), the offset 220 * is calculated by subtracting @base from the gpio number. 221 */ 222 struct gpio_chip { 223 const char *label; 224 struct gpio_device *gpiodev; 225 struct device *parent; 226 struct module *owner; 227 228 int (*request)(struct gpio_chip *chip, 229 unsigned offset); 230 void (*free)(struct gpio_chip *chip, 231 unsigned offset); 232 int (*get_direction)(struct gpio_chip *chip, 233 unsigned offset); 234 int (*direction_input)(struct gpio_chip *chip, 235 unsigned offset); 236 int (*direction_output)(struct gpio_chip *chip, 237 unsigned offset, int value); 238 int (*get)(struct gpio_chip *chip, 239 unsigned offset); 240 int (*get_multiple)(struct gpio_chip *chip, 241 unsigned long *mask, 242 unsigned long *bits); 243 void (*set)(struct gpio_chip *chip, 244 unsigned offset, int value); 245 void (*set_multiple)(struct gpio_chip *chip, 246 unsigned long *mask, 247 unsigned long *bits); 248 int (*set_config)(struct gpio_chip *chip, 249 unsigned offset, 250 unsigned long config); 251 int (*to_irq)(struct gpio_chip *chip, 252 unsigned offset); 253 254 void (*dbg_show)(struct seq_file *s, 255 struct gpio_chip *chip); 256 int base; 257 u16 ngpio; 258 const char *const *names; 259 bool can_sleep; 260 261 #if IS_ENABLED(CONFIG_GPIO_GENERIC) 262 unsigned long (*read_reg)(void __iomem *reg); 263 void (*write_reg)(void __iomem *reg, unsigned long data); 264 bool be_bits; 265 void __iomem *reg_dat; 266 void __iomem *reg_set; 267 void __iomem *reg_clr; 268 void __iomem *reg_dir; 269 int bgpio_bits; 270 spinlock_t bgpio_lock; 271 unsigned long bgpio_data; 272 unsigned long bgpio_dir; 273 #endif 274 275 #ifdef CONFIG_GPIOLIB_IRQCHIP 276 /* 277 * With CONFIG_GPIOLIB_IRQCHIP we get an irqchip inside the gpiolib 278 * to handle IRQs for most practical cases. 279 */ 280 281 /** 282 * @irq: 283 * 284 * Integrates interrupt chip functionality with the GPIO chip. Can be 285 * used to handle IRQs for most practical cases. 286 */ 287 struct gpio_irq_chip irq; 288 #endif 289 290 #if defined(CONFIG_OF_GPIO) 291 /* 292 * If CONFIG_OF is enabled, then all GPIO controllers described in the 293 * device tree automatically may have an OF translation 294 */ 295 296 /** 297 * @of_node: 298 * 299 * Pointer to a device tree node representing this GPIO controller. 300 */ 301 struct device_node *of_node; 302 303 /** 304 * @of_gpio_n_cells: 305 * 306 * Number of cells used to form the GPIO specifier. 307 */ 308 unsigned int of_gpio_n_cells; 309 310 /** 311 * @of_xlate: 312 * 313 * Callback to translate a device tree GPIO specifier into a chip- 314 * relative GPIO number and flags. 315 */ 316 int (*of_xlate)(struct gpio_chip *gc, 317 const struct of_phandle_args *gpiospec, u32 *flags); 318 #endif 319 }; 320 321 extern const char *gpiochip_is_requested(struct gpio_chip *chip, 322 unsigned offset); 323 324 /* add/remove chips */ 325 extern int gpiochip_add_data_with_key(struct gpio_chip *chip, void *data, 326 struct lock_class_key *lock_key); 327 328 /** 329 * gpiochip_add_data() - register a gpio_chip 330 * @chip: the chip to register, with chip->base initialized 331 * @data: driver-private data associated with this chip 332 * 333 * Context: potentially before irqs will work 334 * 335 * When gpiochip_add_data() is called very early during boot, so that GPIOs 336 * can be freely used, the chip->parent device must be registered before 337 * the gpio framework's arch_initcall(). Otherwise sysfs initialization 338 * for GPIOs will fail rudely. 339 * 340 * gpiochip_add_data() must only be called after gpiolib initialization, 341 * ie after core_initcall(). 342 * 343 * If chip->base is negative, this requests dynamic assignment of 344 * a range of valid GPIOs. 345 * 346 * Returns: 347 * A negative errno if the chip can't be registered, such as because the 348 * chip->base is invalid or already associated with a different chip. 349 * Otherwise it returns zero as a success code. 350 */ 351 #ifdef CONFIG_LOCKDEP 352 #define gpiochip_add_data(chip, data) ({ \ 353 static struct lock_class_key key; \ 354 gpiochip_add_data_with_key(chip, data, &key); \ 355 }) 356 #else 357 #define gpiochip_add_data(chip, data) gpiochip_add_data_with_key(chip, data, NULL) 358 #endif 359 360 static inline int gpiochip_add(struct gpio_chip *chip) 361 { 362 return gpiochip_add_data(chip, NULL); 363 } 364 extern void gpiochip_remove(struct gpio_chip *chip); 365 extern int devm_gpiochip_add_data(struct device *dev, struct gpio_chip *chip, 366 void *data); 367 extern void devm_gpiochip_remove(struct device *dev, struct gpio_chip *chip); 368 369 extern struct gpio_chip *gpiochip_find(void *data, 370 int (*match)(struct gpio_chip *chip, void *data)); 371 372 /* lock/unlock as IRQ */ 373 int gpiochip_lock_as_irq(struct gpio_chip *chip, unsigned int offset); 374 void gpiochip_unlock_as_irq(struct gpio_chip *chip, unsigned int offset); 375 bool gpiochip_line_is_irq(struct gpio_chip *chip, unsigned int offset); 376 377 /* Line status inquiry for drivers */ 378 bool gpiochip_line_is_open_drain(struct gpio_chip *chip, unsigned int offset); 379 bool gpiochip_line_is_open_source(struct gpio_chip *chip, unsigned int offset); 380 381 /* Sleep persistence inquiry for drivers */ 382 bool gpiochip_line_is_persistent(struct gpio_chip *chip, unsigned int offset); 383 384 /* get driver data */ 385 void *gpiochip_get_data(struct gpio_chip *chip); 386 387 struct gpio_chip *gpiod_to_chip(const struct gpio_desc *desc); 388 389 struct bgpio_pdata { 390 const char *label; 391 int base; 392 int ngpio; 393 }; 394 395 #if IS_ENABLED(CONFIG_GPIO_GENERIC) 396 397 int bgpio_init(struct gpio_chip *gc, struct device *dev, 398 unsigned long sz, void __iomem *dat, void __iomem *set, 399 void __iomem *clr, void __iomem *dirout, void __iomem *dirin, 400 unsigned long flags); 401 402 #define BGPIOF_BIG_ENDIAN BIT(0) 403 #define BGPIOF_UNREADABLE_REG_SET BIT(1) /* reg_set is unreadable */ 404 #define BGPIOF_UNREADABLE_REG_DIR BIT(2) /* reg_dir is unreadable */ 405 #define BGPIOF_BIG_ENDIAN_BYTE_ORDER BIT(3) 406 #define BGPIOF_READ_OUTPUT_REG_SET BIT(4) /* reg_set stores output value */ 407 #define BGPIOF_NO_OUTPUT BIT(5) /* only input */ 408 409 #endif 410 411 #ifdef CONFIG_GPIOLIB_IRQCHIP 412 413 int gpiochip_irq_map(struct irq_domain *d, unsigned int irq, 414 irq_hw_number_t hwirq); 415 void gpiochip_irq_unmap(struct irq_domain *d, unsigned int irq); 416 417 void gpiochip_set_chained_irqchip(struct gpio_chip *gpiochip, 418 struct irq_chip *irqchip, 419 unsigned int parent_irq, 420 irq_flow_handler_t parent_handler); 421 422 void gpiochip_set_nested_irqchip(struct gpio_chip *gpiochip, 423 struct irq_chip *irqchip, 424 unsigned int parent_irq); 425 426 int gpiochip_irqchip_add_key(struct gpio_chip *gpiochip, 427 struct irq_chip *irqchip, 428 unsigned int first_irq, 429 irq_flow_handler_t handler, 430 unsigned int type, 431 bool threaded, 432 struct lock_class_key *lock_key); 433 434 #ifdef CONFIG_LOCKDEP 435 436 /* 437 * Lockdep requires that each irqchip instance be created with a 438 * unique key so as to avoid unnecessary warnings. This upfront 439 * boilerplate static inlines provides such a key for each 440 * unique instance. 441 */ 442 static inline int gpiochip_irqchip_add(struct gpio_chip *gpiochip, 443 struct irq_chip *irqchip, 444 unsigned int first_irq, 445 irq_flow_handler_t handler, 446 unsigned int type) 447 { 448 static struct lock_class_key key; 449 450 return gpiochip_irqchip_add_key(gpiochip, irqchip, first_irq, 451 handler, type, false, &key); 452 } 453 454 static inline int gpiochip_irqchip_add_nested(struct gpio_chip *gpiochip, 455 struct irq_chip *irqchip, 456 unsigned int first_irq, 457 irq_flow_handler_t handler, 458 unsigned int type) 459 { 460 461 static struct lock_class_key key; 462 463 return gpiochip_irqchip_add_key(gpiochip, irqchip, first_irq, 464 handler, type, true, &key); 465 } 466 #else 467 static inline int gpiochip_irqchip_add(struct gpio_chip *gpiochip, 468 struct irq_chip *irqchip, 469 unsigned int first_irq, 470 irq_flow_handler_t handler, 471 unsigned int type) 472 { 473 return gpiochip_irqchip_add_key(gpiochip, irqchip, first_irq, 474 handler, type, false, NULL); 475 } 476 477 static inline int gpiochip_irqchip_add_nested(struct gpio_chip *gpiochip, 478 struct irq_chip *irqchip, 479 unsigned int first_irq, 480 irq_flow_handler_t handler, 481 unsigned int type) 482 { 483 return gpiochip_irqchip_add_key(gpiochip, irqchip, first_irq, 484 handler, type, true, NULL); 485 } 486 #endif /* CONFIG_LOCKDEP */ 487 488 #endif /* CONFIG_GPIOLIB_IRQCHIP */ 489 490 int gpiochip_generic_request(struct gpio_chip *chip, unsigned offset); 491 void gpiochip_generic_free(struct gpio_chip *chip, unsigned offset); 492 int gpiochip_generic_config(struct gpio_chip *chip, unsigned offset, 493 unsigned long config); 494 495 #ifdef CONFIG_PINCTRL 496 497 /** 498 * struct gpio_pin_range - pin range controlled by a gpio chip 499 * @node: list for maintaining set of pin ranges, used internally 500 * @pctldev: pinctrl device which handles corresponding pins 501 * @range: actual range of pins controlled by a gpio controller 502 */ 503 struct gpio_pin_range { 504 struct list_head node; 505 struct pinctrl_dev *pctldev; 506 struct pinctrl_gpio_range range; 507 }; 508 509 int gpiochip_add_pin_range(struct gpio_chip *chip, const char *pinctl_name, 510 unsigned int gpio_offset, unsigned int pin_offset, 511 unsigned int npins); 512 int gpiochip_add_pingroup_range(struct gpio_chip *chip, 513 struct pinctrl_dev *pctldev, 514 unsigned int gpio_offset, const char *pin_group); 515 void gpiochip_remove_pin_ranges(struct gpio_chip *chip); 516 517 #else 518 519 static inline int 520 gpiochip_add_pin_range(struct gpio_chip *chip, const char *pinctl_name, 521 unsigned int gpio_offset, unsigned int pin_offset, 522 unsigned int npins) 523 { 524 return 0; 525 } 526 static inline int 527 gpiochip_add_pingroup_range(struct gpio_chip *chip, 528 struct pinctrl_dev *pctldev, 529 unsigned int gpio_offset, const char *pin_group) 530 { 531 return 0; 532 } 533 534 static inline void 535 gpiochip_remove_pin_ranges(struct gpio_chip *chip) 536 { 537 } 538 539 #endif /* CONFIG_PINCTRL */ 540 541 struct gpio_desc *gpiochip_request_own_desc(struct gpio_chip *chip, u16 hwnum, 542 const char *label); 543 void gpiochip_free_own_desc(struct gpio_desc *desc); 544 545 #else /* CONFIG_GPIOLIB */ 546 547 static inline struct gpio_chip *gpiod_to_chip(const struct gpio_desc *desc) 548 { 549 /* GPIO can never have been requested */ 550 WARN_ON(1); 551 return ERR_PTR(-ENODEV); 552 } 553 554 #endif /* CONFIG_GPIOLIB */ 555 556 #endif 557