*********************************************************** AMIGA BBCEMULATOR VERSION 0.95 - DRAFT DOCUMENTATION *********************************************************** Introduction ~~~~~~~~~~~~ The Amiga BBCEmulator is a program which will turn part of your Amiga into something rather, but not exactly, like a BBC Model B with BASIC 2 and DFS. It runs as a PROCESS on its own screen within the Amiga multi-tasking operating system; thus you can run it AT THE SAME TIME as Amiga programs like editors and Workbench accessories. This means that if you have an Amiga 2000 with Bridgecard and a reasonable amount of memory, you can run BBC applications, PC applications, and native Amiga applications at the same time if you so wish, with easy transfer of data between the different environments. You can even run several BBCEmulators at once if you want to! Our principal objective in creating the BBCEmulator has been to run existing education software, written in BBC BASIC or in a mixture of BASIC and 6502 assembler, as well as possible - WITHOUT killing off the Amiga's native advantages such as split screens and multi-tasking. Speed of execution of BBC BASIC is very good - we have clocked speeds of over seven times faster than the original on some programs. We can also run programs written entirely in 6502 assembler - however, since we are having to emulate 6502 (RISC chip) hardware in 68000 (CISC chip) software, this isn't nearly as fast, and isn't recommended for serious applications. Emulator strategy has been to create a "bridge" from the BBC operating system through to the Amiga's operating environment. This means that we can run nearly all "legal" BBC software which uses BASIC and the OS - ie software which will run on things like 6502 second processors. We cannot however run "illegal" software that dodges the OS and goes direct to BBC screen memory or to the hardware. In practice, this means that we can run nearly all educational programs written in BASIC or a mixture of BASIC and assembler, but not things like arcade-style games - sorry! Principal components of the BBCEmulator software are as follows: Beebos: A "bridge" from the BBC operating system through to the Amiga graphics libraries, maths libraries, etc. DFS: "Disk furtling system" - a bridge from DFS through to AmigaDOS. BASIC: A new implementation of BBC BASIC, re-coded from scratch in 68000 assembler, but with the aim of being as compatible as possible with BBC BASIC 2 (except for the bugs!). A VERY fast implementation, though we say it ourselves. 6502: An emulation of the 6502 chip, written in 68000 assembler - enables programs which call assembler subroutines to work properly, though not as fast as the original. Other elements in the software are a "CLI environment" entered by *GO, and a simple 6502 monitor, entered by *MONITOR. This documentation assumes basic familiarity with the Amiga environment as explained in the User Guide; it also assumes familiarity with the BBC computer. Material needing a more advanced understanding of the Amiga system are flagged as "Techy notes" - ignore these if you want to. Getting started ~~~~~~~~~~~~~~~ You should first backup the BBCEmulator disk and put the original in a safe place - you MAY NOT however make copies except for your own use on your own machine, except by special agreement with Commodore. To get started in the BBCEmulator, you should insert your copy of the master disk, open the disk by double-clicking on its Icon, then invoke the BBCEmulator by double clicking on the Icon. The disks will turn for a bit while it fetches various bits and pieces; if you a running on a single drive system you may be prompted to reinsert your Workbench for the BBCEmulator to load certain Amiga system libraries. You should then find yourself in the BBCEmulator. Note that the BBCEmulator expects to find BASIC in the same drawer as itself - so if you copy the program somewhere else, you should move BASIC as well. If it can't find BASIC you will find yourself in the CLI environment, the prompt for which is a star '*'. To PAUSE the BBCEmulator, perform a mouse-click anywhere in the BBCEmulator screen; this will also give you an Amiga "drag bar" at the top of the screen, which can be used to pull it up and down, or rearrange it relative to the Workbench and any other screens you may have open. With the BBCEmulator in pause mode, it is possible to run various accessories from the Amiga Workbench and Extras disk, including Palette and GraphicDump utilities. To get rid of the drag bar and get the BBCEmulator running again, click again anywhere in the BBCEmulator screen below the drag bar. To EXIT the BBCEmulator, enter the special command: *CLOSEDOWN TECHY NOTE: In order to run properly, the BBCEmulator needs to be on a PAL Amiga with at least 300K free memory, with a 68000 (not 68010 etc) processor. It also expects to find mathstrans.library in its LIBS: directory. If any of these conditions aren't met, it will fail to open. The keyboard ~~~~~~~~~~~~ The first thing you will probably want to do on entering the BBCEmulator is to press CAPS LOCK - this is in order to talk to BASIC sensibly. The BBCEmulator pays attention to your Keymap and Preferences settings as determined by your Amiga Workbench. Note that Preferences determine things like key repeat delays - things like *FX 11 and 12 have no effect. The numeric keypad works as would be expected. Certain keys are "stolen" by the BBCEmulator to have special effects. These are as follows: Function keys - as BBC function keys; F10 used for F0 Cursor keys - as BBC cursor keys for copy key editing, Backspace - acts like BBC DELETE Del - acts like copy key Help - acts like BREAK Note that some protection has been applied to the BREAK facility - to BREAK it is necessary to HOLD DOWN LEFT AMIGA (CBM key on some A500s) THEN PRESS HELP. This performs a "warm boot" like BBC BREAK; you can also perform a "cold boot" by HOLDING DOWN CTRL AND LEFT AMIGA THEN PRESSING HELP. Cold boot differs from warm boot in that it resets the programmable function keys, and resets the DFS - note that this involves a few seconds pause for disk activity if you are running on floppies. Graphics modes ~~~~~~~~~~~~~~ The BBCEmulator supports the following graphics modes: 0 640 x 256 2 colours 80x32 1 320 x 256 4 colours 40x32 2 320 x 256 16 colours 20x32 3 text only 2 colours 80x25 4 320 x 256 2 colours 40x32 5 320 x 256 4 colours 20x32 6 text only 2 colours 40x25 7 Teletext display 40x25 Note that in modes 2 and 5 the horizontal resolution is actually double the original - which doesn't seem to be a problem. The double width (20 column) characters are rendered accurately however. The BBC's Teletext (Mode 7) display is emulated in software in the BBCEmulator. Mode 7 is the fastest mode on the BBC, but the slowest mode on the BBCEmulator. This is because we are having to emulate character- based hardware in pixel-based software - think of a very skilled painter trying to create text as fast as a crummy old typewriter. The speed of BBCEmulator Mode 7 should be more than fast enough for all practical application purposes; however it is not recommended for program editing. For this reason, the "power up default" for the BBCEmulator has been set to Mode 6. Note that Teletext HOLD and RELEASE graphics are not available in version 0.95 of the BBCEmulator. Vdu drivers ~~~~~~~~~~~ The following VDU calls are supported: VDU 0 No effect VDU 1 NOT YET AVAILABLE VDU 2 NOT YET AVAILABLE VDU 3 NOT YET AVAILABLE VDU 4 Text at text cursor VDU 5 Text at graphics cursor VDU 6 NOT YET AVAILABLE VDU 7 Make a beep VDU 8 Backspace cursor VDU 9 Forwardspace cursor VDU 10 Move down cursor VDU 11 Move up cursor VDU 12 Clear text window VDU 13 Carriage return VDU 14 Page mode on VDU 15 Page mode off VDU 16 Clear graphics window VDU 17 Change text colour VDU 18 Change graphics colour - GCOL 0 ONLY VDU 19 Change colour palette VDU 20 Restore default palette VDU 21 NOT YET AVAILABLE VDU 22 MODE VDU 23 User-defined character VDU 24 NOT YET AVAILABLE VDU 25 PLOT VDU 26 Default windows VDU 27 No effect VDU 28 Define text window VDU 29 Define graphics origin VDU 30 Home cursor VDU 31 Move cursor VDU 127 Backspace and delete Note that the BBCEmulator character set is always fully "exploded" - meaning that any character from 32 to 126 and 128 to 255 can be redefined using VDU 23. VDU 23,1 to switch cursor on/off is supported, as are various variations on VDU 23,0. Other uses of VDU 23,0 are NOT supported however. Note also that GCOL modes 1 to 4 are not available from the Amiga graphics library, and are therefore not supported. Operating system commands ~~~~~~~~~~~~~~~~~~~~~~~~~ The following standard commands are supported via the BBCEmulator CLI: *CAT *BASIC *CODE [X,Y] - NOT YET IMPLEMENTED *EXEC *FX A [,X,Y] *GO [
] *HELP [] *KEY N *LOAD [
] *LINE - NOT YET IMPLEMENTED *MOTOR 0/1 - NO EFFECT *OPT X,Y - OPT 4 ONLY *RUN *ROM - NO EFFECT *SAVE [][] *SPOOL *TAPE - NO EFFECT *TV X,Y - NO EFFECT *GO by itself will enter a special "CLIPrompt" environment, with a '*' prompt; to get back to BASIC use '*BASIC'. A number of special commands are also supported; these are discussed elsewhere in this document. *AEXEC [] *ASPOOL [] *CLOSEDOWN *CONNECT [] *FORCECLOSE *ICOPY *IMPORT *MONITOR *SEVER ASPOOL and AEXEC ~~~~~~~~~~~~~~~~ *ASPOOL and *AEXEC are like their DFS equivalents, but take an AmigaDOS path-name as a parameter, and work in AmigaDOS compatible format. They are used to transfer text files between the BBCEmulator and the standard Amiga environments. For example, to export a program Eric to the Amiga RAM disk in AmigaDOS compatible format, use *ASPOOL RAM:Eric LIST *ASPOOL This file could then be edited using an Amiga editor such as MicroEmacs; it could then by imported back again by NEW *AEXEC RAM:Eric Printer redirection by CTRL-B is not yet supported explicitly within the BBCEmulator. For the time being, a good way to get a program listing is *ASPOOL PRT: LIST *ASPOOL Alternatively, you might prefer to ASPOOL to a RAM: file as above, start a new CLI on the Workbench, then on this CLI enter COPY RAM:Eric PRT: This will allow you to print as a background process, without holding up the BBCEmulator. If you have Workbench 1.3, you may wish to experiment communicating directly between BBCEmulator and other Amiga processes by means of "pipes". For example, try pulling down the BBCEmulator in front of an AmigaDOS CLI on Workbench, load a BASIC program in BBCEmulator, then type TYPE PIPE:A in the AmigaDOS CLI then *ASPOOL PIPE:A in the BBCEmulator LIST *ASPOOL *ASPOOL, *AEXEC and Pipes can be used to establish direct communication between two copies of the BBCEmulator - if anyone can think of any possible use for this! Disk Furtling System ~~~~~~~~~~~~~~~~~~~~ The Disk Furtling System allows an Amiga "drawer" or directory to appear as a complete DFS disk to the BBCEmulator. Silly DFS limitations like 31 files per drawer have been retained for reasons of strict compatibility - tell us if you think we should increase this - however, it is possible to have as many DFS drawers as you like on any Amiga disk. The BBCEmulator startup default is to assign DFS drives 0 to 3 to Amiga drawers Drive0, Drive1, Drive2 and Drive3. This can be changed later using *ASSIGN - eg to assign DFS drive 0 to the Amiga RAM disk use *ASSIGN 0 RAM: or, more generally, *ASSIGN The DFS expects to find its files in the form $.ERIC (.), and its catalog information in a special file DFSCat. If you try to assign to a drawer without a DFSCat you will get a warning message "No catalog"; if you try to access a drive which has not been assigned or which has no catalog you will get an error message "Drive not valid". If you forget where a drive is assigned, you can find out by just typing *ASSIGN It is possible to access a DFS drawer from outside the BBCEmulator - eg from the Amiga CLI, or from a utility program such as CLIMate. If you have been making changes in the drawer from outside the BBCEmulator, then you can build a new DFSCat by using the command *MAKE eg to get a valid DFS "disk" in the Amiga RAM disk, you should *ASSIGN 0 RAM: *MAKE 0 If any files of the form . are found in the specified directory, MAKE will prompt with the filename; you can then enter a (hex) load address followed optionally by an execution address, or just press return if this has no relevance. If you have added or deleted files to an existing DFS drawer from outside the BBCEmulator, then you can update the DFSCat to reflect just the changes made by *REMAKE Standard DFS and UTILS commands supported are: *ACCESS [L] *COMPACT *COPY *DELETE *DIR *DRIVE *ENABLE *INFO *LIB *RENAME *TITLE *DISC *DISK *BUILD *DUMP *LIST *TYPE *BACKUP, *DESTROY and *WIPE are not supported - it is easier to perform this sort of operation from the Amiga CLI (or CLIMate etc), then to fix up the DFS directory using *REMAKE. Individual DFS Drawers can be copied from disk to disk by dragging the "disk drive" Icons; complete BBCEmulator disks can be backed up by dragging the Icons in the normal manner. BBCEmulator non-standard DFS commands are as follows: *ASSIGN [] *BOOT [] *MAKE *REMAKE Note that the characters $ and / have special meanings to AmigaDOS - in order to avoid confusing the system, these characters appear as pound signs (Amiga ALT-L) and as broken vertical bars (ALT-I) in AmigaDOS directories respectively. Import facilities ~~~~~~~~~~~~~~~~~ The BBCEmulator contains special commands to allow existing files to be transferred from a BBC with DFS, by means of a serial cable. PLEASE NOTE that this is intended to allow you to transfer your own files, and public domain software; using it to transfer commercial software is almost certainly a breach of licencing agreement - in exactly the same way as making unauthorized copies by any other mechanism. The amount of piracy in education is increasingly encouraging anyone any good at writing educational software to pack it in and do something else, so please don't add to the problem - we mean this! In order to transfer files which you are legitimately entitled to, you will need a serial cable to run between the BBC's RS423 and the Amiga's RS232 ports. A standard "null-modem" cable (ie one in which data in and out are crossed, NOT a "modem" cable where they go straight through) should do fine; if you don't have one you will need to have a cable made up as follows: BBC data in pin A to Amiga TXD pin 2 BBC data out pin B to Amiga RXD pin 3 BBC 0V pin C to Amiga system 0V pin 7 BBC CTS pin D to BBC RTS pin E Code transfer is supported via the following commands: *CONNECT *SEVER *IMPORT *ICOPY To connect at the default baud rate (9600 baud), ensure the lead is connected correctly, enter the BBCEmulator, and type *CONNECT This will prompt you to enter a command at the BBC end (*FX 2,1), then press any key on Amiga. Connection will then either then proceed ok, and the BBC will print a message indicating that it is under remote control from the Amiga, or it will fail - eg because the lead isn't right - and the Amiga will print "Connect failed". Connection can be terminated by pressing ESC. To connect at a different baud rate - eg 1200 baud, type *CONNECT 1200 then follow the instructions printed. Baud rates supported are 150, 300, 1200, 2400, 4800, 9600 and 19200, though the last is NOT guaranteed - indeed it doesn't work properly at the moment! Note that use of the lower baud rates MIGHT allow *CONNECT to be used over a modem link. This is not recommended however except over error correcting modems, as the error checking in the program itself is only very simple. To disconnect "politely" and free the remote machine, enter *SEVER To disconnect "rudely" perform a BREAK (left-Amiga HELP) on the BBCEmulator. The far end will then have to be manually reset by pressing BREAK. Having connected, it is then possible to copy files. To copy an entire disk from remote drive 1 to BBCEmulator drive 0 use *IMPORT 1 0 Note that this will erase the previous contents of BBCEmulator drive 0. More generally, use *IMPORT To copy files selectively, use *ICOPY. To copy files from directory B on remote drive 1 to BBCEmulator drive 0 use *ICOPY 1 0 B.* More generally, the syntax is *ICOPY where is an Ambiguous File Specification as used by *COPY. IMPORT or ICOPY can be terminated politely by pressing ESC, which will cause termination after the current file has been completed, or rudely by pressing BREAK (left-Amiga HELP), which will terminate immediately. In the latter case, it will be necessary to reset the remote machine (press BREAK) then reconnect before trying again. NOTE that IMPORT and ICOPY are designed to work with standard DFS on the remote machine. Non-standard systems are not guaranteed to work correctly. Boot facilities ~~~~~~~~~~~~~~~ If you are using the system's default ASSIGNs, then having imported a disk to drive 0, you can then "boot" the disk by the special command *BOOT 0 Alternatively, you can both invoke the BBCEmulator and auto-boot the disk by double-clicking on the corresponding "5 1/4 disk" icon on the Amiga Workbench. This will start the BBCEmulator and boot the disk. As soon as the application is finished - at the point where it would return to the BASIC '>' prompt - the BBCEmulator will exit back to the Amiga Workbench. Techy note - More about booting ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Readers reasonably familiar with the Amiga may appreciate the following additional information about booting: The "5 1/4 disk" Icons are Amiga project Icons, set with stack size 16000, and Default Tool = BBCEmulator. You can use IconEd, or various public domain Icon edit tools to create custom imagery for boot icons for particular programs. The effect of double clicking on a 5 1/4 disk icon "Boot1" (or whatever) is in fact to force the BBCEmulator automatically to AExec file "Boot1" on entry. The default contents of this file are: *FORCECLOSE *ASSIGN 0 DRIVE1 *BOOT 0 but you can change this for special purposes using an editor like Emacs. The trick of forcing the BBCEmulator to close down instead of returning to BASIC '>' prompt (or CLI environment '*' prompt) is achieved using the special command *FORCECLOSE Note that if a *FORCECLOSE has been performed, then an ordinary BREAK (LEFT- AMIGA-HELP) will exit the BBCEmulator. However, a hard break (CTRL-LEFT- AMIGA-HELP) will override *FORCECLOSE, and stay in the system. It is also possible to run the BBCEmulator from the Amiga CLI environment, using a command such as BEEB BOOT0 where "BOOT0" is the name of a file to AExec on entry. NOTE that in order to do this, you should first CD to the directory containing the BBCEmulator and BASIC (or the system won't find BASIC); you should also set the stack to at least 16000 using the STACK command. Reader's familiar with the Amiga's s:startup-sequence will realize that it is therefore possible to create a "turnkey" disk, that will automatically boot a BBCEmulator application after a disk is inserted on the power-up prompt for Workbench. BBC BASIC ~~~~~~~~~ BBCEmulator BASIC is a new version of BBC BASIC, coded in 68000 assembler. Keywords supported are as follows: ABS ACS ADVAL AND ASC ASN ATN AUTO BGET BPUT CALL CHAIN CHR$ CLEAR CLG CLOSE CLS COLOUR COS COUNT DATA DEF DEG DELETE DIM DIV DRAW ELSE END ENDPROC ENVELOPE EOF EOR ERL ERR ERROR EVAL EXP EXT FALSE FN FOR GCOL GET GET$ GOSUB GOTO HIMEM IF INKEY INKEY$ INPUT INSTR( INT LEFT$( LEN LET LINE LIST LN LOAD LOCAL LOG LOMEM MID$( MOD MODE MOVE NEW NEXT NOT OFF OLD ON OPENIN OPENOUT OPENUP OR OSCLI PAGE PAGE PI PLOT POINT( POS PRINT PROC PTR RAD READ REM RENUMBER REPEAT REPORT RESTORE RETURN RIGHT$( RND RUN SAVE SGN SIN SOUND SPC SQR STEP STOP STR$ STRING$( TAB( TAN THEN TIME TO TRACE TRUE UNTIL USR VAL VDU VPOS WIDTH The only areas of possible difficulty are as follows: Floating Point Precision - The BBCEmulator uses the Amiga's "fast floating point" maths routines - these are VERY fast, but work to only four bytes precision, as opposed to five bytes on the BBC. The default value of @% is therefore set to &060A as opposed to &090A, giving six rather than nine decimal places of accuracy. CALL with parameters - The simple cases of CALL (eg CALL P%, CALL &3000) work fine; the exotic cases where CALL is passed a list of variables are however not supported, and give an error message "Not implemented". This is because 68000 BBC BASIC uses a different internal variables representation to the 6502 version. ENVELOPE - Passed to the OS, but not yet implemented. ADVAL command - always returns zero. Negative INKEY - always returns zero. GCOL modes 1 to 4 - not supported by the OS. 6502 Monitor ~~~~~~~~~~~~ A simple 6502 monitor is included, loosely based on the old PET monitors like Supermon! Entry is via *MONITOR; commands are * execute CLI command Q exit monitor M display memory . alter memory R display registers ; alter registers D disassemble G go Commands are typically followed by one or more hex parameters, eg M 0000 0100 display page zero M 0200 display block from $0200 M display next block D 8000 8020 disassemble from $8000 to $8020 D A000 disassemble next block from $A000 D disassemble next block G 8000 execute from $8000 G execute from current PC '.' and ';' are designed so that register and memory contents can be changed by cursoring up, then using the copy key from the start of the line in question. Operating system ~~~~~~~~~~~~~~~~ Calls currently supported under the 6502 emulator are as follows: GSINIT - Fully supported GSREAD - Fully supported OSFIND - All DFS compatible options OSGBPB - All DFS compatible options OSBPUT - Fully supported OSBGET - Fully supported OSARGS - All DFS compatible options OSFILE - All DFS compatible options OSRDCH - Keyboard or exec file only OSASCI - Fully supported OSNEWL - Fully supported OSWRCH - Screen or spool file only OSWORD - Nearly all calls supported OSBYTE - Major calls supported OSCLI - Fully supported Indirection via the Page 2 vectors is NOT properly supported under version 0.95. OSBYTE calls supported are as follows: OSBYTE &00 Identify Operating System Version OSBYTE &01 Read/write the user flag - NOT YET OSBYTE &02 Select input stream - NOT YET OSBYTE &03 Select output stream - NOT YET OSBYTE &04 Enable/disable cursor editing OSBYTE &06 Set character ignored by printer - NOT YET OSBYTE &07 Set RS423 baud rate for receiving data - NOT YET OSBYTE &08 Set RS423 baud rate for transmitting data - NOT YET OSBYTE &09 Set duration of the mark state of flashing colours OSBYTE &0A Set duration of the space state of flashing colours OSBYTE &0F Flush selected buffer class OSBYTE &12 Reset soft keys OSBYTE &13 Wait for vertical sync - NOT YET OSBYTE &14 Explode soft character RAM allocation OSBYTE &15 Flush selected buffer OSBYTE &77 Close any SPOOL or EXEC files OSBYTE &7C Clear ESCAPE condition OSBYTE &7D Set Escape condition OSBYTE &7E Acknowledge detection of an ESCAPE condition OSBYTE &7F Check for end-of-file on an opened file OSBYTE &81 Read key with time limit OSBYTE &82 Read machine high order address OSBYTE &83 Read top of operating system RAM address (OSHWM) OSBYTE &84 Read bottom of display RAM address (OSLWM) OSBYTE &85 Read bottom of display RAM address for a specified mode OSBYTE &86 Read text cursor position (POS and VPOS) OSBYTE &87 Read character at text cursor position - NOT YET OSBYTE &88 Execute code indirected via USERV - NOT YET OSBYTE &91 Get character from buffer - NOT YET OSBYTE &DA Read/write number of items in VDU queue OSBYTE &E1 Read/write function key status OSBYTE &E2 Read/write SHIFT+function key status OSBYTE &E3 Read/write CTRL+function key status OSBYTE &E4 Read/write CTRL+SHIFT+function key status OSBYTE &E5 Read/write status of ESCAPE key OSBYTE &E6 Read/write ESCAPE effects OSWORD calls supported are as follows: OSWORD &00 Read line from input stream to memory OSWORD &01 Read system clock OSWORD &02 Write system clock OSWORD &03 Read interval timer OSWORD &04 Write interval timer OSWORD &07 Generate a sound OSWORD &08 Define an envelope - NOT YET OSWORD &09 Read pixel colour OSWORD &0A Read character definition OSWORD &0B Read the VDU palette OSWORD &0C Write the VDU palette - NOT YET OSWORD &0D Read current/previous graphics cursorposition - NOT YET