Events Introduction
Programmer's Reference Manuals
» Part 1 - Introduction
» Events
» Introduction
Overview
RISC OS like all other Operating System must be able inform tasks that something specific has occurred so appropriate action can be taken, if required. Each specific event is assigned a number; an event number. These are typically generated by OS_GenerateEvent when RISC OS services an interrupt.
Events are disabled default, which prevents RISC OS from generating events. This is because there is a significant processor overhead involved in generating events. Events can be enabled or disabled individually if required.
For each event number, a counter keeps track of how many requests have been made to enable it. As long as the counter remains above zero, RISC OS will always generate the event when appropriate. An event will only be disabled after equal numbers of disable event and enable event calls have been made (i.e. counter falls to zero). This method ensures that the system always generates the event if at least one task requires it. On reset, the event counters are set to zero, although some modules may need an event and hence increment the appropriate event counter.
In addition to the Operating System generating event numbers, it is also possible for developers to generate their own events too (event code 9), or if required, request their own event code (see Allocate pages).
List of events
A complete list of events available under RISC OS is available here and provides details on their use. As stated above, Event code 9 is assigned for developer use.
Using events
To use an event the following steps must followed:
- The event vector must first be claimed by calling OS_Claim
- Enable the appropriate event(s) by calling OS_Byte 14
The purpose of claiming the vector is to assign a new routine that must be called when the event occurs. Because multiple tasks may claim the same event, the routine is added to the list of routines that must be called. If you wish to add multiple ‘identical’ routines use OS_AddToVector. You may wish to read up on Software Vectors for more information on the use of vectors.
When an event is no longer required the follow steps must be taken:
- Disable the appropriate event(s) by calling OS_Byte 13
- Release the event vector by calling OS_Release
Event handling routines
The routine dealing with the events must do so very quickly, so it can continue with the previous task as quickly as possible. Often, events are handled so quickly that users never realise their task was temporarily halted.
If a routine cannot deal with an event quickly, it should re-enable interrupts (as they are always disabled when entering a routine), but it must then be disabled before passing on or intercepting the call and ensure that the processing of one event is complete before they start processing another.
Please note: The routine is always entered in a non-user processor mode.
Error handling
Routines that handle events must only call the error-returning SWI calls. That is SWI calls that have their X bit set. i.e. either add the value &20000 to the SWI number, or add the letter ‘X’ in front of the SWI name.
If an error is returned to the routine, appropriate action must be taken within the routine. It may be useful to store an error indicator within the routine, so that the next call to an appropriate SWI (one in the module that provides the routine) will generate an error.