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: direction setting register for generic GPIO 231 * @bgpio_dir_inverted: indicates that the direction register is inverted 232 * (gpiolib private state variable) 233 * @bgpio_bits: number of register bits used for a generic GPIO i.e. 234 * <register width> * 8 235 * @bgpio_lock: used to lock chip->bgpio_data. Also, this is needed to keep 236 * shadowed and real data registers writes together. 237 * @bgpio_data: shadowed data register for generic GPIO to clear/set bits 238 * safely. 239 * @bgpio_dir: shadowed direction register for generic GPIO to clear/set 240 * direction safely. 241 * 242 * A gpio_chip can help platforms abstract various sources of GPIOs so 243 * they can all be accessed through a common programing interface. 244 * Example sources would be SOC controllers, FPGAs, multifunction 245 * chips, dedicated GPIO expanders, and so on. 246 * 247 * Each chip controls a number of signals, identified in method calls 248 * by "offset" values in the range 0..(@ngpio - 1). When those signals 249 * are referenced through calls like gpio_get_value(gpio), the offset 250 * is calculated by subtracting @base from the gpio number. 251 */ 252 struct gpio_chip { 253 const char *label; 254 struct gpio_device *gpiodev; 255 struct device *parent; 256 struct module *owner; 257 258 int (*request)(struct gpio_chip *chip, 259 unsigned offset); 260 void (*free)(struct gpio_chip *chip, 261 unsigned offset); 262 int (*get_direction)(struct gpio_chip *chip, 263 unsigned offset); 264 int (*direction_input)(struct gpio_chip *chip, 265 unsigned offset); 266 int (*direction_output)(struct gpio_chip *chip, 267 unsigned offset, int value); 268 int (*get)(struct gpio_chip *chip, 269 unsigned offset); 270 int (*get_multiple)(struct gpio_chip *chip, 271 unsigned long *mask, 272 unsigned long *bits); 273 void (*set)(struct gpio_chip *chip, 274 unsigned offset, int value); 275 void (*set_multiple)(struct gpio_chip *chip, 276 unsigned long *mask, 277 unsigned long *bits); 278 int (*set_config)(struct gpio_chip *chip, 279 unsigned offset, 280 unsigned long config); 281 int (*to_irq)(struct gpio_chip *chip, 282 unsigned offset); 283 284 void (*dbg_show)(struct seq_file *s, 285 struct gpio_chip *chip); 286 287 int (*init_valid_mask)(struct gpio_chip *chip); 288 289 int base; 290 u16 ngpio; 291 const char *const *names; 292 bool can_sleep; 293 294 #if IS_ENABLED(CONFIG_GPIO_GENERIC) 295 unsigned long (*read_reg)(void __iomem *reg); 296 void (*write_reg)(void __iomem *reg, unsigned long data); 297 bool be_bits; 298 void __iomem *reg_dat; 299 void __iomem *reg_set; 300 void __iomem *reg_clr; 301 void __iomem *reg_dir; 302 bool bgpio_dir_inverted; 303 int bgpio_bits; 304 spinlock_t bgpio_lock; 305 unsigned long bgpio_data; 306 unsigned long bgpio_dir; 307 #endif 308 309 #ifdef CONFIG_GPIOLIB_IRQCHIP 310 /* 311 * With CONFIG_GPIOLIB_IRQCHIP we get an irqchip inside the gpiolib 312 * to handle IRQs for most practical cases. 313 */ 314 315 /** 316 * @irq: 317 * 318 * Integrates interrupt chip functionality with the GPIO chip. Can be 319 * used to handle IRQs for most practical cases. 320 */ 321 struct gpio_irq_chip irq; 322 #endif 323 324 /** 325 * @need_valid_mask: 326 * 327 * If set core allocates @valid_mask with all its values initialized 328 * with init_valid_mask() or set to one if init_valid_mask() is not 329 * defined 330 */ 331 bool need_valid_mask; 332 333 /** 334 * @valid_mask: 335 * 336 * If not %NULL holds bitmask of GPIOs which are valid to be used 337 * from the chip. 338 */ 339 unsigned long *valid_mask; 340 341 #if defined(CONFIG_OF_GPIO) 342 /* 343 * If CONFIG_OF is enabled, then all GPIO controllers described in the 344 * device tree automatically may have an OF translation 345 */ 346 347 /** 348 * @of_node: 349 * 350 * Pointer to a device tree node representing this GPIO controller. 351 */ 352 struct device_node *of_node; 353 354 /** 355 * @of_gpio_n_cells: 356 * 357 * Number of cells used to form the GPIO specifier. 358 */ 359 unsigned int of_gpio_n_cells; 360 361 /** 362 * @of_xlate: 363 * 364 * Callback to translate a device tree GPIO specifier into a chip- 365 * relative GPIO number and flags. 366 */ 367 int (*of_xlate)(struct gpio_chip *gc, 368 const struct of_phandle_args *gpiospec, u32 *flags); 369 #endif 370 }; 371 372 extern const char *gpiochip_is_requested(struct gpio_chip *chip, 373 unsigned offset); 374 375 /* add/remove chips */ 376 extern int gpiochip_add_data_with_key(struct gpio_chip *chip, void *data, 377 struct lock_class_key *lock_key, 378 struct lock_class_key *request_key); 379 380 /** 381 * gpiochip_add_data() - register a gpio_chip 382 * @chip: the chip to register, with chip->base initialized 383 * @data: driver-private data associated with this chip 384 * 385 * Context: potentially before irqs will work 386 * 387 * When gpiochip_add_data() is called very early during boot, so that GPIOs 388 * can be freely used, the chip->parent device must be registered before 389 * the gpio framework's arch_initcall(). Otherwise sysfs initialization 390 * for GPIOs will fail rudely. 391 * 392 * gpiochip_add_data() must only be called after gpiolib initialization, 393 * ie after core_initcall(). 394 * 395 * If chip->base is negative, this requests dynamic assignment of 396 * a range of valid GPIOs. 397 * 398 * Returns: 399 * A negative errno if the chip can't be registered, such as because the 400 * chip->base is invalid or already associated with a different chip. 401 * Otherwise it returns zero as a success code. 402 */ 403 #ifdef CONFIG_LOCKDEP 404 #define gpiochip_add_data(chip, data) ({ \ 405 static struct lock_class_key lock_key; \ 406 static struct lock_class_key request_key; \ 407 gpiochip_add_data_with_key(chip, data, &lock_key, \ 408 &request_key); \ 409 }) 410 #else 411 #define gpiochip_add_data(chip, data) gpiochip_add_data_with_key(chip, data, NULL, NULL) 412 #endif 413 414 static inline int gpiochip_add(struct gpio_chip *chip) 415 { 416 return gpiochip_add_data(chip, NULL); 417 } 418 extern void gpiochip_remove(struct gpio_chip *chip); 419 extern int devm_gpiochip_add_data(struct device *dev, struct gpio_chip *chip, 420 void *data); 421 422 extern struct gpio_chip *gpiochip_find(void *data, 423 int (*match)(struct gpio_chip *chip, void *data)); 424 425 /* lock/unlock as IRQ */ 426 int gpiochip_lock_as_irq(struct gpio_chip *chip, unsigned int offset); 427 void gpiochip_unlock_as_irq(struct gpio_chip *chip, unsigned int offset); 428 bool gpiochip_line_is_irq(struct gpio_chip *chip, unsigned int offset); 429 int gpiochip_reqres_irq(struct gpio_chip *chip, unsigned int offset); 430 void gpiochip_relres_irq(struct gpio_chip *chip, unsigned int offset); 431 void gpiochip_disable_irq(struct gpio_chip *chip, unsigned int offset); 432 void gpiochip_enable_irq(struct gpio_chip *chip, unsigned int offset); 433 434 /* Line status inquiry for drivers */ 435 bool gpiochip_line_is_open_drain(struct gpio_chip *chip, unsigned int offset); 436 bool gpiochip_line_is_open_source(struct gpio_chip *chip, unsigned int offset); 437 438 /* Sleep persistence inquiry for drivers */ 439 bool gpiochip_line_is_persistent(struct gpio_chip *chip, unsigned int offset); 440 bool gpiochip_line_is_valid(const struct gpio_chip *chip, unsigned int offset); 441 442 /* get driver data */ 443 void *gpiochip_get_data(struct gpio_chip *chip); 444 445 struct gpio_chip *gpiod_to_chip(const struct gpio_desc *desc); 446 447 struct bgpio_pdata { 448 const char *label; 449 int base; 450 int ngpio; 451 }; 452 453 #if IS_ENABLED(CONFIG_GPIO_GENERIC) 454 455 int bgpio_init(struct gpio_chip *gc, struct device *dev, 456 unsigned long sz, void __iomem *dat, void __iomem *set, 457 void __iomem *clr, void __iomem *dirout, void __iomem *dirin, 458 unsigned long flags); 459 460 #define BGPIOF_BIG_ENDIAN BIT(0) 461 #define BGPIOF_UNREADABLE_REG_SET BIT(1) /* reg_set is unreadable */ 462 #define BGPIOF_UNREADABLE_REG_DIR BIT(2) /* reg_dir is unreadable */ 463 #define BGPIOF_BIG_ENDIAN_BYTE_ORDER BIT(3) 464 #define BGPIOF_READ_OUTPUT_REG_SET BIT(4) /* reg_set stores output value */ 465 #define BGPIOF_NO_OUTPUT BIT(5) /* only input */ 466 467 #endif 468 469 #ifdef CONFIG_GPIOLIB_IRQCHIP 470 471 int gpiochip_irq_map(struct irq_domain *d, unsigned int irq, 472 irq_hw_number_t hwirq); 473 void gpiochip_irq_unmap(struct irq_domain *d, unsigned int irq); 474 475 void gpiochip_set_chained_irqchip(struct gpio_chip *gpiochip, 476 struct irq_chip *irqchip, 477 unsigned int parent_irq, 478 irq_flow_handler_t parent_handler); 479 480 void gpiochip_set_nested_irqchip(struct gpio_chip *gpiochip, 481 struct irq_chip *irqchip, 482 unsigned int parent_irq); 483 484 int gpiochip_irqchip_add_key(struct gpio_chip *gpiochip, 485 struct irq_chip *irqchip, 486 unsigned int first_irq, 487 irq_flow_handler_t handler, 488 unsigned int type, 489 bool threaded, 490 struct lock_class_key *lock_key, 491 struct lock_class_key *request_key); 492 493 bool gpiochip_irqchip_irq_valid(const struct gpio_chip *gpiochip, 494 unsigned int offset); 495 496 #ifdef CONFIG_LOCKDEP 497 498 /* 499 * Lockdep requires that each irqchip instance be created with a 500 * unique key so as to avoid unnecessary warnings. This upfront 501 * boilerplate static inlines provides such a key for each 502 * unique instance. 503 */ 504 static inline int gpiochip_irqchip_add(struct gpio_chip *gpiochip, 505 struct irq_chip *irqchip, 506 unsigned int first_irq, 507 irq_flow_handler_t handler, 508 unsigned int type) 509 { 510 static struct lock_class_key lock_key; 511 static struct lock_class_key request_key; 512 513 return gpiochip_irqchip_add_key(gpiochip, irqchip, first_irq, 514 handler, type, false, 515 &lock_key, &request_key); 516 } 517 518 static inline int gpiochip_irqchip_add_nested(struct gpio_chip *gpiochip, 519 struct irq_chip *irqchip, 520 unsigned int first_irq, 521 irq_flow_handler_t handler, 522 unsigned int type) 523 { 524 525 static struct lock_class_key lock_key; 526 static struct lock_class_key request_key; 527 528 return gpiochip_irqchip_add_key(gpiochip, irqchip, first_irq, 529 handler, type, true, 530 &lock_key, &request_key); 531 } 532 #else 533 static inline int gpiochip_irqchip_add(struct gpio_chip *gpiochip, 534 struct irq_chip *irqchip, 535 unsigned int first_irq, 536 irq_flow_handler_t handler, 537 unsigned int type) 538 { 539 return gpiochip_irqchip_add_key(gpiochip, irqchip, first_irq, 540 handler, type, false, NULL, NULL); 541 } 542 543 static inline int gpiochip_irqchip_add_nested(struct gpio_chip *gpiochip, 544 struct irq_chip *irqchip, 545 unsigned int first_irq, 546 irq_flow_handler_t handler, 547 unsigned int type) 548 { 549 return gpiochip_irqchip_add_key(gpiochip, irqchip, first_irq, 550 handler, type, true, NULL, NULL); 551 } 552 #endif /* CONFIG_LOCKDEP */ 553 554 #endif /* CONFIG_GPIOLIB_IRQCHIP */ 555 556 int gpiochip_generic_request(struct gpio_chip *chip, unsigned offset); 557 void gpiochip_generic_free(struct gpio_chip *chip, unsigned offset); 558 int gpiochip_generic_config(struct gpio_chip *chip, unsigned offset, 559 unsigned long config); 560 561 #ifdef CONFIG_PINCTRL 562 563 /** 564 * struct gpio_pin_range - pin range controlled by a gpio chip 565 * @node: list for maintaining set of pin ranges, used internally 566 * @pctldev: pinctrl device which handles corresponding pins 567 * @range: actual range of pins controlled by a gpio controller 568 */ 569 struct gpio_pin_range { 570 struct list_head node; 571 struct pinctrl_dev *pctldev; 572 struct pinctrl_gpio_range range; 573 }; 574 575 int gpiochip_add_pin_range(struct gpio_chip *chip, const char *pinctl_name, 576 unsigned int gpio_offset, unsigned int pin_offset, 577 unsigned int npins); 578 int gpiochip_add_pingroup_range(struct gpio_chip *chip, 579 struct pinctrl_dev *pctldev, 580 unsigned int gpio_offset, const char *pin_group); 581 void gpiochip_remove_pin_ranges(struct gpio_chip *chip); 582 583 #else 584 585 static inline int 586 gpiochip_add_pin_range(struct gpio_chip *chip, const char *pinctl_name, 587 unsigned int gpio_offset, unsigned int pin_offset, 588 unsigned int npins) 589 { 590 return 0; 591 } 592 static inline int 593 gpiochip_add_pingroup_range(struct gpio_chip *chip, 594 struct pinctrl_dev *pctldev, 595 unsigned int gpio_offset, const char *pin_group) 596 { 597 return 0; 598 } 599 600 static inline void 601 gpiochip_remove_pin_ranges(struct gpio_chip *chip) 602 { 603 } 604 605 #endif /* CONFIG_PINCTRL */ 606 607 struct gpio_desc *gpiochip_request_own_desc(struct gpio_chip *chip, u16 hwnum, 608 const char *label, 609 enum gpiod_flags flags); 610 void gpiochip_free_own_desc(struct gpio_desc *desc); 611 612 #else /* CONFIG_GPIOLIB */ 613 614 static inline struct gpio_chip *gpiod_to_chip(const struct gpio_desc *desc) 615 { 616 /* GPIO can never have been requested */ 617 WARN_ON(1); 618 return ERR_PTR(-ENODEV); 619 } 620 621 #endif /* CONFIG_GPIOLIB */ 622 623 #endif 624