17.2.3 __ISR Macros

The <sys/attribs.h> header file provides macros intended to simplify the application of attributes to interrupt functions. There are also vector macros defined in the processor header files. (See the appropriate header file in the compiler’s /pic32mx/include/proc directory.)

__ISR(V, IPL)

Use the __ISR(v, IPL) macro to assign the vector-number location and associate it with the specified IPL. This will place a jump to the interrupt handler at the associated vector location. This macro also applies the nomips16 attribute since PIC32 devices require that interrupt handlers must use the MIPS32 instruction set.

The following example creates an interrupt handler function for the core timer interrupt that has an interrupt priority level of two. The compiler places a dispatch function at the associated vector location. To reach this function, the core timer interrupt flag and enable bits must be set, and the interrupt priority should be set to a level of two. The compiler generates software context-saving code for this handler function.

#include <xc.h>
#include <sys/attribs.h>
void __ISR(_CORE_TIMER_VECTOR, IPL2SOFT) CoreTimerHandler(void);

The example below creates an interrupt handler function for the core software interrupt 0 that has an interrupt priority level of three. The compiler places a dispatch function at the associated vector location. To reach this function, the core software interrupt flag and enable bits must be set, and the interrupt priority should be set to a level of three. The device configuration fuses must assign Shadow Register Set 1 to interrupt priority level three. The compiler generates code that assumes that register context will be saved in SRS1.

#include <xc.h>
#include <sys/attribs.h>
void __ISR(_CORE_SOFTWARE_0_VECTOR,IPL3SRS) CoreSoftwareInt0Handler(void);

The example below creates an interrupt handler function for the core software interrupt 1 that has an interrupt priority level of zero. The compiler places a dispatch function at the associated vector location. To reach this function, the core software interrupt 1 flag and enable bits must be set, and the interrupt priority should be set to a level of zero. The compiler generates code that determines at run time whether software context saving is required.

#include <xc.h>
#include <sys/attribs.h>
void __ISR(_CORE_SOFTWARE_1_VECTOR, IPL0AUTO) CoreSoftwareInt1Handler(void);

The next example is functionally equivalent to Example 14-4. Because the IPL specifier is omitted, the compiler assumes IPL0AUTO.

#include <xc.h>
#include <sys/attribs.h>
void __ISR(_CORE_SOFTWARE_1_VECTOR) _CoreSoftwareInt1Handler(void);

__ISR_AT_VECTOR(v, IPL)

Use the __ISR_AT_VECTOR(v, IPL) to place the entire interrupt handler at the vector location and associate it with the software-assigned interrupt priority. Application code is responsible for making sure that the vector spacing is set to accommodate the size of the handler. This macro also applies the nomips16 attribute since ISR functions are required to be MIPS32.

The following example creates an interrupt handler function for the core timer interrupt that has an interrupt priority level of two. The compiler places the entire interrupt handler at the vector location. It does not use a dispatch function. To reach this function, the core timer interrupt flag and enable bits must be set, and the interrupt priority should be set to a level of two. The compiler generates software context-saving code for this handler function.

#include <xc.h>
#include <sys/attribs.h>
void __ISR_AT_VECTOR(_CORE_TIMER_VECTOR, IPL2SOFT) CoreTimerHandler(void);

INTERRUPT-VECTOR MACROS

Each processor-support header file provides a macro for each interrupt-vector number (for example, /pic32mx/include/proc/p32mx360f512l.h. See the appropriate header file in the compiler install directory). When used in conjunction with the __ISR() macro provided by the sys\attribs.h header file, these macros help make an Interrupt Service Routine easier to write and maintain.

The example below creates an interrupt handler function for the Timer 1 interrupt that has an interrupt priority level of seven. The compiler places a dispatch function at the vector location associated with macro _TIMER_1_VECTOR as defined in the device-specific header file. To reach this function, the Timer 1 interrupt flag and enable bits must be set, and the interrupt priority should be set to a level of seven. For devices that allow assignment of shadow registers to specific IPL values, the device Configuration bit settings must assign Shadow Register Set 1 to interrupt priority level seven. The compiler generates code that assumes that register context will be saved in SRS1.

#include <xc.h>
#include <sys/attribs.h>
void __ISR (_TIMER_1_VECTOR, IPL7SRS) Timer1Handler (void);