;----------------------------------------------------------------------------
;File name:	BS_COMP.TXT			Revision date:	1999.04.16
;Created by:	Ulf Ronald Andersson		Creation date:	1999.01.31
;----------------------------------------------------------------------------

The files in the BS_COMP folder are intended for inclusion in special boot
sectors.  This means that they are extremely compact for what they do, and
that they each do something that can be extremely useful in a boot sector
context (at least for debugging), but which is not normally needed by other
programs.  (Naturally they may be used there too anyway.)

TRACER.I	Included in header of boot sector source file
--------
This defines a set of macros for use in tracing execution of a boot sector
during debugging phase of development.  It is extremely compact, but even
so allows removal of all extra code (after debugging) simply by changing
an assembly symbol's value (trace_mode set 0).  Normal usage is to simply
insert lines with "trace   'x'" as trace points, varying 'x' to use other
letters to ensure runtime identification.  At end of the boot sector code
you need to call the 'trace_code' macro to insert the actual subroutine.
With trace_mode set to zero neither macro has any effect at all, so you
do not need to add any conditionals yourself to remove debugging traces.


FINDCOOK.S	Included in code section of boot sector source
----------
This is a subroutine for searching cookie jar for a cookie and is designed
to allow simple use in a loop when searching for many cookies.  The name of
the cookie to be searched for must be stored at (a0) before the call, and
the a0 value is preserved, so that an array of cookie names can be used in
multiple searching.  Results are in d0/d1 as cookie name/value and you call
it by "bsr find_cookie".


RELOCATE.S	Included in code section of boot sector source
----------
This is a subroutine for relocating a program already loaded into RAM in raw
standard program format.  It allows the program header to reside in separate
RAM, but all other program file segments must reside contiguously after the
TEXT segment.  The relocation is performed identically to how it would have
been done by GEMDOS Pexec (use of Pexec from boot sectors should be avoided).
After relocation the TEXT and DATA segments still reside in the same place,
but in relocated form, and the BSS area following them has been cleared.
Call it with a0->TEXT and a1->header by "bsr relocate".


SEEMEM.S	Included in code section of boot sector source
--------
This is the largest of the boot sector components, and will not be able to
coreside with any extensive boot sector program.  It is however invaluable
in debugging, since it allows easy inspection and manipulation of RAM in a
completely unaltered machine state, as it was when the sector was booted.
(NB: loading any program at all could change that state )  This is mainly
a tool for investigating elusive boot state data.  To use it, simply set
a0->first_area_to_be_inspected and then call it by "bsr seemem".

;----------------------------------------------------------------------------
;End of file:	BS_COMP.TXT
;----------------------------------------------------------------------------
