Interrupts

To use the functions described in this page, the file <hal.h> should be included.

Even though in JSLK interrupts are handled by each platform's HAL, some features are still shared. The header <hal.h> must be included to make use of the functions described below.

Interrupt handlers

Interrupt handlers are divided in two, a low level handler and a high level handler. The low level handler is defined by the kernel and applies to all interrupts (except for IRQ's which have a different handler). The high level handler can be defined by the kernel or a third party and are specific to each interrupt number but can be reused. To register an interrupt handler the following function can be used:

int registerInterruptHandler(uint8_t num, hiHand_t handler, ...)

Special types

hiHand_t: A pointer type to a high level handler function.

typedef void (*hiHand_t)(regs_t)

Arguments

uint8_t num: The interrupt number where the handler will be registered.

hiHand_t handler: The high level handler for the interrupt.

Optional arguments will be explained in a later section.

Return value

Returns 0 if successful

Note: Unless they are chained, there can only be one high level handler registered per interrupt.

Finding a free interrupt

In order to find a free interrupt (one without a handler) the following function can be used:

uint8_t findFreeInterrupt()

Return value

Returns the number of a free interrupt as an uint8_t.

Unregistering an interrupt handler

When having a handler registered is not required, it's a good practice to free the interrupt that was in use. This can be done through the following function:

int clearInterrupt(uint8_t num)

Arguments

uint8_t num: The number of interrupt to be freed.

Return value

Returns 0 if successful

Chaining interrupts

Every interrupt can be chained in JSLK. This means that an interrupt can have multiple handlers, and when it's called, every handler will be executed in the order it was registered. To chain an interrupt, call registerInterruptHandler() and specify the interrupt number you want your handler to be chained to and pass the CHAINED_INTERRUPT flag as an optional argument.

Note: If an interrupt number is locked or protected, you won't be able to chain a handler to it.

Protecting interrupts

If you have registered an interrupt and want to protect it from other handlers to be chained, you can specify the CHAIN_PROTECT flag when registering the interrupt. If you want to add chained handlers before protecting it, the CHAIN_LOCK flag can be set when registering the last chained handler. To protect an interrupt from being freed, the FREE_PROTECT flag can be used.

Generating interrupts

To force an interrupt to be fired, the following function can be used:

void genInterrupt(uint8_t num)

Arguments

uint8_t num: The interrupt number to fire.

Enabling / disabling interrupts

To enable or disable interrupts, the following function can be used:

uint8_t _interrupts(mode_t mode)

Arguments

mode_t mode: An on or off value.

Sample code

sample.c

#include <hal.h>

_interrupts(on);  // Switch on interrupts

_interrupts(off); // Switch off interrupts

Note: It is not considered a good practice to switch interrupts on or off to perform atomic operations. See Timers and other primitives for more.