PSID64 README
                                 =============

INTRODUCTION
------------

PSID64 is a program that automatically generates a C64 self extracting
executable from a PSID file. The executable contains the PSID data, a
pre-relocated player and may also - if there is enough space available in the
C64 environment - contain a demonstration program with information about the
PSID file.

PSID files contain music code and data originally generated on the Commodore 64
(C64). If you're new to PSID files please refer to the introduction chapter of
the High Voltage SID Collection documentation for a brief introduction into SID
music.

Before PSID64, playing PSID files on a C64 or a C64 emulator has been a rather
frustrating experience. The fundamental problem of where to locate the PSID
driver has simply not been appropriately addressed. Actually, having a PSID
file play at all has been pure luck, since there has been made no attempt to
find a memory range that is not written to by the music code. Not surprisingly,
a large number of PSID files could not be played at all using existing C64
computers and C64 emulator SID players.

The document "Proposal for C64 compatible PSID files", written by Dag Lem and
Simon White extends the PSID format with relocation information. PSID64 is the
first implementation of a PSID player intended for playback on a real C64 or
C64 environment that uses this relocation information stored in the PSID
header.


USAGE
-----

PSID64 is invoked from the command line as follows:

    psid64 [OPTION]... PSID_FILE...

where PSID_FILE is the names of one or more the PSID files. The resulting
C64 executable(s) are written to the current directory. Options available:

  -b, --blank-screen   use a minimal driver that blanks the screen
  -g, --global-comment include the global comment STIL text
  -o, --output=FILE    specify output file
  -r, --root           specify HVSC root directory
  -v, --verbose        explain what is being done
  -h, --help           display this help and exit
  -V, --version        output version information and exit


KEYS PLAYER INSTRUCTIONS
------------------------

1-0, A-Z  Select song 1-36
+   Select next song (*)
-   Select previous song (*)
INST/DEL  Toggle screen blanking on/off (*)
RUN/STOP  Stop playback
LEFT ARROW  Fast forward (**)
SHIFT LEFT / LOCK Show rastertime used by player (**)
CONTROL + CBM + DEL Reset computer (*)

* not available in minimal driver (i.e. the driver that blanks the screen)
** not available for custom players (i.e. play address is $0000).


OTHER TOOLS
-----------

Andre Fachat's relocating 6502 cross assembler XA is used to create the
relocatable driver code. XA can be found at:

    http://www.tu-chemnitz.de/~fachat/c64/xa/index.html

The C64 executables produced by PSID64 can be compressed with pucrunch, the
freeware cross-cruncher developed by Pasi 'Albert' Ojala. Pucrunch can be
downloaded from:

    http://www.cs.tut.fi/~albert/Dev/pucrunch/

     .___________________________________________________________.
     |                                                           |
     |       A M I G A   O S   4 . 0   C O M P I L E   B Y       |
    ._______                                        .______.     |
    |  ____/________________________________________|      |__   .
  ._|____._         |      ._       |      ._       |       _/______.
  |      |/         |      |/       |      |/       |      |/       |
  |                 |      _________|               |               |
  |_________________|______|spt/up  |_______________|_______________| 
     .                                                           .
     |                                                           | 
     |   I am in a shitty economical situation, so if you feel   | 
     |  that what I do is  worth anything, use paypal to donate  |  
     |         to my email addy, spotATtriadDOTse, thanx!        | 
     |                                                           | 
     |                    Spot / Up Rough 2006                   | 
     |___________________________________________________________|