Mirror of http://hcs64.com/usf/usf.txt.
USF specification v1.2 9/19/04 - v1.0 - First official version 10/10/04 - v1.1 - Removed bug tags, added _enablecompare tag 1/14/06 - v1.2 - added _enableFIFOfull tag --- Structure of a USF file A USF file may contain an N64 save state and/or ROM image. The structure is that of a PSF file with version code 0x21. The save state and ROM are stored in the reserved area of the PSF file. The compressed program section is not used, thus the program size and CRC should both be zero. The organization of the reserved area is: SR64 ROM image (stored as little endian 4 byte words) or 4 zero bytes (signifying no ROM) then SR64 Project 64 v1.4 save state (format below) or 4 zero bytes (signifying no save state) --- Definition of SR64 Format SR64 is a sparse storage scheme. Instead of storing an entire file SR64 makes it possible to store only those parts which are important. USF uses this format to store the ROM and save state. SR64 format is: 4 byte identifier: "SR64" each chunk: 4 byte little endian chunk length n (if 0 this ends the sparse segment) 4 byte little endian chunk offset n bytes data --- Loading a USF or USFlib/miniUSF 1. initialize the ROM and save state to zero. 2. if the USF contains a _lib tag (_libn not supported as of this version) recursively load the specified file starting from step 2 3. load the ROM and save state, replacing any data with the same addresses that may have already been loaded By convention a file that includes a _lib tag is named with a .miniusf extension and a file that is included via a _lib tag is name with a .usflib extension. --- Definition of Project 64 v1.4 save state (DWORD is 4-byte little endian, _int64 is 8-byte little endian) 0x000: DWORD: 0x23D8A6C8, identifier 0x004: DWORD: RDRAM size in bytes 0x008: ROM header, first 0x40 bytes of ROM stored as DWORDs 0x048: DWORD: VI timer (PJ64 internal) 0x04c: DWORD: PC 0x050: 32 _int64: CPU General Purposes Registers 0x150: 32 _int64: Floating Point Registers 0x250: 32 DWORD: COP0 Registers 0x2d0: 32 DWORD: Floating Point Control Registers 0x350: _int64: HI 0x358: _int64: LO 0x360: 10 DWORD: RDRAM Registers 0x388: 10 DWORD: SP Registers 0x3b0: 10 DWORD: DP Registers 0x3d8: 4 DWORD: MI Registers 0x3e8: 14 DWORD: VI Registers 0x420: 6 DWORD: AI Registers 0x438: 13 DWORD: PI Registers 0x46c: 8 DWORD: RI Registers 0x48c: 4 DWORD: SI Registers 0x49c: 32 TLB entries (20 bytes each), see PJ64 source for format 0x71c: PIF RAM, 0x40 bytes stored as DWORDs 0x75c: RDRAM, stored as DWORDs, whatever size specified by 0x004. 0x75c+RDRAM size: 0x1000 bytes RSP DMEM, stored as DWORDs 0x175c+RDRAM size: 0x1000 bytes RSP IMEM, stored as DWORDs Most of these values are relatively straightforward and would be a component of any N64 emulator. --- _enablecompare tag A MIPS processor has an exception triggered when the Count register equals the Compare register. The Count register is always incrementing, and many games that don't even need this register leave it enabled anyway. This causes a slight problem with USFs, because it is possible that this exception will not be triggered during the logging of the USF. This results in USFs that crash many minutes into the track when the exception handler is not found. The initial solution was to disable this exception in 64th Note, but it has since been discovered that several games do require this exception for sound generation. In order to preserve compatibility with the old sets this exception is disabled by default. It can be enabled by including the _enablecompare tag in the affected miniUSF or USFlib (which will affect the entire set). Note that the value of the tag is unimportant, it can be _enablecompare=1, _enablecompare=true, or _enablecompare=false if you want to be confusing. This feature was introduced in 64th Note v0.06. --- _enableFIFOfull tag The FIFO full flag in the AI status register is set when a buffer has been sent and cleared when it is done playing. Some games rely on this behavior, and expect the playback to take a real number of cycles. Initially 64th Note never set the FIFO full flag, but once a game was encountered that needed it this feature was added and it broke some games, so it must be enabled by the individual game. Without this tag 64th Note never sets the FIFO full flag. If this tag is found (regardless of its value, as with _enablecompare) the flag will be set for approximately the playback time of the buffer. This feature was introduced in 64th Note v1.0 beta 23.
