Acorn Z80 Tube MOS Entry Points
                    ===============================
       File: mdfs.net/Docs/Comp/Z80Tube/MOSEntries - Update: 0.10
                 Author: J.G.Harston - Date: 15-10-1989


As well as the standard MOS entry points which are documented in Appendix
J of the CP/M manual, and listed in the BBC BASIC (Z80) manual, there exists
some other very useful entry points.  This is a complete list of them. 


ESCFLG    &FF80  Escape flag - bit 7 is set on escape.
TERMFLG   &FF81  TERM flag.
FAULT     &FF82  Fault pointer.
DEF_ERR   &FF84  Address of default error handler.



PR_OUT    &FF9E  Print a character to OSWRCH or TERMOUT
On entry: A = character to be printed
On exit:  with TERM set to OSWRCH:
              all registers preserved.
          with TERM set to TERMOUT:
              C is corrupted
              HL is corrupted after sending ESC &3F (clear to end of screen)
                 or ESC &40 (clear to end of line)

Calling this routine either calls the OSWRCH code, or the TERMOUT code,
depending on the setting of TERM.  Altering TERM alters the address field
of this entry to point to the required code.  When TERM is set to TERMOUT,
the following ESCape sequences are obeyed:
          ESC, &3D ('='), Y, X        move cursor to X-32,Y-32
          ESC, &3E ('>'), C, C ... 0  print characters C-32, until C=0
          ESC, &3F ('?')              clear to end of line
          ESC, &40 ('@')              clear to end of line
Any other ESC, char sequence is ignored.  ESC ? and ESC @ only work
correctly in 80 column screen modes



INIT_FF   &FFA1  Set up OSWORD &FF in host
On entry: -
On exit:  HL, DE, B, A are corrupted

Calling this routine sets up the code to handle OSWORD &FF (block transfer)
in the host processor.  It is called by the TUBE OS on startup, and should
not be called again, as then the vector daisy-chaining will end in a loop.
The JGH BBC BASIC (Z80) ROM initialisation removes this call by putting a
RET opcode at location &FFA1.



M_OSWD_7F   &FFA4  Multiple OSWORD &7F call
On entry: HL points to the OSWORD &7F control block
On exit:  A holds the result byte from (HL+10).  A=0 means ok.
          B, C, DE are corrupted.

This routine tries to access a disk drive.  The call is made up to 40 times
before giving up and returning with the failure result byte in A. Every ten
unsuccessful attempts, the routine tries to seek to track zero, sector zero
on the drive being accessed, before continuing to attempt to access the
drive.  If the routine succeeds, then zero is returned in the A register,
otherwise A holds the disk error number.

 

LD_CCP    &FFA7  Load CCP and BDOS
On entry: -
On exit:  A holds zero if successful.
          BC, DE, HL are corrupted.

This routine is used to reload the CCP from disk after a warm CPM reset. 
It loads the Acorn CP/M CCP and BDOS from the disk in drive zero, using
the code of the multiple OSWORD &7F call detailed above.  If a disk error
occurs, the error 'Disk fault', number 0 is generated.  The segments
loaded are:
          Track 0, sectors 8 and 9 loaded to &D400 to &D5FF
          Track 1, sectors 0 to 9 loaded to &D600 to &DFFF
          Track 2, sectors 0 to 9 loaded to &E000 to &E9FF
In effect, the routine loads sectors 0/8 to 2/9 to memory &D400 to &E9FF.



PR_HEX    &FFAA  Print A in hex
On entry: A = value to be printed
On exit:  A is corrupted

This routine prints out the A register in hexadecimal to two digits and
leading zeros.  This routine is overwritten by the Acorn CPM BIOS.



PR2HEX    &FFAD  Print HL in hex
On entry: HL = value to be printed
On exit:  A is corrupted
               
This routine prints out the HL register in hexadecmial to four digits and
leading zeros.  This routine is overwritten by the Acorn CPM BIOS.



USR_INT   &FFB0  User interupt routine
On entry: -
On exit:  -

This call is made if an unrecognised interupt occurs.  By default it just
points to a RET instruction.  Any routine that intercepts this call MUST
preserve ALL registers.  As it is called on an interupt, it should not last
longer than about 5 msecs. at the maximum.



PR_TEXT   &FFB3  Print in-line text
On entry: -
On exit:  -

This routine prints out the text following the call to OSWRCH.  The text
should be terminated with a zero byte, which also gets printed, eg:
          CALL PR_TEXT
          DEFM "HELLO THERE":NOP
          \ continue here
This routine is overwritten by the Acorn CPM BIOS



PRNT_C    &FFB6  Send C to TERMOUT
On entry: C = character to be printed
On exit:  A is corrupted
          HL is corrupted after sending ESC &3F and ESC &40

Calling this routine prints the character in the C register using TERMOUT.
See the description of PR_OUT at address &FF9E.



CLI_COM   &FFB9  Enter CLI processor
No entry parameters
No exit from call

Calling this routine enters the CLI processor.  This presents a '*' prompt
and sends all input to OSCLI.  This routine is overwritten by the Acorn
CPM BIOS.



RST_38    &FFBC  Default error jump
On entry: -
On exit:  -
The default error jump code to initialise locations &0038 to &003A with.
Enters the default error handler which displays the error message and then
enters the CLI processor.



INIT_ERR  &FFBF  Initialise default error code
On entry: -
On exit:  -

Copies the default error jump code at &FFBC to locations &0038 to &003A.



TRK_00    &FFC2  Do OSWORD &7F with SP set to &FF80
On entry: -
On exit:  -

Temporarily sets SP to &FF80 and does an OSWORD &7F to seek track zero of
drive 0.



KBD_TST   &FFC5  Reads status of keyboard input
On entry: -
On exit:  A holds &00 if no characters pending
          A holds &FF if there are input characters pending

This routine tests if there are any characters waiting to be read, either in
the input buffer, or from a soft key expansion.  A returns &00 if there are
no characters pending, or &FF if there are.



TERM      &FFC8  Read or set the TERM status
On entry: A read or set parameter 
On exit:  A holds the old TERM status, or preserved if invalid parameter
          HL is corrupted or preserved if A holds an invalid parameter

The calls sets whether the PR_OUT routine at address &FF9E calls OSWRCH or
TERM_OUT.  The entry values for A are:
           A=0    Set PR_OUT to do OSWRCH
           A=1    Set PR_OUT to do TERM_OUT
           A=&FF  Read current setting
If A does not hold one of these values, then the routine does nothing.



OSWRD2    &FFCB  Do an OSWORD call, reading the control block to DE
On entry: A is the OSWORD call number
          HL points to the control block
          DE points to where to receive the returned control block
On exit:  -

This call does a standard OSWORD call, but the returned control block is
put into the memory pointed to by DE.


The following entry points are the standard BBC entries:

OSFIND    &FFCE  Open or close a file
OSGBPB    &FFD1  Multiple byte file access
OSBPUT    &FFD4  Put a byte to a file
OSBGET    &FFD7  Get a byte from a file
OSARGS    &FFDA  Read or set file arguments
OSFILE    &FFDD  Load or save file
OSRDCH    &FFE0  Input a character
OSASCI    &FFE3  Print a character, with CR converted to LF,CR
OSNEWL    &FFE7  Print a LF,CR sequence
OSWRCH    &FFEE  Print a character
OSWORD    &FFF1  Do an OSWORD call
OSBYTE    &FFF4  Do an OSBYTE call
OSCLI     &FFF7  Interpret a command


The following three addresses hold system vectors:

BRKV      &FFFA  Address of error handler
EVENTV    &FFFC  Address of event handler
INTV      &FFFE  Address of primary interupt handler


Entry points into BBC BASIC 
==========================

BBC BASIC has come entry points at its start in page 1 (as with many other
Z80 programs).  This is a full list of them.

&100	Startup.
&103	Return to command entry prompt - do END.
&106	Give 'Escape' error.
&109	Report error. A=err num, text follows the call.
&10C	Print text after call (same as pr_text).
&10F	Print text from HL until 0 byte.
&112	Check program and set TOP.
&115	Clear variables - do CLEAR.
&118	Execute program in memory - do RUN.
&11B	Do OSCLI of string pointed to by HL.
&11E	Read a byte from a file - do A=BGET#H.
&121	Write a byte to a file - do BPUT#H,A.
&124	Check EOF of a file - do Z=EOF#E.
&127	Close all files - do CLOSE#0.


Update History
--------------
15-10-1989 v0.10