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