Revision (current)
Last Updated by zeromus on 12/4/2020 8:39 PM
!! Backgrounder
Currently supported for: PCE, GB/GBC, SMS/GG, Genesis, SNES
The CodeData (CD) Logger primarily tracks information for each byte in the ROM about how it's used by the game program: the most useful distinction is between code and data, but in some cases more fine-grained information is useful. This data is helpful for reverse engineering games, so that automated disassembly tools can produce .db tables for stuff known to be data, and disassemble stuff known to be code. Typically you will want to turn on the CD logger and play through as much of the game as possible, to trigger reading of every level, script, sound, and art, to get the coverage as near to 100% as you can.
!! File Format
! Type definitions
* A "string" is an LEB128 encoded number which is the number of bytes in the string, followed by that many bytes of UTF-8 character data.
* A "number" is a little endian 32 bit integer.
! File Format
Header:
* string id: file identifier, always "BIZHAWK-CDL-2"
* string sub-id: a string, padded at the end to a length of 15 with spaces, saying which platform the CDL file is for: PCE or GB
* number sub-version: another version number, in case the console-specifics change but not the overall format
* number NumberOfBlocks: number of memory areas represented in this file
For each block:
* string BlockName: identifying name of the block. These usually (but not always) follow the naming of a corresponding MemoryDomain. In the future we'll try to normalize these more.
* number bytelength: length of the block in bytes.
* byte data(bytelength): one byte of information for each byte in the original block.
! PCE
The PCE implementation is pretty complex due to the diversity of memory mapping options and the general thoroughness with which the CD logger has been designed. This core supports disassembling from the CD logger. Only the PCE implementation currently tracks writes (the remainder track only reads)
For PCE, the BlockNames are:
ROM
HUCard ROM, or syscard bios ROm
Cart Battery RAM
32K of battery backed ram in the Populous cart
Super System Card RAM
192K of ram in the super system card
TurboCD RAM
64K of ram in the turboCD
BRAM
8K of TurboCD backup RAM. The actual RAM is smaller, but the CDL will record all
activity in that 8K region.
Main Memory
8K or 32K (SGX) of main memory
MMIO
8K of space in block ff, containing system IO ports.
UNKNOWN
8K long area which any unknown block maps to.
Each byte has 8 bits of flags on what the byte has been observed to do:
// was fetched as an opcode
Code = 0x01,
// was read or written as data
Data = 0x02,
// was read and used as a pointer to data via indirect addressing
DataPtr = 0x04,
// was read or written as stack
Stack = 0x08,
// was read or written as data via indirect addressing
IndirectData = 0x10,
// was read and used as function pointer
// NB: there is no "IndirectCode"; all code is marked simply as code regardless of how it is reached
FcnPtr = 0x20,
// was used as a source or destination (either initial or during the loop) of a block xfer
BlockXFer = 0x40,
// was fetched as an operand byte to an opcode
CodeOperand = 0x80
! GB (gambatte)
CartRAM may or may not be present. Of course CartRAM may vary in size (and WRAM will depend on gb/gbc type)
Blocknames: ROM, CartRAM, WRAM, HRAM
Flags:
ExecFirst = 0x01
ExecOperand = 0x02
Data = 0x04
! GBHawk
CartRAM may or may not be present. Of course CartRAM may vary in size (and WRAM will depend on gb/gbc type)
Blocknames: ROM, CartRAM, WRAM, HRAM (note: these do not match the memory domain names)
Flags:
ExecFirst = 0x01
ExecOperand = 0x02
Data = 0x04
Write = 0x08 (this is used to distinguish data writes from data reads)
! Genesis
SRAM may or may not be present. I suppose it may vary in size. MD Cart will vary in size, of course. All the Sega CD stuff hasn't been analyzed yet.
Blocknames: MD Cart, 68K RAM, Z80 RAM, SRAM
Flags:
Exec68k = 0x01
Data68k = 0x04
ExecZ80First = 0x08
ExecZ80Operand = 0x10
DataZ80 = 0x20
DMASource = 0x40 -- Should be useful for identifying the origin of graphics data on the cart ROM.
! SMS/GG
Save RAM and Cart (Volatile) RAM may or may not be present, and most of it may vary in size.
Blocknames: ROM, Main RAM, Save RAM, Cart (Volatile) RAM
Flags:
ExecFirst = 0x01
ExecOperand = 0x02
Data = 0x04
! SNES
CARTRAM may be variable. APURAM is full 64KB despite some of the space being mapped to registers. The Exec* and CPUData flags are set for the S-CPU and SMP both. Since each CPU can only access its respective memories, there are no conflicts.
Blocknames: CARTROM, CARTRAM, WRAM, APURAM, SGB_CARTROM, SGB_CARTRAM, SGB_WRAM, SGB_HRAM
Flags:
ExecFirst = 0x01 //initial CPU instruction operand
ExecOperand = 0x02 //subsequent CPU instruction operands
CPUData = 0x04 //data was read by CPU instruction
DMAData = 0x08 //data was read by DMA
BRR = 0x80 //for SMP, data was read by DSP sampledata loading
CPUXFlag = 0x10 //for S-CPU along with ExecFirst and ExecOperand...
CPUMFlag = 0x20 //...these indicate whether the X and M flag were set at the time.
Additional blocknames: CARTROM-D, CARTROM-DB - for advanced users, these are word- and byte-sized mirrors of the CARTROM address space which contain the most recent D and DB registers when the CARTROM was accessed (word is little endian)
! NES
Use FCEUX