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

8.5 HEADER PROTOCOL OF MEMORY MODULES
A module of code can be relocated into high memory so that it's last byte is positioned
at the value returned from the @HIGH$ SuperVisor Call. The module is then protected from
being overwritten by other modules by adjusting HIGH$ to point to the address preceding
the start of the module. Modules relocated and protected in this manner, must include a
standard header that identifies the module. Modules placed into the low memory I/O driver
region also must adhere to this standard. The header is used by the system to accomplish
a number of important functions. First, it provides a locatable storage region for
pointers used in the device independent library operations. Second, it provides a name
string used by the @GTMOD SuperVisor Call to locate a specific module. Other data
contained in the header provides the information needed to identify the entry address of
each module so protected.
The following code describes this standard header:
ENTRY JR BEGIN ;Branch around linkage
STUFHI DW $-$ ;To contain last byte used
DB MODDCB-ENTRY-5 ;Calculate length of 'NAME'
DB 'MODNAME' ;Name of this module
MODDCB DW $-$ ;To contain DCB pointer for module
DW 0 ;Reserved by the DOS
;*=*=*
; Area that can be used to store data
;*=*=*
.
BEGIN EQU $
;*=*=*
; Actual module code start
;*=*=*
Let's examine this module header line by line so that you gain an understanding of its
purpose. At the label "ENTRY", the header always will have a relative jump instruction.
The operand of the jump will almost always reference the starting address of your module.
An exception to this would occur if the data area was extensive so that it placed the
label "BEGIN" beyond the range of the jump relative instruction. If such was the case,
you must provide an absolute jump (JP) instruction just prior to the data area. The
address of this instruction will then be used as a reference in the operand field of the
ENTRY jump relative.
It is also possible that the "module" is not a program but rather a data area that you
have reserved. This data area must still have a memory header; however, since there
exists no BEGIN address, it is recommended that you reference the operand of the ENTRY
jump relative instruction so that it jumps to ENTRY (i.e. jumps to itself). This is the
second exception.
The 2-byte storage region identified by the label STUFHI must be loaded with a value
equal to the last memory address used by the module. The program routine that relocates
the module into its memory position is responsible for loading this value. The system's
@GTMOD routine uses the value to be able to branch sequentially from module to module. If
the module is placed into high memory, this address value is the value returned by
@HIGH$.
The next two fields of the header are the name LENGTH and NAME fields. The NAME field
will contain the module's name as assigned by the programmer. This is the name string
that is used in the @GTMOD SuperVisor Call to locate the module. The name must range from
characters in length and cannot have any character value below X'20'. The length
of the name is then placed into bit positions 0-3 of the LENGTH field. The system uses
the length value to determine how many characters must be matched in the NAME field. Bits
4-7 of the LENGTH byte are reserved by the operating system.
8-14