ftp.barnyard.co.uk/2015.02.ftp.barnyard.co.uk.tar/ftp.barnyard.co.uk/cpm/walnut-creek-CDROM/CPM/ZCPR33/A-R/JLTOOLS.LBR/JETLDR.MZO/JETLDR.MMO

Text File | 2000-06-30 | 18KB | 471 lines

To:    Z-System Users
From:    Bridger Mitchell
Subject:JetLDR, ZRL files, and Named-Common Segments
Date:    7/8/88


       The New ZRL Files -  Named Common Z-System Segments

This mouthful of nominatives refers to a new method of assembling
Z-System (ZCPR3) operating system segments into relocatable files
or modules.  The resulting "ZRL" files are _portable_ across
systems of different sizes, different addresses, and to other
Z-System computers.   No reassembly is required.

To help distinguish these "REL" files from other relocatable files
(which are normally intended to be linked into an executable COM
file), we will refer to them as type "ZRL" -- Z-system ReLocatable.

A single ZRL file will suffice as the command processor for all
(CP/M 2.2) Z-Systems, whatever their memory location!  Another
single file will serve all users desiring a particular version of
a flow command processor.  The same applies to the FCP and IOP
packages.

To _use_ the new ZRL files you need only JetLDR (which fully
replaces LDR and LLDR).  The Z3PLUS Z-System (for CP/M 3) and the
new Z-COM (version 2.0)  also use (and require) the new ZRL
format files.  In addition, the next release of XBIOS for SB180
and SB180/FX computers will support this format.

To _assemble_ the new ZRL files you need an assembler that
supports multiple named-common relocation addresses.  Some that
do are various SLR assemblers, and M80.  The current version of
ZAS (from Alpha) lacks this feature, but an upgrade (EZASM) is
in the works.

I have one _important request_.  The naming standards stated
here have been developed jointly with Jay Sage, Joe Wright, and
Echelon.  In order to maintain true portability, please do not
circulate on bulletin boards any Z-System segments in ZRL form
that don't adhere to these new standards.

JetLDR and CMNREL are Copyright 1988 by Bridger Mitchell, all
rights reserved.  JetLDR is bundled with Z3PLUS and NZCOM; it is
also available separately at a nominal charge.  CMNREL is
available for licensing by developers.  Please scrupulously
observe the copyright laws -- any redistribution of these
programs is illegal.

The remainder of this memo contains information on using JetLDR
and technical information about the named-common relocation
bases.


              USING JetLDR

JetLDR should fully replace LDR and LLDR.  The complete
command-line syntax is:

A> JetLDR //
     gives usage message

A> JetLDR  [du:]file1.typ, [du:]file2.typ, ...
     loads file1.typ, file2.typ, ...

A> JetLDR [du:]lbrfile[.lbr] file1.typ file2.typ ...
     loads members file1.typ, file2.typ, ... of the library file "lbrfile.lbr"

The optional "du:" may be a drive/user spec, or a named
directory.  If neither is given, JetLDR will search one or more
directories for the file, according to several patchable
configuration bytes, described below.

The file types may be:

  FCP - flow commands       ENV - environment
  IOP - input/output        NDR - named directories
  RCP - resident commands   Z3T - terminal capabitlities
  ZRL -- FCP, RCP, IOP, CCP, CP3, DOS, DO3, BIO, or CFG in relocatable format

If the file type is  ZRL or REL (in SLR or MS-relocatable format)
then JetLDR will relocate and load the FCP, RCP, IOP, CCP, DOS, BIO,
or CFG package, provided that its corresponding module name is:

    FCPxxx    xxx = any ascii characters
    RCPxxx
    IOPxxx
    CCPxxx    (for cp/m 2.2)
    CP3xxx    (for cp/m 3)
    DOSxxx    (for cp/m 2.2)
    DO3xxx    (for cp/m 3)
    BIOxxx
    BSXxxx
    RSXxxx
    CFGxxx    for configuring following module(s)
    xxxxxx  a custom module

Any intersegment addresses should be referenced via Named Common
relocation bases (see below).

On CP/M 2.2 systems, JetLDR relocates a CCP package and
writes the absolute image to a file in the root directory,
because there is no general-purpose method of installing that
image into the warm-boot procedure of the host computer.  The
user can then run SYSGEN or the corresponding utility for his
system to install the image.

The CFG option is described in JLCFG.MMO.  It provides for
customized loading and patching of system modules.  One important
application of a CFG is to write the CCP to the system tracks,
banked memory, or whatever is appropriate in the host system, so
that the newly-loaded CCP will thereafter be used on warm boots.

JetLDR loads a DOS package to the current bdos base (xx00h)
address and executes bdos function 13 (reset disk system) before
returning.  JetLDR loads a BIO package to the current bios base
address (xx00) as pointed to by (0001h).  As soon as a BIO
package is moved into position JetLDR executes a <<cold>> boot;
no further messages or loading are attempted!

JetLDR does extensive checking for addressing conflicts before
loading a package, and will not load a package too large for the
current buffer size.  This will help to catch most mistakes that
result from specifying the wrong absolute code package for the
current system.  In the longer term, I recommend that users
switch to using only ZRL files for Z-System segments containing
code (i.e. everything but Z3ENV, Z3T and NDR).

As originally defined, an IOP had no way of being de-installed.
Now, before loading an IOP package, JetLDR calls the existing IOP
SELECT routine with register B = 0FFh.  This value is an invalid
device selection.  It is used here to enable any new IOP to
execute its deinitialization routine before being overloaded by
another IOP.

               File Search Options

The first record of JetLDR can be patched to configure the
options for searching for files.  The patch points are identified
by ascii labels, with the default values shown:

PATHF determines whether path searching will be used to locate
the file(s). If the flag is 0, then the fixed DU area below will be
used.  If it is 0FFH, then the other path-related flags will be
used to determine how the search is performed.

    DEFB    'PATH'
PATHF:    DEFB    0FFh        ; Path search flag (NO = use DU given below)

ROOTF determines whether only the root of the path will be
searched.  If it is 0FFH, then only the root will be used; if it
is 0, then the entire path will be searched.

    DEFB    'ROOT'
ROOTF:    DEFB    0        ; NO = use entire path / YES = root only

If full path searching is selected, then SCANCUR determines
whether or not to include the current directory first.

    DEFB    'SCANCUR'
SCANCUR:
    DEFB    0FFH        ; YES = search current DU first

If path searching is disabled, then the explicit directory
specified here will be searched for files.

    DEFB    'DU'
CMDDRV:    DEFB    0        ; Drive to use if not path (drive A = 0)
CMDUSR:    DEFB    0        ; User to use if not path




           Extended External Environment Type

JetLDR supports extended external environment types (type >=
80h).  If bit 7 of the environment type byte is set, then the
following locations in the environment descriptor contain
additional system data:

z3env+  08h    db    environment type
z3env+  34h    dw    valid drives vector

z3env+    3Fh    dw    ccp base address
z3env+     41h    db    ccp buffer size (80h records)
z3env+    42h    dw    bdos base address (xx00 or xx80)
z3env+    44h    db    bdos buffer size (80h records)
z3env+    45h    dw    bios base address (xx00)


JetLDR's algorithm is this:

1. If the host environment is not type >= 80h, it assumes a
standard system (bdos size 0E00h, ccp size 800h), and computes
the bdos and ccp addresses from the value at 0001h.  It installs
these addresses and sets environment type 80h.  It sets valid
bits for all drives up to the envrionment's current 'maxdrv'.

2. Otherwise, it preserves the environment type and system
addresses, overlaying them on any ENV segment that may be
loaded.

Z3PLUS, NZCOM version 2.0, and upgraded Z-tools use these system
data to support advanced features.  ZCPR34, FF, and other
tools use the valid-drive vector to selectively disable
drives not accessible on a system.

Sharp-eyed users will note that the extended environment has
"stolen" bytes originally defined for CRT1 and Printers 2 and
3.  As the Z-System has actually developed, these parameters
are of very limited use, and almost no program actively
refers to them.  The new CPSET tool should be used to
manipulate the crt and printer parameters.

An application can determine whether an environment descriptor
contains valid system data by testing bit 7 of the environment
type byte (z3env+8).  By using JetLDR to load any system segment,
you will automatically upgrade the running environment to type 80h,
with current system parameters.  Thus, JetLDR provides a painless
assembly-free method of upgrading an existing environment to
be compatible with the new extended-environment tools.


          NAMED-COMMON RELOCATION BASES

Until now, a Z-System command processor, or other code package,
had to be reassembled for each system size.  A new assembly was
required whenever a package buffer was enlarged or moved.  Thus,
the first step in bringing up ZCPR3 on a new machine was
assembling everything for the particular system's addresses. Even
on "bootable disk" Z-Systems, separate sets of files were
required for different sized systems.

Users no longer need to assemble source code!  Named-common ZRL
files for all Z-System code packages have made assemblers
obsolete for pure users.  Now, a _single_ ZCPR34.ZRL file will
run on _all_ CP/M 2.2-compatible Z-Systems.  Similarly, a
_single_ FCP, RCP or IOP relocatable file can be used immediately by
all CP/M 2.2 and CP/M Plus Z-systems.

Named-commons, combined with the new Z3PLUS and NZCOM
auto-install systems, make the Z-System truly portable, capable
of running out of the box, without reassembly, on virtually any
CP/M 2 or CP/M 3 system with a Z-80-compatible processor.

The remainder of this file contains technical information on
using named-common references.  Additional information regarding
relocatable code will be found in my "Advanced CP/M" column in The
Computer Journal #33.


         How named-common relocation bases work


When assembly-language code is written for _absolute_ addressing,
all addresses and symbols refer to fixed locations in memory.

For example, suppose the external environment's message buffer
is located at 0FC00h.  The traditional ZCPR3 system would
contain an equate

    z3msg equ 0FC00h

in an "include" or "maclib" file, and references to the message
buffer in the command processors would be of the form

    ld    hl,z3msg

When assembled, this address (0FC00h) is hard-wired into the
resulting command processor file.

Relocating assemblers permit the user to split the computer's
address space into different logical segments.   For example,
programs often contain separate code (CSEG) and data (DSEG)
segments. The resulting REL file tags each address with a flag
indicating to which segment (CSEG, DSEG, or absolute) it refers.

Modern assemblers carry this flexibility further, and permit the
use of several additional segments.  Each segment is addressed
relative to a specific _named relocation base_.  All references
to an address in one relocation base are tagged in the REL file
with an internal relocation base number.  In addition, the name
of the base and its associated internal base number is included
somewhere in the file.

To use this feature, we omit the previous equate and instead
declare z3msg to be in a separate base, named "_MSG_", as follows

    COMMON    /_MSG_/
    z3msg    equ    $

We place all of the command processor code in the code segment

    CSEG
; ...
    ld    hl,z3msg    ; sample reference to z3msg
; ...

The result:  the address in the ZRL file for "z3msg" is not
0FC00h, but 0000 plus a tag to the named-common base _MSG_.

The ZRL file requires one more step of processing to become
executable -- linking to the final run-time addresses for the
system where it is to run.  This process is conventionally
performed by a linking editor (such as SLRNK or L80):  the user
supplies final addresses for each segment (CSEG, DSEG, and named
commons), and the linker produces an absolute image file (COM or
perhaps CIM).

This is where JetLDR comes in.  It performs the linking step, by
obtaining the final addresses _from the current external
environment_ of the computer system in which it is running.
Thus, a Z-System ZRL file is tailored to the exact system that is
running at the moment.


           Other uses of Named-Common

In fact, this is also where Z3PLUS, the Z-System for CP/M Plus
(CP/M 3) Z-80 computers, comes in.  I developed the named-common
relocatable files approach in order to be able to use a single, new
command-processor file on all CP/M Plus systems.  Inside the Z3PLUS
system is a relocating loader similar to JetLDR's.

This named-common relocatable format has also been adopted by Joe
Wright, for NZCOM version 2 -- the auto-install Z-System
package for Z80 CP/M 2.2 computers.  Again, NZCOM has just a
single ZRL file for each type of Z-System segment, regardless of
system size and configuration.

Portability in ZRL format is real:  CP/M Plus users, running
Z3PLUS, will be able to exchange Z-System packages (RCP, FCP) in
named-common ZRL format with CP/M 2.2 systems.  (The packages
themselves will have to be capable of running under both CP/M 2.2
and CP/M Plus operating systems.  In general, two areas require
attention:  calculation of disk space and direct use of BIOS disk
functions.)

JetLDR and named commons also make it possible to create and
load resident system extensions (RSXs) more easily than before.
This application is described in my TCJ #34 column.


     Writing and Assembling Code with Named-Commons

To use named-commons you need an assembler that supports additional
relocation bases.  Three that do are the SLR and SLR+ (virtual
memory version) and M80.

For Z-System use, JetLDR, Z3PLUS, and NZCOM have adopted the
following names for system segments:

named-        Z-System segment
common

_BIOS_        BIOS location

_CBIO_        CBIOS location in a NZCOM system

_SCB_        CP/M Plus system control block

_ENV_        ZCPR3 external environment descriptor

_SSTK_        shell stack

_MSG_        message buffer

_FCB_        external fcb

_MCL_        multiple command line buffer

_XSTK_        external stack

_CCP_        command processor

_RSX_        CP/M Plus RSX containing Z-system

_ID_        <<TEXT>> buffer containing identification of REL file.

These named-common declarations, along with equates for key
addresses in each segment (such as z3msg) are contained in the
file Z3COMMON.LIB.  The command processor, the Z3PLUS system,
and specialized BIO modules require several of these named-commons;
a command-processor should "include" this file.

All other Z-System code segments (RCP, FCP, IOP) should declare
only the _ENV_ and _BIOS_ relocation bases.  The addresses of
other system segments should be obtained from the external
environment.  To modify an existing source file (e.g. for an
RCP), remove any "include" or "maclib" statements that include
either Z3BASE.LIB or other files with absolute system segment
references.  Check the source file for any external references
and convert them to named-common base references.  For example,
to access the wheel byte, replace

    ld    a,(z3whl)    ;old way

with

    push    hl        ; new way
    ld    hl,(z3env+29h)    ; get ptr to wheel byte
    ld    a,(hl)
    pop    hl


Assemble the file to relelocatable format; to help distinguish it
from an "ordinary" REL file, specify the output file type, or
rename it, to type ZRL.

The file RCPSAMPL.ASM contains a small, sample RCP with H
(command help), SP (disk space), and WHL (set wheel byte)
commands.  It illustrates the use of the named-common method,
and also provides a CP/M Plus-compatible disk space function.



              The _ID_ Named Common

JetLDR, Z3PLUS and NZCOM normally require that the
named-common segments include only _addresses_, not actual code.
However, there is one exception: the _ID_ segment.  This
relocation base is special -- it may include up to 256 bytes of
nul-terminated ascii data.  Its purpose is to embed identifying
information into the ZRL file, such as version number, date, and
supported features.

For example, an RCP source file might contain:

    COM /_ID_/
    defb    '3/26/88 vers. 1.2c 1.0K',0dh,0ah
    defb    'H, SAVE, P, POKE, SP',0

JetLDR will display the id text when it loads the file.  It can
also be viewed, somewhat clumsily, with a debugger or disk
utility.  Perhaps someone will eventually write a simple
librarian that scans ZRL files and displays their names and ID
fields.


    Loading Named-Common Routines with CMNREL

A few, specialized applications (such as Z3PLUS) need to be able
to themselves load code in named-common REL format.  The
CMNREL.REL (common relocation) module provides this service.
The interface requirements are detailed in a separate memo.

CMNREL itself does not restrict the use of code/data in
any of the named commons, and this feature is used for
specialized JetLDR applications with a CFG module, such
as loading an RSX.

               Using a CFG Module

A configuration (CFG) module (in ZRL format) may be loaded as one
file/member of the JetLDR command-line list.  The file is loaded
to a buffer, and relocated to that address.  The resulting code
is then called at key points in the JetLoad process, and may be
used to customize the normal loading process of the other ZRL
modules.

The CFG feature is intended to  help automate the installation of
system segments/modules that require special configuration.
Examples would be:  linking up DateStamper to a DOS, loading an
RSX or BSX, loading a DOS requiring special patches,
loading/relocating code into a NZCOM patch area, and
deinitializing/initializing an interrupt-driven bios module.

See the memo JLCFG.MMO for details.
interface requirements are detailed in a separate memo.

CMNREL itself does not r