LXR linux/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
   9struct 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 */
  18struct 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 */
  26struct gpio_array;
  27
  28/**
  29 * Struct containing an array of descriptors that can be obtained using
  30 * gpiod_get_array().
  31 */
  32struct 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 */
  48enum 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 */
  61int gpiod_count(struct device *dev, const char *con_id);
  62
  63/* Acquire and dispose GPIOs */
  64struct gpio_desc *__must_check gpiod_get(struct device *dev,
  65                                         const char *con_id,
  66                                         enum gpiod_flags flags);
  67struct gpio_desc *__must_check gpiod_get_index(struct device *dev,
  68                                               const char *con_id,
  69                                               unsigned int idx,
  70                                               enum gpiod_flags flags);
  71struct gpio_desc *__must_check gpiod_get_optional(struct device *dev,
  72                                                  const char *con_id,
  73                                                  enum gpiod_flags flags);
  74struct 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);
  78struct gpio_descs *__must_check gpiod_get_array(struct device *dev,
  79                                                const char *con_id,
  80                                                enum gpiod_flags flags);
  81struct gpio_descs *__must_check gpiod_get_array_optional(struct device *dev,
  82                                                        const char *con_id,
  83                                                        enum gpiod_flags flags);
  84void gpiod_put(struct gpio_desc *desc);
  85void gpiod_put_array(struct gpio_descs *descs);
  86
  87struct gpio_desc *__must_check devm_gpiod_get(struct device *dev,
  88                                              const char *con_id,
  89                                              enum gpiod_flags flags);
  90struct 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);
  94struct gpio_desc *__must_check devm_gpiod_get_optional(struct device *dev,
  95                                                       const char *con_id,
  96                                                       enum gpiod_flags flags);
  97struct gpio_desc *__must_check
  98devm_gpiod_get_index_optional(struct device *dev, const char *con_id,
  99                              unsigned int index, enum gpiod_flags flags);
 100struct gpio_descs *__must_check devm_gpiod_get_array(struct device *dev,
 101                                                     const char *con_id,
 102                                                     enum gpiod_flags flags);
 103struct gpio_descs *__must_check
 104devm_gpiod_get_array_optional(struct device *dev, const char *con_id,
 105                              enum gpiod_flags flags);
 106void devm_gpiod_put(struct device *dev, struct gpio_desc *desc);
 107void devm_gpiod_unhinge(struct device *dev, struct gpio_desc *desc);
 108void devm_gpiod_put_array(struct device *dev, struct gpio_descs *descs);
 109
 110int gpiod_get_direction(struct gpio_desc *desc);
 111int gpiod_direction_input(struct gpio_desc *desc);
 112int gpiod_direction_output(struct gpio_desc *desc, int value);
 113int gpiod_direction_output_raw(struct gpio_desc *desc, int value);
 114
 115/* Value get/set from non-sleeping context */
 116int gpiod_get_value(const struct gpio_desc *desc);
 117int 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);
 121void gpiod_set_value(struct gpio_desc *desc, int value);
 122int 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);
 126int gpiod_get_raw_value(const struct gpio_desc *desc);
 127int 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);
 131void gpiod_set_raw_value(struct gpio_desc *desc, int value);
 132int 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 */
 138int gpiod_get_value_cansleep(const struct gpio_desc *desc);
 139int 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);
 143void gpiod_set_value_cansleep(struct gpio_desc *desc, int value);
 144int 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);
 148int gpiod_get_raw_value_cansleep(const struct gpio_desc *desc);
 149int 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);
 153void gpiod_set_raw_value_cansleep(struct gpio_desc *desc, int value);
 154int 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
 159int gpiod_set_debounce(struct gpio_desc *desc, unsigned debounce);
 160int gpiod_set_transitory(struct gpio_desc *desc, bool transitory);
 161
 162int gpiod_is_active_low(const struct gpio_desc *desc);
 163int gpiod_cansleep(const struct gpio_desc *desc);
 164
 165int gpiod_to_irq(const struct gpio_desc *desc);
 166int gpiod_set_consumer_name(struct gpio_desc *desc, const char *name);
 167
 168/* Convert between the old gpio_ and new gpiod_ interfaces */
 169struct gpio_desc *gpio_to_desc(unsigned gpio);
 170int desc_to_gpio(const struct gpio_desc *desc);
 171
 172/* Child properties interface */
 173struct device_node;
 174struct fwnode_handle;
 175
 176struct 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);
 180struct 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);
 185struct 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);
 189struct 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
 197static inline int gpiod_count(struct device *dev, const char *con_id)
 198{
 199        return 0;
 200}
 201
 202static 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}
 208static inline struct gpio_desc *__must_check
 209gpiod_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
 217static inline struct gpio_desc *__must_check
 218gpiod_get_optional(struct device *dev, const char *con_id,
 219                   enum gpiod_flags flags)
 220{
 221        return NULL;
 222}
 223
 224static inline struct gpio_desc *__must_check
 225gpiod_get_index_optional(struct device *dev, const char *con_id,
 226                         unsigned int index, enum gpiod_flags flags)
 227{
 228        return NULL;
 229}
 230
 231static inline struct gpio_descs *__must_check
 232gpiod_get_array(struct device *dev, const char *con_id,
 233                enum gpiod_flags flags)
 234{
 235        return ERR_PTR(-ENOSYS);
 236}
 237
 238static inline struct gpio_descs *__must_check
 239gpiod_get_array_optional(struct device *dev, const char *con_id,
 240                         enum gpiod_flags flags)
 241{
 242        return NULL;
 243}
 244
 245static 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
 253static 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
 262static 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
 270static inline struct gpio_desc *__must_check
 271devm_gpiod_get(struct device *dev,
 272                 const char *con_id,
 273                 enum gpiod_flags flags)
 274{
 275        return ERR_PTR(-ENOSYS);
 276}
 277static inline
 278struct gpio_desc *__must_check
 279devm_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
 287static inline struct gpio_desc *__must_check
 288devm_gpiod_get_optional(struct device *dev, const char *con_id,
 289                          enum gpiod_flags flags)
 290{
 291        return NULL;
 292}
 293
 294static inline struct gpio_desc *__must_check
 295devm_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
 301static inline struct gpio_descs *__must_check
 302devm_gpiod_get_array(struct device *dev, const char *con_id,
 303                     enum gpiod_flags flags)
 304{
 305        return ERR_PTR(-ENOSYS);
 306}
 307
 308static inline struct gpio_descs *__must_check
 309devm_gpiod_get_array_optional(struct device *dev, const char *con_id,
 310                              enum gpiod_flags flags)
 311{
 312        return NULL;
 313}
 314
 315static 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
 323static 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
 333static 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}
 339static 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}
 345static 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}
 351static 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
 359static 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}
 365static 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}
 374static inline void gpiod_set_value(struct gpio_desc *desc, int value)
 375{
 376        /* GPIO can never have been requested */
 377        WARN_ON(desc);
 378}
 379static 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}
 388static 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}
 394static 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}
 403static 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}
 408static 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
 418static 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}
 424static 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}
 433static 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}
 438static 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}
 447static 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}
 453static 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}
 462static 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}
 468static 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
 478static 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
 485static 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
 492static 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}
 498static 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
 505static 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
 512static 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
 520static inline struct gpio_desc *gpio_to_desc(unsigned gpio)
 521{
 522        return NULL;
 523}
 524
 525static 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 */
 533struct device_node;
 534struct fwnode_handle;
 535
 536static inline
 537struct 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
 545static inline
 546struct 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
 555static inline
 556struct 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
 564static inline
 565struct 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
 576static inline
 577struct 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
 589int gpiod_export(struct gpio_desc *desc, bool direction_may_change);
 590int gpiod_export_link(struct device *dev, const char *name,
 591                      struct gpio_desc *desc);
 592void gpiod_unexport(struct gpio_desc *desc);
 593
 594#else  /* CONFIG_GPIOLIB && CONFIG_GPIO_SYSFS */
 595
 596static inline int gpiod_export(struct gpio_desc *desc,
 597                               bool direction_may_change)
 598{
 599        return -ENOSYS;
 600}
 601
 602static inline int gpiod_export_link(struct device *dev, const char *name,
 603                                    struct gpio_desc *desc)
 604{
 605        return -ENOSYS;
 606}
 607
 608static inline void gpiod_unexport(struct gpio_desc *desc)
 609{
 610}
 611
 612#endif /* CONFIG_GPIOLIB && CONFIG_GPIO_SYSFS */
 613
 614#endif
 615