CP/M Box is an emulator of the Amstrad PCW computer architecture, that is: 8256, 8512, 9512, 9256, 9512+ and PcW10. It is also capable of emulating additional hardware, different options and configurations, etc.
It does not emulate the PcW16, since it belongs to a different architecture; it has its own emulator.
The current version of the emulator is 1.9.2, to which this manual refers.
The objective is to achieve an emulation as faithful as possible to the original machine.
This emulator does not need any kind of installation, simply unzip the contents of the ZIP file in a folder and proceed to execute it.
Additionally, this program supports the automation of commands through the command line, using the same syntax as the macros, which are explained in its corresponding section. It can be used to associate file extensions, using it with external launchers, etc.
A snapshot file is a complete state of the machine (including memory, hardware status, disk content, etc.) along with metadata about the emulated machine.
When dragging a file on the window it would be loaded without further ado. If during the release on the window the shift key was pressed, the emulation would be activated if it were deactivated.
An actions file is a snapshot together with additional data that describe the events that happened after that moment. It is useful to save tutorials or games in a more compact way than a video.
When dragging a file on the window it would be loaded without further ado. If during the release on the window the shift key was pressed, the emulation would be activated if it were deactivated.
A disk file contains the user data of a physical diskette, along with some of its geometric information.
The emulator is capable of loading both CPCEmu DSK files (normal and extended, with or without protection) and raw images with IMG extension.
The emulator works with disk images in memory, with the option to dump them back when extracted. You also have the option to insert them write protected.
When dragging a file on the window it would be inserted on the unit A. If during the release on the window the control key was pressed, it would be inserted in the unit B; if the shift key was pressed, the emulator would be reset and the emulation would be activated if it were disabled (interesting option for boot disks).
Additionally, the emulator allows to accelerate emulation during disk loads.
This emulator allows video recording, recording exactly what is shown on the emulated screen together with the sound.
This option requires Windows 7 or latter, and a computer capable of video realtime compression.
The emulator maps each one of the PCW keys to the one closest to the keyboard of the PC. They can be changed by the user in the emulation options, as well as consult their assignment.
Also, the cursors of the PC along with the numeric * and / can emulate a joystick in case of not having one connected to the PC.
The emulator recognizes any joystick / pad that Windows recognizes, by directly mapping the X, Y axis and the first two buttons to the emulated joystick (Cascade, Kempston, Spectravideo, DK'tronics, Electric Studio), and converting the signal to digital in case of necessity.
If the keypad option is enabled, the joystick will additionally emulate the arrows on the PCW numeric keypad with the axes, and the space and tab with the buttons.
The emulator is capable of emulating a PCW mouse (AMX, Kempston, KeyMouse, Electric Studio). To be able to handle the pointer in the emulated PCW the pointer must be captured, which is done by clicking with the right button on the emulated screen. To release it, just press the escape key.
The emulator is capable of emulating a PCW stylus (Trojan, Electric Studio) using the mouse. The instructions are the same as in the previous case.
Additionally there is an option to show a special cursor on the screen to see its current position.
The emulator is capable of emulating several mass storage devices (Gem, Flash Disk, uIde). You can use both raw images and HDF files that include geometric information of the disk.
Given the size of these files, its information is not stored in the snapshots, but a link to the file that contains it.
Additionally, the emulator allows you to map a directory over the virtual M drive under CP/M.
While windowed, the following elements are available:
At the top of the window, like in any other application, there is the title bar.
It has the title of the application and also the file name of the floppy inserted at the A drive.
Finally, it also has the typical icons for minimize, maximize and close the window, with the usual behaviour with one exception: maximize icon activates the full screen mode, which can be canceled pressing Escape.
Under the menus we have the bar, which is divided into three sections:
This section represents the emulated computer screen, with its selected visual options.
It allows drag and drop of snapshot, actions and discs files over it.
In this window you can choose the hardware options to emulate. The acceptance of them will cause a reset of the emulation. The options are divided into several tabs:
In this window you can choose the options of the emulator. The acceptance of them will not cause a reset. The options are divided into several tabs:
The debugger is a floating, resizeable window, and always on top of the emulator. As long as it is open, the emulator works in debugging mode.
When executing code, it acquires some transparency to indicate unavailability and to be able to see what it is underneath. Execution can always be stopped with the Escape key.
When not executing code, the current video position will be marked on the PCW screen with two red lines.
The window consists of several sections:
This section shows the value of the different Z80 registers, in red if they were modified since the last operation. Their value can be modified directly.
Furthermore you can see the status of the different flags. Double clicking on them changes their value.
Finally, if you are using decimal mode, the values of the registers show their high and low parts separated if the mouse is hovered over it.
This section represents a memory disassembly, by default from the PC register.
Rows with font in red indicate they have a breakpoint; the one for current PC value has also a bisque background. Double-clicking on a row fills in the data to set a breakpoint in that address.
Below are the following buttons:
This section allows you to define breakpoints. Each one has the following properties:
The buttons down below are for add, remove and edit a breakpoint. A double click over an existing one also edits it, and they can also be dragged to reorder the list.
The expression determines which addresses should cause breakpoint. Its syntax is:
Notes on semantics:
Examples:
Here the value of some hardware registers is shown; again, in red those that have changed.
This window represents a memory dump. The value of each position can be changed by writing a new value on its cell.
Below are the following buttons and options:
Furthermore, while in debugging mode, certain special Z80 instructions are supported:
The PCW snapshot format was born from the need to represent everything necessary for emulation (including tapes and discs) in a single file and at the same time to be easily manipulated by the advanced user.
Thus each PCW file is nothing more than a ZIP file, which contains other files inside. In this way it can be manipulated with any compressor application.
There are two types of files inside of it: text (INI, readable and editable with any text editor) and data dumps (other extensions, usually BIN).
There are always a "Config.ini" file (hardware configuration of the emulator), a "Hardware.ini" one (state of said hardware) and "RAM.bin" one (memory dump) present.
Each line in the text files is like "A=B", meaning propery A has value B. Inside "Hardware.ini", the Z80 registers are the "Z80_xxx" properties.
Action files are the same as a snapshot, with an extra file with the port and keyboard data values that must be read.
The emulator has a small macro interpreter, which consists in the execution of one or more actions of the emulator.
These can be launched from the command line or stored in the macros folder of the emulator.
In the case of being stored in the folder, these consist of two files with the same name and TXT and PNG extensions respectively. When starting the emulator these are listed and added in the form of buttons to the emulator, into their section of the bar, and can be invoked by pressing said button.
The language of macros is composed of tokens (commands or parameters of commands) separated by blanks (spaces, tabs, carriage returns). In the case that a parameter contains spaces, it can be surrounded with quotes to avoid being fragmented in tokens.
The language is very simple: a succession of separate commands, each one followed by its parameters equally separated. Each command has a short form (one character, less writing) and a long form (one word, more intuitive), both of which can be used interchangeably.
The commands are not case-sensitive. In short form the commands can optionally be preceded by - or /, for compatibility.
The execution of these commands is asynchronous to the emulation if it is active, unless otherwise indicated.
The commands are:
Short | Long | Description |
---|---|---|
8 | EXIT | Without parameters. Closes the emulator. |
9 | WAITK | Without parameters. Waits until the keyboard buffer is empty. |
@ | EXEC | Take five parameters. The first one is the value of the Z80 register PC, the other four the memory configuration (ports $F0-$F3 of GA). |
R | RESET | Take an optional parameter. Reset the emulator, and if there is a parameter, it specify a file with the hardware definition to apply, or makes a hard reset if its *. |
M | MAP | Take a parameter. Maps the emulated M unit, the parameter specifies the folder to map or . to deactivate it. |
A | DISKA | Take a parameter. If the value is . then remove the disk from drive A, otherwise it inserts the disk image file specified in the parameter. Obsolete. |
B | DISKB | Same as the previous case, but for unit B. |
D | DISK | Similar to the previous two cases, but it takes two parameters. The first is the unit (A or B), the second the specified file or if it is . extracts the current one. |
E | SYNC | Without parameters. "Synchronizes" status (stops the emulator and sets it to normal speed). Obsolete. |
T | TYPE | Take a parameter. Adds the parameter as string of characters to the keyboard buffer. Supports character # as escape for characters, in hexadecimal two-digit format. |
W | WAIT | Take a parameter. Waits for the number of milliseconds determined by it. In case the emulation is stopped, it is started. |
F | FULL | Take an optional parameter. This can be OFF or 0 for window mode, ON or 1 for full screen mode, none for toggle. |
G | SPEED | Take an optional parameter. OFF or 0 for normal mode, ON or 1 for fast mode, none to toggle. |
O | TURN | Take an optional parameter. OFF or 0 to stop emulation, ON or 1 to start it, none for toggle. |
X | EXTERNAL | Take two parameters. Executes the external program indicated by the first with the parameters indicated in the second. |
P | POKE | Take two parameters. Writes into the absolute memory address indicated by the first the value indicated by the second. Both are numbers in hexadecimal. |
Q | DEBUG | Without parameters. Opens the debugger. |
S | SNAPLOAD | Take a parameter. Loads the snapshot file indicated by it. |
U | SNAPSAVE | Same as previous case, but for saving. |
Y | BINLOAD | Take two parameters. Loads into the absolute memory address indicated by the first the binary file indicated by the second. |
Z | BINSAVE | Same as previous case, but for saving. |
Common mistakes:
Contact:
Thanks: