cpct_setInterruptHandler

Sets a user provided function as new interrupt handler.

C Definition

void cpct_setInterruptHandler ( void (*intHandler)(void) )

Input Parameters (2 Bytes)

Assembly call

call cpct_setInterruptHandler_asm

Parameter Restrictions

• intHandler (HL) can theoretically be any 16-bit value.  However, it must point to the start of a function that will be called at each interrupt.  If it points to somewhere else, undefined behaviour will happen.  Most probably, the program will crash as random code will be executed (that placed at the provided address).  User defined function (intHandler) must not return any value nor accept any parameters.

Details

It modifies the interrupt vector to establish a new interrupt handler that calls user provided function.  The user must provide a pointer to the function (intHandler) that will handle interrupts.  This function does not call intHandler or check it in any way.  It just sets it for being called at the next interrupts.  Provided intHandler function must not return any value nor accept any parameter.

This function creates wrapper code to safely call user provided intHandler.  This code saves registers on the stack (AF, BC, DE, HL and IX) and restores them after user code from intHandler finishes.  Therefore, user does not have to worry about saving registers.  However, be very careful if you modify the alternate set of registers (AF’, BC’, DE’, HL’) as they will not be saved by default.  User is responsible for saving and restoring the values on the alternate register set whenever they are modified.  Otherwise, behaviour is undefined when returning from the function.

Destroyed Register values

A, HL

Required memory

40 bytes (17 bytes function + 23 bytes for safe interrupt wrapper code)

Time Measures

• This first measure is the time required for cpct_setInterruptHandler to execute: that is, the time for setting up the hook for the system to call user defined code.

Case | microSecs (us) | CPU Cycles
-------------------------------------
Any  |      23        |    92
-------------------------------------

• This second measure is the time overhead required for safely calling user defined function.  That is, time required by the wrapper code to save registers, call user’s intHandler, restoring the registers and returning.  This overhead is to be assumed each time interrupt handler is called, so up to 6 times per frame, 300 times per second.

Case      | microSecs (us) | CPU Cycles
------------------------------------------
Overhead  |      58        |    184
------------------------------------------