view release on metacpan or  search on metacpan

SID_file_format.txt  view on Meta::CPAN

                          ===========================
                          SID FILE FORMAT DESCRIPTION
                          ===========================

AUTHORS:
Michael Schwendt (PSID v1 and v2)
Simon White (PSID v2NG, RSID)
Dag Lem (PSID v2NG)
Wilfred Bos (PSID v3, RSID v3, PSID v4, RSID v4)
LaLa (This document)


INTRODUCTION
============

This document describes the SID file format used for SID tunes in the HVSC
(High Voltage SID Collection - http://hvsc.de). It is based mostly on
Michael Schwendt's document that describes the file format and the PSID v2NG
extensions described by Simon White and Dag Lem.

SID files use the .sid file extension.

Since PSID v2 is simply an extension of PSID v1, PSID v2NG is an extension of
PSID v2, RSID is a restricted version of PSID v2NG, PSID v3/v4 and RSID v3/v4
are extensions of PSID v2NG and RSID v2, all of the formats are discussed
together below. RSID in specific is discussed in detail under the 'magicID'
field description.

The information presented here targets programmers or other people with
reasonable background. It is not suitable for newbies who have never before
used a machine code monitor, a disassembler, or a hexadecimal editor.


The SID file header v1
======================

The detailed structure of the SID header looks like the following. Header
offsets are in hexadecimal notation. Other integer values are decimal unless
explicitly marked otherwise. Any stored integer values are in big-endian
format:

+00    magicID: 'PSID' or 'RSID'

This is a four byte long ASCII character string containing the value
0x50534944 or 0x52534944. 'RSID' (Real SID) denotes that the file strictly
requires a true Commodore-64 environment to run properly. 'PSID' files will
generally run trouble-free on older PlaySID and libsidplay1 based emulators,
too.

Some words about the Real C64 SID file format (RSID):

The RSID format was designed to contain tunes that are not PlaySID compatible,
but strictly require a real C64 environment to run. Tunes that are multi-speed
and/or contain samples and/or use additional interrupt sources or do busy
looping will cause older SID emulators to lock up or play very wrongly (if at
all).

By using the name RSID for such rips all existing SID emulators will reject
these tunes safely until they can be upgraded to cope with the additional
requirements.

Due to the nature of these tunes, every effort must be made to make sure they
are directly runnable on an actual C64 computer. As such the tunes will only
be presented with the default C64 power-on environment and expected to
configure and use all hardware appropriately.

RSID is based on PSIDv2NG with the following modifications:

magicID = RSID
version = 2, 3 and 4 only
loadAddress = 0 (reserved)
playAddress = 0 (reserved)
speed = 0 (reserved)
psidSpecific flag is called C64BASIC flag

The above fields MUST be checked and if any differ from the above then the
tune MUST be rejected. The definitions above will force tunes to contain
proper hardware configuration code and install valid interrupt handlers.

See section "The SID file environment" mentioned later in this document for the
default C64 power-on environment for each SID file format.

+04    WORD version

Available version number can be 0001, 0002, 0003 or 0004. Headers of version 2,
3 and 4 provide additional fields. RSID and PSID v2NG files must have 0002,
0003 or 0004 here.

+06    WORD dataOffset

This is the offset from the start of the file to the C64 binary data area.
Because of the fixed size of the header, this is either 0x0076 for version 1
and 0x007C for version 2, 3 and 4.

+08    WORD loadAddress

The C64 memory location where to put the C64 data. 0 means the data are in
original C64 binary file format, i.e. the first two bytes of the data contain
the little-endian load address (low byte, high byte). This must always be true
for RSID files. Furthermore, the actual load address must NOT be less than
$07E8 in RSID files.

You must be absolutely sure what to enter here. There is no way to detect
automatically whether the first two bytes in a C64 data file are meant to be a
load address or some arbitrary bytes of code or data. Unless your C64 file is
not a normal binary file and thus has no load address in front, you need not
enter anything else than 0 here. The SID tune will not play if you specify a
load address which is present in the C64 file already.

Normal C64 binary data files have a load address in their first two bytes, so
they can be loaded to a pre-defined destination address by executing
LOAD"FILE",8,1, for instance. If a load address is explicitly specified in the
sidtune info file, some sidtune converters and utilities conjecture that the
C64 data don't have a load address in their first two bytes. Hence, the