The Programmer's Guide to TRSDOS Version 6 - Tim Mann's Home ...

7. Interfacing via SuperVisor Calls
7.1 SUPERVISOR CALL LINKAGE
This chapter discusses specific linkage necessary to communicate with the operating
system for service requests at the assembly language level. Requests for system resources
are accomplished via SuperVisor Calls (SVCs). The following sections describe each SVC
and the register contents passed to and from the system.
The DOS does not affect the contents of the Z-80's alternate registers (AF', BC', DE',
and HL'). Where the DOS makes use of index registers IX and IY, it will save them prior
to their use and restore them when that use is completed. The exception, of course, is
where IX and/or IY are used to pass information to or from the DOS.
Each SVC specifies what registers are altered by the system. The AF register will always
be altered. Most SVCs incorporate return codes. Where applicable, the return code is
passed in the accumulator and the Z-flag status is indicative of an error or success [ Z
= success, NZ = error ]. Some SVCs use only the state of the Z-flag to indicate a
pass/fail situation. The return code convention is specified under the linkage shown for
each SVC.
SuperVisor Calls utilize a number from 0 to 127. Numbers from 128 to 255 are not
interpreted as SVCs but are used internally by the DOS for other system overlay
invocations. The SVC number is placed in the accumulator once the registers particular to
the SVC are set up and control is passed to the operating system by issuing a RST 40 (RST
28H) Z-80 instruction.
7.1.1 Adding or Changing SVC Entries
Some programmers may find it useful to alter the performance of existing SuperVisor Calls
to suit unique situations. A program may even be written that could utilize additional
SVCs. Four SVC slots [numbers 124-127] have been provided for application programs. An
examination of the following SVC tables will reveal a good handful of SVC numbers that
have not yet been assigned by Logical Systems. Caution is to be observed in utilizing any
of these reserved slots since you may find your program unusable with a future release of
the operating system. [Remember that four RST instructions: RST 8, RST 16, RST 24, and
RST 32 are available for use by application software.]
In any event, be it modification of the vector for an existing SVC or the addition of
your own into a "user" SVC, the interface is simple. The SVC table is always (and will
always) be origined at the start of a RAM page. The page address (i.e. the high-order
byte of the SVC table) can be obtained from the system via the FLAGS pointer returned by
the @FLAGS SVC. Since the low order byte starts out with 0 for SVC-00, you can locate the
exact address for the SVC vector by multiplying the SVC number by two, loading the result
into the low order byte of a register pair (say L), then loading the high order byte of
that register pair (say H) with the SVC table base address (FLAGS$+26). This will then
index the low order byte of the SVC vector. The SVC vectors are stored in standard lowhigh
order.
7.2 PROGRAM ENTRY AND EXIT CONDITIONS
When the operating system executes a program either from DOS Ready or via an SVC (@CMNDI ,
@CMNDR, or @RUN), certain conditions prevail. These conditions relate to the register
contents and the stack location. The useful register contents are as follows:
BC Contains a pointer to the start of the command line. This is useful for
those applications desiring to know what program name caused their
invocation (as in the command-line arguments applicable to C programs).
7-1