***************************************************************************** BBC Emulator DOCs.....Edited by Sewer Possum. These DOC's were taken from the AMIGA documentation. There are obvious differences, the ST doesn't have the AMIGAs multi-tasking capabilities for a start, so I don't know how useful or accurate these DOC's are... ***************************************************************************** Introduction ~~~~~~~~~~~~ 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. 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. The BBC Emulator 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! 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. To EXIT the BBCEmulator, enter the special command: *CLOSEDOWN 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, etc Backspace - acts like BBC DELETE Del - acts like copy key Help - acts like BREAK 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. 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 *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 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 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 BBCEmulator non-standard DFS commands are as follows: *ASSIGN [] *BOOT [] *MAKE *REMAKE 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! 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. 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 where is an Ambiguous File Specification as used by *COPY. 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. 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: 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 cursor position - NOT YET Yeh, I know...not much to go on, eh? These brief DOC's will have to do until we get some more complete and specific for the ST BBC Emulator program. DO NOT write to us with queries about the program....this is all the documen- tation we've got. Sewer Possum.