μT-Kernel 2.0 Specification
Prev	μT-Kernel/SM Functions	Next

Interrupt Management Functions

μT-Kernel/SM interrupt management functions are functions for disabling or enabling external interrupt, retrieving interrupt disable status, controlling interrupt controller, etc.

Interrupt handling is largely hardware-dependent, different on each system, and therefore difficult to standardize. The following are given as standard specification, but it may not be possible to follow these exactly on all systems. Implementors should comply with these specifications as much as possible; but where implementation is not feasible, full compliance is not mandatory. If functions not in the standard specification are added, however, the function names must be different from those given here. In any case, DI(), EI(), and isDI() must be implemented in accordance with the standard specification.

Interrupt management functions are provided as library functions or C language macros. These can be called from a task-independent portion and while dispatching and interrupts are disabled.

CPU Interrupt Control

These functions are for CPU external interrupt flag control. Generally they do not perform any operation on the interrupt controller.

DI(), EI(), and isDI() are C language macros.

DI - Disable External Interrupts

C Language Interface

#include <tk/tkernel.h>

DI (UINT intsts );

Parameter

UINT intsts Interrupt Status Variable that stores the CPU external interrupt flag

Return Parameter

None.

Error Codes

None.

Valid Context

Task portion	Quasi-task portion	Task-independent portion
YES	YES	YES

Description

Controls the external interrupt flag in the CPU and disables all external interrupts. Also stores the flag state in intsts before disabling interrupt.

This API is defined as a C language macro and intsts is not a pointer. Write a variable directly.

EI - Enable External Interrupt

C Language Interface

#include <tk/tkernel.h>

EI (UINT intsts );

Parameter

UINT intsts Interrupt Status Variable that stores the CPU external interrupt flag

Return Parameter

None.

Error Codes

None.

Valid Context

Task portion	Quasi-task portion	Task-independent portion
YES	YES	YES

Description

Controls the external interrupt flag in the CPU and reverts the flag state to intsts. That is, this API reverts the flag state to the state before disabling external interrupts by the previously executed DI(intsts).

If the state before executing DI(intsts) was the external-interrupt-enabled, the subsequent EI(intsts) enables external interrupts. On the other hand, if the state was already interrupt-disabled at the time DI(intsts) was executed, interrupt is not enabled by EI(intsts). However, if 0 is specified in intsts, the external interrupt flag in the CPU is set to the interrupt-enable state.

intsts must be either the value saved by DI() or 0. If any other value is specified, the subsequent correct behavior is not guaranteed.

isDI - Get Interrupt Disable Status

C Language Interface

#include <tk/tkernel.h>

BOOL disint = isDI (UINT intsts );

Parameter

UINT intsts Interrupt Status Variable that stores the CPU external interrupt flag

Return Parameter

BOOL disint Interrupt Disabled Status External interrupt disabled status

Error Codes

None.

Valid Context

Task portion	Quasi-task portion	Task-independent portion
YES	YES	YES

Description

Checks the external interrupt flag in the CPU that was stored in intsts by the previously executed DI(), and returns TRUE(a non-zero value) if the flag status is determined as the interrupt-disabled by μT-Kernel/OS, or FALSE otherwise.

intsts must be the value saved by DI(). If any other value is specified, the subsequent correct behavior is not guaranteed.

Example 4. Sample Usage of isDI

void foo()
{
        UINT    intsts;

        DI(intsts);

        if ( isDI(intsts) ) {
                /* Interrupt was already disabled at the time the above DI() was called */
        } else {
                /* Interrupt was enabled at the time the above DI() was called */
        }

        EI(intsts);
}

SetCpuIntLevel - Set Interrupt Mask Level in CPU

C Language Interface

#include <tk/tkernel.h>

void SetCpuIntLevel (INT level );

Parameter

INT level Interrupt Mask Level Interrupt mask level

Return Parameter

None.

Error Code

None.

Valid Context

Task portion	Quasi-task portion	Task-independent portion
YES	YES	YES

Related Service Profile Items

Only when all the service profile items below are set to be effective, this system call can be used.

TK_SUPPORT_CPUINTLEVEL Support for setting and obtaining CPU interrupt priority level

Description

Set interrupt mask level of CPU and disable interrupts that have lower interrupt priority than level. Interrupts that have interrupt priority that is equal to level or higher are enabled.

When INTLEVEL_DI is specified to level, the interrupt mask level within the interrupt controller is set to disable all external interrupts at all priority levels. Generally speaking, this is the same state of the system after DI() is called.

When INTLEVEL_EI is specified to level, the mask level within the interrupt controller is set to enable all external interrupts at all priority levels. Generally speaking, this is the same state of the system after EI(0) is called.

While interrupts are disabled due to the execution of this API, dispatch may be delayed, as in the case of the interrupt handler's being executed, until the interrupts are enabled again.

The range of value that can be specified by level and the concrete value of INTLEVEL_DI are implementation-dependent. The ordering relation of the interrupt level as numeric value and the interrupt priority is implementation-dependent. Generally speaking, the specification about these is decided based on the CPU architecture.

Additional Notes

"Interrupt mask level" is defined to be the lower bound of interrupt priority level (interrupt level) for external interrupts that are enabled (masked). On CPU that can assign priority levels to external interrupts, when external interrupt priority levels are specified as parameters to EnableInt(), those with priorities equal to or higher than the interrupt mask level are enabled. This API sets the interrupt mask level within CPU, and has a similar function as that of SetCtrlIntLevel() which sets the interrupt mask level within the interrupt controller. The former affects the result of interrupt enable/disable setting done by DI(), EI(). The latter has nothing to do with this.

This API sets the interrupt mask level within CPU without regard to the previous setting. Note that there are both cases of either the increase of the disabled interrupts, or the decrease of disabled interrupts after the execution of this API.

Difference from T-Kernel 2.0

This API is a new addition in μT-Kernel 2.0 specification.

Difference from μT-Kernel 1.0

This API is a new addition in μT-Kernel 2.0 specification.

GetCpuIntLevel - Get Interrupt Mask Level in CPU

C Language Interface

#include <tk/tkernel.h>

INT level = GetCpuIntLevel (void );

Parameter

None.

Return Parameter

INT level Interrupt Mask Level Interrupt mask level

Error Code

None.

Related Service Profile Items

Only when all the service profile items below are set to be effective, this system call can be used.

TK_SUPPORT_CPUINTLEVEL Support for setting and obtaining CPU interrupt priority level

Description

Get the current value of interrupt mask level in CPU, and return it as the value of return parameter level.

The range of value that can be specified by level is implementation-dependent.

Additional Notes

See the explanation and additional notes in SetCpuIntLevel.

Difference from T-Kernel 2.0

This API is a new addition in μT-Kernel 2.0 specification.

Difference from μT-Kernel 1.0

This API is a new addition in μT-Kernel 2.0 specification.

Control of Interrupt Controller

These functions control the interrupt controller. Generally they do not perform any operation with respect to the CPU interrupt flag.

	Difference from T-Kernel 2.0
	The use of interrupt vector number (INTVEC) has been abolished, and interrupt number is used instead for functions that accepted INTVEC in the previous specification. With this change, DINTNO macro becomes no longer necessary, and is not included in the specification any more. However, in order to maintain compatibility with T-Kernel 2.0, it is recommended to offer the following DINTNO macro definition. #define DINTNO(intvec) (intvec)

Difference from T-Kernel 2.0

The use of interrupt vector number (INTVEC) has been abolished, and interrupt number is used instead for functions that accepted INTVEC in the previous specification. With this change, DINTNO macro becomes no longer necessary, and is not included in the specification any more. However, in order to maintain compatibility with T-Kernel 2.0, it is recommended to offer the following DINTNO macro definition.

#define DINTNO(intvec)  (intvec)

EnableInt - Enable Interrupts

C Language Interface

#include <tk/tkernel.h>

void EnableInt (UINT intno );

void EnableInt (UINT intno , INT level );

Parameter

UINT	`intno`	Interrupt Number	Interrupt number
INT	`level`	Interrupt Priority Level	Interrupt priority level

Return Parameter

None.

Error Codes

None.

Valid Context

Task portion	Quasi-task portion	Task-independent portion
YES	YES	YES

Related Service Profile Items

TK_HAS_ENAINTLEVEL Interrupt priority level (level) can be specified as the 2nd argument

Only when all the service profile items below are set to be effective, this system call can be used.

TK_SUPPORT_INTCTRL Support of μT-Kernel standard Interrupt Controller functions

Description

Enable interrupt with interrupt number, intno. On a system where interrupt priority level can be specified, level is used to specify the interrupt priority level.

The interrupt number that can be specified in intno is limited to a number that can be usable by tk_def_int and at the same time, an interrupt number that is controlled by the interrupt controller. The subsequent correct behavior of the system as a whole when an invalid intno is specified is not guaranteed.

Either the support of level or the support without level is provided.

Difference from T-Kernel 2.0

The use of interrupt vector number (INTVEC) has been abolished, and interrupt number is used instead for functions that accepted INTVEC in the previous specification.

Difference from μT-Kernel 1.0

This API was not in the older μT-Kernel specification, but, with the introduction of service profile mechanism, this API can now be used when the profile permits it.

DisableInt - Disable Interrupts

C Language Interface

#include <tk/tkernel.h>

void DisableInt (UINT intno );

Parameter

UINT intno Interrupt Number Interrupt number

Return Parameter

None.

Error Codes

None.

Valid Context

Task portion	Quasi-task portion	Task-independent portion
YES	YES	YES

Related Service Profile Items

Only when all the service profile items below are set to be effective, this system call can be used.

TK_SUPPORT_INTCTRL Support of μT-Kernel standard Interrupt Controller functions

Description

Disable interrupt with the interrupt number, intno. Generally speaking, an interrupt that is disabled will become pending and, once it is enabled by EnableInt(), an interrupt is generated. If it is desired to cancel an interrupt condition that became pending because the interrupt was disabled, ClearInt() must be called.

Difference from T-Kernel 2.0

The use of interrupt vector number (INTVEC) has been abolished, and interrupt number is used instead for functions that accepted INTVEC in the previous specification.

Difference from μT-Kernel 1.0

This API was not in the older μT-Kernel specification, but, with the introduction of service profile mechanism, this API can now be used when the profile permits it.

ClearInt - Clear Interrupt

C Language Interface

#include <tk/tkernel.h>

void ClearInt (UINT intno );

Parameter

UINT intno Interrupt Number Interrupt number

Return Parameter

None.

Error Codes

None.

Valid Context

Task portion	Quasi-task portion	Task-independent portion
YES	YES	YES

Related Service Profile Items

Only when all the service profile items below are set to be effective, this system call can be used.

TK_SUPPORT_INTCTRL Support of μT-Kernel standard Interrupt Controller functions

Description

If an interrupt with interrupt number, intno, has been generated, it is cleared.

Difference from T-Kernel 2.0

The use of interrupt vector number (INTVEC) has been abolished, and interrupt number is used instead for functions that accepted INTVEC in the previous specification.

Difference from μT-Kernel 1.0

This API was not in the older μT-Kernel specification, but, with the introduction of service profile mechanism, this API can now be used when the profile permits it.

EndOfInt - Issue EOI to Interrupt Controller

C Language Interface

#include <tk/tkernel.h>

void EndOfInt (UINT intno );

Parameter

UINT intno Interrupt Number Interrupt number

Return Parameter

None.

Error Codes

None.

Valid Context

Task portion	Quasi-task portion	Task-independent portion
YES	YES	YES

Related Service Profile Items

Only when all the service profile items below are set to be effective, this system call can be used.

TK_SUPPORT_INTCTRL Support of μT-Kernel standard Interrupt Controller functions

Description

Issue EOI to Interrupt Controller. intno must identify an interrupt that is the target of EOI. Generally this must be executed at the end of an interrupt handler.

Difference from T-Kernel 2.0

The use of interrupt vector number (INTVEC) has been abolished, and interrupt number is used instead for functions that accepted INTVEC in the previous specification.

Difference from μT-Kernel 1.0

This API was not in the older μT-Kernel specification, but, with the introduction of service profile mechanism, this API can now be used when the profile permits it.

CheckInt - Check Interrupt

C Language Interface

#include <tk/tkernel.h>

BOOL rasint = CheckInt (UINT intno );

Parameter

UINT intno Interrupt Number Interrupt number

Return Parameter

BOOL rasint Interrupt Raised Status External interrupt raised status

Error Codes

None.

Valid Context

Task portion	Quasi-task portion	Task-independent portion
YES	YES	YES

Related Service Profile Items

Only when all the service profile items below are set to be effective, this system call can be used.

TK_SUPPORT_INTCTRL Support of μT-Kernel standard Interrupt Controller functions

Description

Check to see if an interrupt with interrupt number, intno, has been generated. If an interrupt with the interrupt number, intno, has been generated, TRUE (a non-zero value) is returned, and if it has not, then FALSE is returned.

Difference from T-Kernel 2.0

The use of interrupt vector number (INTVEC) has been abolished, and interrupt number is used instead for functions that accepted INTVEC in the previous specification.

Difference from μT-Kernel 1.0

This API was not in the older μT-Kernel specification, but, with the introduction of service profile mechanism, this API can now be used when the profile permits it.

SetIntMode - Set Interrupt Mode

C Language Interface

#include <tk/tkernel.h>

void SetIntMode (UINT intno , UINT mode );

Parameter

UINT	`intno`	Interrupt Number	Interrupt number
UINT	`mode`	Mode	Interrupt mode

Return Parameter

None.

Error Codes

None.

Valid Context

Task portion	Quasi-task portion	Task-independent portion
YES	YES	YES

Related Service Profile Items

Only when all the service profile items below are set to be effective, this system call can be used.

TK_SUPPORT_INTMODE Support for setting interrupt mode

Description

Set the interrupt mode of interrupt specified by intno to mode.

The settable modes and how to specify mode are implementation-dependent. The following is an example of settable modes:

mode := (IM_LEVEL || IM_EDGE) | (IM_HI || IM_LOW)

#define IM_LEVEL        0x0002          /* Level trigger */
#define IM_EDGE         0x0000          /* Edge trigger */
#define IM_HI           0x0000          /* H level/Interrupt at rising edge */
#define IM_LOW          0x0001          /* L level/Interrupt at falling edge */

If invalid mode is specified, the subsequent correct behavior is not guaranteed.

Difference from T-Kernel 2.0

The use of interrupt vector number (INTVEC) has been abolished, and interrupt number is used instead for functions that accepted INTVEC in the previous specification.

Difference from μT-Kernel 1.0

New API introduced based on T-Kernel 2.0 specification

SetCtrlIntLevel - Set Interrupt Mask Level in Interrupt Controller

C Language Interface

#include <tk/tkernel.h>

void SetCtrlIntLevel (INT level );

Parameter

INT level Interrupt Mask Level Interrupt mask level

Return Parameter

None.

Error Code

None.

Valid Context

Task portion	Quasi-task portion	Task-independent portion
YES	YES	YES

Related Service Profile Items

Only when all the service profile items below are set to be effective, this system call can be used.

TK_SUPPORT_CTRLINTLEVEL Support for setting and obtaining interrupt priority level inside interrupt controller

Description

Set interrupt mask level of the interrupt controller and disable interrupts that have lower interrupt priority than level. Interrupts that have interrupt priority that is equal to level or higher are enabled.

When INTLEVEL_DI is specified to level, the interrupt mask level within the interrupt controller is set to disable all external interrupts at all priority levels.

When INTLEVEL_EI is specified to level, the mask level within the interrupt controller is set to enable all external interrupts at all priority levels.

While interrupts are disabled due to the execution of this API, dispatch may be delayed, as in the case of the interrupt handler's being executed, until the interrupts are enabled again.

Additional Notes

"Interrupt mask level" is defined to be the lower bound of interrupt priority level (interrupt level) for external interrupts that are enabled (masked). On CPU that can assign priority levels to external interrupts, when external interrupt priority levels are specified as parameters to EnableInt(), those with priorities equal to or higher than the interrupt mask level are enabled. This API sets the interrupt mask level within interrupt controller, and has a similar function as that of SetCpuIntLevel() which sets the interrupt mask level within the CPU. The former does not affect the result of interrupt enable/disable setting done by DI(), EI() at all. The latter affects the setting.

This API sets the interrupt mask level within interrupt controller without regard to the previous setting. Note that there are both cases of either the increase of the disabled interrupts, or the decrease of disabled interrupts after the execution of this API.