Yape User Manual

YAPE (Yet Another Plus/4 Emulator) is copyright Attila Grósz, 2000-2003
Homepage: http://yape.plus4.net

Legal

YAPE is FREEWARE and as such comes without warranty of any kind, either expressed or implied, including, but not limited to the implied warranties of merchantability and fitness for a particular purpose. The entire risk as to the quality and performance of the program is with you. Should the program prove defective or harmful, you assume the cost of all necessary servicing, repair or correction. You may freely redistribute verbatim copies of YAPE as long as the original copyright and no warranty notices are present.

What is YAPE?

YAPE is a Commodore 264 family emulator. It's an 8-bit microcomputer family from the once-great-now-defunc Commodore Business Machines Ltd. They were released as a successor to the immensely popular Commodore 64 supposedly to either compete with the ZX Spectrum or other micros but eventually failed to gain market success and the whole line was dumped within a couple of years. However they were hugely popular in a few countries such as Hungary, Germany or Italy (to a certain extent also in the UK).

The program features an accurate cycle-exact approach and a high level of emulation. The user interface aims to exploit the potentials of the Windows operating environment. The emulator is written in C++ and is compiled with MS Visual C++. There's an older port to other platforms than Windows (using the SDL library). In the future there'll probably be other ports made.

YAPE was born out of a disassembler project during the summer of 2000 and had been for some time the only actively updated Commodore 264 family emulator. See the Changes.txt for development and release milestones.

Minimum system requirements

Since YAPE is a cycle-based emulator (much like the Commodore 64 emulators Hoxs or Frodo), its system requirements are higher than that of other line-, instruction- or event-based emulators. In return however, it makes development easier for me while providing maximum possible accuracy. For attaining 100% relative speed to the original hardware, you need:

PII 333 MHz or higher without sound and true drive emulation.
PII 500 MHz or higher for both sound and true drive emulation.
8 MB VGA card capable of DirectX 3.0
Sound card (DirectSound compatible)
Windows 9x, 2000/XP (and NT 4.0 without sound)

Features

The following 264 family members are emulated:

You can select the desired machine configuration from the 'Machine' submenu's Configuration option. The Commodore 364 prototype unit is not emulated as the interfacing between the machine and the speech hardware (Toshiba glue chip) is unknown.

The following hardware components are emulated:

Note, that the SID card and the 256 KB RAM are extensions to the original hardware and not to be found in stock machines.

The following are not emulated at the moment:
YAPE can interact with the Windows operating environment in the following ways:

Installing and running the emulator

Installation is simple: just copy all the files from the ZIP file into a separate folder on your hard disk. You start the emulator by simply double clicking on YAPE.EXE. If you have associated some emulator image formats withYAPE, you can also start it up by doubleclicking on the image. To set/amend the associations, simply select 'File associtioans' from the 'File' menu.

Once running the emulator, you can PAUSE it any time by pressing the Pause/Break key or selecting this option from the Machine menu. Once paused the emulator will not use up your PC's CPU resources.

While using the emulator, you can monitor some internals by pressing SHIFT+F9 or selecting the 'Quickdebugger' option from the Screen menu. The following information is displayed then:

You can toggle on/off the speedometer by pressing ALT+S or selecting the 'Display speed' option from the Screen menu. The default speed is 100% which means that the emulator is running 100% of the original machine's speed, and 50 FPS (frames per second) which is the PAL standard. You can select a lower or higher speed the top speed is limited only by your hardware (the processor and the graphics card both have an effect as well as your emulator settings). If you have a slow graphic card, you can select a lower framerate from the Screen menu but that may cause the screen to flicker. The fastest display mode is full-screen, but the graphical user interface is then mostly becomes unavailable from there.

If for some reason during tape loading for example) you want to boost the speed to the very limit you can select the 'Full throttle' option from the Machine menu (or alternatively press ALT+W). This will turn off sound, set the frame rate to 10 frames per second giving the emulated machine more CPU power.

Just like the real machine, you can reset the emulator, too. The switches are accessible from the 'Machine' submenu. The following reset variances are supported:

You can quit the emulator in several ways: ESC key quits with a confirmation dialog window, F12 and ALT+F4 quits immediately.

Loading and starting programs

Most Commodore plus/4 programs are distributed in either PRG (raw) or D64 (disk format). There are some other formats as it was noted above but they are much scarcer. The most convenient way of loading programs to YAPE is to choose 'Autostart image' from the File menu (or by pressing F7). You'll be presented a file dialog window where all supported images in the actual folder can be seen. If you select any of them, YAPE loads and tries to RUN it. If the program is in PRG/P00 format and has a SYS startup code, it'll fail. In that case you have to find out the start address yourself (probably from the file name or the documentation). Note, that the autostart feature will reset the emulated machine hence all previous RAM contents will be lost.

There are other ways of loading programs to the emulator, but these are dependent on the format, and won't be started automatically. Also the memory contents will not be lost:

For games, demos and programs, visit:
http://plus4.emucamp.com or
ftp://c64.rulez.org/pub/plus4 or
http://www.c16.de or
ftp://ftp.funet.fi/pub/cbm/plus4

On how to make TAP or WAV images from your original tapes that can then be loaded into the emulator, visit:
http://markus.brenner.de
http://minus4.plus4.net

Keyboard and joystick control

The emulated C= 264 keyboard is mapped to its original place wherever it was possible. Changing the default mapping is not (yet) possible. It can be annoying if you're not used to the plus/4 keyboard, but heck, this is a plus/4 emulator, isn't it? Here are the mappings of a couple of special keys:
plus/4 PC

ESCAPE: ` (tilde)
COMMODORE: right Ctrl
CTRL: left Ctrl
SHIFT LOCK: Caps Lock
RUN/STOP: Tab
HOME: Home
POUND: End
INS/DEL: BackSpace
CURSOR PAD: cursor keys
RESET: F11

These are the key mappings when the josytick is emulated through the PC keyboard.

JOYSTICK MOVE: cursor keys
JOYSTICK FIRE: numeric 0

Select 'Joystick emulation' from the 'Settings' submenu to plug the virtual joystick to the numeric keypad and the numeric 0 key. If you do not succeed try 'Swap joystick' (or press ALT+J), this will switch between joystick port 1 and 2. Tick the 'Use PC joystick' option if you own a PC jopystick and want to use that for joystick emulation.

Disk drive support

Currently two kinds of drives are supported: the 1541C and the 1551. In the future there might be more exotic drives supported, but the available software for them is very limited so the priority is low.

1541C drive emulation (CPU)

The 1541 is a well-known device also compatible with other Commodore products, like the popular C64. This mode sports a full-blown 1541 emulation together with a 1 MHz 6502 CPU, the 2 VIA-6522 chips and the floppy disk controller, disk rotation etc. Custom loaders are therefore also supported. The D64 files are first converted to GCR format and buffered by the emulator internally for reading. Writing is not yet supported just as programs that depend on the very exact disk rotation.

You can debug the drive from the external monitor (see chapter 'The external monitor' later).

1551 drive emulation (IEC and CPU)

The 1551 is a high-speed parallel drive specifically made for the 264-series. It has a proprietary interface called TCBM that has not been used in any other Commodore products. The 1551 emulation has two modes: IEC and CPU. The first one is not real disk drive emulation. Disk commands are caught on the parallel bus and intepreted by the emulator itself, so actually the behaviour of the DOS is simulated. Advantage is that it has virtually no overhead compared to a true drive emulation, disadvantage is that custom disk loaders will not work with it. The 1551/CPU mode aims to emulate a full 1551 drive together with the 2 TIA chips, 2 MHz 6510T processor, 555 astable multivibrator for IRQ and the disk drive mechanics (that is actually the same as that of the 1541). As a consequence, it's the slowest drive emulation mode, while in turn all possible custom loaders should work fine (in due time).

1551/IEC is currently the only mode with support for device numbers other than 8 (namely 9). Also the only mode where floppy write operations and T64 images are supported. However, almost all DOS commands are supported, except for B-E (block-execute) and M-E (memory-execute).

Note: the option 'Set drive folder' only affects the 1551/IEC emulation when no D64 files are attached (on startup or after a 'Detach D64' is selected from the File menu). It sets the current folder for the 1551 and it will be used for disk save and write operations. The possibilities are limited when using a folder as a drive, as it may not have blocks for example.

Tape device support

There's read/write support for low level raw tape images commonly known as the MTAP format. Loading a TAP image's content is simple: you can do it via the 'Autostart image' option or thru the Tape menu by selecting 'Attach TAP'. If you choose for the latter, you have to make sire that you type the appropriate BASIC commands for tape loading: LOAD"",1,1 . Then press F5 to start the tape. If you have the Quickdebugger selected from the Screen menu you can see as the the emulator advances in the file.

Creating TAPs is  a bit more complicated. Firstly: you can only create new TAP files, can not append to existing ones or overwrite them. To create an empty TAP image, select 'Create TAP' from the Tape menu. You can select between wholewave and halfwave format by ticking/unticking this option in the file dialog window. The wholewave format is about half the size of the halfwave one, but is less compatible with all the turbos. As the 264 family's tape interface is edge-triggered, rather than level-triggered, there are more possible waveforms than on the Commodore 64 for example. You must not attach the newly created TAP again! When you typed SAVE from the emulated machine you can press the RECORD button by selecting it from the Tape menu or pressing SHIFT+F6. When finished saveing make sure you detach the TAP you've just written and reattach it before trying to load as the 'Detach' option puts some very important information into the TAP header which you miss you may be unable to use your TAP elsewhere.

Alternatively you can load 8-bit digitised WAV or RAW samples to the emulator. It is however not encouraged as is having a lower sample frequency than the MTAP while taking up to about 8 times more disk space. The advatage is that you can create working WAV/RAW samples without any special hardware if you're lucky enough.

The external monitor

YAPE has a simple external monitor which you can use to track the internals of the emulated machine. You can enter the monitor by pressing ALT+M or selecting 'Monitor' from the Machine menu. The monitor is console-like that is you have to type in commands and press ENTER. Limited editing functioanlity within the command line is also supported (cursor left/right, BACKSPACE etc.). You can also enter the monitor explicitely either by reaching a breakpoint (set from the monitor) or a crash instruction (in the latter case you are prompted with a confirmation dialog window first).
The monitor features:

You can get a simple help on these commands from the monitor itself by typing '?'. To exit the monitor type 'X' or simply click the upper left corner of the monitor window.

Development using YAPE

If you don't own the original hardware or it is not functional anymore, you may consider developing under the emulator with an approppriate cross-development tool. Programming information on the 264-family hardware can be found:

Cross development tools that can be used with YAPE directly:

Credits

A number of people helped me during development either by providing hardware information, testing or user hints. Thanks to:

The following information sources were used:

And of course special thanks to all the users and the plus/4 sceners who helped and encouraged me during all the years! Kudos for all those nasty demos that failed or still fail to run properly! Keep up the good work, and keep the scene alive! Cheers!

Miscellaneous

If you like YAPE you may wish to check out my other emulator project, called 'Ultimo'. It emulates a Hungarian 8-bit microcomputer called Primo, manufactured between 1984 and 1986. Find it at: http://primo.homeserver.hu (in Hungarian only).