Convert Asset Array

Asset_56910 gCourseDataAssets[] = {
    { (void *)&_224420_ROM_START, (void *)&_224420_ROM_END, 0x000024A8 },
    { (void *)&_23CB80_ROM_START, (void *)&_23CB80_ROM_END, 0x00003468 },
    // ...
};

How to use

Identify the array to convert

Look for arrays of type Asset_56910 or similar asset structures in src/data/course_data.c or other data files.

Extract the pattern

For each array entry, extract:

• Start address (first pointer value)
• End address (second pointer value)
• Size field (third value, typically ignored for ROM_START/ROM_END)

Step 1: Add USE_ASSET declarations

In include/assets.h, add USE_ASSET declarations for each unique start address:

USE_ASSET(_224420);
USE_ASSET(_23CB80);
USE_ASSET(_24D6C0);
// ... etc, sorted numerically

Step 2: Update the array initialization

Convert the array entries from:

{ (void *)0x00224420, (void *)0x00226BA0, 0x000024A8 }

To:

{ (void *)&_224420_ROM_START, (void *)&_224420_ROM_END, 0x000024A8 }

The pattern is:

• Remove leading 0x and 00 prefixes from addresses
• Replace (void *)0xADDRESS with (void *)&_ADDRESS_ROM_START or _ROM_END
• Keep the size field unchanged

Step 3: Update snowboardkids2.yaml

For each asset segment:

1. Find the location - Search for the address in the YAML:

   grep -n "0x224420\|0x226BA0" snowboardkids2.yaml
   

2. Add or convert segments - If you see:

   • [0x224420, bin] alone → Convert to named segment:

     - name: _224420
       type: bin
       vram: 0
       start: 0x224420
     

   • Named segment without end marker → Add end marker:

     - name: _224420
       type: bin
       vram: 0
       start: 0x224420
     
     - [0x226BA0, bin]  # This marks where _224420 ENDS
     

3. Maintain proper ordering - Ensure segments are in ascending address order:

   • Named segment definition
   • End marker (next segment's start)
   • Next named segment

Example structure:

- name: _224420
  type: bin
  vram: 0
  start: 0x224420

- [0x226BA0, bin]  # End marker for _224420, also marks start of next

- name: _23CB80
  type: bin
  vram: 0
  start: 0x23CB80

- [0x240520, bin]  # End marker for _23CB80

Step 4: Validate

Build and verify:

./tools/build-and-verify.sh

Watch for errors:

• Segment XXXXX has zero size - End marker followed by named segment at same address (remove redundant end marker)
• Segments out of order - YAML entries not in ascending address order
• Missing USE_ASSET - Undefined ROM_START/ROM_END symbols
• Wrong segment size - End marker at wrong address causing data mismatch
• Checksum mismatch - Use data_diff.py --find-first-mismatch to find the problematic symbol

Common Patterns

Pattern 1: Single address used by multiple entries

Why: Multiple array entries may reference the same asset (duplicates share data).

Pattern 2: Asset marker already exists as [0xADDRESS, bin]

If multiple array entries use the same start/end addresses (common for duplicate assets), only declare the asset once:

// Both entries 15 and 16 use the same addresses
{ (void *)&_34A2C0_ROM_START, (void *)&_34A2C0_ROM_END, 0x00000438 },
{ (void *)&_34A2C0_ROM_START, (void *)&_34A2C0_ROM_END, 0x00000438 },

Pattern 2: Asset marker already exists as [0xADDRESS, bin]

When you see [0x226BA0, bin] in the YAML:

1. Add a named segment BEFORE it:

   - name: _224420
     type: bin
     vram: 0
     start: 0x224420
   
   - [0x226BA0, bin]  # End of _224420
   

2. Convert the marker to a named segment with its own end marker:

   - name: _226BA0
     type: bin
     vram: 0
     start: 0x226BA0
   
   - [0x228400, bin]  # End of _226BA0
   

Pattern 3: Redundant end markers

WRONG: End marker followed by named segment at same address:

- name: _226BA0
  type: bin
  vram: 0
  start: 0x226BA0

- [0x228400, bin]        # REDUNDANT! _228400 starts at same address

- name: _228400
  type: bin
  vram: 0
  start: 0x228400

CORRECT: Named segment serves as boundary:

- name: _226BA0
  type: bin
  vram: 0
  start: 0x226BA0

- name: _228400          # Ends _226BA0, starts at 0x228400
  type: bin
  vram: 0
  start: 0x228400

When explicit end markers ARE needed:

• When there's a gap before the next named segment
• When the next "segment" is just an address marker without data
• When you need precise control over where a USE_ASSET segment ends

Quick Reference Commands

# Check if asset exists
grep "_224420:" snowboardkids2.yaml

# Find all uses of an address
grep -r "0x00224420" src/

# Validate segment order
python3 -m splat split snowboardkids2.yaml

# Build and verify
./tools/build-and-verify.sh

# Check data mismatches
python3 tools/data-differ/data_diff.py gSpriteAssets

# Find first mismatching data symbol
python3 tools/data-differ/data_diff.py --find-first-mismatch

Debugging and Troubleshooting

Zero-size segment errors

Error: Segment 228400 has zero size.

Cause: Having both an end marker [0xADDRESS, bin] AND a named segment starting at the same address creates a zero-size segment.

# WRONG - Creates zero-size segment:
- [0x228400, bin]        # End marker for _226BA0

- name: _228400          # Named segment at SAME address
  type: bin
  vram: 0
  start: 0x228400

Fix: Remove the redundant end marker when a named segment exists at that address:

# CORRECT - Named segment serves as boundary:
- name: _228400
  type: bin
  vram: 0
  start: 0x228400

Why: A named segment automatically marks the end of the previous segment. The previous segment (_226BA0 in this case) ends where _228400 starts.

Understanding segment boundaries

Key principle: Named segments automatically end where the next segment starts.

- name: _226BA0
  type: bin
  vram: 0
  start: 0x226BA0
  # Automatically ends at 0x228400 (where _228400 starts)

- name: _228400
  type: bin
  vram: 0
  start: 0x228400
  # Automatically ends at 0x23CB80 (where _23CB80 starts)

- name: _23CB80
  type: bin
  vram: 0
  start: 0x23CB80

When to use explicit end markers:

• When there's a gap between segments (unused ROM space)
• When you need to end a segment at an address that doesn't have a named segment
• When a segment is used but doesn't need a named segment in the YAML

# Example with explicit end marker:
- name: _34A2C0
  type: bin
  vram: 0
  start: 0x34A2C0

- [0x34A750, bin]      # Explicit end marker - _34A2C0 ends here

- name: _34CB50        # Gap from 0x34A750 to 0x34CB50
  type: bin
  vram: 0
  start: 0x34CB50

Finding all redundant end markers

When debugging zero-size segment errors, use this Python script to find all redundant end markers:

import re

with open('snowboardkids2.yaml', 'r') as f:
    lines = f.readlines()

for i in range(len(lines) - 1):
    end_match = re.match(r'\s*-\s*\[0x([0-9A-Fa-f]+),\s*bin\]', lines[i])
    if end_match:
        end_addr = end_match.group(1).upper()
        for j in range(i+1, min(i+5, len(lines))):
            name_match = re.match(r'\s*-\s*name:\s*_' + end_addr + r'\b', lines[j])
            if name_match:
                print(f"Line {i+1}: [0x{end_addr}, bin] followed by name: _{end_addr} at line {j+1}")
                break

Common YAML structure mistakes

1. End marker followed by named segment at same address → Remove end marker
2. Named segment with no end marker when needed → Add [0xEND_ADDRESS, bin]
3. Segments out of ascending address order → Reorder segments
4. Missing USE_ASSET declaration → Add to include/assets.h

Only create named segments for addresses used with ROM symbols

Before adding a named segment to the YAML, verify the address is actually used with ROM_START/ROM_END symbols:

# Check if address is used with ROM symbols
grep -r "_228400_ROM" src/ include/

If the address is only used as a hardcoded pointer (e.g., { (void *)0x00228400, ... }), you typically don't need a named segment. An end marker is sufficient:

# If _228400 is only used as hardcoded pointer:
- [0x228400, bin]        # Just marks end of previous segment

# If _228400 is used with ROM symbols:
- name: _228400          # Needed for USE_ASSET(_228400)
  type: bin
  vram: 0
  start: 0x228400

Exception: You may need a named segment even if not currently using ROM symbols, if you plan to convert the code later.

Data mismatch debugging

If the build fails with checksum mismatch:

1. Find the first mismatching symbol:

   python3 tools/data-differ/data_diff.py --find-first-mismatch
   

2. Examine the byte differences to understand which addresses are wrong

3. Check the YAML segments around those addresses:

   grep -n "0xADDRESS" snowboardkids2.yaml
   

4. Verify:

   • Named segments exist for all used addresses
   • End markers are at correct addresses
   • No zero-size segments
   • Segments are in ascending order

Example: Converting gSpriteAssets

Original array:

Asset_56910 gSpriteAssets[] = {
    { (void *)0x00226BA0, (void *)0x00228400, 0x00002208 },
    { (void *)0x00240520, (void *)0x002415B0, 0x00001BA8 },
    // ... 14 more entries
};

After conversion:

Asset_56910 gSpriteAssets[] = {
    { (void *)&_226BA0_ROM_START, (void *)&_226BA0_ROM_END, 0x00002208 },
    { (void *)&_240520_ROM_START, (void *)&_240520_ROM_END, 0x00001BA8 },
    // ... 14 more entries
};

With YAML segments:

- name: _226BA0
  type: bin
  vram: 0
  start: 0x226BA0

- [0x228400, bin]

- name: _240520
  type: bin
  vram: 0
  start: 0x240520

- [0x2415B0, bin]