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