*** SID/PSID (Various SIDPlay / PlaySID Emulator Formats) *** Document revision 1.0 The data files used by SIDPLAY contain binary C64 data and music player machine code. Both, the programmer on the C64 and this emulator need information on how to access the code inside the binary file. That means, information like the memory location to load the file to, the number of tunes, the starting address of the executable code and its subroutines. This specific information has to be delivered in either a separate file - which is often called info file - or in form of a header in the single binary data file. A standalone C64 data file without a header or without a corresponding info file is considered invalid. It is recommended that you get accustomed to one-file sidtunes with the *.sid extension. For raw C64 binary files the extension .c64 or .prg is preferred in order to be able to assign a .sid extension to the additional info file. Supported and merely used file formats are: PlaySID single-file-format (widely known as PSID) PlaySID info-file-format (Raw C64 binary file plus Amiga Workbench icon tooltype file .INFO) SIDPLAY info-file-format (Raw C64 binary file plus SIDPLAY ASCII text info file, previously .SID) C64 Sidplayer format (.MUS) Raw data or PSID files have appeared as *.data, *.psid or psid.*. DAT files The .DAT file name extension has been introduced by the early versions of SIDPLAY/DOS. It has never been used to specify a file format. Its main use has been in assigning a unique file name extension to any sidtune file, but especially raw C64 data files, and allowing to use .SID for additional info files. INFO files These are Amiga Workbench tooltype icons containing binary graphics data and ASCII text information strings. They have been used by PlaySID and are supported by SIDPLAY. Their file name extension normally is .info or .INF. This is a two-file format. A separate C64 binary data file is required. On Amiga the corresponding C64 data files usually haven't had filename extensions. However, they might have been renamed on other systems. SIDPLAY info files These are plain ASCII text files which have been introduced by the earlier versions of SIDPLAY/DOS. They are used to be able to alter the information inside with a normal ASCII text editor. They can be converted to a single file that contains a binary header. This is a two-file format. A separate C64 binary data file is required. Notice that each pair of files usually has the old DOS-naming of .SID for the info file and .DAT for the C64 data file. The SIDPLAY info file is derived from the information inside the PlaySID one-file format. It is structured like this: SIDPLAY INFOFILE ADDRESS=,, SONGS=[,] SPEED= NAME= AUTHOR= COPYRIGHT= SIDSONG= The first line of the text containing ``SIDPLAY INFOFILE'' is only used to identify the type of file. ADDRESS=,, Each specified address is a 16-bit effective C64 memory location in case insensitive hexa-decimal notation without a prefix, e.g. C000 or E012, but neither $FCE2 nor 0xFCE2. Preceding zeroes are ignored. is the C64 memory location where to put the C64 data. 0 means, the data is in original C64 format, i.e. the first two bytes contain the little-endian load address (low byte, high byte). Please don't explicitly specify the load address unless required for sure. If the load address is explicitly specified, some sidtune converters and utilities conjecture that the C64 data lacks its load address. Hence they move it in front of the C64 data. This would create two redundant bytes if the C64 data already had a load address in the first two bytes. Additionally, those extra bytes in the beginning can confuse disassemblers. is the start address of the machine code subroutine that initializes a song by accepting the contents of the 8-bit 6510 Accumulator as the song number parameter. 0 means, the address is equal to the effective load address. is the start address of the machine code subroutine that can be called frequently to produce a continuous sound. 0 means, the initialization subroutine is expected to install an interrupt handler, which then calls the music player. If so, the value in the bank-select register $01 determines whether the IRQ vector $0314/$0315 (Kernal-ROM on) or the IRQ vector $FFFE/$FFFF (Kernal-ROM off) is to be used. SONGS=,[] is the decimal number of songs (or sound effects) that can be initialized by calling the init address. The minimum is 1. is the decimal number of the song to be played by default. This value is meant as a proposal and is optional. It has a default of 1. It often specifies the first song you would hear upon starting the program is has been taken from. SPEED= is a value in case insensitive hexa-decimal notation without a prefix. Preceding zeroes are ignored. The value contains information about the speed of each song. For each song a bit is reserved, bit 0 for song 1, bit 1 for song 2, and so on. A bit set to 0 means, the music player subroutine is called at 50 Hz. A bit set to 1 means, the real speed is indicated by the CIA 1 Timer A $DC04/05, which defaults to 60 Hz. To not break compatibility to the PlaySID formats, use a maximum of 32 bits, which is equal to 32 songs. Due to a bug in PlaySID, the PSID format can only handle up to 8 songs correctly. On the contrary, the SIDPLAY info format is extended to 256 bits, which is equal to 256 songs. Examples: SPEED=0 replays every song at 50 Hz speed. SPEED=1F replays songs 1-5 at 60 Hz speed, all other songs at 50 Hz speed. NAME= AUTHOR= COPYRIGHT= These three fields are all plain ASCII text strings. There are limited to a maximum of 80 characters each. To not break compatibility to the PlaySID formats, use a maximum of 31 characters. SIDSONG= is used to indicate that the corresponding C64 data file is in (Enhanced) Sidplayer file format. This field is optional and defaults to NO. An example file ``EXAMPLE.SID'' may look like this: SIDPLAY INFOFILE ADDRESS=2AF0,3002,300C SONGS=3,2 SPEED=0 NAME=Example AUTHOR=Example COPYRIGHT=199? (c) Example SIDSONG=NO PSID file header You can display any file with a normal ASCII/HEX editor. If the first four characters (bytes) contain the word PSID, and if close to the beginning there are ASCII text strings containing readable author and copyright information, you can almost be sure that it is in PlaySID v2.2+ (Amiga) one-file format. The detailed structure of the PSID header looks like the following. Header offsets are in hexa-decimal notation. Other integer values are decimal unless explicitly marked otherwise. Because of the Amiga hardware, any stored integer values are in big-endian format: +00 ``PSID'' This is a four byte long ASCII character string containing the value 0x50534944. +04 WORD version Available version number can either be 0001 or 0002. Headers of version 2 provide additional fields. +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. Whether the value in this field might also be the address of the used Amiga timer interrupt handler is unconfirmed. Although interrupt level 7 really is at address 0x0000007C, the other value would be invalid. The playsid.library doesn't recognize PSID files with other data offets. +08 WORD loadAddr The C64 memory location where to put the C64 data. 0 means, the data is in original C64 format, i.e. the first two bytes contain the little-endian load address (low byte, high byte). Please don't explicitly specify the load address unless required for sure. If the load address is explicitly specified, some sidtune converters and utilities conjecture that the C64 data lacks its load address. Hence they move it in front of the C64 data. This would create two redundant bytes if the C64 data already had a load address in the first two bytes. Additionally, those extra bytes in the beginning can confuse disassemblers. +0A WORD initAddr The start address of the machine code subroutine that initializes a song, accepting the contents of the 8-bit 6510 Accumulator as the song number parameter. 0 means, the address is equal to the effective load address. +0C WORD playAddr The start address of the machine code subroutine that can be called frequently to produce a continuous sound. 0 means, the initialization subroutine is supposed to install an interrupt handler, which then calls the music player at some place. +0E WORD songs The number of songs (or sound effects) that can be initialized by calling the init address. The minimum is 1. The maximum is 256. +10 WORD startSong The song number to be played by default. This value is meant as a proposal and is optional. It often specifies the first song you would hear upon starting the program is has been taken from. It has a default of 1. +12 LONGWORD speed This field does not work like it was intended. The PlaySID authors wrote: speeddata contains info about playspeed. For each tune a bit is reserved, bit 0 for tune nr 1 and so on. A 0 bit means vertical sync (50Hz PAL Amiga or 60Hz NTSC Amiga) and a 1 bit means 60 Hz or the time set in $DC04/05. Default value is 0 for all bits. Unfortunately, PlaySID's behaviour upon evaluating this field is different. Only the least significant byte does work. When starting to count from 0, all songs above or equal to number 8 are always set to speed 0, i.e. 50 Hz PAL. Since 32-bits are used, the technique would work only for a maximum of 32 songs anyway. +16 ``'' +36 ``'' +56 ``'' These are 32 byte long zero terminated ASCII character strings. Upon evaluating the header, a zero byte will always be put into the last byte of each string. So the maximum number of available free characters is 31. +76 Version 1 of the PSID header is complete at this point. The binary C64 data starts here. The PSID file header v2 Version 2 of the header provides additional fields. These are undocumented, but most likely rarely used. +76 WORD flags If bit 0 of this field is set, the appended binary data is in Compute!'s Sidplayer MUS format, and does not contain a built-in music player. An external player machine code must be merged to replay such a sidtune. This field almost ever contains a zero. +78 LONGWORD reserved This is undocumented. +7C Version 2 of the PSID header ends here. This offset is the start of the binary C64 data.