Content  

Introduction:

Ana Rosa is an emulator of the Amstrad PcW16 computer architecture. It is also capable of emulating additional hardware, different options and configurations, etc.

It does not emulate the classic PCW models, since they belongs to a different architecture; they have its own emulator.

The current version of the emulator is 0.1.1, to which this manual refers.

The objective is to achieve an emulation as faithful as possible to the original machine.

Features:

Requirements:

Legal stuff:

Installation and use:

Installation:

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.

On the other hand, the emulated machine does require an installation, since a complete image of the flash is not included by default.

Snapshots:

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.

Actions:

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.

Disks:

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.

Videos:

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.

Keyboard:

The emulator maps each PC key to the exact same key of the PcW16. When the input is not captured, the emulator keyboard shortcuts do not generate keystrokes, and vice versa: when there is capture, the keyboard shortcuts do not work.

To exit this capture, just press the Application key (between right Windows and right Control), or just remove the focus from the application (Windows key, etc.).

Joystick:

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 and converting the signal to digital in case of necessity.

Mouse:

The emulator is capable of emulating a PcW16 mouse. To be able to handle the pointer in the emulated PcW16 the input must be captured, which is done by clicking with the right button on the emulated screen. To release it, just press the Application key.

Mass storage:

The emulator is capable of emulating several mass storage devices Flash and ATA. In the first case, it will try to use a file called 1024.bin or 2048.bin according to the size of the flash in the emulator folder. If they do not exist, they will be created, and will require an installation.

In the second case, 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.

Interface:

While windowed, the following elements are available:

Title:

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.

Menus:

Bar:

Under the menus we have the bar, which is divided into three sections:

Screen:

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.

Hardware:

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:

Emulation:

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:

Advanced use:

Debugger:

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:

Registers:

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.

Disassembly:

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:

Breakpoints:

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:

Others:

Hardware registers:

Here the value of some hardware registers is shown; again, in red those that have changed.

Memory:

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:

P16 file format:

The PcW16 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 PcW16 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), a "Memory.bin" one (RAM dump) and a "Flash.bin" (Flash dump) one 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.

Macros:

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:

ShortLongDescription
8EXITWithout parameters. Closes the emulator.
9WAITKWithout parameters. Waits until the keyboard buffer is empty.
@EXECTake five parameters. The first one is the value of the Z80 register PC, the other four the memory configuration (ports $F0-$F3 of GA).
RRESETTake 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 *.
ADISKATake 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.
BDISKBSame as the previous case, but for unit B.
DDISKSimilar 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.
ESYNCWithout parameters. "Synchronizes" status (stops the emulator and sets it to normal speed). Obsolete.
TTYPETake a parameter. Adds the parameter as string of characters to the keyboard buffer. Supports character # as escape for characters, in hexadecimal two-digit format.
WWAITTake a parameter. Waits for the number of milliseconds determined by it. In case the emulation is stopped, it is started.
FFULLTake an optional parameter. This can be OFF or 0 for window mode, ON or 1 for full screen mode, none for toggle.
GSPEEDTake an optional parameter. OFF or 0 for normal mode, ON or 1 for fast mode, none to toggle.
OTURNTake an optional parameter. OFF or 0 to stop emulation, ON or 1 to start it, none for toggle.
XEXTERNALTake two parameters. Executes the external program indicated by the first with the parameters indicated in the second.
PPOKETake two parameters. Writes into the absolute memory address indicated by the first the value indicated by the second. Both are numbers in hexadecimal.
QDEBUGWithout parameters. Opens the debugger.
SSNAPLOADTake a parameter. Loads the snapshot file indicated by it.
USNAPSAVESame as previous case, but for saving.
YBINLOADTake two parameters. Loads into the absolute memory address indicated by the first the binary file indicated by the second.
ZBINSAVESame as previous case, but for saving.

Notes:

F.A.Q.:

Common mistakes:

More information:

Contact:

Thanks:


© 2011- HabiSoft.