Software vectors

Claiming vectors

When you call a SWI, RISC OS uses the SWI number to decide which routine in the RISC OS ROMs you want. For an ordinary SWI, RISC OS looks up the address of the SWI routine and then branches to it. However, if you call a vectored SWI, it instead gets the address from the corresponding vector that is held in RAM. Normally this would be the address of the standard routine held in ROM.

You can change this address by using the SWI OS_Claim, documented later in this chapter. RISC OS will then instead branch to your own routine, held at the address you pass to OS_Claim.

Your own routine can do one of the following:

• replace the original routine, passing control directly back to the caller
• do some processing before calling the standard routine, which then passes control back to the caller
• call the standard routine, process some of the results it returns, and then pass control back to the caller.

If your routine completely replaces the standard one, it is said to intercept the call; otherwise it is said to pass on the call.

An example

As an example, let's look at the SWI OS_WriteC routine. When RISC OS decodes a SWI with SWI number &00, it knows that you are requesting a write character operation. RISC OS gets an address from a vector - in this case called WrchV - and passes control to the routine.

Now by default, the WrchV contains the address of the standard write character routine in ROM. If you claim the vector using SWI OS_Claim, whenever an OS_WriteC is executed, your own routine will be called first.

Vector chains

So far, we've deliberately been vague about how vectors store the addresses of the routine. In fact, the vector is the head of a chain of structures, which point to the next claimant on the vector, and to both the code and the workspace associated with this claimant. Consequently:

• there may be more than one routine on a given vector
• no claimant has to remember what the previous owner of the vector was
• vectors can be claimed and released by many different pieces of software in any order, not just in a stack-like order.

The routines are called in the reverse order to the order in which they called SWI OS_Claim. The last routine to OS_Claim the vector will be the first one called. If that routine passes the call on, the next most recent claimant will get the call, and so on. If any of the routines on the vector intercept the call, the earlier claimants will not be called.

When not to intercept a vector

There are some vectors which should not be intercepted; they must always be passed on to other claimants. This is because the default owner, ie the routine which is called if no one has claimed the vector, might perform some important action. The error vector, ErrorV, is a good example. The default owner of this vector is a routine which calls the error handler. If you intercept ErrorV, the error handler will never be called, and errors won't be dealt with properly.

Multiply installing the same routine

When SWI OS_Claim adds a routine to a vector, it automatically removes any identical earlier instances of the routine from the chain (ie instances having the same pointer to code, and the same pointer to workspace). If you don't want this to happen, use the SWI OS_AddToVector instead.

Desktop applications

Under an environment such as the desktop, multiple applications are run concurrently. The currently running application is mapped into memory at &8000. Desktop applications periodically return control to the Window Manager (or Wimp) by calling the SWI Wimp_Poll; at this point the Wimp may decide to swap to another application. In doing so, it maps the current application out of the application space, and maps the new application into that space. Thus every application is given the illusion that it is the only one in the system.

If your application has claimed a vector using a routine in its own space, it must obviously release that vector each time it (and the claiming routine) may be swapped out of application space. Before each call your application makes to Wimp_Poll (which is when it may be swapped out), it must call SWI OS_DelinkApplication to remove any claiming routines in application space. When its call to Wimp_Poll returns (and hence it is swapped back in), it must then call SWI OS_RelinkApplication to reclaim those vectors.

Use of registers

If you write a routine that uses a vector, it must obey the same entry and exit conditions as the corresponding RISC OS routine. For example, a routine on WrchV must preserve all registers, just as the SWI OS_WriteC does.

If you pass the call on, you can deliberately alter some of the registers to change the effect of the call. However, if you do so, you must arrange for control to return again to your routine. You must then restore the register values that the old routine would normally have returned, before finally returning control to the calling program. This is because some applications might rely on the returned values being those documented in this manual.

Processor modes

The processor mode in which the routine is entered depends on the vector:

• Routines vectored through IrqV are always executed in IRQ mode.
• Routines vectored through Vectors &10 to &16 ( EventV, InsV, KeyV, RemV, CnpV) and TickerV are generally executed in IRQ mode, but may be executed in SVC mode if called using SWI OS_CallAVector, and in certain other unspecified circumstances.
• All other routines are executed in SVC mode – the mode entered when the SWI instruction is executed.

Returning errors

Routines using most of the vectors can return errors by setting the V flag, and storing an error pointer in R0. The routine must not pass on the call, as one of the parameters (R0) has been changed; this would cause problems for the next routine on the vector. The routine must instead intercept the call, returning control back to the calling program.

You can't do this with all the vectors; some of them (those involving IRQ calls in particular) have nowhere to send the error to.

Returning from a vectored routine

You should use one of two methods to return from a vectored routine. These are described immediately below; for an example, see the example program.

More complex uses of vectors

Sometimes, you may want to do more complex things with a vector, such as:

• preprocessing registers to alter the effect of a standard routine
• postprocessing to change the effect of future calls
• repeatedly calling a routine or group of routines.

There are a number of important things to remember if you are doing so. You must make sure that:

• the vector still looks exactly the same to a program that is calling it, even if it now does different things
• your routine will cope with being called in all the processor modes that its vector uses (for example, SVC or IRQ mode for a routine on InsV)
• the values of R10 and R11 are preserved when earlier claimants of the vector are repeatedly called.

Vector defintions

In most cases, the interrupt status is given as undefined. This is because the vectors may be called either by the SWI(s) which normally use them, many of which ensure a given interrupt status, or by SWI OS_CallAVector, which does not alter the interrupt status.

List of software vectors

The software vectors are listed below. The names of the routines which can cause each vector to be called are in brackets:

All other vectors are currently reserved.

Additional information on software vectors

Many of the vectors are by default used to indirect calls of SWIs, and so the routine they call is the same as that the SWI calls.

An example program

The example program below illustrates all these important points. You can adapt it to write your own routines.

The program claims WrchV, adding a routine that:

• changes the case of the character depending on the state of a flag (preprocessing)
• calls the remaining routines on the vector to write the altered character
• toggles the flag (postprocessing)
• ensures that all registers are set to the values that would be returned by the default write character routine
• returns control to the calling program.

Note that the program releases the vector before ending, even if an error occurs.

DIM code% 100
FOR pass%=0 TO 3 STEP 3
P%=code%
[ OPT pass%
.vectorcode%
; save the entry value, the necessary state for the repeated call,
; and our workspace pointer
STMFD r13!, {r0, r10-r12, r14}


; do our preprocessing; as a trivial example, convert to the current case
LDRB r14, [r12]                     ; pick up upper/lowercase flag
CMP r14, #0                         ; decide which territory manager table to use
LDREQ r1, lowercase_table%
LDRNE r1, uppercase_table%
LDRB r0, [r1, r0]                   ; look up character and put back in r0


; now do the call to the rest of the vector. Since this is WrchV, we know that
; we are in SVC mode; however, the code below will correctly call the rest of
; the vector whatever the mode.

STMFD r13!, {r15}                   ; pushes PC+12, complete with flags and mode
ADD r12, r13, #8                    ; stack contains pc,r0,r10,r11,r12,r14
                                    ; so point at the stacked r10
LDMIA r12, {r10-r12, r15}           ; and restore the state needed to call the
                                    ; rest of the chain (r10 and r11), and
                                    ; “return” to the non-vector claiming address.
                                    ; The load of r12 wastes one cycle.


; we are now at the pc+12 that we stacked; this is therefore where the
; rest of the vector returns to when it has finished.


LDR r12, [r13, #12]                 ; reload our workspace pointer
                                    ; Note that the offset of #12 - and the earlier
                                    ; #8 when we pushed onto the stack - refer to
                                    ; this example only and are not general
                                    ; Note also that the pc we pushed was
                                    ; pulled by the vector claimer.


; we could now do some more processing, set r0 up to another character,
; and loop round to done_preprocess% again; instead, we’ll just do some
; example postprocessing; we’ll toggle our upper/lowercase flag.


LDRB r14, [r12]
EOR r14, r14, #1
STRB r14, [r12]


; now return; if there was no error then intercept the call to the
; vector, returning the original character.


LDMVCFD r13!, {r0, r10-r12, r14, r15}


; could pass the call on instead by omitting r14 from the addresses
; to pull - ie use LDMVCFD r13!, {r0, r10-r12, r15}
; there was an error; set up the correct error pointer, flags, and
; claim the vector.


STR r0, [r13]                       ; save the error pointer
LDMFD r13!, {r0, r10-r12, r14, r15} ; return with V still set, and claim the vector


; reserve space to store the addresses of the territory manager case tables
.lowercase_table%
EQUD 0
.uppercase_table%
EQUD 0
]
NEXT


REM Get addresses of the territory manager case tables
SYS “Territory_LowerCaseTable”,-1 TO !lowercase_table%
SYS “Territory_UpperCaseTable”,-1 TO !uppercase_table%
DIM flag% 1
?flag%=0
WrchV%=3
ON ERROR SYS “XOS_Release”, WrchV%, vectorcode%, flag%: PRINTREPORT$: END
SYS “OS_Claim”, WrchV%, vectorcode%, flag%
REPEAT
  INPUT command$
  OSCLI command$
UNTIL command$=””
SYS “XOS_Release”, WrchV%, vectorcode%, flag%
END