Logo by Alkaron (anonymous IP: 18.97.14.80,2260) | ||||||||||||||
| ||||||||||||||
Audio (343) Datatype (51) Demo (203) Development (602) Document (24) Driver (97) Emulation (149) Game (1015) Graphics (502) Library (118) Network (234) Office (66) Utility (932) Video (69) Total files: 4405 Full index file Recent index file
Amigans.net OpenAmiga Aminet IntuitionBase
Support the site
|
=================================================== HVSC UPDATE TOOL AND HVSC UPDATE SCRIPT DESCRIPTION =================================================== version 2.8.4 AUTHORS: The Shark <shark()dhp.com> (original author of the HVSC Update Tool, maintained it until v2.5) Michael Schwendt <sidplay()geocities.com> (v2.4.x portability fixes, v2.5 - v2.6.1, v2.7.0 GCC v3 patch) LaLa <LaLa()C64.org> (v2.7.0) INTRODUCTION ============ In order to provide a clean and easy way to update the High Voltage SID Collection (HVSC - http://www.hvsc.c64.org) from time to time, an HVSC Update pack is provided to users. It contains an Update script, which describes how the update should be performed, plus a bunch of SID files in PSID v2NG format that will be moved to their final location inside HVSC as described in the Update script. (See the PSID v2NG document for a complete description of that file format.) The HVSC Update Tool uses the Update script to carry out the actions described in it. The Win32 version of the HVSC Update Tool is packaged inside every HVSC Update pack, since a large percentage of HVSC users are using some flavor of the Microsoft Windows operating system. Users of other operating systems can find executables for their systems on the HVSC webpage, or can ask for the HVSC Update Tool source code from the HVSC Crew to compile an executable themselves. The HVSC Update Tool was written by The Shark, the person who brought HVSC itself into life. Later it was modified by Michael Schwendt to make it more compatible with many operating systems, and then by LaLa to add PSID v2NG support to it. Certain source files of the tool were lifted from Michael Schwendt's libsidplay SID emulator library and were later hacked for PSID v2NG conformance by LaLa. UPDATE TOOL =========== See also 'VERSION DEPENDENCY' later. DIR HIERARCHY DEPENDENCY ------------------------ The Update Tool checks for the existence of the Hubbard_Rob directory in the HVSC - if it doesn't exist, a warning is issued stating where the Update script should be placed and the user is given the choice to quit or continue. The Update script depends on a presumed HVSC directory hierarchy and thus, the Update Tool assumes the Update script is placed in a directory inside the HVSC (usually named 'update') before performing the update. Filenames relative to the main directory of the HVSC therefore are actually relative to the parent directory of this 'update' directory. MODIFYING SID FILES ------------------- Any file that is modified with the Update Tool (i.e. modified by keywords that change bits, bytes or characters inside a PSID file) is always saved as a valid PSID v2NG file, even if it wasn't such before. This means that, for example, any bits that might have been set in the 'reserved' field of the file before will be zeroed out by the Update Tool, since this field is defined as such in the PSID v2NG specification. AFTER THE UPDATE ---------------- If the Update Tool encounters errors during an update, it logs them to a file named 'ErrorXX.hvs', where XX is the same number that is found in the filename of the Update script. If no errors are encountered, there will be no ErrorXX.hvs file produced and the UpdateXX.hvs script itself will be moved to the DOCUMENTS directory of HVSC. UPDATE SCRIPT ============= Below is a complete description of the format of the Update script. When in doubt, the UpdateXX.hvs files found in the DOCUMENTS directory of HVSC always provide good examples. FILENAME -------- The name of the Update script must follow the convention 'UpdateXX.hvs', where 'XX' is a 2-digit decimal number that is usually one larger than the number of the most recent Update script found in the DOCUMENTS directory inside HVSC. If an Update script with the same filename already exists in the DOCUMENTS directory, the Update Tool quits immediately with an error, since it's assumed that the user wants to apply an update to an already updated collection. FILE FORMAT ----------- The HVSC Update script is a plain text file. Lines starting with a ``#'' or ``;'' character as the first non-space character are treated as comments unless they belong to a block of parameter lines. Comment lines can be everywhere except between successive parameter lines. Empty or blank lines are ignored, i.e. skipped. Leading white-space characters of a line are skipped unless the line belongs to a block of parameter lines which are meant to be copied into the sidtune file directly (see description of TITLE, AUTHOR, COPYRIGHT, CREDITS keywords). VERSION DEPENDENCY ------------------ The first few lines of every update script must contain these lines which reflect the Update Tool's dependency on the version of HVSC to be updated with the Update script: # Resulting Version: 4.6 # Previous Version: 4.5 The Update Tool will fetch the version numbers from these lines. The number of white-space between the words can be arbitrary. The HVSC version is fetched directly from the main HVSC documentation file found inside the HVSC as /DOCUMENTS/hv_sids.txt. The first few lines of that file must contain a line which contain nothing else than the word "release" followed by a real value. White-space is ignored. Example: release 4.5 Note that due to the difference between the PSID v2NG and v2 file specification, if the version of HVSC being updated with this version of the tool is lower than 3.9, the 'startPage', 'pageLength', 'psidSpecific', 'clock' and 'sidModel' fields will be automatically zeroed out when saving PSID files! KEYWORDS -------- Actions to be performed during an update are described by keywords. Each keyword selects a mode for actions and can be followed by one or more blocks of parameters - or another keyword (i.e. no parameters). Thus, repeated statement of the same keyword in front of successive parameter blocks is not necessary. Keywords are case-sensitive. Parameter blocks consist of one or more lines of text. This version of the tool recognizes the following keywords (sometimes also called directives): AUTHOR: 2 CLOCK: 2 COPYRIGHT: 2 CREDITS: 4 DELETE: 1 FIXLOAD: 1 FLAGS: 5 FREEPAGES: 2 INITPLAY: 2 MKDIR: 1 MOVE: 2 MUSPLAYER: 2 PLAYSID: 2 REPLACE: 2 SIDMODEL: 2 SONGS: 2 SPEED: 2 TITLE: 2 The numbers after the keywords describe the number of parameter lines that are taken in the mode selected by the given keyword. HVSC-RELATIVE PATHNAMES ----------------------- Every keyword above takes at least one parameter which is a pathname that is relative to the HVSC's main directory and must contain the slash (/) or back- slash (\) characters as file/directory separators. In this document all pathnames are so-called HVSC-relative pathnames unless explicitly stated otherwise. Destination directories must end with a / or \ character in order to be recognized as a directory unless they exist already. To improve readability of the script, it is recommended that all directories end with a / or \ character. Filenames, directory names, and pathnames are all case-insensitive. The HVSC Update Tool examines each directory to determine the correct case of a full path name. This is done to be file-system independent, archiver independent, and to allow for small typos in the script. These all name the same file: /Galway_Martin/Wizball.sid /GALWAY_Martin/Wizball.SID /galway_martin/wizball.sid The intended case for new files and directories is specified in form of destination pathnames (or the files in the HVSC Update pack). The precedence of file naming is the following in decreasing order of priority: 1.) Take case of the destination file name (if specified). 2.) Take case of the source file name (if specified). 3.) Take case of file name found in the HVSC Update pack. NOTE: The old HVSC Update Tool (version 2.4.x and older) did not do this properly! See the REPLACE keyword below for examples. DESCRIPTION OF KEYWORDS ----------------------- Below is a listing of each keyword, the parameters they take and a detailed description of what they do. Since many of the keywords change specific fields inside PSID v2NG files, the reader is advised to become familiar with the PSID file format before reading further. The format of parameter lines is as follows: - <dir> is a place-holder for an HVSC-relative path to a directory. - <file> is a place-holder for an HVSC-relative path to a file. - <32-bit hex> indicates a 32-bit hexadecimal value (with no prefix). - <16-bit hex> indicates a 16-bit hexadecimal value (with no prefix). - <8-bit hex> indicates an 8-bit hexadecimal value (with no prefix). - <dec> indicates a decimal value. - <text> indicates plain text that is max. 31 characters long, end-of-string delimiter excluded. - <PAL | NTSC> indicates the possible case-sensitive (!) values for the given parameter, in this case only two, PAL and NTSC. Note that repeated statement of command keywords in the examples below is redundant. MKDIR ----- Creates the last directory in the specified pathname which is the only parameter it takes. Causes an error if the path leading to that directory does not exist. NOTE: This keyword is almost obsolete since MOVE and REPLACE can create the last sub-dir in a path on the fly. Format: MKDIR <dir> Examples: # Creates the Example directory, provided that /VARIOUS/AMJ/ exists. MKDIR /VARIOUS/A-F/AMJ/Example/ # Causes an error if directory Blubb1 does not exist. MKDIR /VARIOUS/S-Z/Zardax/Blubb1/Blubb2/ DELETE ------ Deletes the file or directory specified by the pathname on the single parameter line. The given file must exist or an error is produced. The directory to be deleted must be empty or an error is produced. Only the last directory in the pathname is deleted. Formats: DELETE <file> DELETE <dir> Examples: # File must exist. # Why, if we want to get rid of it anyway? :) DELETE /DRAX/Worktunes/Bad_Rip.sid # Deletes the UNKOWN directory inside the DEMOS directory if it's empty, # leaves the DEMOS directory untouched. DELETE /DEMOS/UNKNOWN/ MOVE ---- Probably the most complex keyword found in Update scripts since it can take many forms, although its usage should be fairly intuitive. This keyword always takes two parameter lines, where both parameter lines contain a pathname: the first parameter line is always the source and the second is always the destination. Formats: MOVE <dir> <dir> Non-recursive copy of directory contents, i.e. it does not include sub- directories and their contents. It deletes the files in the source directory (but not the directory itself). Creates the destination directory if it doesn't exist, yet. MOVE <file> <file> Copies the source file to the destination file. Gives an error if the destination file already exists. Gives an error if the directory of the destination file does _not_ exist (this prevents creating unwanted dirs on the fly). Deletes the source file when done. MOVE <file> <dir> Copies the source file to the destination directory. If the destination directory does not exist, it creates it. Note that this will not create the full path, but just the last directory component like MKDIR. Deletes the source file when done. Examples: # Moves the given SID file from the update directory to its final destination # in HVSC. MOVE /update/Crowther_Antony/Gryphon.sid /Crowther_Antony/ # Moves the non-recursive contents of the Olsen directory from the update # directory to its final destination in HVSC. MOVE /update/VARIOUS/A-F/Amorphis/Olsen/ /VARIOUS/A-F/Amorphis/Olsen/ # Renames Gyroscope_loader.sid to Gyroscope_3_crack.sid as it moves it to its # new location in HVSC. MOVE /GAMES/G-L/Gyroscope_loader.sid /DEMOS/Gyroscope_3_crack.sid # The next two parameter blocks show a plaform-independent safe way of # changing the case of one or more characters of a filename. MOVE /GAMES/M-R/Rings_N_Up.sid /GAMES/M-R/Rings_n_Up_.sid /GAMES/M-R/Rings_n_Up_.sid /GAMES/M-R/Rings_n_Up.sid # Moves the new file to its new location and deletes the old file (which # was likely a bad rip). MOVE /update/GAMES/A-F/Boom_title.sid /GAMES/A-F/ DELETE /DEMOS/Boom.sid # Note, this is the prefered way of doing the above two actions, since other # scripts scanning the Update script will be able to deduce the new filename # this way, unlike in the previous case. MOVE /DEMOS/Boom.sid /GAMES/A-F/Boom_title.sid REPLACE /update/GAMES/A-F/Boom_title.sid /GAMES/A-F/ REPLACE ------- Probably the second most complex keyword found in Update scripts. :-) Like MOVE, this keyword also takes two parameter lines, where both parameter lines contain a pathname: the first parameter line is always the source and the second is always the destination. Formats: REPLACE <dir> <dir> Non-recursive merge of directory contents, i.e. it does not include sub- directories and their contents. Creates the last destination directory if it doesn't exist. Note that this will not create the full path, but just the last directory component like MKDIR. Overwrites any destination file that already exists. Deletes the source files (but not the directory that contains them). REPLACE <file> <file> Replaces the destination file with the source file. Overwrites the destination file if it already exists. Deletes the source file when done. Gives no error if destination file does _not_ exist. REPLACE <file> <dir> Copies the destination file to the destination directory. Overwrites the destination file if it already exists. Deletes the source file when done. If the destination directory does not exist, it is created. Note that this will not create the full path, but just the last directory component like MKDIR. Examples: # Example to demonstrate case-insensitivity. # # The following example overwrites any file named ``example.sid'', # disregarding case, and calls it ``eXaMpLe.SID'', disregarding the case of # the actual file in the HVSC Update pack. REPLACE /update/DEMOS/eXaMpLe.SID /DEMOS/ # The following overwrites any file named ``example.sid'', disregarding case, # and calls it ``Example.sid'', disregarding the case of the actual file in # the HVSC Update pack. REPLACE /update/DEMOS/eXaMpLe.SID /DEMOS/Example.sid TITLE, AUTHOR, COPYRIGHT ------------------------ These keywords take a destination file name as the first and a credit line as the second parameter line. A credit line must not be an empty or blank line and is limited to 31 characters, end-of-string delimiter excluded. TITLE changes the 'name' field inside a PSID file, AUTHOR the 'author' and COPYRIGHT the 'copyright' field. Note that these keywords _always_ change the destination file to a valid PSID v2NG file! Format: TITLE <file> <name - text> AUTHOR <file> <author - text> COPYRIGHT <file> <copyright - text> Example: # This is a comment inside an Update script. # Below example changes the 'name' field inside Amtrak.sid. TITLE /20CC/Amtrak.sid Amtrak CREDITS ------- This keyword provides an easier way to change the 3 credit lines inside a PSID file at once. The CREDITS keyword takes a path to a file and three successive lines as parameters. A parameter line consisting of nothing but an asterisk (*) leaves the corresponding credit line in the given PSID file untouched. See also TITLE, AUTHOR and COPYRIGHT above. Note that this keyword _always_ changes the destination file to a valid PSID v2NG file! NOTE: HVSC Update #10 has a parameter block which lacks the third credit line. Since old versions of the Update Tool did not detect this and hence did not cause an error, empty credit lines either must be allowed or the update version must be checked and Update #10 treated differently. Format: CREDITS <file> <* = don't change | name - text> <* = don't change | author - text> <* = don't change | copyright - text> Examples: CREDITS /20CC/Amtrak.sid Amtrak Edwin van Santen 1989 20th Century Composers # Another example. Don't change author name. # Next blank line will be skipped, these set of comments are ignored. /20CC/Amtrak.sid Amtrak * 1989 20th Century Composers SPEED ----- Changes the 'speed' field inside a PSID file. It takes a destination file name as the first and a hexadecimal value as the second parameter line. The hexadecimal value shouldn't be bigger than 32 bits. If the number of bits set this way is more than the number of songs in a PSID file, only the relevant bits will be set by the Update Tool. Note that this keyword _always_ changes the destination file to a valid PSID v2NG file! Format: SPEED <file> <speed - 32-bit hex> Example: # Changes the 'speed' field to 0x0000007F. SPEED /GAMES/A-F/Bird_Mother.sid 7F SONGS ----- Changes the 'songs' and 'startSong' fields inside a PSID file. It takes a destination file name as the first and two comma separated decimal values as the second parameter line: the first one changes the 'songs' field, the second the 'startSong' field. The decimal values should be less than 256 and the second value should be less than the first. There should be no whitespace around the comma. Note that this keyword _always_ changes the destination file to a valid PSID v2NG file! Format: SONGS <file> <songs - dec>,<startSong - dec> Example: # Changes the number of songs to 6 and the 'startSong' to 3. SONGS /Brooke_Jason/Pi_r_Squared.sid 6,3 INITPLAY -------- Changes the 'initAddress' and 'playAddress' fields inside a PSID file. It takes a destination file name as the first and two comma separated hexadecimal values as the second parameter line: the first one changes the 'initAddress' field, the second the 'playAddress' field. Since these refer to C64 addresses, the values should be maximum 16 bits large. There should be no whitespace around the comma. Note that this keyword _always_ changes the destination file to a valid PSID v2NG file! Format: INITPLAY <file> <initAddress - 16-bit hex>,<playAddress - 16-bit hex> Example: # Changes the 'initAddress' to $107E and the 'playAddress' to $1078. INITPLAY /20CC/Airwolf_Mix.sid 107E,1078 MUSPLAYER --------- Changes the 'musPlayer' field (bit 0 of the 'flags' field) inside a PSID file. It takes a destination file name as the first and a binary value as the second parameter line. A 0 indicates a built-in player, a 1 that Compute's Sidplayer is required to play the given SID tune. Note that this keyword _always_ changes the destination file to a valid PSID v2NG file! Format: MUSPLAYER <file> <0 = built-in player | 1 = Compute's Sidplayer is required> Example: # Changes bit 0 of 'flags' to indicate a built-in player is present in the SID # file. MUSPLAYER /Hubbard_Rob/Commando.sid 0 PLAYSID ------- Changes the 'psidSpecific' field (bit 1 of the 'flags' field) inside a PSID file. It takes a destination file name as the first and a binary value as the second parameter line. A 0 indicates the 'data' portion of the PSID file is C64 compatible, a 1 indicates that it's PlaySID specific (requiring special extensions introduced by the Amiga PlaySID program, like sample support, random value support, etc.) Note that this keyword _always_ changes the destination file to a valid PSID v2NG file! Format: PLAYSID <file> <0 = C64 compatible | 1 = PlaySID specific> Example: # Changes bit 1 of 'flags' to indicate this SID file is PlaySID specific. PLAYSID /Tel_Jeroen/Hotrod.sid 1 CLOCK ----- Changes the 'clock' field (bits 2-3 of the 'flags' field) inside a PSID file which indicate the video standard to be used to play the included SID tune, basically determining its speed. The keyword takes a destination file name as the first and a case-sensitive textual value as the second parameter line. Note that this keyword _always_ changes the destination file to a valid PSID v2NG file! Format: CLOCK <file> <UNKNOWN | PAL | NTSC | ANY or EITHER> Example: # Changes bits 2-3 of 'flags' to indicate this is an NTSC tune. CLOCK /GAMES/G-L/Into_the_Eagles_Nest_USA.sid NTSC SIDMODEL -------- Changes the 'sidModel' field (bits 3-4 of the 'flags' field) inside a PSID file which indicate the SID model the tune inside the given PSID file was intended for. The keyword takes a destination file name as the first and a case-sensitive textual value as the second parameter line. Note that this keyword _always_ changes the destination file to a valid PSID v2NG file! Format: SIDMODEL <file> <UNKNOWN | 6581 | 8580 | ANY or EITHER> # Changes bits 3-4 of 'flags' to indicate this tune was intended for an 8580 # SID chip. SIDMODEL /VARIOUS/A-F/Agemixer/Azmagutah_8580.sid 8580 FLAGS ----- Similar to the CREDITS keyword it makes it easier to change all bitfields found in the 'flags' field of a PSID file at once. It takes a destination file name as the first parameter line and 4 other parameter lines that are identical to the ones described in the MUSPLAYER, PLAYSID, CLOCK and SIDMODEL keywords above (in the same order). A parameter line consisting of nothing but an asterisk (*) leaves the corresponding bitfield in the given PSID file untouched. Note that this keyword _always_ changes the destination file to a valid PSID v2NG file! Format: FLAGS <file> <* = don't change | 0 = built-in player | 1 = Compute's Sidplayer is required> <* = don't change | 0 = C64 compatible | 1 = PlaySID specific> <* = don't change | UNKNOWN | PAL | NTSC | ANY or EITHER> <* = don't change | UNKNOWN | 6581 | 8580 | ANY or EITHER> Example: # Changes the 'clockSpeed' to indicate PAL and the 'sidModel' to indicate # 8580 SID chip, leaves the other bits in 'flags' untouched. FLAGS /VARIOUS/A-F/Agemixer/Azmagutah_8580.sid * * PAL 8580 FREEPAGES --------- Changes the 'startPage' and 'pageLength' fields inside a PSID file. It takes a destination file name as the first and two comma separated hexadecimal values as the second parameter line: the first one changes the 'startPage' field, the second the 'pageLength' field. The values should be maximum 8 bits large. There should be no whitespace around the comma. Note that this keyword _always_ changes the destination file to a valid PSID v2NG file! Format: FREEPAGES <file> <startPage - 8-bit hex>,<pageLength - 8-bit hex> # Indicates that the SID tune doesn't use the memory area $C000-$D000. FREEPAGES /Hubbard_Rob/Commando.sid C0,10 FIXLOAD ------- Increases load address of the C64 'data' inside a PSID file by 2. It is used to drop the first two bytes of C64 data to get rid of a duplicate load address ($0FFE instead of $1000, for example). It takes one parameter line only, which should be the filename to be modified. Note that this keyword _always_ changes the destination file to a valid PSID v2NG file! Format: FIXLOAD <file>
|
Copyright © 2004-2024 by Björn Hagström All Rights Reserved |