--=-=========================-=-- PC-DRAGON 6809 EMULATOR --=-=========================-=-- Version 2.02 Reference Manual Copyright 1993-97 By PAUL BURGIN Table Of Contents 1 INTRODUCTION 5 1.1 EMULATOR OVERVIEW 5 1.2 FILES IN THE ARCHIVE 6 1.3 OPERATIONAL REQUIREMENTS 6 2 PC-DRAGON EMULATOR 8 2.1 BASIC OPERATION 8 2.2 DIALOGUE BOXES 8 2.2.1 GENERAL FUNCTIONALITY 8 2.2.2 MENUS 9 2.2.3 INPUT BOXES 9 2.2.4 NUMERIC INPUT BOXES 9 2.3 FILENAME ENTRY 9 2.4 EMULATION OF HARDWARE AND PERIPHERALS 10 2.4.1 KEYBOARD 10 2.4.2 VIDEO 12 2.4.3 CASSETTE PORT 12 2.4.4 PRINTER PORT 13 2.4.5 JOYSTICK PORT 14 2.4.6 CARTRIDGE PORT 14 2.5 EMULATOR OPTIONS AND MENUS 15 2.5.1 HELP SCREEN 15 2.5.2 TEXT VIEWER MENU 15 2.5.3 FILE MANAGEMENT MENU 15 2.5.4 OPTIONS MENU 15 2.5.5 VIDEO MODE MENU 16 2.5.6 FUNCTION KEY CONFIGURATION 17 2.5.7 CONTROL MENU 17 2.5.8 ASSEMBLER MENU 17 2.5.9 INFORMATION AND CONFIGURATION SCREEN 17 2.6 PROGRAM DEVELOPMENT TOOLS 18 2.6.1 INTEGRATION OF THE EMULATOR WITH AN ASSEMBLER 18 2.6.2 BUILT-IN DEBUGGER 18 2.6.3 EMULATOR SERVICES 20 2.7 ADDITIONAL INFORMATION 22 2.7.1 VIDEO REFRESH INTERRUPT 22 2.7.2 ILLEGAL AND UNDOCUMENTED INSTRUCTIONS 22 2.7.3 SNAPSHOTS 22 2.7.4 BOOTUP SNAPSHOTS 25 2.7.5 SWAPPING 25 2.7.6 FUNCTION KEY ASSIGNMENTS 25 2.7.7 CHANGING EMULATOR COLOURS FROM THE COMMAND LINE 26 2.7.8 CASSETTE FILES 26 3 FILE TRANSFER 28 3.1 OVERVIEW 28 3.2 DRAGON CONVERT 28 3.2.1 EXTRACTING FILES FROM SAMPLED CASSETTES 29 3.2.2 CONVERTING OTHER FILE TYPES 30 3.2.3 CONVERTING FILES FROM CASSETTE FORMAT 30 3.3 COPYCAS UTILITY 31 3.4 WHATIS UTILITY 31 3.5 READVOC UTILITY 32 3.6 HOW TO TRANSFER YOUR ROM 32 4 EPILOGUE 34 4.1 STANDARD DISCLAIMER 34 4.2 HOW TO CONTACT THE AUTHOR 34 4.3 HOW AND WHY YOU SHOULD REGISTER 34 4.4 OTHER DRAGON / COCO EMULATORS 35 4.5 THE NATIONAL DRAGON USERS GROUP 35 4.6 DRAGON E-MAIL LIST 36 4.7 ACKNOWLEDGEMENTS 36 4.8 LEGAL BITS AND PIECES 36 5 APPENDICES 37 5.1 APPENDIX A: TABLE OF EMULATOR SERVICES 37 5.2 APPENDIX B: TABLE OF CONFIGURABLE COLOURS 41 5.3 APPENDIX C: DEFAULT FUNCTION STRINGS 42 1 INTRODUCTION 1.1 Emulator Overview Welcome to PC-Dragon version 2. This program is a Dragon 32, Dragon 64 and Tandy CoCo II emulator for IBM PCs and compatibles. It emulates the base 6809 microprocessor and many associated peripherals, enabling you to use Dragon and CoCo software on your PC. PC-Dragon emulates all documented 6809 features as well as a few undocumented characteristics. Also emulated are the interrupt mechanism, the VDG refresh signal, the Dragon or CoCo keyboard, and printer, cassette and joystick ports. Text mode is emulated using the PC 40 column text mode, and all 56 graphics modes are implemented. Optional emulation of artifacted colours is available in monochrome graphics modes. The emulator also features a powerful built-in disassembler and debugger, and integrated support for the freeware Motorola 6809 assembler. There is a history buffer and many emulation options. These include configurable text and graphics colours, variable interrupt rates, and programmable function keys. A range of `services' allow a Dragon or CoCo programmer to access the emulator environment and options from within BASIC or machine code programs. The emulator supports a number of file types for transferring information to and from the emulated machine. There are snapshot facilities fully compatible with Jeff Vavasour's CoCo2 emulator versions 1.2 to 1.5, as well as facilities to use files in cassette, cartridge, screenshot, ROM, and Motorola S-record format. By making use of the Dragon Convert utility, files in Q-Basic, Dragon-DOS, digital audio and raw binary format may also be converted to PC-Dragon compatible files. This enables you to transfer cassette software to the PC if you have a SoundBlaster Pro card (or equivalent). A utility is also included which can read Dragon cassettes via the PC parallel port (this requires a special cable). To use PC-Dragon you must supply a valid ROM image file taken from a genuine Dragon or CoCo. The emulator will then detect which of the supported architectures to emulate and provide a PC implementation of that machine. Note that the different architectures each have different RAM requirements and emulation speeds. Dragon 32 emulation, for example, requires 48K less memory than Dragon 64 emulation and also performs approximately 30% faster. If you have more than one ROM image then you can choose a specific architecture using the available command line switches (/32, /64 or /T). If you have obtained PC-Dragon from a bulletin board or FTP server then you should not have received a ROM image with this package (for reasons of copyright). However, a number of methods for transferring the ROM from your real machine to your PC are suggested in section 3.6 of this reference manual. This documentation refers in general to the `Dragon' to mean either of Dragon 32, Dragon 64 or Tandy CoCo II. It explicitly mentions a machine where the architectural differences are significant. 1.2 Files In The Archive The emulator archive consists of the following files: DRAGON.EXE PC-Dragon emulator. PCDRAGON.ICO Icon file for use with MS-Windows. FILE_ID.DIZ A short archive description used by bulletin boards. DC.EXE Multi-purpose file conversion utility. COPYCAS.EXE A utility to make renamed copies of cassette files. WHATIS.EXE A utility to recognise and extract information from various files. READVOC.COM A utility to sample cassettes via the PC parallel port. ROM_STUB.DGN A header file for raw ROM images. PCDRAGON.TXT Reference manual converted to plain text format. WHATSNEW.202 List of changes for PC-Dragon version 2.02. The following example snapshot files are also included: BOOTSNAP.??? These files allow the emulator to initialise quickly. DIAGRAM.??? Circuit diagram for the parallel cassette interface cable. TETRAS.D96 Unreleased Dragon 32/64 arcade game. SHANGHAI.D96 Dragon 32/64 oriental patience game. Note that PC-Dragon archives contain directories which can be unpacked together with the files, but are optional. A second freeware PC-Dragon archive is available containing the emulator source code and reference manual in postscript. The registered version of PC-Dragon contains all files within a single archive. Once unpacked, the source code for the emulator can be found in the SOURCE sub directory. READVOC.COM and the DIAGRAM files are included with permission from Gerton Lunter. All other programs are the sole work of the author. The freeware archives may be distributed in complete form only - individual files must not be added or removed. The registered version must not be distributed. If you like PC-Dragon and use the freeware version regularly then you are encouraged to register. All proceeds from registrations are donated to charity; please see section 4.3 for registration details. 1.3 Operational Requirements PC-Dragon runs on any PC with EGA graphics and MS-DOS 3.0 (or above). However, at least a 486 is recommended because the emulator is not very fast (expect only 40% of the real speed when using a 486DX-33). The emulator can be run full screen under MS-Windows or in a DOS box if Dragon graphics modes are not required. Similarly, non-EGA video cards may be used if graphics modes are not required. The emulator requires up to 310K of base memory, and may also swap memory to disk for selected operations. It is possible to run PC-Dragon from either floppy or hard disk but initialisation is considerably slower from floppy disk. The TextView pager is also very slow when used with slow drives, because it operates on the text entirely from disk. A mouse may be used for joystick emulation and mouse support services. A PC joystick may also be used to emulate the Dragon joysticks. To read and write Dragon cassettes using the Dragon Convert utility, sampling software and a SoundBlaster Pro sound card (or equivalent) are required. A sound card is not required to read Dragon cassettes using ReadVoc, but a special cable must be constructed (the circuit diagram for this cable is included with PC-Dragon). The freeware Motorola 6809 assembler AS9.EXE is required to use the Integrated Development Environment (IDE) features of the emulator. This assembler is available from several FTP sites including SimTel and its mirror sites (e.g. sunsite.doc.ic.ac.uk). Look for filename `motoasms.zip' in the `crossasm' directory. PC-Dragon can be run under the Acorn Archimedes 80188 PC emulator but execution is very slow indeed. The Amiga PC-Task emulator is not compatible with PC-Dragon. 2 PC-Dragon Emulator 2.1 Basic Operation The emulator should be run by typing `DRAGON' together with any command line options that you require. You can also give the names of up to two snapshot or cartridge files which you wish to have installed upon start-up of the emulator. If you add your PC-Dragon directory to your PATH environment variable then you will not need to change into the correct directory before running PC-Dragon. If all is well then the title screen for the emulator will be displayed. Press a key and the Dragon will begin its boot sequence. Once the emulator is running any keys that you press will be input to the Dragon rather than the PC, but pressing F1 to F10 will access menus which control the emulator (so long as there are no outstanding key presses in the keyboard buffer). At any time you can press keys CTRL-ALT to activate to the control menu, and CTRL-Q or CTRL-X to exit from the emulator. This will immediately return you to MS-DOS. The emulator will automatically locate and use any ROM files that are found in your PC-Dragon directory or CARTRIGE sub directory. However if no ROM files can be found or your command line options cannot be fulfilled then the emulator will report an error message and fail to start. There are many command line options which may be used with PC-Dragon to configure the behaviour of the emulator. Any that you use regularly may be placed in the file PCDRAGON.CFG in the same directory as DRAGON.EXE and will then be used as defaults upon start-up of the emulator. You can still override the new defaults by typing appropriate options on the command line when you start the emulator or by using the on-screen menus. 2.2 Dialogue Boxes 2.2.1 General Functionality PC-Dragon features a number of dialogue boxes which are used to configure and manage the emulator. Dialogue boxes are red windows with yellow text and generally operate in a consistent manner. All accept CTRL-Q or CTRL-X to quit the emulator immediately, and ESC to dismiss the dialogue box without making a selection. RETURN, SPACE, END and F1 to F10 may also be used to dismiss dialogue boxes if these keys are available. However, at other times RETURN will accept changes, F1 to F10 cannot be used from the F7 menu, END cannot be used from input boxes, and SPACE or RETURN are used to access the next page when there is more than one page of information. 2.2.2 Menus To select items from menus simply press the number key listed against the item that you require. For the file menu (F3) you can also use `L' to load snapshots and `S' to save snapshots. For the function key menu (F7) press either F1 to F10, `1' to `9' (same as F1 to F9), `0' (same as F10), `#' (for F6) or `A' to `Z' to select which key you wish to re-configure. Do not hold down the ALT key when you do this. 2.2.3 Input Boxes Input boxes appear when the emulator requires you to enter a text string. For example, to enter a snapshot filename, or to assign a new string to a programmable function key. When the input box appears the current string will be highlighted in the box. You can accept this as the new string by pressing RETURN or replace it by overtyping it. You can also press END (or UP/DOWN/RIGHT) to append to the old string or BACKSPACE to edit it. At any time you can press HOME to delete all of the input, RETURN to accept the input, or ESC to abandon the operation. All input boxes are intended to input only one string at a time. If you press SPACE then it will be translated to an underscore (this is essential for the input of function key strings, which translate underscores back to spaces when they're used). 2.2.4 Numeric Input Boxes Numeric input boxes behave in the same way as text input boxes but have additional features useful for the input of numeric values. By default numeric input boxes require that new values are given in hexadecimal. But you can type a decimal value by preceding the value with a `#' character or an octal value by preceding the value with `o' or `O'. Hexadecimal numbers may be qualified explicitly by typing `$'. You can also type the names of 16-bit registers `PC', `X', `Y', `U' or `S' into any numeric input box to enter the current value of a register. 2.3 Filename Entry A number of emulator functions prompt for a filename to be entered. Full or relative path names can be used, or if you give just a filename and no directory then the emulator will look in the current directory (plus any other default sub directories). Filename extensions are optional - the emulator will append a default extension if you do not give one. Note, however, that to specify the name of a file which does not have an extension you must give a "." at the end of the name to prevent the emulator from adding the default extension. When opening files for output the emulator will not overwrite existing files without confirmation. The following are the default extensions and optional sub directories used by PC-Dragon: +---------------+--------------------------+--------------------+ | File Type | Default Extension | Sub Directory | +===============+==========================+====================+ | CARTRIDGE | DGN | CARTRIGE | +---------------+--------------------------+--------------------+ | SNAPSHOT | PAK or D32/D64/D96/CCO | SNAPSHOT | +---------------+--------------------------+--------------------+ | | | CASSETTE | | CASSETTE | CAS | CASSETTE\GAMES | | | | CASSETTE\ARCHIVE | +---------------+--------------------------+--------------------+ | SCREENSHOT | Derived from current | - | | | display mode. | | +---------------+--------------------------+--------------------+ | SOURCE FILE | A09 | - | +---------------+--------------------------+--------------------+ | MOTOROLA FILE | S19 | - | +---------------+--------------------------+--------------------+ 2.4 Emulation Of Hardware And Peripherals 2.4.1 Keyboard There are two modes of keyboard emulation available with PC-Dragon. These are `Real Mode' and `PC Mode'. `PC Mode' is the default. It is also used internally by the emulator when dialogue boxes are displayed. In `PC Mode' keyboard input is passed from the emulator to the emulated machine by breakpointing the installed operating system ROM and returning the character code equivalent to the PC key pressed. This method works well for most BASIC software and some machine code software, and also allows the PC to buffer input before it is required by the Dragon. This facilitates the provision of the history buffer and the programmable function keys. However, there are some programs, particularly games software, which access the keyboard at the hardware level rather than through the operating system. For these programs the emulator provides the `Real Mode' keyboard emulation. In `Real Mode' PC keys are directly equated with keys on the Dragon keyboard - thus some key combinations produce unexpected results on the screen due to the differences between the PC and Dragon keyboards. You can switch between keyboard modes either from the general options menu (F4, 1) or by typing /K on the command line when you start PC-Dragon. If a program tries to access the keyboard at the hardware level and you do not have `Real Mode' selected then the emulator will still attempt to provide `Real Mode' information to the program, however this pseudo `Real Mode' information is less compatible than true `Real Mode'. Therefore you may still experience problems, particularly when using programs which require keys to be pressed continually. The following PC keys are used to emulate special Dragon keys: ESC or END BREAK key. HOME CLEAR key. PG UP Pause (SHIFT + @ key). PG DN Continue (ENTER key). INS, DEL `I' and `D' keys (as used by the EDIT command). CURSOR KEYS Dragon cursor keys. CAPS LOCK Dragon caps lock (SHIFT + 0 key). The following keys apply only to `PC Mode': SHIFT + F1 to F4 SHIFT + Dragon cursor keys. SHIFT + TAB ESC key (as used by the EDIT command). The following keys apply only to `Real Mode': ALT + CURSOR KEYS SHIFT + Dragon cursor keys. ALT + ESC ESC key (as used by the EDIT command). `[' and `]' Brackets `(' and `)'. There are also additional facilities which are available only in `PC Mode'. These are: Freeze Mode Engage SCROLL LOCK to inhibit changes to the video mode. History Buffer At any prompt press CTRL-RETURN to repeat every key typed between the two most recent presses of the RETURN key. Function Keys The keys F6 and ALT-F1 to F10 can be programmed to perform any sequences of key presses. Press F7 to change the current assignments. BASIC Keywords The keys ALT-A to Z can be programmed to perform sequences of key presses in the same way as above. The default assignments for ALT-A to Z keys are shortcuts for BASIC keywords. For example ALT-G for `GOTO', ALT- N for `NEXT' and ALT-R for `RUN [RETURN]'. These additional facilities are implemented at the lowest level of keyboard handling performed by the emulator, which enables all key sequences to be simulated whether they are input for the Dragon or function keys handled by the emulator. 2.4.2 Video PC-Dragon uses the PC 40 column text mode to emulate the Dragon text mode, with IBM approximations to Dragon graphics blocks used to simulate low resolution graphics. Graphics modes are emulated using EGA 16 colour graphics, with all 56 of the Dragon graphics modes fully implemented. A 2- bit encoding scheme is used for all modes, with separately configurable colours for the bit pairs 00 (both bits), 01 (left bit), 01 (right bit), 10 (left bit), 10 (right bit), and 11 (both bits). Semi-graphics modes are not supported and will cause the emulator to display a 4 colour graphics mode of similar resolution. The emulator supports optional artifacting in black and white graphics modes. This may be enabled either by using the /AR and /AB command line options or by using the display options menu. The emulator then imitates the red/blue blur exhibited by NTSC televisions. This facility is useful for Dragon emulation as well as CoCo emulation since many Dragon programs have been imported from the USA where the effect is sometimes used to an advantage. Examples of games which are much improved by turning on artifacting are Mr Dig, Zaxxon, The Vortex Factor and Shenanigans. Software which uses fast mode switching techniques to achieve special effects (such as parts of Rommels Revenge, Time Bandit, Space Wrek and Zaxxon) will not be displayed very smoothly by the emulator. This is because PC-Dragon cannot refresh the graphic screen fast enough. For such games engage SCROLL LOCK to defeat the effect. This fixes the display into a single video mode. 2.4.3 Cassette Port The cassette port is emulated by intercepting operating system requests for reading and writing to cassette and redirecting these to operate on DOS files. The `virtual cassette' files contain exact same data that would be on a cassette and are given the extension CAS. To use cassette files simply type the Dragon commands exactly as you would on a real machine (e.g. `CSAVE', `OPEN', `CLOADM'). A dialogue box will then appear prompting you to enter the name of the virtual cassette file to use. Type in the filename and press RETURN. The cassette will remain accessible until the end is reached, until the Dragon attempts to open the cassette stream in a different I/O mode, or until the cassette port is reset by pressing F3, 1 (this is useful if you encounter an IO ERROR?). Filename prompting may be disabled by using the general options menu or the /NN command line option. The default name will then be used unless an error is encountered. When searching for virtual cassette files, the emulator will optionally use sub directories CASSETTE, CASSETTE\GAMES and CASSETTE\ARCHIVE below your PC- Dragon directory. The CASSETTE sub directory is read/write whereas CASSETTE\GAMES and CASSETTE\ARCHIVE are treated as read-only. Cassette port emulation is implemented using special I/O opcodes which are installed into the ROM image(s) upon start-up of the emulator. This enables the breakpoints to remain active even if the Dragon 64 is switched into map mode 1 and the alternative ROM image is used. Similar I/O opcodes are also used for the implementation of joystick and keyboard breakpoints. All of these may be disabled by using the /NB option upon start-up. This gives `pure' emulation of the base machine but makes cassette facilities unavailable. 2.4.4 Printer Port A printer may be connected to a communications port of the PC and used directly from within PC-Dragon. Either parallel or serial ports may be selected for output irrespective of the machine being emulated. If any parallel/serial conversion of data is required then it is performed automatically by the emulator. There are a number of printer options, which can be selected using either the printer menu (F4, 3) or the command line options. To configure which port is used for printer output specify /LPT1, /LPT2, /COM1 or /COM2 when you start PC-Dragon. Alternatively printer output may be redirected to the file PRINTER.OUT by specifying /F or /FILE instead of a port name. By default port LPT1 is used if it is present, otherwise COM1 will be used or printing to a file will be enabled. For serial ports the baud rate may be specified as /B1200, /B2400, /B4800 or /B9600 (the default is 2400bps). In all cases the data is transmitted as 8 bits with 1 stop bit and no parity. Two modes of support for character output are available. In the default `basic' mode characters are simply transmitted to the port on request from the Dragon (provided that the printer is ready). In `advanced' mode (/P option) the first character sent to a printer causes a standard configuration/initialisation sequence to be issued to the printer. Following this the emulator will pause for 5 seconds for the printer to return on-line and then (for parallel printers) the emulator will poll the printer to enquire whether it is ready to receive characters before sending data. If the printer is not ready then PC-Dragon will wait for up to 20 seconds if necessary. For printers which require both and codes as line terminators the emulator may be instructed to automatically translate codes into . To do this specify /CRLF on the command line or use the printer menu. This feature is useful for text output only and is disabled by default. Note that because Dragon software often outputs garbage to printers as a side effect of generating sound, it is not recommended that advanced printer spooling be enabled unless printing facilities are actually required. Moreover, it is usually desirable to turn off any connected printer whilst running programs which do not use the printer. Networked users may wish to disable printer support completely by giving the /NP option. For CoCo emulation the time which elapses between each bit sent to the serial port must be no greater than 10 seconds in order for the bits to be assembled into parallel data. If more than 10 seconds elapses then the current incomplete byte is assumed lost and is discarded. 2.4.5 Joystick Port PC-Dragon provides emulation of the Dragon joysticks using either the keyboard, mouse or PC joystick. By default a mouse is used, but the joystick menu (F4, 4) or /JOY option may be used to select the PC joystick instead (note that this causes a reduction in performance). Swirl the joystick at the start of play to configure the available range. You can also choose either analogue or digital emulation. Analogue is the default mode, with /G used to choose digital emulation. If `Real Mode' keyboard emulation is selected then the keyboard can be used to simulate the joysticks. The cursor or keypad arrow keys perform digital movement, with keypad `5' providing the fire buttons. Keypad `1' and `3' may be used for left and right fire buttons separately. When software reads the joystick positions directly through the Dragon hardware a sampling rate is used by the emulator to reduce the number of unnecessary updates that it performs. By default 28 hardware reads are accepted before the stick positions are updated. To change this use the joystick menu or /Rr to change the sampling rate value (r must be in the range 0 to 255). 2.4.6 Cartridge Port Machine code cassette files may be converted to the DGN format and used with the emulator as cartridge images. Use the Dragon Convert utility to do this. Cartridge files may then be installed prior to start-up of the emulator by typing their name on the command line. They can also be installed later by using the F3 menu. Cartridges which are loaded from the command line or PCDRAGON.CFG file may or may not automatically execute depending on how they were designed. Bootup snapshots (these are introduced in section 2.7.4) prevent cartridges from automatically executing (if necessary you can type /SB to prevent the emulator from loading bootup snapshots). The ROM_STUB.DGN file can be used in conjunction with the MS-DOS `COPY' command to make cartridge files of any cartridges that you have transferred to your PC as a raw image (e.g. by uploading the data from an EPROM programmer). See section 3.6 for further information on using this header file. Cartridges can be copied to cassette and transferred to PC format by using a sound card and Dragon Convert (see section 3.2). In most cases you should save either 4K or 8K of data starting at address $C000. For example, to capture the Alldream cartridge use: CSAVEM "ALLDREAM", &HC000, &HDFFF, &HC000 Cartridges which automatically execute may be captured using a technique which is described in the documentation for CoCo2. As an alternative to the DGN format, cartridges may also be used in snapshot format (see section 2.7.3). 2.5 Emulator Options And Menus 2.5.1 Help Screen Press F1 to access the help screen. Then press SPACE or RETURN to page through the display, or ESC to dismiss the help screen. 2.5.2 Text Viewer Menu Press F2 to access the text viewer menu. Using this menu you can invoke the built-in text viewer to display this manual or the contents of local sub directories. 2.5.3 File Management Menu Press F3 to perform file management. You can then press `1' to reset the cassette port (useful if you encounter an IO ERROR?) or `2' to `7' to load or save various types of files. Press `2' or `L' to load a snapshot, or `3' or `S' to save. See section 2.7.3 for more information about snapshot files. Pressing `4' or `5' allows you to load or save screenshots. These are unformatted files containing the contents of the currently displayed Dragon screen. The default extension given to the filename will depend on the current video mode. It will be DTX for text mode or D## in graphics mode, where ## is a number `00' to `15' representing the current resolution. The final two options on the file management menu allow you to load programs in cartridge (DGN) or Motorola S-record (S19) format into memory. These files will not automatically execute upon loading. 2.5.4 Options Menu Press F4 to access the options menu. From here you can select further menus to change the current PC-Dragon configuration. Options accessible from these menus may also be changed by using the command line when you start the emulator, using PC-Dragon programmer services (except for options relating to snapshots), or chosen as default by placing the command line text in file PCDRAGON.CFG. A summary of the available command line equivalents may be obtained by typing `DRAGON /?' or `DRAGON /H'. You can also use the U*IX style `-' rather than `/' to specify options. Comments may be included in the configuration file by prefixing them with `#'. Press `1' to configure the keyboard mode, enable or disable the cassette filename prompt, instruct the emulator to ignore or pause upon encountering illegal opcodes, change the level of swapping, or configure the IRQ rate. Press `2' to turn lower case text on or off, turn the PC cursor on or off, or change the current artifacting mode. Press `3' to change the printer port and serial baud rate, enable or disable to translation, or change the printer interfacing mode. Press `4' to configure the joystick emulation device, type, and sampling rate. Press `5' to select the format used for loading and saving snapshots, enable or disable compression of saved snapshot data, change the save length for snapshots, alter the portability designation saved with snapshots, and to allow or inhibit the loading of emulator options, the debugger state, and PC- Dragon `extensions'. Press `6' to change the Dragon colours. You should then choose either text mode colours, monochrome graphics colours, or 4 colour graphics mode colours. Following this select the palette (as determined by the `SCREEN' command) and choose foreground/background or pixels/border options as required. If you wish to change pixel colours a menu will appear from which you should select which colour number you wish to change the appearance of. Note that whether you are changing monochrome colours or 4 colour mode colours the pixel colours are configured based on a 2-bit encoding scheme (see section 2.4.2). Once the item that you wish to change has been selected a window will appear which shows the available colours. The current colour is indicated by `*'. Select a new colour by pressing `1' to `9' or `A' to `F' (or press ESC, RETURN or SPACE to leave the colour unchanged). 2.5.5 Video Mode Menu Press F5 to change the current Dragon video mode. You can then alter the number of available colours, the palette number in use, the width of graphics mode pixels, the number of bytes of RAM used for video memory (together with the pixel width this determines the resolution of graphics modes), and the base address of video memory. A number of short-cut keys are also available. You can switch immediately to PMODEs 1 to 4 by pressing CTRL-F1 to F4, and to text mode by pressing CTRL- F8. To toggle the palette, number of colours, or pixel width you can press CTRL-F5, CTRL-F6 or CTRL-F7. 2.5.6 Function Key Configuration Press F7 to change the assignment of `PC Mode' function keys. With the F7 menu displayed press the key that you wish to change (without ALT) and then enter the new text string to be assigned to that key. To assign a string to F6 press `#' (after doing this you will need to press `6' if you later wish to reassign ALT-F6). See section 2.7.6 for more information on function key assignments. 2.5.7 Control Menu Press F8 to access the control menu. You can also access the control menu by pressing the key combination CTRL-ALT. Note, however, that CTRL-ALT will work at any time whereas F8 will only work when the keyboard buffer is empty (this in fact applies to all emulator control keys, but only when `PC Mode' keyboard emulation is selected). From the control menu you can perform warm or cold restarts (equivalent to a real machines RESET button and OFF/ON switch respectively). You can also run an MS-DOS shell or switch to the built-in debugger. Accessing the control menu discards any key presses which are queued in the keyboard buffer. 2.5.8 Assembler Menu The assembler menu is accessed by pressing F9. This menu provides facilities which integrate the emulator to an assembler. It is discussed in detail in section 2.6.1. Alternatively, pressing CTRL-F9 jumps directly to the editor and then returns to the assembler menu when editing is complete. 2.5.9 Information And Configuration Screen Press CTRL-F10 to display the information and configuration screen. The screen displays a summary of the current PC-Dragon configuration and additional run-time information such as the current video mode. Included on the information screen is an estimate of the performance of the emulator relative to a real Dragon. This calculation is based on the time taken to execute instructions equivalent to two seconds on a real machine (i.e. normally this is 100 counts of the TIMER function). The speed is only measured when required for the display, and is not updated unless the emulator was executing continuously during the two emulated seconds prior to CTRL-F10 being pressed. Press ESC to return to the emulator. 2.6 Program Development Tools 2.6.1 Integration Of The Emulator With An Assembler PC-Dragon includes integrated support for the freeware Motorola assembler AS9.EXE. To use the assembler activate the assembler menu by pressing F9 and then press `1' to edit your source file. Pressing CTRL-F9 also has the same effect. PC-Dragon then starts your text editor and returns to the assembler menu when you exit. You can now press `2' to call the assembler. If the assembly completes successfully then PC-Dragon will display the message `Assembled with no errors!' and load the program image into memory. If unsuccessful then a TextView window will open to allow you to review the assembler output. To edit the source again press `1' as above. At a later time you can return to the assembler menu and press `3' to reload the program image (this also exits the assembler menu) or `4' to view the assembler output again. To change the 6809 source filename used press `5' and enter the new filename. By default `SOURCE' is used and the extension `A09' is added. The source filename may also be specified on the command line when you start PC- Dragon by preceding it with `@'. To configure the paths for the assembler and your favourite editor use the /IA and /IE command line options. These should followed by the path name. E.g. DRAGON /IAC:\UTILS\AS9 /IEB.EXE @MY6809.ASM Warning: AS9.EXE seems to implement memory allocation in a way which is incompatible with PC-Dragon. You may experience crashes after calling the assembler, particularly if you try to run an MS-DOS shell. 2.6.2 Built-In Debugger PC-Dragon includes a powerful built-in debugger and disassembler. The debugger tracks recently executed instructions, allows modifications to registers, flags and memory, and supports a wide range of break conditions. To switch to the debugger press F10 or select the debugger from the control menu. The debugging screen will then be displayed. The screen contains three windows. On the left hand side is a window which can display either the current Dragon text screen, one of two help pages for the debugger, or a memory dump (beware that selecting the memory dump display slows down single step execution). At the bottom of the screen is a small window which displays status messages and other information. The right hand half of the screen is used for the main debugger window. This contains a disassembly section, a section showing the contents at the top of the user and system stacks, a section displaying the current register and flag values, and a section displaying the current global breakpoints. The disassembly section of the main window shows the four most recent instructions executed (if known), the current instruction (highlighted in blue), and the next four instructions to be executed (assuming that no jumps or interrupts occur). The disassembly section also contains a cursor denoted by `>' and `<'. The cursor is used to mark addresses on a temporary basis and may be moved up and down the display using the cursor keys, or returned to the address of the program counter by pressing HOME. If you move the cursor beyond the bottom of the display then the disassembly will scroll to the next instruction. The functions of the debugger are accessed using the following keys: 1 Set breakpoint 1 address. Keys `2' to `6' similarly set the addresses for breakpoints 2 to 6. These breakpoints are global, remaining active in addition to any other break conditions which are activated. A Display the effective address associated with the current instruction. B Set a temporary breakpoint and continue execution. D Switch to disassembler. Enter the required start address at the prompt. Then SPACE scrolls the disassembly by a full page, ENTER and DOWN keys scroll the display by a single line, and `D' allows a new address to be specified. E Quick edit memory - does not prompt for a new address. F Toggle CPU flags. Press additional keys to indicate which flags to toggle. G Continue execution until a global breakpoint is reached. H Display main help page. Press `H' again for the secondary help page. I Fill memory with a constant value. Enter the required boundary addresses and the fill value. Memory will then be filled inclusive of the addresses given. M Dump/edit memory. Enter the start address at the prompt. Then change the values as required, scroll up and down using the cursor keys, or press TAB to switch between the hexadecimal and ASCII sections of the display. N This key causes the conditional jump at the current address to be evaluated. Program execution then continues until evaluation of the condition gives a different result (i.e. a different execution path is taken). O Continue execution until a specific opcode is reached. Enter the required opcode at the prompt (both 8-bit and 16-bit opcodes can be entered). Q Continue execution until an RTS instruction is reached. R Change register values. Press additional keys to indicate which register you wish to change and then enter the new value. If you attempt to assign a value larger than 255 to either A or B then the value will be assigned to D. S Step to the next instruction. T Display the current Dragon text screen in the left hand window (this is the default use of the window). V Continue execution until a register changes or has been assigned a specific value. Press a key to select which register is to be monitored and then enter the value on which execution should halt. To break on any change in the value of the register simply enter the current value. X Continue execution with a new program counter value. Enter the required new program counter value at the prompt. SPACE Step over to the next instruction. This command is equivalent to the `S' command except when the current instruction is a JSR, BSR or LBSR instruction. After stepping over a jump instruction the disassembly continues to display the instructions stepped over rather than those most recently executed. RETURN Set a temporary breakpoint at the current cursor address and continue execution. TAB Set or remove a global breakpoint at the current cursor address (LEFT and RIGHT cursor keys also have the same function). To quit from the debugger press either ESC or END. Once you have quit all execution tracing and break conditions are suspended. This gives the fastest possible execution speed. If you dismiss the debugger screen with commands such as `B', `G' or `X' then the debugger will still be active and the performance of the emulator will be reduced. 2.6.3 Emulator Services PC-Dragon provides a range of services to allow the emulated Dragon to access the emulator environment and configuration options. The services are accessed by the use of special write-only memory in the region $FFEC to $FFEF and may be used from both BASIC and machine code. Upon start-up of the emulator the services are disabled in order to maintain software compatibility. To enable the services simply write $50 to address $FFEE and $43 to address $FFEF. They can then be accessed by reading from address $FFEE or $FFEF. If $FFEE is read then the 6809 registers A, B, X, Y and U are used to pass any required parameters to the services and to receive the results. If $FFEF is read then memory is used instead. Memory locations $FFEC and $FFED should point to the address of the parameters, which must be formatted as a register dump in the order A, B, X, Y and U. On start-up of the emulator the contents of $FFEC and $FFED are initialised to point at $FFE0; enabling the services also makes memory in the region $FFE0 to $FFEB available as RAM. The services available in this version of PC-Dragon are listed in Appendix A. In all cases the B register is used to indicate the required service number. All registers not explicitly specified in the table are not affected, and all services return 0 upon success, 255 if the requested service is not supported, or an error code as specified. Appendix B lists the colour values used by the colour configuration services. An example code fragment to initially detect PC-Dragon is given below: LDD #$5043 ; Enable PC services. STD $FFEE LDX #0 ; Set X <> signature. CLRB ; Service 0: installation check. TST $FFEE ; Call emulator service. CMPX #$5043 ; Check for PC-Dragon signature. BNE NOTPCD The following will change the default text screen colours to BLUE on BUFF: LDD #$5043 ; Enable PC services. STD $FFEE LDD #5 ; Service 5: set text colours. LDX #$1706 ; Set-up new colours. TST $FFEE ; Call emulator service. To turn on the PC cursor from BASIC: POKE &HFFEE,ASC("P") `Enable PC services. POKE &HFFEF,ASC("C") POKE &HFFE1,2 `Service 2: cursor control. POKE &HFFE0,1 `New state is solid. I=PEEK(&HFFEF) `Call service. Finally, the following is a short program which will allow the mouse to draw on a PMODE3 graphics screen. The normal drawing colour will be yellow. Hold down the left mouse button for blue, the right mouse button for red, or both to erase. 10 PMODE3:SCREEN1,0:PCLS 20 POKE &HFFEE,ASC("P") `Enable PC services. 30 POKE &HFFEF,ASC("C") 40 POKE &HFFE1,8 `Service 8: get mouse status 50 IF PEEK(&HFFEF) THEN STOP `Call service, check return. 60 COLOR (PEEK(&HFFE0)+2) AND 7 `Set colour from button info. 70 LINE-(PEEK(65507),PEEK(65509)),PSET `Draw line to cursor. 80 GOTO 50 2.7 Additional Information 2.7.1 Video Refresh Interrupt The video refresh IRQ is emulated by PC-Dragon, and occurs relative to the emulated machine speed (every 17,800 emulated clock cycles). However, since the emulator does not run at real speed except on very fast machines, the frequency of the interrupt does not usually match the 50Hz signal of the real machine. On a 486DX-33 the frequency is approximately 20Hz. To help overcome this deficiency the interrupt rate may be artificially increased if required. Simply use the general options menu or the /Q option to alter the number of cycles between interrupts. This allows some programs which use the IRQ interrupt for timing purposes to run faster (e.g. Chuckie Egg), as well as reducing the pauses during sound effects in some software. PC-Dragon does not emulate the horizontal retrace signal. 2.7.2 Illegal And Undocumented Instructions PC-Dragon includes emulation of the undocumented RESET opcode, and also treats undocumented `illegal' register transfers and exchanges in the same way as a real 6809. In order to maximise speed no action is taken for illegal indexed mode postbytes. E.g. STA (,U+) does not officially exist but will be executed correctly by PC-Dragon due to the symmetry of the instruction set. When other unknown opcodes are encountered the emulator will pause and display a window describing the problem. The message invites you to choose an action for handling the opcode. You can ignore the opcode, ignore all future illegal opcodes (this choice may also be selected as default using the general options menu or /II command line option), or you can switch to the control menu. The debugger may be accessed from the control menu if required. 2.7.3 Snapshots Snapshots are frozen images of the current state of the emulated machine together with the current emulator options/configuration settings. They may be saved at any time and loaded back later to restore the emulator and emulated machine to the exact same state. Snapshots created by emulators/utilities other than PC-Dragon may be loaded into PC-Dragon but will not necessarily contain as much information as those created by PC- Dragon; snapshot files may even contain just a memory dump and an execution address. By default the emulator will use a snapshot format which is fully compatible with the CoCo2 emulator, although you must use the snapshot options to configure which version of CoCo2 you have (the default is V1.4, which is also suitable for CoCo2 V1.5). There are also snapshot options to disable the loading of emulator options/configuration settings from snapshots. The saved length of snapshots may be changed (but not the start address), and Run Length Encoded (RLE) compression may be used when snapshots are saved. Compression can significantly reduce the disk space required for storing snapshots but you should be aware that if you choose to use compression then saved snapshots will no longer be compatible with CoCo2. The PC-Dragon implementation of RLE compression automatically optimises the substitution codes for each snapshot (although the compression rate achieved is still much less more complex techniques such as Lempel-Ziv-Welch encoding). As mentioned above, all snapshots saved by PC-Dragon also contain additional information which is not used by other emulators. These `extensions' contain a description of the current debugger state (current breakpoints, last edit address, active break conditions, etc.), additional machine state information, and additional user options. They are incorporated into the snapshot format in a way which does not affect compatibility with other emulators. When a snapshot is loaded by PC-Dragon it will automatically detect and use the `extensions' if they are present. Note however that if you manually edit a snapshot or load one into another emulator and re-save it then the `extensions' will be destroyed. This will rarely cause problems but it is possible to reduce the usefulness of a snapshot in this way. For example, because the base snapshot format does not contain all of necessary PIA data, many snapshots saved by other emulators cannot be loaded from the command line without finding that the keyboard is unusable in `Real Mode' (using a bootup snapshot file can usually correct this problem). By default PC-Dragon uses the PAK extension when saving a snapshot. PAK is also used when loading but in addition to this the emulator will look for snapshots with extensions D32, D64, D96 or CCO as appropriate to the architecture being emulated. The extension D96 is used to identify snapshots which are compatible with both Dragon 32 emulation and Dragon 64 emulation. An option from the snapshot menu can be used to specify the portability of snapshots prior to using the snapshot save facility. A snapshot can be designated as non-portable, portable to any Dragon, or portable to any supported architecture. The `Incorrect ROM' warning message is then inhibited when the snapshot is reloaded. Note, however, that this feature is implemented for cosmetic reasons only - the emulator automatically attempts to repair snapshots which are loaded into incompatible architectures irrespective of the portability designation. When loading a compressed snapshot file you do not need to specify that the snapshot is compressed or set the correct snapshot format version. The emulator will automatically detect the snapshot format used and uncompress the data. If you load a snapshot with a start address of $C000 then PC-Dragon will assume that it is a cartridge game and will generate an FIRQ in order to execute it. To configure the snapshot options from the command line use /SV followed by the version of CoCo2 that you have (`2', `3' or `4'), /SP followed by the portability designation to be given to saved snapshots (`N', `D' or `A'), /SC to enable or disable compression, /SL followed by a number in the range 1 to 65280 indicating the snapshot save length, /SO to inhibit the retrieval of emulator options when snapshots are loaded, /SD to inhibit the restoration of the debugger state, and /SX to inhibit PC-Dragon `extensions'. If you have the NDUG release of CoCo2 V1.2 then you should select V1.2 format snapshots. For the Internet release of CoCo2 V1.2 and for CoCo2 V1.3 you should select V1.3 format. For CoCo2 V1.4, CoCo2 V1.5 and T3 select V1.4 format. 2.7.4 Bootup Snapshots At start-up PC-Dragon attempts to speed up initialisation by loading a snapshot which has been prepared with an image of a fully booted up machine. If such a snapshot is found then the snapshot is executed immediately rather than you having to wait whilst the emulated machine performs a cold boot and self-test. Bootup snapshots must be in compressed format and named BOOTSNAP (with extension D32, D64 or CCO as appropriate). They are always loaded with PC- Dragon `extensions' enabled and emulator options and debugger state ignored. Working bootup snapshots are included with this distribution of PC-Dragon but may be replaced if required. If you wish to do this then you should ensure that you use the emulator with `Real Mode' keyboard emulation selected when booting the Dragon to prepare your snapshot. If you forget to do this then the bootup snapshot will not contain the PIA information necessary to use `Real Mode' keyboard emulation in the future. The command line /SB option may be used to disable the loading of bootup snapshots. 2.7.5 Swapping PC-Dragon is able to swap memory to disk prior to functions which require auxiliary programs to be called. This makes more conventional memory available to these programs. With no swapping PC-Dragon may use up to 310K of base memory, but with swapping enabled PC-Dragon can reduce it's usage to 190K. The default swapping option causes memory to be swapped out to disk only when you call an MS-DOS shell. The swapping level may be increased so that swapping is also enabled for calls to your editor or prior to all calls to auxiliary programs. To change the swapping level use either the general options menu or /IS (and a number from 0 to 3) from the command line. 2.7.6 Function Key Assignments With `PC Mode' keyboard emulation selected the keys F6, ALT-F1 to F10, and ALT-A to Z may be programmed to simulate other key presses. The function keys may be programmed with up to 64 characters each and the letter keys with up to 10 characters each. To change the assignments use the /F option, the emulator services, or the F7 key. The default assignments are listed in Appendix C. The new strings should normally be given in lower case. This is because the strings represent key presses rather than formatted input and will be translated to upper case at the time that they are passed to the Dragon operating system. Note also that underscore should be used instead of the SPACE character because SPACE is interpreted as an option separator by MS- DOS. If using the command line to change key assignments /F should be followed by the name of the key to change and the new text string. For the key id give `#' for F6, `1' to `10' for ALT-F1 to F10, and `A' to `Z' for ALT-A to Z. The text string may be delimited by virtually any character. E.g. `DRAGON /FCXcloadmX' is an acceptable command line assigning the BASIC keyword `CLOADM' to ALT-C and using the `X' character as a delimiter. Text strings may contain control sequences in addition to printable characters. To specify a control character simply use the `^' notation. E.g. `DRAGON /F#!^Q!' configures F6 to quit the emulator. The `^' character is also used as an escape character, so that `^^' represents the UP key. The sequence `^@' may be used for the null character, thereby enabling extended ASCII codes to be simulated. For example `^@B' represents the F8 key. 2.7.7 Changing Emulator Colours From The Command Line To change the emulator colours from the command line the /O option is used. This should be followed by `T' for text colours, `G' for graphics colours or `B' for border colours. Then `0' or `1' for the `SCREEN' value, and (except for text mode) `0' or `1' for PMODE0 (monochrome) or PMODE1 (4 colour mode) colours. After these initial characters you should give the new colour as a hexadecimal string. For text mode the required hexadecimal string is two characters. The first represents the foreground colour and the second the background colour. These are in the range `0' to `F', using the standard PC text mode colour mappings (see Appendix B). For graphics mode colours a string of six EGA colour values is required; one byte for each of the 2-bit values in the scheme described in section 2.4.2. For border colours a single EGA colour value is required. 2.7.8 Cassette Files The CAS file type used by the emulator is simply a raw bit stream of cassette data. Because of this it is simple to append one cassette onto the end of another by using the MS-DOS `COPY' command (the /B switch must be given so that a binary copy is performed). For example, the following command will add the cassette PART2.CAS onto the end of the cassette PART1.CAS: COPY /B PART1.CAS + PART2.CAS COMPLETE.CAS Since the emulator does not need to start and stop a cassette recorder it does not need a motor delay when writing data. File leaders are also optional. You can therefore speed up PC-Dragon writes to cassette (and save on disk space) by issuing the following POKEs before you type `CSAVE', `CSAVEM' or `OPEN' commands: For Dragon ROM: POKE 144,0 : POKE 145,1 `Reduce number of leader bytes. POKE 149,0 `Reduce cassette motor delay. For CoCo ROM: POKE 146,0 : POKE 147,1 `Reduce number of leader bytes. `Cannot reduce CoCo motor delay. Note that if you are planning to use virtual cassette files with the CoCo2 emulator then you shouldn't shorten the leader in this way. Furthermore, if you intend to use Dragon Convert to transfer files back to a real Dragon then you might even wish to save programs with longer leaders than normal. To do this you could type: For Dragon ROM: POKE 144,3 `Increase number of leader bytes. For CoCo ROM: POKE 146,3 `Increase number of leader bytes. Cassette files containing machine code programs can be used with either Dragon or CoCo emulation but are unlikely to execute correctly on both platforms due to the differences between the ROMs of the machines. BASIC programs can usually be used with any architecture so long as they are saved in ASCII format. E.g. CSAVE "BASICPRG", A will save a BASIC program that can be used in conjunction with any ROM file. More disk space is required when files are saved in this format and the time taken to load and save is also greatly increased. 3 File Transfer 3.1 Overview PC-Dragon includes utilities to support the transfer of Dragon cassette and disk software to the PC environment. To transfer cassette software you will need either a SoundBlaster Pro sound card or a special cable which connects the PC parallel port to a cassette recorder. The reliability that you can expect from either method varies according to the equipment used. To transfer disk software you will need additional Dragon-DOS disk reading software such as Compusense's PC Convert. The documentation for CoCo2 also describes methods for transferring software using a serial cable (suitable for Dragon 64 and CoCo only), and for transferring cartridges to the PC. After transferring software to the emulator you should be aware that it may not function correctly in the following cases: 1) Software which uses semigraphics display modes or fast mode switching will not be displayed correctly. 2) Any software that plays music or sound effects will suffer from long pauses. In any event the execution speed of the software will be highly dependent on how powerful your PC is. The following sections describe the included utilities. These translate PC files in various formats to or from the formats used by the emulator. 3.2 Dragon Convert Dragon Convert is a multi-purpose utility to convert various file types to the virtual cassette format used by PC-Dragon. It can convert sampled Dragon cassettes in digital audio format (WAV and VOC files), Dragon-DOS files (BIN and BAS), PC-Dragon cartridge files (DGN), QBasic (BAS) and pure binary files. In can also be used to convert files from virtual cassette format into cartridge (DGN) or QBasic (BAS) format. The filename of the file to be converted should be given as the last argument to Dragon Convert (`DRAGON' is otherwise used as the default). If no extension is given then the program will look for a file with extension WAV, VOC, BIN, BAS, DGN or CAS. The different methods of operation of Dragon Convert are described below. A summary of the available command line options may be obtained by typing `DC' with no arguments. Note that Dragon Convert will overwrite existing files without warning. 3.2.1 Extracting Files From Sampled Cassettes Where the input to Dragon Convert is a WAV or VOC file the audio information is scanned for Dragon cassette data and converted to a virtual cassette file. The output filename is derived from the Dragon filename rather than the input filename. During conversion Dragon Convert displays a counter to show the progress converting the input file. If the cassette programs conform to the conventional Dragon cassette format then the filenames and load/execution addresses of binary files are listed as the programs are encountered. All of the files contained within a single input file will be placed into a single output file. If Dragon Convert detects a loading error in the WAV or VOC file then you are given the option to abort the conversion, to retry a block, or to proceed with the conversion ignoring the error. If you choose to ignore errors then the converted file is unlikely to be usable, although commercial software does exist which deliberately contains errors. If you choose to retry a block then the current conversion parameters (see below) will appear so that different parameters may be entered. Type the new values at the prompts or press RETURN to leave one of the parameters unchanged. Dragon Convert then attempts to load the failed block using the new parameter values. There is, of course, no advantage to be gained by retrying a block without adjusting either of the parameters. Dragon Convert will normally assume that the sampled file begins with a leader, and will initially seek the leader in order to synchronise with the data. If a leader is not present then this will usually cause data to be missed - if necessary give the /L option on the command line to disable the feature. Although Dragon Convert is designed to work with data in the conventional Dragon cassette format it may also be used with cassettes which use a proprietary format. For such programs specify /R on the command line and Dragon Convert will scan the input as a raw bit stream. This results in a file called CASSETTE.CAS. When Dragon Convert is used with this option the display shows only the number of bytes converted and loading errors cannot be reported. The following actions may be taken if you suffer from loading errors: o Use the highest available sampling rate for your sound card. At least 22KHz is required. o The amplitude of the input data should comfortably span the available range. Adjust the input volume if necessary. o It is a good idea to clean up the wave form before presenting it for conversion. Try cutting any white space before the first program block and removing any noisy parts of the leaders. o MS-Windows software (E.g. Creative Wave Studio) usually produces better results than MS-DOS based software. o The wavelength amplitude threshold may be specified on the command line using the /Wn option. For a 44KHz sample a threshold of 29 to 31 is usually correct. For 22KHz files the value of n should be in the range 12 to 15. This option is usually essential if you use the /L option. o The relative volume of the wave form may be specified using the /Sn command line option, where 0 < n < 126. This option typically has less impact than the /Wn option, but is usually essential if you use the /L option. You can abort the operation of Dragon Convert in the middle of a conversion by pressing the CTRL key. 3.2.2 Converting Other File Types Dragon Convert can be used to add the required cassette formatting data to several file types so that they may be loaded into the emulator using the virtual cassette system. Simply specify the filename of the file to be converted on the Dragon Convert command line. If the input file is a cartridge (DGN) file then it will be converted to a cassette file with a filename taken from the header of the cartridge file. For all other conversions the output filename is derived from the input filename. Output is always to the current directory. For Dragon-DOS and cartridge files the header information held in the file is retained by the cassette file. For other binary files the cassette file is given a load address of $600 and an execution address of $167. When an ASCII file is converted it is assumed to be a QBasic file and is converted to a gapped ASCII BASIC cassette file. Dragon Convert automatically reformats the carriage returns and line feeds in the file to Dragon format and ensures that the line numbers have appropriate spacing. You must save your QBasic files in ASCII format to use this facility. An ASCII input file may instead be converted to a cassette file in binary format by giving the /B option on the command line. This also inhibits the data reformatting. 3.2.3 Converting Files From Cassette Format A secondary use of Dragon Convert is to convert cassette files back to digital audio format so that they can be written to cassette and loaded into a real machine. When converting to audio format the cassette file is not examined; this enables any file type or proprietary format to be converted. To use Dragon Convert for this purpose simply specify the filename of a cassette file on the command line when you start the program. By default a 44KHz WAV file will result. This gives very high quality playback but requires more than 8Mb of hard disk space for a 32K Dragon file. You can specify /22 on the command line to request a 22KHz output file instead, or /11 for an 11KHz output file. Dragon Convert can also be used to convert cassette files to two other formats. Machine code or tokenised BASIC cassette files may be converted to PC-Dragon cartridge files, whilst ASCII BASIC cassette files may be converted to QBasic files. Specify the /D option to perform these conversions. If the input file is found to contain errors then Dragon Convert will exit immediately. Bit stream cassette files will also be rejected. 3.3 CopyCas Utility CopyCas is a utility to make renamed copies of cassette files. It will choose an appropriate new DOS filename and copy the data held in the cassette file renaming the first Dragon file at the same time. The syntax for CopyCas is as follows: COPYCAS [/C] dragon-source dragon-destination The filenames that are required are the Dragon filenames rather than the names of the equivalent DOS files. They are not case sensitive unless the /C option is given. CopyCas will fail if the first block in the cassette file is not a header block, if the block is not byte-aligned within the file, if an ?IO ERROR is encountered in the first block, or if the Dragon source and destination filenames translate to the same DOS file. Please note that CopyCas will overwrite existing files without warning. 3.4 WhatIs Utility WhatIs is a general purpose utility which uses simple heuristic rules to recognise and extract information from files of various types. It can probe cassette, snapshot and cartridge files and describe their contents in some detail. Specify the name of the file to be examined when you run WhatIs. WhatIs has two modes of operation. By default it will simply print a sentence or two describing the contents of the input file. For a full description of the input file run WhatIs in verbose mode by giving the /V option on the command line. It will then decode as much of the information in the file as it is able to recognise. When used in verbose mode with a cassette file, for example, WhatIs will print a breakdown of the names and cassette blocks for all of the Dragon programs in the file. When used with a snapshot file it will describe the machine state which is encapsulated in the snapshot and the emulator options which are required. WhatIs also attempts to classify approximately 50 other common file types, in a similar manner to the `FILE' command of U*IX. All decisions are based on the contents of the files and not the filenames or extensions. 3.5 ReadVoc Utility ReadVoc is a utility which can read Dragon cassettes via the PC parallel port. It requires a special cable to be constructed but this is a simple and inexpensive process (alternatively, ready-made cables can be ordered from Brian Gaff, the UK support contact for Gerton Lunter's Z80 emulator). The circuit diagram for the cable is included with the PC-Dragon - to view it start the emulator by typing `DRAGON DIAGRAM'. If you decide to construct the cable then you would be advised to also obtain `z80-302.zip' and utilise the test and calibration programs supplied with Z80. Once you have the cable connected and your cassette set up you can sample cassettes into PC files by typing `READVOC' and the name of the output file. The resultant VOC file may then be converted to the PC-Dragon virtual cassette format using Dragon Convert as described above. READVOC.COM and the DIAGRAM files are the work and copyright of Gerton Lunter. To obtain a command summary for ReadVoc start the program with no command line arguments. 3.6 How To Transfer Your ROM There are several ways to transfer your ROM for use with PC-Dragon. The method suggested here is to use the included Dragon Convert utility to transfer the ROM in the same way as cassettes. Alternatively you could transfer the ROM on disk, use a serial cable, or use the same ROM file as you use with the CoCo2 emulator. If you have access to the Internet then you may be able to download a copy of the ROM from an FTP or WWW site (at the time of writing there is a link to a site containing the ROMs at `http://public.logica.com/~burginp/emulators.html#roms'). The procedure for transfer via cassette and the Dragon Convert utility is as follows: 1) Boot up your Dragon 32, Dragon 64 or CoCo. 2) Ready your tape recorder for recording and commit the ROM to cassette by typing: CSAVEM "DRAGROM", &H8000, &HBFFF, 0 If you have a CoCo you may optionally use the name TANDYROM rather than DRAGROM. 3) Boot up your PC and SoundBlaster Pro wave form editor software. Sample the cassette recorded in step 2 into a file. Alternatively, use the parallel cable and the ReadVoc utility. A large output file should result. 4) Now use Dragon Convert to extract the cassette data. Type: DC DRAGROM Please don't expect the conversion to work on the first attempt. You are likely to need to adjust the command line switches until you find a combination which is suited to your hardware. If you still have no success then you may wish to try repeating step 3. Upon successful conversion the file DRAGROM.CAS will be created. 5) Now use Dragon Convert again to convert the cassette data to a cartridge file. Type: DC /D DRAGROM.CAS This should produce the file DRAGROM.DGN in the current directory. 6) If you have a Dragon 64 then you may optionally also wish to transfer the 64K version of the Dragon ROM. This will enable you to use the emulator in 64K BASIC mode. The procedure to transfer this second ROM is much as before. Boot up your Dragon 64 and switch to 64K mode by typing `EXEC 48000'. Now commit the second ROM to cassette by typing: CSAVEM "D64ROM2", &HC000, &HFEFF, 0 Transfer this file to your PC by using the procedure described before in steps 3 to 5. This time the result should be the file D64ROM2.DGN, which should be saved in your PC-Dragon directory or CARTRIGE sub directory. If you already have your ROM image(s) in DOS format then you can create the required DGN files from such raw images by using the included header file ROM_STUB.DGN. You might, for instance, wish to transfer the ROM from your Dragon to your PC on a floppy disk if you are a disk user. To do this use a program such as Compusense's PC Convert to transfer the ROM image as a BIN file. Raw images can be converted to DGN files using the MS-DOS `COPY' command. Type: COPY /B ROM_STUB.DGN + raw-image DRAGROM.DGN This method also works for D64ROM2.DGN, which may be either $3F00 bytes or the full $4000 bytes. Another alternative is to transfer the ROM using a `bit banger' serial link (for CoCo or Dragon 64 owners). This method is described in the documentation for CoCo2. If you have a ROM image suitable for use with the CoCo2 emulator then you can use that ROM file with PC-Dragon without modification. To do this just copy the file into your PC-Dragon directory or CARTRIGE sub directory. If you have copies of both the Dragon 32 and Dragon 64 ROMs then you should name your preferred ROM either DRAGROM or DRAGON, and the other ROM either D32ROM or D64ROM as appropriate. Please note that the ROM software is copyrighted by Microsoft and must not be distributed. 4 Epilogue 4.1 Standard Disclaimer This software is supplied `as is' with no guarantee of correctness or fitness for purpose either explicit or implied. The author hereby disclaims all responsibility for losses incurred through the use of this program and the advice given in this manual. By using the program you are deemed to have accepted these conditions of use. You may copy and distribute the freeware version of PC-Dragon freely so long as the software and documentation remain unchanged. No files may be added to or removed from the archives. There is no fee payable for using the freeware version of the software. If the emulator is obtained from a distribution service then no additional charge may be made for PC-Dragon. The registered version of PC-Dragon may not be distributed in part or whole. Special restrictions also apply to the PC-Dragon source code. Please read the README.TXT file included with the source code. 4.2 How To Contact The Author I welcome all comments and bug reports concerning PC-Dragon. Please contact me by e-mail at address burginp@logica.com. If this is impossible then please contact me by post at the following address: Paul Burgin 18 Moorcroft Road Sheffield S10 4GS England 4.3 How And Why You Should Register If you like PC-Dragon and use it regularly then please show your support by registering. The registration charge is only œ10, US $20 or 30DM, and all proceeds are donated to Oxfam. Your donation can therefore help to save lives and relieve suffering in less fortunate parts of the world. To register simply send your payment (UK cheque, international money order, or cash by registered post) together with your name and address to the postal address given above. In return you will receive a 3.5" disk containing the latest version of the emulator together with the complete C source code for the emulator (315K, suitable for Turbo/Borland C++). The registered version source code includes the file TITLE.C which is not supplied in the freeware version. A printed copy of this manual is not included in the package. The right to revise or withdraw the terms of this offer are reserved. Please check the document date and write first to confirm the price or terms in case of doubt. I am no longer supplying freeware versions of PC-Dragon by mail order so for these please contact NDUG or an Internet site/bulletin board which carries the updates. As an alternative to registration you are gratefully encouraged to donate an amount that you think appropriate for your usage of PC-Dragon directly to a humanitarian charity of your choice (no political or religious causes please). I say this because whilst sending donations to me directly will encourage the development of similar programs, the primary purpose of registrations is to raise money for charity rather than to `sell' the program. PC-Dragon is, after all, far from `crippleware' since even the source code is freely distributable. Whatever you decide, I thank you for using the program. 4.4 Other Dragon / CoCo Emulators CoCo2 is an excellent freeware Dragon and Tandy CoCo II emulator written by Jeff Vavasour. It emulates a different range of features to PC-Dragon and also executes programs much faster. If you do not already have it then look for `coco2-15.zip' at your favourite BBS or SimTel mirror site. A version of CoCo2 has been licensed by the author for non-profit distribution by the National Dragon Users Group. Jeff is also the author of several other emulators, including a CoCo III emulator which is available by registration only. T3 is a multi-tasking multi-session Dragon and Tandy CoCo II emulator that I'm currently developing. It is written in 80386 assembler, and therefore T3 will run only on 386, 486 and Pentium based PCs. It also requires a VGA compatible graphics adapter and MS-DOS v4.00. Again it emulates a different range of features to PC-Dragon. It's execution speed is a little faster than CoCo2. T3 is available from SimTel mirror sites (additionally, beta versions are occasionally available at `http://public.logica.com/~burginp/t3.html'). DREaM is a Dragon and Tandy CoCo II emulator written by which runs on any Amiga with 68020 processor or higher (an A1200 will give 100% speed). There are two versions, one with Copper support and one without. Features include sound and joystick emulation, plus support for virtual cassettes and snapshots. DREaM is available at `http://public.logica.com/~burginp/emulators.html#dream'. 4.5 The National Dragon Users Group The National Dragon Users Group is an active user group for users and enthusiasts of the Dragon and Tandy CoCo. It is based in the UK but has members from all over the world and new members are always welcome. If you're enthusiastic towards the Dragon or CoCo then why not keep in touch with other users and help to keep the group alive and by joining NDUG? As a member you could purchase the latest commercial, group and members programs, gain access to a panel of expert volunteers on the help line, and read all the latest news, views and reviews in the bi-monthly newsletter. Perhaps you would even like to write some newsletter articles yourself? A years membership is still only œ8 for the UK, which represents excellent value for money. Surf to `http://mudhole.ehche.ac.uk/~dragon/info.htm' for more details. NDUG is also the official distributor for the unregistered versions of PC-Dragon and T3. 4.6 Dragon E-Mail List The Dragon e-mail list now has a strong following and a stable address. To join the list send a message to dragon-list-request@grempc.demon.co.uk. There is also a mailing list for CoCo users. To be added to the list send the message `subscribe coco' to listserv@pucc.princeton.edu. 4.7 Acknowledgements I would like to thank Jeff Vavasour, Graham Kinns, Keiran Anscomb, David Linsley and everyone else who has provided information and feedback during the development of PC-Dragon. Special thanks also to Gerton Lunter for the ReadVoc utility and the circuit diagram for the parallel interface cable. The keyboard interrupt code is based on a freeware module written by Lee Hamel. 4.8 Legal Bits And Pieces Dragon, Dragon 32 and Dragon 64 were once trademarks of Dragon Data Ltd. Tandy and Tandy CoCo are trademarks of the Tandy Corporation. Acorn and Archimedes are trademarks of Acorn Computers. Microsoft, MS-DOS, MS-Windows and QBasic are trademarks of Microsoft Corp. IBM is a trademark of International Business Machines Ltd. SoundBlaster Pro is a trademark of Westpoint Creative Ltd. Compusense is a trademark of P.S.E. Computers. Amiga is a trademark of Commodore International. ReadVoc and the cable diagram are the work and copyright of Gerton Lunter. Similar trademarks apply in other countries. 5 Appendices 5.1 Appendix A: Table Of Emulator Services NUMBER | DESCRIPTION OF SERVICE --------+------------------------------------------------------------------- 0 | INSTALLATION/VERSION CHECK | Return: A = number of last service supported | X = $5043 signature | Y = PC-Dragon version (major, minor) --------+------------------------------------------------------------------- 1 | CLOSE DOS FILES --------+------------------------------------------------------------------- 2 | PC CURSOR CONTROL | Params: A b6-b0 = 0 off, 1 on (solid), >1 on (underline) | A b7 = 0 change, 1 do not change | Return: A = previous state --------+------------------------------------------------------------------- 3 | LOWER CASE CONTROL | Params: A b0 = 0 disable, 1 enable | A b1 = 0 do not refresh screen, 1 refresh screen | A b7 = 0 change, 1 do not change | Return: A = previous state --------+------------------------------------------------------------------- 4 | JOYSTICK EMULATION CONTROL | Params: A b6-b0 = 0 analogue, >0 digital | A b7 = 0 change, 1 do not change | Return: A = previous state --------+------------------------------------------------------------------- 5 | GET/SET TEXT MODE COLOURS | Params: A b0 = 0 do not refresh screen, 1 refresh screen | A b7 = 0 change, 1 do not change | X b15-b12 = new foreground colour in 'screen 0,0' | X b11-b8 = new background colour in 'screen 0,0' | X b7 -b4 = new foreground colour in 'screen 0,1' | X b3 -b0 = new background colour in 'screen 0,1' | Return: X = previous values; eg. BLK, GREEN, BLK, BROWN --------+------------------------------------------------------------------- 6 | GET/SET GRAPHICS MODE COLOURS | Params: A b0 = 0 'pmode 0' colour set, 1 'pmode 1' | A b1 = 0 'screen 1,0' colour set, 1 'screen 1,1' | A b2 = 0 do not refresh screen, 1 refresh screen | A b7 = 0 change, 1 do not change | U b15-b8 = EGA colour for all of Dragon '00' bit pairs | X b15-b8 = EGA colour for '0' of Dragon '01' bit pairs | X b7 -b0 = EGA colour for '1' of Dragon '01' bit pairs | Y b15-b8 = EGA colour for '1' of Dragon '10' bit pairs | Y b7 -b0 = EGA colour for '0' of Dragon '10' bit pairs | U b7 -b0 = EGA colour for all of Dragon '11' bit pairs | Return: U = previous values for 00 and 11; eg. GREEN, RED | X = previous values for 01; eg. YELLOW, YELLOW | Y = previous values for 10; eg. BLUE, BLUE --------+------------------------------------------------------------------- 7 | GET/SET GRAPHICS BORDER COLOURS | Params: A b0 = 0 do not refresh screen, 1 refresh screen | A b7 = 0 change, 1 do not change | X b15-b8 = EGA colour for border in 'screen 1,0' | X b7 -b0 = EGA colour for border in 'screen 1,1' | Return: X = previous values; eg. GREEN, WHITE --------+------------------------------------------------------------------- 8 | GET MOUSE POSITION AND BUTTON STATUS | Return: A b0 = 0 left button not pressed, 1 pressed | A b1 = 0 right button not pressed, 1 pressed | A b2 = 0 middle button not pressed, 1 pressed | X = mouse x position | (range 0 to 31 in text mode) | (range 0 to 255 in graphics mode) | Y = mouse y position | (range 0 to 15 in text mode) | (range 0 to 191 in graphics mode) | ERROR = 1 if no mouse driver found | NB: $FF00 is added to X or Y if pointer lies beyond screen edge. --------+------------------------------------------------------------------- 9 | EXIT TO DOS --------+------------------------------------------------------------------- 10 | MOUSE POINTER CONTROL | Params: A b6-b0 = 0 pointer off, >0 pointer on | A b7 = 0 change, 1 do not change | Return: A = previous state | ERROR = 1 if no mouse driver found | NB: Always turn mouse pointer off before changing video mode. --------+------------------------------------------------------------------- 11 | GET CASSETTE STATUS | Return: A = 0 failed, 1 ready, 2 reading, 3 writing --------+------------------------------------------------------------------- 12 | GET SAM INFORMATION | Return: A = map mode (0 or 1) | B = video resolution (0 to 15) | X = screen base address | Y = screen end address --------+------------------------------------------------------------------- 13 | GET PC DATE AND TIME | Return: B = mins | A = hours | X = day number | Y = month | U = year --------+------------------------------------------------------------------- 14 | ILLEGAL INSTRUCTION CONTROL | Params: A b6-b0 = 0 pause emulator, >0 ignore | A b7 = 0 change, 1 do not change | Return: A = previous state --------+------------------------------------------------------------------- 15 | FILENAME PROMPT CONTROL | Params: A b6-b0 = 0 do not prompt, >0 prompt | A b7 = 0 change, 1 do not change | Return: A = previous state --------+------------------------------------------------------------------- 16 | KEYBOARD TYPE CONTROL | Params: A b6-b0 = 0 'PC Mode', >0 'Real Mode' | A b7 = 0 change, 1 do not change | Return: A = previous state --------+------------------------------------------------------------------- 17 | PRINTER CONTROL | Params: A b6-b0 = 0 file, 1 LPT1, 2 LPT2, | 3 COM1, 4 COM2, >4 disable printer | A b7 = 0 change, 1 do not change | Return: A = previous state | ERROR = 1 if port not available --------+------------------------------------------------------------------- 18 | CRLF TRANSLATION CONTROL | Params: A b6-b0 = 0 off, >0 translate | A b7 = 0 change, 1 do not change | Return: A = previous state --------+------------------------------------------------------------------- 19 | PRINTER INTERACTION MODE CONTROL | Params: A b6-b0 = 0 basic, >0 advanced | A b7 = 0 change, 1 do not change | Return: A = previous state --------+------------------------------------------------------------------- 20 | SERIAL BAUD RATE CONTROL | Params: A b1-b0 = 0 1200bps, 1 2400bps, 2 4800bps, 3 9600bps | A b7 = 0 change, 1 do not change | Return: A = previous state --------+------------------------------------------------------------------- 21 | IRQ RATE CONTROL | Params: A b7 = 0 change, 1 do not change | X = clock cycles per IRQ | Return: X = previous value --------+------------------------------------------------------------------- 22 | ARTIFACTING CONTROL | Params: A b1-b0 = 0 off, 1 blue edge, 2 red edge | A b7 = 0 change, 1 do not change | Return: A = previous state --------+------------------------------------------------------------------- 23 | GET/SET GRAPHICS BORDER COLOURS V2.0 | Params: A b0 = 0 do not refresh screen, 1 refresh screen | A b7 = 0 change, 1 do not change | X b15-b8 = EGA colour for monochrome 'screen 1,0' | X b7 -b0 = EGA colour for monochrome 'screen 1,1' | Y b15-b8 = EGA colour for 4-colour 'screen 1,0' | Y b7 -b0 = EGA colour for 4-colour 'screen 1,1' | Return: X & Y = previous values --------+------------------------------------------------------------------- 24 | JOYSTICK DEVICE CONTROL | Params: A b6-b0 = 0 mouse, >0 PC joystick | A b7 = 0 change, 1 do not change | X = hardware sampling rate (range 0 to 255) | Return: A = previous state | X = previous sampling rate | ERROR = 1 if PC joystick not detected --------+------------------------------------------------------------------- 25 | GET FUNCTION KEY ASSIGNMENT | Params: A = key to read ('#', 1 to 10, or 'A' to 'Z') | X = address to write text string | Return: *X = function key string, null terminated | ERROR = 1 if key number not valid --------+------------------------------------------------------------------- 26 | SET FUNCTION KEY ASSIGNMENT | Params: A = key to change ('#', 1 to 10, or 'A' to 'Z') | X = address of source text string | Return: ERROR = 1 if key number not valid --------+------------------------------------------------------------------- 27 | GENERATE SOUND FROM PC SPEAKER | Params: X = frequency, or 0 for off | Y = length (in milliseconds), or 0 for infinite --------+------------------------------------------------------------------- b - bit number or bit range 5.2 Appendix B: Table Of Configurable Colours Text Colours Background Colours Graphics Colours Black 0 Black 0 Black 00 Green 2 Green 2 Green 02 Yellow E Brown* E Yellow 3E Blue 1 Blue 1 Blue 01 Red 4 Red 4 Red 04 Buff 7 Buff 7 Buff 07 Cyan 3 Cyan 3 Cyan 03 Magenta 5 Magenta 5 Magenta 3D Brown 6 Brown 6 Brown 06 Dark Grey 8 Black* 8 Dark Grey 38 Light Green A Green* A Light Green 3A Light Blue 9 Blue* 9 Light Blue 39 Light Red C Red* C Light Red 3C White F Buff* F White 3F Light Cyan B Cyan* B Light Cyan 3B Pink D Magenta* D Dark Pink 05 *with flashing foreground text 5.3 Appendix C: Default Function Strings Function Key Command Function Key Command ALT - F1 cload^m ALT - F6 line( ALT - F2 csave^m ALT - F7 pset( ALT - F3 cloadm^m ALT - F8 preset( ALT - F4 csavem"", ALT - F9 left$( ALT - F5 circle( ALT - F10 right$( Function Key Command Function Key Command ALT - A and ALT - N next ALT - B gosub ALT - O or ALT - C color ALT - P paint( ALT - D draw ALT - Q edit ALT - E else ALT - R run^m ALT - F for ALT - S step ALT - G goto ALT - T then ALT - H hex$( ALT - U return ALT - I input ALT - V val( ALT - J joystk( ALT - W screen ALT - K poke ALT - X exec ALT - L list^m ALT - Y inkey$ ALT - M pmode ALT - Z peek( 08/06/97