plus4emu 1.1.1
==============

plus4emu is an open source, portable emulator of the Commodore Plus/4
computer, written in C++, and supporting Windows and POSIX platforms
(32 bit Windows, 32 and 64 bit Linux, and MacOS X have been tested).
It implements accurate, high quality hardware emulation, however, the
system requirements are higher than that of most other emulators.

Features
========

General
-------

  * graphical user interface using the FLTK library
  * software (FLTK based) or OpenGL video, with resizable emulator
    window, fullscreen mode, brightness/contrast/gamma can be set
    globally or separately for red/green/blue channels, color
    saturation control; additional features in OpenGL mode only: single
    or double buffered (with synchronization to vertical refresh) mode,
    linear texture filtering, and some display effects
  * real time audio output uses the PortAudio library (v18 or v19), with
    support for many native audio APIs (MME/DirectSound/ASIO on Windows,
    OSS/ALSA/JACK on Linux, and CoreAudio on MacOS X); high quality
    sample rate conversion with low aliasing; volume control, two first
    order highpass filters with configurable cutoff frequency, and an
    optional parametric equalizer can be applied to the audio signal
  * recording sound output to a WAV format sound file
  * saving screenshots as 768x576 8-bit RLE compressed TGA files
  * saving and loading snapshots of the state of the emulated machine
  * demo recording (snapshot combined with stream of keyboard events
    which can be played back with accurate timing)
  * simple GUI debugger with support for breakpoints/watchpoints,
    viewing the current state of CPU registers and memory paging,
    displaying memory dump or loading from or saving to a file in ASCII
    or binary format, modifying memory or searching for a pattern of
    bytes, disassembler with support for all undocumented 6502 opcodes,
    address offset for code that runs at a different location than where
    it is at the time of disassembling, and saving disassembly to a
    file. For memory operations and the disassembler, addresses can be
    16 bit CPU (affected by current paging and includes memory mapped
    I/O registers) or 22 bit physical (all ROM and RAM data can be
    accessed, regardless of memory paging) addresses.
  * configurable keyboard map for the emulated machine; it is also
    possible to use external game controller devices like joysticks and
    gamepads

Plus/4 emulation
----------------

  * cycle based emulation of the 7501/8501 CPU, supporting all
    documented and undocumented opcodes, and fully compatible decimal
    mode
  * TED 7360/8360 emulation with high level of compatibility, implements
    all documented video modes, PAL/NTSC mode switching, as well as most
    known display artifacts; all registers can be read and written, and
    the internal operation and timing is reproduced with good accuracy
  * RAM size can be 16, 32, 64, 256, or 1024 kilobytes (the latter two
    using the Hannes memory expansion)
  * up to 8 16 kilobyte banks of ROM can be loaded from external image
    files
  * tape emulation with playback, recording, and setting tape position;
    markers can be created for quick positioning to specific tape
    locations (useful for tapes with multiple files); uses custom file
    format which is PCM audio data with 1 to 8 bits of sample resolution
    and variable sample rate, and header including the table of markers;
    there is also limited (read only) support for the commonly used C16
    tape files, as well as read-write (although without markers) support
    for sound files like WAV, AIFF, etc.
  * experimental hardware level emulation of the 1541, 1551, and 1581
    floppy disk drives, with support for D64 and D81 files
  * load and automatically start .PRG file on start-up
  * .PRG, .D64, and .D81 files can be associated with plus4emu on
    Windows
  * SID chip (MOS 8580) emulation using version 0.16 of the reSID
    library written by Dag Lem
  * optional extension ROM (p4fileio.rom) for direct access to .PRG
    files by the load/save commands on the host system in a single user
    selectable directory

Installation
============

Linux
-----

On Linux and other POSIX platforms, the emulator is installed from the
source code, available at the SourceForge download page
  http://sourceforge.net/project/showfiles.php?group_id=192837
or the most recent state of the code can be downloaded from SVN with the
following command:
  svn co http://plus4emu.svn.sourceforge.net/svnroot/plus4emu plus4emu
In addition to the standard development tools (a recent version of the
GNU C/C++ compiler, binutils, etc.), you need the following packages:

  * SCons (http://www.scons.org/)
  * Python interpreter for running SCons
  * FLTK 1.1.x (http://www.fltk.org/software.php?VERSION=1.1.7)
    NOTES:
      * this library should be compiled with the --enable-threads
        'configure' option - many Linux distributions include binaries
        of the FLTK library built without --enable-threads, so you may
        need to compile it from sources
      * on MacOS X, FLTK 1.1.7 needs to be patched with the included
        fltk-1.1.7-MacOSX.patch file
  * PortAudio (http://www.portaudio.com/download.html), version 18 and
    19 are supported, but v19 is recommended
  * libsndfile (http://www.mega-nerd.com/libsndfile/#Download)
  * dotconf (http://www.azzit.de/dotconf/) (optional, but recommended as
    it is used for reading ASCII format configuration files)
  * SDL (http://www.libsdl.org/) 1.2 for joystick input (optional);
    NOTE: on Linux, version 1.2.10 and newer do not work, so using 1.2.9
    is recommended

Once these are installed, you can edit the file 'SConstruct' in the top
level source directory for setting compiler flags etc., and run the
command 'scons' for building the emulator. The resulting executable
files (plus4emu and tapconv) can be copied to any directory that is in
the PATH; on MacOS X, an .app package is created in 'plus4emu.app'.
When installing the first time, you also need to set up configuration
files and ROM images:

  * download http://www.sharemation.com/IstvanV/roms/plus4emu_roms.zip,
    and extract it to ~/.plus4emu/roms (or, in the case of MacOS X,
    ~/Library/Application Support/plus4emu/roms)
  * after installing the ROM images, run 'plus4emu', and click OK to the
    windows that pop up asking for the base directory of configuration
    and data files, and if configuration files should be installed

It is possible to reinstall configuration files later by running the
'makecfg' utility.

Windows
-------

A binary package with an installer is available at the SourceForge
download page:
  http://sourceforge.net/project/showfiles.php?group_id=192837
To install, just run the executable, and follow the instructions.
The installer can automatically download the ROM images needed for
running the emulator, but these can also be installed manually by
downloading http://www.sharemation.com/IstvanV/roms/plus4emu_roms.zip,
and extracting it to roms\ under the selected installation folder.
When asked if configuration files should be reinstalled, click 'OK'
when installing the first time, but this step can be skipped in later
installations to preserve the configuration.

Usage
=====

Command line options
--------------------

  -h
  -help
  --help
    print the list of available command line options
  -cfg <FILENAME>
    load an ASCII format configuration file on startup, and apply
    settings
  -prg <FILENAME>
    load and run program file on startup
  -disk <FILENAME>
    load and automatically start disk image on startup
  -snapshot <FILENAME>
    load snapshot or demo file on startup
  -opengl
    use OpenGL video driver (this is the default, and is recommended
    when hardware accelerated OpenGL is available)
  -no-opengl
    use software video driver; this is slower than OpenGL when used at
    high resolutions, and also disables many display effects, but should
    work on all machines; however, it will use a color depth of 24 bits,
    while in OpenGL mode the textures are 16 bit (R5G6B5) only, to
    improve performance
  OPTION=VALUE
    set configuration variable 'OPTION' to 'VALUE'; the available
    variable names are the same as those used in ASCII format
    configuration files
  OPTION
    set boolean configuration variable 'OPTION' to true

'File' menu
-----------

Configuration / Load from ASCII file

  Select and load an ASCII format configuration file and apply the new
  settings. If the configuration file does not include all the supported
  options, those that are omitted are left unchanged.

Configuration / Load from binary file

  Load a plus4emu format binary file, which may be a previously saved
  snapshot or demo, a binary format configuration file, or a program
  file with plus4emu header.

Configuration / Save as ASCII file

  Save the current emulator configuration to an ASCII text file, which
  can be edited with any text editor, and can be loaded at a later time.

Configuration / Save

  Save the current emulator configuration in binary format to the
  default file (~/.plus4emu/plus4cfg.dat). This is also automatically
  done when exiting the emulator.

Configuration / Revert

  Reload emulator configuration from ~/.plus4emu/plus4cfg.dat, and apply
  the original settings.

Save snapshot

  Save a snapshot of the current state of the emulated machine to the
  selected file. The snapshot will also include the current memory
  configuration and ROM images, but clock frequency and timing settings
  are not restored when loading a snapshot. The file format may be
  subject to changes between different releases of the emulator. Note
  that the state of any floppy drives is currently not saved, and the
  drives are reset on loading a snapshot.

Load snapshot (F7)

  Load a plus4emu format binary file, which may be a previously saved
  snapshot or demo, a binary format configuration file, or a program
  file with plus4emu header.

Quick snapshot / Set file name

  Select file name for quick snapshots. The default is
  ~/.plus4emu/qs_plus4.dat. This setting is not saved on exit.

Quick snapshot / Save (Ctrl + F9)

  Save snapshot to the quick snapshot file (see notes above).

Quick snapshot / Load (Ctrl + F10)

  Load the quick snapshot file if it exists.

Record demo

  Save snapshot (including clock frequency and timing settings) and
  record keyboard events to the selected file until the recording is
  stopped. The events can be replayed with accurate timing when the
  file is loaded later. Note that the file format may change between
  different releases of the emulator, and the timing may also be
  incorrect when using a different version to play a demo file.

Stop demo (Ctrl + F12)

  Stop any currently running demo playback or recording.

Load demo (F7)

  Load a plus4emu format binary file, which may be a previously saved
  snapshot or demo, a binary format configuration file, or a program
  file with plus4emu header.

Record sound file

  Write 16 bit signed PCM sound output to a WAV format sound file.

Stop sound recording

  Close sound output file if it is currently being written.

Save screenshot

  Save a screenshot in 8 bit RLE compressed TGA format. The video output
  is captured immediately after activating this menu item, and is saved
  at a resolution of 768x576 without any processing (color correction,
  effects, etc.).

Quit

  Exit the emulator.

'Machine' menu
--------------

Reset / Reset (F11)

  This has the same effect as using the reset button on the real
  machine.

Reset / Force reset (Ctrl + F11)

  In addition to a normal reset, make sure that the emulated machine is
  really restarted using the standard ROM reset routines, and do not
  allow programs to disable reset by setting custom (RAM) handlers;
  however, most of the RAM data is still preserved.
  This option will also turn off automatically enabled extensions that
  increase CPU usage, such as SID emulation and 1541/1551/1581 drives
  with no disk opened.

Reset / Reset clock frequencies

  Reset clock frequency and timing settings to those specified in the
  machine configuration; this is normally only useful after demo
  playback, which may override the settings.

Reset / Reset machine configuration (Shift + F11)

  Reset memory configuration (RAM size, ROM images), clock frequency,
  and timing settings according to the machine configuration, and clear
  all RAM data. Implies 'Force reset' and 'Reset clock frequencies'.
  Reverting the configuration can be useful after snapshot loading or
  demo playback, as these may change the settings.

Enable SID emulation

  Turn on SID emulation, making the SID registers appear at FD40-FD5F
  and FE80-FE9F; this increases the CPU usage of the emulator.
  SID emulation is also automatically enabled when a byte is written to
  the above mentioned address ranges, but some programs detect if a SID
  card is present by only reading the registers, and in those cases
  using this option is needed. SID emulation remains active until the
  next use of 'Force reset' or 'Reset machine configuration', and
  snapshot data includes SID state and whether it was enabled or not at
  the time of saving the snapshot.

Quick configuration / Load config 1 (PageDown)

  Load the configuration file ~/.plus4emu/p4vmcfg1.cfg, and apply the
  new settings.

Quick configuration / Load config 2 (PageUp)

  Load the configuration file ~/.plus4emu/p4vmcfg2.cfg, and apply the
  new settings.

Quick configuration / Save config 1

  Save the current clock frequency and timing settings to
  ~/.plus4emu/p4vmcfg1.cfg.

Quick configuration / Save config 2

  Save the current clock frequency and timing settings to
  ~/.plus4emu/p4vmcfg2.cfg.

'Options' menu
--------------

Display / Set size to 384x288
Display / Set size to 768x576
Display / Set size to 1152x864

  Resize the emulator window to predefined width/height values; this has
  no effect in fullscreen mode. While the window can also be resized
  using the window manager, sizes that are integer multiples of the
  actual screen resolution of the emulated machine may look better,
  particularly when texture filtering is not used, and are also slightly
  faster when using the software video driver.

Display / Cycle display mode (F9)

  Cycle between these four display modes:
    window with no menu bar
    window with menu bar (this is the default)
    fullscreen with menu bar
    fullscreen with no menu bar

Sound / Increase volume

  Increase sound output volume by about 1.5 dB.

Sound / Decrease volume

  Decrease sound output volume by about 1.5 dB.

Floppy / Configure... (Alt + D)

  Opens a dialog for setting up floppy emulation. For each drive, an
  image file can be selected. If the file name is left empty, that means
  having no disk in that particular drive. It may also be possible to
  directly access a real disk by using the /dev/fd* devices (on Linux)
  or \\.\A: (on Windows) as the image file.
  The file format must be either D64 or D81; the type is determined from
  the file size. Opening a D64 file will enable 1541 or 1551 emulation
  for that particular drive, while the 1581 will be emulated for D81
  files.
  Since these drives are emulated at the hardware level (with a 6502
  CPU, etc.), enabling them increases the CPU usage. A drive will remain
  active until a different type of image file is opened, or a snapshot
  is loaded or 'Force reset' (or anything that implies it) is used while
  there is no disk opened.

Floppy / Remove disk / Unit 8
Floppy / Remove disk / Unit 9
Floppy / Remove disk / Unit 10
Floppy / Remove disk / Unit 11
Floppy / Remove disk / All drives

  These are just shortcuts for setting the image file name for a
  specific floppy drive to an empty string.

Floppy / Replace disk / Unit 8
Floppy / Replace disk / Unit 9
Floppy / Replace disk / Unit 10
Floppy / Replace disk / Unit 11
Floppy / Replace disk / All drives

  Set the image file name for a specific (or all) floppy drive to an
  empty string, and then set the original file name again. This is
  mostly useful when accessing real floppy disks, after the disk is
  changed.

Set working directory

  Set the directory to be accessed by the optional file I/O ROM
  extension modules.

Copyright
=========

plus4emu is copyright (C) 2003-2007 by Istvan Varga
<istvanv@users.sourceforge.net>.
reSID 0.16 copyright (C) 2004 by Dag Lem.

This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 2 of the License, or (at your
option) any later version.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
59 Temple Place, Suite 330, Boston, MA  02111-1307 USA

Credits
-------

Thanks to Hársfalvi Levente for testing the emulator and providing some
hardware information, and MagerValp for testing on MacOS X and
contributing binaries.

