Mercurial > hg > xmms-sid

comparison src/SID_file_format.txt @ 420:e9e0b633d417

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add SID format documentation
author Matti Hamalainen <ccr@tnsp.org>
date Wed, 20 Dec 2006 15:38:03 +0000
parents
children
comparison
equal deleted inserted replaced
419:bf4664ed897d 420:e9e0b633d417
1
2 ===========================
3 SID FILE FORMAT DESCRIPTION
4 ===========================
5
6 AUTHORS:
7 Michael Schwendt <sidplay@geocities.com> (PSID v1 and v2)
8 Simon White <sidplay2@yahoo.com> (PSID v2NG, RSID)
9 Dag Lem <dag@nimrod.no>(PSID v2NG)
10 LaLa <LaLa@C64.org> (This document)
11
12
13 INTRODUCTION
14 ============
15
16 This document describes the SID file format used for SID tunes in the HVSC
17 (High Voltage SID Collection - http://www.hvsc.c64.org). It is based mostly on
18 Michael Schwendt's excellent document found at:
19
20 http://www.geocities.com/SiliconValley/Lakes/5147/sidplay/doc_formats.html
21
22 and the PSID v2NG extensions described by Simon White and Dag Lem in:
23
24 http://sidplay2.sourceforge.net
25
26 SID files use the .sid file extension.
27
28 Since PSID v2 is simply an extension of PSID v1, PSID v2NG is an extension of
29 PSID v2, and RSID is a restricted version of PSID v2NG, all of the formats are
30 discussed together below. RSID in specific is discussed in detail under the
31 'magicID' field description.
32
33 The information presented here targets programmers, freaks, or other people
34 with reasonable background. It is not suitable for newbies who have never
35 before used a machine code monitor, a disassembler, or a hexadecimal editor.
36
37
38 The SID file header v1
39 ======================
40
41 The detailed structure of the SID header looks like the following. Header
42 offsets are in hexadecimal notation. Other integer values are decimal unless
43 explicitly marked otherwise. Any stored integer values are in big-endian
44 format:
45
46 +00 magicID: ``PSID'' or ``RSID''
47
48 This is a four byte long ASCII character string containing the value
49 0x50534944 or 0x52534944. 'RSID' (Real SID) denotes that the file strictly
50 requires a true Commodore-64 environment to run properly. 'PSID' files will
51 generally run trouble-free on older PlaySID and libsidplay1 based emulators,
52 too.
53
54 Some words about the Real C64 SID file format (RSID):
55
56 The RSID format was designed to contain tunes that are not PlaySID compatible,
57 but strictly require a real C64 environment to run. Tunes that are multi-speed
58 and/or contain samples and/or use additional interrupt sources or do busy
59 looping will cause older SID emulators to lock up or play very wrongly (if at
60 all).
61
62 By using the name RSID for such rips all existing SID emulators will reject
63 these tunes safely until they can be upgraded to cope with the additional
64 requirements.
65
66 Due to the nature of these tunes, every effort must be made to make sure they
67 are directly runnable on an actual C64 computer. As such the tunes will only
68 be presented with the default C64 power-on environment and expected to
69 configure and use all hardware appropriately.
70
71 RSID is based on PSIDv2NG with the following modifications:
72
73 magicID = RSID
74 version = only 2
75 loadAddress = 0 (reserved)
76 playAddress = 0 (reserved)
77 speed = 0 (reserved)
78 psidSpecific flag = 0 (reserved)
79
80 The above fields MUST be checked and if any differ from the above then the
81 tune MUST be rejected. The definitions above will force tunes to contain
82 proper hardware configuration code and install valid interrupt handlers.
83
84 The default C64 environment is as follows:
85
86 VIC - IRQ set to raster 0, but not enabled.
87 CIA 1 timer A - set to 60Hz with the counter running and IRQs active.
88 Other timers - disabled and loaded with $FFFF.
89 Bank register - $37
90
91 A side effect of the bank register is that init MUST NOT be located under a
92 ROM/IO memory area (addesses $0000-$07E8, $A000-$BFFF and $D000-$FFFF).
93 Since every effort needs to be made to run the tune on a real C64 the load
94 address of the image MUST NOT be set lower than $07E8.
95
96 +04 WORD version
97
98 Available version number can either be 0001 or 0002. Headers of version 2
99 provide additional fields. RSID and PSID v2NG files must have 0002 here.
100
101 +06 WORD dataOffset
102
103 This is the offset from the start of the file to the C64 binary data area.
104 Because of the fixed size of the header, this is either 0x0076 for version 1
105 and 0x007C for version 2.
106
107 +08 WORD loadAddress
108
109 The C64 memory location where to put the C64 data. 0 means the data are in
110 original C64 binary file format, i.e. the first two bytes of the data contain
111 the little-endian load address (low byte, high byte). This must always be true
112 for RSID files. Furthermore, the actual load address must NOT be less than
113 $07E8 in RSID files.
114
115 You must be absolutely sure what to enter here. There is no way to detect
116 automatically whether the first two bytes in a C64 data file are meant to be a
117 load address or some arbitrary bytes of code or data. Unless your C64 file is
118 not a normal binary file and thus has no load address in front, you need not
119 enter anything else than 0 here. The SID tune will not play if you specify a
120 load address which is present in the C64 file already.
121
122 Normal C64 binary data files have a load address in their first two bytes, so
123 they can be loaded to a pre-defined destination address by executing
124 LOAD"FILE",8,1, for instance. If a load address is explicitly specified in the
125 sidtune info file, some sidtune converters and utilities conjecture that the
126 C64 data don't have a load address in their first two bytes. Hence, the
127 explicit load address from the info file is moved in front of the C64 data to
128 create a valid C64 binary file which can be easily loaded on a C64, too. If
129 that C64 file were to be saved, it would contain two superfluous data bytes at
130 offset 2 if an original load address had been in the first two bytes of the
131 old file. This process of adding a duplicate load address can be repeated. The
132 file loader strips off the first two bytes (the used load address) and puts
133 the rest of the file contents (including the now obsolete load address at file
134 offset 2) into memory. If the new load address is the same than the old one
135 the two added bytes cause the whole data to be displaced by two bytes, which
136 most likely results in malfunctioning code. Also, superfluous bytes in memory
137 then can confuse disassemblers which start at the beginning of the file or
138 memory buffer.
139
140 +0A WORD initAddress
141
142 The start address of the machine code subroutine that initializes a song,
143 accepting the contents of the 8-bit 6510 Accumulator as the song number
144 parameter. 0 means the address is equal to the effective load address.
145
146 In RSID files initAddress must never point to a ROM area ($A000-$BFFF or
147 $D000-$FFFF) or be lower than $07E8.
148
149 +0C WORD playAddress
150
151 The start address of the machine code subroutine that can be called frequently
152 to produce a continuous sound. 0 means the initialization subroutine is
153 expected to install an interrupt handler, which then calls the music player at
154 some place. This must always be true for RSID files.
155
156 +0E WORD songs
157
158 The number of songs (or sound effects) that can be initialized by calling the
159 init address. The minimum is 1. The maximum is 256.
160
161 +10 WORD startSong
162
163 The song number to be played by default. This value is optional. It often
164 specifies the first song you would hear upon starting the program is has been
165 taken from. It has a default of 1.
166
167 +12 LONGWORD speed
168
169 This is a 32 bit big endian number. Each bit in 'speed' specifies the speed
170 for the corresponding tune number, i.e. bit 0 specifies the speed for tune 1.
171 If there are more than 32 tunes, the speed specified for tune 32 is also used
172 for all higher numbered tunes.
173
174 A 0 bit specifies vertical blank interrupt (50Hz PAL, 60Hz NTSC), and a 1 bit
175 specifies CIA 1 timer interrupt (default 60Hz).
176
177 Surplus bits in 'speed' should be set to 0.
178
179 For RSID files 'speed' must always be set to 0.
180
181 Note that if 'play' = 0, the bits in 'speed' should still be set for backwards
182 compatibility with older SID players. New SID players running in a C64
183 environment will ignore the speed bits in this case.
184
185 WARNING: This field does not work in PlaySID for Amiga like it was intended,
186 therefore the above is a redefinition of the original 'speed' field in SID
187 v2NG! See also the 'clock' (video standard) field described below for 'flags'.
188
189 +16 ``<name>''
190 +36 ``<author>''
191 +56 ``<released>'' (also known as ``<copyright>'')
192
193 These are 32 byte long zero terminated ASCII character strings. Upon
194 evaluating the header, a zero byte will always be put into the last byte of
195 each string. So the maximum number of available free characters is 31.
196
197 +76 <data>
198
199 Version 1 of the SID header is complete at this point. The binary C64 data
200 starts here.
201
202
203 The SID file header v2
204 ======================
205
206 Version 2 of the header incorporates the v1 header fields and provides
207 additional fields. Some of these are actually v2NG specific - those are noted
208 below.
209
210 +76 WORD flags
211
212 This is a 16 bit big endian number containing the following bitfields:
213
214 - Bit 0 specifies format of the binary data (musPlayer):
215 0 = built-in music player,
216 1 = Compute!'s Sidplayer MUS data, music player must be merged.
217
218 If this bit is set, the appended binary data are in Compute!'s Sidplayer MUS
219 format, and does not contain a built-in music player. An external player
220 machine code must be merged to replay such a sidtune.
221
222 - Bit 1 specifies whether the tune is PlaySID specific, e.g. uses PlaySID
223 samples (psidSpecific):
224 0 = C64 compatible,
225 1 = PlaySID specific.
226
227 This is a v2NG specific field.
228
229 PlaySID samples were invented to facilitate playback of C64 volume register
230 samples with the original Amiga PlaySID software. PlaySID samples made samples
231 a reality on slow Amiga hardware with a player that was updated only once a
232 frame.
233
234 Unfortunately, converting C64 volume samples to PlaySID samples means that
235 they can no longer be played on a C64, and furthermore the conversion might
236 potentially break the non-sample part of a tune if the timing between writes
237 to the SID registers is at all altered. This follows from the ADSR bugs in the
238 SID chip.
239
240 Today, the speed of common hardware and the sophistication of the SID players
241 is such that there is little need for PlaySID samples. However, with all the
242 PlaySID sample PSIDs in existence there's a need to differentiate between SID
243 files containing only original C64 code and PSID files containing PlaySID
244 samples or having other PlaySID specific issues. As stated above, bit 1 in
245 'flags' is reserved for this purpose.
246
247 For the same reasons, this flag must always be set to 0 in RSID files.
248
249 - Bits 2-3 specify the video standard (clock):
250 00 = Unknown,
251 01 = PAL,
252 10 = NTSC,
253 11 = PAL and NTSC.
254
255 This is a v2NG specific field.
256
257 As can be seen from the 'speed' field, it is not possible to specify NTSC C64
258 playback. This is unfortunate, since the different clock speeds means that a
259 tune written for the NTSC C64 will be slightly detuned if played back on a PAL
260 C64. Furthermore, NTSC C64 tunes driven by a vertical blank interrupt have to
261 be converted to use the CIA 1 timer to fit into this scheme. This can cause
262 severe problems, as the NTSC refresh rate is once every 17045 cycles, while
263 the CIA 1 timer A is latched with 17095 cycles. Apart from the difference in
264 timing itself, the SID ADSR bugs can actually break the tune.
265
266 The 'clock' (video standard) field was introduced to circumvent this problem.
267
268 - Bits 4-5 specify the SID version (sidModel):
269 00 = Unknown,
270 01 = MOS6581,
271 10 = MOS8580,
272 11 = MOS6581 and MOS8580.
273
274 This is a v2NG specific field.
275
276 The MOS6581 and the MOS8580 have three notable differences. First, combined
277 waveforms are generally louder on a MOS8580, to the extent that some
278 combinations that are clearly audible on a MOS8580 are completely silent on a
279 MOS6581. Second, the internal DC levels in the MOS8580 are so small that
280 software or hardware tricks must be used to play volume samples. Third, the
281 MOS8580 analog filter has totally different characteristics from the MOS6581
282 analog filter.
283
284 To ensure that music specifically written for one of the two SID versions can
285 be played back correctly, bits 4-5 in 'flags' are used as stated above.
286
287 - Bits 6-15 are reserved and should be set to 0.
288
289 +78 BYTE startPage (relocStartPage)
290
291 This is a v2NG specific field.
292
293 This is an 8 bit number. If 'startPage' is 0, the SID file is clean, i.e. it
294 does not write outside its data range within the driver ranges. In this case
295 the largest free memory range can be determined from the start address and the
296 data length of the SID binary data. If 'startPage' is 0xFF, there is not even
297 a single free page, and driver relocation is impossible. Otherwise,
298 'startPage' specifies the start page of the single largest free memory range
299 within the driver ranges. For example, if 'startPage' is 0x1E, this free
300 memory range starts at $1E00.
301
302 +79 BYTE pageLength (relocPages)
303
304 This is a v2NG specific field.
305
306 This is an 8 bit number indicating the number of free pages after 'startPage'.
307 If 'startPage' is not 0 or 0xFF, 'pageLength' is set to the number of free
308 pages starting at 'startPage'. If 'startPage' is 0 or 0xFF, 'pageLength' must
309 be set to 0.
310
311 The relocation range indicated by 'startPage' and 'pageLength' should never
312 overlap or encompass the load range of the C64 data. For RSID files, the
313 relocation range should also not overlap or encompass any of the ROM areas
314 ($A000-$BFFF and $D000-$FFFF) or the reserved memory area ($0000-$03FF).
315
316 +7A WORD reserved
317
318 This is a 16 bit number and is reserved and should be set to 0.
319
320 +7C <data>
321
322 Version 2 of the SID header ends here. This offset is the start of the binary
323 C64 data. See also 'loadAddress' for what the first 2 bytes of 'data' might
324 indicate.