Advanced Plus 6 Support ROM
                     ===========================
                        Updated:  01-Feb-2019

This ROM provides support for the Electron Plus 1 and a ROM Manager to
support the Advanced Plus 6 ROM/RAM board. This documentation should be read
in conjunction with the Plus 1 User Guide.

With the AP6 ROM present when power is applied the Electron boots into BASIC
regardless of its priority. From then on the default language can be
configured with *LANG. If no default language is selected the language
priority order is changed so that ROMs numbered lower than the AP6 ROM take
priority over higher numbered ROMs. If no language is found, the AP6 gives a
*command prompt. The *command prompt can also be entered by pressing
*-BREAK.

All commands can be prefixed by a 'P' character to prevent clashes with
other ROMs. For instance, if a higher priority ROM has a *ROMs command,
*PROMS will call the AP6 *ROMS command.


UTILS commands
==============
*BUILD <file>
-------------
*BUILD creates a file with the specified name and each line of keyboard
input is written to the file, suitable for using with *EXEC. The input is
terminated by pressing Escape which then closes the file.

*DUMP <file>
------------
*DUMP displays a hexadecimal and ASCII dump of the named file, with each
line preceeded by the offset into the file of each line. The width of the
dumpout adjusts to fit the width of the text window.

*LIST <file>
------------
*LIST displays the contents of the file directly to the VDU with each line
preceeded with a line number. CR, LF, CRLF and LFCR end-of-line sequences
are all displayed as a single newline.

*TYPE <file>
------------
*TYPE displays the contents of the file directly to the VDU. CR, LF, CRLF
and LFCR end-of-line sequences are all displayed as a single newline.

*FORMAT <drive> (S|M|L) (Y)
---------------------------
Formats the disk in the specified floppy drive as an ADFS disk. The drive
number can be 0/1, 4/5 or A/B, but always selects one of the two floppy
drives even if a hard drive is attached. The size specifies S(mall) for
40-track single-sided, M(edium) for 80-track single sided and L(arge) for
80-track double-sided.

If the Y option is not given, the user is prompted to continue before
formatting. If the disk is already formatted, the user is prompted again
before overwriting it. If the Y option is given the *FORMAT command goes
ahead without any prompting to start the format or to overwrite an existing
disk.

While the formatting is progressing the drive and track number is displayed.

*FORMAT uses main memory to create the track layout. To try to avoid
overwriting any program or data in main memory it uses &1800 bytes below
screen memory (eg &4800 upwards in MODE 6), and will change to MODE 6 (or
MODE 7 if present) if in MODE 0-3 to free enough memory.

If using Acorn ADFS 1.00 a dummy file ZYSysHelp is saved to protect against
a bug in the ADFS. If ADFS is not the current filing system, the command is
passed on to any other ROMs or filing systems, and you will get a 'Bad
command' error if nothing else responds.

*VERIFY <drive>
---------------
Verifies the disk in the specified floppy drive as an ADFS disk by reading
all the data on every track. The drive number can be 0/1, 4/5 or A/B, but
always selects one of the two floppy drives even if a hard drive is
attached.

While the verification is progressing the drive and track number is
displayed. If an error occurs it is displayed with a new line so you will
have a list of all tracks with an error on them.

*VERIFY uses main memory to read the data. To try to avoid overwriting any
program or data in main memory it uses &1400 bytes below screen memory (eg
&4C00 upwards in MODE 6), and will change to MODE 6 (or MODE 7 if present)
if in MODE 0-3 to free enough memory.

If ADFS is not the current filing system, the command is passed on to any
other ROMs or filing systems, and you will get a 'Bad command' error if
nothing else responds.

*TUBE ON|OFF|<num>
------------------
Enables or disables an active second processor. *TUBE <num> selects a second
processor CPU with the Matchbox protocol. The selection takes effect at the
next BREAK.


SROM commands
=============
*INSERT (<rom>|<*>) (I)
-----------------------
Inserts a ROM, counteracting a previous *UNPLUG. The ROM will not become
active until the next BREAK. If no <rom> is given the user is prompted
through a list of ROMs and asked to confirm which ROMs to insert. If a
'*' is given, all ROMs are inserted silently.

If the I option is given and the ROM has a valid ROM header, then it is
inserted into the ROM table and will respond to service calls. Note that
some ROMs such as filing systems also need BREAK pressing to initialise
them.

*UNPLUG (<rom>|<*>) (U)
-----------------------
Unplugs a ROM, making it invisible to the system until it is *INSERTed. The
ROM remains active until the next BREAK. If no <rom> is given the user is
prompted through a list of ROMs and asked to confirm which ROMs to UNPLUG.
If a '*' is given, all ROMs are unplugged silently.

If the U option is given the ROM is immediately removed from the ROM table
and will stop responding to service calls.

Note, if you *UNPLUG the AP6 control ROM it stops responding after the next
BREAK, /as do all other *UNPLUGged ROMs/. This can be useful to put the
Electron in a "stripped-down" state by *UNPLUGging everything except BASIC.

Once the AP6 ROM has been *UNPLUGged you can re-enable it by pressing
Ctrl-Caps-BREAK, which will drop to the AP6 *command prompt.

*SRLOCK <rom>|<*>
-----------------
This locks a bank of sideways RAM, making it write protected. If no <rom> is
given then all banks are locked. Note that banks of sideways RAM are paired
so locking 0, 1, 5, 13 will also lock 2, 3, 6, 15, and vice versa. If a '*'
is given, all ROMs are unlocked.

*SRUNLOCK (<rom>|<*>)
---------------------
This unlocks a bank of sideways RAM, allowing writes to it. If no <rom> is
given then all banks are unlocked. Note that banks of sideways RAM are
paired so unlocking 0, 1, 5, 13 will also unlock 2, 3, 6, 15, and vice
versa. If a '*' is given, all ROMs are unlocked.

*SRLOAD <file> <rom> (U)(L)(I)
------------------------------
Loads the specified <file> into sideways bank <rom>. The following options
can be used:

    U: Unlock  Unlocks the bank before copying the file into SRAM.
    L: Lock    Locks the bank after copying the file into SRAM.
    I: Insert  If the ROM has a valid ROM header it is inserted into the ROM
               table and will respond to service calls. Note that some ROMs
               such as filing systems also need BREAK pressing to initialise
               them.

*SRLOAD will load to sideways RAM or EEPROM if it is unlocked. If the bank
is ROM or is locked a 'Bank not writable' error is generated. *SRLOAD uses
main memory at &2000-&5FFF to load the file, and will change to MODE 6 (or
MODE 7 if present) if not in MODE 6 or 7 to free enough memory.

You will also get a 'Bank not writable' error if you attempt to *SRLOAD on
top of the AP6 Support ROM. If the Support ROM is in rewritable RAM or
EEPROM you must use an external *SRLOAD or *EELOAD command to overwrite it.

*SRSAVE <file> <rom>
--------------------
Save the specified sideways bank <rom> as <file>. No check is made to test
if the <rom> has any valid contents. If the ROM is a language the saved
file's load and execution addresses will be set to the ROM's language entry
address.

*SRSAVE uses main memory at &2000-&5FFF to save the file, and will change to
MODE 6 (or MODE 7 if present) if not in MODE 6 or 7 to free enough memory.

*SRWIPE <rom> (U)(L)
--------------------
Wipes the <rom> bank and removes it from the ROM table. The following
options can be used:

    U: Unlock  Unlocks the bank before wiping it.
    L: Lock    Locks the bank after wiping it.

*SRWIPE will wipe sideways RAM or EEPROM if it is unlocked. If the bank is
ROM or is locked a 'Bank not writable' error is generated.

*ROMS (*)
---------
Lists all active ROMs, unplugged ROMs and banks of sideways RAM. Each line
is in the following format:

ROM n * (SLR) ROM TITLE VERSION
    . .  ...
    n .  ...  is the ROM number in hex
      *  ...  indicates the default language
         U..  indicates the bank is unplugged
         S..  indicates the ROM has a service entry
          L.  indicates the ROM has a language entry
           E  indicates the bank is EEPROM
           R  indicates the bank is RAM

If the bank contains a valid ROM the ROM's title and version string is
displayed. If a '*' is given, all ROM banks are listed, regardless of
any contents.

*LROMS (*)
----------
This locks all ROMs in the same way as *SRLOCK with no <rom>, then does
*ROMS.

*UROMS (*)
----------
This unlocks all ROMs in the same way as *SRUNLOCK with no <rom>, then does
*ROMS.

*LANG (<rom>)
-------------
This specifies the default language to enter on Ctrl-BREAK. When Ctrl-BREAK
is pressed, if the default language is *UNPLUGged or <rom> was not specified
the highest priority language is selected by checking all the ROMs. The ROMs
in sockets numbered below the AP6 ROM are checked first, then the ROMs in
sockets numbered above the AP6 ROM. If there are no available languages or
the AP6 ROM is the default ROM a 'No Language Environment' *command prompt
is given.

*AQRPAGE <page>
---------------
Selects a bank of Advanced QuarterMeg RAM, and rebuilds the ROM table.

*SRPAGE <rom> <page>
--------------------
Selects a sub-bank within a pageable ROM, and rebuilds the ROM table.


BREAK key
=========
The AP6 Support ROM tests for some keypresses when BREAK is pressed.

CAPS-BREAK - This forces all ROMs to be INSERTed. This is useful if you have
             UNPLUGed all ROMs as it will quickly re-insert them all.

*-BREAK    - This drops straight to a *command prompt regardless of what
             language is configured. This can be useful if something has
             crashed and locked up the computer beyond even Ctrl-BREAK
             working, as you can then enter commands to recover.

If any error occurs during startup, then the *command prompt is entered
instead of the computer hanging, similar to on the Master or with a second
processor enabled.


Errors
======
Error 17: Escape
----------------
When a command is terminated by pressing Escape, an 'Escape' error is given.

Error 135: Bank not writable
----------------------------
This error is given if *SRLOAD or *SRWIPE is used specifying a sideways ROM
or a locked bank of RAM or EEPROM, or if you try to *SRLOAD on top of the
AP6 support ROM.

Error 138: Bank not ROM
-----------------------
This error is given if *SRPAGE is used with a bank that contains writable
memory. Sub-bank paging is implemented by writing to ROM space, so it is
not possible with writable memory as the writable memory would be written
to by writing to the paging register.

Error 146: Aborted
------------------
If (Y)es is not given when *FORMAT prompts the user to continue or to
overwrite an existing disk, an 'Aborted' error is given.

Error 148: Bad size
-------------------
*FORMAT can only specify a drive size as L(arge) M(edium) or S(mall).

Error 201: Disk read only
-------------------------
This error is given if you try to *FORMAT a write-protected disk.

Error 204: Bad filename
------------------------
If no <file> is given to *SRLOAD or *SRSAVE a 'Bad filename' error is given.

Error 205: Bad drive
--------------------
*FORMAT and *VERIFY only allow the use of drive 0,1,4,5,A,B,E,F to specify
floppy drive 0 or floppy drive 1.

Error 214: File not found
-------------------------
If a command to load or read a file specifies a non-existant file a 'File
not found' error is given. Filing system commands may also give other
filing-system specific errors.

Error 249: Language?
Error 249: Not a language
-------------------------
If you specify a non-language ROM with *LANG a 'Not a language' error will
be given. On Ctrl-BREAK if there are no languages that can be entered a
'Language?' error will be given.

Error 252: Bad number
---------------------
<rom> can be a decimal or hexadecimal ROM number from 0 to 15 or 0 to F. If
a number outside this range is specified the error 'Bad number' is given.
Commands that operate on multiple ROMs can also accept '*' to specify all
ROMs.

Error 254: Bad command
----------------------
If *FORMAT or *VERIFY is used when ADFS is not the current filing system,
the command is passed on to other ROMs and then to the filing system. If
nothing else responds with a *FORMAT or *VERIFY command a 'Bad command'
error will be given.


Compatability
=============
The ROM manager recognises the standard SROM commands. To allow programs to
be compatable with other ROM managers the following aliases are recognised:

  *RLOAD *ROMLOAD -> *SRLOAD
  *RSAVE *ROMSAVE -> *SRSAVE
  *ZERO           -> *SRWIPE
  *LOCK           -> *SRLOCK
  *UNLOCK         -> *SRUNLOCK

For compatability with Acorn SRAM commands *SRLOAD and *SRSAVE can take
<start> <end> and +<length> parameters, which are just ignored and always
default to <start>=8000 and <length>=4000 or <end>=C000. So, for example,
the Acorn syntax: *SRLOAD file 8000 6 is accepted with the 8000 being
ignored.

*SRLOAD and *SRSAVE also allow the (Q)uick option which specifies
loading/saving via main memory. This is ignored as *SRLOAD and *SRSAVE
always use main memory.

Both *HELP SROM and *HELP SRAM will list the SROM commands.


Plus 1 Notes
============
The following is some information in addition to the Plus 1 User Guide.

When using TAPE or ROMFS the AP6 ROM automatically disables the Plus 1
functions so you don't have to do them yourself when using serial file
handling (BPUT, BGET, PRINT#, INPUT#).


OSBYTE 2 will select serial input if serial hardware is present.
  On entry:
    X=0 Use the keyboard for input
    X=1 Use the serial input for input
    X=2 Use the keyboard for input, but also enable the serial port so that
        input bytes are received and buffered.
  On exit:
    X=previous input source, 0 or 1.


OSBYTE 3 will select serial output if serial hardware is present.
  On entry:
    X=bitmap of output ports to send bytes to:
      b0 : Enable output to serial port
      b1 : Disable output to VDU drivers
      b2 : Disable all printer output entirely
      b3 : Enable printer output without VDU 2/VDU 3
      b4 : Disable output to *SPOOL file
      b5 : Not used
      b6 : Disable printer output unless preceeded by VDU 1
      b7 : Not used
  On exit:
    X=previous output destination.

  Common OSBYTE 3 settings are:
    *FX3,0  - normal state, serial disabled, VDU enabled, printer enabled by
              VDU 2, spool output if *SPOOL file open
    *FX3,1  - normal output, also sent to serial port
    *FX3,2  - disable all output except printer port and any *SPOOL file
    *FX3,3  - disable VDU, enable serial port and any *SPOOL file
    *FX3,16 - normal output without copying to *SPOOL file
    *FX3,18 - disable all output except printer port
    *FX3,23 - disable all output except serial port
    *FX3,86 - disable all output entirely

The output destination can be changed as a bitmap by using OSBYTE &EC.


OSBYTE 7 and 8 select serial receive and transmit speed.
  On entry:
    X=0 9600 (default)        X=7  9600
    X=1 75                    X=8  19200
    X=2 150                   X=9  110
    X=3 300                   X=10 600
    X=4 1200                  X=11 1800
    X=5 2400
    X=6 4800                  X>11 ignored
  On exit:
    X is corrupted.


OSBYTE 16 sets the number of ADC channels to sample
  On entry:
    X=number of channels to sample, X=0 turns off all sampling
  On exit:
    X=number of channels actually selected. There is usually a maximum of 4
      ADC channels.


OSBYTE 17 forces an ADC conversion to start
  On entry:
    X=channel number to start the conversion on
  On exit:
    X=channel conversion actually started on. There is usually a maximum of
      4 ADC channels.


OSBYTE 110 Writes to the ROMSTROBE port
  On entry:
     X= new ROMSTROBE value
  On exit:
     X= old ROMSTROBE value

The ROMSTROBE port is at &FC73 on the Electron, and writes the byte of data
while the ROMSTROBE line is activated on the cartridge slot.


OSBYTE 156 Writes to the serial control registers.
  On entry:
    X=3,   Y=0   to reset the ACIA
    X=0,   Y=159 to stop transmitting a serial break
    X=96,  Y=159 to start transmitting a serial break
    X=n*4, Y=227 to set word format
  On exit:
    X,Y corrupted


OSBYTE 163,128 Enables and disables various Plus 1 features.
  On entry, X=128 and:
    Y=0 enable printer and ADC
    Y=1 disable printer and ADC
    Y=2 enable serial system
    Y=3 disable serial system
    Y=4 restore ROM table. This call is made during Reset as part of the
        process to change the priority of language ROMs. It will normally be
        ignored if called outside the Reset process.
  On exit:
    If the Plus 1 is absent X is returned as &FF. Otherwise:
    If Y<4 on entry:
        X=old enable/disable state, &00 if enabled, <>&00 if disabled.
        X will always be <&80, so b7=Plus 1 absent, b6-b0=option disabled.
    If Y=4 on entry:
        X=&80+AP6 ROM if no LANG configured
        X=&00+LANG if LANG configured
    If Y>4 on entry:
        X is returned unchanged

  You can test the current Plus 1 state by calling OSBYTE 163 twice, for
    example:
      LDY #0                       :\ Y=0 to enable Plus 1
      LDX #128:LDA #163:JSR OSBYTE :\ Enable Plus 1, returns X=old state
      TXA:BMI Plus1Absent          :\ Bit 7 set, no Plus 1
      PHA:TAY                      :\ Save Enable/Disable state
      LDX #128:LDA #163:JSR OSBYTE :\ Return Plus 1 to previous state
      PLA                          :\ Get Enable/Disable state back
      BEQ Plus1Enabled
      BNE Plus1Disabled


The ROM Manager adds the following two OSBYTEs.

OSBYTE 161 Read configuration setting
OSBYTE 162 Write configuration setting
  On entry:
    X=configuration setting
      X=5  *LANG setting in bits 4-7
      X=6  *INSERT bitmap for ROMs 0 to 7, bit 0=ROM 0, '1'=inserted
      X=7  *INSERT bitmap for ROMs 8 to 15, bit 0=ROM 8, '1'=inserted
      X=15 *TUBE ON/OFF setting in bit 0, '1'=enabled
    Y=byte to write with OSBYTE 162
  On exit:
    X=preserved, or &FF if OSBYTE call not supported
    Y=byte read with OSBYTE 161, preserved with OSBYTE 162 or if call not
      supported


Technical Information
=====================
Memory usage:
  &0D68-&0D6B Plus 1
  &0D6C-&0D6F ROM Manager
  &0D70-&0D7D ROMFS/CFS vectors
  &0AC0-&0AFF Used to create ZYSysHelp file
  &2000-&5FFF *SRLOAD/*SRSAVE file buffer
  &1A00 bytes below current screen memory: *FORMAT workspace
  &1400 bytes below current screen memory: *VERIFY workspace