This function attaches a C interrupt function, fn, to the interrupt selected by sel. Multiple handlers may be attached to the same interrupt, but there is no way to detach a handler from an interrupt.
sel is a CPU interrupt number, not an interrupt source number. Diamond runs with the hardware default mapping of CPU interrupts to interrupt sources as set out in the TI C6000 processor documentation; at present, there is no way to configure a different mapping. If you are attaching to an external interrupt line (EXTINT4—EXTINT7) you should make sure that you have claimed this interrupt for your own exclusive use. Some Diamond implementations reserve an external interrupt line to manage interprocessor communications. This is described in Reserved Hardware Resources.
fn is a pointer to your handler function. If you choose to write this function in C, it must be declared with the interrupt keyword. User-defined handlers are entered with interrupts globally disabled (GIE cleared) and a return address in the IRP register. This matches the requirements of code generated by the C compiler for interrupt functions.
sp points to the start of a stack area of size bytes provided by the caller. Before entering the handler, the kernel sets the stack pointer (register B15) to the end of this area, which must remain valid for as long as the interrupt can occur. Therefore it is usually, but not necessarily, allocated from static storage. Using a separate stack for interrupt handlers means that ordinary threads don’t have to worry about allocating enough stack space for any interrupt handlers that may be invoked while they are executing.
size is the length, in bytes, of the interrupt handler stack pointed to by sp. It must be large enough to accommodate the stack frames of the handler and any functions it calls. Note that if a C interrupt function calls any other functions, including i_sema_signal or i_event_set (see later), the C compiler generates code to save all registers on entry to the function and restore them on exit. This can be costly.
c6xint_attach_fn returns a non-zero value if the operation fails or zero if it succeeds. It calls malloc to allocate a structure describing the handler and its stack, so it may fail if the heap is full.
For example, to attach a handler to CPU interrupt 15 (interrupt source TINT1 in the default mapping):
#include <c6xint.h>
char handler_stack[2048];
void interrupt handler(void) {
...
}
main() {
c6xint_attach_fn(15, handler, handler_stack, sizeof(handler_stack));
. . .
}
|