|
420
|
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.
|
