1 - BBC Micro Memory Map

1.1 - Page 00

On the BBC Micro addresses 0x0000…0x008F are reserved for the current language. The table above lists the known BASIC II memory map for those addresses.

BBC Basic reserves 0x0070…0x008F for user programs. User code should not use addresses outside that range unless they have replaced BASIC.

1.2 - Page 02

1.3 - Page 03

1.4 - Page 08-0D

1.5 - Page 0E-18 DFS

This table relates to a BBC Model B with Acorn DFS active. This will use pages 0x0E to 0x18 with the USER workspace starting at page 0x19.

This does NOT apply when either the Cassette or ROM filesystem is active, or on a BBC Master 128. In those cases USER workspace starts at page 0x0E.

1.6 - Paged Roms

2 - MOS

2.1 - OSEVEN

The user event may be generated using this routine. Software replacing OS routines should generate the appropriate events by making this call.

2.2 - OSCLI

This call provides the machine code user with a convenient method of performing any of the * commands that the system provides from Basic.

The command required is placed in a string as normal text terminated by a CR character and this call is made with the address in X & Y.

If the string passed to the CLI is not terminated by a carriage return within 255 bytes this routine has undefined effects.

The OS provides a default set of commands: (Note these have * in them but that is not necessary when passing the command to OSCLI)

These commands may be abbreviated by taking the first few letters and terminating with a ‘.’ character. Parameters may be passed in the text following the command.

Other unrecognised commands are first offered to paged ROMs and are then offered to the currently selected filing system via the filing system control vector.

2.3 - OSRDRM

This call returns a byte read from a paged ROM. The ROM number is in Y. The address to read is in &F6 and &F7

This routine was included for the implementation of ROM filing system software in paged ROM and is not recommended for general use.

2.4 - OSRDCH

This routine reads a character from the currently selected input stream and returns it in the accumulator.

If an error should occur acknowledgement of the error condition should be made using OSBYTE &7E.

2.5 - OSWRCH

2.6 - OSBYTE

2.6.1 - &00 (0) OS Version

Entry parameters

On exit:

This OSBYTE call returns the OS type in X or as a message via BRK if X=0 on entry.

Returned values

2.6.2 - &01 (1) set user flag

Entry parameters

On exit:

This OSBYTE call is left free for user applications and is not used by the operating system. The user flag defaults to 0.

2.6.3 - &02 (2) select input stream

Entry parameters

On exit:

Examples

*FX 2,0 X=0 keyboard selected, RS423 disabled

*FX 2,1 X=1 RS423 selected & enabled

*FX 2,2 X=2 keyboard selected, RS423 enabled

Default: *FX2,0

Electron

Any call with X<>0 will result in an unknown OSBYTE service call being made to paged ROMs unless a previous call was recognised & changed the input source.

2.6.4 - &03 (3) select output stream

Entry parameters

On exit:

This call selects the output streams to be used. The X register contains the streams to use, one per bit:

*FX 3,0 selects the default output:

• RS423 disabled
• VDU enabled
• Printer enabled if selected by VDU 2
• Spooled output enabled if selected by *SPOOL

Econet

Bit 3 should not be used to enable the printer as it might conflict with Econet claiming the printer.

Electron

If RS423 or printer output is selected on the Electron a paged ROM service call is issued. If no suitable response is received the output is thrown away.

2.6.5 - &04 (4) enable/disable cursor editing

Entry parameters

On exit:

X=0 Enable cursor editing (default).

X=1 Disable editing, cursor keys return ASCII values like other keys.

X=2 Disable editing, cursor keys act as soft keys.

2.6.6 - Enable/Disable events

Entry parameters

On exit:

OSBYTE 13 is used to disable specific events. OSBYTE 14 is used th enable specific events.

Event type passed in X

2.6.7 - &72 (114) Shadow ram

Shadow mode

Shadow mode is the option to force all screen's to use Shadow memory. By default it is disabled so that mode's 0..7 on the BBC Micro will use system memory whilst modes 128..135 will use shadow memory.

When shadow mode is enabled all modes use shadow memory. e.g. 0..7 will have 128 added to give 128..135.

*FX114 or *FX114,0 is the equivalent of *SHADOW.

*FX114,1 is the equivalent of *SHADOW 1 .

2.6.8 - &8B (139) Select file options

Entry parameters

On exit:

2.6.9 - &8C (140) Select tape filesystem

On exit:

2.6.10 - &8D (141) Select ROM filesystem

On exit:

2.6.11 - &8E (142) Enter language ROM

Entry parameters

The language ROM is entered via its entry point with A=1. Locations &FD and &FE in zero page are set to point to the copyright message in the ROM.

This call does not return as the new Language will take over the machine.

2.6.12 - &8F (143) Issue paged ROM service call

Entry parameters

On exit:

Refer to the section about service roms on how this call works.

2.6.13 - &90 (144) Alter display parameters

Electron

On the Electron this is not implemented and returns with all registers preserved.

2.6.14 - Read/Write to mapped IO

Entry parameters

On exit:

Refer to the hardware secion about the FRED, JIM & SHEILA 1MHz buses.

2.6.15 - MOS Variables

On exit:

The OSBYTE calls &A6 to &FF (166-255) read and write the MOS variables.

Reading & writing the variables are handled by the formula:

newValue = (oldValue AND Y) EOR X

The all return the old value in X and the next location in Y.

MOS Variables

The MOS variables start in memory from address &0236. Each variable is accessible via OSBYTE calls 166..255. The internal label .mosVariablesMinus166 refers to the address &0190 (= &0236-166) so that the lookup is done by simply adding the accumulator to that address.

2.7 - OSWORD

2.7.1 - Read line from input

This routine takes a specified number of characters from the currently selected input stream.

Input is terminated following a RETURN or an ESCAPE. DELETE (&7F/127) deletes the previous character and CTRL U (&15/21) deletes the entire line.

If characters are presented after the maximum line length has been reached the characters are ignored and a BEL (ASCII 7) character is output.

OSWORD 0x00 is the only OSWord which return's data in the registers.

Parameter block

Only characters greater or equal to XY+3 and less than or equal to XY+4 will be accepted. This is useful for forms where you want only digits by setting the minimum to '0' and maximum to '9'

On exit

2.7.2 - Read/Write system clock

The clock is a five byte clock value is read or written to the address contained in the X and Y registers.

For example the TIME function in BASIC uses OSWORD 0x01.

This clock is incremented every hundredth of a second and is set to 0 by a hard BREAK.

2.7.3 - Interval timer

This routine may be used to read/write the interval timer, used for events.

For read (OSWord 0x03) the current clock value will be writted to the 5 bytes pointed to by the XY registers.

For write (OSWord 0x04) the new clock value is contained in the 5 bytes pointed to by the XY registers.

2.7.4 - Read/Write I/O processor memory

A byte of I/O processor memory may be read or written across the Tube using this call. A 32 bit address should be contained in memory at the address contained in the X and Y registers.

For writes (OSWord 0x06) the value to write should be placed in XY+4

For reads (OSWord 0x05) the value read is placed in XY+4 on exit.

Parameter block

If the I/O processor uses 16 bit memory addressing only least significant two bytes need to be specified.

2.7.5 - Sound command

This routine takes an 8 byte parameter block addressed by the X and Y registers. The 8 bytes of the parameter block may be considered as the four parameters used for the SOUND command in BASIC.

Parameter block

For example, to perform a

SOUND 1,-15,200,20

Parameter block

2.7.6 - Define an Envelope

The ENVELOPE parameter block should contain 14 bytes of data which correspond to the 14 parameters described in the ENVELOPE command. This call should be entered with the parameter block address contained in the X and Y registers.

2.7.7 - Read pixel value

This routine returns the status of a screen pixel at a given pair of X and Y co-ordinates.

Parameter block

On exit, XY+4 contains the logical colour at the required point or &FF if the point specified was off the screen.

2.7.8 - Read character definition

This call returns the 8 bytes which define the 8 by 8 matrix of each character.

The call requires a 9 byte parameter block pointed to by the X and Y registers.

The first byte contains the ASCII value of the character definition to be read.

After the call the 8 byte definition is contained in bytes 1 to 8 of the parameter block, with the top row in byte 1 and the bottom row in byte 8.

2.7.9 - Read/Write palette

These routines read and write the colour palette. They take a 5 byte parameter block:

Parameter block

Write Palette

The OSWORD 12 write palette call performs the same task as a VDU 19 command which can be used from machine code using OSWRCH.

The advantage of using this OSWORD call rather than the conventional VDU route is that there is a significant saving in time.

Another advantage is that OSWORD calls can be used in interrupt routines while VDU routines cannot.

2.7.10 - Read last two graphics cursor positions

The operating system keeps a record of the last two graphics cursor, positions in order to perform triangle filling if requested. These cursor positions may be read using this call. X and Y should provide the address of 8 bytes of memory into which the data may be written.

Parameter block

2.7.11 - Read CMOS clock

This routine reads from the onboard CMOS clock.

For systems without a CMOS clock, the MOS passes the calls to sideways ROM's for support.

The first byte of the parameter block is a function code representing the action required. The rest of the block's content (including its size) depends on that function.

2.7.12 - Write CMOS clock

This routine allows the onboard CMOS clock to be set. For systems without a CMOS clock, the MOS passes the calls to sideways ROM's for support.

The first byte of the parameter block is a function code representing the action required. The rest of the block's content (including its size) depends on that function.

2.7.13 - IP Networking and DNS Resolution

This call is supported on the Network API documentation for the SPROW Ethernet upgrade for the Master Series which I happen to have installed in my BBC Master 128.

This call is modelled on the Berkeley Sockets API.

Call format

The control block follows the convention for high-numbered OSWORD calls where the control block contains the request & response sizes, action and result codes as the first 4 bytes of the block.

Actions

To allow for many functions to be performed but without using up lots of OSWord numbers a one byte action code is included, allowing for up to 256 different pieces of functionality. The action codes are further split into groups of 64 each:

Unused or reserved action codes will return an error number at XY+3.

2.7.13.1 - Socket operations

2.7.13.2 - Resolver operations

2.7.13.3 - Library functions

 1REM Network functions
 2REM (C)2010 SPROW
 3:
 4DEFFNgethost(name$)
 5wordblk?0=8:REM Parameters in
 6wordblk?1=24:REM Parameters out
 7wordblk?2=&41:REM Resolver_GetHost
 8wordblk?3=0:REM No error on entry
 9wordblk!4=nameblk
10$nameblk=name$
11A%=192:X%=wordblk:Y%=wordblk DIV256:CALL&FFF1
12IFwordblk?3<>0 THEN=0
13=wordblk+4:REM Address not value
14:
15DEFFNcreat(pf%,type%,prot%)
16wordblk?0=16:REM Parameters in
17wordblk?1=8:REM Parameters out
18wordblk?2=&00:REM Socket_Creat
19wordblk?3=0:REM No error on entry
20wordblk!4=pf%
21wordblk!8=type%
22wordblk!12=prot%
23A%=192:X%=wordblk:Y%=wordblk DIV256:CALL&FFF1
24IFwordblk?3<>0 THEN=-1
25=wordblk!4
26:
27DEFFNbind(handle%,addr%,addrlen%)
28wordblk?0=16:REM Parameters in
29wordblk?1=8:REM Parameters out
30wordblk?2=&01:REM Socket_Bind
31wordblk?3=0:REM No error on entry
32wordblk!4=handle%
33wordblk!8=addr%
34wordblk!12=addrlen%
35A%=192:X%=wordblk:Y%=wordblk DIV256:CALL&FFF1
36IFwordblk?3<>0 THEN=-1
37=wordblk!4
38:
39DEFFNlisten(handle%,count%)
40wordblk?0=12:REM Parameters in
41wordblk?1=8:REM Parameters out
42wordblk?2=&02:REM Socket_Listen
43wordblk?3=0:REM No error on entry
44wordblk!4=handle%
45wordblk!8=count%
46A%=192:X%=wordblk:Y%=wordblk DIV256:CALL&FFF1
47IFwordblk?3<>0 THEN=-1
48=wordblk!4
49:

 50DEFFNaccept(handle%,addr%,addrlenblk%)Network programmer's API
 51wordblk?0=16:REM Parameters in
 52wordblk?1=8:REM Parameters out
 53wordblk?2=&03:REM Socket_Accept
 54wordblk?3=0:REM No error on entry
 55wordblk!4=handle%
 56wordblk!8=addr%
 57wordblk!12=addrlenblk%
 58A%=192:X%=wordblk:Y%=wordblk DIV256:CALL&FFF1
 59IFwordblk?3<>0 THEN=-1
 60=wordblk!4
 61:
 62DEFFNconnect(handle%,addr%,addrlen%)
 63wordblk?0=16:REM Parameters in
 64wordblk?1=8:REM Parameters out
 65wordblk?2=&04:REM Socket_Connect
 66wordblk?3=0:REM No error on entry
 67wordblk!4=handle%
 68wordblk!8=addr%
 69wordblk!12=addrlen%
 70A%=192:X%=wordblk:Y%=wordblk DIV256:CALL&FFF1
 71IFwordblk?3<>0 THEN=-1
 72=wordblk!4
 73:
 74DEFFNrecv(handle%,data%,len%,opts%)
 75wordblk?0=20:REM Parameters in
 76wordblk?1=8:REM Parameters out
 77wordblk?2=&05:REM Socket_Recv
 78wordblk?3=0:REM No error on entry
 79wordblk!4=handle%
 80wordblk!8=data%
 81wordblk!12=len%
 82wordblk!16=opts%
 83A%=192:X%=wordblk:Y%=wordblk DIV256:CALL&FFF1
 84IFwordblk?3<>0 THEN=-1
 85=wordblk!4
 86:
 87DEFFNsend(handle%,data%,len%,opts%)
 88wordblk?0=20:REM Parameters in
 89wordblk?1=8:REM Parameters out
 90wordblk?2=&08:REM Socket_Send
 91wordblk?3=0:REM No error on entry
 92wordblk!4=handle%
 93wordblk!8=data%
 94wordblk!12=len%
 95wordblk!16=opts%
 96A%=192:X%=wordblk:Y%=wordblk DIV256:CALL&FFF1
 97IFwordblk?3<>0 THEN=-1
 98=wordblk!4
 99:
100DEFPROCshutdown(handle%,type%)
101wordblk?0=12:REM Parameters in
102wordblk?1=4:REM Parameters out
103wordblk?2=&0B:REM Socket_Shutdown
104wordblk?3=0:REM No error on entry
105wordblk!4=handle%Network programmer's API
106wordblk!8=type%
107A%=192:X%=wordblk:Y%=wordblk DIV256:CALL&FFF1
108ENDPROC
109:
110DEFPROCclose(handle%)
111wordblk?0=8:REM Parameters in
112wordblk?1=4:REM Parameters out
113wordblk?2=&10:REM Socket_Close
114wordblk?3=0:REM No error on entry
115wordblk!4=handle%
116A%=192:X%=wordblk:Y%=wordblk DIV256:CALL&FFF1
117ENDPROC

3 - Filesystems

3.1 - Acorn Disk File System

Physical format

Acorn DFS is a single sided, single density 40 or 80 track format. A double sided disc can hold two DFS volumes. Each track carries ten 256 byte sectors numbered from 0 to 9.

Sector ID's

Each sector is given an ID at format time; the parameters of the ID, listed below, are used by the DFS and the floppy disc controller to address sectors.

• C, the cylinder number ranges from 0 on the outermost track to 39 or 79 on the innermost track.
• H, the head number = 0. Acorn DFS ignores this after formatting.
  Some DFS formatters set it to 1 on the upper surface of the disc (corresponding to drives 2 or 3.)
• R, the record number runs sequentially from 0 to 9 within each track.
  There is a standard track skew of 3; that is, the sectors having R = 0 are the first sector of the first track, the fourth sector of the second track, the seventh of the third, the tenth of the fourth, and so on.
• N, the record length = 1, showing that the sector length is 27 + 1, or 256 bytes.

All these parameters can potentially take any value between 0 and 255, and so confuse Acorn DFS and some non-standard controllers. Some copy protection schemes make use of this feature.

3.2 - Acorn System Disk File System / Atom DOS

Discs for the System series have an identical catalogue format to those for the BBC Micro, except all entries are in a directory " " (space), disks do not have a cycle number, and files do not have bits 16 and 17 of load and execution addresses.

The places they would occupy are reserved and must be cleared. A BASIC program named DCONV, on the Utility disc, performs this task.

Catalog format

The disk layout is identical to Acorn DFS with some differences shown below:

Differences between Acorn DFS and System DFS

• The Reserved entries must be clear.
• The disk type in bits 2 and 3 of sector 1 byte 6 must be clear as with DFS.
• Lk. in byte 7 is the same as for Acorn DFS

Sources

This section is based loosely on the following:

• Acorn DFS disk format - beebwiki.mdfs.net
• Acorn, Watford, Solidisk and Duggan DFS Filesystem Structure mdfs.net

3.3 - Angus Duggan HDFS

Angus Duggan's HDFS shares the same basic file structure as Acorn's DFS.

Sector 1 byte 6 bit 3 is set for HDFS with but 2 clear for single-sided and set for double-sided disks.

HDFS subdirectories follow the same format as the main catalogue.

Sources

This section is based loosely on the following:

• Acorn DFS disk format - beebwiki.mdfs.net
• Acorn, Watford, Solidisk and Duggan DFS Filesystem Structure mdfs.net

3.4 - Opus DDOS

This is a double density format, but it is mentioned here as the volume catalogues are based on Acorn DFS.

DDOS discs are partitioned into between one and eight volumes. Track 0 is reserved for the DFS-style volume catalogues, plus a disc catalogue unique to DDOS.

In each volume catalogue:

• The start sector may be any number less than the disc size, as DDOS adds a partition offset and so the catalogue is not in the same space as the files.
• The disc size is the size of the current volume. It is an 11 bit quantity, the top bit being in bit 2 of sector 1 byte 6.
  If and only if this bit is set:
  • The file length steals an extra bit from the execution address of each file (bit 6 of sector 1 byte 14+n.)
  • The start sector steals an extra bit from the load address of each file (bit 2 of sector 1 byte 14+n.)

Sources

This section is based loosely on the following:

• Acorn DFS disk format - beebwiki.mdfs.net
• Acorn, Watford, Solidisk and Duggan DFS Filesystem Structure mdfs.net

3.5 - Watford 62 Disk File System

Watford 62 DFS is identical to Watford DFS except it places a second catalogue in sectors 2 and 3 of track 0, allowing 62 files on one volume. To identify the second catalogue it sets its title to 12 × &AA bytes.

Without due care a system running Acorn DFS can corrupt a Watford disc as it is unaware of the extra files. On such a system the user may run a *SWAP utility to exchange the catalogues. In practice there is a special entry in the first catalogue (directory !, name !!!!!!!, length &200, start sector 2) protecting the second one from being overwritten.

If any file in the first catalogue starts before sector 4, and it is not the special file, the disc is not a Watford DFS disc.

Sources

This section is based loosely on the following:

• Acorn DFS disk format - beebwiki.mdfs.net
• Acorn, Watford, Solidisk and Duggan DFS Filesystem Structure mdfs.net

3.6 - Watford DDFS

This is also a double density format with catalogues similar to Acorn DFS.

It uses 19 bit file lengths and 11 bit LBAs throughout, but the 'extra' bits are stored in the top bits of the disc title and file names, which are cleared in Acorn DFS.

Sources

This section is based loosely on the following:

• Acorn DFS disk format - beebwiki.mdfs.net
• Acorn, Watford, Solidisk and Duggan DFS Filesystem Structure mdfs.net

3.7 - Watford Disk File System

The Watford DFS uses the same structure as Acorn's DFS with some additional attributes:

In byte 6 of Sector 1, bit 2 is clear and 3 is clear for Acorn & WDFS for disks up to 256K, but set for WDFS and disks larger than 256K.

Watford DFS use 19-bit file lengths and 11-bit sector numbers making the largest possible disk being 512K and the largest file size of 512K-1.

Catalog format

The disk layout is identical to Acorn DFS with some differences shown below:

Differences between Acorn DFS and WDFS

• Sector 1 byte 6 bit 3 is always 0 like Acorn DFS
• Sector 1 byte 6 bit 2 is bit 10 of the disk size / sectors in volume. 0=max 256K, 1=max 512K
• Len in byte 5 of the filename is bit 18 of the File Length.
• Len in byte 6 of the filename is bit 10 of the Start Sector.
• Lk. in byte 7 is the same as for Acorn DFS

Sources

This section is based loosely on the following:

• Acorn DFS disk format - beebwiki.mdfs.net
• Acorn, Watford, Solidisk and Duggan DFS Filesystem Structure mdfs.net

4 - Configuration of the Master Series

4.1 - ANFS specific options

4.2 - View specific options

4.3 - *CONFIGURE Baud <0-8>

4.4 - *CONFIGURE Boot / NoBoot

4.5 - *CONFIGURE Caps / NoCaps

4.6 - *CONFIGURE Data <0-7>

4.7 - *CONFIGURE Delay <0-255>

4.8 - *CONFIGURE Dir / NoDir

4.9 - *CONFIGURE FDrive <0-7>

4.10 - *CONFIGURE File <0-15>

4.11 - *CONFIGURE Hard / Floppy

4.12 - *CONFIGURE Ignore <0-255>

4.13 - *CONFIGURE Lang <0-15>

4.14 - *CONFIGURE Mode

4.15 - *CONFIGURE Print <0-4>

4.16 - *CONFIGURE Quiet / Loud

4.17 - *CONFIGURE Repeat <0-255>

4.18 - *CONFIGURE Scroll / NoScroll

4.19 - *CONFIGURE Tube/NoTube

4.20 - *CONFIGURE TV <0-255>,<0-1>

5 - reference

5.1 - API by Address

5.2 - API by Name

5.3 - OSByte calls