The only important registers it does not save are the TBLPTRU/H/L, which you should save/restore if the ISR accesses const data arrays or strings. This can be done using the SAVE_CONTEXT() and RESTORE_CONTEXT() macros as shown below:

These macros take the place of the compiler's equivalent built-in 'save(0)/restore' functions, and if enabled by the '#option _IVT_SAVE_CONTEXT' setting will also save the TBLPTRU/H/L registers.

   SAVE_CONTEXT(priority)    // high or low... change 'priority' to match ISR INTR_PRIORITY... 0=low, 1=high

   SAVE_SYSTEM_CONTEXT(priority)  // high or low... change 'priority' to match ISR INTR_PRIORITY... 0=low, 1=high

SAVE_SYSTEM_CONTEXT allows multiple isr handlers to share the context storage for SF system variables. Since ISR handlers are defined as events, using the traditional 'save(0)' statement in multiple handlers would result in each handler allocating an additional 31 bytes of ram for the system context and additional hdw registers which is unnecessary. SAVE_SYSTEM_CONTEXT is also slightly faster since it does not have to save the additional registers which are saved automatically as part of the hardware shadow registers.

   'SAVE_CONTEXT(priority)            // same as above... change 'priority' to match IRQ priority setting
   'SAVE_SYSTEM_CONTEXT()              // saves SF system variables (and TABLEPTR registers if enabled)
    'SAVE_SYSTEM_CONTEXT(priority)      // same as above... change 'priority' to match IRQ priority setting

   'RESTORE_CONTEXT(priority)          // same as above... change 'priority' to match IRQ priority setting
   'RESTORE_SYSTEM_CONTEXT()          // restores SF system variables (and TABLEPTR registers if enabled)
    'RESTORE_SYSTEM_CONTEXT(priority)  // same as above... change 'priority' to match IRQ priority setting

The IVT is a table of up to 256 entries, one for each IRQ vector number. Each entry is a 16-bit word that contains the address of the interrupt handler for that vector number (more on this later).  The IVT resides in ROM so it must be fixed at compile-time, however you can set the base address of the IVT using the IVTBASEU/H/L registers at run-time. This allows the code to setup multiple IVT tables

The number of available interrupt vectors varies with the device, but it typically ranges from 82 to 128. The IVT must include entries for all interrupt vector numbers up to the highest vector used by your program. Since an IVT entry requires a word value, a complete table of 128 entries requires 128*2 = 256 bytes of ROM space. The max number of IRQs and the IRQ vector number definitions themselves can be found in the device .bas file located in the compiler 'Includes' folder.

The 18F interrupt mechanism can be set to use a single priority for all interrupts or to allow the use of high and low priority setting through the IPEN register flag. The default setting is IPEN = 0 (all interrupts are high-priority), but this can be set using the ENABLE_INTR_PRIORITY() and DISABLE_INTR_PRIORITY() macros. Unless you have the need to allow a high-priority interrupt
to be able to interrupt a running low-priority one, it is recommended to leave the interrupt priority setting at its default setting and just use a single priority.

If interrupt priority is enabled then each interrupt can be assigned as either low (priority=0) or high (priority=1). The individual priorities for each IRQ are set using INTR_PRIORITY(irq_no, priority), which defaults to high-priority if left unchanged. INTR_PRIORITY() sets/clears the respective bit in the IPRx register for the given irq_no.

There are two levels of hardware shadow registers for saving context: one for high-priority interrupts (priority=1) and one for low-priority interrupts (priority=0) In addition to the program counter (PC), the hardware context automatically saves the registers:
  STATUS, WREG, BSR, FSR0/1/2, PRODL/H and PCLATH/U

The only important registers it does not save are the TBLPTRU/H/L, which you should save/restore if accessing const data or strings in the ISR. This can be done using the SAVE_CONTEXT() and RESTORE_CONTEXT() macros as shown below:

       SAVE_CONTEXT()                     // high-priority

There are three different implementations of SAVE_CONTEXT/RESTORE_CONTEXT, and their usage depends on the global INTR_PRIORITY enable setting...
    SAVE_CONTEXT()            // high-priority
    SAVE_CONTEXT(priority)    // high or low... change 'priority' to match IRQ priority setting (0 or 1)
    SAVE_CONTEXT_ISS()        // use run-time Interrupt State Status from INTCON1 (uses more code)

SAVE_CONTEXT_ISS can determine the priority state at runtime, but it will generate more code and is slower. This might be useful where the interrupt priority for a handler is dynamically changed and not fixed at compilation.

If the ISR uses system library functions or calls other routines you may also need to save the system library variables and/or the frame context. This can be done using 'save/restore' statement blocks just as with traditional interrupts.

The only restriction with using a traditional save/restore block is that it must be used outside of any SAVE_CONTEXT/RESTORE_CONTEXT macros.

   // define interrupt entry point
    ENTER_INTR_HANDLER(handler_name)    // change 'handler_name' to match 'public event' name

   // save SF system variable context (if req'd, must be before SAVE_CONTEXT)
   save(0)

    // save TABLEPTR registers (if req'd, for const data/string access)
    SAVE_CONTEXT(priority)              // change 'priority' to match IRQ priority setting (0 or 1)

   // clear IF
   INTR_REQ(irq_no, 0)                // chnage 'irq_no' to match intr vector number
   
   // restore TABLEPTR (if saved above)
    RESTORE_CONTEXT(priority)          // high/low... change 'priority' to match... 0=low, 1=high

    // restore SF system variable context (if saved above)
    restore

Due to the manner in which the IVT is setup, there must be an entry in the table for every IRQ number, even if the interrupt is unused. To simplify this, the IVT.bas module defines a default_interrupt_handler() routine which is used by CREATE_IVT when the vector table database
is initialized. The default_interrupt_handler() will perform a device reset for any unhandled interrupt requests. This is all done automatically, so nothing further needs to be done by the user.

// ivt.bas contains a default_intr_handler() routine which is defined by default
// set '#option _IVT_DEFAULT_HANDLER = false' to override the default routine in ivt.bas
// and use our own local routine

// our local default_intr_handler()

The PIC18 interrupt structure is managed using two settings: each peripheral has its own interrupt enable bit located in the PIEx registers, and the global interrupt enable bit GIE (or GIE and GIEL if using interrupt priorities).

!!!Example 2 - two interrupts, low and high priority w/context save

// IRQ_TMR1

// IRQ_TMR3 (low-priority w/context save example)

   // save SF system variable context (must be before SAVE_CONTEXT)
    save(0)
    // save TABLEPTR registers
    SAVE_CONTEXT(LOW_PRIORITY)

   // restore TABLEPTR registers
   RESTORE_CONTEXT(LOW_PRIORITY)
   // restore SF system variable context
    restore

ENABLE_INTR_PRIORITY()

// - two IVT tables
// - replace default_intr_handler

// ivt.bas contains a default_intr_handler() routine which is enabled by default
// if you wish to override that routine with your own handler, then:
//  - set '#option _IVT_DEFAULT_HANDLER = false'
//  - define a replacement event 'public event default_interrupt_handler()' routine
//  - add at least one reference to the new routine between CREATE_IVT/END_IVT using
//      SET_IVT_HANDLER(<unused irq_no>, default_interrupt_handler)
//    if you add it first then it doesn't matter what irq_no you use

// set this option true to test using the default handler

// override the default_intr_handler() in ivt.bas with our own local routine

   LED = 1

   LED = 0

// common handler for both tmr1 and tmr3 (using vector table 2)

   // WREG contains the interrupt number

// enable and generate IRQ=UNUSED_IRQ

INTR_REQ(UNUSED_IRQ, 1)      // generate intr (should go to default_handler)

// test TMR1 and TMR3 interrupts

// - LED should go ON for 1/2 sec then OFF for 1 sec
// let it run for 10 secs

// repeat forever...

The 'enable()/disable()' keywords used in traditional interrupts are replaced by the ENABLE_INTERRUPT()/DISABLE_INTERRUPT() macros.

   SAVE_CONTEXT(priority)              // change 'priority' to match IRQ priority setting... 0=low, 1=high

   SAVE_CONTEXT(priority)    // high or low... change 'priority' to match IRQ priority setting... 0=low, 1=high

   SAVE_CONTEXT()            // high-priority only

Many new 18F devices include a Vectored Interrupt Controller (VIC) module, available on the XV18 core devices. Vectored Interrupts bring new enhancements to the interrupt scheme used in current 18F designs, improving speed and flexibility.

These interrupt vectors are located in low memory at $0008 and $0018, and are fully supported in Swordfish
using the Enable, Disable, and Interrupt statements. See the Users Manual/online Help section on Interrupts for more details.

When an interrupt occurs, the processor uses the interrupt vector number 0-255 as an index into the IVT. It retrieves the word address from the table, shifts it left by 2 (multiplying it by 4), and branches to that address. Why does it shift the address? The IVT holds a 16-bit word, which only allows a value up to 64K. Multiplying the word address from the table by 4 allows the vector to point to up to 256K bytes of code address space.

Many new 18F devices include a Vectored Interrupt Controller (VIC) module, available on the XV18 core devices.
Vectored Interrupts bring new enhancements to the interrupt scheme used in current 18F designs, improving speed
and flexability.

Also, check out the article "PIC 18F Interrupts in Swordfish" https://www.sfcompiler.co.uk/wiki/pmwiki.php?n=SwordfishUser.Interrupts by RadioT for some additional tips.

One of the issues with the two-vector approach is once you have more than two interrupts you must begin to add code
to detect which peripheral is generating the interrupt request. This adds additional latency and complexity to the ISR.

In this case, saving and restoring the interrupt context becomes much more challenging. It also means that you have to move the
interrupt routine to outside the .bas module that uses it since you likely have to reference three different source modules,
breaking the modular approach used in existing Swordfish modules.

Vectored interrupt mode departs from the traditional scheme. While it still provides for two interrupt priorities (high and low),
the interrupt priority no longer sets the vector address as it does in legacy mode. Instead, each interrupt source is assigned its own individual vector number, from 0 to 255.
This allows interrupts to have a unique ISR handler so you no longer need code like the above to check the IF and IE flags.
Since ISRs are no longer shared among modules, you can move the interrupt handler code back into the .bas module that uses it.
This is all accomplished through the Interrupt Vector Table (IVT). Vectored interrupts are enabled via the Multi-Vector Enable bit (MVECEN)
in the config setting. For compatability with existing Swordfish modules, the device include file for XV18 core devices sets MVECEN off
so by default interrupts operate in traditional legacy mode.

The IVT is a table of up to 256 entries, one for each IRQ vector number. Each entry is a 16-bit word that contains the address (more on this later)
of the interrupt handler for that vector number.  The IVT resides in ROM so it must be fixed at compile-time, however you can
set the base address of the IVT using the IVTBASEU/H/L registers at run-time. This allows the code to setup mutiple IVT tables

When an interrupt occurs, the processor uses the interrupt vector number 0-255 as an index into the IVT. It retrieves the word address from the table,
shifts it left by 2 (multiplying by 4), and branches to that address. Why does it shift the address? The IVT holds a 16-bit word, which only allows a value up to 64K.
Multiplying the word address from the table by 4 allows the vector to point to up to 256K bytes of code address space.

The downside to this is that the ISR code MUST be located on a 4-byte address boundary, but Swordfish has no built-in mechanism to enforce this restriction.
The ENTER_INTR_HANDLER() macro will add padding to the start of the interrupt handler routine if needed to adjust the value used
to set the IVT entry point, making it compatible with the word-length address entry requirement.

The number of available interrupt vectors varies with the device, but it typically ranges from 82 to 128. The IVT must include entries
for all interrupt vector numbers up to the highest vector used by your program. Since an IVT entry requires a word value,
a complete table of 128 entries requires 128*2 = 256 bytes of ROM space. The max number of IRQs and the IRQ vector number definitions
themselves can be found in the device .bas file located in the compiler 'Includes' folder.

This new module contains macros and routines that can be used to setup and manage the IVT and interrupts when using vectored interrupts.
Replacements for the standard Enable, Disable, and Interrupt statements are provided and must be used in place of these original functions when
operating in VIC mode. Including IVT.bas will automatically set the MVECEN config setting to ON, enabling multi-vectored mode.
Before we look at creating an IVT, let's look at the required format for an ISR interrupt handler.

Interrupt handlers replace the traditional 'interrupt' routines, and must be declared using the 'event' attribute.
They should follow the basic format:

ENTER_INTR_HANDLER will make any required adjustments to the code offset and will set the interrupt entry point.
This marks the first executable statement in the handler, so you cannot use variable declarations that include an initializer since they would be skipped.

Before exiting the ISR you should clear the source of the interrupt request. This can be done using the INTR_REQ() macro as
shown above to set the IF flag to 0.

EXIT_INTR_HANDLER() will perform a 'RETFIE 1', restoring the hardware context and reenabling interrupts.

The 18F interrupt mechanism can be set to use a single priority for all interrupts or to allow the use of high and low priority setting
through the IPEN register flag. The default setting is IPEN = 0 (all interrupts are high-priority), but this can be set
using the ENABLE_INTR_PRIORITY() and DISABLE_INTR_PRIORITY() macros. Unless you have the need to allow a high-priority interrupt
to be able to interrupt a running low-priority one, it is recommended to leave the interrupt priority setting at its default setting.

If interrupt priority is enabled then each interrupt can be assigned as either low (priority=0) or high (priority=1).
The individual priorities are set using INTR_PRIORITY(irq_no, priority), which defaults to high-priority if left unchanged.
INTR_PRIORITY() sets/clears the respective bit in the IPRx register for the given irq_no.

There are two levels of hardware shadow registers for saving context, one for high-priority interrupts (priority 1) and one for low-priority interrupts (priority 0)
In addition to the program counter (PC), the hardware context automatically saves the registers:

The only important registers it does not save are the TBLPTRU/H/L, which you should save/restore if accessing const data or strings in the ISR.
This can be done using the SAVE_CONTEXT() and RESTORE_CONTEXT() macros as shown below:

SAVE_CONTEXT_ISS can determine the priority state at runtime, but it will generate more code and is slower.
This might be useful where the interrupt priority for a handler is dynamically changed and not fixed at compilation.

If the ISR uses system library functions or calls other routines you may also need to save the system library variables
and/or the frame context. This can be done using 'save/restore' statement blocks just as with traditional interrupts.

To create an interrupt vector table in program memory you first use CREATE_IVT(), then add a series of SET_IVT_HANDLER() entries
for every IRQ used by your program, and finally mark the end of the table using END_IVT().

CREATE_IVT(table_name) is used to initialize the vector table database settings and assign a unique name to the table.

Assigning a name to the table does two things: it provides a table name which is used when programming the IVTBASE registers,
and also allows you to have multiple tables and switch between them at run-time. The SET_IVTBASE(table_name) macro will load the
registers with the address of the specified table_name.

SET_IVT_HANDLER() updates the vector table database for an individual IRQ with the address of an interrupt handler.
The format for adding a handler is SET_IVT_HANDLER(irq_no, event_handler), where 'irq_no' is 0-255 (or one of the IRQ_xxx consts
from the device file), and 'event_handler' is the name assigned to the event routine by ENTER_INTR_HANDLER (ie 'tmr1_handler').

This example shows the creation of two tables. In the second table TMR1 and TMR3 share the same interrupt handler rouitne.

Due to the manner in which the IVT is setup, there must be an entry in the table for every IRQ number, even if the interrupt is unused.
To simplify this, the IVT.bas module defines a default_interrupt_handler() routine which is used by CREATE_IVT when the vector table database
is initialized. The default_interrupt_handler() will perform a device reset for any unhandled interrupt requests.
This is all done automatically, so nothing further needs to be done by the user.

You can override the default interrupt handler and provide your own routine if desired. To do this, set '#option _IVT_DEFAULT_HANDLER=false'
and create a public event routine named 'default_interrupt_handler()'. When you create the IVT, you must register the routine using SET_IVT_HANDLER.
If you list default_interrupt_handler first then the irq_no used is unimportant, and your routine will now be used for all unspecified interrupts.

The PIC18 interrupt structure is managed using two settings: each peripheral has its own interrupt enable bit located in the PIEx registers,
and the global interrupt enable bit GIE (or GIE and GIEL if using interrupt priorities).

INTR_ENABLE(vector_no, val) is used to set/clear the individual PIEx interrupt enable mask register bit, where 'vector_no' is the number of the IRQ (can be one of the constants from the device file),
and 'val' is the PIRx bit setting... '0' disables the interrupt, and '1' enables the interrupt.

while ENABLE_INTERRUPT(priority)/DISABLE_INTERRUPT(priority) can be used for either GIE or GIEL depending on the 'priority' value setting...
0=GIEL (low-priority) and 1=GIE (high-priority). You can also use the LOW_PRIORITY/HIGH_PRIORITY constant values.