Privileged System Mode Calls l 8
Return 64
Deallocates a 64-byte
OS9 F$Ret64 103E 31 block of memory
Entry Conditions:
A
= block number
X = address of the base page
Error Output:
CC = carry set on error
B = error code (if any)
Additional Information:
0
See
the
Allocate 64
system call for more
information.
8-101
OS-9 Technical Reference
Set
Process DAT
Copies all or part of
Image
the DAT image into a
process descriptor
F$SetImg 103E 3C
Entry Condition:
A = starting image block number
B = block count
X = process descriptor pointer
U = new image pointer
Error Output:
CC = carry set on error
B = error
code (if any)
Additional Information:
0
While copying part or all of the DAT image, this system
call also sets an image change flag in the process descrip
tor. This flag guarantees that as a process returns from
the system call. The call updates the hardware to match
the new process DAT image.
The support module for this call is OS9p1.
8-102
Privileged System Mode Calls l 8
Set P
rocess Task
Writes to the hardware
DAT Registers
DAT registers
F$SetTsk 103E 41
Entry Conditions:
X = pointer to process descriptor
Error Output:
CC = carry set on error
B = error code (if
any)
Additional Information:
This system call sets the process task hardware DAT regis
ters, and clears the image change flag in the process
descriptor. It also writes to DAT RAM the process's seg
ment address information.
· The support module for this call is OS9p1.
8-103
OS-9 Technical Reference
System Link
F$SLink 103E 34
Adds a module from
outside the current
address space into
current address space
Entry Conditions:
A = module type
X = module name string pointer
Y = name string DAT image pointer
Exit Conditions:
A
B
X
Y
U
module type
module revision (if no error)
updated name string pointer
module entry point
module pointer
Error Output:
CC = carry set on error
B
= error code (If
an error occurs)
Additional Information:
0
The I/O System uses the System Link call to link into the
current process's address space those modules specified by a
device name in a user call. User calls such as Create File
and Open Path use this System Link.
0
The support module for this call is OS9p 1.
s-104
Privileged System Mode Calls / 8
Request System
Memory
OS9 F$SRqMem 103E 28
Entry Conditions:
D = byte count
Exit Conditions:
U = starting address of the memory area
D = new memory size
Error Output:
CC = carry set on error
B = error code (if
any)
Additional Information:
Allocates a block of
memory of the
specified size from the
top of available RAM
The Request System Memory call rounds the size request
to the next page boundary.
This call allocates memory only for system address space.
8-105
OS-9 Technical Reference
Return System
Deallocates a block of
Memory
contiguous pages
OS9 F$SRtMem 103E 29
Entry Conditions:
U = starting address of memory to return;
must point to an
even page boundary
D = number of bytes to return
Error Output:
CC = carry set on error
B = error code (if
any)
Additional Information:
~ Register U must point to an even page boundary.
~ This call deallocates memory for system address space only.
8-106
Privileged System Mode Calls / 8
Set SVC
Adds or replaces a
OS9 F$SS.~ vc 103E 32 system call
Entry Conditions:
Y = address of the system call
initialization table
Error Output:
CC = C bit set
B = error code
Additional Information:
· Set SVC adds or replaces a system call, which you have
written, to OS-9's user and system mode system call tables.
· Register Y passes the address of a table, which contains the
function codes and offsets, to the corresponding system call
°handler routines. This table has the following format:
Relative Use
Address
$00
Function Code
4-
First entry
$01 Offset From Byte 3
$02 To Function Handler
$03 Function Code Second entry
$04 Offset From Byte 6
$05 To Function Handler
More Entries
4-
More entries
$80
4-
End-of-table mark
8-107
OS-9 Technical Reference
If the most significant bit of the function code is set, OS-9
updates the system table.
If the most significant bit of the function code is not set,
OS-9 updates the system and user tables.
The function request codes are in the range $29-$34. IO
calls are in the range $80-$90
To use a privileged system call, you must be executing a
program that resides in the system map and that executes
The system call handler routine must process the system
call and return from the subroutine with an RTS
The handler routine might alter all CPU registers (except
Register U passes the address of the register stack to the
system call handler as shown in the following diagram:
Relative Name
Address
U CC $00 R$CC
$01 R$D
A $01 R$A
B $02 R$B
DP $03 R$DP
X $04 R$X
Y $06 R$Y
U $08 R$U
PC $OA R$PC
Codes $70-$7F are reserved for user definition.
8-108
Privileged System Mode Calls l 8
Store A Byte
Stores A at O,X in
rIn
A Task
Task B
F$STABX 103E 4A
Entry Conditions:
A = byte to store
B = destination
task
number
X = logical destination
address
Error Output:
CC = carry set on error
B = error code (if any)
Additional Information:
· This system call is similar to the assembly language
instruction "STA O,X". The difference is that in the system
call, X refers to an address in the given task's address
space, instead of the current address space.
t The support module for this system call is OS9p1.
8-109
OS-9 Technical Reference
Install virtual
interrupt
OS9 F$VIRQ 103E 27
Entry Conditions:
Installs a virtual
interrupt handler
routine
D
X
initial count value
0 to delete entry
1 to install entry
address of 5-byte packet
Error Output:
CC = carry set on error
B = appropriate error code
Additional Information:
Install VIR(a for use with devices in the Multi-Pak Expan
sion Interface. This call is explained in detail in Chapter 2.
8-110
Privileged System Mode Calls / 8
Validate Module
OS9 F$VModul 103E 2E
Checks the module
header parity and CRC
bytes of a module
Entry Conditions:
D = DAT image pointer
X = new module block offset
Exit Conditions:
U = address of the module directory entry
Error Output:
CC = carry set on error
B = error code
(if any)
Additional Information:
0
If the values of the specified module are valid, OS-9
searches the module directory for a module with the same
name. If one exists, OS-9 keeps in memory the module that
has the higher revision level. If both modules have the save
revision level, OS-9 retains the module in memory.
OS-9 Technical Reference
Get Status System Calls
You use the Get Status system calls with the RBF manager sub
routine GETSTA. The OS-9 Level Two system reserves function
Codes 7-127 for use by Microware. You can define Codes 128-255
and their parameter-passing conventions for your own use. (See
the sections on device drivers in Chapters 4, 5, and 6.)
The Get Status routine passes the register stack and the speci
fied function code to the device driver.
Following are the Get Status functions and their codes.
SS.OPT
(Function code $00). Reads the option section of the path
descriptor, and copies it into the 32-byte area pointed to by Reg
ister X
Entry Conditions:
A = path number
B = $00
X = address to receive status packet
Error Output:
CC = carry set on error
B = error code
(if any)
Additional Information:
0
Use SS.OPT to determine the current settings for editing
functions, such as echo and auto line feed.
8-112
System Calls / 8
SS.RDY
(Function code $O1). Tests for data available on SCF-supported
devices
Entry Conditions:
A
B
path number
$01
Exit Conditions:
If the device is ready:
CC = carry clear
B = $00
If the device is not ready:
CC = carry set
B = $F6 (E$SRNDY)
Error Output:
CC = carry set
B = error
code
SS.SIZ
AC-TA P
~'.~C A1. s o
('o ThE
Y ~,! °
6 S' tS
S S· IeQ SAY
it P7vlrAr a4(
BY7Es
Cc = c L Cr 41?
B Eiv~
~i,P6A*ora ypA.W.oD
oftd.E
ad
(Function code $02). Gets the current file size on a RBF-sup
ported devices only
Entry Conditions:
A = path number
B = $02
Exit Conditions:
X = most significant 16 bits of the current ale size
U = least significant 16 bits of the current file size
Error Output:
CC = carry set on error
B = error code
(if any)
8-113
OS-9 Technical Reference
SS.POS
(Function code $05). Gets the current file position (RBF-sup
ported devices only)
Entry Conditions:
A = path number
B = $05
Exit Conditions:
X = most significant 16 bits of the current file position
U = least significant 16 bits of the current file position
Error Output:
CC = carry set on error
B = error code (if any)
SS.EOF
(Function code $06). Tests for the end of the file (EOF)
Entry Conditions:
A = path number
B = $06
Exit Conditions:
If there is no EOF:
CC =carry clear
B = $00
If there is an EOF:
CC =carry set
B = $D3 (E$EOF)
Error Output:
CC =carry set
B = error code
8-114
System Calls / 8
SS.DevNm
(Function Code $OE). Returns a device name
Entry Conditions:
A = path
number
B = $OE
X = address
of
32 -byte buffer for name
Exit Conditions:
X = address of buffer, name moved to buffer
SS.DSTAT
(Function code $12). Returns the display status
Entry Conditions:
A = path
number
B = $12
Exit Conditions:
A = color
code
of
the pixel at the cursor address
X = address
of
the graphics display memory
Y = graphics cursor address; X = M
SB, Y = LSB
Additional Information:
0
This function is supported only the the VDGINT module
and deals with VDG-compatible graphics screens. See
SS.AAGBf for information regarding Level Two operation.
8-115
OS-9 Technical Reference
SS.JOY
(Function code $13). Returns the joystick values
Entry Conditions:
A = path number
B = $13
X = joystick number
0 = (right joystick)
1 = (left joystick)
Exit Conditions:
A = fire button down
0 = none
1 = Button 1
2 = Button 2
3 = Button 1 and Button 2
X = selected joystick x value (0-63)
Y = selected joystick y value (0-63)
A = fire
button status
$FF = fire button is on
$00 = fire button is off
8-116
System Calls l 8
SS.A1faS
(Function code $1C). Returns VDG alpha screen memory
information
Entry Conditions:
A = path number
B = $1C
Exit Conditions:
A = caps lock status
$00 = lower case
$FF = upper case
X = memory
address of
the buffer
Y = memory
address of
the cursor
Additional Information:
0
SS.A1faS
maps the screen into the user address space. The
call requires a full block of memory for screen mapping.
This call is only for use with VDG text screens handled by
i- VDGINT.
~ The support module for this call is VDGINT.
Warning: Use extreme care when poking the screen, since
other system variables reside in screen memory. Do not
change any addresses outside of the screen.
8-117
OS-9 Technical Reference
SS.Cursr
(Function code $25). Returns VDG alpha screen cursor
information
Entry Conditions:
A = path number
B = $25
Exit Conditions:
A = character code of the character at the current cursor
address
X = cursor X position (column)
Y = cursor Y position (row)
Additional Information:
· SS.Cursor returns the character at the current cursor posi
tion. It also returns the X-Y address of the cursor relative
to the current device's window or screen. SS.Cursor works
only with text screens.
· The support module for this call is VDGINT.
8-118
System Calls / 8
(Function code 26). Returns the window or screen size
Entry Conditions:
A
B
path number
$26
Exit Conditions:
number of columns on screenlwirulow
number of rows on screen/window
Additional Information:
· Use this call to determine the size of an output screen. The
values returned depend on the device in use:
For non-CCIO devices, the call returns the values follow
ing the XON/XOFF bytes in the device descriptor.
For CCIO devices, the call returns the size of the window
or screen in use by the specified device.
For window devices. the call returns the size of the cur
rent working area of the window.
· The support modules for this call are VDGINT, GrfInt, and
WindInt.
8-119
OS-9 Technical Reference
SS.KySns
(Function code $27). Returns key down status
Entry Conditions:
A = path number
B = $27
Exit Conditions:
A = keyboard scan information
Additional Information:
0
Accumulator A returns with a bit pattern representing
eight keys. With each keyboard scan, OS9 updates this bit
pattern. A set bit (1) indicates that a key was pressed since
the last scan. A clear bit (0) indicates that a key was not
pressed. Definitions for the bits are as follows:
Bit Key
0
SHIFT
1
CTRL
or
CLEAR
2
ALT
or CE
3
0
(up arrow)
4
0
(down arrow)
5
C]
(left arrow)
6 F:i:l
(right arrow)
7 Space Bar
The bits can be masked with the following equates:
SHIFTBIT equ %00000001
CNTRLBIT equ %00000010
ALTERBIT equ %00000100
UPBIT equ %00001000
DOWNBIT equ %00001000
LEFTBIT equ %00100000
RIGHTBIT equ %01000000
SPACEBIT equ % 10000000
0
The support module for this call is CC310.
8-120
System Calls / 8
SS.Comst
(Function code
$28). Return serial port configuration
information
Entry Conditions:
A = path number
B = $28
Exit Conditions:
Y = high byte: parity
low byte: baud rate
(See the Setstat call SS.ComSt for values)
Error Output:
CC = carry set on error
B = error
code
(if any)
Additional Information:
0
The SCF manager uses this call when performing an
SS.Opt Getstat on an SCF-type device. User calls to
SS.ComSt do not update the path descriptor. Use the
SS.OPT Getstat call for most applications, because it auto
matically updates the path descriptor.
8-121
OS-9 Technical Reference
SS.MpGPB
(Function code $84). Maps the Get/Put buffer into a user
address space
Entry Conditions:
A = path number
B = $84
X = high byte: buffer group number
low byte: buffer number
Y = action to take
1 = map buffer
0 = unmap buffer
Exit Conditions:
X = address of the mapped buffer
Y = number of bytes in buffer
Error Output:
CC = carry set on error
B = error
code (if any)
Additional Information:
· The support modules for this call are GrfTnt and WindInt.
· SS.MpGPB maps a Get/Put buffer into the user address
space. You can then save the buffer to disk or directly mod
ify the pixel data contained in the buffer. Use extreme care
when modifying the buffer so that you do not write outside
of the buffer data area.
8-122
System Calls / 8
SS.MnSel
(Function code $87). Requests that the high-level menu handler
take control of menu selection
Entry Conditions:
A = path
number
B = $87
Exit Conditions:
A = menu
ID
(if valid selection)
0 (if invalid selection)
B = item
number of menu
(if valid selection)
Error Output:
CC = carry set on error
B = error
code (if
invalid selection)
Additional Information:
· After detecting a valid mouse click (when the mouse is
pointing to a control area on a window), a process needs to
call SS.MnSel. This call tells the enhanced window inter
face to handle any menu selection being made.
If
accumula
tor A returns with 0, then no selection has been made. The
calling process needs to test and handle other returned
values.
· A condition where Register A returns a valid menu ID
number and Register B returns 0 signals the selection of a
menu with no items. The application can now take over and
do a special graphics pull down of its own. The menu title
remains highlighted until the application calls the
SS.UMBar SetStat to update the menu bar.
· The support module for this call is WindInt.
8-123
OS-9 Technical Reference
SS.Mouse
(Function code $89). Gets mouse status
Entry Conditions:
A = path
number
B = $89
X = data storage area address
Y = mouse port select:
0 = automatic selection
1 = right side
2 = left side
Exit Conditions:
X = data storage area address
Error Output:
CC = carry set on error
B = error code (if any)
V~ ~ I~ I~f ~ ~ ~
T
k ~ ~Z ~
~' Y ?`~s I~ ~rwEE
p l'. T `a ~`~ ~ ~ T. *'r`To
8-124
System Calls / 8
Additional Information:
0
SS.Mouse returns information on the current mouse and its
fire button. The following list defines the 32-byte data
packet that SS.Mouse creates:
PtNalid rmb 1 Is returned info valid? (0 = no,
1= yes)
Pt.Actv rmb 1 Active side (0 = off, 1 = right, 2 =
left)
Pt.ToTm rmb 1 Timeout initial value
Pt.TTTo rmb 1 Time until timeout
Pt.TSSt rmb 2 Time since counter start
Pt.CBSA rmb 1 Current button state (Button A)
Pt.CBSB rmb 1 Current button state (Button B)
Pt.CCtA rmb 1 Click count (Button A)
Pt.CCtB rmb 1 Click count (Button B)
Pt.TTSA rmb 1 Time this state counter (Button A)
Pt.TTSB rmb 1 Time this state counter (Button B)
Pt.TLSA rmb 1 Time last state counter (Button A)
Pt.TLSB rmb 1 Time last state counter (Button B)
,·~' rmb 2 RESERVED
Pt.BDX rmb 2 Button down frozen Actual X
Pt. BDY rmb 2 Button down frozen Actual Y
Pt.Stat rmb 1 Window pointer type location
Pt.Res rmb 1 Resolution (0-640 by 0 =10/1=1)
Pt.AcX rmb 2 Actual X value
Pt.AcY rmb 2 Actual Y value
Pt. WRX rmb 2 Window relative X
Pt. WRY rmb 2 Window relative Y
Pt. Siz equ . Packet size 32 bytes
SPt.SRX rmb 2 System use, screen relative X
SPt. SRY rmb 2 System use, screen relative Y
SPt.Siz equ . Size of packet for system use
Button Information:
PtNalid.
The valid byte gives the caller an indication of
whether the information contained in the returned packet
is accurate. The information returned by this call is only
valid if the process is running on the current interactive
window. If the process is on a non-interactive window, the
byte is zero and the process can ignore the information
8-125
OS-9 Technical Reference
Pt.Actv. This byte shows which port is selected for use by
all mouse functions. The default value is Right (1) . You can
change this value with the SS.GIP Setstat call.
Pt.ToTm. This is the count down value (as of the instant
the Getstat call is made). This value starts at the value
contained in the Pt.ToTm and counts down to zero at a rate
of 60 counts per second. The system maintains all counters
until this value reaches 0, at which point it sets all
counters and states to 0. The mouse scan routine changes
into a quiet mode which requires less overhead than when
the mouse is active. The timeout begins when both buttons
are in the up (open) state. The timer is reinitialized to the
value in Pt.ToTm when either button goes down (closed).
Pt.TSSt. This counter is constantly increasing, beginning
when either button is pressed while the mouse is in the
quiet state. All counts are a number of ticks (60 per sec
ond). The timer counts to $FFFF, then stays at that value
if additional ticks occur.
Pt.CBSA. These flag bytes indicate the state of the button
Pt.CBSB. at the last system clock tick. A value of 0 indi
cates that the button is up (open). A value other than zero
indicates that the button is down (closed). Button A is
available on all Tandy joysticks and mice. Button B is only
available for products that have two buttons.
The system scans the mouse buttons each time it scans the
Pt.CCtA. This is the number of clicks that have occurred
Pt.CCtB. since the mouse went into an active state. A
click is defined as pressing (closing) the button, then releas
ing (opening) the button. The system counts the clicks as
Pt.TTSA. This counter is the number of ticks that have
Pt.TTSB. occurred during the current state, as defined by
Pt. CBSx. This counter starts at one (counts the tick when
the state changes) and increases by one for each tick that
occurs while the button remains in the same state (open or
8-126
