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  * Struct containing an array of descriptors that can be obtained using
  22  * gpiod_get_array().
  23  */
  24 struct gpio_descs {
  25         unsigned int ndescs;
  26         struct gpio_desc *desc[];
  27 };
  28
  29 #define GPIOD_FLAGS_BIT_DIR_SET         BIT(0)
  30 #define GPIOD_FLAGS_BIT_DIR_OUT         BIT(1)
  31 #define GPIOD_FLAGS_BIT_DIR_VAL         BIT(2)
  32
  33 /**
  34  * Optional flags that can be passed to one of gpiod_* to configure direction
  35  * and output value. These values cannot be OR'd.
  36  */
  37 enum gpiod_flags {
  38         GPIOD_ASIS      = 0,
  39         GPIOD_IN        = GPIOD_FLAGS_BIT_DIR_SET,
  40         GPIOD_OUT_LOW   = GPIOD_FLAGS_BIT_DIR_SET | GPIOD_FLAGS_BIT_DIR_OUT,
  41         GPIOD_OUT_HIGH  = GPIOD_FLAGS_BIT_DIR_SET | GPIOD_FLAGS_BIT_DIR_OUT |
  42                           GPIOD_FLAGS_BIT_DIR_VAL,
  43 };
  44
  45 #ifdef CONFIG_GPIOLIB
  46
  47 /* Return the number of GPIOs associated with a device / function */
  48 int gpiod_count(struct device *dev, const char *con_id);
  49
  50 /* Acquire and dispose GPIOs */
  51 struct gpio_desc *__must_check gpiod_get(struct device *dev,
  52                                          const char *con_id,
  53                                          enum gpiod_flags flags);
  54 struct gpio_desc *__must_check gpiod_get_index(struct device *dev,
  55                                                const char *con_id,
  56                                                unsigned int idx,
  57                                                enum gpiod_flags flags);
  58 struct gpio_desc *__must_check gpiod_get_optional(struct device *dev,
  59                                                   const char *con_id,
  60                                                   enum gpiod_flags flags);
  61 struct gpio_desc *__must_check gpiod_get_index_optional(struct device *dev,
  62                                                         const char *con_id,
  63                                                         unsigned int index,
  64                                                         enum gpiod_flags flags);
  65 struct gpio_descs *__must_check gpiod_get_array(struct device *dev,
  66                                                 const char *con_id,
  67                                                 enum gpiod_flags flags);
  68 struct gpio_descs *__must_check gpiod_get_array_optional(struct device *dev,
  69                                                         const char *con_id,
  70                                                         enum gpiod_flags flags);
  71 void gpiod_put(struct gpio_desc *desc);
  72 void gpiod_put_array(struct gpio_descs *descs);
  73
  74 struct gpio_desc *__must_check devm_gpiod_get(struct device *dev,
  75                                               const char *con_id,
  76                                               enum gpiod_flags flags);
  77 struct gpio_desc *__must_check devm_gpiod_get_index(struct device *dev,
  78                                                     const char *con_id,
  79                                                     unsigned int idx,
  80                                                     enum gpiod_flags flags);
  81 struct gpio_desc *__must_check devm_gpiod_get_optional(struct device *dev,
  82                                                        const char *con_id,
  83                                                        enum gpiod_flags flags);
  84 struct gpio_desc *__must_check
  85 devm_gpiod_get_index_optional(struct device *dev, const char *con_id,
  86                               unsigned int index, enum gpiod_flags flags);
  87 struct gpio_descs *__must_check devm_gpiod_get_array(struct device *dev,
  88                                                      const char *con_id,
  89                                                      enum gpiod_flags flags);
  90 struct gpio_descs *__must_check
  91 devm_gpiod_get_array_optional(struct device *dev, const char *con_id,
  92                               enum gpiod_flags flags);
  93 void devm_gpiod_put(struct device *dev, struct gpio_desc *desc);
  94 void devm_gpiod_put_array(struct device *dev, struct gpio_descs *descs);
  95
  96 int gpiod_get_direction(struct gpio_desc *desc);
  97 int gpiod_direction_input(struct gpio_desc *desc);
  98 int gpiod_direction_output(struct gpio_desc *desc, int value);
  99 int gpiod_direction_output_raw(struct gpio_desc *desc, int value);
 100
 101 /* Value get/set from non-sleeping context */
 102 int gpiod_get_value(const struct gpio_desc *desc);
 103 void gpiod_set_value(struct gpio_desc *desc, int value);
 104 void gpiod_set_array_value(unsigned int array_size,
 105                            struct gpio_desc **desc_array, int *value_array);
 106 int gpiod_get_raw_value(const struct gpio_desc *desc);
 107 void gpiod_set_raw_value(struct gpio_desc *desc, int value);
 108 void gpiod_set_raw_array_value(unsigned int array_size,
 109                                struct gpio_desc **desc_array,
 110                                int *value_array);
 111
 112 /* Value get/set from sleeping context */
 113 int gpiod_get_value_cansleep(const struct gpio_desc *desc);
 114 void gpiod_set_value_cansleep(struct gpio_desc *desc, int value);
 115 void gpiod_set_array_value_cansleep(unsigned int array_size,
 116                                     struct gpio_desc **desc_array,
 117                                     int *value_array);
 118 int gpiod_get_raw_value_cansleep(const struct gpio_desc *desc);
 119 void gpiod_set_raw_value_cansleep(struct gpio_desc *desc, int value);
 120 void gpiod_set_raw_array_value_cansleep(unsigned int array_size,
 121                                         struct gpio_desc **desc_array,
 122                                         int *value_array);
 123
 124 int gpiod_set_debounce(struct gpio_desc *desc, unsigned debounce);
 125
 126 int gpiod_is_active_low(const struct gpio_desc *desc);
 127 int gpiod_cansleep(const struct gpio_desc *desc);
 128
 129 int gpiod_to_irq(const struct gpio_desc *desc);
 130
 131 /* Convert between the old gpio_ and new gpiod_ interfaces */
 132 struct gpio_desc *gpio_to_desc(unsigned gpio);
 133 int desc_to_gpio(const struct gpio_desc *desc);
 134
 135 /* Child properties interface */
 136 struct fwnode_handle;
 137
 138 struct gpio_desc *fwnode_get_named_gpiod(struct fwnode_handle *fwnode,
 139                                          const char *propname, int index,
 140                                          enum gpiod_flags dflags,
 141                                          const char *label);
 142 struct gpio_desc *devm_fwnode_get_index_gpiod_from_child(struct device *dev,
 143                                                 const char *con_id, int index,
 144                                                 struct fwnode_handle *child,
 145                                                 enum gpiod_flags flags,
 146                                                 const char *label);
 147
 148 #else /* CONFIG_GPIOLIB */
 149
 150 static inline int gpiod_count(struct device *dev, const char *con_id)
 151 {
 152         return 0;
 153 }
 154
 155 static inline struct gpio_desc *__must_check gpiod_get(struct device *dev,
 156                                                        const char *con_id,
 157                                                        enum gpiod_flags flags)
 158 {
 159         return ERR_PTR(-ENOSYS);
 160 }
 161 static inline struct gpio_desc *__must_check
 162 gpiod_get_index(struct device *dev,
 163                 const char *con_id,
 164                 unsigned int idx,
 165                 enum gpiod_flags flags)
 166 {
 167         return ERR_PTR(-ENOSYS);
 168 }
 169
 170 static inline struct gpio_desc *__must_check
 171 gpiod_get_optional(struct device *dev, const char *con_id,
 172                    enum gpiod_flags flags)
 173 {
 174         return NULL;
 175 }
 176
 177 static inline struct gpio_desc *__must_check
 178 gpiod_get_index_optional(struct device *dev, const char *con_id,
 179                          unsigned int index, enum gpiod_flags flags)
 180 {
 181         return NULL;
 182 }
 183
 184 static inline struct gpio_descs *__must_check
 185 gpiod_get_array(struct device *dev, const char *con_id,
 186                 enum gpiod_flags flags)
 187 {
 188         return ERR_PTR(-ENOSYS);
 189 }
 190
 191 static inline struct gpio_descs *__must_check
 192 gpiod_get_array_optional(struct device *dev, const char *con_id,
 193                          enum gpiod_flags flags)
 194 {
 195         return NULL;
 196 }
 197
 198 static inline void gpiod_put(struct gpio_desc *desc)
 199 {
 200         might_sleep();
 201
 202         /* GPIO can never have been requested */
 203         WARN_ON(1);
 204 }
 205
 206 static inline void gpiod_put_array(struct gpio_descs *descs)
 207 {
 208         might_sleep();
 209
 210         /* GPIO can never have been requested */
 211         WARN_ON(1);
 212 }
 213
 214 static inline struct gpio_desc *__must_check
 215 devm_gpiod_get(struct device *dev,
 216                  const char *con_id,
 217                  enum gpiod_flags flags)
 218 {
 219         return ERR_PTR(-ENOSYS);
 220 }
 221 static inline
 222 struct gpio_desc *__must_check
 223 devm_gpiod_get_index(struct device *dev,
 224                        const char *con_id,
 225                        unsigned int idx,
 226                        enum gpiod_flags flags)
 227 {
 228         return ERR_PTR(-ENOSYS);
 229 }
 230
 231 static inline struct gpio_desc *__must_check
 232 devm_gpiod_get_optional(struct device *dev, const char *con_id,
 233                           enum gpiod_flags flags)
 234 {
 235         return NULL;
 236 }
 237
 238 static inline struct gpio_desc *__must_check
 239 devm_gpiod_get_index_optional(struct device *dev, const char *con_id,
 240                                 unsigned int index, enum gpiod_flags flags)
 241 {
 242         return NULL;
 243 }
 244
 245 static inline struct gpio_descs *__must_check
 246 devm_gpiod_get_array(struct device *dev, const char *con_id,
 247                      enum gpiod_flags flags)
 248 {
 249         return ERR_PTR(-ENOSYS);
 250 }
 251
 252 static inline struct gpio_descs *__must_check
 253 devm_gpiod_get_array_optional(struct device *dev, const char *con_id,
 254                               enum gpiod_flags flags)
 255 {
 256         return NULL;
 257 }
 258
 259 static inline void devm_gpiod_put(struct device *dev, struct gpio_desc *desc)
 260 {
 261         might_sleep();
 262
 263         /* GPIO can never have been requested */
 264         WARN_ON(1);
 265 }
 266
 267 static inline void devm_gpiod_put_array(struct device *dev,
 268                                         struct gpio_descs *descs)
 269 {
 270         might_sleep();
 271
 272         /* GPIO can never have been requested */
 273         WARN_ON(1);
 274 }
 275
 276
 277 static inline int gpiod_get_direction(const struct gpio_desc *desc)
 278 {
 279         /* GPIO can never have been requested */
 280         WARN_ON(1);
 281         return -ENOSYS;
 282 }
 283 static inline int gpiod_direction_input(struct gpio_desc *desc)
 284 {
 285         /* GPIO can never have been requested */
 286         WARN_ON(1);
 287         return -ENOSYS;
 288 }
 289 static inline int gpiod_direction_output(struct gpio_desc *desc, int value)
 290 {
 291         /* GPIO can never have been requested */
 292         WARN_ON(1);
 293         return -ENOSYS;
 294 }
 295 static inline int gpiod_direction_output_raw(struct gpio_desc *desc, int value)
 296 {
 297         /* GPIO can never have been requested */
 298         WARN_ON(1);
 299         return -ENOSYS;
 300 }
 301
 302
 303 static inline int gpiod_get_value(const struct gpio_desc *desc)
 304 {
 305         /* GPIO can never have been requested */
 306         WARN_ON(1);
 307         return 0;
 308 }
 309 static inline void gpiod_set_value(struct gpio_desc *desc, int value)
 310 {
 311         /* GPIO can never have been requested */
 312         WARN_ON(1);
 313 }
 314 static inline void gpiod_set_array_value(unsigned int array_size,
 315                                          struct gpio_desc **desc_array,
 316                                          int *value_array)
 317 {
 318         /* GPIO can never have been requested */
 319         WARN_ON(1);
 320 }
 321 static inline int gpiod_get_raw_value(const struct gpio_desc *desc)
 322 {
 323         /* GPIO can never have been requested */
 324         WARN_ON(1);
 325         return 0;
 326 }
 327 static inline void gpiod_set_raw_value(struct gpio_desc *desc, int value)
 328 {
 329         /* GPIO can never have been requested */
 330         WARN_ON(1);
 331 }
 332 static inline void gpiod_set_raw_array_value(unsigned int array_size,
 333                                              struct gpio_desc **desc_array,
 334                                              int *value_array)
 335 {
 336         /* GPIO can never have been requested */
 337         WARN_ON(1);
 338 }
 339
 340 static inline int gpiod_get_value_cansleep(const struct gpio_desc *desc)
 341 {
 342         /* GPIO can never have been requested */
 343         WARN_ON(1);
 344         return 0;
 345 }
 346 static inline void gpiod_set_value_cansleep(struct gpio_desc *desc, int value)
 347 {
 348         /* GPIO can never have been requested */
 349         WARN_ON(1);
 350 }
 351 static inline void gpiod_set_array_value_cansleep(unsigned int array_size,
 352                                             struct gpio_desc **desc_array,
 353                                             int *value_array)
 354 {
 355         /* GPIO can never have been requested */
 356         WARN_ON(1);
 357 }
 358 static inline int gpiod_get_raw_value_cansleep(const struct gpio_desc *desc)
 359 {
 360         /* GPIO can never have been requested */
 361         WARN_ON(1);
 362         return 0;
 363 }
 364 static inline void gpiod_set_raw_value_cansleep(struct gpio_desc *desc,
 365                                                 int value)
 366 {
 367         /* GPIO can never have been requested */
 368         WARN_ON(1);
 369 }
 370 static inline void gpiod_set_raw_array_value_cansleep(unsigned int array_size,
 371                                                 struct gpio_desc **desc_array,
 372                                                 int *value_array)
 373 {
 374         /* GPIO can never have been requested */
 375         WARN_ON(1);
 376 }
 377
 378 static inline int gpiod_set_debounce(struct gpio_desc *desc, unsigned debounce)
 379 {
 380         /* GPIO can never have been requested */
 381         WARN_ON(1);
 382         return -ENOSYS;
 383 }
 384
 385 static inline int gpiod_is_active_low(const struct gpio_desc *desc)
 386 {
 387         /* GPIO can never have been requested */
 388         WARN_ON(1);
 389         return 0;
 390 }
 391 static inline int gpiod_cansleep(const struct gpio_desc *desc)
 392 {
 393         /* GPIO can never have been requested */
 394         WARN_ON(1);
 395         return 0;
 396 }
 397
 398 static inline int gpiod_to_irq(const struct gpio_desc *desc)
 399 {
 400         /* GPIO can never have been requested */
 401         WARN_ON(1);
 402         return -EINVAL;
 403 }
 404
 405 static inline struct gpio_desc *gpio_to_desc(unsigned gpio)
 406 {
 407         return ERR_PTR(-EINVAL);
 408 }
 409
 410 static inline int desc_to_gpio(const struct gpio_desc *desc)
 411 {
 412         /* GPIO can never have been requested */
 413         WARN_ON(1);
 414         return -EINVAL;
 415 }
 416
 417 /* Child properties interface */
 418 struct fwnode_handle;
 419
 420 static inline
 421 struct gpio_desc *fwnode_get_named_gpiod(struct fwnode_handle *fwnode,
 422                                          const char *propname, int index,
 423                                          enum gpiod_flags dflags,
 424                                          const char *label)
 425 {
 426         return ERR_PTR(-ENOSYS);
 427 }
 428
 429 static inline
 430 struct gpio_desc *devm_fwnode_get_index_gpiod_from_child(struct device *dev,
 431                                                 const char *con_id, int index,
 432                                                 struct fwnode_handle *child,
 433                                                 enum gpiod_flags flags,
 434                                                 const char *label)
 435 {
 436         return ERR_PTR(-ENOSYS);
 437 }
 438
 439 #endif /* CONFIG_GPIOLIB */
 440
 441 static inline
 442 struct gpio_desc *devm_fwnode_get_gpiod_from_child(struct device *dev,
 443                                                    const char *con_id,
 444                                                    struct fwnode_handle *child,
 445                                                    enum gpiod_flags flags,
 446                                                    const char *label)
 447 {
 448         return devm_fwnode_get_index_gpiod_from_child(dev, con_id, 0, child,
 449                                                       flags, label);
 450 }
 451
 452 #if IS_ENABLED(CONFIG_GPIOLIB) && IS_ENABLED(CONFIG_GPIO_SYSFS)
 453
 454 int gpiod_export(struct gpio_desc *desc, bool direction_may_change);
 455 int gpiod_export_link(struct device *dev, const char *name,
 456                       struct gpio_desc *desc);
 457 void gpiod_unexport(struct gpio_desc *desc);
 458
 459 #else  /* CONFIG_GPIOLIB && CONFIG_GPIO_SYSFS */
 460
 461 static inline int gpiod_export(struct gpio_desc *desc,
 462                                bool direction_may_change)
 463 {
 464         return -ENOSYS;
 465 }
 466
 467 static inline int gpiod_export_link(struct device *dev, const char *name,
 468                                     struct gpio_desc *desc)
 469 {
 470         return -ENOSYS;
 471 }
 472
 473 static inline void gpiod_unexport(struct gpio_desc *desc)
 474 {
 475 }
 476
 477 #endif /* CONFIG_GPIOLIB && CONFIG_GPIO_SYSFS */
 478
 479 #endif