BeebEm for the Apple Mac ======================== BeebEm is a BBC Micro and Master 128 emulator. It enables you to run BBC Micro software on your Apple Mac. The software is a port of the Microsoft Windows version of BeebEm, currently being developed by Mike Wyatt. The program is still work in progress and is not complete yet so some options available in the Windows version are not yet in the Mac version. These will be added in due course. This document will only describe the differences between the Mac version and the Windows version. Please see the README.TXT file for further instructions in the use of the BeebEm emulator. Installation ------------ As you are reading this, you have probably already installed the software onto your computer. If not, just unzip the archive file to a suitable directory. To run the program, double click the BeebEm3 application icon. This will launch the program and (hopefully !) display a Master 128 window in the middle of your screen. The program has a menu bar where you can configure the program options. If you change a menu option, remember to use Save Preferences off the Options menu to store the program settings to disc. See the README.TXT file for further information on the menu options. Disc Images ----------- There are some sample disc images in the diskimg folder. The images with an 'ssd' extension are DFS images. The four scsi?.dat files are ADFS hard disc images. There are also some demo tunes in scsi0.dat which you can listen to with the PLAY program. COLDTEA is a favourite of mine. The sasi0.dat file is a Torch Z80 hard disc image. Tape Images ----------- There is a sample tape image in the Tapes folder. You load tape images from the File -> Load Tape menu option. If you then *TAPE, you can *. or CH."" as normal to catalog tapes or load programs. Further tape options are on the Comms Menu. The Tape Control option opens a dialog box showing the blocks of data on the tape. You can click on a block to re-position the tape, ie fast-forward or rewind the virtual tape. You can also create a new tape by selecting the Record button off the Tape Control dialog. You can download disc and tape images off the internet from such sites as : http://www.stairwaytohell.com http://bbc.nvg.org Keyboard Mapping ---------------- The keyboard is mapped as per the Windows version with the exception of : Beeb Mac Caps Left Alt f0 F10, F11 Break F12, F13 If you are using OS 10.4.X, you should find that the default hot key actions for F9-F12 are disabled when BeebEm has focus. If not, ensure you have "Enable access for assistive devices" ticked in the Universal Access preferences. To get F9 to F12 to be recognised in OS 10.2.x or 10.3.x, you will have to temporarily disable these default hot keys by going into System Preferences, Keyboard & Mouse, Keyboard Shortcuts and unselect any shortcut using these keys. Torch-Z80 Co Processor Support ------------------------------ The software now fully supports the Torch-Z80 co-processor board. If you do not know what this is, you can safely ignore this next section :) The Torch-Z80 board was an add-on card to the BBC computers which allowed you to run CPN (a clone of CP/M) software. It was Z80 based, came with 64K of RAM and connected to the BBC via the Tube interface. It had no hardware I/O of it's own but used the display, keyboard, disc drives etc of the host processor. Although it used the host disc drives, the disc formats were different to DFS or ADFS. It still used 80 track, double sided discs (400K) but these discs cannot be read on the BBC without special disc converting software. If you wish to create your own disc images of original Torch Z80 software, I use XFER 5.1 (http://www.g7jjf.com). The emulator comes as default with Torch-Z80 support disabled (to prevent confusion for new users). To configure support, you need to load a sideways ROM image for the Host Tube support. A configuration file has already been created for this so the simplest thing to do is replace the Roms.cfg file with the Roms_Torch.cfg file (backing up Roms.cfg first of course !) This file simply loads the required MCP122.ABM ROM into ROM Slot 0. With this new configuration, running the emulator will default to a blue Mode 0 screen. You need to the select Torch Z80 Second Processor off the Hardware menu (the emulator will reboot) and type *MCP to enter CPN. If you try and run *MCP without enabling the Torch Z80 Second Processor off the Hardware menu, you will get a 'No Z80!' error message on screen. By default, the system will try and autoboot off Drive C and if you don't have a suitable disc image mounted, it will bring back an error. To prevent this, when typing *MCP, hold down the Alt key (Caps Lock) and this will prevent CPN from autobooting. I cannot give you a full overview of CPN but typing HELP is a good start as well as exploring the disc images found at : http://www.g7jjf.com/disc_images.htm The original Torch Standard Utilities Ver 2.0 disc is included on drive C and the Torch Hard Disc Utilities Ver 4.0 are on Drive D and both contain several useful programs to get you going. The Torch Z80 fully supports Econet emulation which provides TORCHNET facilities for sharing drives amongst multiple computers or instances of BeebEm. If you have any specific questions about the Torch-Z80 support, please drop me an e-mail and I will try to answer any queries you might have. Master 512 Co Processor Support ------------------------------- The software now supports the Master 512 Co-Processor board. The Master 512 board was an add-on card to the BBC computers which allowed you to run DOS Plus (based on CP/M but largely MS-DOS compatible) software. It was 80186 based, ran at 10 MHz came with 512K of RAM (or 1MB with third party upgrades) and connected to the BBC via the Tube interface. You start the Master 512 by selecting 80186 Second Processor off the hardware menu. This will boot off a 10MB hard disc image (ADFS Drive 0) which comes pre-installed with the original DOS Plus system and the GEM application software. The emulator will also recognise Drive A and B if a suitable DOS Plus formatted disc is loaded. The emulator should recognise various disc formats (look at the DISK program for more info) but I would only recommend using 640K ADFS .adl format and 800K DOS Plus .img format discs. GEM can be started by typing 'GEM' from the command prompt. GEM uses the AMX mouse support which much be enabled for the mouse to work. I would recommend you start GEM first then enable AMX Mouse support afterwards. Please note that mouse support works but due to the acceleration factors built into the GEM driver, mouse movement can be a bit erratic. I hope to improve this in future versions of the emulator. The Master 512 should run most MS-DOS 2.1 compatible software but no guarantees are given for what will and what won't work. I will start a library of known good disc images at : http://www.g7jjf.com/512_disc_images.htm Please feel free to send me any more you know work with the Master 512. Acorn Z80 Co Processor Support ------------------------------ The software now supports the Acorn Z80 Co-Processor board. The Acorn Z80 was a CP/M based system running with 64KB RAM on a Z80 processor. You start the Acorn Z80 by selecting Acorn Z80 Co-Processor off the hardware menu. If you load a CP/M system disc in drive 0, the system will then boot to an A: prompt. I have included a CP/M Utilities disc in the installation which will boot the system. The Acorn Z80 originally came with 7 discs which can be download from my web site at : http://www.g7jjf.com/acornz80_disc_images.htm These discs contain the Acorn Z80 application software including : CPM Utilities BBC Basic Mallard Basic CIS Cobol MemoPlan GraphPlan FilePlan Accountant Nucleus You will also find some manuals for this software on my site as well. The Acorn Z80 should also run most CP/M compatible software but no guarantees are given for what will and what won't work. I will start a library of known good disc images at : http://www.g7jjf.com/acornz80_disc_images.htm Please feel free to send me any more you know work with the Acorn Z80. Acorn ARM Second Processor Support ---------------------------------- The software now supports the Acorn ARM Second Processor board, also known as the ARM Evaluation System. The ARM interpreter and disassembler code is based on software written by David Sharp to whom I am grateful for allowing me to use it with BeebEm. The Acorn ARM Second Processor was an 8MHz system running with 4MB RAM on an ARM 1 RISC processor. You start the Acorn ARM by selecting ARM Second Processor off the hardware menu. The ARM Second Processor has no operating system but relies on a sideways ROM to provide a command line prompt to the user. Once you see the A* prompt, type *HELP SUPERVISOR to see what inbuilt commands are available. The ARM Evaluation System came with 6 discs full of software. I have included disc 3 in the installation which contains ARM Basic. Load the armdisc3.adl disc image (ensuring you are in ADFS mode), type *MOUNT 4 and *AB to load ARM Basic. The remaining disc images plus a hard disc image containing all 6 disc images can be downloaded from my web site at : http://www.g7jjf.com/acornArm_disc_images.htm These discs contain the Acorn ARM application software including : TWIN - Editor ARM Assembler/Linker/Debugger ARM Basic Lisp Prolog Fortran 77 General File Utilities You will also find some manuals for the ARM Second Processor on my site as well but if you have any manuals or other disc images I don't have, please feel free to send me copies to add to the library. Teletext Support ---------------- The software now supports the Acorn Teletext Adapter. Unfortunately, I haven't got my teletext server software finished yet so the emulation can only work from teletext data captured to disc files. You can download some sample teletext data from : http://www.g7jjf.com/teletext.htm Speech Generator ---------------- The BBC B and B+ had the facility for installing a TMS5220 Speech Generator chip and associated TMS6100 PHROM containing the digitised voice of the BBC newsreader Kenneth Kendall. With these two chips installed, you could easily make the computer speak using the BASIC SOUND command. BeebEm now supports the TMS5220 and upto 16 different PHROM's. A new configuration file has been created to specify which PHROM's are available. The configuration file is phroms.cfg and contains a list of 16 PHROM filenames or EMPTY if a PHROM is not available. Two PHROM's are currently included with the emulator and are stored in the Phroms directory. They are PHROMA which was the original Kenneth Kendall voice and PHROMUS which is an American voice speaking a different dictionary. To say a word, you use the SOUND command, eg : SOUND -1, 179, 0, 0 would speak COMPUTER using PHROMA. The -1 specifies the PHROM number to use, from -1 to -16 which corresponds to each entry in the phroms.cfg file. A list of words available in PHROMSUS is included in the Phroms directory for reference. A list for PHROMA can be found in Appendix A and B of the manual detailed below. The Torch Z80 Co Processor also supports the speech system. Try the SNAKE game off the system utilities disc. There is also BACKCHAT. Please remember that the Master 128 doesn't support speech so you need to be in Model B/B+ mode for speech to work. For more information on using the Speech System you are referred to the Acorn Speech System User Guide which you can download from : http://www.g7jjf.com/docs/acorn_speech_user_guide.pdf (1202KB) If anyone has any more PHROM images, can they please email them to me so I can include them with the distribution. Source Code ----------- The full source code for the program is in the src sub-directory. You will need the XCode 3.0 development tools to be able to modify and re-compile the program. Performance ----------- In the default configuration and a 640x512 screen, the program runs at approx 38fps on my Mac Mini 1.4GHz. Running full screen (ie, click green + button or cmd-Z) the speed drops to about 20 fps but is still fully playable with no sound break up. Missing Functions ----------------- The following functions have yet to be ported across : Some items off Comms menu Some items off Options menu I can live without these functions but if you have a preference for items you think ought to go back in, please let me know. Known Problems -------------- There are currently no known problems with the emulator. If you do find any problems, please let me know. This is my first attempt at writing Mac software and I've yet to fully come to terms with the hugh library of Carbon API's. If you have any suggestions for doing things a better way, please get in touch. I am especially interested in how I can improve the frame rate of the program. The CopyBits function seems awfully slow :) Version History --------------- 3.3a - 09/02/08 Added disc LED lights in 8271 mode (code by Richard Drysdall) Added 1770 controller options in Model B mode Added support for Watford Double Density 720K disc images (use file extension .wdd to recognise disc image) 3.3 - 01/01/08 Added remote client/server ethernet option for serial port emulation(so you could write software to telnet to a remote network, write a simple web browser or ftp client etc, running on the Beeb)Added print screen functionAdded copy screen to clipboard functionAdded three new higher resolution screen modes (code by Richard Drysdall)Added freeze when minimised optionAdded load/save user keyboard layouts (code by Richard Drysdall) Added protect on load disc option Bug fix - Missing scan line at top of screenBug fix - Missing scan lines at bottom of screenBug fix - Non-default window size not set on startupBug fix - Random crash when changing from mode 7 to any other screen modeBug fix - Cursor position wrong when in column 1 in editing modeSlight tweak to source code to get it to compile using Xcode 3 on LeopardSlight change to sound routine to remove some artefacts 3.2a - 15/09/07 Added clipboard as destination for printerAdded cmd-C to copy BASIC program to clipboardAdded cmd-V to paste BASIC program from clipboard(alternatives to using *SPOOL/*EXEC with disc files)Corrected emulation of PLY processor instructionAdded new program and disc icons Set root directory to $ for new ADFS images Fixed keyboard interrupt handling routine Fixed disc write protect menu update after ejecting a disc Increased default Econet flag fill timeout to 250000 3.2 - 14/05/07 Added ARM Second Processor support 3.1 - 01/01/07 Added serial port supportAdded preliminary 300 baud support for CSW, Swarm now loadsAdded hard disc activity LED'sAdded CSW support to Tape Control windowAdded support for Level 3 Econet User Port RTC ModuleAdded support for mixed mode ADFS/NETFS format discs 3.0x - 19/11/06 Added preliminary 300 baud support for CSW, Swarm now loadsAdded hard disc activity LED'sAdded CSW support to Tape Control windowAdded support for Level 3 Econet User Port RTC ModuleAdded support for mixed mode ADFS/NETFS format discs 3.0w - 07/10/06 Added cmd-P screen dump command (To create bmp pictures for BBC Games List program) 3.0v - 04/10/06 Fixed problem of saving to ADFS hard disc under 65C02 emulation Altered launching of BeebEm by clicking on image file to autorun disc (for compatibility with new BBC Games List database frontend program) 3.0u - 13/09/06 Added preliminary support for loading CSW format tape imagesAdded emulation of Microvitec touch screenAdded user port breakout box Fixed joystick emulation in Master 128 mode Fixed problem of ESC key not always being detectedFixed problem of accessing files when ADFS and DFS discs loaded side by sideFixed a couple of tape related game loading problems Fixed interrupt clearing issue in 8271 disk emulation Minor VIA timing tweak to make Snapper work again 3.0t - 20/08/06 Rebuilt application as universal binary Added UDP broadcast support for TeleText server software Added changes done by Mike Wyatt to BeebEm Ver 3.3, namely : Added menu options to enable/disable Teletext adapter and hard drive emulation. Removed ADFS and ATS ROMs from Model-B configuration as they were causing a few problems. Improved VIA and interrupt timing and fixed instruction cycle count for branches. The following programs now run: Nightshade (tape), Lancelot, The Empire Strikes Back, Dabs Fingerprint, Yie Ar Kung-Foo (tape) Added "Eject Disc" options to the file menu. The name of the currently loaded image file is shown next to the menu option. Change sound volume to be exponential (suggested by Rich Talbot-Watkins). Seems to be a definite improvement on the linear scale. There is a menu option to switch between the two. 3.0s - 01/04/06 (my 40th birthday if anyone is interested !) Added support for Acorn Z80 Co-Processor 3.0r - 26/03/06 Added support for Master 512 Co-Processor Added support for Acorn Teletext Adapter 3.0q - 30/12/05 Added SCSI ADFS Hard Disc support Added SASI Torch Z80 Hard Disc support Added Econet support (see README.TXT for more information) (Therefore TORCHNET works using the Torch Z80 Co-Processor) Removed IDE support as no longer needed 3.0p - 24/12/05 Added emulation of TMS5220/TMC6100 Speech Generator 3.0o - 20/12/05 Added 6502/Z80 Debugger You may need to drop the frame rate when running the debugger as it does slow down the emulation speed, eg View -> 25 FPS. See the README.TXT file for further information on the debugger. 3.0n - 16/12/05 Added Motion Blur option Added tape relay sounds Fixed problem with case-sensitive filing systems Fixed tape control window not scrolling properly Fixed tape control window showing extra block data 3.0m - 22/11/05 Added Full Screen display mode (toggle with cmd-Z) Merged in BeebEm for Windows bug fixes, namely : Improved VIA timing emulation and fixed some instruction cycle counts Fixed bug in horizontal displayed register emulation Fixed bug in virtical sync position register emulation Fixed bug in virtical displayed/total register emulation for mode 7 3.0l - 01/11/05 Added Skip Frame and Frame Size options to video capture 3.0k - 28/10/05 Added QuickTime recording of running program 3.0j - 25/09/05 Added user defined keyboard mapping 3.0i - 23/09/05 Added key mapping for '@' character (forgot to put it in !) Added support for tape images 3.0h - 21/08/05 Added support for 16 bit colour displays 3.0g - 17/08/05 Fixed problem of emulator sometimes dropping to 0 fps Fixed problem of red close button forcing emulator full screen 3.0f - 07/08/05 Added support for the Torch Z80 co-processor card Changed compiler to use GCC 3.3 so works on 10.3.7 without missing library errors Fix to remove _kCGColorSpaceGenericRGB error on pre 10.4.x OS's 3.0e - 16/07/05 Increased screen refresh rate by using custom CopyBits procedure Added support for launching BeebEm by selecting disc image from Finder Added support for disabling F9-F12 hot keys on Tiger OS Changed compiler options to use weak linking so the program should load under OS 10.2.x and 10.3.x Added program icons 3.0d - 14/07/05 Added support for analogue mouse stick Added support for digital mouse stick Added support for AMX mouse 3.0c - 12/07/05 Added support for F9-F12 Remapped Break key to F12 Remapped F0 key to F10 Added Map A,S to CAPS,CTRL option 3.0b - 11/07/05 Added Save Preferences menu option (stored in beebem.ini) Added New Disc 0/1 menu options Added Load/Save State Added Quick Load/Save State Added Printer options 3.0a - 04/07/05 Initial Release Jon Welch jon@g7jjf.com http://www.g7jjf.com 9th February 2008