include/linux/gpio/consumer.h

   1 /* SPDX-License-Identifier: GPL-2.0 */
   2 #ifndef __LINUX_GPIO_CONSUMER_H
   3 #define __LINUX_GPIO_CONSUMER_H
   4
   5 #include <linux/bug.h>
   6 #include <linux/err.h>
   7 #include <linux/kernel.h>
   8
   9 struct device;
  10
  11 /**
  12  * Opaque descriptor for a GPIO. These are obtained using gpiod_get() and are
  13  * preferable to the old integer-based handles.
  14  *
  15  * Contrary to integers, a pointer to a gpio_desc is guaranteed to be valid
  16  * until the GPIO is released.
  17  */
  18 struct gpio_desc;
  19
  20 /**
  21  * Opaque descriptor for a structure of GPIO array attributes.  This structure
  22  * is attached to struct gpiod_descs obtained from gpiod_get_array() and can be
  23  * passed back to get/set array functions in order to activate fast processing
  24  * path if applicable.
  25  */
  26 struct gpio_array;
  27
  28 /**
  29  * Struct containing an array of descriptors that can be obtained using
  30  * gpiod_get_array().
  31  */
  32 struct gpio_descs {
  33         struct gpio_array *info;
  34         unsigned int ndescs;
  35         struct gpio_desc *desc[];
  36 };
  37
  38 #define GPIOD_FLAGS_BIT_DIR_SET         BIT(0)
  39 #define GPIOD_FLAGS_BIT_DIR_OUT         BIT(1)
  40 #define GPIOD_FLAGS_BIT_DIR_VAL         BIT(2)
  41 #define GPIOD_FLAGS_BIT_OPEN_DRAIN      BIT(3)
  42 #define GPIOD_FLAGS_BIT_NONEXCLUSIVE    BIT(4)
  43
  44 /**
  45  * Optional flags that can be passed to one of gpiod_* to configure direction
  46  * and output value. These values cannot be OR'd.
  47  */
  48 enum gpiod_flags {
  49         GPIOD_ASIS      = 0,
  50         GPIOD_IN        = GPIOD_FLAGS_BIT_DIR_SET,
  51         GPIOD_OUT_LOW   = GPIOD_FLAGS_BIT_DIR_SET | GPIOD_FLAGS_BIT_DIR_OUT,
  52         GPIOD_OUT_HIGH  = GPIOD_FLAGS_BIT_DIR_SET | GPIOD_FLAGS_BIT_DIR_OUT |
  53                           GPIOD_FLAGS_BIT_DIR_VAL,
  54         GPIOD_OUT_LOW_OPEN_DRAIN = GPIOD_OUT_LOW | GPIOD_FLAGS_BIT_OPEN_DRAIN,
  55         GPIOD_OUT_HIGH_OPEN_DRAIN = GPIOD_OUT_HIGH | GPIOD_FLAGS_BIT_OPEN_DRAIN,
  56 };
  57
  58 #ifdef CONFIG_GPIOLIB
  59
  60 /* Return the number of GPIOs associated with a device / function */
  61 int gpiod_count(struct device *dev, const char *con_id);
  62
  63 /* Acquire and dispose GPIOs */
  64 struct gpio_desc *__must_check gpiod_get(struct device *dev,
  65                                          const char *con_id,
  66                                          enum gpiod_flags flags);
  67 struct gpio_desc *__must_check gpiod_get_index(struct device *dev,
  68                                                const char *con_id,
  69                                                unsigned int idx,
  70                                                enum gpiod_flags flags);
  71 struct gpio_desc *__must_check gpiod_get_optional(struct device *dev,
  72                                                   const char *con_id,
  73                                                   enum gpiod_flags flags);
  74 struct gpio_desc *__must_check gpiod_get_index_optional(struct device *dev,
  75                                                         const char *con_id,
  76                                                         unsigned int index,
  77                                                         enum gpiod_flags flags);
  78 struct gpio_descs *__must_check gpiod_get_array(struct device *dev,
  79                                                 const char *con_id,
  80                                                 enum gpiod_flags flags);
  81 struct gpio_descs *__must_check gpiod_get_array_optional(struct device *dev,
  82                                                         const char *con_id,
  83                                                         enum gpiod_flags flags);
  84 void gpiod_put(struct gpio_desc *desc);
  85 void gpiod_put_array(struct gpio_descs *descs);
  86
  87 struct gpio_desc *__must_check devm_gpiod_get(struct device *dev,
  88                                               const char *con_id,
  89                                               enum gpiod_flags flags);
  90 struct gpio_desc *__must_check devm_gpiod_get_index(struct device *dev,
  91                                                     const char *con_id,
  92                                                     unsigned int idx,
  93                                                     enum gpiod_flags flags);
  94 struct gpio_desc *__must_check devm_gpiod_get_optional(struct device *dev,
  95                                                        const char *con_id,
  96                                                        enum gpiod_flags flags);
  97 struct gpio_desc *__must_check
  98 devm_gpiod_get_index_optional(struct device *dev, const char *con_id,
  99                               unsigned int index, enum gpiod_flags flags);
 100 struct gpio_descs *__must_check devm_gpiod_get_array(struct device *dev,
 101                                                      const char *con_id,
 102                                                      enum gpiod_flags flags);
 103 struct gpio_descs *__must_check
 104 devm_gpiod_get_array_optional(struct device *dev, const char *con_id,
 105                               enum gpiod_flags flags);
 106 void devm_gpiod_put(struct device *dev, struct gpio_desc *desc);
 107 void devm_gpiod_unhinge(struct device *dev, struct gpio_desc *desc);
 108 void devm_gpiod_put_array(struct device *dev, struct gpio_descs *descs);
 109
 110 int gpiod_get_direction(struct gpio_desc *desc);
 111 int gpiod_direction_input(struct gpio_desc *desc);
 112 int gpiod_direction_output(struct gpio_desc *desc, int value);
 113 int gpiod_direction_output_raw(struct gpio_desc *desc, int value);
 114
 115 /* Value get/set from non-sleeping context */
 116 int gpiod_get_value(const struct gpio_desc *desc);
 117 int gpiod_get_array_value(unsigned int array_size,
 118                           struct gpio_desc **desc_array,
 119                           struct gpio_array *array_info,
 120                           unsigned long *value_bitmap);
 121 void gpiod_set_value(struct gpio_desc *desc, int value);
 122 int gpiod_set_array_value(unsigned int array_size,
 123                           struct gpio_desc **desc_array,
 124                           struct gpio_array *array_info,
 125                           unsigned long *value_bitmap);
 126 int gpiod_get_raw_value(const struct gpio_desc *desc);
 127 int gpiod_get_raw_array_value(unsigned int array_size,
 128                               struct gpio_desc **desc_array,
 129                               struct gpio_array *array_info,
 130                               unsigned long *value_bitmap);
 131 void gpiod_set_raw_value(struct gpio_desc *desc, int value);
 132 int gpiod_set_raw_array_value(unsigned int array_size,
 133                               struct gpio_desc **desc_array,
 134                               struct gpio_array *array_info,
 135                               unsigned long *value_bitmap);
 136
 137 /* Value get/set from sleeping context */
 138 int gpiod_get_value_cansleep(const struct gpio_desc *desc);
 139 int gpiod_get_array_value_cansleep(unsigned int array_size,
 140                                    struct gpio_desc **desc_array,
 141                                    struct gpio_array *array_info,
 142                                    unsigned long *value_bitmap);
 143 void gpiod_set_value_cansleep(struct gpio_desc *desc, int value);
 144 int gpiod_set_array_value_cansleep(unsigned int array_size,
 145                                    struct gpio_desc **desc_array,
 146                                    struct gpio_array *array_info,
 147                                    unsigned long *value_bitmap);
 148 int gpiod_get_raw_value_cansleep(const struct gpio_desc *desc);
 149 int gpiod_get_raw_array_value_cansleep(unsigned int array_size,
 150                                        struct gpio_desc **desc_array,
 151                                        struct gpio_array *array_info,
 152                                        unsigned long *value_bitmap);
 153 void gpiod_set_raw_value_cansleep(struct gpio_desc *desc, int value);
 154 int gpiod_set_raw_array_value_cansleep(unsigned int array_size,
 155                                        struct gpio_desc **desc_array,
 156                                        struct gpio_array *array_info,
 157                                        unsigned long *value_bitmap);
 158
 159 int gpiod_set_debounce(struct gpio_desc *desc, unsigned debounce);
 160 int gpiod_set_transitory(struct gpio_desc *desc, bool transitory);
 161
 162 int gpiod_is_active_low(const struct gpio_desc *desc);
 163 int gpiod_cansleep(const struct gpio_desc *desc);
 164
 165 int gpiod_to_irq(const struct gpio_desc *desc);
 166 int gpiod_set_consumer_name(struct gpio_desc *desc, const char *name);
 167
 168 /* Convert between the old gpio_ and new gpiod_ interfaces */
 169 struct gpio_desc *gpio_to_desc(unsigned gpio);
 170 int desc_to_gpio(const struct gpio_desc *desc);
 171
 172 /* Child properties interface */
 173 struct device_node;
 174 struct fwnode_handle;
 175
 176 struct gpio_desc *gpiod_get_from_of_node(struct device_node *node,
 177                                          const char *propname, int index,
 178                                          enum gpiod_flags dflags,
 179                                          const char *label);
 180 struct gpio_desc *devm_gpiod_get_from_of_node(struct device *dev,
 181                                               struct device_node *node,
 182                                               const char *propname, int index,
 183                                               enum gpiod_flags dflags,
 184                                               const char *label);
 185 struct gpio_desc *fwnode_get_named_gpiod(struct fwnode_handle *fwnode,
 186                                          const char *propname, int index,
 187                                          enum gpiod_flags dflags,
 188                                          const char *label);
 189 struct gpio_desc *devm_fwnode_get_index_gpiod_from_child(struct device *dev,
 190                                                 const char *con_id, int index,
 191                                                 struct fwnode_handle *child,
 192                                                 enum gpiod_flags flags,
 193                                                 const char *label);
 194
 195 #else /* CONFIG_GPIOLIB */
 196
 197 static inline int gpiod_count(struct device *dev, const char *con_id)
 198 {
 199         return 0;
 200 }
 201
 202 static inline struct gpio_desc *__must_check gpiod_get(struct device *dev,
 203                                                        const char *con_id,
 204                                                        enum gpiod_flags flags)
 205 {
 206         return ERR_PTR(-ENOSYS);
 207 }
 208 static inline struct gpio_desc *__must_check
 209 gpiod_get_index(struct device *dev,
 210                 const char *con_id,
 211                 unsigned int idx,
 212                 enum gpiod_flags flags)
 213 {
 214         return ERR_PTR(-ENOSYS);
 215 }
 216
 217 static inline struct gpio_desc *__must_check
 218 gpiod_get_optional(struct device *dev, const char *con_id,
 219                    enum gpiod_flags flags)
 220 {
 221         return NULL;
 222 }
 223
 224 static inline struct gpio_desc *__must_check
 225 gpiod_get_index_optional(struct device *dev, const char *con_id,
 226                          unsigned int index, enum gpiod_flags flags)
 227 {
 228         return NULL;
 229 }
 230
 231 static inline struct gpio_descs *__must_check
 232 gpiod_get_array(struct device *dev, const char *con_id,
 233                 enum gpiod_flags flags)
 234 {
 235         return ERR_PTR(-ENOSYS);
 236 }
 237
 238 static inline struct gpio_descs *__must_check
 239 gpiod_get_array_optional(struct device *dev, const char *con_id,
 240                          enum gpiod_flags flags)
 241 {
 242         return NULL;
 243 }
 244
 245 static inline void gpiod_put(struct gpio_desc *desc)
 246 {
 247         might_sleep();
 248
 249         /* GPIO can never have been requested */
 250         WARN_ON(desc);
 251 }
 252
 253 static inline void devm_gpiod_unhinge(struct device *dev,
 254                                       struct gpio_desc *desc)
 255 {
 256         might_sleep();
 257
 258         /* GPIO can never have been requested */
 259         WARN_ON(desc);
 260 }
 261
 262 static inline void gpiod_put_array(struct gpio_descs *descs)
 263 {
 264         might_sleep();
 265
 266         /* GPIO can never have been requested */
 267         WARN_ON(descs);
 268 }
 269
 270 static inline struct gpio_desc *__must_check
 271 devm_gpiod_get(struct device *dev,
 272                  const char *con_id,
 273                  enum gpiod_flags flags)
 274 {
 275         return ERR_PTR(-ENOSYS);
 276 }
 277 static inline
 278 struct gpio_desc *__must_check
 279 devm_gpiod_get_index(struct device *dev,
 280                        const char *con_id,
 281                        unsigned int idx,
 282                        enum gpiod_flags flags)
 283 {
 284         return ERR_PTR(-ENOSYS);
 285 }
 286
 287 static inline struct gpio_desc *__must_check
 288 devm_gpiod_get_optional(struct device *dev, const char *con_id,
 289                           enum gpiod_flags flags)
 290 {
 291         return NULL;
 292 }
 293
 294 static inline struct gpio_desc *__must_check
 295 devm_gpiod_get_index_optional(struct device *dev, const char *con_id,
 296                                 unsigned int index, enum gpiod_flags flags)
 297 {
 298         return NULL;
 299 }
 300
 301 static inline struct gpio_descs *__must_check
 302 devm_gpiod_get_array(struct device *dev, const char *con_id,
 303                      enum gpiod_flags flags)
 304 {
 305         return ERR_PTR(-ENOSYS);
 306 }
 307
 308 static inline struct gpio_descs *__must_check
 309 devm_gpiod_get_array_optional(struct device *dev, const char *con_id,
 310                               enum gpiod_flags flags)
 311 {
 312         return NULL;
 313 }
 314
 315 static inline void devm_gpiod_put(struct device *dev, struct gpio_desc *desc)
 316 {
 317         might_sleep();
 318
 319         /* GPIO can never have been requested */
 320         WARN_ON(desc);
 321 }
 322
 323 static inline void devm_gpiod_put_array(struct device *dev,
 324                                         struct gpio_descs *descs)
 325 {
 326         might_sleep();
 327
 328         /* GPIO can never have been requested */
 329         WARN_ON(descs);
 330 }
 331
 332
 333 static inline int gpiod_get_direction(const struct gpio_desc *desc)
 334 {
 335         /* GPIO can never have been requested */
 336         WARN_ON(desc);
 337         return -ENOSYS;
 338 }
 339 static inline int gpiod_direction_input(struct gpio_desc *desc)
 340 {
 341         /* GPIO can never have been requested */
 342         WARN_ON(desc);
 343         return -ENOSYS;
 344 }
 345 static inline int gpiod_direction_output(struct gpio_desc *desc, int value)
 346 {
 347         /* GPIO can never have been requested */
 348         WARN_ON(desc);
 349         return -ENOSYS;
 350 }
 351 static inline int gpiod_direction_output_raw(struct gpio_desc *desc, int value)
 352 {
 353         /* GPIO can never have been requested */
 354         WARN_ON(desc);
 355         return -ENOSYS;
 356 }
 357
 358
 359 static inline int gpiod_get_value(const struct gpio_desc *desc)
 360 {
 361         /* GPIO can never have been requested */
 362         WARN_ON(desc);
 363         return 0;
 364 }
 365 static inline int gpiod_get_array_value(unsigned int array_size,
 366                                         struct gpio_desc **desc_array,
 367                                         struct gpio_array *array_info,
 368                                         unsigned long *value_bitmap)
 369 {
 370         /* GPIO can never have been requested */
 371         WARN_ON(desc_array);
 372         return 0;
 373 }
 374 static inline void gpiod_set_value(struct gpio_desc *desc, int value)
 375 {
 376         /* GPIO can never have been requested */
 377         WARN_ON(desc);
 378 }
 379 static inline int gpiod_set_array_value(unsigned int array_size,
 380                                         struct gpio_desc **desc_array,
 381                                         struct gpio_array *array_info,
 382                                         unsigned long *value_bitmap)
 383 {
 384         /* GPIO can never have been requested */
 385         WARN_ON(desc_array);
 386         return 0;
 387 }
 388 static inline int gpiod_get_raw_value(const struct gpio_desc *desc)
 389 {
 390         /* GPIO can never have been requested */
 391         WARN_ON(desc);
 392         return 0;
 393 }
 394 static inline int gpiod_get_raw_array_value(unsigned int array_size,
 395                                             struct gpio_desc **desc_array,
 396                                             struct gpio_array *array_info,
 397                                             unsigned long *value_bitmap)
 398 {
 399         /* GPIO can never have been requested */
 400         WARN_ON(desc_array);
 401         return 0;
 402 }
 403 static inline void gpiod_set_raw_value(struct gpio_desc *desc, int value)
 404 {
 405         /* GPIO can never have been requested */
 406         WARN_ON(desc);
 407 }
 408 static inline int gpiod_set_raw_array_value(unsigned int array_size,
 409                                             struct gpio_desc **desc_array,
 410                                             struct gpio_array *array_info,
 411                                             unsigned long *value_bitmap)
 412 {
 413         /* GPIO can never have been requested */
 414         WARN_ON(desc_array);
 415         return 0;
 416 }
 417
 418 static inline int gpiod_get_value_cansleep(const struct gpio_desc *desc)
 419 {
 420         /* GPIO can never have been requested */
 421         WARN_ON(desc);
 422         return 0;
 423 }
 424 static inline int gpiod_get_array_value_cansleep(unsigned int array_size,
 425                                      struct gpio_desc **desc_array,
 426                                      struct gpio_array *array_info,
 427                                      unsigned long *value_bitmap)
 428 {
 429         /* GPIO can never have been requested */
 430         WARN_ON(desc_array);
 431         return 0;
 432 }
 433 static inline void gpiod_set_value_cansleep(struct gpio_desc *desc, int value)
 434 {
 435         /* GPIO can never have been requested */
 436         WARN_ON(desc);
 437 }
 438 static inline int gpiod_set_array_value_cansleep(unsigned int array_size,
 439                                             struct gpio_desc **desc_array,
 440                                             struct gpio_array *array_info,
 441                                             unsigned long *value_bitmap)
 442 {
 443         /* GPIO can never have been requested */
 444         WARN_ON(desc_array);
 445         return 0;
 446 }
 447 static inline int gpiod_get_raw_value_cansleep(const struct gpio_desc *desc)
 448 {
 449         /* GPIO can never have been requested */
 450         WARN_ON(desc);
 451         return 0;
 452 }
 453 static inline int gpiod_get_raw_array_value_cansleep(unsigned int array_size,
 454                                                struct gpio_desc **desc_array,
 455                                                struct gpio_array *array_info,
 456                                                unsigned long *value_bitmap)
 457 {
 458         /* GPIO can never have been requested */
 459         WARN_ON(desc_array);
 460         return 0;
 461 }
 462 static inline void gpiod_set_raw_value_cansleep(struct gpio_desc *desc,
 463                                                 int value)
 464 {
 465         /* GPIO can never have been requested */
 466         WARN_ON(desc);
 467 }
 468 static inline int gpiod_set_raw_array_value_cansleep(unsigned int array_size,
 469                                                 struct gpio_desc **desc_array,
 470                                                 struct gpio_array *array_info,
 471                                                 unsigned long *value_bitmap)
 472 {
 473         /* GPIO can never have been requested */
 474         WARN_ON(desc_array);
 475         return 0;
 476 }
 477
 478 static inline int gpiod_set_debounce(struct gpio_desc *desc, unsigned debounce)
 479 {
 480         /* GPIO can never have been requested */
 481         WARN_ON(desc);
 482         return -ENOSYS;
 483 }
 484
 485 static inline int gpiod_set_transitory(struct gpio_desc *desc, bool transitory)
 486 {
 487         /* GPIO can never have been requested */
 488         WARN_ON(desc);
 489         return -ENOSYS;
 490 }
 491
 492 static inline int gpiod_is_active_low(const struct gpio_desc *desc)
 493 {
 494         /* GPIO can never have been requested */
 495         WARN_ON(desc);
 496         return 0;
 497 }
 498 static inline int gpiod_cansleep(const struct gpio_desc *desc)
 499 {
 500         /* GPIO can never have been requested */
 501         WARN_ON(desc);
 502         return 0;
 503 }
 504
 505 static inline int gpiod_to_irq(const struct gpio_desc *desc)
 506 {
 507         /* GPIO can never have been requested */
 508         WARN_ON(desc);
 509         return -EINVAL;
 510 }
 511
 512 static inline int gpiod_set_consumer_name(struct gpio_desc *desc,
 513                                           const char *name)
 514 {
 515         /* GPIO can never have been requested */
 516         WARN_ON(desc);
 517         return -EINVAL;
 518 }
 519
 520 static inline struct gpio_desc *gpio_to_desc(unsigned gpio)
 521 {
 522         return NULL;
 523 }
 524
 525 static inline int desc_to_gpio(const struct gpio_desc *desc)
 526 {
 527         /* GPIO can never have been requested */
 528         WARN_ON(desc);
 529         return -EINVAL;
 530 }
 531
 532 /* Child properties interface */
 533 struct device_node;
 534 struct fwnode_handle;
 535
 536 static inline
 537 struct gpio_desc *gpiod_get_from_of_node(struct device_node *node,
 538                                          const char *propname, int index,
 539                                          enum gpiod_flags dflags,
 540                                          const char *label)
 541 {
 542         return ERR_PTR(-ENOSYS);
 543 }
 544
 545 static inline
 546 struct gpio_desc *devm_gpiod_get_from_of_node(struct device *dev,
 547                                               struct device_node *node,
 548                                               const char *propname, int index,
 549                                               enum gpiod_flags dflags,
 550                                               const char *label)
 551 {
 552         return ERR_PTR(-ENOSYS);
 553 }
 554
 555 static inline
 556 struct gpio_desc *fwnode_get_named_gpiod(struct fwnode_handle *fwnode,
 557                                          const char *propname, int index,
 558                                          enum gpiod_flags dflags,
 559                                          const char *label)
 560 {
 561         return ERR_PTR(-ENOSYS);
 562 }
 563
 564 static inline
 565 struct gpio_desc *devm_fwnode_get_index_gpiod_from_child(struct device *dev,
 566                                                 const char *con_id, int index,
 567                                                 struct fwnode_handle *child,
 568                                                 enum gpiod_flags flags,
 569                                                 const char *label)
 570 {
 571         return ERR_PTR(-ENOSYS);
 572 }
 573
 574 #endif /* CONFIG_GPIOLIB */
 575
 576 static inline
 577 struct gpio_desc *devm_fwnode_get_gpiod_from_child(struct device *dev,
 578                                                    const char *con_id,
 579                                                    struct fwnode_handle *child,
 580                                                    enum gpiod_flags flags,
 581                                                    const char *label)
 582 {
 583         return devm_fwnode_get_index_gpiod_from_child(dev, con_id, 0, child,
 584                                                       flags, label);
 585 }
 586
 587 #if IS_ENABLED(CONFIG_GPIOLIB) && IS_ENABLED(CONFIG_GPIO_SYSFS)
 588
 589 int gpiod_export(struct gpio_desc *desc, bool direction_may_change);
 590 int gpiod_export_link(struct device *dev, const char *name,
 591                       struct gpio_desc *desc);
 592 void gpiod_unexport(struct gpio_desc *desc);
 593
 594 #else  /* CONFIG_GPIOLIB && CONFIG_GPIO_SYSFS */
 595
 596 static inline int gpiod_export(struct gpio_desc *desc,
 597                                bool direction_may_change)
 598 {
 599         return -ENOSYS;
 600 }
 601
 602 static inline int gpiod_export_link(struct device *dev, const char *name,
 603                                     struct gpio_desc *desc)
 604 {
 605         return -ENOSYS;
 606 }
 607
 608 static inline void gpiod_unexport(struct gpio_desc *desc)
 609 {
 610 }
 611
 612 #endif /* CONFIG_GPIOLIB && CONFIG_GPIO_SYSFS */
 613
 614 #endif