RISCOS.com

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

 

Communications within RISC OS


Introduction

There are some important SWI calls that RISC OS uses to communicate between different parts of itself, or to communicate with application programs. Because these SWI calls are used by lots of different parts of RISC OS, you will find they are referred to in many different places in the manual. It's therefore important that you know of these SWIs to understand such references. Most of the SWIs belong to modules that are described elsewhere in the manual, so we just cross reference them here.

Vectors

OS_CallAVector is used to call the routine(s) on a software vector. This SWI and the calls necessary to add routines to a vector have already been described in the chapter Software vectors.

Service calls

OS_ServiceCall is used to pass a service around modules. Modules can decide whether they wish to provide the service, and if so whether they will then pass the service call on to other modules. A reason code in R1 indicates the type of service. You have already seen some examples of OS_ServiceCall - the reason codes to claim and release FIQs.

This call is fully documented in OS_ServiceCall onwards of the chapter on Modules.

Window manager SWIs

The window manager provides various SWIs that enable it to communicate with window based programs (notably Wimp_Poll); and further SWIs so that programs can communicate with and pass data to each other (notably Wimp_SendMessage).

These calls are all fully documented in the chapter The Window Manager.

Call Backs

CallBacks are routines that are called when RISC OS is threaded out. There are two types:

  • Transient CallBacks are set up using OS_AddCallBack. They are called once only, and may be called when RISC OS is threaded but idle. They might be used by an interrupt handling routine that is unable to do some things itself (eg calling a re-entrant SWI, or performing a long operation that would unacceptably increase interrupt latency), but wishes to have a routine 'called back' later to do these things.
  • Non-transient CallBacks are set up using OS_SetCallBack. They are handled by the CallBack handler; you can replace the default one using OS_ChangeEnvironment.

For full details, see the chapter entitled Program Environment.

UpCalls

The kernel provides the SWI OS_UpCall, which warns applications of particular situations. It is described below.

OS_UpCall
(SWI &33)

Calls that RISC OS makes up to an application to warn of particular situations

On entry

R0 = reason code
Other registers are reason code dependent

On exit

R0 preserved
Other registers are reason code dependent

Interrupts

Interrupt status is unaltered
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

This SWI calls the vector UpCallV. To use UpCalls, you must either claim the vector and install a routine on it (see the chapter entitled Software vectors), or install an UpCall handler (see the chapter entitled Program Environment).

They are called UpCalls because they are calls that RISC OS makes up to an application, rather than calls that the application makes down to RISC OS. They generally occur in the foreground, and are hence different to Events, which occur in the background.

The reason code in R0 may be one of the following:

Code

Meaning

Page

1

Media not present (ie previously used but no longer accessible)

OS_UpCall 1 and 2

2

Media not known (ie not previously used)

OS_UpCall 1 and 2

3

File is being modified

OS_UpCall 3

4

Media search end (ie medium supplied, or operation cancelled)

OS_UpCall 4

6

Task wants to sleep until some termination condition is met

OS_UpCall 6

7

Open pipe has been closed or deleted

OS_UpCall 7

8

Buffer filling (ie free space has become less than threshold)

OS_UpCall 8

9

Buffer emptying (ie free space has become more than threshold)

OS_UpCall 9

10

Stream created

OS_UpCall 10

11

Stream closed

OS_UpCall 11

256

Application is starting

OS_UpCall 256

257

RISC OS would like to move memory

OS_UpCall 257

For full details of each reason code, see the entries on the given pages.

Some of the above are made for information only, others allow the application to take appropriate action (such as to prompt for a missing floppy disc to be inserted in the drive). The caller of the UpCall (normally RISC OS) may then look at any returned state, and decide what action to take next. In many cases it will generate an error if the application has not dealt appropriately with the situation.

Writing code to handle UpCalls

Routines that deal with UpCalls should be viewed as system extensions, and so should only call error-returning SWIs ('X' SWIs).

If a routine installed on the vector does deal with the situation it should intercept the call to the vector, as there is no longer any point informing any other routines or the UpCall handler of the situation. If it cannot deal with the situation it must pass the call on, as another may be able to do so.

Related SWIs

None

Related vectors

UpCallV


OS_UpCall 1 and 2
(SWI &33)

Warns your program that a filing medium is not present (OS_UpCall 1) or not known (OS_UpCall 2)

On entry

R0 = 1 (Media not present) or 2 (Media not known)
R1 = filing system number (see Filing system numbers)
R2 = pointer to a null-terminated medium name string, or -1 if irrelevant
R3 = device number, or -1 if irrelevant
R4 = iteration count for repeated issuing of the call (0 initially)
R5 = minimum timeout period (in centiseconds)
R6 = pointer to a null terminated medium type string

On exit

R0 = 0 if medium changed, -1 if medium no longer required, else preserved
R1 - R6 preserved

Use

This call is made by RISC OS filing systems when a program tries to access:

  • a filing medium that it has previously used but can no longer access (R0 = 1)
  • a filing medium that it has not previously used (R0 = 2).

It calls the UpCall vector.

To use OS_UpCall 1 or 2, you must either claim UpCallV and install a routine on the vector, or install an UpCall handler. Your routine should:

  • prompt you to supply the medium with a string built up using:
    1. the medium type string (passed in R6)
    2. the filing system name (obtained by calling XOS_FSControl 33 acting on the value of R1 - see OS_FSControl 33 for details)
    3. the medium name (passed in R2)

      for example:

      Please insert disc adfs:Mike and press Space (Esc to abort)

  • give you a way of indicating that you have either supplied the medium, or wish to cancel the operation
  • intercept the vector with R0 = -1 if you wish to cancel the operation.
  • intercept the vector with R0 = 0 if the timeout limit is reached, or if you say you have supplied the medium

When you intercept the call to the vector, control passes back to the filing system routine that called OS_UpCall:

  • If R0 = -1, then the routine calls OS_UpCall 4; it then returns an error to say that the medium was not found.
  • If R0 = 0, then the routine checks for you that the medium has been changed and the correct one supplied. If so, it calls OS_UpCall 4; otherwise it just calls OS_UpCall 1 or 2 again, after incrementing R4.

The timeout period in R5 is set to a small value for media that can detect when the medium has been changed (such as floppy disc drives) and to a large value (typically &FFFFFFFF) for other media. In the former case, this means that RISC OS will automatically detect that new medium has been supplied, and check that it is the correct one.

The most common use of OS_UpCall 1 and 2 is to request that a floppy disc is inserted.

Related SWIs

OS_UpCall 4


OS_UpCall 3
(SWI &33)

Warns your program that a file is being modified

On entry

R0 = 3 (Modifying file)
R1 - R7 vary, depending on the value of R9
R8 = filing system information word
R9 = reason code

On exit

All registers preserved

Use

This call warns your program that a file is being modified. The reason code in R9 tells you how:

    R9 Meaning
    0 Saving memory to file
    1 Writing catalogue information
    2 Writing load address only
    3 Writing execution address only
    4 Writing attributes only
    6 Deleting file
    7 Creating empty file
    8 Creating directory
    257 Creating and opening for update
    258 Opening for update
    259 Closing file
    512 Ensuring file's size
    520 Renaming file
    521 Setting attributes

It is made when a program calls one of several SWIs provided by the FileSwitch module:

  • reason codes 0 - 8 are caused by calls to OS_File
  • reason codes 257 - 259 are caused by calls to OS_Find
  • reason codes 512 - 521 are caused by calls to OS_FSControl.

You may find it helpful to examine the documentation of the above FileSwitch SWI calls.

The following general points apply:

  • all strings are null terminated except where specified
  • all object names will already have been expanded by FileSwitch, checked for basic validity, and had filing system prefixes stripped
  • object names will also be canonicalised, except under RISC OS 2.

This UpCall is made before the operation, which may subsequently fail. For example, you may receive a rename UpCall for a locked file, which will subsequently fail to rename (because it's locked). If a filename is invalid for a given operation (eg you try to create a file with a wildcarded leafname) FileSwitch will generate an error, and no UpCall will be generated.

The call is used by the desktop filer to maintain its directory displays. It is provided for information only; if you wish to use this UpCall, you must not intercept it, nor must you alter the contents of any of these registers used to pass parameters:

R9 = 0

Saving memory to file

R1 = pointer to filename
R2 = load address
R3 = execution address
R4 = pointer to start of buffer
R5 = pointer to end of buffer
R6 = pointer to special field (or 0)

R9 = 1

Writing catalogue information

R1 = pointer to filename
R2 = load address
R3 = execution address
R5 = attributes
R6 = pointer to special field (or 0)

R9 = 2

Writing load address only

R1 = pointer to filename
R2 = load address
R6 = pointer to special field (or 0)

R9 = 3

Writing execution address only

R1 = pointer to filename
R3 = execution address
R6 = pointer to special field (or 0)

R9 = 4

Writing attributes only

R1 = pointer to object name
R5 = attributes
R6 = pointer to special field (or 0)

R9 = 6

Deleting file

R1 = pointer to object name
R6 = pointer to special field (or 0)

R9 = 7

Creating empty file

R1 = pointer to filename
R2 = load address
R3 = execution address
R4 = start address
R5 = end address
R6 = pointer to special field (or 0)

R9 = 8

Creating directory

R1 = pointer to directory name
R2 = load address (to be used as timestamp)
R3 = execution address (to be used as timestamp)
R4 = number of entries (0 for default)
R6 = pointer to special field (or 0)

R9 = 257

Creating and opening for update

R1 = pointer to filename
R2 = external handle that file will be given (if successfully opened)
R6 = pointer to special field (or 0)

R9 = 258

Opening for update

R1 = pointer to filename
R2 = external handle that file will be given (if successfully opened)
R6 = pointer to special field (or 0)

R9 = 259

Closing file

R1 = external handle

R9 = 512

Ensuring file's size

R1 = external handle
R2 = size to ensure
R8 = filing system information word

R9 = 520

Renaming file

R1 = pointer to current object name
R2 = pointer to desired object name
R6 = pointer to current special field (or 0)
R7 = pointer to desired special field (or 0)

R9 = 521

Setting attributes

R1 = pointer to object name
R2 = pointer to attribute string (control character terminated)
R6 = pointer to special field (or 0)

Related SWIs

None

OS_UpCall 4
(SWI &33)

Informs your program that a missing filing medium has been supplied, or that an operation involving one has been cancelled

On entry

R0 = 4 (Media search end)

On exit

R0 preserved

Use

This call is made by RISC OS to inform your program that a missing filing medium has been supplied, or that an operation involving one has been cancelled. It is always preceded by call(s) of OS_UpCall 1 or OS_UpCall 2. It calls the UpCall vector.

To use OS_UpCall 4, you must either claim UpCallV and install a routine on the vector, or install an UpCall handler. This call is typically used to remove error messages displayed when OS_UpCall 1 or 2 was first generated.

Related SWIs

OS_UpCall 1 and 2

OS_UpCall 6
(SWI &33)

Informs the TaskWindow module that a task wants to sleep until some termination condition is met

On entry

R0 = 6 (Sleep)
R1 = pointer to poll word (in a global memory area, eg the RMA)

On exit

R0 = 0 if UpCall claimed

Use

This call is made by a task that wants to sleep until some termination condition is met, signalled by the contents of the poll word becoming non-zero. It is not available in RISC OS 2.

Control may return to the task before the poll word becomes non-zero, but is only guaranteed to return if and when the poll word becomes non-zero.

While the task is sleeping other tasks will continue to be polled by the Wimp.

If the termination condition can be recognised externally (ie in another Wimp task or under interrupt) hence causing the poll word to be set non-zero, the calling task should set the poll word to zero on entry. Otherwise the poll word must be non-zero on entry, so that control will return to the calling task after each Wimp Poll.

Note that a task must not use this UpCall if it is not re-entrant, or may have been called by a task which is not re-entrant.

The calling task must be running in a task window. The TaskWindow module intercepts this UpCall; you should not do so yourself. These two restrictions may be removed in future versions of RISC OS.

Related SWIs

OS_UpCall 7

OS_UpCall 7
(SWI &33)

Informs the TaskWindow module that an open pipe has been closed or deleted

On entry

R0 = 7 (Sleep no more)
R1 = pointer to poll word (in a global memory area, eg the RMA)

On exit

R0 preserved if V flag clear
R0 = pointer to error block if V flag set

Use

This call is made by PipeFS if an open pipe is closed or deleted. It is not available in RISC OS 2.

The TaskWindow module then traps this and objects if any of its tasks are currently waiting for the poll word related to that pipe to become non-zero, by returning an error.

This prevents a *Shut command from deleting the workspace which is being accessed by the TaskWindow, which could potentially cause address exceptions.

Related SWIs

OS_UpCall 6

OS_UpCall 8
(SWI &33)

A buffer's free space has become less than its specified threshold

On entry

R0 = 8 (Buffer filling)
R1 = buffer handle
R2 = 0

On exit

All registers preserved

Use

The Buffer Manager issues this call when data is inserted into the specified buffer, and the free space becomes less than its current threshold. For full details of buffer handles and thresholds, see the chapter entitled The Buffer Manager.

This call is never issued under RISC OS 2.

Related SWIs

OS_UpCall 9

OS_UpCall 9
(SWI &33)

A buffer's free space has become greater than or equal to its specified threshold

On entry

R0 = 9 (Buffer emptying)
R1 = buffer handle
R2 = -1

On exit

All registers preserved

Use

The Buffer Manager issues this call when data is removed from the specified buffer, and the free space becomes greater than or equal to its current threshold. For full details of buffer handles and thresholds, see the chapter entitled The Buffer Manager.

This call is never issued under RISC OS 2.

Related SWIs

OS_UpCall 8

OS_UpCall 10
(SWI &33)

Stream created

On entry

R0 = 10 (Stream created)
R1 = device driver's handle
R2 = 0 if created for reception (else created for transmission)
R3 = file handle for stream
R4 = DeviceFS stream handle, as passed to device driver on initialisation

On exit

All registers preserved

Use

DeviceFS issues this call when a stream is created. It serves as a broadcast, and all registers should be preserved. For full details of device handles and streams, see the chapter entitled DeviceFS.

This call is never issued under RISC OS 2.

Related SWIs

OS_UpCall 11

OS_UpCall 11
(SWI &33)

Stream closed

On entry

R0 = 11 (Stream closed)
R1 = device driver's handle
R2 = 0 if closed for reception (else closed for transmission)
R3 = file handle for stream
R4 = DeviceFS stream handle, as passed to device driver on initialisation

On exit

All registers preserved

Use

DeviceFS issues this call when a stream is closed. It serves as a broadcast, and all registers should be preserved. For full details of device handles and streams, see the chapter entitled DeviceFS.

This call is never issued under RISC OS 2.

Related SWIs

OS_UpCall 10

OS_UpCall 256
(SWI &33)

Warns your program that a new application is going to be started

On entry

R0 = 256 (New application)
R2 = proposed Currently Active Object pointer

On exit

R0 = 0 to stop application, else R0 is preserved

Use

This call is made just before a new application is going to be started in the current application space - for example due to a *Run or module command. It calls the UpCall vector.

To use OS_UpCall 256, you must either claim UpCallV and install a routine on the vector (see the chapter entitled Software vectors), or install an UpCall handler (see the chapter entitled Program Environment).

One reason to use this call is so that an application can tidy up after itself before a new one starts, eg removing routines from vectors. Again, see the chapter entitled Program Environment.

Another reason to use this UpCall is to prevent an application from starting. If you don't want the application to start, your routine should set R0 to 0, and intercept the call to the vector. This will cause the error 'Unable to start application' to be given. Otherwise, you must pass the call on with all registers preserved.

Related SWIs

None

OS_UpCall 257
(SWI &33)

Informs your program that RISC OS would like to move memory

On entry

R0 = 257 (Moving memory)
R1 = amount that application space is going to change by

On exit

R0 = 0 to permit memory move, else R0 is preserved
R1 is preserved

Use

This call is made just before OS_ChangeDynamicArea tries to move memory. The call is only made if the currently active object is in the application space. It calls the UpCall vector. By default (if you do not claim the vector) the memory is not moved.

To allow the memory to be moved, you must either claim UpCallV and install a routine on the vector (see the chapter entitled Software vectors), or install an UpCall handler (see the chapter entitled Program Environment). Your routine must shuffle your application's workspace so that the memory move can go ahead. It must then set R0 = 0, and pass on the call to the vector.

Related SWIs

OS_ChangeDynamicArea

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