include/asm-generic/gpio.h

   1 /*
   2  * Copyright (c) 2011 The Chromium OS Authors.
   3  * Copyright (c) 2011, NVIDIA Corp. All rights reserved.
   4  * SPDX-License-Identifier:     GPL-2.0+
   5  */
   6
   7 #ifndef _ASM_GENERIC_GPIO_H_
   8 #define _ASM_GENERIC_GPIO_H_
   9
  10 /*
  11  * Generic GPIO API for U-Boot
  12  *
  13  * --
  14  * NB: This is deprecated. Please use the driver model functions instead:
  15  *
  16  *    - gpio_request_by_name()
  17  *    - dm_gpio_get_value() etc.
  18  *
  19  * For now we need a dm_ prefix on some functions to avoid name collision.
  20  * --
  21  *
  22  * GPIOs are numbered from 0 to GPIO_COUNT-1 which value is defined
  23  * by the SOC/architecture.
  24  *
  25  * Each GPIO can be an input or output. If an input then its value can
  26  * be read as 0 or 1. If an output then its value can be set to 0 or 1.
  27  * If you try to write an input then the value is undefined. If you try
  28  * to read an output, barring something very unusual,  you will get
  29  * back the value of the output that you previously set.
  30  *
  31  * In some cases the operation may fail, for example if the GPIO number
  32  * is out of range, or the GPIO is not available because its pin is
  33  * being used by another function. In that case, functions may return
  34  * an error value of -1.
  35  */
  36
  37 enum gpio_flags {
  38         GPIOFLAG_INPUT,
  39         GPIOFLAG_OUTPUT_INIT_LOW,
  40         GPIOFLAG_OUTPUT_INIT_HIGH,
  41 };
  42
  43 struct gpio {
  44         unsigned int gpio;
  45         enum gpio_flags flags;
  46         const char *label;
  47 };
  48
  49 /**
  50  * @deprecated  Please use driver model instead
  51  * Request a GPIO. This should be called before any of the other functions
  52  * are used on this GPIO.
  53  *
  54  * Note: With driver model, the label is allocated so there is no need for
  55  * the caller to preserve it.
  56  *
  57  * @param gp    GPIO number
  58  * @param label User label for this GPIO
  59  * @return 0 if ok, -1 on error
  60  */
  61 int gpio_request(unsigned gpio, const char *label);
  62
  63 /**
  64  * @deprecated  Please use driver model instead
  65  * Stop using the GPIO.  This function should not alter pin configuration.
  66  *
  67  * @param gpio  GPIO number
  68  * @return 0 if ok, -1 on error
  69  */
  70 int gpio_free(unsigned gpio);
  71
  72 /**
  73  * @deprecated  Please use driver model instead
  74  * Make a GPIO an input.
  75  *
  76  * @param gpio  GPIO number
  77  * @return 0 if ok, -1 on error
  78  */
  79 int gpio_direction_input(unsigned gpio);
  80
  81 /**
  82  * @deprecated  Please use driver model instead
  83  * Make a GPIO an output, and set its value.
  84  *
  85  * @param gpio  GPIO number
  86  * @param value GPIO value (0 for low or 1 for high)
  87  * @return 0 if ok, -1 on error
  88  */
  89 int gpio_direction_output(unsigned gpio, int value);
  90
  91 /**
  92  * @deprecated  Please use driver model instead
  93  * Get a GPIO's value. This will work whether the GPIO is an input
  94  * or an output.
  95  *
  96  * @param gpio  GPIO number
  97  * @return 0 if low, 1 if high, -1 on error
  98  */
  99 int gpio_get_value(unsigned gpio);
 100
 101 /**
 102  * @deprecated  Please use driver model instead
 103  * Set an output GPIO's value. The GPIO must already be an output or
 104  * this function may have no effect.
 105  *
 106  * @param gpio  GPIO number
 107  * @param value GPIO value (0 for low or 1 for high)
 108  * @return 0 if ok, -1 on error
 109  */
 110 int gpio_set_value(unsigned gpio, int value);
 111
 112 /* State of a GPIO, as reported by get_function() */
 113 enum gpio_func_t {
 114         GPIOF_INPUT = 0,
 115         GPIOF_OUTPUT,
 116         GPIOF_UNUSED,           /* Not claimed */
 117         GPIOF_UNKNOWN,          /* Not known */
 118         GPIOF_FUNC,             /* Not used as a GPIO */
 119
 120         GPIOF_COUNT,
 121 };
 122
 123 struct udevice;
 124
 125 struct gpio_desc {
 126         struct udevice *dev;    /* Device, NULL for invalid GPIO */
 127         unsigned long flags;
 128 #define GPIOD_REQUESTED         (1 << 0)        /* Requested/claimed */
 129 #define GPIOD_IS_OUT            (1 << 1)        /* GPIO is an output */
 130 #define GPIOD_IS_IN             (1 << 2)        /* GPIO is an output */
 131 #define GPIOD_ACTIVE_LOW        (1 << 3)        /* value has active low */
 132 #define GPIOD_IS_OUT_ACTIVE     (1 << 4)        /* set output active */
 133
 134         uint offset;            /* GPIO offset within the device */
 135         /*
 136          * We could consider adding the GPIO label in here. Possibly we could
 137          * use this structure for internal GPIO information.
 138          */
 139 };
 140
 141 /**
 142  * dm_gpio_is_valid() - Check if a GPIO is gpio_is_valie
 143  *
 144  * @desc:       GPIO description containing device, offset and flags,
 145  *              previously returned by gpio_request_by_name()
 146  * @return true if valid, false if not
 147  */
 148 static inline bool dm_gpio_is_valid(struct gpio_desc *desc)
 149 {
 150         return desc->dev != NULL;
 151 }
 152
 153 /**
 154  * gpio_get_status() - get the current GPIO status as a string
 155  *
 156  * Obtain the current GPIO status as a string which can be presented to the
 157  * user. A typical string is:
 158  *
 159  * "b4:  in: 1 [x] sdmmc_cd"
 160  *
 161  * which means this is GPIO bank b, offset 4, currently set to input, current
 162  * value 1, [x] means that it is requested and the owner is 'sdmmc_cd'
 163  *
 164  * TODO(sjg@chromium.org): This should use struct gpio_desc
 165  *
 166  * @dev:        Device to check
 167  * @offset:     Offset of device GPIO to check
 168  * @buf:        Place to put string
 169  * @buffsize:   Size of string including \0
 170  */
 171 int gpio_get_status(struct udevice *dev, int offset, char *buf, int buffsize);
 172
 173 /**
 174  * gpio_get_function() - get the current function for a GPIO pin
 175  *
 176  * Note this returns GPIOF_UNUSED if the GPIO is not requested.
 177  *
 178  * TODO(sjg@chromium.org): This should use struct gpio_desc
 179  *
 180  * @dev:        Device to check
 181  * @offset:     Offset of device GPIO to check
 182  * @namep:      If non-NULL, this is set to the nane given when the GPIO
 183  *              was requested, or -1 if it has not been requested
 184  * @return  -ENODATA if the driver returned an unknown function,
 185  * -ENODEV if the device is not active, -EINVAL if the offset is invalid.
 186  * GPIOF_UNUSED if the GPIO has not been requested. Otherwise returns the
 187  * function from enum gpio_func_t.
 188  */
 189 int gpio_get_function(struct udevice *dev, int offset, const char **namep);
 190
 191 /**
 192  * gpio_get_raw_function() - get the current raw function for a GPIO pin
 193  *
 194  * Note this does not return GPIOF_UNUSED - it will always return the GPIO
 195  * driver's view of a pin function, even if it is not correctly set up.
 196  *
 197  * TODO(sjg@chromium.org): This should use struct gpio_desc
 198  *
 199  * @dev:        Device to check
 200  * @offset:     Offset of device GPIO to check
 201  * @namep:      If non-NULL, this is set to the nane given when the GPIO
 202  *              was requested, or -1 if it has not been requested
 203  * @return  -ENODATA if the driver returned an unknown function,
 204  * -ENODEV if the device is not active, -EINVAL if the offset is invalid.
 205  * Otherwise returns the function from enum gpio_func_t.
 206  */
 207 int gpio_get_raw_function(struct udevice *dev, int offset, const char **namep);
 208
 209 /**
 210  * gpio_requestf() - request a GPIO using a format string for the owner
 211  *
 212  * This is a helper function for gpio_request(). It allows you to provide
 213  * a printf()-format string for the GPIO owner. It calls gpio_request() with
 214  * the string that is created
 215  */
 216 int gpio_requestf(unsigned gpio, const char *fmt, ...)
 217                 __attribute__ ((format (__printf__, 2, 3)));
 218
 219 struct fdtdec_phandle_args;
 220
 221 /**
 222  * struct struct dm_gpio_ops - Driver model GPIO operations
 223  *
 224  * Refer to functions above for description. These function largely copy
 225  * the old API.
 226  *
 227  * This is trying to be close to Linux GPIO API. Once the U-Boot uses the
 228  * new DM GPIO API, this should be really easy to flip over to the Linux
 229  * GPIO API-alike interface.
 230  *
 231  * Also it would be useful to standardise additional functions like
 232  * pullup, slew rate and drive strength.
 233  *
 234  * gpio_request)( and gpio_free() are optional - if NULL then they will
 235  * not be called.
 236  *
 237  * Note that @offset is the offset from the base GPIO of the device. So
 238  * offset 0 is the device's first GPIO and offset o-1 is the last GPIO,
 239  * where o is the number of GPIO lines controlled by the device. A device
 240  * is typically used to control a single bank of GPIOs. Within complex
 241  * SoCs there may be many banks and therefore many devices all referring
 242  * to the different IO addresses within the SoC.
 243  *
 244  * The uclass combines all GPIO devices together to provide a consistent
 245  * numbering from 0 to n-1, where n is the number of GPIOs in total across
 246  * all devices. Be careful not to confuse offset with gpio in the parameters.
 247  */
 248 struct dm_gpio_ops {
 249         int (*request)(struct udevice *dev, unsigned offset, const char *label);
 250         int (*free)(struct udevice *dev, unsigned offset);
 251         int (*direction_input)(struct udevice *dev, unsigned offset);
 252         int (*direction_output)(struct udevice *dev, unsigned offset,
 253                                 int value);
 254         int (*get_value)(struct udevice *dev, unsigned offset);
 255         int (*set_value)(struct udevice *dev, unsigned offset, int value);
 256         /**
 257          * get_function() Get the GPIO function
 258          *
 259          * @dev:     Device to check
 260          * @offset:  GPIO offset within that device
 261          * @return current function - GPIOF_...
 262          */
 263         int (*get_function)(struct udevice *dev, unsigned offset);
 264
 265         /**
 266          * xlate() - Translate phandle arguments into a GPIO description
 267          *
 268          * This function should set up the fields in desc according to the
 269          * information in the arguments. The uclass will have set up:
 270          *
 271          *   @desc->dev to @dev
 272          *   @desc->flags to 0
 273          *   @desc->offset to the value of the first argument in args, if any,
 274          *              otherwise -1 (which is invalid)
 275          *
 276          * This method is optional so if the above defaults suit it can be
 277          * omitted. Typical behaviour is to set up the GPIOD_ACTIVE_LOW flag
 278          * in desc->flags.
 279          *
 280          * Note that @dev is passed in as a parameter to follow driver model
 281          * uclass conventions, even though it is already available as
 282          * desc->dev.
 283          *
 284          * @dev:        GPIO device
 285          * @desc:       Place to put GPIO description
 286          * @args:       Arguments provided in descripion
 287          * @return 0 if OK, -ve on error
 288          */
 289         int (*xlate)(struct udevice *dev, struct gpio_desc *desc,
 290                      struct fdtdec_phandle_args *args);
 291 };
 292
 293 /**
 294  * struct gpio_dev_priv - information about a device used by the uclass
 295  *
 296  * The uclass combines all active GPIO devices into a unified numbering
 297  * scheme. To do this it maintains some private information about each
 298  * device.
 299  *
 300  * To implement driver model support in your GPIO driver, add a probe
 301  * handler, and set @gpio_count and @bank_name correctly in that handler.
 302  * This tells the uclass the name of the GPIO bank and the number of GPIOs
 303  * it contains.
 304  *
 305  * @bank_name: Name of the GPIO device (e.g 'a' means GPIOs will be called
 306  * 'A0', 'A1', etc.
 307  * @gpio_count: Number of GPIOs in this device
 308  * @gpio_base: Base GPIO number for this device. For the first active device
 309  * this will be 0; the numbering for others will follow sequentially so that
 310  * @gpio_base for device 1 will equal the number of GPIOs in device 0.
 311  * @name: Array of pointers to the name for each GPIO in this bank. The
 312  * value of the pointer will be NULL if the GPIO has not been claimed.
 313  */
 314 struct gpio_dev_priv {
 315         const char *bank_name;
 316         unsigned gpio_count;
 317         unsigned gpio_base;
 318         char **name;
 319 };
 320
 321 /* Access the GPIO operations for a device */
 322 #define gpio_get_ops(dev)       ((struct dm_gpio_ops *)(dev)->driver->ops)
 323
 324 /**
 325  * gpio_get_bank_info - Return information about a GPIO bank/device
 326  *
 327  * This looks up a device and returns both its GPIO base name and the number
 328  * of GPIOs it controls.
 329  *
 330  * @dev: Device to look up
 331  * @offset_count: Returns number of GPIOs within this bank
 332  * @return bank name of this device
 333  */
 334 const char *gpio_get_bank_info(struct udevice *dev, int *offset_count);
 335
 336 /**
 337  * gpio_lookup_name - Look up a GPIO name and return its details
 338  *
 339  * This is used to convert a named GPIO into a device, offset and GPIO
 340  * number.
 341  *
 342  * @name: GPIO name to look up
 343  * @devp: Returns pointer to device which contains this GPIO
 344  * @offsetp: Returns the offset number within this device
 345  * @gpiop: Returns the absolute GPIO number, numbered from 0
 346  */
 347 int gpio_lookup_name(const char *name, struct udevice **devp,
 348                      unsigned int *offsetp, unsigned int *gpiop);
 349
 350 /**
 351  * get_gpios() - Turn the values of a list of GPIOs into an integer
 352  *
 353  * This puts the value of the first GPIO into bit 0, the second into bit 1,
 354  * etc. then returns the resulting integer.
 355  *
 356  * @gpio_list: List of GPIOs to collect
 357  * @return resulting integer value
 358  */
 359 unsigned gpio_get_values_as_int(const int *gpio_list);
 360
 361 /**
 362  * gpio_request_by_name() - Locate and request a GPIO by name
 363  *
 364  * This operates by looking up the given list name in the device (device
 365  * tree property) and requesting the GPIO for use. The property must exist
 366  * in @dev's node.
 367  *
 368  * Use @flags to specify whether the GPIO should be an input or output. In
 369  * principle this can also come from the device tree binding but most
 370  * bindings don't provide this information. Specifically, when the GPIO uclass
 371  * calls the xlate() method, it can return default flags, which are then
 372  * ORed with this @flags.
 373  *
 374  * If we find that requesting the GPIO is not always needed we could add a
 375  * new function or a new GPIOD_NO_REQUEST flag.
 376  *
 377  * At present driver model has no reference counting so if one device
 378  * requests a GPIO which subsequently is unbound, the @desc->dev pointer
 379  * will be invalid. However this will only happen if the GPIO device is
 380  * unbound, not if it is removed, so this seems like a reasonable limitation
 381  * for now. There is no real use case for unbinding drivers in normal
 382  * operation.
 383  *
 384  * The device tree binding is doc/device-tree-bindings/gpio/gpio.txt in
 385  * generate terms and each specific device may add additional details in
 386  * a binding file in the same directory.
 387  *
 388  * @dev:        Device requesting the GPIO
 389  * @list_name:  Name of GPIO list (e.g. "board-id-gpios")
 390  * @index:      Index number of the GPIO in that list use request (0=first)
 391  * @desc:       Returns GPIO description information. If there is no such
 392  *              GPIO, dev->dev will be NULL.
 393  * @flags:      Indicates the GPIO input/output settings (GPIOD_...)
 394  * @return 0 if OK, -ENOENT if the GPIO does not exist, -EINVAL if there is
 395  * something wrong with the list, or other -ve for another error (e.g.
 396  * -EBUSY if a GPIO was already requested)
 397  */
 398 int gpio_request_by_name(struct udevice *dev, const char *list_name,
 399                          int index, struct gpio_desc *desc, int flags);
 400
 401 /**
 402  * gpio_request_list_by_name() - Request a list of GPIOs
 403  *
 404  * Reads all the GPIOs from a list and requetss them. See
 405  * gpio_request_by_name() for additional details. Lists should not be
 406  * misused to hold unrelated or optional GPIOs. They should only be used
 407  * for things like parallel data lines. A zero phandle terminates the list
 408  * the list.
 409  *
 410  * This function will either succeed, and request all GPIOs in the list, or
 411  * fail and request none (it will free already-requested GPIOs in case of
 412  * an error part-way through).
 413  *
 414  * @dev:        Device requesting the GPIO
 415  * @list_name:  Name of GPIO list (e.g. "board-id-gpios")
 416  * @desc_list:  Returns a list of GPIO description information
 417  * @max_count:  Maximum number of GPIOs to return (@desc_list must be at least
 418  *              this big)
 419  * @flags:      Indicates the GPIO input/output settings (GPIOD_...)
 420  * @return number of GPIOs requested, or -ve on error
 421  */
 422 int gpio_request_list_by_name(struct udevice *dev, const char *list_name,
 423                               struct gpio_desc *desc_list, int max_count,
 424                               int flags);
 425
 426 /**
 427  * gpio_get_list_count() - Returns the number of GPIOs in a list
 428  *
 429  * Counts the GPIOs in a list. See gpio_request_by_name() for additional
 430  * details.
 431  *
 432  * @dev:        Device requesting the GPIO
 433  * @list_name:  Name of GPIO list (e.g. "board-id-gpios")
 434  * @return number of GPIOs (0 for an empty property) or -ENOENT if the list
 435  * does not exist
 436  */
 437 int gpio_get_list_count(struct udevice *dev, const char *list_name);
 438
 439 /**
 440  * gpio_request_by_name_nodev() - request GPIOs without a device
 441  *
 442  * This is a version of gpio_request_list_by_name() that does not use a
 443  * device. Avoid it unless the caller is not yet using driver model
 444  */
 445 int gpio_request_by_name_nodev(const void *blob, int node,
 446                                const char *list_name,
 447                                int index, struct gpio_desc *desc, int flags);
 448
 449 /**
 450  * gpio_request_list_by_name_nodev() - request GPIOs without a device
 451  *
 452  * This is a version of gpio_request_list_by_name() that does not use a
 453  * device. Avoid it unless the caller is not yet using driver model
 454  */
 455 int gpio_request_list_by_name_nodev(const void *blob, int node,
 456                                     const char *list_name,
 457                                     struct gpio_desc *desc_list, int max_count,
 458                                     int flags);
 459
 460 /**
 461  * dm_gpio_free() - Free a single GPIO
 462  *
 463  * This frees a single GPIOs previously returned from gpio_request_by_name().
 464  *
 465  * @dev:        Device which requested the GPIO
 466  * @desc:       GPIO to free
 467  * @return 0 if OK, -ve on error
 468  */
 469 int dm_gpio_free(struct udevice *dev, struct gpio_desc *desc);
 470
 471 /**
 472  * gpio_free_list() - Free a list of GPIOs
 473  *
 474  * This frees a list of GPIOs previously returned from
 475  * gpio_request_list_by_name().
 476  *
 477  * @dev:        Device which requested the GPIOs
 478  * @desc:       List of GPIOs to free
 479  * @count:      Number of GPIOs in the list
 480  * @return 0 if OK, -ve on error
 481  */
 482 int gpio_free_list(struct udevice *dev, struct gpio_desc *desc, int count);
 483
 484 /**
 485  * gpio_free_list_nodev() - free GPIOs without a device
 486  *
 487  * This is a version of gpio_free_list() that does not use a
 488  * device. Avoid it unless the caller is not yet using driver model
 489  */
 490 int gpio_free_list_nodev(struct gpio_desc *desc, int count);
 491
 492 /**
 493  * dm_gpio_get_value() - Get the value of a GPIO
 494  *
 495  * This is the driver model version of the existing gpio_get_value() function
 496  * and should be used instead of that.
 497  *
 498  * For now, these functions have a dm_ prefix since they conflict with
 499  * existing names.
 500  *
 501  * @desc:       GPIO description containing device, offset and flags,
 502  *              previously returned by gpio_request_by_name()
 503  * @return GPIO value (0 for inactive, 1 for active) or -ve on error
 504  */
 505 int dm_gpio_get_value(struct gpio_desc *desc);
 506
 507 int dm_gpio_set_value(struct gpio_desc *desc, int value);
 508
 509 /**
 510  * dm_gpio_set_dir() - Set the direction for a GPIO
 511  *
 512  * This sets up the direction according tot the provided flags. It will do
 513  * nothing unless the direction is actually specified.
 514  *
 515  * @desc:       GPIO description containing device, offset and flags,
 516  *              previously returned by gpio_request_by_name()
 517  * @return 0 if OK, -ve on error
 518  */
 519 int dm_gpio_set_dir(struct gpio_desc *desc);
 520
 521 /**
 522  * dm_gpio_set_dir_flags() - Set direction using specific flags
 523  *
 524  * This is like dm_gpio_set_dir() except that the flags value is provided
 525  * instead of being used from desc->flags. This is needed because in many
 526  * cases the GPIO description does not include direction information.
 527  * Note that desc->flags is updated by this function.
 528  *
 529  * @desc:       GPIO description containing device, offset and flags,
 530  *              previously returned by gpio_request_by_name()
 531  * @flags:      New flags to use
 532  * @return 0 if OK, -ve on error, in which case desc->flags is not updated
 533  */
 534 int dm_gpio_set_dir_flags(struct gpio_desc *desc, ulong flags);
 535
 536 /**
 537  * gpio_get_number() - Get the global GPIO number of a GPIO
 538  *
 539  * This should only be used for debugging or interest. It returns the nummber
 540  * that should be used for gpio_get_value() etc. to access this GPIO.
 541  *
 542  * @desc:       GPIO description containing device, offset and flags,
 543  *              previously returned by gpio_request_by_name()
 544  * @return GPIO number, or -ve if not found
 545  */
 546 int gpio_get_number(struct gpio_desc *desc);
 547
 548 /**
 549  * @deprecated  Please use driver model instead
 550  * Request a GPIO and configure it
 551  * @param gpios pointer to array of gpio defs
 552  * @param count number of GPIOs to set up
 553  */
 554 static inline int gpio_request_one(unsigned int gpio, enum gpio_flags flags,
 555                                 const char *label)
 556 {
 557         int ret;
 558
 559         ret = gpio_request(gpio, label);
 560         if (ret)
 561                 return ret;
 562
 563         if (flags == GPIOFLAG_INPUT)
 564                 gpio_direction_input(gpio);
 565         else if (flags == GPIOFLAG_OUTPUT_INIT_LOW)
 566                 gpio_direction_output(gpio, 0);
 567         else if (flags == GPIOFLAG_OUTPUT_INIT_HIGH)
 568                 gpio_direction_output(gpio, 1);
 569
 570         return ret;
 571 }
 572
 573 /**
 574  * Request a set of GPIOs and configure them
 575  * @param gpios pointer to array of gpio defs
 576  * @param count number of GPIOs to set up
 577  */
 578 static inline int gpio_request_array(const struct gpio *gpios, int count)
 579 {
 580         int ret;
 581         int i;
 582
 583         for (i = 0; i < count; i++) {
 584                 ret = gpio_request_one(gpios[i].gpio, gpios[i].flags,
 585                                 gpios[i].label);
 586                 if (ret) {
 587                         printf("Failed to request GPIO%d (%u of %u): %d\n",
 588                                 gpios[i].gpio, i, count, ret);
 589                         goto error;
 590                 }
 591         }
 592         return 0;
 593
 594 error:
 595         while (--i >= 0)
 596                 gpio_free(gpios[i].gpio);
 597
 598         return ret;
 599 }
 600
 601 /**
 602  * @deprecated  Please use driver model instead
 603  * Release a set of GPIOs
 604  * @param gpios pointer to array of gpio defs
 605  * @param count number of GPIOs to set up
 606  */
 607 static inline int gpio_free_array(const struct gpio *gpios, int count)
 608 {
 609         int ret = 0;
 610         int i;
 611
 612         for (i = 0; i < count; i++)
 613                 ret |= gpio_free(gpios[i].gpio);
 614
 615         return ret;
 616 }
 617 #endif  /* _ASM_GENERIC_GPIO_H_ */