A process may use mmap(2) to memory-map a single memory page from the external interrupt device file into the process' address space. At the beginning of this page, a counter of an unsigned long type is maintained. This counter is incremented with each external interrupt received by the device.

Alternatively, the read(2) system call returns a string representation of the counter's current value.

The poll(2) and select(2) system calls allow a process to wait for an interrupt to trigger:

The flock(2) system call with the options LOCK_EX|LOCK_MAND ensures exclusive write access to the device attribute files (for example, /sys/class/extint/extint #/mode).

---

Note: You must define the _GNU_SOURCE macro before including the header files in order to use the LOCK_MAND flag on the call to flock(2).

---

When this lock is obtained, only a process that has access to the corresponding file descriptor will be able to write to the attribute files for that device. Any other process that attempts a write(2) system call on one of these attribute files will fail with errno set to EAGAIN.

The flock() system call will block until there are no other processes that have the device file open and until no other flock() is active on the device. However, if LOCK_NB is passed to flock(), the call will fail and errno will be set to EWOULDBLOCK.

While a lock is in place, any attempt to call open(2) on the device will block. However, if O_NONBLOCK is passed to open(), the call will fail and errno will be set to EWOULDBLOCK.

To release the lock, call flock() with the LOCK_UN argument. The lock will also be automatically dropped when the last user of the corresponding file descriptor closes the file, including via a process exit. The lock will persist if the file descriptor is inherited across fork(2) or exec(2) system calls.

---

Note: You must not pass the LOCK_MAND flag along with the LOCK_UN flag. The flock() system call behavior is unspecified in this case.

---

Example 3-1 illustrates a method of searching for an unused external interrupt device that can be used exclusively by that program.

#define _GNU_SOURCE

#include <stdio.h>
#include <sys/file.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
#include <limits.h>
#include <errno.h>
#include <string.h>
int main(void) {
        char devfile[PATH_MAX];
        int i = 0;
        int fd;
        int found = 0;
        int status;

try_again:
        /* Search for free /dev/extint# device */
        while (i <= 255) {
                sprintf(devfile, "/dev/extint%d", i);
                i++;

                fd = open(devfile, O_RDONLY|O_NONBLOCK);
                if (fd >= 0) {
                        /* Found a unlocked device. */
                        found = 1;
                        break;
                }

                /* An error occurred.  Check why. */
                if (EWOULDBLOCK == errno) {
                        /* Found a locked device. */
                        printf("Tried %s, but it is locked.\n", devfile);
                }
                /* Some other type of error, just try next device.
                 * But don't complain about non-existent devices.
                 */
                if (ENOENT != errno)
                        printf("Unexpected error opening %s: %s\n",
                               devfile, strerror(errno));
        }

        if (!found) {
                printf("Could not find unlocked extint device to use.\n");
                return 1;
        }

        /* Try locking this device to gain exclusive access. */
        status = flock(fd, LOCK_EX|LOCK_MAND|LOCK_NB);
        if (status != 0) {
                if (EWOULDBLOCK == errno) {
                        /* The device was available, but another process
                         * has locked it between the time we opened it
                         * and made the flock() call.
                         */
                        printf("Opened %s, but someone else locked it.\n",
                               devfile);
                } else {
                        /* Some other error occurred. */
                        printf("Unexpected error locking %s: %s\n",
                               devfile, strerror(errno));
                }
                /* Try the next device. */
                found = 0;
                close(fd);
                goto try_again;
        }

        /* Successfully gained exclusive use of device */
        printf("Exclusive use of %s established.\n", devfile);

        /* Application code begins... */

        /* ... application code ends. */

        /* Unlock and close external interrupt device */
        flock(fd, LOCK_UN);
        close(fd);

        /* Successful run */
        return 0;
}

To register the low-level driver with the abstraction layer, use the following call:

struct extint_device*
extint_device_register(struct extint_properties *ep,
                       void *devdata);

The ep argument is a pointer to an extint_properties structure that specifies the particular low-level driver functions that the abstraction layer should call when reading/writing the attributes described in “sysfs Attribute Files”.

The devdata argument is an opaque pointer that is stored by the extint code. To retrieve or modify this value, use the following calls:

void* extint_get_devdata(const struct extint_device *ed);
void extint_set_devdata(struct extint_device *ed, void* devdata);

The low-level driver may use the devdata value in any manner desired, because the extint driver does not interpret its contents.

The return value is one of the following:

The struct extint_properties call table is as follows:

struct extint_properties {
        /* Owner module */
        struct module *owner;

        /* Get/set generation mode */
        ssize_t (*get_mode)(struct extint_device * ed, char *buf);
        ssize_t (*set_mode)(struct extint_device * ed, const char *buf,
                            size_t count);

        /* Get generation mode list */
        ssize_t (*get_modelist)(struct extint_device * ed, char *buf);

        /* Get/set generation period */
        unsigned long (*get_period)(struct extint_device * ed);
        ssize_t (*set_period)(struct extint_device * ed, unsigned long period);

        /* Get low-level provider name */
        ssize_t (*get_provider)(struct extint_device *ed, char *buf);

        /* Generation period quantum */
        unsigned long (*get_quantum)(struct extint_device * ed);

        /* Get/set ingest source */
        ssize_t (*get_source)(struct extint_device * ed, char *buf);
        ssize_t (*set_source)(struct extint_device * ed, const char *buf,
                              size_t count);

        /* Get ingest source list */
        ssize_t (*get_sourcelist)(struct extint_device * ed, char *buf);

        /* Arm/disarm timer */
        int64_t (*arm_timer)(struct extint_device * ed, int64_t ns, int when);
        void (*disarm_timer)(struct extint_device * ed);
};

---

Note: Additional fields not of interest to the low-level external interrupt driver may be present. You should include /usr/local/include/extint.h to acquire these structure definitions.

---

The owner value should be set to the module that contains the functions pointed to by the remaining structure members. The remaining functions implement low-level aspects of the abstraction layer attributes. They all take a pointer to the struct extint_device as was returned from the registration function. In all of these functions, you can retrieve the value passed as the devdata argument to the registration function by using the following call:

extint_get_devdata(ed);

You can update the value by using the following call:

extint_set_devdata(ed, newvalue);

Typically, this value is a pointer to driver-specific data for the individual device being operated upon. It may, for example, contain pointers to mapped PCI regions where control registers reside.

When an external interrupt signal triggers an interrupt that is handled by the low-level driver, the driver should make the following call:

void
extint_interrupt(struct extint_device *ed);

This allows the abstraction layer to perform any appropriate abstracted actions, such as update the interrupt count or trigger poll/ select actions. The sole argument is the struct extint_device that was returned from the registration call.

When the driver desires to deregister a particular device previously registered with the abstraction layer, it should make the following call:

void
extint_device_unregister(struct extint_device *ed);

The sole argument is the struct extint_device that was returned from the registration call. There is no error return from this call, but if invalid data is passed to it, the likelihood of a kernel panic is very high.

If your hardware device supports capabilities that are not provided for in the abstraction layer, you can do one of the following:

For example, the SGI PCIE-RT card has the ability to map the interrupt output control register directly into a user application in order to avoid the kernel overhead of reading/writing the abstracted attribute files. Using this capability means that the application must have intimate knowledge of the control register's format, something that cannot be abstracted away by the kernel and is very specific to this particular hardware implementation. This capability is provided by the pcie_rt driver, which supplies its own character special device along with a pcie_rt device class.

For systems (not just applications) that are critically interested in responding as quickly as possible to an externally triggered event, waiting for a poll/select operation, or even busy-waiting on the value of the interrupt counter to change, may have unexpected harmful effects (such as tying up a CPU spinning on a value) or may not provide appropriate response times.

A callout mechanism lets you write your own kernel module in order to gain minimal-latency notification of events and react accordingly. It also provides an extension capability that might be of interest in certain situations. For example, there could be an application that requires an interrupt counter page similar to the one maintained by the abstraction layer, but that starts counting at 0 when the device special file is opened. Or, there could be an application that requires a signal to be generated and delivered to the process when an interrupt is ingested. These examples are more esoteric than the simple counter page, and are best provided by a separate module rather than cluttering the main external interrupt abstraction code.

To register a callout to be invoked upon interrupt ingest, allocate a struct extint_callout , fill it in, and pass it to the following call:

int
extint_callout_register(struct extint_device *ed,
                        struct extint_callout *ec);

The first argument is the struct extint_device corresponding to the particular abstracted external interrupt hardware device of interest. How this structure is found is up to the caller; however, the file_to_extint_device function will convert a struct file pointer to a struct extint_device pointer. This function will return -EINVAL if an inappropriate file descriptor is passed to it.

The second argument is one of the following structures:

struct extint_callout {
        struct module* owner;
        void (*function)(void *);
        void *data;
};

---

Note: Additional fields not of interest to the external interrupt user may be present. You should include /usr/local/include/extint.h to acquire these structure definitions.

---

The owner field should be set to the module containing the function and data pointed to by the remaining fields.

The function pointer is a callout function that is to be invoked whenever an interrupt is ingested by the abstraction layer for the device of interest. The data field is the only argument passed to it; it is used opaquely and is provided solely for use by the caller. That is, the abstraction layer will invoke the following upon each interrupt of the specified device:

ec->function(data);

You can register multiple callouts for the same abstracted external interrupt device. They will be invoked in no guaranteed order, but will be invoked one at a time.

The interrupt counter will be incremented before the callouts are invoked, but before any signal/poll notifications occur.

The module specified by the owner field in the callout structure, as well as the module corresponding to the low-level external interrupt device driver, will have their reference counts increased by one until the callout is deregistered.

To remove a callout, call the following with the same arguments as provided during callout registration:

extern void
extint_callout_unregister(struct extint_device *ed,
                          struct extint_callout *ec);

You can remove both active and orphaned callouts in this manner with no distinction between the two.

The callout function must continue to be able to be invoked until the call to extint_callout_unregister completes.