RISCOS.com

www.riscos.com Technical Support:
Programmer's Reference Manual

 

Events


Introduction

Events are used by RISC OS to indicate that something specific has occurred. These are typically generated using the SWI OS_GenerateEvent when RISC OS services an interrupt. The following events are available:

Number Event type
0 Output buffer has become empty
1 Input buffer has become full
2 Character has been placed in input buffer
3 End of ADC conversion on a BBC I/O expansion card
4 Electron beam has reached last displayed line (VSync)
5 Interval timer has crossed zero
6 Escape condition has been detected
7 RS423 error has been detected
8 Econet user remote procedure has been called
9 User has generated an event
10 Mouse buttons have changed state
11 A key has been pressed or released
12 Sound system has reached the start of a bar
13 PC Emulator has generated an event
14 Econet receive has completed
15 Econet transmit has completed
16 Econet operating system remote procedure has been called
17 MIDI system has generated an event
18 Reserved for use by an external developer
19 Internet has generated an event
20 Reserved for use by an external developer
21 Reserved for use by an external developer
22 Device overrun
23 Reserved for use by an external developer
24 A driver has received a frame for the Internet module
25 A driver has completed an Internet transmission request
26 Reserved for use by Acorn
27 Reserved for use by Acorn
28 Portable BMU has received an event

Note that you may generate events yourself, using event number 9, which is reserved for users. You may also get an allocation of an event number from Acorn if you need one - for example, if you are producing an expansion card that generates events.

Enabling and disabling events

Generating events all the time would use a lot of processor time. To avoid this, events are by default disabled. You can enable or disable each event individually.

To avoid problems with several applications using events at the same time, RISC OS keeps a count for each event. This count is increased each time an event is enabled, and decreased when an event is disabled. Thus disabling an event will not stop it being generated if another program still needs the event.

RISC OS sets all event counts to zero at each reset, although some of its system extension modules may need events, and so immediately increment the counts.

Expansion card modules

If the module that is using events has been loaded from an expansion card, it must behave as follows:

  • enable the event on all kinds of initialisation
  • call OS_Byte 253 on a reset to find out what type it was:
    • if it was a soft reset, enable the event
    • if it was a hard reset or power-on do nothing, as the module will just have been initialised, and so will already have enabled the event
  • disable the event on all kinds of finalisation.

Using events

To use event(s), you must first OS_Claim the event vector EventV. See the chapter entitled Software vectors for further details of vectors. You must then call OS_Byte 14 to enable each of the events you wish to use.

The event routine

When an event occurs, your event routine (that claimed the event vector) is entered. The event number is stored in register R0; other information may be stored in R1 onwards, depending on the event - see below.

The restrictions which apply to interrupt handlers also apply to event handlers - namely, event routines are entered with interrupts disabled, with the processor in a non-user mode. They may only re-enable interrupts if they disable them again before passing on or intercepting the call, and they must ensure that the processing of one event is completed before they start processing another. The use of certain operating system calls must be avoided. For further details see the chapter entitled Restrictions.

Note: Events may not be received in the order in which they are generated.

Finishing with events

When you finish using the events you must first call OS_Byte 13 to disable each event that you originally enabled. You must then OS_Release the event vector EventV.

SWI Calls


OS_Byte 13
(SWI &06)

Disables an event

On entry

R0 = 13
R1 = event number

On exit

R0 preserved
R1 = old enable state
R2 corrupted

Interrupts

Interrupts are disabled
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

This call disables an event by decreasing the count of the number of times that event has been enabled. If the count is already zero, it is not altered. The previous enable state of the event is returned in R1:

R1 = 0 previously disabled
R1 > 0 previously enabled

Note that to disable an event totally, you must use OS_Byte 13 the same number of times as you use OS_Byte 14.

Related SWIs

OS_Byte 14, OS_GenerateEvent

Related vectors

EventV, ByteV


OS_Byte 14
(SWI &06)

Enables an event

On entry

R0 = 14
R1 = event number

On exit

R0 preserved
R1 = old enable state
R2 corrupted

Interrupts

Interrupts are disabled
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

This call enables an event by increasing the count of the number of times that event has been enabled. The previous enable state of the event is returned in R1:

R1 = 0 previously disabled
R1 > 0 previously enabled

When you finish using the vector, you should disable it again by calling OS_Byte 13.

Related SWIs

OS_Byte 13, OS_GenerateEvent

Related vectors

EventV, ByteV


OS_GenerateEvent
(SWI &22)

Generates an event

On entry

R0 = event number
R1... = event parameters

On exit

All registers preserved

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

Note that, as usual, the event vector will only be called if the event number given in R0 has previously been enabled using OS_Byte 14.

Related SWIs

OS_Byte 13, OS_Byte 14

Related vectors

EventV

Details of events

Details of all the events and the values they pass to the event routines are given below.

Output buffer empty event

R0 = 0
R1 = buffer number

This event is generated when the last character has just been removed from an output buffer (e.g. printer buffer, serial port output buffer) which has output empty events enabled, or an attempt is made to remove another character from the buffer once it has been emptied. See the chapter entitled Buffers.

Input buffer full event

R0 = 1
R1 = buffer number (bits 0 - 30) and byte/block operation flag (bit 31):

    bit 31 clear => byte operation - R2 holds byte
    bit 31 set => block operation - R2 points to block of length R3
R2 = byte that could not be inserted into buffer (if byte operation);
    else R2 = pointer to data not inserted (if block operation)
R3 = number of bytes not inserted (if block operation)

This event is generated when an input buffer (which has input full events enabled) is full and when the operating system tries to enter a character into the buffer but fails. See the chapter entitled Buffers.

Block operations do not occur in RISC OS 2, nor do they occur for buffers that are not handled by the buffer manager.

Character input event

R0 = 2
R1 = buffer number (0 for keyboard, or 1 for serial input)
R2 = byte being inserted into buffer

This event is generated when OS_Byte 153 is called to insert any character except Escape into the keyboard buffer, or into the serial buffer when serial input is treated as keyboard input (ie OS_Byte 181 is set to zero). If the character is Escape, then the Escape event is instead generated.

See the chapter entitled Character Input for a description of buffer values for the keyboard buffer.

OS_Byte 153 is called by the keyboard driver to insert keys into the keyboard buffer, and by the serial device driver when it receives a character.

ADC end conversion event

R0 = 3
R1 = channel that just converted

This event is generated when the analogue-to-digital convertor on the BBC I/O expansion card finishes a conversion. See the documentation supplied with the card.

Vertical sync event

R0 = 4

This event is generated when the electron beam reaches the bottom of the displayed area and is about to start displaying the border colour. This event corresponds to the time when the OS_Byte 19 call returns to you. In low-resolution modes this will be every fiftieth of a second; in modes requiring a multisync monitor it will be more frequent.

You could use it, for example, to start a timer which will cause a subsequent interrupt. On this interrupt you could change the screen palette, to display more than the usual number of colours on the screen at once.

Interval timer event

R0 = 5

This event is generated when the interval timer, which is a five-byte value incremented 100 times a second, has reached zero. See OS_Word 3 for details of the interval timer.

The interval timer is obsolescent, since there is only one provided, which is not very useful in a multi-tasking environment. You should instead use OS_CallAfter or OS_CallEvery.

Escape event

R0 = 6

This event is generated either when Esc is pressed, or when an escape condition is received from the RS423 input port and OS_Byte 181 is set to zero. See the chapter entitled Character Input for a discussion of escape conditions.

RS423 error event

R0 = 7
R1 = pseudo 6850 status register shifted right 1 place
R2 = character received

This event is generated when an RS423 error is detected. Such errors are parity errors, framing errors etc. On entry, the bits of R1 have the following meanings:

    Bit Meaning when set
    5 Parity error
    4 Over-run error
    3 Framing error
Econet user remote procedure event

R0 = 8
R1 = pointer to argument buffer
R2 = remote procedure call number
R3 = station number
R4 = network number

This event is generated when an Econet user remote procedure call occurs. See the chapter entitled Econet for further details.

User event

R0 = 9
R1... = values defined by user

This event is generated when you call OS_GenerateEvent with R0=9. The other registers are as set up by you. Note that this is entered in SVC mode, not IRQ mode.

Mouse button event

R0 = 10
R1 = mouse X co-ordinate
R2 = mouse Y co-ordinate
R3 = button state
R4 = 4 bytes of monotonic centi-second value

This event is generated when a mouse button changes, ie when a button is pressed or released. The button state is given in R3 as follows:

    Bit Meaning when set
    0 Right-hand button down
    1 Centre button down
    2 Left-hand button down
Key up/down event

R0 = 11
R1 = 0 for key up, 1 for key down
R2 = key number
R3 = keyboard driver ID

This event is issued whenever a key on the keyboard is pressed or released. The key number, R2, is a low-level internal key number transmitted by the keyboard to the IOC device, and does not relate to other codes used elsewhere. The table below lists the values for each possible key, giving the high and low hex digit of the key code:


Low-level internal key numbers

Where there is some ambiguity, eg the digit keys, it should be clear from referring to the keyboard layout which code refers to which key. The keys are numbered top to bottom, left to right, starting from Esc at the top left corner. 4D is unused on the UK model, but may be used on some other models for an extra key.

Note that the keycodes given in this event bear no relationship to any other code you will see. They are not, for example, related to the INKEY numbers described in the chapter entitled Character Input. They apply to the keyboard supplied on the UK model.

Sound start of bar event

R0 = 12
R1 = 2
R2 = 0

This event is generated whenever the sound beat counter is reset to zero, marking the start of a bar. See the chapter entitled The Sound system for more details.

The 0 in R2 may change in future versions to give the invocation number of the task causing the event.

PC Emulator event

R0 = 13

This event is claimed by the PC Emulator package.

Econet receive event

R0 = 14
R1 = receive handle
R2 = status of completed operation

This event is generated when an Econet reception completes. The status returned in R2 will always be 9 (Status_Received). See the chapter entitled Econet for further details.

Econet transmit event

R0 = 15
R1 = transmit handle
R2 = status of completed operation

This event is generated when an Econet transmission completes. The status returned in R2 can have the following values:

    0 Transmitted
    1 Line jammed
    2 Net error
    3 Not listening
    4 No clock

See the chapter entitled Econet for further details.

Econet OS remote procedure event

R0 = 16
R1 = pointer to argument buffer
R2 = remote procedure call number
R3 = station number
R4 = network number

This event is generated when an Econet operating system remote procedure call occurs. Current remote procedure call numbers are:

    0 Character from Notify
    1 Initialise Remote
    2 Get View parameters
    3 Cause fatal error
    4 Character from Remote

See the chapter entitled Econet for further details.

MIDI event

R0 = 17
R1 = event code

This event is generated when certain MIDI events occur. The values R1 may have are:

    0 A byte has been received when the buffer was previously empty
    1 A MIDI error occurred in the background
    2 The scheduler queue is about to empty, and you can schedule more data.

These events only occur if you have fitted an expansion card with MIDI sockets. See the manual supplied with the card for further details.

Internet event

R0 = 19
R1 = event code
R2 = socket descriptor

This event is generated when certain Internet events occur. The values R1 may have are:

    0 A socket has input waiting to be read
    1 An urgent event has occurred, such as the arrival of out-of-band data
    2 A socket connection is broken.

These events only occur if you are using the Internet module supplied with the TCP/IP Protocol Suite. See the TCP/IP Programmer's Guide for further details.

Device overrun event

R0 = 22
R1 = device driver's handle
R2 = file handle
R3 = 0

This event is generated when the SWI DeviceFS_ReceivedCharacter is called on an unbuffered stream, and the previously received character has not been read. The new character overwrites any previous character.

Internet receive event

R0 = 24
R1 = pointer to data buffer chain containing Rx data
R2 = pointer to name of interface controlled by driver ('et', 'en', etc)
R3 = physical unit number (0 - 3)
R4 = Rx frame type

This event is generated by a driver to indicate to the Internet module that it has received and stored a frame from the network.

This event is not used by DCI4 versions of the Internet module, such as the one in RISC OS 3.6.

Internet transmission status event

R0 = 25
R1 = pointer to data buffer chain containing Tx data
R2 = pointer to name of interface controlled by driver ('et', 'en', etc)
R3 = physical unit number (0 - 3)
R4 = error number (driver specific), or 0 if successful

This event is generated by a driver to indicate to the Internet module that it has completed a transmission request. It does not necessarily imply successful transmission and reception by the target host.

This event is not used by DCI4 versions of the Internet module, such as the one in RISC OS 3.6.

Portable BMU interrupt event

R0 = 28
R1 = status bits for BMU variable 10 (see Variable Read/Write Description)

This event is generated by the Portable module when it receives interrupts from the BMU (battery management unit). You must not claim it yourself. See the chapter entitled The Portable module for further details.

This edition Copyright © 3QD Developments Ltd 2015
Last Edit: Tue,03 Nov 2015