RT_Register (changes)

Showing changes from revision #0 to #1: Added | Removed | Changed

RTSupport

» SWI Calls

» RT_Register

RT_Register

(SWI &575C0)

Register a routine with the RTSupport module

Interrupts

• Interrupts are disabled
• Fast interrupts are enabled

Processor Mode

• Processor is in SVC mode

Re-entrancy

• SWI is re-entrant

Use

This SWI adds a new routine to the list of routines to potentially be executed each time the interrupt dispatcher is unthreaded (but before transient and non-transient callbacks are executed, if the dispatcher is returning to USR mode). Each routine remains registered until removed by a call to RT_Deregister, but it may sleep for a time by use of a pollword. It is recommended that if it is known that a routine will sleep for an extended time, that a Deregister/Register pair should be used instead, to reduce cache thrashing during interrupt handling (when the RTSupport module has to check all possible pollwords).

Each time the RTSupport module gains control of the CPU, it scans its list of routines in decreasing priority order for routines that are unblocked (ie where the pollword is non-zero). If a real-time routine was interrupted, then routines of a higher priority are executed, followed by the interrupted routine, and then equal and lower priority routines are examined. (However, note that if and only if routines have their priorities changed dynamically, it is possible that while a routine is executing, a second routine at the same priority level may be in a pre-empted state.) If the RTSupport module encounters two unblocked routines at the same priority level, then the calling order is undefined.

The routines are called as follows:

So for example the routine may be implemented as

• Assembler, with the static data referenced using R12 as is conventional in RISC OS.
• C code interfaced directly, as long as R10 and R13_sys are set up to describe a standard stack chunk with the reserved words at its base set up to enable static data relocation, for example by copying them from the base of the SVC stack prior to the RT_Register call:

_kernel_stack_chunk *chunk = calloc(1, CHUNK_SIZE);
chunk->sc_mark = 0xF60690FF;
chunk->sc_size = CHUNK_SIZE;
memcpy(chunk + 1, _kernel_current_stack_chunk() + 1, 28);
_kernel_swi_regs r = { /* ... */ .r[5] = ((int) chunk) + 560,
                       .r[6] = ((int) chunk) + CHUNK_SIZE, /* ... */ };
_kernel_swi(RT_Register, &r, &r);

Here is an example callback-model routine written in C that repeatedly sleeps for a second at a time (assuming the default pollword is never set):

typedef struct {
  unsigned int flags;
  unsigned int *pollword;
  unsigned int timeout;
} routine_result_t;

__value_in_regs routine_result_t MyRoutine(void *r0) {
  unsigned int time;
  _swix(OS_ReadMonotonicTime, _OUT(0), &time);
  return (routine_result_t) { 1 << 2, NULL, time + 100 };
}

• C code interfaced via a veneer: if you want to be able to call _kernel_raise_error() and functions which rely upon it like exit(), abort() and assert(), which assume the outermost stack frame was called as a function returning a _kernel_oserror *, or for use as a threading library where actions need to be taken when the thread exits (eg unblocking joining threads) you will need an assembler veneer to the C code, to patch the r14_sys the C code sees on entry with a pointer to a suitable cleanup function.

The priority passed in R7 can be an integer from 1 (lowest priority) to 255 (highest priority). Priority 0 is reserved for the exclusive use of the foreground process. However, it is preferred that a string pointer be used instead: the string is used to look up a priority in the file RTSupport:Priorities. This enables easy tuning of priority levels for a given system, without the need for each real-time component to be individually configurable. For example, the file might be as follows:

Critical:224
AudioFill:192
VideoPaint:160
Normal:128
AudioDecode:96
VideoDecode:64
Coroutine:32

Notes

If the routines pollword is nonzero at the time the routine is registered, and the routine is at a higher priority than the current context, then RT_Register will attempt to yield to the routine straight away. This also opens up the possibility for the routine to deregister itself before the RT_Register call returns.

See also

• RT_Deregister