Mastering Sideways ROM & RAM - Module 00 - Preface
--------------------------------------------------

  This course has been designed to provide BBC Microcomputer users
with sufficient knowledge and confidence to write software for
sideways RAM (SWR) and to convert their own existing programs, in any
BBC Micro supported language, to run from the ROM Filing System (RFS).

  A total of 31 BASIC 1 programs will be used to illustrate the
course. Most of these programs will be used to generate the object
code to be loaded into SWR.

 The example programs can all be saved onto one side of a 100K disc.
All the programs are completely independant of their line numbers
although the numbers will be used when describing the techniques
covered in the examples. Because the programs are written in BASIC 1
they will run on all BBC model B computers as well as on the Master
and Compact computers without any modifications. Most of the programs
will also run on the Acorn Electron, which uses BASIC 2.

The programs used to illustrate the course.
-------------------------------------------

program name:     Used in modules:

ABSOL             12    Absolute workspace
ALLRFS            23    RFS
AUTORFS           22    RFS ROM cartridges
BOOTRFS           19    Booting the RFS
BUFFER            14    Unrecognised interupts
CURSOR            05    Reading arguments
DEMO              18-24 All RFS modules
ENABLE            04    Enabling * commands
ENABTST           04    Demonstrate *ENABLE
ERROR             08    Errors in service code
FILES             13    Trapping errors
HELP              16    Extended help
INTLACE           12    Service code 1
LOCK              10    program to convert to SWR
MODONE            24    Modular programming
MODTWO            24    Modular programming
NEWCOM            03    Simple * command interpreter
NOBASIC           17    Language ROM design
OSBYTE            06    Unrecognised Osbyte
OSWDEMO           07    Osword demonstration
OSWORD            07    Unrecognised Osword
PEEK              09    Reading numerical arguments
PRIVATE           11    Private workspace
READROM           All   Examine sideways RAM
RFSERV            20    RFS * commands
RFSGEN            18-24 All RFS modules
RFSHEAD           18    Simple RFS header
RFSLANG           21    RFS * commands
SOUNDS            15    Multiple command interpreter
TRACE             02-24 Service call trace
VECTOR            10    Extended ROM vectors


  The programs used to illustrate the course have not been designed to
use the extra memory or facilities available on the Master computer
but notes on suitable modifications have been included where
appropriate. In some cases it is necessary to press Ctrl+Break on the
Master computer when it is only necessary to press Break on the BBC B.
It is desirable, but not essential, to use a disc based system for the
RFS modules in the course. Tape-only users will be given all the
information they need to use the programs.

The course modules
------------------

00. Preface. This module.

  No programs.

01. Module 1 will introduce the sideways ROM and RAM system. The
program READROM will be used to illustrate how paged memory banks are
switched using the paged ROM select register at &FE30 and its copy at
&F4. The operating system routine Osrdrm will also be used by READROM
to read individual bytes from the sideways ROMs.

  program: READROM

02. Module 2 will introduce the header which must be used by every ROM
image and the service calls issued to every active ROM. The program
TRACE will be used to illustrate how service calls are issued to the
sideways ROMs and to explain how service calls can be trapped in SWR
software. A summary of which service calls will be dealt with in the
course will be included in this module.

  programs: TRACE, READROM

03. A simple one-command interpreter for unrecognised * commands will
be demonstrated in module 3. The conversion of an Assembly language
sound effects program, ZAP, into a sideways RAM program NEWCOM will be
explained. The new sideways RAM program will replace the user memory
program by providing a new * command *ZAP to make the same sound
effect.

  programs: NEWCOM, TRACE

04. The Disc Filing System uses the command *ENABLE to protect
"dangerous" routines from accidental use. The DFS *ENABLE command can
be used from within your own sideways RAM programs. This technique
will be explained and demonstrated in module 4 but it can only be
guaranteed to work in your sideways RAM programs with Acorn DFS 0.9
and 1.20.

  programs: ENABLE, ENABTST

05. Arguments can follow the * command used to call a sideways RAM
utility. The operating system provides two subroutines, Gsinit and
Gsread, which can be used to initialise and read an argument. Reading
arguments with Gsinit and Gsread will be explained and demonstrated in
module 5.

  program: CURSOR

06. The operating system can be used to convert the ASCII
representation of the numbers 0 to 255 into binary by defining a new
Osbyte call. This will be demonstrated with a new Osbyte call number
&64 (*FX 100). *FX100,x,y will be used to convert the x and y
parameters into binary and to store them in reserved zero page memory
locations ready to be accessed by a new routine.

  programs: OSBYTE, TRACE

07. The new Osbyte call defined in module 6 is, like all Osbyte calls,
limited to reading and writing two numerical parameters. A new Osword
can read and write as many parameters as your new routines need. This
will be demonstrated with a new Osword &64 which will read four
parameters to perform the equivalent of a 'PRINT @' routine.

  programs: OSWORD, OSWDEMO, TRACE

08. When the user of a SWR utility types an out of range or unexpected
argument it should be recognised as an error and the SWR utility
should halt any BASIC program and report an error message. This will
be demonstrated with a new command *CHECK (0-6) which will create an
error if an appropriate filing system has not been selected or if an
argument is out of range or omitted.

  program: ERROR

09. Arguments which follow a * command can only be read as an ASCII
string. If the string represents a number it has to be converted into
binary and stored in user memory before it can be used as a number.
Reading hexadecimal numerical arguments, checking their range and
validity, and converting them from an ASCII string into a binary
number will be explained and demonstrated in module 9.

  program: PEEK

10. The BBC Micro vectors can be altered to point to new routines in
either user memory or in sideways RAM. When sideways RAM or ROM is
used for the new routines it is necessary to use extended ROM vectors.
The use of extended ROM vectors will be explained and demonstrated
with the conversion of a user memory cassette file locking routine
into sideways RAM format.

  programs: VECTOR, LOCK

11. It is often necessary for sideways RAM programs to use an area of
user memory as workspace. If the data stored in the workspace must not
be corrupted by other programs it is necessary to use private
workspace. Claiming private workspace will be explained and
demonstrated with an example program which reads the number of disc
cycles on the disc in the default drive.

  programs: PRIVATE, TRACE

12. Absolute workspace will only be of interest to the more
experienced user but a skeleton interpreter will be presented. The
absolute workspace service call (service call 1) is sent to every
active ROM when the computer is switched on and when the Break key is
pressed. If all the registers are preserved service call 1 (or service
call &FE on the Master computer) can be used to provide a variety of
functions. This additional use of service call 1 will be demonstrated
with a program which keeps the video interlace switched off.

  programs: ABSOL, INTLACE, TRACE

13. Errors created in other sideways ROMs can be trapped and acted
upon within your own sideways RAM programs. Module 13 demonstrates how
the "Disc full" and "Cat full" errors generated by the DFS can be
trapped and used to prompt for a disc change. This is not a simple
task and uses most of the techniques described earlier in the course.

  programs: FILES, TRACE

14. When an interupt is generated by hardware in the computer system
and that interupt is not recognised by the MOS, it is first offered to
the paged ROMs and then to the user via the IRQ2 vector. Dealing with
unrecognised interupts will be dealt with in module 14 and illustrated
with a 15.75K SWR parallel printer buffer.

  program: BUFFER

15. All the earlier modules of the course that have used an
unrecognised * command interpreter have used a simple one-command
interpreter. A multiple command interpreter will be introduced,
explained and demonstrated in module 15. The multiple command
interpreter will accept commands shortened with a dot and prefixed
with an optional character.

  program: SOUNDS

16. When a multiple command interpreter is used in a SWR utility ROM
it is easy to forget the syntax of all the new commands. It is often
useful for a SWR program to respond to the *HELP command by explaining
the syntax of its new commands. The multiple command interpreter
introduced in module 15 will be developed in module 16 to provide an
extended help service.

  programs: HELP, TRACE

17. All the ROM images created in the earlier modules of the course
will be service ROM images. Language ROMs are introduced in module 17
with the example language NOBASIC. Language ROM design will be used
again when dealing with the RFS but it is simple enough to understand
and should be of interest in its own right.

  program: NOBASIC

18. The ROM Filing System is available on all BBC Microcomputers with
MOS 1.0, or later. In order to store files in the RFS they have to be
formatted with a block structure very similar to that used by the Tape
Filing System. The RFS will be introduced in module 18 with a simple
RFS interpreter and formatting program.

  programs: RFSHEAD, RFSGEN, DEMO, TRACE

19. The Disc Filing system can be booted with D+Break, the Tape Filing
system with Space+Break and the Network Filing System with N+Break.
You might expect the ROM Filing System to boot with R+Break but it does
not work. An interpreter which will boot the RFS with R+Break will be
demonstrated and explained in module 19.

  programs: BOOTRFS, RFSGEN, DEMO

20. Existing programs, in almost any BBC Microcomputer-supported
language, can be run from the RFS with star commands without modifying
the existing program. This can be done with either a service or a
language ROM design. Module 20 deals with the service ROM design and
demonstrates how a BASIC program stored in the RFS can be run in user
memory with the new command *DEMO.

  programs: RFSGEN, RFSERV, DEMO

21. The language ROM design can be used to run programs from the RFS
with a new * command. The language ROM can be used in the highest
priority ROM socket and selected as the default language when the
computer is switched on and when Ctrl+Break is pressed. This will be
demonstrated with a new language called RFS. The only function of this
language is to run a BASIC program in user memory.

  programs: RFSGEN, RFSLANG, DEMO

22. ROM cartridges should load and run a program from the cartridge
when the Break key is pressed. The RFS language ROM design introduced
in module 21 can be modified to produce the format needed for ROM
cartridges which will run BASIC and machine code programs in this way.
This technique uses an interception of service call &FE.

  programs: AUTORFS, RFSGEN, DEMO

23. All but one of the RFS ROMs in a computer should use the simple
interpreter introduced in module 18. Module 23 demonstrates a more
complex RFS header that only needs to be used in one of the RFS ROMs.
It includes extended help, auto-boot and running programs with a new *
command. Detailed instructions are included for novice BASIC
programmers.

  programs: ALLRFS, RFSGEN, RFSHEAD, DEMO

24. All the source code programs demonstrating the SWR techniques will
have HIMEM set to &3C00. This allows up to 16K of object code to be
held in memory in mode 7. The DFS sets PAGE to &1900 on the BBC B
leaving only 8.75k for the source code. Because of this it is
sometimes necessary to use modular programs with forward referencing
to overcome the memory limitations of the BBC Micro. These techniques
will be demonstrated in module 24.

  programs: MODONE, MODTWO, RFSGEN, DEMO

25. Index.

  No programs.

  When writing this course it was necessary to make some assumptions
about the readers who will use it to help them write their own
sideways RAM software. The sideways ROM/RAM system has been widely
described and discussed in so many BBC Micro publications that it
seemed unnecessary to describe the basic concept in any detail. If you
don't know what sideways ROM/RAM is you are unlikely to want to, or to
be able to, write software to run in it.

  I have assumed that you have programmed your BBC Micro in both BASIC
and Assembly language. If you do not understand programming in 6502
Assembly language using the BBC assembler you can expect to have some
difficulty with most of the course modules except perhaps modules 18
to 24 which deal with the RFS. Module 23 was written specifically for
BASIC programmers with absolutely no understanding of Assembly
language. If you have worked through a course in machine code
programming, such as the Telesoftware Osbits course, you should be
able to complete this course without any problems.

  It seemed reasonable to assume that the readers with BBC B+ 128K and
Master series computers will have looked at the manuals provided with
their machines and already know how to load and use software in this
area of memory. Readers with BBC B and BBC B+ 64K micros will need to
make some modifications to the hardware of their machine and I will
give some advice on choosing a suitable upgrade. Instructions on
loading software into the sideways RAM it provides will be supplied by
the manufacturer of the upgrade.

  All the example programs have been written in BASIC 1 which lacks
the pseudo-opcodes to implement equate functions. These pseudo-opcodes
have been implemented in all the programs using BASIC functions. The
functions are called using, for example, OPT FNequb(&0D) as the
equivalent of the BASIC 2 EQUB &0D. The BASIC 1 assembler will not
accept a colon as part of a expression and so, for example, an
expression such as CMP #ASC(":") which is acceptable to BASIC 2 is
replaced with CMP #ASC("9")+1 which assembles identically and is
accepted by BASIC 1.

  BASIC 1 does not implement remote assembly and so all references to
absolute addresses have had the difference between the address at
which they run (&8000) and the address at which they are assembled
(&3C00) added to that address. All references to absolute addresses,
for example subroutine in JSR subroutine, have been replaced with the
remote equivalent JSR subroutine+diff. The constant diff has been
assigned the value of &8000-&3C00 in all the programs that use it.

  All the programs used to illustrate the course could be used by a
non-programmer to build a sideways RAM library without understanding
why the programs work but the real objective of the course is to teach
programmers how to create their own software and not how to use the
examples provided.