gpiolib: Update the kernel documentation - add Return sections (94bd9ce1) · Commits · git / linux-net

drivers/gpio/gpiolib-acpi.c

+17 −5

Original line number	Diff line number	Diff line
		@@ -153,8 +153,12 @@ static int acpi_gpiochip_find(struct gpio_chip gc, const void data)
		* @path: ACPI GPIO controller full path name, (e.g. "\\_SB.GPO1")
		* @pin: ACPI GPIO pin number (0-based, controller-relative)
		*
		* Return: GPIO descriptor to use with Linux generic GPIO API, or ERR_PTR
		* error value. Specifically returns %-EPROBE_DEFER if the referenced GPIO
		* Returns:
		* GPIO descriptor to use with Linux generic GPIO API.
		* If the GPIO cannot be translated or there is an error an ERR_PTR is
		* returned.
		*
		* Specifically returns %-EPROBE_DEFER if the referenced GPIO
		* controller does not have GPIO chip registered at the moment. This is to
		* support probe deferral.
		*/
		@@ -224,6 +228,9 @@ EXPORT_SYMBOL_GPL(acpi_gpio_get_irq_resource);
		* I/O resource or return False if not.
		* @ares: Pointer to the ACPI resource to fetch
		* @agpio: Pointer to a &struct acpi_resource_gpio to store the output pointer
		*
		* Returns:
		* %true if GpioIo resource is found, %false otherwise.
		*/
		bool acpi_gpio_get_io_resource(struct acpi_resource *ares,
		struct acpi_resource_gpio **agpio)
		@@ -876,7 +883,9 @@ static int acpi_gpio_property_lookup(struct fwnode_handle *fwnode,
		* that case @index is used to select the GPIO entry in the property value
		* (in case of multiple).
		*
		* If the GPIO cannot be translated or there is an error, an ERR_PTR is
		* Returns:
		* GPIO descriptor to use with Linux generic GPIO API.
		* If the GPIO cannot be translated or there is an error an ERR_PTR is
		* returned.
		*
		* Note: if the GPIO resource has multiple entries in the pin list, this
		@@ -924,6 +933,8 @@ static struct gpio_desc acpi_get_gpiod_by_index(struct acpi_device adev,
		* resource with the relevant information from a data-only ACPI firmware node
		* and uses that to obtain the GPIO descriptor to return.
		*
		* Returns:
		* GPIO descriptor to use with Linux generic GPIO API.
		* If the GPIO cannot be translated or there is an error an ERR_PTR is
		* returned.
		*/
		@@ -1042,7 +1053,8 @@ struct gpio_desc acpi_find_gpio(struct fwnode_handle fwnode,
		* The GPIO is considered wake capable if the GpioInt resource specifies
		* SharedAndWake or ExclusiveAndWake.
		*
		* Return: Linux IRQ number (> %0) on success, negative errno on failure.
		* Returns:
		* Linux IRQ number (> 0) on success, negative errno on failure.
		*/
		int acpi_dev_gpio_irq_wake_get_by(struct acpi_device adev, const char con_id, int index,
		bool *wake_capable)
		@@ -1429,7 +1441,7 @@ static int acpi_find_gpio_count(struct acpi_resource ares, void data)
		* @fwnode: firmware node of the GPIO consumer
		* @con_id: function within the GPIO consumer
		*
		* Return:
		* Returns:
		* The number of GPIOs associated with a firmware node / function or %-ENOENT,
		* if no GPIO has been assigned to the requested function.
		*/

drivers/gpio/gpiolib-cdev.c

+6 −2

Original line number	Diff line number	Diff line
		@@ -2748,7 +2748,9 @@ static ssize_t lineinfo_watch_read(struct file file, char __user buf,
		* gpio_chrdev_open() - open the chardev for ioctl operations
		* @inode: inode for this chardev
		* @file: file struct for storing private data
		* Returns 0 on success
		*
		* Returns:
		* 0 on success, or negative errno on failure.
		*/
		static int gpio_chrdev_open(struct inode inode, struct file file)
		{
		@@ -2814,7 +2816,9 @@ static int gpio_chrdev_open(struct inode inode, struct file file)
		* gpio_chrdev_release() - close chardev after ioctl operations
		* @inode: inode for this chardev
		* @file: file struct for storing private data
		* Returns 0 on success
		*
		* Returns:
		* 0 on success, or negative errno on failure.
		*/
		static int gpio_chrdev_release(struct inode inode, struct file file)
		{

drivers/gpio/gpiolib-devres.c

+36 −2

Original line number	Diff line number	Diff line
		@@ -52,6 +52,11 @@ static int devm_gpiod_match_array(struct device dev, void res, void *data)
		* Managed gpiod_get(). GPIO descriptors returned from this function are
		* automatically disposed on driver detach. See gpiod_get() for detailed
		* information about behavior and return values.
		*
		* Returns:
		* The GPIO descriptor corresponding to the function @con_id of device
		* dev, %-ENOENT if no GPIO has been assigned to the requested function, or
		* another IS_ERR() code if an error occurred while trying to acquire the GPIO.
		*/
		struct gpio_desc __must_check devm_gpiod_get(struct device dev,
		const char *con_id,
		@@ -70,6 +75,11 @@ EXPORT_SYMBOL_GPL(devm_gpiod_get);
		* Managed gpiod_get_optional(). GPIO descriptors returned from this function
		* are automatically disposed on driver detach. See gpiod_get_optional() for
		* detailed information about behavior and return values.
		*
		* Returns:
		* The GPIO descriptor corresponding to the function @con_id of device
		* dev, NULL if no GPIO has been assigned to the requested function, or
		* another IS_ERR() code if an error occurred while trying to acquire the GPIO.
		*/
		struct gpio_desc __must_check devm_gpiod_get_optional(struct device dev,
		const char *con_id,
		@@ -89,6 +99,11 @@ EXPORT_SYMBOL_GPL(devm_gpiod_get_optional);
		* Managed gpiod_get_index(). GPIO descriptors returned from this function are
		* automatically disposed on driver detach. See gpiod_get_index() for detailed
		* information about behavior and return values.
		*
		* Returns:
		* The GPIO descriptor corresponding to the function @con_id of device
		* dev, %-ENOENT if no GPIO has been assigned to the requested function, or
		* another IS_ERR() code if an error occurred while trying to acquire the GPIO.
		*/
		struct gpio_desc __must_check devm_gpiod_get_index(struct device dev,
		const char *con_id,
		@@ -141,8 +156,10 @@ EXPORT_SYMBOL_GPL(devm_gpiod_get_index);
		* GPIO descriptors returned from this function are automatically disposed on
		* driver detach.
		*
		* On successful request the GPIO pin is configured in accordance with
		* provided @flags.
		* Returns:
		* The GPIO descriptor corresponding to the function @con_id of device
		* dev, %-ENOENT if no GPIO has been assigned to the requested function, or
		* another IS_ERR() code if an error occurred while trying to acquire the GPIO.
		*/
		struct gpio_desc devm_fwnode_gpiod_get_index(struct device dev,
		struct fwnode_handle *fwnode,
		@@ -182,6 +199,11 @@ EXPORT_SYMBOL_GPL(devm_fwnode_gpiod_get_index);
		* function are automatically disposed on driver detach. See
		* gpiod_get_index_optional() for detailed information about behavior and
		* return values.
		*
		* Returns:
		* The GPIO descriptor corresponding to the function @con_id of device
		* dev, %NULL if no GPIO has been assigned to the requested function, or
		* another IS_ERR() code if an error occurred while trying to acquire the GPIO.
		*/
		struct gpio_desc __must_check devm_gpiod_get_index_optional(struct device dev,
		const char *con_id,
		@@ -207,6 +229,12 @@ EXPORT_SYMBOL_GPL(devm_gpiod_get_index_optional);
		* Managed gpiod_get_array(). GPIO descriptors returned from this function are
		* automatically disposed on driver detach. See gpiod_get_array() for detailed
		* information about behavior and return values.
		*
		* Returns:
		* The GPIO descriptors corresponding to the function @con_id of device
		* dev, %-ENOENT if no GPIO has been assigned to the requested function,
		* or another IS_ERR() code if an error occurred while trying to acquire
		* the GPIOs.
		*/
		struct gpio_descs __must_check devm_gpiod_get_array(struct device dev,
		const char *con_id,
		@@ -243,6 +271,12 @@ EXPORT_SYMBOL_GPL(devm_gpiod_get_array);
		* function are automatically disposed on driver detach.
		* See gpiod_get_array_optional() for detailed information about behavior and
		* return values.
		*
		* Returns:
		* The GPIO descriptors corresponding to the function @con_id of device
		* dev, %NULL if no GPIO has been assigned to the requested function,
		* or another IS_ERR() code if an error occurred while trying to acquire
		* the GPIOs.
		*/
		struct gpio_descs *__must_check
		devm_gpiod_get_array_optional(struct device dev, const char con_id,

drivers/gpio/gpiolib-legacy.c

+3 −0

Original line number	Diff line number	Diff line
		@@ -22,6 +22,9 @@ EXPORT_SYMBOL_GPL(gpio_free);
		* @label: a literal description string of this GPIO
		*
		* DEPRECATED This function is deprecated and must not be used in new code.
		*
		* Returns:
		* 0 on success, or negative errno on failure.
		*/
		int gpio_request_one(unsigned gpio, unsigned long flags, const char *label)
		{

drivers/gpio/gpiolib-of.c

+34 −14

Original line number	Diff line number	Diff line
		@@ -46,12 +46,15 @@ enum of_gpio_flags {
		* @propname: property name containing gpio specifier(s)
		*
		* The function returns the count of GPIOs specified for a node.
		* Note that the empty GPIO specifiers count too. Returns either
		* Number of gpios defined in property,
		* -EINVAL for an incorrectly formed gpios property, or
		* -ENOENT for a missing gpios property
		* NOTE: The empty GPIO specifiers count too.
		*
		* Returns:
		* Either number of GPIOs defined in the property, or
		* * %-EINVAL for an incorrectly formed "gpios" property, or
		* * %-ENOENT for a missing "gpios" property.
		*
		* Example::
		*
		* Example:
		* gpios = <0
		* &gpio1 1 2
		* 0
		@@ -77,6 +80,11 @@ static int of_gpio_named_count(const struct device_node *np,
		* "gpios" for the chip select lines. If we detect this, we redirect
		* the counting of "cs-gpios" to count "gpios" transparent to the
		* driver.
		*
		* Returns:
		* Either number of GPIOs defined in the property, or
		* * %-EINVAL for an incorrectly formed "gpios" property, or
		* * %-ENOENT for a missing "gpios" property.
		*/
		static int of_gpio_spi_cs_get_count(const struct device_node *np,
		const char *con_id)
		@@ -373,7 +381,8 @@ static void of_gpio_flags_quirks(const struct device_node *np,
		* @index: index of the GPIO
		* @flags: a flags pointer to fill in
		*
		* Returns GPIO descriptor to use with Linux GPIO API, or one of the errno
		* Returns:
		* GPIO descriptor to use with Linux GPIO API, or one of the errno
		* value on the error condition. If @flags is not NULL the function also fills
		* in flags for the GPIO.
		*/
		@@ -425,7 +434,8 @@ static struct gpio_desc of_get_named_gpiod_flags(const struct device_node np,
		*
		* DEPRECATED This function is deprecated and must not be used in new code.
		*
		* Returns GPIO number to use with Linux generic GPIO API, or one of the errno
		* Returns:
		* GPIO number to use with Linux generic GPIO API, or one of the errno
		* value on the error condition.
		*/
		int of_get_named_gpio(const struct device_node np, const char propname,
		@@ -711,7 +721,8 @@ struct gpio_desc of_find_gpio(struct device_node np, const char *con_id,
		* of_find_gpio() or of_parse_own_gpio()
		* @dflags: gpiod_flags - optional GPIO initialization flags
		*
		* Returns GPIO descriptor to use with Linux GPIO API, or one of the errno
		* Returns:
		* GPIO descriptor to use with Linux GPIO API, or one of the errno
		* value on the error condition.
		*/
		static struct gpio_desc of_parse_own_gpio(struct device_node np,
		@@ -779,7 +790,8 @@ static struct gpio_desc of_parse_own_gpio(struct device_node np,
		* @chip: gpio chip to act on
		* @hog: device node describing the hogs
		*
		* Returns error if it fails otherwise 0 on success.
		* Returns:
		* 0 on success, or negative errno on failure.
		*/
		static int of_gpiochip_add_hog(struct gpio_chip chip, struct device_node hog)
		{
		@@ -813,7 +825,9 @@ static int of_gpiochip_add_hog(struct gpio_chip chip, struct device_node hog)
		*
		* This is only used by of_gpiochip_add to request/set GPIO initial
		* configuration.
		* It returns error if it fails otherwise 0 on success.
		*
		* Returns:
		* 0 on success, or negative errno on failure.
		*/
		static int of_gpiochip_scan_gpios(struct gpio_chip *chip)
		{
		@@ -923,6 +937,9 @@ struct notifier_block gpio_of_notifier = {
		* This is simple translation function, suitable for the most 1:1 mapped
		* GPIO chips. This function performs only one sanity check: whether GPIO
		* is less than ngpios (that is specified in the gpio_chip).
		*
		* Returns:
		* GPIO number (>= 0) on success, negative errno on failure.
		*/
		static int of_gpio_simple_xlate(struct gpio_chip *gc,
		const struct of_phandle_args *gpiospec,
		@@ -972,6 +989,9 @@ static int of_gpio_simple_xlate(struct gpio_chip *gc,
		* If succeeded, this function will map bank's memory and will
		* do all necessary work for you. Then you'll able to use .regs
		* to manage GPIOs from the callbacks.
		*
		* Returns:
		* 0 on success, or negative errno on failure.
		*/
		int of_mm_gpiochip_add_data(struct device_node *np,
		struct of_mm_gpio_chip *mm_gc,