include/asm-generic/gpio.h

4  * SPDX-License-Identifier:	GPL-2.0+
15  * Generic GPIO API for U-Boot
17  * --
20  *    - gpio_request_by_name()
21  *    - dm_gpio_get_value() etc.
24  * --
26  * GPIOs are numbered from 0 to GPIO_COUNT-1 which value is defined
29  * Each GPIO can be an input or output. If an input then its value can
35  * In some cases the operation may fail, for example if the GPIO number
36  * is out of range, or the GPIO is not available because its pin is
38  * an error value of -1.
43  * Request a GPIO. This should be called before any of the other functions
44  * are used on this GPIO.
49  * @param gpio	GPIO number
50  * @param label	User label for this GPIO
51  * @return 0 if ok, -1 on error
53 int gpio_request(unsigned gpio, const char *label);
57  * Stop using the GPIO.  This function should not alter pin configuration.
59  * @param gpio	GPIO number
60  * @return 0 if ok, -1 on error
62 int gpio_free(unsigned gpio);
66  * Make a GPIO an input.
68  * @param gpio	GPIO number
69  * @return 0 if ok, -1 on error
71 int gpio_direction_input(unsigned gpio);
75  * Make a GPIO an output, and set its value.
77  * @param gpio	GPIO number
78  * @param value	GPIO value (0 for low or 1 for high)
79  * @return 0 if ok, -1 on error
81 int gpio_direction_output(unsigned gpio, int value);
85  * Get a GPIO's value. This will work whether the GPIO is an input
88  * @param gpio	GPIO number
89  * @return 0 if low, 1 if high, -1 on error
91 int gpio_get_value(unsigned gpio);
95  * Set an output GPIO's value. The GPIO must already be an output or
98  * @param gpio	GPIO number
99  * @param value	GPIO value (0 for low or 1 for high)
100  * @return 0 if ok, -1 on error
102 int gpio_set_value(unsigned gpio, int value);
104 /* State of a GPIO, as reported by get_function() */
110 	GPIOF_FUNC,		/* Not used as a GPIO */
118 	struct udevice *dev;	/* Device, NULL for invalid GPIO */
121 #define GPIOD_IS_OUT		(1 << 1)	/* GPIO is an output */
122 #define GPIOD_IS_IN		(1 << 2)	/* GPIO is an input */
126 	uint offset;		/* GPIO offset within the device */
128 	 * We could consider adding the GPIO label in here. Possibly we could
129 	 * use this structure for internal GPIO information.
134  * dm_gpio_is_valid() - Check if a GPIO is valid
136  * @desc:	GPIO description containing device, offset and flags,
142 	return desc->dev != NULL;  in dm_gpio_is_valid()
146  * gpio_get_status() - get the current GPIO status as a string
148  * Obtain the current GPIO status as a string which can be presented to the
153  * which means this is GPIO bank b, offset 4, currently set to input, current
159  * @offset:	Offset of device GPIO to check
166  * gpio_get_function() - get the current function for a GPIO pin
168  * Note this returns GPIOF_UNUSED if the GPIO is not requested.
173  * @offset:	Offset of device GPIO to check
174  * @namep:	If non-NULL, this is set to the name given when the GPIO
175  *		was requested, or -1 if it has not been requested
176  * @return  -ENODATA if the driver returned an unknown function,
177  * -ENODEV if the device is not active, -EINVAL if the offset is invalid.
178  * GPIOF_UNUSED if the GPIO has not been requested. Otherwise returns the
184  * gpio_get_raw_function() - get the current raw function for a GPIO pin
186  * Note this does not return GPIOF_UNUSED - it will always return the GPIO
192  * @offset:	Offset of device GPIO to check
193  * @namep:	If non-NULL, this is set to the name given when the GPIO
194  *		was requested, or -1 if it has not been requested
195  * @return  -ENODATA if the driver returned an unknown function,
196  * -ENODEV if the device is not active, -EINVAL if the offset is invalid.
202  * gpio_requestf() - request a GPIO using a format string for the owner
205  * a printf()-format string for the GPIO owner. It calls gpio_request() with
208 int gpio_requestf(unsigned gpio, const char *fmt, ...)
214  * gpio_xlate_offs_flags() - implementation for common use of dm_gpio_ops.xlate
223  * struct struct dm_gpio_ops - Driver model GPIO operations
228  * This is trying to be close to Linux GPIO API. Once the U-Boot uses the
229  * new DM GPIO API, this should be really easy to flip over to the Linux
230  * GPIO API-alike interface.
235  * gpio_request() and gpio_free() are optional - if NULL then they will
238  * Note that @offset is the offset from the base GPIO of the device. So
239  * offset 0 is the device's first GPIO and offset o-1 is the last GPIO,
240  * where o is the number of GPIO lines controlled by the device. A device
245  * The uclass combines all GPIO devices together to provide a consistent
246  * numbering from 0 to n-1, where n is the number of GPIOs in total across
247  * all devices. Be careful not to confuse offset with gpio in the parameters.
260 	 * get_function() Get the GPIO function
263 	 * @offset:  GPIO offset within that device
264 	 * @return current function - GPIOF_...
269 	 * xlate() - Translate phandle arguments into a GPIO description
274 	 *   @desc->dev to @dev
275 	 *   @desc->flags to 0
276 	 *   @desc->offset to 0
284 	 * desc->dev.
286 	 * @dev:	GPIO device
287 	 * @desc:	Place to put GPIO description
289 	 * @return 0 if OK, -ve on error
296  * struct gpio_dev_priv - information about a device used by the uclass
298  * The uclass combines all active GPIO devices into a unified numbering
302  * To implement driver model support in your GPIO driver, add a probe
304  * This tells the uclass the name of the GPIO bank and the number of GPIOs
307  * @bank_name: Name of the GPIO device (e.g 'a' means GPIOs will be called
310  * @gpio_base: Base GPIO number for this device. For the first active device
313  * @name: Array of pointers to the name for each GPIO in this bank. The
314  * value of the pointer will be NULL if the GPIO has not been claimed.
323 /* Access the GPIO operations for a device */
324 #define gpio_get_ops(dev)	((struct dm_gpio_ops *)(dev)->driver->ops)
327  * gpio_get_bank_info - Return information about a GPIO bank/device
329  * This looks up a device and returns both its GPIO base name and the number
339  * dm_gpio_lookup_name() - Look up a named GPIO and return its description
341  * The name of a GPIO is typically its bank name followed by a number from 0.
342  * For example A0 is the first GPIO in bank A. Each bank is a separate driver
347  * @return 0 if OK, -ve on error
352  * gpio_hog_lookup_name() - Look up a named GPIO and return the gpio descr.
355  * @desc:	Returns GPIO description, on success, else NULL
356  * @return:	Returns 0 if OK, else -ENODEV
361  * gpio_hog_probe_all() - probe all gpio devices with
362  * gpio-hog subnodes.
369  * gpio_lookup_name - Look up a GPIO name and return its details
371  * This is used to convert a named GPIO into a device, offset and GPIO
374  * @name: GPIO name to look up
375  * @devp: Returns pointer to device which contains this GPIO
377  * @gpiop: Returns the absolute GPIO number, numbered from 0
383  * gpio_get_values_as_int() - Turn the values of a list of GPIOs into an int
385  * This puts the value of the first GPIO into bit 0, the second into bit 1,
389  * @return resulting integer value, or -ve on error
394  * dm_gpio_get_values_as_int() - Turn the values of a list of GPIOs into an int
396  * This puts the value of the first GPIO into bit 0, the second into bit 1,
401  * @return resulting integer value, or -ve on error
406  * gpio_claim_vector() - claim a number of GPIOs for input
408  * @gpio_num_array:	array of gpios to claim, terminated by -1
409  * @fmt:		format string for GPIO names, e.g. "board_id%d"
410  * @return 0 if OK, -ve on error
415  * gpio_request_by_name() - Locate and request a GPIO by name
418  * tree property) and requesting the GPIO for use. The property must exist
421  * Use @flags to specify whether the GPIO should be an input or output. In
423  * bindings don't provide this information. Specifically, when the GPIO uclass
427  * If we find that requesting the GPIO is not always needed we could add a
431  * requests a GPIO which subsequently is unbound, the @desc->dev pointer
432  * will be invalid. However this will only happen if the GPIO device is
437  * The device tree binding is doc/device-tree-bindings/gpio/gpio.txt in
441  * @dev:	Device requesting the GPIO
442  * @list_name:	Name of GPIO list (e.g. "board-id-gpios")
443  * @index:	Index number of the GPIO in that list use request (0=first)
444  * @desc:	Returns GPIO description information. If there is no such
445  *		GPIO, dev->dev will be NULL.
446  * @flags:	Indicates the GPIO input/output settings (GPIOD_...)
447  * @return 0 if OK, -ENOENT if the GPIO does not exist, -EINVAL if there is
448  * something wrong with the list, or other -ve for another error (e.g.
449  * -EBUSY if a GPIO was already requested)
455  * gpio_request_list_by_name() - Request a list of GPIOs
464  * fail and request none (it will free already-requested GPIOs in case of
465  * an error part-way through).
467  * @dev:	Device requesting the GPIO
468  * @list_name:	Name of GPIO list (e.g. "board-id-gpios")
469  * @desc_list:	Returns a list of GPIO description information
472  * @flags:	Indicates the GPIO input/output settings (GPIOD_...)
473  * @return number of GPIOs requested, or -ve on error
480  * dm_gpio_request() - manually request a GPIO
485  * @desc:	GPIO description of GPIO to request (see dm_gpio_lookup_name())
486  * @label:	Label to attach to the GPIO while claimed
487  * @return 0 if OK, -ve on error
492  * gpio_get_list_count() - Returns the number of GPIOs in a list
497  * @dev:	Device requesting the GPIO
498  * @list_name:	Name of GPIO list (e.g. "board-id-gpios")
499  * @return number of GPIOs (0 for an empty property) or -ENOENT if the list
505  * gpio_request_by_name_nodev() - request GPIOs without a device
514  * gpio_request_list_by_name_nodev() - request GPIOs without a device
524  * gpio_dev_request_index() - request single GPIO from gpio device
526  * @dev:	GPIO device
527  * @nodename:	Name of node for which gpio gets requested, used
528  *		for the gpio label name
529  * @list_name:	Name of GPIO list (e.g. "board-id-gpios")
530  * @index:	Index number of the GPIO in that list use request (0=first)
532  * @dtflags:	GPIO flags read from DT defined see GPIOD_*
533  * @desc:	returns GPIO descriptor filled from this function
541  * dm_gpio_free() - Free a single GPIO
545  * @dev:	Device which requested the GPIO
546  * @desc:	GPIO to free
547  * @return 0 if OK, -ve on error
552  * gpio_free_list() - Free a list of GPIOs
560  * @return 0 if OK, -ve on error
565  * gpio_free_list_nodev() - free GPIOs without a device
573  * dm_gpio_get_value() - Get the value of a GPIO
581  * @desc:	GPIO description containing device, offset and flags,
583  * @return GPIO value (0 for inactive, 1 for active) or -ve on error
590  * dm_gpio_get_open_drain() - Check if open-drain-mode of a GPIO is active
592  * This checks if open-drain-mode for a GPIO is enabled or not. This method is
595  * @desc:	GPIO description containing device, offset and flags,
597  * @return Value of open drain mode for GPIO (0 for inactive, 1 for active) or
598  *	   -ve on error
603  * dm_gpio_set_open_drain() - Switch open-drain-mode of a GPIO on or off
605  * This enables or disables open-drain mode for a GPIO. This method is
609  * In open-drain mode, instead of actively driving the output (Push-pull
610  * output), the GPIO's pin is connected to the collector (for a NPN transistor)
611  * or the drain (for a MOSFET) of a transistor, respectively. The pin then
612  * either forms an open circuit or a connection to ground, depending on the
615  * @desc:	GPIO description containing device, offset and flags,
617  * @return 0 if OK, -ve on error
622  * dm_gpio_set_dir() - Set the direction for a GPIO
627  * @desc:	GPIO description containing device, offset and flags,
629  * @return 0 if OK, -ve on error
634  * dm_gpio_set_dir_flags() - Set direction using specific flags
637  * instead of being used from desc->flags. This is needed because in many
638  * cases the GPIO description does not include direction information.
639  * Note that desc->flags is updated by this function.
641  * @desc:	GPIO description containing device, offset and flags,
644  * @return 0 if OK, -ve on error, in which case desc->flags is not updated
649  * gpio_get_number() - Get the global GPIO number of a GPIO
652  * that should be used for gpio_get_value() etc. to access this GPIO.
654  * @desc:	GPIO description containing device, offset and flags,
656  * @return GPIO number, or -ve if not found