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