UserSpaceGPIOinterrupts [FreeBSD WIKI]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Implementation of a user space interface for GPIO interrupts ======
  * Student: Christian Krämer (uddka@student.kit.edu)
  * Mentors: 
    * Chuck Tuffli (chuck@%%FreeBSD%%.org)
    * Luiz Otavio O Souza (loos@%%FreeBSD%%.org)

===== Project description =====

%%FreeBSD%% already has support for interrupts implemented in the GPIO controller drivers of several %%SoCs%%, but there are no interfaces to take advantage of them out of user space yet. The goal of this project is to implement such an interface by providing descriptors which integrate with the common I/O system calls and multiplexing mechanisms.

===== Approach to solving the problem =====

Writing a kernel driver that sets the interrupts up and controls the interrupt related resources. Furthermore, the driver provides a handler function for the interrupts which serves the file descriptors. A user space API to create and configure those descriptors must also be implemented (ideally these functions would be integrated into libgpio and gpioctl). These API should allow the configuration of interrupt specific attributes like trigger-type. To conclude, some hardware tests shall be done on %%SoCs%% that support GPIO generated interrupts.

Upon suggestion of my mentors the major part of the kernel functionality was integrated in the already existing gpioc driver. This allows to use the already existing functions for interrupt configuration of libgpio to set and retrieve the configuration flags. The gpioctl utility was updated in order to be able to print the interrupt capabilities and flags.

===== Deliverables =====

  * Writing a kernel driver that provides an interface to the user space. ✔
  * Implement support for the most common I/O system calls / multiplexing mechanisms.
    * read() ✔
      * Places the pin number on which the interrupt occurred in the buffer.
      * Blocking and non-blocking behaviour.
    * poll()/select() ✔
    * kqueue() ✔
    * <del>asynchronous I/O</del>
      * Since %%FreeBSD%% 11 asynchronous I/O operations are not allowed on all file descriptor types any more, because they are considered as unsafe. This behaviour also includes character device file descriptors.
    * signal driven I/O. ✔
      * Posting SIGIO when the O_ASYNC was set.
  * Pin distinction <del>either</del> by using separate <del>character devices or</del> file descriptors. ✔
  * Many-to-many relationship between pins and file descriptors ✔
    * A file descriptor can monitor several GPIO pins.
    * A GPIO pin can be monitored by multiple file descriptors.
  * Integration with gpioctl and libgpio. ✔
  * Interrupt rate limiting.

===== Test Plan =====

Hardware tests should be done on the %%BeagleBone%% Black (TI Sitara AM3359) and %%RaspberryPi%% 3 (Broadcom BCM2837), because their %%SoCs%% support interrupts along with the gpiobus driver.

Initially it should be sufficient to wire simple push buttons to the GPIO pins, or to connect them to each other with a simple delay circuit. When everything works fine so far, I am planning to do some more advanced hardware tests e. g. by connecting a Microcontroller for automated long-term scenarios, or even by generating some stress on the pins.

===== The Code =====

The source code of the kernel driver can be found in [[https://github.com/ckraemer/freebsd/tree/gsoc2018|my fork of the FreeBSD src tree]] on %%GitHub%%. The utilities for configuration and testing are located in [[https://github.com/ckraemer/gsoc2018-utils|this repository]].

===== Notes =====

==== Usage ====

Usage of the code is quite simple. First of all, get a handle to the appropriate gpioc device via the [[https://man.freebsd.org/gpio_open|gpio_open]] or [[https://man.freebsd.org/gpio_open_device|gpio_open_device]] functions of [[https://man.freebsd.org/gpio(3)|gpio(3)]]. After that set the configuration with an interrupt flag using [[https://man.freebsd.org/gpio_pin_config|gpio_pin_config]] on any pin(s) which should be monitored. The interrupt flags are declared in sys/gpio.h. Please note, that only pins configured as input can utilize interrupt capabilities and only one interrupt flag per pin can be set at once. After configuring the pin(s) with an interrupt flag, simply call [[https://man.freebsd.org/read(2)|read(2)]] or any other I/O multiplexing syscall on the handle. You can also take a look at [[https://github.com/ckraemer/gsoc2018-utils/blob/master/src/gpioc_intr_test.c|gpioc_intr_test]] of the utilities repository.

==== Possible further improvements ====

  * Interrupt rate limiting.
  * Buffer for occurred interrupts.
    * Currently only the last pin is stored in the kernel driver per file descriptor.
  * Specific kevent filter.
    * Implementing a custom kevent filter brings the advantage that the pin on which the interrupt occurred can be stored directly in the filter-specific data fields of the kevent structure. Thereby no more separate call to read() is necessary.

==== Questions asked regarding this project ====

  * Does Linux or any other OS already provide an API, and if so does it make sense to be compatible with them or can it be done better?
    * In Linux this is possible via sysfs. There are virtual files provided for configuration, and also for the actual value of the pin which can be monitored when the pin is accordingly configured. This is no option for %%FreeBSD%%, because achieving compatibility with sysfs for this feature seems unsuitable.\\ I do not know about other operating systems yet, but I think this should be integrated into the already existing utilities in the %%FreeBSD%% base system for GPIOs (libgpio and gpioctl) in the first place.