Bruce Godden and Paul Overell, Locomotive Software
David Radisic, Amstrad

Published by
Amstrad Consumer Electronics plc
Brentwood House
169 Kings Road
Brentwood Essex

All rights reserved
First edition 1986

Reproduction or translation of any part of this publication without the written permission of the copyright owner is unlawful (woops).

Amstrad and Locomotive Software reserve the right to amend or alter the specification without notice. While every effort has been made to verify that this complex software works as described, it is not possible to test any program of this complexity under all possible conditions. Therefore the program and this manual are provided “as is” without warranty of any kind, either express or implied.

IBM is a trademark of International Business Machines Corporation.
CP/M, CP/M Plus and Dr Logo are trademarks of Digital Research Inc.

SOFT 968 Copyright © 1986 Locomotive Software Ltd. and Amstrad Consumer Electronics plc

The computers in the CPC range contain ROMs which hold the BASIC interpreter and the ‘firmware’. The firmware consists of low level routines responsible for driving the hardware, handling the screen, handling real-time events and other similar functions.
This manual describes the firmware.

This manual is applicable to the full range of CPC machines; 464, 664, 6128 and 464+DDI-1. The firmware in these machines is not identical. All 464s contain V1.0 of the firmware, all 664s contain V1.1 and all 6128s contain V1.2. All firmware calls are upwards compatible, that is, any firmware call available in V1.0 is available in V1.1 and V1.2 and any firmware call available in V1.1 is available in V1.2. Upwards compatibility will be maintained in any future versions of the firmware.

As stated above this manual relates only to the firmware section of the ROMs. Other AMSOFT publications describe the BASIC interpreter (though not at a system level) and the various implementations of CP/M. However, the areas in which CP/M and the firmware interact are covered in this manual. Also, areas of the firmware that are affected by the addition of a disc interface are covered in this manual.

The Key Manager is the pack associated with the keyboard. All the attributes of the keyboard are generated and controlled by the Key Manager. These attributes include repeat speed, shift and control keys, function keys and key translation. The joysticks are also scanned by the Key Manager.

The Key Manager has three levels of operation. The lowest level scans the keyboard, the middle level converts the key pressings into key values and the top level converts the key values into characters. The user may access the Key Manager at whichever level is most appropriate for a given program. It is usually unwise, however, for a program to mix accesses at different levels.

• 3.1 Keyboard Scanning
• 3.2 Key Translation
• 3.3 Characters from the Keyboard
• 3.4 Shift and Caps Lock
• 3.5 Repeating keys
• 3.6 Breaks
• 3.7 Function Keys and Expansion Tokens
• 3.8 Joysticks

The Text VDU is a character based screen driver. It controls 8 different streams each of which can have an area of screen allocated to it (a window). The Text VDU allows characters to be written to the screen and read from the screen. It also treats certain 'characters' as 'control codes' which can have various effects, from moving the cursor to setting the colour of an ink.

• 4.1 Text VDU Coordinate Systems
• 4.2 Streams
• 4.3 Text Pen and Paper Inks
• 4.4 Text Windows
• 4.5 The Current Position and the Cursor
• 4.6 Characters and Matrices
• 4.7 Character Output and Control Codes

The Graphics VDU allows individual pixels (dots) on the screen to be set or tested and lines to be drawn. The plotting takes place on an ideal screen that is always 640 points wide and 400 points high. This means that more than one point on the ideal screen will map onto a particular pixel on the real screen. The width of the ideal screen (640 points) is chosen to be the horizontal number of pixels on the screen in the highest resolution mode (mode 2). The height of the ideal screen (400 points) is chosen to be twice the vertical number of pixels on the screen in all modes. This ensures that the aspect ratio of the screen is approximately unity, i.e. a circle looks circular and not elliptical.

• 5.1 Graphics VDU Coordinate Systems
• 5.2 The Current Graphics Position
• 5.3 Graphics Pen and Paper Inks
• 5.4 Graphics Write Mode
• 5.5 Graphics Window
• 5.6 Writing Characters
• 5.7 Drawing Lines (Only applicable to V1.1 firmware)
• 5.8 Filling Areas (Only applicable to V1.1 firmware)

The Screen Pack is used by the Text and Graphics VDUs to access the hardware of the screen. It also controls the features of the screen that affect both the Text VDU and Graphics VDU, such as what mode the screen is in.

• 6.1 Screen Modes
• 6.2 Inks and Colours
• 6.3 Screen Addresses
• 6.4 Screen Memory Map

The Sound Manager deals with the sound chip. It allows various envelopes and sounds to be set up and played under the control of the user. Most of the control is achieved using software rather than the sound chip hardware.

• 7.1 The Sound Chip
• 7.2 Tone Periods and Amplitudes
• 7.3 Enveloping
• 7.4 Sound Commands
• 7.5 Sound Queues
• 7.6 Synchronisation
• 7.7 Holding Sounds

The Cassette Manager deals with reading files from and writing files to tape. These operations can either be performed on a character by character basis or on a whole file at once. There is no hardware support for the cassette, even the timing for reading and writing bits is performed by software.

The format of data on the tape is described in great detail. This will only be of academic interest to most users. More general information can be found in sections 8.4 onwards. In the case of V1.1 machines or the CPC464 with a DDI-1 fitted, a |TAPE command will have to be used to access the Tape Operating System.

• 8.1 File Format
• 8.2 Record Format
• 8.3 Bit Format
• 8.4 The Header Record
• 8.5 Read and Write Speeds
• 8.6 Cataloguing
• 8.7 Reading Files
• 8.8 Writing Files
• 8.9 Reading and Writing Simultaneously
• 8.10 Filenames
• 8.11 Cassette Manager Messages
• 8.12 Escape Key
• 8.13 Low Level Cassette Driving

AMSDOS is a disc operating system used with all the CPC range of computers, of course, in the case of the 464 the DDI-1 has to be fitted. AMSDOS enables programs to be access disc files in a similar manner to cassette files, indeed existing programs which currently use the cassette should be able to use disc files with little or no modification.
The main source of incompatability will be filenames, AMSDOS filenames must conform to CP/M standards but cassette filenames are far less restricted.

AMSDOS has been designed to complement CP/M, not to compete with it. They share the same file structure and can read and write each other's files.

AMSDOS resides in the same ROM as the CP/M BIOS.

• 9.1 Features
• 9.2 Filenames
• 9.3 File Headers
• 9.4 Disc Organisation
• 9.5 Boot Sector
• 9.6 AMSDOS Messages
• 9.7 BIOS Facilities Available to AMSDOS
• 9.8 Store requirements
• 9.9 Extended Disc Parameter Blocks

The system can address up to 252 expansion ROMs, mapped over the top 16K of memory, starting at #C000. The Kernel supports two varieties of expansion ROM, foreground and background. A resident system extension (RSX) is similar in use to a background ROM, but must be loaded into RAM before it can be used.

A foreground ROM contains one or more programs, only one of which may be running at one time. The on-board BASIC is the default foreground program. Other possible foreground programs are:

• other systems, such as FORTH or CP/M.
• applications, such as a Word Processor or Spread Sheet.
• tools, such as an Assembler or Debugger.

A RAM program, once loaded, takes over the machine in much the same way as a foreground ROM program. Games will generally be RAM programs.

There may be up to 16 background ROMs, each of which provides some sort of service independent of the foreground program. It is expected that expansion peripherals will each have an associated background ROM containing suitable support routines. Other background ROMs may augment the existing machine software; for example, by providing further graphics functions.

A resident system extension (RSX), once loaded, provides some sort of service in the same way as a background ROM. An RSX might, for example, provide special support for a given printer - where it is more economical to provide the software on cassette rather than in ROM (or PROM).

• 10.1 ROM Addressing
• 10.2 The Format of an Expansion ROM
• 10.3 Foreground ROMs and RAM Programs
• 10.4 Background ROMs
• 10.5 Resident System Extensions
• 10.6 External Commands
• 10.7 Examples

There is only one source of interrupts in an unexpanded CPC (not Plus), namely a regular time interrupt. Expansion boards may generate interrupts, but suitable software must be provided to deal with the extra interrupts.

The system runs with interrupts enabled most of the time. It is inadvisable to disable interrupts for a prolonged period if this is avoidable because the time interrupts will be missed.

A number of firmware routines enable interrupts and this is remarked upon in their descriptions. In particular the kernel routines dealing with ROMs and the restart instructions ( eg. LOW JUMP ) enable interrupts.

• 11.1 The Time Interrupt
• 11.2 External Interrupts
• 11.3 Nonmaskable Interrupts
• 11.4 Interrupts and Events
• 11.5 Interrupt Queues

The event mechanism is primarily provided by the Kernel to support the handling of interrupts and other external events. However, the mechanism may also be used to handle internal events in complicated programs (such as a simulation, for ex ample). An event is characterised by the following:

• a. Event Class (see section 12.1)
  Events may be synchronous or asynchronous, express or normal.

• b. Event Priority (see section 12.1)
  Synchronous events have an associated priority.

• c. Event Count (see section 12.2)
  • Each time an event occurs the count is incremented.
  • Each time an event is processed the count is decremented.
  • The event may be disarmed by setting the count negative.

• d. Event Routine. (see section 12.3)
  The address of the routine which is called to process the event.

An event appears to the Kernel as a data block containing the above values (see Appendix X for the exact layout of an event block). The block must be in the central 32K bytes of memory, so that the Kernel can access it without worrying about the ROM enable state.

When an event occurs the associated event block is kicked by calling KL EVENT. If the event count is negative, the 'kick' is ignored, otherwise the event count is incremented (up to a maximum of 127) and the event routine will be called at some time in the future - depending on the event class. When the event routine returns the event count is decremented, unless it has been set to zero or negative in the meantime.

• 12.1 Event Class
• 12.2 Event Count
• 12.3 Event Routine
• 12.4 Disarming and Reinitializing Events

The Machine Pack deals with the low level driving of the hardware. It also talks to the Centronics port (and hence the printer) and is in charge of running 'load and go' programs.

• 13.1 Hardware Interfaces
• 13.2 The Printer
• 13.3 Loading and Running Programs

This section gives the detailed entry and exit conditions and effects of the routines in the indirections jumpblock. See section 14.2 for a list of these routines.

The firmware indirections are taken by the firmware at key points. They allow the user to intercept and alter a number of firmware actions without having to provide a complete new firmware package.

The descriptions given are for the default settings of the indirections. Replacement routines need not perform all the actions that the default routine performs although they are advised to do so.

Place the cursor blob on the screen (if enabled).

If the cursor is enabled and turned on then the cursor blob is drawn on the screen. If not then no action is taken. The current text position is forced into the window (see TXT VALIDATE) and the cursor blob is written at the resulting position. The cursor blob is an inverse patch. This routine will only be called twice if TXT UNDRAW CURSOR is called in between.

No conditions.

AF corrupt.
All other registers preserved.

This indirection is provided to allow the user to change the form of the cursor blob. See TXT PLACE CURSOR for a description of how the cursor blob is normally written.

The Text VDU routines call this indirection whenever the cursor is placed on the screen. All the Text VDU routines that read from the screen, write to the screen or change the current position remove the cursor (using TXT UNDRAW CURSOR) before performing their action and place it back on the screen afterwards (using TXT DRAW CURSOR). An example of such a routine is TXT WR CHAR that writes a character on the screen.

This indirection is set up when TXT INITIALISE or TXT RESET is called.

TXT PLACE CURSOR
TXT UNDRAW CURSOR

Remove the cursor blob from the screen (if enabled).

If the cursor is enabled and turned on then the cursor blob is removed from the screen. If not then no action is taken. The cursor blob is an inverse patch. This routine will only be called after TXT DRAW CURSOR has been used to place the cursor on the screen.

No conditions.

AF corrupt. All other registers preserved.

This indirection is provided to allow the user to change the form of the cursor blob. See TXT REMOVE CURSOR for a description of how the cursor blob is normally removed.

The Text VDU routines call this indirection to remove the cursor from the screen. All the Text VDU routines that read from the screen, write to the screen or change the current position remove the cursor (using TXT UNDRAW CURSOR) before performing their action and place it back on the screen afterwards (using TXT DRAW CURSOR). An example of such a routine is TXT WR CHAR that writes a character on the screen.

This indirection is set up when TXT INITIALISE or TXT RESET is called.

TXT DRAW CURSOR
TXT REMOVE CURSOR

Write a character onto the screen.

Put a character on the screen at a character position.

A contains the character to write.
H contains the physical column to write at.
L contains the physical row to write at.

AF, BC, DE and HL corrupt.
All other registers preserved.

The character position to write at is given in physical coordinates. i.e. Row 0, column 0 is the top left corner of the screen. The position is not checked for legality.

TXT WRITE CHAR is called by TXT WR CHAR to print a character on the screen. The removing of the cursor blob and the calculation of the new current position are performed by TXT WR CHAR and not by TXT WRITE CHAR.

This indirection is set up when TXT INITIALISE or TXT RESET is called.

TXT OUTPUT
TXT UNWRITE
TXT WR CHAR

Read a character from the screen.

Try to read a character from the screen at a character position.

H contains the physical column to read from.
L contains the physical row to read from.

If a readable character was found:

• Carry true.
• A contains the character read.

If no recognisable character was found:

• Carry false.
• A contains zero.

Always: BC, DE, HL and other flags corrupt.
All other registers preserved.

The character position to read from is given in physical coordinates. i.e. Row 0, column 0 is the top left corner of the screen. The position is not checked for legality.

This indirection is called by TXT RD CHAR to read a character from the screen. TXT RD CHAR removes the cursor from the screen before calling this indirection.

The read is performed by comparing the matrix found on the screen with the matrices used to generate characters. As a result changing a character matrix, changing the pen or paper inks or changing the screen (e.g. drawing a line through a character) may make the character unreadable. In particular the cursor blob will cause confusion and so it should not be on the screen.

Special precautions are taken against generating inverse space (character #8F). Initially the character is read assuming that the background to the character was written in the current paper ink. If this fails to generate a recognisable character or it generates inverse space then another try is made by assuming that the character was written in the current pen ink.

The characters are scanned starting with #00 and finishing with #FF. Thus, if there are two possible character matrices that match the screen, the smaller of the two character numbers will be returned.

This indirection is set up when TXT INITIALISE or TXT RESET is called.

TXT RD CHAR
TXT WRITE CHAR

Output a character or control code.

Print a character on the screen or obey a control code (characters #00..#1F). Works on the currently selected stream (except as noted below).

A contains the character or code.

AF, BC, DE and HL corrupt.
All other registers preserved.

This indirection is called by TXT OUTPUT to do the work of printing characters or obeying the control codes. It is provided to allow the user to change the method of dealing with characters and control codes or to allow the user to redirect output (to the printer for example). TXT OUTPUT merely preserves the registers around the call of TXT OUT ACTION.

Control codes may take up to 9 parameters. These are the characters sent following the initial control code. The characters sent are stored in a buffer until sufficient have been received to make up all the required parameters. The control code buffer is only long enough to accept 9 parameter characters.

There is only one control code buffer which is shared between all the streams. It is, therefore, possible to get unpredictable results if the output stream is changed part of the way through sending a control code sequence.

If the VDU is disabled then no characters will be printed on the screen. In V1.1 firmware control codes that are specially marked in the control code table will not be obeyed if the VDU is disabled. Other control codes and all control codes in V1.0 firmware will be obeyed.

If the graphics character write mode is enabled then all characters and control codes are printed using the G raphics VDU (see GRA WR CHAR) and are not obeyed. Normally characters are written by the Text VDU (see TXT WR CHAR).

This indirection is set up when TXT INITIALISE or TXT RESET is called.

TXT OUTPUT
TXT WR CHAR

Plot a point.

Check if the point lies inside the current window and if so write it in the current graphics pen ink and using the current graphics write mode. The current graphics position is always moved to the specified point.

DE contains the user X coordinate of the point to plot.
HL contains the user Y coordinate of the point to plot.

AF, BC, DE and HL corrupt.
All other registers preserved.

The position of the point to plot is given in user coordinates, i.e. relative to the user origin.

This indirection is called by GRA PLOT RELATIVE and GRA PLOT ABSOLUTE to plot the point requested. It is provided to allow the user to change the method for plotting (to output to an X -Y plotter for example). GRA PLOT RELATIVE converts from relative to user coordinates and then calls this indirection; GRA PLOT ABSOLUTE calls this indirection immediately.

To write the point on the screen the SCR WRITE indirection is used. Thus the point is plotted using the current graphics write mode.

This indirection is set up when GRA INITIALISE or GRA RESET is called.

GRA PLOT ABSOLUTE
GRA PLOT RELATIVE
GRA TEST
SCR WRITE

Test a point.

Cheek if the point is inside the graphics window and return the ink it is currently set to if so. Otherwise, return the current graphic paper ink. The current graphics position is always moved to the specified point.

DE contains the user X coordinate of the point to test.
HL contains the user Y coordinate of the point to test.

A contains the decoded ink of the specified point.
BC, DE, HL and flags corrupt.
All other registers preserved.

The position of the point to test is given in user coordinates, i.e. relative to the user origin.

This indirection is used by GRA TEST RELATIVE and GRA TEST ABSOLUTE to test the point requested. It is provided to allow the user to change the method for testing (comparing with the current pen ink for example). GRA TEST RELATIVE converts from relative to user coordinates and then calls this indirection; GRA TEST ABSOLUTE calls this indirection immediately.

To test the ink of a point inside the window the SCR READ indirection is used.

This indirection is set up when GRA INITIALISE or GRA RESET is called.

GRA PLOT
GRA TEST ABSOLUTE
GRA TEST RELATIVE
SCR READ

Draw a line.

Draw a line between the current graphics position and the given endpoint using the current graphics write mode. Points on the line that lie outside the current graphics window will not be plotted. The current graphics position is always moved to the specified endpoint.

DE contains the user X coordinate of the endpoint.
HL contains the user Y coordinate of the endpoint.

AF, BC, DE and HL corrupt. All other registers preserved.

The position of the endpoint is given in user coordinates, i.e. relative to the user origin.

This indirection is used by GRA LINE RELATIVE and GRA LINE ABSOLUTE to draw the line requested. It is provided to allow the user to change the method for line drawing (to output to an X -Y plotter for example). GRA LINE RELATIVE converts from relative to user coordinates and then calls the indirection; GRA LINE ABSOLUTE calls the indirection immediately.

The line is split up into horizontal or vertical sections that are drawn separately (see SCR HORIZONTAL and SCR VERTICAL). The SCR WRITE indirection is called to write the points in these sections. This means that the line is plotted using the current graphics write mode.

In V1.0 firmware the line is plotted in the current pen ink. But in V1.l firmware the setting of the line mask determines how pixels on the line will be plotted. The line mask is bit significant and is used repeatedly in the order bit 7, bit 6 down to bit 0 for each pixel in the line. If the bit is one then the pixel is plotted in the graphics pen ink. If the bit is zero then the action taken depends on the graphics background write mode. If the background mode is opaque then the pixel is plotted in the graphics paper ink. If the background mode is transparent then the pixel is not plotted.

In V 1.1 firmware the first pixel of the line (that at the current graphics position) is not plotted if the first point plotting mode is set false.

This indirection is set up when GRA INITIALISE or GRA RESET is called.

GRA LINE ABSOLUTE
GRA LINE RELATIVE
GRA SET BACK
GRA SET FIRST
GRA SET LINE MASK
SCR HORIZONTAL
SCR VERTICAL

Read a pixel from the screen.

Read a pixel from the screen and decode its ink.

HL contains the screen address of the pixel.
C contains the mask for the pixel.

A contains the decoded ink that the pixel was set to.
Flags corrupt.
All other registers preserved.

The mask supplied must be a mask for a single pixel otherwise the decoding of the ink read from the screen will not work correctly.

This indirection is set up when SCR I NITIALISE or SCR RESET is called. It is called by GRA TEST.

GRA TEST
SCR WRITE

Write pixel(s) using the current graphics write mode.

Plot a pixel or pixels on the screen using the current graphics write mode.

HL contains the screen address of the pixel(s).
C contains the mask for the pixel(s).
B contains the encoded ink to plot with.

AF corrupt.
All other registers preserved.

The pixel mask supplied can be for a single pixel or more than one pixel (or even no pixels). The ink supplied should be encoded to cover the whole of a byte (see SCR INK ENCODE).

The pixel is plotted using the current Graphics VDU write mode. These modes are:

• FORCE : Pixel is set to the new ink irrespective of the old ink.
• XOR : Pixel is set to the ink formed by exclusive-orIng the new ink for the pixel and its current setting.
• AND : Pixel is set to the ink formed by anding the new ink for the pixel and its current setting.
• OR : Pixel is set to the ink formed by oring the new ink for the pixel and its current setting.

The write mode can be set by calling SCR ACCESS appropriately.

This indirection is called by all Graphics VDU write routines, in particular GRA PLOT RELATIVE, GRA PLOT ABSOLUTE, GRA LINE RELATIVE, GRA LINE ABSOLUTE and GRA WR CHAR, to plot pixels on the screen. It is provided to allow the user to intercept the lowest level of point plotting (perhaps to add yet another plotting mode).

This indirection is set up when SCR INITIALISE or SCR RESET is called.

GRA PLOT
SCR ACCESS
SCR PIXELS
SCR READ

Clear the screen to ink 0.

Clear the screen memory to zeros. This indirection is provided to allow the user to prevent the screen being cleared after the mode is changed.

No conditions.

AF, BC, DE and HL corrupt.
All other registers preserved.

Normally this indirection performs the actions described in SCR CLEAR. In V1.0 firmware it is necessary for the user to set up the inks if this indirection is intercepted (see Appendix XIII). In V1.1 firmware the screen pack sets up the inks for the user after SCR MODE CLEAR has been called. This indirection is set up when SCR INITIALISE or SCR RESET is called. N.B. When this indirection is called the text and graphics VDUs are in non-standard states.

SCR CLEAR
SCR SET MODE

Test for break (or reset).

Test if the escape key is pressed, if not then no action is taken. If escape, shift and control are all pressed and no other keys then the system is reset. Otherwise, a break event is reported (see KM BREAK EVENT).

Interrupts disabled.
C contains shift and control key states.

AF and HL corrupt.
All other registers preserved.

This indirection is called by the firmware from the interrupt path. Thus interrupts are disabled and they must remain disabled.

If bit 7 of C is set then the control key is pressed. If bit 5 of C is set then one of the shift keys is pressed.

This indirection is called after the keys have been scanned and the escape key was found to have been pressed. It is provided to allow the user to alter the action of a break (particularly to prevent the system reset, see RESET ENTRY).

This indirection is set up when KM INITIALISE or KM RESET is called.

KM BREAK EVENT

Print a character or time out.

Wait for the Centralises port to become not busy and then send a character to it. If the port remains busy for a long time the routine times out and the character is not sent.

A contains the character to send.

If the character was sent OK:

• Carry true.

If the Centronics port timed out:

• Carry false.

Always:

• A and BC corrupt.
• All other registers preserved.

This indirection is provided to allow the user to drive the printer in a different way.
For example, ‘escape sequences’ could be handled or the time out could be changed.

This indirection is called by the routine MC PRINT CHAR. It tests whether the printer is busy in the same way as MC BUSY PRINTER and sends the character in the same way as MC SEND PRINTER.

This indirection is set up when MC RESET PRINTER is called.

MC BUSY PRINTER
MC PRINT CHAR
MC SEND PRINTER

Scan the keyboard.

Scans the keyboard and updates the key state map. Newly pressed keys are detected and appropriate markers are inserted into the key buffer.

No conditions except that interrupts must be disabled.

AF, BC, DE and HL corrupt.
All other registers preserved and interrupts remain disabled.

This indirection is called every fiftieth of a second during a ticker interrupt. The repeat speeds and start -up delays of the keys are measured in scans of the keyboard and hence fiftieths of a second.

If the escape key is pressed then the indirection KM TEST BREAK is called to process the break.

KL SCAN NEEDED
KM READ KEY
KM TEST BREAK
KM TEST KEY

Separate from the main firmware jumpblock is a small jumpblock for Kernel routines associated with ROM state and ROM selection. The routines accessed through this jumpblock are all RAM resident, to avoid confusion while the ROM state and ROM select are changed! The RAM area is copied out of ROM during the power-up initialization. The jumpblock should not be altered by the user.

The entry KL POLL SYNCHRONOUS is the ‘odd man out’ amongst the routines in this jumpblock. Unlike the other synchronous event handling routines, which are in the lower ROM, this routine is RAM resident. This minimises the overhead involved in polling for synchronous events.

A brief listing of the entries in this jumpblock can be found in section 14.3. A discussion of ROMs and the memory map can be found in section 2, further discussion of ROMs can be found in section 10 and a discussion of events can be found in section 12.

Enable the upper ROM.

Enables the currently selected upper ROM. Reading from addresses #C000 and up will now return the contents of the ROM.

No conditions.

A contains the previous ROM state.
Flags corrupt.
All other registers preserved.

The mechanisms provided for calling subroutines in the upper ROM and for selecting upper ROMs automatically enable the ROM as required. This routine is used by the firmware but is otherwise of little use.

The previous ROM state may be passed to KL ROM RESTORE to reset the state to what it was before this routine was called.

This routine enables interrupts.

KL L ROM ENABLE
KL ROM RESTORE
KL ROM SELECT
KL U ROM DISABLE

Disable the upper ROM.

Disables the upper ROM. Reading from addresses #C000 and up will now return the contents of the RAM.

No conditions.

A contains the previous ROM state.
Flags corrupt.
All other registers preserved.

Disabling the upper ROM gives read access t o the top 16K of RAM, which is usually used as the screen memory. Note that the mapping of a location in screen memory to pixels on the screen depends on the mode and on the screen offset. It is inadvisable to disable the upper ROM while executing instructions in it! The previous ROM state may be passed to KL ROM RESTORE to reset the state to what it was before this routine was called. This routine enables interrupts.

KL L ROM DISABLE
KL ROM RESTORE
KL U ROM ENABLE

Enable the lower ROM.

Enables the lower ROM. Reading from addresses below #4000 will now return the contents of the ROM.

No conditions.

A contains the previous ROM state.
Flags corrupt.
All other registers preserved.

In general the lower ROM is disabled except when a firmware routine is called. The firmware jumpblock arranges to enable the lower ROM automatically and to disable it again when the routine returns. This routine is used by the firmware but is otherwise of little use.

The previous ROM state may be passed to KL ROM RESTORE to reset the state to what it was before this routine was called.

This routine enables interrupts.

KL L ROM DISABLE
KL ROM RESTORE
KL U ROM ENABLE

Disable the lower ROM.

Disables the lower ROM. Reading from addresses below #4000 will now return the contents of the RAM.

No conditions.

A contains the previous ROM state. Flags corrupt. All other registers preserved.

In general the lower ROM is disabled except when a firmware routine is called.
The firmware jumpblock arranges to enable the lower ROM automatically and to disable it again when the routine returns.

The previous ROM state may be passed to KL ROM RESTORE to reset the state to what it was before this routine was called.

This routine enables interrupts.

KL LROM ENABLE
KL ROM RESTORE
KL U ROM DISABLE

Restore the previous ROM state.

The ROM state change routines all return a value giving the previous ROM state.
Given that value KL ROM RESTORE will reset the state to what it was before the change.

A contains the previous ROM state.

AF corrupt. All other registers preserved.

The previous ROM state is the value returned by one of:

• KL U ROM ENABLE
• KL U ROM DISABLE
• KL L ROM ENABLE
• KL L ROM DISABLE
• KL ROM SELECT

It is possible to use KL U ROM DISABLE to reverse the effect of a call of KL U ROM ENABLE (amongst various other combinations). However, calling KL ROM RESTORE is the prefered method since it restores the state to what it was, which might have been enabled anyway.

This routine enables interrupts.

KL L ROM DISABLE
KL L ROM ENABLE
KL ROM SELECT
KL U ROM DISABLE
KL U ROM ENABLE

Select a particular upper ROM.

Select a given upper ROM and enable the upper ROM.

C contains the ROM select address of the required ROM.

C contains the ROM select address of the previously selected ROM.
B contains the previous ROM state.
AF corrupt. All other registers preserved.

The previous state can be passed to KL ROM RESTORE to reset the ROM enable to what it was. Both the previous state and the previous selection can be passed to KL ROM DESELECT to restore the state to what it was and to select the previously selected ROM again.

The mechanisms provided for calling routines in expansion ROMs automatically perform ROM selection as required (see section 2).

It is inadvisable to select another upper ROM whilst executing instructions in the upper ROM.

This routine enables interrupts.

KL CURR SELECTION
KL PROBE ROM
KL ROM DESELECT
KL ROM RESTORE

Ask which upper ROM is currently selected.

Returns the ROM select address of the currently selected upper ROM.

No conditions.

A contains the ROM select address of the currently selected ROM.
All other registers and flags preserved.

It is not possible to predict the ROM select address at which any particular expansion ROM will be fitted. The 'far address' used to reference subroutines in expansion ROMs includes a ROM select byte which must be set up at run time.
This routine returns the ROM select address of the current ROM so that it can set up suitable ‘far addresses'.

KL PROBE ROM
KL ROM SELECT

Ask class and version of a ROM.

The first few bytes of all upper ROMs contain information in a standard form about the ROM. This routine extracts the class, mark number and version number bytes from the ROM at the given ROM select address.

C contains the ROM select address of the ROM to probe.

A contains the ROM's class.
L contains the ROM's mark number.
H contains the ROM's version number.
B and flags corrupt.
All other registers preserved.

The ROM class returned may take any of the following values:
0: Foreground ROM.
1: Background ROM.
2: Extension foreground ROM.
#80: On board ROM (the built in BASIC foreground program).

Selecting a ROM address where no ROM is fitted implicitly selects the on-board ROM and so it will return #80 as its class.
The meaning of the mark and version numbers depends on the ROM. See section 10 for a description of expansion ROMs.

This routine enables interrupts.

KL ROM SELECT
KL CURR SELECTION

Restore previous upper ROM selection.

Set the ROM state and upper ROM selection to what they were before KL ROM SELECT was called.

C contains the ROM select address of the previously selected ROM.
B contains the previous ROM state.

C contains the ROM select address of the currently selected ROM.
B corrupt.
All other registers and flags preserved

The previous ROM selection and state are the values returned by KL ROM SELECT. The currently selected ROM returned by this routine is the ROM that was selected by calling KL ROM SELECT (unless further selections have been made).

The mechanisms provided for calling subroutines in expansion ROMs automatically perform ROM selection as required. It is inadvisable to select another upper ROM whilst executing instructions in the upper ROM.

This routine enables interrupts.

KL CURR SELECTION
KL ROM RESTORE
KL ROM SELECT

Move store (LDIR) with ROMs turned off.

Performs an LDIR instruction (LoaD Increment and Repeat) with both upper and lower ROMs disabled.

BC, DE, HL as required by the LDIR instruction.

F, BC, DE, HL as set by the LDIR instruction.
All other registers preserved.

This routine may be used to move areas of RAM irrespective of the ROM state.

This routine enables interrupts.

KL LDDR
RAM LAM (RST4)

Move store (LDDR) with ROMs turned off.

Performs an LDDR instruction (LoaD Decrement and Repeat) with both upper and lower ROMs disabled.

BC, DE, HL as required by LDDR instruction.

F, BC, DE, HL as set by LDDR instruction.
All other registers preserved.

This routine may be used to move areas of RAM irrespective of the ROM state.

This routine enables interrupts.

KL LDIR
RAM LAM (RST4)

Check if an event with higher priority than the current event is pending.

If the synchronous event queue is not empty then the priority of the highest priority pending event is compared with the current event's priority (if any).

No conditions.

If there is a higher priority event pending:

• Carry true.

If there is no higher priority event pending:

• Carry false.

Always:

• A and other flags corrupt.
• All other registers preserved.

This routine is in the high jumpblock to minimise the overhead of polling for synchronous events. If the synchronous event queue is empty then the routine takes only a few instructions.

While a synchronous event is being processed the Kernel remembers its priority.

The synchronous event routine may itself poll the synchronous event queue, but only events of a higher priority than itself are notified to it.

This routine may enable interrupts.

KL EVENT
KL DONE SYNC
KL DO SYNC
KL NEXT SYNC

Ensure keyboard is scanned at next opportunity.

Force the Key Manager to scan the keyboard when the next ticker interrupt occurs.
This may be used to reduce the probability of key pressings being missed while interrupts are disabled.

No conditions.

AF and HL corrupt.
All other registers preserved.

The keyboard is normally scanned on every sixth ticker interrupt (every fiftieth of a second). While interrupts are disabled the ticks are lost and the keyboard will not be scanned. If interrupts are disabled for a significant period (more than three ticks) then this routine should be called just before interrupts are re-enabled. If interrupts are disabled for a long time (more than twelve ticks) then the user might consider calling this routine and re-enabling interrupts for a short time every fiftieth of a second.

KM SCAN KEYS

The bottom of memory, from #0000 to #003F inclusive, is occupied by the code for the restart (RST) instructions and a number of Kernel entries. Most of these entries are concerned with access to subroutines in ROM and RAM. The RST's are:

• RST 0 performs a system reset.
• RST instructions 1 to 5 inclusive have been used to extend the Z80 instruction set to provide extra CALL and JUMP instructions, which use addresses extended to include ROM state and ROM select components.
• RST 6 is available to the user.
• RST 7 is used by interrupts.

Since all the entries supplied must be available whether the lower ROM is enabled or not, the area is copied into RAM from the ROM during power-up initialization.

The user is not intended to alter this jumpblock (except where noted in the USER RESTART and EXT INTERRUPT areas). If the user does change the area then it is the user's responsibility to ensure that the changes do not affect other programs. To some extent this can be achieved by ensuring that t he lower ROM is always enabled when other programs are running. However, since the other programs may disable the lower ROM this is insufficient in most cases. Ideally the original jumpblock contents should be restored where there is any doubt.

Section 2 c ontains a discussion of ROMs and the memory map and section 10 contains a general discussion of external ROMs. A brief list of the routines in this area can be found in section 14.4.

Completely reset the machine as if powered up.

When the machine is first turned on execution starts here. Calling or jumping to #0000, or executing RST 0, resets the machine to its initial power-up state.

No conditions.

Does not return!

All hardware is reset and the firmware is completely initialized. Once all tables and jumpblocks have been set up, control is passed to the default entry in ROM 0 (see section 10).

MC START PROGRAM

Jump to lower ROM or RAM, takes inline ‘low address’ to jump to.

RST 1 is used to extend the instruction set. It is an expanded form of the jump instruction. It should be followed by a 2 byte ‘low address’ which specifies the location to jump to and the required ROM state.

All registers and flags are passed to the target routine untouched.

All registers and flags are as set by the target routine.

The ‘low address’ following the restart instruction is laid out as follows:

• If the ‘U’ bit is set then the upper ROM is disabled.
• If the ‘L’ bit is set then the lower ROM is disabled.
• ‘Address’ is the actual address of the target routine to jump to once the ROM state has been set.

When the target routine returns the ROM state is restored to what it was before the jump. To accomplish this 4 bytes are pushed onto the stack and so care should be taken when indexing up the stack (to find the address of inline parameters, for example).

The LOW JUMP, RST 1, 'instruction' may replace the first byte of a JP (jump) instruction. It is intended for use in jumpblocks. The main firmware jumpblock is made up almost exclusively of LOW JUMP ‘instructions’.

It is assumed that the destination of the jump is a routine which will return in the usual way. The restart instruction itself does not return. The value at the top of the stack when a LOW JUMP is executed must, therefore, be a return address.

Executing a LOW JUMP enables interrupts.

FAR CALL (RST 3)
FIRM JUMP (RST 5)
KL FAR ICALL
KL FAR PCHL
KL LOW PCHL

Jump to lower ROM or RAM.
Register HL contains the ‘low address’ to jump to.

Takes a ‘low address’ as a parameter and jumps to it. The ‘low address’ specifies both the address to jump to and the ROM state required.

HL contains the ‘low address’ to jump to. All registers and flags are passed to the target routine untouched.

All registers and flags are as set by the target routine.

The ‘low address’ is laid out as follows:

• If the ‘U’ bit is set then the upper ROM is disabled.
• If the ‘L’ bit is set then the lower ROM is disabled.
• ‘Address’ is the actual address to jump to, once the ROM state has been set.

When the target routine returns the ROM state is restored to what it was before the jump. To accomplish this 4 bytes are pushed onto the stack and so care should be taken when indexing up the stack (to find the address of inline parameters, for example).

It is assumed that the destination of the jump is a routine which will return in the usual way. The value at the top of the stack when a LOW PCHL is executed must, therefore, be a return address.

Interrupts are enabled.

KL FAR ICALL
KL FAR PCHL
LOW JUMP (RST1)
PCHL INSTRUCTION

Jump to address in BC.

Equivalent to the JP (HL) instruction (or PCHL in some assembler dialects), except that the destination is in BC not HL.

BC contains the address to jump to. All registers and flags are passed to the target routine untouched.

All registers and flags are as set by the target routine.

Calling PCBC INSTRUCTION is a useful way of invoking a routine whose address has been picked out of a table or otherwise established at run time.

KL FAR PCHL
KL LOW PCHL
KL SIDE PCHL
PCDE INSTRUCTION
PCHL INSTRUCTION

Call to a sideways ROM, takes inline ‘side address’ to call.

RST 2 is used to extend the instruction set. It is an expanded form of the CALL instruction. It should be followed by a 2 byte ‘side address’ which specifies the location to call and the required ROM selection.

All registers and flags are passed to the target routine untouched except for IY (which is set to point at a background ROM's upper data area).

IY corrupt.
All other registers and flags are as set by the target routine.

The ‘side address’ following the restart instruction is laid out as follows:

• 'Off’ gives a value in the range 0..3, which, when added to the ROM select address of the main foreground ROM, gives the ROM select address of the required ROM.
• After #C000 has been added to it, ‘address’ is the address of the routine to call.

The target routine returns to the instruction immediately following the inline 'side address'. The ROM select and ROM state are restored to what they were before the call. To accomplish this 6 bytes are pushed onto the stack and so care should be taken when indexing up the stack (to find the address of inline parameters, for example).

When the target routine is entered the lower ROM is disabled and the appropriate upper ROM is selected and enabled.

SIDE CALLs are provided to support foreground programs split over a number of ROMs (up to four). See section 9 on expansion ROMs.

Interrupts are enabled.

FAR CALL (RST3)
KL SIDE PCHL

Call to a sideways ROM, HL contains the ‘side address’ to call.

Takes a ‘side address’ and calls it. The ‘side address’ specifies the address of the routine to call and which upper ROM to select.

HL contains the ‘side address’ to call.
All registers and flags are passed to the target routine untouched except for IY (which is set to point at a background ROM’s upper data area).

IY corrupt.
All other registers and flags are as set by the target routine.

The ‘side address’ is laid out as follows:

• 'Off’ gives a value in the range 0..3, which, when added to the ROM select address of the main foreground ROM, gives the ROM select address of the required ROM.
• After #C000 has been added to it, ‘address’ is the address of the routine to call.

When the target routine is entered the lower ROM is disabled and the appropriate upper ROM is selected and enabled.

The target routine returns to the ROM select and ROM state are restored to what they were before the call. To accomplish this 6 bytes are pushed onto the stack and so care should be taken when indexing up the stack (to find the address of inline parameters, for example).

Side calls are provided to support foreground programs split over a number of ROMs (up to four). See section 10 on external ROMs.

Interrupts are enabled.

FAR CALL (RST3)
KL FAR ICALL
KL FAR PCHL

Jump to address in DE.

Equivalent to the JP (HL) instruction (or PCHL in some assembler dialects), except that the destination is in DE not HL.

DE contains the address to jump to.
All registers and flags are passed to the target routine untouched.

All registers and flags are as set by the target routine.

Calling PCDE INSTRUCTION is a useful way of invoking a routine whose address has been picked out of a table or otherwise established at run time.

KL FAR PCHL
KL LOW PCHL
KL SIDE PCHL
PCBC INSTRUCTION
PCHL INSTRUCTION

Call subroutine in RAM or any ROM, takes inline address of ‘far address’.

RST 3 is used to extend the instruction set. It is an expanded form of the CALL instruction that allows routines to be called anywhere in RAM or in any ROM. The restart is followed by the address of a 3 byte ‘far address’ which specifies the location to call and the required ROM state and ROM selection.

All registers and flags are passed to the target routine untouched except for IY (which is set to point at a background ROM's upper data area).

IY preserved.
All other registers and flags are as set by the target routine.

The restart instruction takes a 2 byte inline parameter which is the address of a ‘far address’. The ‘far address’ is laid out as follows:

• Bytes 0..1 give the address of the routine to call.
• Byte 2 is the ROM select byte which takes values as follows:
  • #00..#FB: Select the given ROM, enable upper, disable lower.
  • #FC: No change of ROM selection, enable upper, enable lower.
  • #FD: No change of ROM selection, enable upper, disable lower.
  • #FE: No change of ROM selection, disable upper, enable lower.
  • #FF: No change of ROM selection, disable upper, disable lower.

The reason that the 'far address' is not contained in the FAR CALL instruction directly is because the ROM select byte for routines in ROM will depend upon the particular configuration of expansion ROMs on the machine and must therefore be established and set at run time.

Registers are passed to the target routine untouched except for the IY register.
When entering a background ROM this is set to point at the base of the ROM's upper data area. (See section 10.4 and KL INIT BACK).

The target routine returns to the instruction immediately following the inline parameter. The ROM select and ROM state are restored to what they were before the call. This is accomplished by pushing values on the stack and so care should be taken when indexing up the stack after a FAR CALL instruction. (The stack usage is 4 bytes for ROM select bytes in the range #FC..# FF and 6 bytes for ROM select bytes in the range #00.. #FB.)

Interrupts are enabled.

KL FAR ICALL
KL FAR PCHL
LOW JUMP (RST1)
SIDE CALL (RST2)

Call subroutine in RAM or any ROM.
C and HL contain the ‘far address’ to call.

The far call mechanism allows subroutines to be called anywhere in RAM or in any ROM. This routine takes a 'far address' and calls the given routine setting the requested ROM state and ROM selection.

HL contains the address of the routine to call.
C contains the ROM select byte.
All registers and flags are passed to the target routine untouched except for IY (which is set to point at a background ROM's upper data area).

IY preserved.
All other registers and flags are as set by the target routine.

The ROM select byte takes values as follows:

• #00..#FB: Select the given ROM, enable upper, disable lower.
• #FC: No change of ROM selection, enable upper, enable lower.
• #FD: No change of ROM selection, enable upper, disable lower.
• #FE: No change of ROM selection, disable upper, enable lower.
• #FF: No change of ROM selection, disable upper, disable lower.

Registers are passed to the target routine untouched except for the IY index register. When entering a background ROM this is set to point at the base of the ROM's upper data area. (See section 10.4 and KL INIT BACK).

When the target routine returns, the ROM select and ROM state are restored to what they were before the call. This is accomplished by pushing values onto the stack and so care should be taken when indexing up the stack after using this routine. (The stack usage is 4 bytes for ROM select bytes in the range #FC..#FF and 6 bytes for ROM select bytes in the range #00.. #FB.)

Interrupts are enabled.

FAR CALL (RST3)
KL FAR ICALL
KL LOW PCHL
KL SIDE PCH

Jump to address in HL.

Entry comprises a JP (HL) instruction (or PCHL in some assembler dialects).

HL contains the address to jump to.
All registers and flags are passed to the target routine untouched.

All registers and flags are as set by the target routine.

Calling PCHL INSTRUCTION is a useful way of invoking a routine whose address has been picked out of a table or otherwise established at run time.

KL FAR PCHL
KL LOW PCHL
KL SIDE PCHL
PCBC INSTRUCTION
PCDE INSTRUCTION

LD A,(HL) with all ROMs disabled.

RST 4 is used to extend the instruction set. It is equivalent to a LD A,(HL) instruction except that it always reads from RAM irrespective of whether the ROMs are enabled or not.

HL contains the address of the location to read.

A contains the value read from the given location.
All other registers and flags preserved.

Writing to a location always writes to RAM, even if the location is in one of the ROM areas and the ROM is enabled. The RAM LAM, RST 4, 'instruction' is the read equivalent.

Interrupts are enabled.

KL LDDR
KL LDIR

Call subroutine in RAM or any ROM, HL points at ‘far address’.

The far call mechanism allows subroutines to be called anywhere in RAM or in any ROM. This routine takes the address of a 'far address' and calls the given routine setting the ROM state and ROM selection required.

HL contains the address of the ‘far address’ to call. All registers and flags are passed to the target routine untouched except for IY (which is set to point at a background ROM's upper data area).

IY preserved.
All other registers and flags are as set by the target routine.

The parameter passed is the a ddress of a 3 byte 'far address'. This is laid out as follows:

• Bytes 0..1 give the address of the routine to call.
• Byte 2 is the ROM select byte which takes values as follows:
  • #00..#FB: Select the given ROM, enable upper, disable lower.
  • #FC: No change of ROM selection, enable upper, enable lower.
  • #FD: No change of ROM selection, enable upper, disable lower.
  • #FE: No change of ROM selection, disable upper, enable lower.
  • #FF: No change of ROM selection, disable upper, disable lower.

Registers are passed to the target routine untouched except for the IY index register. When entering a background ROM this is set to point at the base of the ROM's upper data area. (See section 10.4 and KL INIT BACK).

When the target routine returns, the ROM select and ROM state are restored to what they were before the call. This involves pushing values onto the stack and so care should be taken in indexing up the stack after calling this routine. (The stack usage is 4 bytes for ROM select bytes in the range #FC.. #FF and 6 bytes for ROM select bytes in the range #00.. #FB.)

Interrupts are enabled.

KL FAR CALL
KL FAR PCHL

Jump to lower ROM, takes inline address to jump to.

RST 5 is used to ext end the instruction set. It is an expanded form of the jump instruction for jumping to routines in the lower ROM or into the central 32K of RAM. The restart is followed by the address of the routine to jump to.

All registers and flags are passed to the target routine untouched.

All registers and flags are as set by the target routine.

The lower ROM is enabled before the jump is taken and is disabled (rather than restored) when the target routine returns. Neither the upper ROM state nor the ROM selection are changed. Two bytes are pushed onto the stack and so care should be taken when indexing up the stack (to find the address of inline parameters, for example).

It is assumed that the destination of the jump is a routine which will return in the usual way. The restart instruction itself does not return. The value at top of stack when a FIRM JUMP is executed must, therefore, be a return address.

The FIRM JUMP, RST 5, 'instruction' may replace the first byte of a JP (jump) instruction, particularly in jumpblocks, much like a LOW JUMP. A FIRM JUMP is slightly faster than a LOW JUMP but a LOW JUMP is more flexible in dealing with ROM states.

Interrupts are enabled.

LOW JUMP(RST1)

Undedicated RST instruction.

The eight bytes from #0030 to #0037 inclusive maybe patched as required.

Unknown.

Unknown.

If the lower ROM is disabled when an RST 6 instruction is executed then the instructions patched into locations #0030 to #0037 are executed in the normal way.

If the lower ROM is enabled when the RST 6 instruction is executed then the firmware disables the lower ROM and jumps to #0030 to execute the instructions planted by the user.

Generally the lower ROM is disabled except while the firmware is active. Since there are no RST 6s in the firmware there should be no problem about the ROM state when a RST 6 is executed. However, to cope with all eventualities, if the lower ROM is found to be enabled when the restart is executed then the ROM state before the lower ROM is disabled is saved in location #002B. If the lower ROM is found to be disabled then location #002B is left untouched. The value stored is suitable to be passed to KL ROM RESTORE to re-enable the ROM (although KL L ROM ENABLE will have the same effect).

The user can detect whether the lower ROM was enabled when the restart was executed if location #002B is set to zero when the RST 6 area is patched and after processing each restart. If #002B is zero when the RST 6 code is entered then the lower ROM was disabled, and if it is non-zero then the lower ROM was enabled.

The default action for RST 6 as set at power-up is to perform a RST 0, i.e. a system reset.

None.

Hardware interrupt entry point.

The Z80 runs in interrupt mode 1, which treats normal interrupts as RST 7 instructions. The firmware interrupt handler looks after the built in regular time interrupt. External interrupts, generated by expansion hardware, are passed on to user supplied software.

No conditions.

All registers and flags preserved.

The user must not use RST 7s as these are dedicated to the processing of interrupts.
If the interrupt is from an external source then the user supplied interrupt routine, EXT INTERRUPT, is called. See section 10 for a fuller discussion of interrupts.
The user may patch this area (#0038..#003A inclusive) to intercept interrupts if it is absolutely necessary (see Appendix XI, particularly section c).

EXT INTERRUPT

External interrupt routine.

The five bytes from #003B to #003F inclusive must be patched by the user if there are going to be any external interrupts. When an external interrupt is detected by the firmware interrupt handler the lower ROM is disabled and the code at #003B is called.

No conditions.

AF, BC, DE and HL corrupt.
All other registers preserved.

When the routine is called interrupts are disabled and they must remain disabled.

Under no circumstances may the user enable interrupts or use the second register set. Before the routine returns it must clear the interrupt source.

See section 11.2 for a discussion of external interrupts.

When an interrupt routine is set up the current contents of #003B..#003F should be copied elsewhere before they are replaced. If, when the routine is called, it discovers that its hardware is not responsible for the interrupt then it should jump to the copy of the previous external interrupt routine (whose hardware may be responsible).

The purpose of an interrupt routine is to clear the interrupt as quickly as possible, and perhaps perform a minimum of processing. While in the interrupt path no further interrupts are acknowledged. If the interrupt generates a substantial work load, then it should be translated into an event, so that the system is not delayed in the interrupt path for any longer than necessary (see section 11.3).

The interrupt routine must be in RAM at addresses lower than #C000 (as the ROM enable and disable routines cannot be called from the interrupt path).

The default external interrupt routine merely returns. This means that the interrupt will not be cleared and so it will repeat as soon as interrupts are re-enabled. This will cause the machine to 'lock up'.

INTERRUPT ENTRY
KL EVENT

AMSDOS uses the CP/M BIOS to access the disc. In order that a program running under AMSDOS may access the disc directly nine of the BIOS extended jumpblock routines are available.

The routines are accessed as external commands. To find the address of the required routines use KL FIND COMMAND. The command names are single control characters (Ctrl A to Ctrl I) as these cannot be typed in from BASIC. An example of how to use these commands can be found in section 10.7.

N.B. The BIOS extended jumpblock itself is not available, indeed it does not exist in an AMSDOS environment.

The BIOS routines available and their command names are as follows:

• SET MESSAGE Ctrl A (#01)
• SET UP DISC Ctrl B (#02)
• SELECT FORMAT Ctrl C (#03)
• READ SECTOR Ctrl D (#04)
• WRITE SECTOR Ctrl E (#05)
• FORMAT TRACK Ctrl F (#06)
• MOVE TRACK Ctrl G (#07)
• GET DR STATUS Ctrl H (#08)
• SET RETRY COUNT Ctrl I (#09)

The word at #BE40 contains the address of the disc parameter header vector. Disc parameter headers and extended disc parameter blocks may be patched as required. For more details on this see section 9.9.

When one of these routines fails (carry false) it returns an error number in the A register. This is referred to in the following pages as the “error status byte”. If bit 7 of this byte is set then the error has already been reported to the user. Bit 6 is used to distinguish errors generated by the floppy disc controller from those generated by AMSDOS.

If bit 6 is zero then the error numbers are as follows:

• #0E the file is not open as expected.
• #0F hard end of file.

• #10 bad command, usually caused by an incorrect filename.
• #11 file already exists.
• #12 file doesn't exist.
• #13 directory is full.
• #14 disc is full.
• #15 disc has been changed with files open on it.
• #16 file is read-only

• #1A soft end of file (explained in Appendix XIII).

Also V1.1 machines have error #00.

• #00 user has hit escape

If bit 6 is one then the error was detected by the floppy disc controller and the other bits are returned as follows:

• bit 5 data error - CRC error on data or ID field
• bit 4 overrun error
• bit 3 drive not ready - there is no disc in the drive
• bit 2 no data - can't find the sector
• bit 1 not writable - disc is write protected
• bit 0 address mark missing

In addition the routine may also return the address of the “error status buffer”. The first byte of this is a count of the number of bytes received during the results phase of the mPD765A disc controller, the following bytes are those received. For information on the meaning of these bytes see the manufacturer's documentation.

On the following pages are the interfaces to the intercepted routines:

Enable or disable the disc error messages.

When disc error messages are enabled and an error occurs the BIOS will display error messages on the screen and interact with the user. When disabled no messages are displayed.

• If messages are to be enabled: A= #00
• If messages are to be disabled: A= #FF

A contains previous state.
HL and flags corrupt.
All other registers preserved.

The default state is ENABLED.

SET RETRY COUNT

Set disc parameters.

Sets the values for the motor on, motor off, write current off and head settle times.
Sends a SPECIFY command to the floppy disc controller.

HL contains address of parameter block.

Format of the parameter block:

• bytes 0, 1 motor on timeout in 20 millis econd units.
• bytes 2, 3 motor off timeout in 20 millisecond units.
• byte 4 write current off time in 10 microsecond units.
• byte 5 head settle time in 1 millisecond units.
• byte 6 step rate time in 1 millisecond units.
• byte 7 head unload delay (as per mPD765A SPECIFY command).
• byte 8 bits 7.. 1: head load delay, bit 0: non-DMA mode (as per mPD765A SPECIFY command).

AF, BC, DE and HL corrupt.
All other registers preserved.

The values given are used for both drives. When using two differing drives use the slower of the two times.

The default values are:

A motor on time of zero will lock the system up. A motor off time of zero will never turn the motor off.
The standard boot program calls this routine to reset some of the disc parameters as specified in the configuration sector, that is, motor on and off timeouts and the step rate.

SELECT FORMAT
SET RETRY COUNT

Select a disc format.

This routine initializes the extended disc parameter block for the given format.
Normally the BIOS automatically detects the format of a disc when SELDSK is called by looking at the sector numbers, but for programs such as formatters it is necessary to pre-set the format.

A contains first sector number of required format :

• #41 ⇒ system format
• #C1 ⇒ data only format
• #01 ⇒ IBM format

E contains drive number:

• #00 ⇒ A:
• #01 ⇒ B:

AF, BC, DE and HL corrupt.
All other registers preserved.

Bytes 0..21 of the extended disc parameter block are completely reset, all previous values are lost. Bytes 22..24 (track, align flag, auto-select flag) are not affected. See chapter 2.15.

To set a non-standard format the user may patch the extended disc parameter block directly.

Read a sector from disc.

Read the specified sector into store.

• HL contains address of sector buffer
• E contains drive number
• #00 ⇒ A:
• #01 ⇒ B:
• D contains track number
• C contains sector number

If sector read OK:

• Carry true.
  A contains 0
  HL preserved

If failed to read sector correctly:

• Carry false.
  A contains error status byte (as defined above).
  HL contains address of error status buffer.

Always
Other flags corrupt.
All other registers preserved.

The sector buffer may lie anywhere in RAM, even under a ROM.

WRITE SECTOR

Write a sector to disc.

Write the required sector from store.

• HL contains address of sector buffer
• E contains drive number
• #00 ⇒ A:
• #01 ⇒ B:
• D contains track number
• C contains sector number

If sector written OK:

• Carry true.
  A contains 0.
  HL preserved.

If failed to write sector correctly:

• Carry false.
  A contains error status byte as defined above.
  HL contains address of error status buffer.

Always:
Other flags corrupt.
All other registers preserved.

The sector buffer may be anywhere in RAM, even underneath a ROM.

READ SECTOR

Format an enti re track.

Format a track.

• HL contains address of header information buffer
• E contains drive number
• #00 ⇒ A:
• #01 ⇒ B:
• D contains track number

Format of header information:

• sector entry for first sector
• sector entry for second sector
• …
• sector entry for last sector

sector entry format:

If track formatted OK:

• Carry true.
  A contains 0.
  HL preserved.

If failed to format track correctly:

• Carry false.
  A contains error status byte as defined above.
  HL contains address of error status buffer.

Always:
Other flags corrupt.
All other registers preserved.

The extended DPB must be preset for the required format (see SELECT FORMAT)

SELECT FORMAT

Move to specified track.

Move head to specified track without verifying the move.

• E contains drive number
• #00 ⇒ A:
• #01 ⇒ B:
• D contains track number

If moved to track OK:

• Carry true.
  A contains 0.
  HL preserved.

If failed to move to the track:

• Carry false.
  A contains error status byte as defined above.
  HL contains address of error status buffer.

Always:
Other flags corrupt.
All other registers preserved.

This routine is intended as a diagnostic aid and need not normally be used because the read/write/format routines all seek to the correct track automatically.

Return status for specified drive.

This routine return status register 3 of the floppy disc controller as defined below for the specified drive:

A contains drive number

• #00 ⇒ A:
• #01 ⇒ B:

If carry true:

• A contains drive status byte as defined above.
• HL preserved.

If carry false:

• HL contains address of error status buffer, second byte = Drive status byte as described above.
• A corrupt.

Other flags corrupt.
All other registers preserved.

This routine returns carry to indicate which set of exit conditions have occurred. No other meaning should be attached to the state of the carry.

SELECT FORMAT
READ SECTOR
WRITE SECTOR
FORMAT TRACK
MOVE TRACK

Set the number of retries for reading/writing/formatting.

Sets the number of times an operation is retried in the event of an error.

A contains the new value for retry count.

• A contains old value of retry count.
• HL and flags corrupt.

All other registers preserved.

The pattern of retries is as follows. Each ‘Try’ counts one. The retry pattern is repeated until either the operation succeeds or the number of tries has reached the retry count:

• Try
• Try
• Move in one track and back again
• Try
• Move out one track and back again
• Try
• Move to inner track and back again
• Try
• Try
• Move in one track and back again
• Try
• Move out one t rack and back again
• Try
• Move to outer track and back again
• Repeat

The default value is 16, i.e. twice around the above loop.

READ SECTOR
WRITE SECTOR
FORMAT TRACK

The disc ROM contained in the 664/6128 and DDI-1 interface contains a number of external commands. These may be found by using KL FIND COMMAND as described in section 10. Facilities available include switching between drive A and B, switching between the tape and disc operating system, cold booting into CPM, displaying a directory of a disc, and erasing and renaming files.

When using the following commands under BASIC they should be preceded by ‘|’ (obtained by pressing shift and @ together on a QWERTY keyboard) or ‘ù’ (on an AZERTY keyboard) to indicate that they are external commands. When calling KL FIND COMMAND the ‘|’ or ‘ù’ should not be used.

Since these commands are designed to be called from BASIC they use the parameter block mechanism for passing parameters to them (as described in sections 10.6 and 10.7). Briefly, the parameter block is pointed at by IX and A contains the number of parameters supplied. IX points at the last parameter and preceding parameters are at positive offsets from IX. The value stored in the parameter block for an integer parameter is the integer itself, and the value stored for a string parameter is the address of the string descriptor. The first byte of the string descriptor is the length of the string; the second and third bytes are a pointer to the characters. The routine will corrupt registers AF, BC, DE, HL, IX and IY.

The external commands contained in the disc ROM are:

Set the default drive to drive A.

None.

• This command is equivalent to the DRIVE command with 'A' as a parameter.
• This command will fail if AMSDOS is unable to determine the format of the disc in drive A. In which case the default drive will not be changed.
• When AMSDOS is initialized the default drive is set to drive A.

B
DRIVE

Set the default drive to drive B.

None.

• This command is equivalent to the DRIVE command with 'B' as a parameter.
• The command will fail if AMSDOS is unable to determine the format of the disc in drive B. In which case the default drive is not changed.
• When AMSDOS is initialized the default drive is set to drive A.

A
DRIVE

This command shuts down BASIC and AMSDOS and cold boots CP/M.

None.

• MC START PROGRAM is used so all ticker chains etc are lost.
• The CP/M utility AMSDOS.COM performs the inverse function and restores AMSDOS and BASIC.
• This command can also be used to boot any program that uses the CP/M bootstrap mechanism as described in section 9.5.

None.

Display the disc directory.

One optional string parameter.

• The parameter is a filename, possibly containing wild cards, only those files which match this filename are displayed. If the parameter is omitted then '*.*' is assumed.
• The total amount of free space on the disc is shown in Kbytes.
• The directory is displayed in as many columns as will fit in the text window of the currently selected stream.
• Files marked SYS are not shown.
• Files without an extent zero are not shown.
• Unlike CAS CATALOG (DISC) the directory is neither sorted nor are the sizes shown. The output is similar to that of the CP/M DIR command.

A
B
DRIVE
USER

This command redirects both the tape input and output firmware entries to their disc counterparts.

None

The redirected firmware entries are:

• CAS IN OPEN
• CAS IN CLOSE
• CAS IN ABANDON
• CAS IN CHAR
• CAS IN DIRECT
• CAS RETURN
• CAS TEST EOF
• CAS CATALOG
• CAS OUT OPEN
• CAS OUT CLOSE
• CAS OUT ABANDON
• CAS OUT CHAR
• CAS OUT DIRECT

DISC is equivalent to the two commands DISC.IN and DISC.OUT.

DISC.IN
DISC.OUT
TAPE
TAPE.IN
TAPE.OUT

This command redirects the tape input firmware entries to their disc counterparts.

None

The redirected firmware entries are:

• CAS IN OPEN
• CAS IN CLOSE
• CAS IN ABANDON
• CAS IN CHAR
• CAS IN DIRECT
• CAS RETURN
• CAS TEST EOF
• CAS CATALOG

DISC
DISC.OUT
TAPE
TAPE.IN
TAPE.OUT

This command redirects the tape output firmware entries to their disc counterparts.

None.

The redirected firmware entries are:

• CAS OUT OPEN
• CAS OUT CLOSE
• CAS OUT ABANDON
• CAS OUT CHAR
• CAS OUT DIRECT

DISC
DISC.IN
TAPE
TAPE.IN
TAPE.OUT

Set the current default drive.

One string parameter.

• The string parameter must be a single letter in the range ‘A’ to ‘P’ or ‘a’ to ‘p’.
• Drives ‘C’ to ‘P’ are for future enhancement.
• The command will fail if AMSDOS is unable to determine the format of the disc in the requested drive. In which case the default drive will remain unchanged.
• When AMSDOS is initialized the default drive is set to drive A.

A
B

Erase files.

One string parameter.

• The string parameter is a filename, possibly containing wild cards. All files which match this filename are erased.
• A file which matches the filename but is marked R/O will not be erased. In this event a message is displayed for each 16K (extent) of the file.
• If none of the files on the disc match the filename then an error message is displayed.

A
B
DRIVE
USER

Rename a file.

Two string parameters.

• The first string parameter is the new name for the file. A file of this name must not already exist. The second parameter is the name of the file to be renamed.
• Neither name may contain wild cards.
• Both files must be on the same drive.
• The files may be in different users.
• If the file to be renamed is marked R/O then an error message is displayed and the file is not renamed.
• The renamed file will have attributes R/W DIR regardless of the original file's attributes. If the file to be renamed does not exist then an error message is displayed.

A
B
DRIVE
USER

This command restores the tape firmware entries to the state they were before AMSDOS was initialized.

None.

The restored firmware entries are:

• CAS IN OPEN
• CAS IN CLOSE
• CAS IN ABANDON
• CAS IN CHAR
• CAS IN DIRECT
• CAS RETURN
• CAS TEST EOF
• CAS CATALOG
• CAS OUT OPEN
• CAS OUT CLOSE
• CAS OUT ABANDON
• CAS OUT CHAR
• CAS OUT DIRECT

TAPE is equivalent to the two commands TAPE.IN and TAPE.OUT.

Note that any patches made to the jumpblock entries for these routines made before a DISC, DISC.IN or DISC.OUT command was executed will be lost. However, any patches made to these entries before AMSDOS was initialized will be restored.

DISC
DISC.IN
DISC.OUT
TAPE.IN
TAPE.OUT

This command restores the tape input firmware entries to the state they were before AMSDOS was initialized.

None.

The restored firmware entries are:

• CAS IN OPEN
• CAS IN CLOSE
• CAS IN ABANDON
• CAS IN CHAR
• CAS IN DIRECT
• CAS RETURN
• CAS TEST EOF
• CAS CATALOG

Note that any patches to the jumpblock entries for these routines made before a DISC or DISC.IN command was executed will be lost. However, any patches made to these entries before AMSDOS was initialized will be restored.

DISC
DISC.IN
DISC.OUT
TAPE
TAPE.OUT

This command restores the tape output firmware entries to the state they were before AMSDOS was initialized.

None.

The restored firmware entries are:

• CAS OUT OPEN
• CAS OUT CLOSE
• CAS OUT ABANDON
• CAS OUT CHAR
• CAS OUT DIRECT

Note that any patches to the jumpblock entries for these routines made before a DISC or DISC.OUT command was executed will be lost. However, any patches made to these entries before AMSDOS was initialized will be restored.

DISC
DISC.IN
DISC.OUT
TAPE
TAPE.IN

Set the default user number.

One integer parameter.

The user number must be in the range 0 to 15. Any other parameter will cause an error and the default user will remain unchanged. When AMSDOS is initialized the default user number is set to 0.

DIR
ERA
REN

Function keys are more fully explained in section 3, and in section 3.7 in particular. The following table specifies the default string for each expansion token and which key the token is associated with by default.

Tokens 13..31 are all set to empty strings and none of them are defaulted to associate with a key.
ø stands for carriage return (character #0D)

A full discussion of inks and colours can be found in section 6.2. This appendix lists the colours that are available and the default settings for the inks.

There are 27 colours available. The Screen Pack refers to these colours by a grey scale number so that colour 0 is the darkest and colour 26 is the brightest. The hardware requires these grey scales to be translated into the hardware code for the colour. It is unlikely that the user will ever need to deal with the hardware numbers, they are merely given for information.

The user can set the colours in which the 16 inks and the border are displayed.

I'm looking for a copy of this appendix.

Character values in the range 0-31 sent to the main Text VDU output routine (TXT OUTPUT) do not produce a character on the screen, but are interpreted as control codes. These codes may affect the meaning of one or more of the following characters, which are the code's parameters.

All control codes work on the currently selected stream unless otherwise indicated. For instance, setting the pen, code 15, sets the text pen ink for the currently selected stream whilst setting the colour of an ink, code 28, will affect all streams (and the Graphics VDU).

Certain codes force the current position (the cursor position) to a legal position inside the current window before they are obeyed. This is explained in more detail in section 4.5. The cursor may be left in an illegal position.

The following table specifies the default actions for the control codes. By changing entries in the control code table the action of these codes can be altered as desired. See section 4.7 for a full description.

I'm looking for a copy of this appendix.

I'm looking for a copy of this appendix.

A facility is provided whereby special characters which may appear on the screen and which are supported by the AMSTRAD DMP-1, will be printed even though the character codes for the screen and printer may be different. The majority of these symbols will only be available when the printer is switched to one of its foreign language modes.

For example, if a circumflex is to be printed then the character code for the screen would be &A0 but on the printer it is &5E, if a n &A0 was sent to the printer it would be translated into a &5E thus printing a circumflex. The following table shows all the default translation codes:

The default translation table only translates the additional characters in the character set (#A0… #AF). It does not translate any of the standard ASCII characters or the graphics characters.