Previous

Next

Function RTInstallSharedIRQHandlerEx

RTInstallSharedIRQHandlerEx installs a high level interrupt handler on the specified IRQ and enables interrupts for that IRQ:

typedef int (RTTAPI * RTIntHandlerEx)(void * Parameter); 

void RTInstallSharedIRQHandlerEx(int            IRQ, 
                                 RTIntHandlerEx HighLevelHandler, 
                                 void         * Parameter);

Parameters

IRQ

Interrupt Request which triggers the interrupt. Must be in the range 0 .. 31.

HighLevelHandler

Pointer to a function to be called when the interrupt occurs. HighLevelHandler should be a normal C/C++ or Pascal function with one pointer parameters.

Parameter

Value to be passed to the HighLevelHandler when the interrupt occurs. This value may be NULL.

RTInstallSharedIRQHandlerEx can be used to installs up to 32 high level handlers. Several handlers can be installed on the same IRQ, for example, for PCI devices sharing the same IRQ or when independent software modules must be notified of the same interrupt. It is not required nor recommended to call RTEnableIRQ after calling RTInstallSharedIRQHandlerEx. RTInstallSharedIRQHandlerEx calls it internally, if required.

When the hardware interrupt occurs, HighLevelHandler(Parameter) is called with interrupts enabled. The handler may temporarily disable interrupts (though this should usually not be necessary), but it must always return with interrupts enabled. The handler must not call RTIRQEnd. The handler may not call any non-reentrant run-time system functions or any functions which may cause a blocking task switch in a multithreaded environment. The handler cannot make any assumptions about its stack context and should not use more than about 256 bytes of stack space.

For PCI or other interrupt sharing devices, the handler should not blindly assume that its device has triggered the interrupt. Rather, the handler should retrieve all pending interrupt conditions of the device and handle them all. If no interrupt conditions are set, it should return value 0 immediately to allow other handlers for the same IRQ to be invoked.

If the handler returns a value > 0, it is assumed that the interrupt has been handled and other handlers for the same IRQ are not called. If the handler returns 0, the next handler for the same IRQ is called (if any is installed). This algorithm requires that handlers for edge triggered interrupts (ISA devices, for example) must always return 0. Handlers for level triggered interrupts (PCI devices) may return a value > 0 if the handled device had any interrupt conditions set.

Internally, RTInstallSharedIRQHandlerEx uses RTSetTrapVector and RTEnableIRQ to install a low-level interrupt handlers the first time it is called for a specific IRQ. This internal low-level handler saves all required CPU registers, sets up segment registers DS and ES, clears the CPU direction flag, and then calls the high level handlers for the current IRQ previously installed with RTInstallSharedIRQHandlerEx. After all handlers have been called, RTIRQEnd is called, all registers are restored, and the handler returns using the IRETD instruction.

If the total number of installed high level handlers exceeds 32, the program is aborted with an error message.

RTKernel-32 contains the same API function. Software using RTInstallSharedIRQHandlerEx to install its hardware interrupt handlers is portable to On Time RTOS-32 applications with or without RTKernel-32.

RTInstallSharedIRQHandlerEx is the preferred method for applications to install hardware interrupt handlers. Please refer to demo program SerInt for a complete example. Additional information about interrupt handling is also available in section Installing Hardware Interrupt Handlers.

Function RTIRQEnd

Function RTInstallSharedIRQHandler