Implementing interrupts

eLua interrupt support implementation

To add interrupt support for an eLua platform follow the steps below:

Define your interrupts

Your interrupt sources should be defined in platform_conf.h with macros (don’t use C enumerations). The first one should have the value ELUA_INT_FIRST_ID
(defined in inc/elua_int.h), the next one ELUA_INT_FIRST_ID + 1 and so on. Also, there should be a definition for a macro called INT_ELUA_LAST that must be equal to the largest
interrupt source value. An example is given below:

The actual implementation of the interrupt handlers is of course platform specific, so it can stay in the platform.c file. However, since interrupt handlers might require quite a bit
of code, it is recommended to implement them in a separate file. The eLua convention is to use the platform_int.c file for this purpose. For each interrupt defined in step 1 above, 3
functions need to be implemented:

A function that enables or disables the interrupt and returns its previous state (enabled or disabled).

A function that checks if the interrupt is enabled or disabled.

A function that checks the interrupt pending flag and optionally clears it.

These functions are defined in inc/elua_int.h, which also defines an "int descriptor" type:

platform_int.c must have an array of elua_int_descriptor types named elua_int_table (remember to make it const to save RAM). The elements of this array must be in the same
order as the interrupt sources. The interrupt table for the example from step 1 above might look like this:

platform_int.c should implement a function named platform_int_init (defined in inc/platform.h) that must initialize all the required hardware and the internal data structures of
the interrupt subsystem. This function should be called from platform_init.

Implement the interrupt handlers

There are two simple requirements for the interrupt handlers: clear the hardware interrupt flag (if needed) and call cmn_int_handler (src/common.c) to connect the handler with the
eLua interrupt code. An example is given below:

That’s it. If you followed all these steps correctly, your platform should be fully able to support interrupt handlers (as described here). Check the lpc24xx
platform implementation (src/platform/lpc24xx) for a full example.

Interrupt list and naming conventions

To ensure maximum portability and correct system behaviour, interrupt names (as defined in platform_conf.h) must follow a well-defined naming pattern. Please note that this isn’t
merely a convention, many times the names must be properly chosen for the system to work properly. For example, the timer interrupt match will never happen on virtual timers if the
timer interrupt match name isn’t INT_TMR_MATCH (see here for more details on how to use the timer match interrupt).

The naming rule is that the interrupt name must have the format INT_<peripheral>_<type>_, where:

peripheral is a symbolic name of the peripheral to which the interrupt applies.

type is a symbolic name of the interrupt type.

This restriction applies only to interrupt names. The value associated with the interrupt name (as defined in platform_conf.h) can vary from platform to platform, as long as
it follows the rules outlined in step 1 above.

The table below lists all the valid interrupt names currently known to eLua. If you add a new interrupt don’t forget to update the table below.