查看“GPIOLib overview”的源代码

The purpose of this article is to explain how the GPIOlib framework manages IOs/pins, how to configure it, and how to use it.

==Framework purpose==
As explain in [[Overview of GPIO pins]], the pins are multiplexed between "Alternate function", "ANALOG" and "GPIO" modes. The current article deals with the framework to use in order to manipulate GPIO: the GPIOLib framework. The GPIOLib framework is used when you want to control a pin directly in software, i.e. to set pin as output as a certain level (0/1), or to set pin in input configuration, or to configure the GPIO as an interrupt line. More details about GPIO in the kernel documentation are available in gpio.txt <ref name=gpio.txt>[https://www.kernel.org/doc/Documentation/gpio/gpio.txt Kernel documentation - gpio.txt], GPIO Kernel documentation</ref>

==System overview==
[[File:Gpiolib_overview.png]]

===Component description===
* '''GPIOLib:''' 
**provides the GPIOLib API to be used by a driver who wants to control a GPIO. See [[GPIOLib_overview#API_description|API]] for more details.
**calls the pinctrl framework to manage/configure pins.

* '''Pinctrl:''' the pinctrl framework '''core'''. Its role is:
**to call specific vendor callback for the pin configuration (muxing end setting).
**to create the logical pin mapping and guarantee pin exclusivity for a device. See [[Pinctrl overview]]

* '''Pinctrl-stm32:''' microprocessor '''specific''' pinctrl driver, its role is: 
**to register the vendor specific function (callback) in the pinctrl framework.
**to access to hardware registers to configure pins (muxing and all pin capabilities).

* '''IRQ chip''': provides the API<ref>[http://bootlin.com/doc/training/linux-kernel/linux-kernel-slides.pdf Interrupt Management training document], ''Linux Kernel and Driver Development''</ref> to request an IRQ for a GPIO Line.

* '''foo_driver:''' foo_driver could be any driver that needs to control a GPIO.

* '''debugfs:''' provides a debug interface available from the user terminal. See [[GPIOLib_overview#How to monitor with debugfs|How to monitor with debugfs]]. 

* '''GPIO tools:''' tools offered by the kernel to manipulate GPIOs. See [[GPIOLib_overview#Tools|GPIO tools]].

===API description===
Depending on needs and the caller location (kernel space or user space), several APIs are available to control a pin:

* '''User space API:''' the Linux<sup>&reg;</sup> standard character device driver interface<ref>[http://bootlin.com/doc/training/linux-kernel/linux-kernel-slides.pdf character device interface], ''Linux Kernel and Driver Development'' training document, see '''Kernel frameworks for device drivers''' chapter</ref> allows applications to manipulate all "system objects" with the standard file API (open, read, write, close, IOctl...). This is used to manipulate GPIO through user space, as gpio devices are seen as files.
**Refer to  [https://www.gnu.org/software/libc/manual/html_mono/libc.html#Low_002dLevel-I_002fO| GNU documentation] for file manipulation.
**See example [[How to control a GPIO in userspace]]


*'''Kernel space API''': the GPIOLib API provides API to the user driver. 
**See in the Kernel documentation "consumer.txt" <ref>[https://www.kernel.org/doc/Documentation/gpio/consumer.txt Kernel gpio documentation - consumer.txt],to know how to obtain and use GPIO in a driver</ref> to know how to obtain and use GPIO in a driver.
**See in the Kernel documentation "board.txt" <ref name="board.txt">[https://www.kernel.org/doc/Documentation/gpio/board.txt Kernel gpio documentation - board.txt], to know how to assign GPIOs to a consumer device and a function</ref> to know how to assign GPIOs to a consumer device.
** The GPIO descriptor acquisition is linked to a function label declared in the device tree. So there is a direct relationship between the driver and the device tree about this label, and the driver name (see sample code "dummy.c" below (ie "st,dummy" and "redled")).
**See example [[How to control a GPIO in kernel space]]


*'''Debugfs API''': provides only information about GPIO configuration. See [[GPIOLib_overview#How to monitor with debugfs|How to monitor with debugfs]].

==Configuration==
===Kernel configuration===
GPIOLib is activated by default in ST deliveries.

===Device tree configuration===
A detailed device tree configuration is described in [[GPIO device tree configuration]].

==How to use framework==
===How to configure a new board===
If you have to declare a GPIO, please refer first to the hardware block GPIO page: [[GPIO internal peripheral]] and your board scematics. Then either you declare your GPIO directly in [[GPIO device tree configuration|device tree]] or you declare it using the [[STM32CubeMX]].

===How to toggle a GPIO in user space===
[[How to control a GPIO in userspace]]

===How to toggle a GPIO in kernel space===
[[How_to_control_a_GPIO_in_kernel_space]]

===Tools===
[[How to control a GPIO in userspace#GPIO_control_through_libgpiod|Control GPIO through libgpiod]]

==How to trace and debug the framework==

=== How to monitor ===
==== How to monitor with debugfs ====
Some information about gpio is available in [[Debugfs]] interface.
 {{Board$}} cat /sys/kernel/debug/gpio

Output:

 gpiochip0: GPIOs 0-15, parent: platform/soc:pin-controller, GPIOA:
 ...
 gpiochip1: GPIOs 16-31, parent: platform/soc:pin-controller, GPIOB:
 ...
 gpiochip5: GPIOs 80-95, parent: platform/soc:pin-controller, GPIOF:
  gpio-94  (                    |?                   ) out hi    
  gpio-95  (                    |reset               ) out hi    
 ...

It provides per gpiochip: requested GPIOs, the state of the GPIO and the gpio-controller parent.

====Other ways to monitor====
You can also get GPIO information by using [[How to control a GPIO in userspace#GPIO_control_through_libgpiod|gpiodetect - gpioinfo tools]]

=== How to trace ===
By default there is no kernel trace to see the activity on GPIOs. However you could enable [[How to use the kernel dynamic debug|dynamic debug]] for the gpiolib and the pinctrl.
 {{Board$}} dmesg -n8
 {{Board$}} echo "file drivers/pinctrl/* +p" > /sys/kernel/debug/dynamic_debug/control
 {{Board$}} echo "file drivers/gio/* +p" > /sys/kernel/debug/dynamic_debug/control

==Source code location==
The source files are located inside the Linux kernel.

*'''GPIOLib''': gpiolib.c<ref>{{CodeSource | Linux kernel | drivers/gpio/gpiolib.c | GPIOLib source - gpiolib.c}} Provides GPIOLib API</ref> and gpiolib-of.c<ref>{{CodeSource | Linux kernel | drivers/gpio/gpiolib-of.c | GPIOLib source - gpiolib-of.c}} Provides OF-GPIOLib API</ref>

*'''GPIO tools''': folder tools/gpio in Kernel<ref>{{CodeSource | Linux kernel | tools/gpio | gpio tools folder}} Provides all sources of GPIO tools</ref>

*'''Pinctrl core part''': generic core<ref>{{CodeSource | Linux kernel | drivers/pinctrl/core.c | Pinctrl framework source - core.c}} Sources of generic pinctrl framework</ref>, generic pinconf<ref>{{CodeSource | Linux kernel | drivers/pinctrl/pinconf.c | Pinctrl framework source - pinconf.c}} Sources of generic pin configuration</ref> and generic pinmux<ref>{{CodeSource | Linux kernel | drivers/pinctrl/pinmux.c | Pinctrl framework source - pinmux.c}} Sources of generic pin muxing</ref>

*'''STM32 pinctrl vendor part''': folder to STM32 dedicated pinctrl functions<ref>{{CodeSource | Linux kernel | drivers/pinctrl/stm32 | STM32 vendor specific folder}} Provides all vendor specifics functions</ref>

==To go further==
GPIOLib is the main framework to handle a GPIO at run time. However, dedicated GPIO drivers already exist to control basic features (Leds, regulator, buttons, ...). You can find the list (and more details) inside the Kernel documentation <ref>[https://www.kernel.org/doc/Documentation/gpio/drivers-on-gpio.txt Kernel documentation - drivers-on-gpio.txt] List and explain standard kernel drivers used for common GPIO task </ref>

==References==
<references />

<noinclude>
[[Category:IOs pin management|3]]
{{PublicationRequestId |  9261 | 2018-10-18 |AlainF}}
{{ArticleBasedOnModel | Framework overview article model}}
</noinclude>