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