ZX Spectrum Next CP/M BIOS API
==============================


The BIOS on the ZX Spectrum Next provides a few features that may be useful
to you if you are writing a .COM command for CP/M. They are all accessed
via the USERF function (BIOS function 30).

To use these factilities, use the following code to determine the address of
the USERF function:


warm_vector     equ     $0001           ; vector to warm start in page zero

warm_id         equ     1               ; Warm start, BIOS function 1
userf_id        equ     30              ; USERF, BIOS function 30

userf_offset    equ     3*(userf_id-warm_id)

        ld      hl,(warm_vector)        ; obtain BIOS warm start vector
        ld      bc,userf_offset
        add     hl,bc                   ; HL=address of USERF function entry

You may now access USERF facilities by calling the address in HL (this is
usually most easily done by patching a CALL instruction with the contents
of HL).


Additional considerations
=========================
CP/M runs on the ZX Spectrum Next in conjunction with NextZXOS, which means
that as well as the normal TPA (which is around 60.5K on the ZX Spectrum Next)
you can allocate additional memory via the IDE_BANK call and page it in as
desired.

Please note, however, that you *must* disable interrupts before doing any
banking operations using the MMU0..7 registers. This is because interrupts
will perform banking operations themselves and may leave the memory map in
a state that you are not expecting.

It is also wise to never page out MMU0. This allows the Multiface to be used
for debugging etc, since CP/M's page zero contains the necessary code to exit
cleanly from the Multiface.


USERF API
=========

The following describes the API for the USERF function, as at BIOS v0.9.


; ***************************************************************************
; * BIOS USERF function                                                     *
; ***************************************************************************
; Additional BIOS facilities.
; Entry: C=function id
;        Other parameters defined by function
; Exit:  A=$00, function executed successfully
;               Other return parameters defined by function
;        A=$FF, function failed or unsupported function
;
; Currently-supported functions:
;
; ===========================================================================
; C=0: Exit CP/M
;
; Entry: -
; Exit:  does not return
;
; Exits from CP/M and returns to NextZXOS.
; ===========================================================================
; C=1: Perform NextZXOS call
;
; Entry: IY=NextZXOS/IDEDOS/+3DOS call id
;        alternate registers and IX contain entry parameters
; Exit:  alternate registers and IX contain exit values
;
; NOTE:  Any parameters passed in memory must be located between $8000..$bfff
; NOTE:  Success/failure of the NextZXOS/IDEDOS/+3DOS call is as indicated in
;        the documentation for that call (usually returned in A'F' by this call)
; ===========================================================================
; C=2: Obtain NextZXOS drive mappings
;
; Entry: -
; Exit:  HL=address of CP/M->NextZXOS drive mapping table (16 bytes)
;        BC=address of NextZXOS->CP/M drive table (16 bytes)
;
; Each entry in the drive mapping table corresponds to CP/M drive A..P.
; A value of 0 indicates this CP/M drive is not present.
; A value of 'A'..'P' indicates the NextZXOS drive letter under which the
; CP/M drive is mapped.
;
; Each entry in the NextZXOS->CP/M drive table corresponds to NextZXOS drives
; A..P.
; A value of 0 indicates this NextZXOS drive is not present.
; A value of 'A'..'P' indicates the CP/M drive which is mounted on this letter.
; A value of $ff indicates that there is a NextZXOS-only drive on this letter.
;
; WARNING: You should never use NextZXOS calls to read or write to drives
;          that are mounted in CP/M drives, as NextZXOS and the CP/M BDOS
;          use separate I/O buffers. Therefore changes made under CP/M BDOS
;          will not be reflected under NextZXOS and vice versa.
; ===========================================================================
; * C=3: Resize terminal                                                    *
; ===========================================================================
; Entry: D=X offset
;        E=Y offset
;        IXh=width
;        IXl=height
