Delete me: RTSupport Module API Specification (Rev #2, changes)

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

RTSUPPORT MODULE API SPECIFICATION
==================================

The RTSupport module provides facilities supporting real-time code, at a
priority just below that of the interrupt dispatch system, and above that
of any SWIs being handled by the foreground application. Multiple priority
levels are supported, so routines with tighter timing constraints can
pre-empt other real-time routines. Code can be designed either using a
callback model (where the system makes a function call to your entry point)
or using a thread model (where the rest of the system gets CPU time while
your thread sleeps).

Code typically executes in system (SYS) mode and has its own SYS and SVC
stacks, and it may call SWIs (but only re-entrant SWIs) without preventing
higher-priority routines from executing. There is no automatic time-slicing
of routines; it is assumed that the application takes responsibility for
ensuring that the system is not overloaded (although there is a relief valve
to cope with overloaded systems, which ensures that the foreground process
gets a little CPU time at least a few times per second).

Possible future enhancements:
* Per-routine option of maintaining a floating point context for the routine
  (traps would need to be disabled while real-time routines execute)
* Per-routine data storage (for example to support C++ exception handling)
* Reusing spare stack frames in the IRQ stack when nearing overflow (useful
  for timeslicing schemes)
* The facility to recache the priority lookup file after module
  initialisation


                                                        RT_Register
                                                       (SWI &575C0)

Register a routine with the RTSupport module

On entry
  R0 = flags (reserved, should be zero)
  R1 = pointer to default entry point for routine
  R2 = handle to pass in R0 to routine
  R3 = handle to pass in R12 to routine
  R4 = default pointer to pollword for routine
  R5 = initial value of R10 for routine
  R6 = initial value of R13_sys for routine
  R7 = initial priority for routine: integer between 1-255, or a pointer to
       a string

On exit
  R0 = RTSupport module's handle for this routine
  All other registers are preserved

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:

  On entry:
    R0      = contents of R2 when registered
    R10     = first time, this is contents of R5 when registered;
              subsequently, it is preserved from the previous call
    R11     = 0 (to support C code)
    R12     = contents of R3 when registered
    R13_sys = first time, this is contents of R6 when registered;
              subsequently, it is preserved from the previous call
    R13_svc = first time, this is the top of an 8K stack based at a megabyte
              boundary (the same logical address is used for all real-time
              routine SVC stacks, but it differs from the SVC stack address
              used by the foreground process); subsequently, it is preserved
              from the previous call
    R14_sys = return address (only needed if using the callback model)
    SYS mode
    First time, IRQs and FIQs enabled;
    subsequently IRQ disable state is preserved
    Other registers undefined
    Static relocation offsets at base of SVC stack are undefined

  On exit:
    R0      = flags:
              bit 0 set => rescan all higher priority routines (for example,
                           if this routine unblocked a semaphore that a
                           higher priority routine may be sleeping on)
                           otherwise rescan all equal priority routines,
                           including this routine, before descending
              bit 1 set => R1 contains new pollword pointer (otherwise the
                           pollword given at registration is used)
              bit 2 set => R2 contains a monotonic time after which control
                           should be returned even if the pollword is not
                           set
              bit 3 set => R14_sys contains the address to enter next time
                           (otherwise the address used at registration is
                           re-entered)
              other bits are reserved and will currently be zero
    R1      = pollword pointer (if R0 bit 1 is set)
    R2      = timeout monotonic time (if R0 bit 2 is set)
    R10     = value to use at next entry
    R13_sys = value to use at next entry
    R13_svc = value to use at next entry
    R14_sys = next entry point (if R0 bit 3 is set)
    SYS mode, IRQs enabled or disabled, FIQs enabled
    SVC stack may be non-empty
    Processor flags, R1-R9 (except where used to return parameters), R11,
    R12 and R14_svc may be corrupted

  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>