From ddb4e53fc72ec907f99199749cb4c71af4794607 Mon Sep 17 00:00:00 2001 From: Linus Walleij Date: Wed, 8 Jan 2020 01:17:12 +0100 Subject: gpio: Add use guidance documentation The text in this new document is a response to recurring questions about the GPIO in-kernel API vs the userspace ABI. When do you use one or the other? It can be a bit intuitive, but I tried to sum it all up. Reviewed-by: Bartosz Golaszewski Link: https://lore.kernel.org/r/20200108001712.47500-1-linus.walleij@linaro.org Signed-off-by: Linus Walleij --- Documentation/driver-api/gpio/drivers-on-gpio.rst | 8 ++-- Documentation/driver-api/gpio/index.rst | 1 + Documentation/driver-api/gpio/using-gpio.rst | 50 +++++++++++++++++++++++ 3 files changed, 55 insertions(+), 4 deletions(-) create mode 100644 Documentation/driver-api/gpio/using-gpio.rst (limited to 'Documentation/driver-api/gpio') diff --git a/Documentation/driver-api/gpio/drivers-on-gpio.rst b/Documentation/driver-api/gpio/drivers-on-gpio.rst index f3a189320e11..820b403d50f6 100644 --- a/Documentation/driver-api/gpio/drivers-on-gpio.rst +++ b/Documentation/driver-api/gpio/drivers-on-gpio.rst @@ -95,7 +95,7 @@ to emulate MCTRL (modem control) signals CTS/RTS by using two GPIO lines. The MTD NOR flash has add-ons for extra GPIO lines too, though the address bus is usually connected directly to the flash. -Use those instead of talking directly to the GPIOs using sysfs; they integrate -with kernel frameworks better than your userspace code could. Needless to say, -just using the appropriate kernel drivers will simplify and speed up your -embedded hacking in particular by providing ready-made components. +Use those instead of talking directly to the GPIOs from userspace; they +integrate with kernel frameworks better than your userspace code could. +Needless to say, just using the appropriate kernel drivers will simplify and +speed up your embedded hacking in particular by providing ready-made components. diff --git a/Documentation/driver-api/gpio/index.rst b/Documentation/driver-api/gpio/index.rst index 5b61032aa4ea..1d48fe248f05 100644 --- a/Documentation/driver-api/gpio/index.rst +++ b/Documentation/driver-api/gpio/index.rst @@ -8,6 +8,7 @@ Contents: :maxdepth: 2 intro + using-gpio driver consumer board diff --git a/Documentation/driver-api/gpio/using-gpio.rst b/Documentation/driver-api/gpio/using-gpio.rst new file mode 100644 index 000000000000..dda069444032 --- /dev/null +++ b/Documentation/driver-api/gpio/using-gpio.rst @@ -0,0 +1,50 @@ +========================= +Using GPIO Lines in Linux +========================= + +The Linux kernel exists to abstract and present hardware to users. GPIO lines +as such are normally not user facing abstractions. The most obvious, natural +and preferred way to use GPIO lines is to let kernel hardware drivers deal +with them. + +For examples of already existing generic drivers that will also be good +examples for any other kernel drivers you want to author, refer to +:doc:`drivers-on-gpio` + +For any kind of mass produced system you want to support, such as servers, +laptops, phones, tablets, routers, and any consumer or office or business goods +using appropriate kernel drivers is paramount. Submit your code for inclusion +in the upstream Linux kernel when you feel it is mature enough and you will get +help to refine it, see :doc:`../../process/submitting-patches`. + +In Linux GPIO lines also have a userspace ABI. + +The userspace ABI is intended for one-off deployments. Examples are prototypes, +factory lines, maker community projects, workshop specimen, production tools, +industrial automation, PLC-type use cases, door controllers, in short a piece +of specialized equipment that is not produced by the numbers, requiring +operators to have a deep knowledge of the equipment and knows about the +software-hardware interface to be set up. They should not have a natural fit +to any existing kernel subsystem and not be a good fit for an operating system, +because of not being reusable or abstract enough, or involving a lot of non +computer hardware related policy. + +Applications that have a good reason to use the industrial I/O (IIO) subsystem +from userspace will likely be a good fit for using GPIO lines from userspace as +well. + +Do not under any circumstances abuse the GPIO userspace ABI to cut corners in +any product development projects. If you use it for prototyping, then do not +productify the prototype: rewrite it using proper kernel drivers. Do not under +any circumstances deploy any uniform products using GPIO from userspace. + +The userspace ABI is a character device for each GPIO hardware unit (GPIO chip). +These devices will appear on the system as ``/dev/gpiochip0`` thru +``/dev/gpiochipN``. Examples of how to directly use the userspace ABI can be +found in the kernel tree ``tools/gpio`` subdirectory. + +For structured and managed applications, we recommend that you make use of the +libgpiod_ library. This provides helper abstractions, command line utlities +and arbitration for multiple simultaneous consumers on the same GPIO chip. + +.. _libgpiod: https://git.kernel.org/pub/scm/libs/libgpiod/libgpiod.git/ -- cgit v1.2.3 From 72780ce5f1a4189f3c8dcfb1c596c65146452668 Mon Sep 17 00:00:00 2001 From: Linus Walleij Date: Mon, 13 Jan 2020 23:08:00 +0100 Subject: gpio: Drop the chained IRQ handler assign function gpiochip_set_chained_irqchip() would assign a chained handler to a GPIO chip. We now populate struct gpio_irq_chip for all chained GPIO irqchips so drop this function. Cc: Andy Shevchenko Signed-off-by: Linus Walleij Link: https://lore.kernel.org/r/20200113220800.77817-1-linus.walleij@linaro.org Signed-off-by: Linus Walleij --- Documentation/driver-api/gpio/driver.rst | 5 ----- drivers/gpio/gpio-mt7621.c | 3 +-- drivers/gpio/gpio-xgs-iproc.c | 3 +-- drivers/gpio/gpiolib.c | 25 +------------------------ include/linux/gpio/driver.h | 5 ----- 5 files changed, 3 insertions(+), 38 deletions(-) (limited to 'Documentation/driver-api/gpio') diff --git a/Documentation/driver-api/gpio/driver.rst b/Documentation/driver-api/gpio/driver.rst index 2ff743105927..871922529332 100644 --- a/Documentation/driver-api/gpio/driver.rst +++ b/Documentation/driver-api/gpio/driver.rst @@ -507,11 +507,6 @@ available but we try to move away from this: cascaded irq has to be handled by a threaded interrupt handler. Apart from that it works exactly like the chained irqchip. -- DEPRECATED: gpiochip_set_chained_irqchip(): sets up a chained cascaded irq - handler for a gpio_chip from a parent IRQ and passes the struct gpio_chip* - as handler data. Notice that we pass is as the handler data, since the - irqchip data is likely used by the parent irqchip. - - gpiochip_set_nested_irqchip(): sets up a nested cascaded irq handler for a gpio_chip from a parent IRQ. As the parent IRQ has usually been explicitly requested by the driver, this does very little more than diff --git a/drivers/gpio/gpio-mt7621.c b/drivers/gpio/gpio-mt7621.c index d1d785f983a7..b992321bb852 100644 --- a/drivers/gpio/gpio-mt7621.c +++ b/drivers/gpio/gpio-mt7621.c @@ -253,8 +253,7 @@ mediatek_gpio_bank_probe(struct device *dev, /* * Directly request the irq here instead of passing - * a flow-handler to gpiochip_set_chained_irqchip, - * because the irq is shared. + * a flow-handler because the irq is shared. */ ret = devm_request_irq(dev, mtk->gpio_irq, mediatek_gpio_irq_handler, IRQF_SHARED, diff --git a/drivers/gpio/gpio-xgs-iproc.c b/drivers/gpio/gpio-xgs-iproc.c index 773e5c24309e..55af83629cfc 100644 --- a/drivers/gpio/gpio-xgs-iproc.c +++ b/drivers/gpio/gpio-xgs-iproc.c @@ -251,8 +251,7 @@ static int iproc_gpio_probe(struct platform_device *pdev) /* * Directly request the irq here instead of passing - * a flow-handler to gpiochip_set_chained_irqchip, - * because the irq is shared. + * a flow-handler because the irq is shared. */ ret = devm_request_irq(dev, irq, iproc_gpio_irq_handler, IRQF_SHARED, chip->gc.label, &chip->gc); diff --git a/drivers/gpio/gpiolib.c b/drivers/gpio/gpiolib.c index 9913886ede90..ea19ce5fbac5 100644 --- a/drivers/gpio/gpiolib.c +++ b/drivers/gpio/gpiolib.c @@ -1805,7 +1805,7 @@ EXPORT_SYMBOL_GPL(gpiochip_irqchip_irq_valid); * gpiochip_set_cascaded_irqchip() - connects a cascaded irqchip to a gpiochip * @gc: the gpiochip to set the irqchip chain to * @parent_irq: the irq number corresponding to the parent IRQ for this - * chained irqchip + * cascaded irqchip * @parent_handler: the parent interrupt handler for the accumulated IRQ * coming out of the gpiochip. If the interrupt is nested rather than * cascaded, pass NULL in this handler argument @@ -1847,29 +1847,6 @@ static void gpiochip_set_cascaded_irqchip(struct gpio_chip *gc, } } -/** - * gpiochip_set_chained_irqchip() - connects a chained irqchip to a gpiochip - * @gpiochip: the gpiochip to set the irqchip chain to - * @irqchip: the irqchip to chain to the gpiochip - * @parent_irq: the irq number corresponding to the parent IRQ for this - * chained irqchip - * @parent_handler: the parent interrupt handler for the accumulated IRQ - * coming out of the gpiochip. - */ -void gpiochip_set_chained_irqchip(struct gpio_chip *gpiochip, - struct irq_chip *irqchip, - unsigned int parent_irq, - irq_flow_handler_t parent_handler) -{ - if (gpiochip->irq.threaded) { - chip_err(gpiochip, "tried to chain a threaded gpiochip\n"); - return; - } - - gpiochip_set_cascaded_irqchip(gpiochip, parent_irq, parent_handler); -} -EXPORT_SYMBOL_GPL(gpiochip_set_chained_irqchip); - /** * gpiochip_set_nested_irqchip() - connects a nested irqchip to a gpiochip * @gpiochip: the gpiochip to set the irqchip nested handler to diff --git a/include/linux/gpio/driver.h b/include/linux/gpio/driver.h index e2480ef94c55..7067bc70a473 100644 --- a/include/linux/gpio/driver.h +++ b/include/linux/gpio/driver.h @@ -585,11 +585,6 @@ int gpiochip_irq_domain_activate(struct irq_domain *domain, void gpiochip_irq_domain_deactivate(struct irq_domain *domain, struct irq_data *data); -void gpiochip_set_chained_irqchip(struct gpio_chip *gpiochip, - struct irq_chip *irqchip, - unsigned int parent_irq, - irq_flow_handler_t parent_handler); - void gpiochip_set_nested_irqchip(struct gpio_chip *gpiochip, struct irq_chip *irqchip, unsigned int parent_irq); -- cgit v1.2.3