@CHIP-RTOS C Library - RTOS API

RTX_Install_RTI_Hook

This function installs a callback function which executes periodically within the 1000 Hz (default rate) Real-Time Interrupt (RTI).

void RTX_Install_RTI_Hook (
                 RTI_HOOK vector,
                 unsigned char delay  )

Parameters

vector

Far pointer to callback procedure to be invoked from within 1000 Hz RTI.   Set this argument to NULL to remove a callback.

typedef unsigned char huge (far * RTI_HOOK ) (void) ;

delay

Number of 1000 Hz RTI before first call.   Set to 1 for callback on very next RTI.   Set to 0 for 256 RTI later.

Return Value

-- none --

Comments

External interrupts are masked and then restored to their state on entry.

The term 'tick' used here refers to a 1 millisecond period when the system timer RTI is operated at its default rate of 1000 Hz.   Note that this RTI rate can be configured to higher rates with the [TIMER] RTI setting in the CHIP.INI, in which case tick time will be under 1 millisecond.

The callback function is free to use any register except for the DS and DI registers.   These two registers must be preserved.

This API was provided for applications which require a precise and variable timing for high frequency front end hardware sampling, for example.

The least significant byte of the callback’s return value (AL register) will be used as the delay count in milliseconds to the next callback.   Examples (assuming 1000Hz RTI):

• Return 1 to execute again on very next RTI, 1 millisecond later.
  
• Return zero for a delay of 256 milliseconds.
  
• Return 5 to execute at a 200 Hz rate.
  

The system supports only a single RTI hook.   Installing a second overwrites the first.   A callback can be removed by installing a NULL callback vector.

Unlike with the RTX timer callback functions, which execute after a task switch to the kernel task, this RTI hook executes directly in the context of the interrupt.   No task switch occurs prior to the callback and execution proceeds on the stack of what ever task was interrupted.   Consequently the callback should be conservative with its stack space usage.

This interrupt has been registered with the RTX kernel, so the user is free to use the task triggering RTX API functions from within the callback such as:

RTX_Wakeup_Task
RTX_Resume_Task
RTX_Signal_Sem
RTX_Signal_Events
RTX_Send_Msg

However any time consuming activity must be avoided and it is not legal to call any RTOS API which could block or result in current task being suspended.   As a rough guideline, the dwell within this callback should be held to under 50 us.   Either very carefully written C code, or assembly code is recommended here.

As true for any installed callback function, it is essential that an application program remove its RTI hook callback (vector set to zero) before program termination.

See Also

RTX_Install_Timer                

RTOS API

This library function invokes a RTOS software interrupt. Refer to this RTOS API function's documentation for more details.

Related Topics

RTX API   Overview

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V1.11	V1.00

Supported by @CHIP-RTOS C Library since version

CLIB
V2.08