From a621c99a96e64e3d6d5d47745a5e832262ac8f7c Mon Sep 17 00:00:00 2001 From: Linus Walleij Date: Tue, 12 Sep 2017 09:32:34 +0200 Subject: gpio: Clarify consumer stubs use-cases After discussion we add a few blurbs to clarify how the stubs in the consumer API are supposed to be used. Cc: Florian Fainelli Cc: Sergei Shtylyov Cc: Andrew Lunn Signed-off-by: Linus Walleij --- Documentation/gpio/consumer.txt | 22 +++++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) (limited to 'Documentation/gpio') diff --git a/Documentation/gpio/consumer.txt b/Documentation/gpio/consumer.txt index 912568baabb9..ddbfa775a78a 100644 --- a/Documentation/gpio/consumer.txt +++ b/Documentation/gpio/consumer.txt @@ -10,14 +10,30 @@ Guidelines for GPIOs consumers ============================== Drivers that can't work without standard GPIO calls should have Kconfig entries -that depend on GPIOLIB. The functions that allow a driver to obtain and use -GPIOs are available by including the following file: +that depend on GPIOLIB or select GPIOLIB. The functions that allow a driver to +obtain and use GPIOs are available by including the following file: #include +There are static inline stubs for all functions in the header file in the case +where GPIOLIB is disabled. When these stubs are called they will emit +warnings. These stubs are used for two use cases: + +- Simple compile coverage with e.g. COMPILE_TEST - it does not matter that + the current platform does not enable or select GPIOLIB because we are not + going to execute the system anyway. + +- Truly optional GPIOLIB support - where the driver does not really make use + of the GPIOs on certain compile-time configurations for certain systems, but + will use it under other compile-time configurations. In this case the + consumer must make sure not to call into these functions, or the user will + be met with console warnings that may be perceived as intimidating. + All the functions that work with the descriptor-based GPIO interface are prefixed with gpiod_. The gpio_ prefix is used for the legacy interface. No -other function in the kernel should use these prefixes. +other function in the kernel should use these prefixes. The use of the legacy +functions is strongly discouraged, new code should use +and descriptors exclusively. Obtaining and Disposing GPIOs -- cgit v1.2.3 From eec1d566cdf94b57e8f5ba9fe60eea214929bcfc Mon Sep 17 00:00:00 2001 From: Lukas Wunner Date: Thu, 12 Oct 2017 12:40:10 +0200 Subject: gpio: Introduce ->get_multiple callback SPI-attached GPIO controllers typically read out all inputs in one go. If callers desire the values of multipe inputs, ideally a single readout should take place to return the desired values. However the current driver API only offers a ->get callback but no ->get_multiple (unlike ->set_multiple, which is present). Thus, to read multiple inputs, a full readout needs to be performed for every single value (barring driver-internal caching), which is inefficient. In fact, the lack of a ->get_multiple callback has been bemoaned repeatedly by the gpio subsystem maintainer: http://www.spinics.net/lists/linux-gpio/msg10571.html http://www.spinics.net/lists/devicetree/msg121734.html Introduce the missing callback. Add corresponding consumer functions such as gpiod_get_array_value(). Amend linehandle_ioctl() to take advantage of the newly added infrastructure. Update the documentation. Cc: Rojhalat Ibrahim Signed-off-by: Lukas Wunner Signed-off-by: Linus Walleij --- Documentation/gpio/consumer.txt | 41 ++++++++++++++++++++++++++++++----------- 1 file changed, 30 insertions(+), 11 deletions(-) (limited to 'Documentation/gpio') diff --git a/Documentation/gpio/consumer.txt b/Documentation/gpio/consumer.txt index ddbfa775a78a..63e1bd1d88e3 100644 --- a/Documentation/gpio/consumer.txt +++ b/Documentation/gpio/consumer.txt @@ -295,9 +295,22 @@ as possible, especially by drivers which should not care about the actual physical line level and worry about the logical value instead. -Set multiple GPIO outputs with a single function call ------------------------------------------------------ -The following functions set the output values of an array of GPIOs: +Access multiple GPIOs with a single function call +------------------------------------------------- +The following functions get or set the values of an array of GPIOs: + + int gpiod_get_array_value(unsigned int array_size, + struct gpio_desc **desc_array, + int *value_array); + int gpiod_get_raw_array_value(unsigned int array_size, + struct gpio_desc **desc_array, + int *value_array); + int gpiod_get_array_value_cansleep(unsigned int array_size, + struct gpio_desc **desc_array, + int *value_array); + int gpiod_get_raw_array_value_cansleep(unsigned int array_size, + struct gpio_desc **desc_array, + int *value_array); void gpiod_set_array_value(unsigned int array_size, struct gpio_desc **desc_array, @@ -312,34 +325,40 @@ The following functions set the output values of an array of GPIOs: struct gpio_desc **desc_array, int *value_array) -The array can be an arbitrary set of GPIOs. The functions will try to set +The array can be an arbitrary set of GPIOs. The functions will try to access GPIOs belonging to the same bank or chip simultaneously if supported by the corresponding chip driver. In that case a significantly improved performance -can be expected. If simultaneous setting is not possible the GPIOs will be set -sequentially. +can be expected. If simultaneous access is not possible the GPIOs will be +accessed sequentially. -The gpiod_set_array() functions take three arguments: +The functions take three arguments: * array_size - the number of array elements * desc_array - an array of GPIO descriptors - * value_array - an array of values to assign to the GPIOs + * value_array - an array to store the GPIOs' values (get) or + an array of values to assign to the GPIOs (set) The descriptor array can be obtained using the gpiod_get_array() function or one of its variants. If the group of descriptors returned by that function -matches the desired group of GPIOs, those GPIOs can be set by simply using +matches the desired group of GPIOs, those GPIOs can be accessed by simply using the struct gpio_descs returned by gpiod_get_array(): struct gpio_descs *my_gpio_descs = gpiod_get_array(...); gpiod_set_array_value(my_gpio_descs->ndescs, my_gpio_descs->desc, my_gpio_values); -It is also possible to set a completely arbitrary array of descriptors. The +It is also possible to access a completely arbitrary array of descriptors. The descriptors may be obtained using any combination of gpiod_get() and gpiod_get_array(). Afterwards the array of descriptors has to be setup -manually before it can be used with gpiod_set_array(). +manually before it can be passed to one of the above functions. Note that for optimal performance GPIOs belonging to the same chip should be contiguous within the array of descriptors. +The return value of gpiod_get_array_value() and its variants is 0 on success +or negative on error. Note the difference to gpiod_get_value(), which returns +0 or 1 on success to convey the GPIO value. With the array functions, the GPIO +values are stored in value_array rather than passed back as return value. + GPIOs mapped to IRQs -------------------- -- cgit v1.2.3 From f0fbe7bce733561b76a5b55c5f4625888acd3792 Mon Sep 17 00:00:00 2001 From: Thierry Reding Date: Tue, 7 Nov 2017 19:15:47 +0100 Subject: gpio: Move irqdomain into struct gpio_irq_chip In order to consolidate the multiple ways to associate an IRQ chip with a GPIO chip, move more fields into the new struct gpio_irq_chip. Signed-off-by: Thierry Reding Acked-by: Grygorii Strashko Signed-off-by: Linus Walleij --- Documentation/gpio/driver.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/gpio') diff --git a/Documentation/gpio/driver.txt b/Documentation/gpio/driver.txt index fc1d2f83564d..dcf6af1d9e56 100644 --- a/Documentation/gpio/driver.txt +++ b/Documentation/gpio/driver.txt @@ -254,7 +254,7 @@ GPIO irqchips usually fall in one of two categories: static irqreturn_t omap_gpio_irq_handler(int irq, void *gpiobank) unsigned long wa_lock_flags; raw_spin_lock_irqsave(&bank->wa_lock, wa_lock_flags); - generic_handle_irq(irq_find_mapping(bank->chip.irqdomain, bit)); + generic_handle_irq(irq_find_mapping(bank->chip.irq.domain, bit)); raw_spin_unlock_irqrestore(&bank->wa_lock, wa_lock_flags); * GENERIC CHAINED GPIO irqchips: these are the same as "CHAINED GPIO irqchips", -- cgit v1.2.3 From dc7b0387ee894c115ef5ddcaaf794125d6d9058c Mon Sep 17 00:00:00 2001 From: Thierry Reding Date: Tue, 7 Nov 2017 19:15:52 +0100 Subject: gpio: Move irq_valid_mask into struct gpio_irq_chip In order to consolidate the multiple ways to associate an IRQ chip with a GPIO chip, move more fields into the new struct gpio_irq_chip. Signed-off-by: Thierry Reding Acked-by: Grygorii Strashko Signed-off-by: Linus Walleij --- Documentation/gpio/driver.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation/gpio') diff --git a/Documentation/gpio/driver.txt b/Documentation/gpio/driver.txt index dcf6af1d9e56..d8de1c7de85a 100644 --- a/Documentation/gpio/driver.txt +++ b/Documentation/gpio/driver.txt @@ -313,8 +313,8 @@ symbol: mark all the child IRQs as having the other IRQ as parent. If there is a need to exclude certain GPIOs from the IRQ domain, you can -set .irq_need_valid_mask of the gpiochip before gpiochip_add_data() is -called. This allocates an .irq_valid_mask with as many bits set as there +set .irq.need_valid_mask of the gpiochip before gpiochip_add_data() is +called. This allocates an .irq.valid_mask with as many bits set as there are GPIOs in the chip. Drivers can exclude GPIOs by clearing bits from this mask. The mask must be filled in before gpiochip_irqchip_add() or gpiochip_irqchip_add_nested() is called. -- cgit v1.2.3