|
www.riscos.com Technical Support: |
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.
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.
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.
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.
CallBacks are routines that are called when RISC OS is threaded out. There are two types:
For full details, see the chapter entitled Program Environment.
The kernel provides the SWI OS_UpCall, which warns applications of particular situations. It is described below.
Calls that RISC OS makes up to an application to warn of particular situations
R0 = reason code
Other registers are reason code dependent
R0 preserved
Other registers are reason code dependent
Interrupt status is unaltered
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
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) | |
|
2 |
Media not known (ie not previously used) | |
|
3 |
File is being modified | |
|
4 |
Media search end (ie medium supplied, or operation cancelled) | |
|
6 |
Task wants to sleep until some termination condition is met | |
|
7 |
Open pipe has been closed or deleted | |
|
8 |
Buffer filling (ie free space has become less than threshold) | |
|
9 |
Buffer emptying (ie free space has become more than threshold) | |
|
10 |
Stream created | |
|
11 |
Stream closed | |
|
256 |
Application is starting | |
|
257 |
RISC OS would like to move memory |
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.
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.
None
UpCallV
Warns your program that a filing medium is not present (OS_UpCall 1) or not known (OS_UpCall 2)
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
R0 = 0 if medium changed, -1 if medium no longer required, else preserved
R1 - R6 preserved
This call is made by RISC OS filing systems when a program tries to access:
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:
for example:
Please insert disc adfs:Mike and press Space (Esc to abort)
When you intercept the call to the vector, control passes back to the filing system routine that called OS_UpCall:
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.
Warns your program that a file is being modified
R0 = 3 (Modifying file)
R1 - R7 vary, depending on the value of R9
R8 = filing system information word
R9 = reason code
All registers preserved
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:
You may find it helpful to examine the documentation of the above FileSwitch SWI calls.
The following general points apply:
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:
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)
Writing catalogue information
R1 = pointer to filename
R2 = load address
R3 = execution address
R5 = attributes
R6 = pointer to special field (or 0)
Writing load address only
R1 = pointer to filename
R2 = load address
R6 = pointer to special field (or 0)
Writing execution address only
R1 = pointer to filename
R3 = execution address
R6 = pointer to special field (or 0)
Writing attributes only
R1 = pointer to object name
R5 = attributes
R6 = pointer to special field (or 0)
Deleting file
R1 = pointer to object name
R6 = pointer to special field (or 0)
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)
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)
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)
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)
Closing file
R1 = external handle
Ensuring file's size
R1 = external handle
R2 = size to ensure
R8 = filing system information word
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)
Setting attributes
R1 = pointer to object name
R2 = pointer to attribute string (control character terminated)
R6 = pointer to special field (or 0)
None
Informs your program that a missing filing medium has been supplied, or that an operation involving one has been cancelled
R0 = 4 (Media search end)
R0 preserved
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.
Informs the TaskWindow module that a task wants to sleep until some termination condition is met
R0 = 6 (Sleep)
R1 = pointer to poll word (in a global memory area, eg the RMA)
R0 = 0 if UpCall claimed
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.
Informs the TaskWindow module that an open pipe has been closed or deleted
R0 = 7 (Sleep no more)
R1 = pointer to poll word (in a global memory area, eg the RMA)
R0 preserved if V flag clear
R0 = pointer to error block if V flag set
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.
A buffer's free space has become less than its specified threshold
R0 = 8 (Buffer filling)
R1 = buffer handle
R2 = 0
All registers preserved
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.
A buffer's free space has become greater than or equal to its specified threshold
R0 = 9 (Buffer emptying)
R1 = buffer handle
R2 = -1
All registers preserved
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.
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
All registers preserved
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.
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
All registers preserved
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.
Warns your program that a new application is going to be started
R0 = 256 (New application)
R2 = proposed Currently Active Object pointer
R0 = 0 to stop application, else R0 is preserved
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.
None
R0 = 257 (Moving memory)
R1 = amount that application space is going to change by
R0 = 0 to permit memory move, else R0 is preserved
R1 is preserved
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.