1 - Spectrum Memory Map Overview

The following table is an overview of the Spectrum Memory map for both 48K and 128K/+2 machines. The +2A and +3 are similar to the 128K but have additional ROM's and alternate all RAM memory layouts. The specifics for the individual machines are listed in their own sections.

Memory Contention

Some memory is contended with the ULA, with the latter having priority whenever the screen is being updated. Time critical code needs to run in uncontended RAM.

On the 48K memory between 0x4000…0x7FFF is contended with the ULS whilst 0x8000…0xFFFF is not.

On the 128K and +2, odd numbered RAM banks are contended with the ULA. Time critical code should run in even numbered RAM banks.

1.1 - Spectrum +2A/+3 Memory Map

The memory of the +2A and +3 are similar to the 128K and +2. The main difference is that these models have four ROMs rather than two and additional memory configurations.

The memory is paged by writing to port 0x7FFD and port 0x1FFD. Port 0x7FFD is almost identical to the 128 except that ROM is now the lower bit.

Both of these ports are write only, so a copy is stored in ram at address 0x5B5C for 7FFD and 0x5B67 for port 1FFD.

• Bit 0 of port 0X1FFD selects the paging mode. If 0 then it's normal but 1 selects an alternate memory map.

  Normal mode

  • RAM - The ram bank to page into 0xC000…0x7FFFF
  • ROM set selects the rom. It's split as 2 bits on each port with bit 0 from 7FFD bit 4 and bit 1 from 1FFD bit 2.

    Rom ID	Rom Selected
    0	128K editor, menu system and self test
    1	128k syntax checker
    2	+3DOS
    3	48K Basic

    The IDs are such that, if 128K code changes rom (as they don't know about the new register) then they would still get the correct rom as bit 0 is from the original port and bit1 would normally be clear at that point.

  Special mode

  In special mode, the RAM bits are ignored and bits 1 and 2 of port 0x1FFD control a memory map layout

  Address	Mode 0	Mode 1	Mode 2	Mode 3
  0000	Bank 0	Bank 4	Bank 4	Bank 4
  4000	Bank 1	Bank 5 Screen #1	Bank 5 Screen #1	Bank 7 Screen #2
  8000	Bank 2	Bank 6	Bank 6	Bank 6
  C000	Bank 3	Bank 7 Screen #2	Bank 3	Bank 3

• SCR set to 0 to display screen #1 in bank 5. Set to 1 to display screen #2 in bank 7.
• DIS if set disables ram paging so that extra memory cannot be used in 48K mode. Once set it cannot be disabled until the machine is reset.
• Disk Motor turns on/off the disk drive motor.
• Printer Strobe controls the printer port

Plus 3

On the Plus 3 ram bankes 1, 3, 4 and 6 are used for the disk cache and RAM disk. Bank 7 contains the editor scratch pads and +3DOS workspace.

1.2 - Spectrum 128K/+2 Memory Map

The memory of the 128K and +2 is organised like below. Note the +2A and +3 are different.

RAM Banks 1, 3, 4 and 6 and most of 7 are used for the ram disk. The rest of bank 7 contains editor scratch pads.

The memory is paged by writing to port 0x7FFD.

This port is write only, so a copy is stored in ram at address 0x5B5C.

• RAM - The ram bank to page into 0xC000…0x7FFFF
• SCR set to 0 to display screen #1 in bank 5.^[3] Set to 1 to display screen #2 in bank 7.^[4]
• ROM set selects the 48K Basic rom, clear the 128K editor.
• DIS if set disables ram paging so that extra memory cannot be used in 48K mode. Once set it cannot be disabled until the machine is reset.

1.3 - Spectrum 48K Memory Map

1.4 - Spectrum Basic Memory Map

The following table shows the memory map of the Spectrum as seen by BASIC.

2 - OS Calls

Unlike most manufacturers, the spectrum rom doesn't have many standard rom entry points with most of them undocumented. This meant that the addresses changed between the different machines.

For example, all 48K Spectrum's had the same ROM, so you were almost guaranteed to be able to use the same routine on different machines. However, the 128K introduced 2 roms so there had to be differences. With the +2A/+3 came 4 roms and to complicate things there exists an English and Spanish version of these roms with different addresses.

Unless otherwise specified, the entry points in this section will be for the 48K Spectrum as that has more documentation available.

The only common entry points (known so far) are the RST entry points, as these are also used by the processor's RST instruction.

2.1 - Calculator

RST 5 on a 48K Spectrum enters the floating point calculator.

2.2 - Clear the screen

This entry point clears the screen.

Unless you need to keep compatibility with BASIC, it's better and faster to use your own routine for this. An example of how to do this is available in the examples section: Clear Screen Example

2.3 - Collect Character restarts

RST 3 returns the character addressed by CHADD returning it if it's printable. If it is not printable then CHADD is incremented until a printable character is found.

RST 4 increments CHADD first before returning the next printable character.

These two resets are used in multiple places in the ROM, the BASIC tokenizer being one of them.

2.4 - ERROR

RST 1 can be used to stop a program with an error

2.5 - Make BC Spaces

RST 6 reserves memory in the workspace

On Entry

BC holds the number of bytes to create

On Exit

DE holds the first byte of the new free space.

HL holds the last byte of the new free space.

2.6 - Maskable Interrupt

RST 7 is also the Maskable Interrupt handler

It increments the real time clock in the FRAMES variable once every 20ms (UK).

It also scans the keyboard.

2.7 - PRINT_A

RST 2 is usually used to write to the current channel, usually the screen.

Internally, RST 2 calls the routine in the CHURCHL vector, returning with all registers preserved unless an error occurred.

Implementing custom channels

Because the rom code uses the CHURCHL vector you can easily replace the current output channel with your own code.

My Teletext emulator does this to allow code to write to the new screen using RST 2.

2.8 - START

Called when the machine is first started, RST 0 can be used to restart the machine.

3 - Screen

Screen Layout

The screen has a fixed resolution of 256x192 pixels or 32x24 characters. Colour is restricted to 8x8 pixel squares equivalent to each character.

It is located in memory at address 0x4000…0x5AFF and is split into two parts:

128K Spectrum's

The 128K Spectrum's have a second screen in RAM Bank #7 which can be used as an alternate to the default one which is in RAM Bank #5. The memory layout is the same except for where it appears in the memory map.

This section will refer to the default memory location as used by all Spectrum's.

If you want to use the alternate screen then you need to change the base address to that of the correct bank. These are shown in the memory map's:

• Spectrum 128K and +2 also for +2A and +3 in Normal Mode
• Spectrum +2A and +3 when in Special Mode

3.1 - Display File

The display file contains the pixel data for the screen.

Arranged in a map of 192 rows, each 32 bytes long. Each byte contains 8 pixels.

Be aware, the rows are not stored linearly, but in a way that has been optimised for the ULA.

The first 256 bytes in memory represents the first byte of each character in the first 8 rows, then the second byte of each character, and so on. Once the first 8 rows have been done it repeats twice more for the next 8 rows then the last 8.

Although the memory map for the spectrum screen seems weird with its layout, it's actually pretty logical. You can tell this weirdness is down to how the ULA works internally.

Calculating the characters address

If you have:

• R with the screen row (0…23)
• C with the column (0…31)
• N for the byte offset within the character (0…7)

then you can calculate the address using the following table:

The formula is simple: $$ Address = \left( \overbrace{ ( 0x40 | ( R \And 0x18 ) | N ) }^{MSB} \ll 8 \right) | \left( \overbrace{ ( ( R \And 0x07) \ll 5 ) | C }^{LSB} \right) $$

Pseudo code:

1lsb := ((R << 5) AND 0xC0) OR C
2msb := 0x40 OR (R AND 0x18) OR N

Machine Code:

An example routine in Z80 Machine Code for this calculation is available to download.

Addresses of bytes within the same character

Get address of the next character

You can get the address of the next character simply by adding one to the lower byte of the address. Be careful however when wrapping around the end of the line as, after the first 8 lines the address will fail.

Ideally you should calculate the address again at the start of each line.

This might explain why the original spectrum editor was 8 lines long, as you only needed to set the high byte to an appropriate 8-line block in memory and set the low byte to the offset in the line being edited to get that characters screen address.

A simple 256 character editor

As long as you restrict yourself to one third of the screen you can simply calculate the address within this simple editor by selecting the high byte for the required section of the screen and use the characters position in the line as the low byte.

3.2 - Display Attributes

The display attribute section contains the colour information and occupies addresses 0x5800…0x5AFF.

It's a direct map of the characters on the screen, arranged in 24 rows, each 32 characters long. Each byte consists of the Foreground (INK) and Background (PAPER) colour for all pixels contained within the equivalent position in the Display File.

4 - System Variables

5 - Basic

5.1 - Basic Tokens

BASIC Tokens

This table is currently incomplete, but it is enough for the Machine Code examples.

6 - +3 DOS

+3DOS is the Disk Operating System of the Spectrum +3. It is contained in ROM 2 on those machines and provides support for:

• Support for one or two floppy disk drives and a RAMdisk.
• CP/M Plus and CP/M 2.2 file compatibility.
• AMSTRAD CPC range and PCW range file and media compatibility.
• Up to 16 files open at the same time.
• Reading and writing files to or from any page in memory.
• Byte level random access.
• Deleting disk files; renaming disk files; changing disk files' attributes.
• Selecting the default drive and user.
• Booting a game or operating system.
• Low level access to floppy disk driver.
• Optional mapping of two logical drives (A: or B:) onto one physical drive (unit 0).

Spectrum +2A

The +2A (not the +2) has the exact same ROM's as the +3, it just has a Cassette tape instead of a 3" floppy drive. As such, +3DOS is available but only provides:

• Only drive M: is available (the RAMdisk)
• The default drive for filenames is initialised to M: rather than A:
• Any attempt to use drives A: or B: will fail with error '22 - Drive not found'
• As the sector cache is not required for use with the RAM disk, it is increased to 64K (the whole of pages 1, 3, 4, 6). This will give 62K of data and 2K of directory (64 entries).
• The presence of the floppy disk interface can be determined by calling DD_INTERFACE. If the interface were not present, then none of the other low level floppy disk routines (DD... etc.) could be called; the effect of doing so is undefined.

Another method to determine if a machine is a +3 or a +2A is to inspect bit 4 of FLAGS3 (0x5B66). If the bit is set then a disk interface is present, hence a +3. If the bit is reset then no disk is present, hence a +2A or a +3 with no disk interface or the interface disabled.

CP/M File compatibility

+3DOS uses the CP/M file structure, subject to the following restrictions:

• Maximum file size of 8 megabytes (CP/M Plus supports a maximum of 32 megabytes).
• Maximum drive size of 8 megabytes (CP/M Plus supports a maximum of 128 megabytes).
• Directory labels are ignored.
• No passwords. XFCBs will be erased, renamed, etc., along with their file(s) but are otherwise ignored.
• No date and time stamps. SFCBs are initialised to zero when a file is created, but are otherwise ignored.
• The archive file attribute is ignored, i.e. it is unaffected by all routines except DOS SET ATTRIBUTES.

6.1 - Essential API

6.1.1 - DOS_INITIALISE

Synopsys

• Initialise +3DOS.
• Initialise disk drivers.
• Initialise cache and the RAMdisk.
• All files closed.
• All drives logged out.
• Default drive A: (if disk interface present), else M:
• Default user 0.
• Retry count 15.
• Error messages disabled.

Entry Parameters

None

Exit Parameters

If OK:

Carry true

A corrupt

Otherwise:

Carry false

A=Error code

Always:

BC DE HL IX corrupt, all other registers preserved.

6.1.2 - DOS_VERSION

Synopsys

Get the DOS issue and version numbers.

Entry Parameters

None

Exit Parameters

If OK:

D = Issue

E = Version (within issue)

Otherwise:

Carry false

A=Error code

Always:

BC DE HL IX corrupt, all other registers preserved.

6.1.3 - DOS_OPEN

Synopsys

Create and/or open a file

Entry Parameters

Exit Parameters

If file newly created:

Carry true

Zero true

A corrupt

If existing file opened:

Carry true

Zero false

A corrupt

Otherwise:

Carry false

A=Error code

Always:

BC DE HL IX corrupt, all other registers preserved.

6.1.4 - DOS_CLOSE

Synopsys

Close a file

Entry Parameters

Exit Parameters

If OK:

Carry true

A corrupt

Otherwise:

Carry false

A=Error code

Always:

BC DE HL IX corrupt, all other registers preserved.

6.1.5 - DOS_ABANDON

Synopsys

Abandon a file

Similar to DOS CLOSE, except that any header, or data, or directory data yet to be written to disk is discarded. This routine should only be used to force a file closed in the event that DOS CLOSE is unable to close the file (for example, if the media is damaged or permanently changed or removed).

Entry Parameters

Exit Parameters

If OK:

Carry true

A corrupt

Otherwise:

Carry false

A=Error code

Always:

BC DE HL IX corrupt, all other registers preserved.

6.1.6 - DOS_REF_HEAD

Synopsys

Point at the header data for this file.

The header data area is 8 bytes long and may be used by the caller for any purpose whatsoever. It is available even if the file does not have a header; however, only files with a header and opened with write access will have the header data recorded on disk.

Note that +3 BASIC uses these 8 bytes (see the note under DOS OPEN which gives the details). If creating a file that will subsequently be LOADed within BASIC, then those bytes should be filled with the relevant values.

Entry Parameters

Exit Parameters

If OK:

Carry true

A corrupt

IX = Address of header data

Otherwise:

Carry false

A = Error code

IX corrupt

Always:

BC DE HL corrupt, all other registers preserved.

6.1.7 - DOS_READ

Synopsys

Read bytes from a file into memory, advancing the file pointer in the process.

This routine does not consider any soft-EOF in the file. Attempting to read past the EOF will produce an error.

Entry Parameters

Exit Parameters

If OK:

Carry true

A corrupt

DE corrupt

Otherwise:

Carry false

A = Error code

DE = Number of bytes remaining unread

Always:

BC HL IX corrupt, all other registers preserved.

The value of C is only used when HL is within the upper 16K of memory (0xC000…0xFFFF). If HL is in this range then C is the RAM bank to use. For most purposes C should be set to 0 which is the default RAM bank mapped to that region.

6.1.8 - DOS_Write

Synopsys

Write bytes from memory into a file, advancing the file pointer in the process.

Entry Parameters

Exit Parameters

If OK:

Carry true

A corrupt

DE corrupt

Otherwise:

Carry false

A = Error code

DE = Number of bytes remaining unwritten

Always:

BC HL IX corrupt, all other registers preserved.

The value of C is only used when HL is within the upper 16K of memory (0xC000…0xFFFF). If HL is in this range then C is the RAM bank to use. For most purposes C should be set to 0 which is the default RAM bank mapped to that region.

6.1.9 - DOS_READ_BYTE

Synopsys

Read a byte from a file, advancing the file pointer in the process. It tests for a soft EOF (0x1A) but it is possible to read past this. Reading to the hard EOF will return an error.

Entry Parameters

Exit Parameters

If OK - not soft-EOF (0x1A)

Carry true

Zero false

A corrupt

C Byte read

If OK - soft-EOF (0x1A)

Carry true

Zero true

A corrupt

C Byte read

Otherwise:

Carry false

A = Error code

C corrupt

Always:

BC DE HL IX corrupt, all other registers preserved.

6.1.10 - DOS_WRITE_BYTE

Synopsys

Write a byte to a file, advancing the file pointer in the process.

Entry Parameters

Exit Parameters

If OK

Carry true

A corrupt

Otherwise:

Carry false

A = Error code

Always:

BC DE HL IX corrupt, all other registers preserved.

6.1.11 - DOS_CATALOG

Synopsys

Fills a buffer with part of the directory (sorted).

The filename specifies the drive, user and a (possibly ambiguous) filename.

Since the size of a directory is variable (and may be quite large), this routine permits the directory to be catalogued in a number of small sections. The caller passes a buffer pre-loaded with the first required filename, or zeroes for the start of the directory. The buffer is loaded with part (or all, if it fits) of the directory sorted in ASCII order. If more of the directory is required, this routine is re-called with the buffer re-initialised with the last file previously returned. This procedure is followed repeatedly until all of the directory has been catalogued.

Note that +3DOS format disks (which are the same as single-sided, single track AMSTRAD PCW range format disks) may have a maximum of 64 directory entries.

Entry Parameters

Exit Parameters

If OK:

Carry true

A corrupt

B number of completed entries in buffer, 0…n.
If B=n then there may be more entries for subsequent calls

Otherwise:

Carry false

A=Error code

B corrupt

Always:

C DE HL IX corrupt, all other registers preserved.

Buffer format

The buffer passed to this routine consists of 2 or more entries, with the first one initialised with the first filename required. It is valid for the first entry to be all zero's.

If the buffer is too small for the directory then it can be called again with entry 0 being a copy of entry n from the previous call.

The file size is the disk space allocated, not the actual file size.

6.1.12 - DOS_FREE_SPACE

Synopsys

Return the amount of free space on a drive.

Entry Parameters

Exit Parameters

If OK:

Carry true

A corrupt

HL = Free space in KB

Otherwise:

Carry false

A=Error code

HL corrupt

Always:

BC DE IX corrupt, all other registers preserved.

6.1.13 - DOS_DELETE

Synopsys

Delete an existing file.

The file must not be open on any file number.

Entry Parameters

Exit Parameters

If OK:

Carry true

A corrupt

Otherwise:

Carry false

A=Error code

Always:

BC DE HL IX corrupt, all other registers preserved.

6.1.14 - DOS_RENAME

Synopsys

Return the amount of free space on a drive.

Entry Parameters

Exit Parameters

If OK:

Carry true

A corrupt

HL = Free space in KB

Otherwise:

Carry false

A=Error code

HL corrupt

Always:

BC DE IX corrupt, all other registers preserved.

6.1.15 - DOS_BOOT

Synopsys

Boot from Disk

This routine loads a single bootstrap sector from the disk in drive A: into memory and enters it. This is for loading games or other operating systems.

Entry Parameters

None

Exit Parameters

If OK:

No exit as the bootstrap has taken over

Otherwise:

Carry false

A=Error code

Always:

BC DE HL IX corrupt, all other registers preserved.

Bootstrap environment

6.1.16 - DOS_SET_DRIVE

Synopsys

Set the default drive (i.e. the drive implied by all filenames that do not specify a drive).

The default drive is initially A:

Does not access the drive, but merely checks that there is a driver for it (which does not imply that the drive exists).

This only affects routines that take filename parameters.

Entry Parameters

Exit Parameters

If OK:

Carry true

A = default drive

Otherwise:

Carry false

A=Error code

Always:

BC DE HL IX corrupt, all other registers preserved.

6.1.17 - DOS_SET_USER

Synopsys

Set the default user area, i.e. the user area implied by all filenames that do not specify a user number.

The default user number is initially 0.

This only affects routines that take filename parameters.

Entry Parameters

Exit Parameters

If OK:

Carry true

A = default user

Otherwise:

Carry false

A=Error code

Always:

BC DE HL IX corrupt, all other registers preserved.

6.2 - Additional API

6.2.1 - DOS_GET_POSITION

Synopsys

Returns the current position in the file

Entry Parameters

Exit Parameters

If OK

Carry true

A corrupt

E HL = File pointer 0x000000…0xFFFFFF (16Mb)
E is most significant byte, L least

Otherwise:

Carry false

A = Error code

E HL = Corrupt

Always:

BC D IX corrupt, all other registers preserved.

6.2.2 - DOS_SET_POSITION

Synopsys

Sets the file pointer. This does not access the disk, nor does it check if the file pointer is >= 8 megabytes.

Entry Parameters

Exit Parameters

If OK

Carry true

A corrupt

Otherwise:

Carry false

A = Error code

Always:

BC DE HL IX corrupt, all other registers preserved.

6.2.3 - DOS_GET_EOF

Synopsys

Get the end of file (EOF) file position greater than all written byte positions. Does not affect the file pointer. Does not consider soft-EOF.

Entry Parameters

Exit Parameters

If OK

Carry true

A corrupt

E HL = File pointer 0x000000…0xFFFFFF (16Mb)
E is most significant byte, L least

Otherwise:

Carry false

A = Error code

E HL = Corrupt

Always:

BC D IX corrupt, all other registers preserved.

6.2.4 - DOS_GET_1346

Synopsys

Get the current location of the cache and RAMdisk.

Pages 1, 3, 4, 6 are considered as an array of 128 sector buffers (numbered 0...127), each of 512 bytes. The cache and RAMdisk occupy two separate (contiguous) areas of this array.

Any unused sector buffers may be used by the caller.

Note that the sizes may be smaller than those specified in DOS_SET_1346, as there is an (unpublished) maximum size of cache and a minimum size of RAMdisk (4 sectors).

Entry Parameters

None

Exit Parameters

D = First buffer of cache

E = Number of cache sector buffers

H = First buffer of RAM disk

L = Number of RAM disk sector buffers

Always:

AF BC IX corrupt, all other registers preserved.

6.2.5 - DOS_SET_1346

Synopsys

Rebuild the sector cache and RAM disk.

This routine is used to make some store available to the user, or to return store to DOS. Note that if the RAM disk is moved, or its size is changed, then all files thereon are erased.

Pages 1, 3, 4, 6 are considered as an array of 128 sector buffers (numbered 0...127), each of 512 bytes. The cache and RAMdisk occupy two separate (contiguous) areas of this array.

The location and size of the cache and RAMdisk can be specified separately; any remaining buffers are unused by DOS and are available to the caller.

Note that the sizes actually used may be smaller than those specified as in practice, there is a maximum cache size and a minimum size of RAMdisk (4 sectors).

A cache size of 0 will still work but will seriously impair the floppy disk performance.

This routine will fail if there are any files open on drive M:

Entry Parameters

Exit Parameters

If OK

Carry true

A corrupt

Otherwise:

Carry false

A = Error code

Always:

BC DE HL IX corrupt, all other registers preserved.

6.2.6 - DOS_FLUSH

Synopsys

Write any pending headers, data, directory entries for this drive.

This routine ensures that the disk is up-to-date. It can be called at any time, even when files are open.

Entry Parameters

Exit Parameters

If OK

Carry true

A corrupt

Otherwise:

Carry false

A = Error code

Always:

BC DE HL IX corrupt, all other registers preserved.

6.2.7 - DOS_SET_ACCESS

Synopsys

Try to change the access mode of an open file.

This routine will fail if the file is already open, in an incompatible access mode, or if write access is required for a read-only file or disk.

Entry Parameters

Exit Parameters

If OK

Carry true

A corrupt

Otherwise:

Carry false

A = Error code

Always:

BC DE HL IX corrupt, all other registers preserved.

6.2.8 - DOS_SET_ATTRIBUTES

Synopsys

Set a file's attributes.

Only the file attributes f1'...f4', t1'...t3' can be set or cleared. The interface attributes f5'...f8' are always 0.

This routine first sets the attributes specified in D, then clears those attributes specified in E, i.e. E has priority.

Entry Parameters

Exit Parameters

If OK

Carry true

A corrupt

Otherwise:

Carry false

A = Error code

Always:

BC DE HL IX corrupt, all other registers preserved.

6.2.9 - DOS_OPEN_DRIVE

Synopsys

Open the disk in this drive as a single file.

The whole disk is presented as a single file regardless of any real files on the disk. This routine can be used to examine/poke directories, files, etc. It should not be used by the uninitiated, the faint-hearted, or by anyone who values their files!

Sets file pointer to 0x000000 (0).

If there are any files open on this drive from other file numbers with shared-read access, then the disk can only be opened with shared-read access from this file number.

If there are any file open on this drive from other file numbers with exclusive access, then the disk cannot be opened from this file number.

Entry Parameters

Exit Parameters

If OK

Carry true

A corrupt

Otherwise:

Carry false

A = Error code

Always:

BC DE HL corrupt, all other registers preserved.

6.2.10 - DOS_SET_MESSAGE

Synopsys

Enable/disable disk error messages.

This should be used to make +3DOS aware of your own ALERT subroutine. When +3DOS detects an error, it will call your ALERT subroutine, passing to it the values documented below. The ALERT subroutine should print the text of the message that +3DOS passes it, then should wait for the user to press a key. If the key is in the reply string (that +3DOS also passes - version V1.0 only), then a 'ret' should be made with A = 0, 1 or 2, or containing the character (depending on the version of +3DOS).

Entry Parameters

Exit Parameters

HL = address of previous ALERT routine, 0 if none

Always:

AF BC DE IX corrupt, all other registers preserved.

ALERT implementations

Note that if you are substituting your own ALERT subroutine, the 'entry conditions' are the conditions passed to your subroutine and the 'exit conditions' are the values that your subroutine must produce and the registers you are allowed to corrupt.

There are two routine interfaces for ALERT, depending on which version of +3DOS is installed.

If you provide an ALERT function, you should have two subroutines, or one with switchable entry and exit conditions, and check the +3DOS version number before deciding which one to use.

+3DOS V1.0

Entry Parameters

Exit Parameters

A = Reply character

Always:

F BC DE HL IX corrupt, all other registers preserved.

+3DOS V1.1 and above

The second version allows the user to provide non-UK error messages and is generally more flexible, is present in +3DOS versions V1.1 and upwards.

Entry Parameters

Exit Parameters

A = Reply
0 = cancel
1 = retry
2 = ignore

Always:

F BC DE HL IX corrupt, all other registers preserved.

6.2.11 - DOS_REF_XDPB

Synopsys

Point at the XDPB for this drive. (The XDPB is required by the floppy disk driver routines.)

Entry Parameters

Exit Parameters

If OK:

Carry true

A corrupt

IX = Address of XDPB

Otherwise:

Carry false

A=Error code

IX corrupt

Always:

BC DE HL corrupt, all other registers preserved.

6.2.12 - DOS_MAP_B

Synopsys

Map drive B: to unit 0 or unit 1. This routine will fail if drive B: has files open.

If mapping B: to unit 0, then each time unit 0 is accessed, a check is made that the drive mapping is correct. If it isn't, then a reverse call to CHANGE DISK is made, to ask the user to change the disk in unit 0.

If mapping B: to unit 1, then if unit 1 does not exist, drive B: is disabled.

Entry Parameters

Exit Parameters

If OK:

Carry true

A corrupt

HL = Address of previous change disk routine, 0 if none

Otherwise:

Carry false

A corrupt

HL corrupt

Always:

BC DE IX corrupt, all other registers preserved.

Change Disk routine

If you are substituting your own CHANGE DISK subroutine, the 'entry conditions' are the conditions passed to your subroutine, and the 'exit conditions' are registers you are allowed to corrupt.

Entry Parameters

Exit Parameters

Always:

AF BC DE IX corrupt, all other registers preserved.

6.3 - Low Level API

The following are the floppy disk driver routines. The unit number is 0…3 for the uPD765A. On the +3, unit 0 is drive A: and unit 1 is drive B:, or optionally, both A: and B: may be mapped onto unit 0. Units 2 and 3 are not used.

With the exception of DD_INTERFACE, none of these routines may be called if the floppy disk interface is not present.

All routines assume that interrupts are enabled on entry, and will still be enabled on exit.

6.3.1 - DD_INTERFACE

Synopsys

Is the floppy disk drive interface present?

This information is also held by BASIC in bit 4 of the FLAGS3 system variable.

Entry Parameters

None

Exit Parameters

If present

Carry true

Otherwise:

Carry false

Always:

A BC DE HL IX corrupt, all other registers preserved.

6.3.2 - DD_INIT

Synopsys

Initialise the disk driver

Entry Parameters

None

Exit Parameters

Always:

AF BC DE HL IX corrupt, all other registers preserved.

6.3.3 - DD_SETUP

Synopsys

Set up disk parameters. Send a specify command.

Entry Parameters

Exit Parameters

Always:

AF BC DE HL IX corrupt, all other registers preserved.

6.3.4 - DD_SET_RETRY

Synopsys

Set the try and retry count. A value of 1 will try the operation once with no retries.

Entry Parameters

Exit Parameters

Always:

AF BC DE HL IX corrupt, all other registers preserved.

6.3.5 - DD_READ_SECTOR

Synopsys

Read a sector

Entry Parameters

Exit Parameters

If OK:

Carry true

A corrupt

Otherwise:

Carry false

A = Error code

Always:

BC DE HL IX corrupt, all other registers preserved.

6.3.6 - DD_WRITE_SECTOR

Synopsys

Write a sector

Entry Parameters

Exit Parameters

If OK:

Carry true

A corrupt

Otherwise:

Carry false

A = Error code

Always:

BC DE HL IX corrupt, all other registers preserved.

6.3.7 - DD_CHECK_SECTOR

Synopsys

Check a sector. (Uses the uPD765A scan equal command.)

Checks that the sector on disk is the same as the copy in memory.

Note that FFh (255) on disk or in memory always matches anything (see uPD765A specification for further details).

Entry Parameters

Exit Parameters

If OK & Equal:

Carry true

Zero true

A corrupt

If OK & Not Equal:

Carry true

Zero false

A corrupt

Otherwise:

Carry false

A = Error code

Always:

BC DE HL IX corrupt, all other registers preserved.

6.3.8 - DD_FORMAT

Synopsys

Format a track. (Uses the uPD765A format track command.)

Entry Parameters

Exit Parameters

If OK:

Carry true

A corrupt

Otherwise:

Carry false

A = Error code

Always:

BC DE HL IX corrupt, all other registers preserved.

Format buffer

The format buffer contains 4 bytes for each sector:

6.3.9 - DD_READ_ID

Synopsys

Read a sector identifier

Entry Parameters

Exit Parameters

If OK:

Carry true

A = sector number from identifier

Otherwise:

Carry false

A = Error code

Always:

HL = Address of result buffer in page 7

BC DE IX corrupt, all other registers preserved.

6.3.10 - DD_TEST_UNSUITABLE

Synopsys

Check that disk is suitable to write to. A single track disk will not work in a double track drive, and vice versa.

Entry Parameters

Exit Parameters

If OK:

Carry true

A corrupt

Otherwise:

Carry false

A = Error code

Always:

BC DE HL IX corrupt, all other registers preserved.

6.3.11 - DD_LOGIN

Synopsys

Log in a new disk. Initialise the XDPB. This routine does not affect or consider the freeze flag.

Entry Parameters

Exit Parameters

If OK:

Carry true

A = Disk type

DE = Size of allocation vector

HL = Size of hash table

Otherwise:

Carry false

A = Error code

DE HL corrupt

Always:

BC IX corrupt, all other registers preserved.

6.3.12 - DD_SEL_FORMAT

Synopsys

Initialise an XDPB for a standard format. This routine does not affect or consider the freeze flag.

Entry Parameters

Exit Parameters

If OK:

Carry true

A = Disk type

DE = Size of 2 bit allocation vector

HL = Size of hash table

Otherwise:

Carry false

A = Error code

DE HL corrupt

Always:

BC IX corrupt, all other registers preserved.

6.3.13 - DD_ASK_1

Synopsys

Check to see if unit 1 is present. BASIC holds this information in bit 5 of the FLAGS3 system variable.

Turn motor on.

Fetch drive status.

If unit 1 is not-ready and write-protected, then unit 1 is missing. Start motor off timeout.

Note that this routine can be fooled by disks which are almost, but not quite, inserted in the drive.

This routine assumes that when a disk is not in the drive, then write-protect is true. This is indeed the case for 3 inch and 8 inch disk drives, but is not the case for 5 1/4 inch disk drives.

Entry Parameters

None

Exit Parameters

If unit 1 present:

Carry true

Otherwise:

Carry false

Always:

A BC DE HL IX corrupt, all other registers preserved.

6.3.14 - DD_DRIVE_STATUS

Synopsys

Issue a sense drive status command.

Entry Parameters

Exit Parameters

A = ST3 status register 3 of uPD765A

Always:

F BC DE HL IX corrupt, all other registers preserved.

6.3.15 - DD_EQUIPMENT

Synopsys

Ask what type of drive this is (i.e. single/double track, single/double sided).

Track information can only be determined once a disk has been seen and had its type identified during logging in.

Side information can only be detected after a double sided disk has been seen and has its type identified during logging in.

Entry Parameters

Exit Parameters

Carry true

A = Side/track information
bits 0…1 side information: 0 = unknown, 1 = single sided, 2 = double sided
bits 2…3 track information: 0 = unknown, 1 = single track, 2 = double track

Always:

F BC DE HL IX corrupt, all other registers preserved.

6.3.16 - DD_ENCODE

Synopsys

Set the copy protection ENCODE subroutine.

Copy protected disks have some of their track and sector numbers encoded on disk. Before each disk access, the ENCODE subroutine is called to encode the physical track and sector numbers.

These encoded track and sector numbers must match those in the sector identifier.

Note that tracks 0…2 on either side of a disk should not be encoded.

Entry Parameters

Exit Parameters

HL = Address of previous encode routine, 0 if none

Always:

AF BC DE IX corrupt, all other registers preserved.

ENCODE routine

If you are substituting your own ENCODE subroutine, the 'entry conditions' are the conditions passed to your subroutine, and the 'exit conditions' are the values that your subroutine must produce and the registers you are allowed to corrupt.

Entry Parameters

Exit Parameters

D = Encoded physical track

E = Encoded physical sector

Always:

AF corrupt, all other registers preserved.

6.3.17 - DD_L_XDPB

Synopsys

Initialise an XDPB for a given format.

This routine does not affect or consider the freeze flag.

Entry Parameters

Exit Parameters

If OK:

Carry true

A = Disk type recorded on disk

DE = Size of allocation vector

HL = Size of hash table

Otherwise:

Carry false

A = Error code

DE HL corrupt

Always:

BC IX corrupt, all other registers preserved.

6.3.18 - DD_L_DPB

Synopsys

Initialise an DPB for a given format.

This routine does not affect or consider the freeze flag.

Entry Parameters

Exit Parameters

If OK:

Carry true

A = Disk type recorded on disk

DE = Size of allocation vector

HL = Size of hash table

Otherwise:

Carry false

A = Error code

DE HL corrupt

Always:

BC IX corrupt, all other registers preserved.

6.3.19 - DD_L_SEEK

Synopsys

Seek to required track. Retry if failure.

Entry Parameters

Exit Parameters

If OK:

Carry true

A corrupt

Otherwise:

Carry false

A = Error code

Always:

BC DE HL IX corrupt, all other registers preserved.

6.3.20 - DD_L_READ

Synopsys

Low level uPD765A read command.

• Read data.
• Read deleted data.
• Read a track.
• Writes commands.
• Reads data.
• Reads results.
• Motor must be running.

Entry Parameters

Exit Parameters

HL = Address of result buffer in page 7

Always:

AF BC DE IX corrupt, all other registers preserved.

6.3.21 - DD_L_WRITE

Synopsys

Low level uPD765A write command.

• Write data.
• Write deleted data.
• Format a track.
• Scan equal.
• Scan low or Equal.
• Writes commands.
• Writes data.
• Reads results.
• Motor must be running.

Entry Parameters

Exit Parameters

HL = Address of result buffer in page 7

Always:

AF BC DE IX corrupt, all other registers preserved.

6.3.22 - DD_L_ON_MOTOR

Synopsys

Turn on the motor. Wait for the motor on time as set by DD SETUP.

Entry Parameters

None

Exit Parameters

Always:

AF BC DE HL IX corrupt, all other registers preserved.

6.3.23 - DD_L_T_OFF_MOTOR

Synopsys

Start motor off timeout.

Entry Parameters

None

Exit Parameters

Always:

AF BC DE HL IX corrupt, all other registers preserved.

6.3.24 - DD_L_OFF_MOTOR

Synopsys

Turn off the motor.

Entry Parameters

None

Exit Parameters

Always:

AF BC DE HL IX corrupt, all other registers preserved.

6.4 - +3DOS File Header

Tape files have headers which contain some system information. +3DOS files may, or may not, have headers. All files created by BASIC's SAVE command will have headers.

The +3DOS header mechanism provides a dedicated 8 byte area in each headed file reserved for BASIC's use. The remainder of the header is reserved for +3DOS. This 8 byte header is utilised in files created by BASIC commands (see DOS OPEN description).

+3DOS files may have a single header in the first 128 bytes of the file - the header record. These headers are detected by a 'signature' and checksum. If the signature and checksum are as expected, then a header is present; if not, there is no header. Thus, it is possible, but unlikely, that a file without a header could be mistaken for one with a header.

Notes

• The file header is the first 128 bytes of the file on disk.
• The Length at bytes 11 is a 32-bit number, the max file size is 8Mb. This includes the 128 byte header.
• The BASIC header at byte 15 is what IX points to after a call to DOS_READ_HEAD so (IX+0) is the File Type.
• The length in the BASIC header is the actual length of the file, without the 128 byte header.
• For File Type 0 - BASIC, Param 1 is either the line number to start execution or 0x8000 for none. Param 2 is the offset of variables. For most purposes this can be the length of the program so no variables.
• For File Type 3 - CODE, Param 1 is the load address. Param 2 is unused
• The checksum byte 127 in the header is the sum of the rest of the header, not XOR like tape files.

6.5 - Error Codes

When a call to a +3DOS API fails then the carry flag will be false and the Accumulator will contain the error code. The errors are in two categories, Recoverable (Green) and Non-recoverable (Red):

7 - reference

7.1 - API by Address

7.2 - API by Name

7.3 - include

7.3.1 - BeebASM

7.3.1.1 - api

7.3.1.2 - headers

7.3.2 - ZAsm

7.3.2.1 - api

7.3.2.2 - headers