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