Note: This utility is now included in GBDK-2020 (version 4.3.0+), so you may already have a copy if you're using that dev kit.
- Releases: See the Releases section to the right
A small command line tool for estimating usage (free space) of Game Boy ROMs (+ Mega Duck, Analogue .pocket, Game Gear, SMS) from the following file types:
- .map (sdcc, rgbds)
- .noi (sdcc)
- .ihx (sdcc)
- .cdb (sdcc)
- .gb / .gbc / .pocket / .duck (ROM image file for: Game Boy / Color, Analogue Pocket, Mega Duck / Cougar Boy)
- .gg / .sms (ROM image file for: Game Gear / Sega Master System. Note: SMS/GG is GBDK-2020 specific)
It produces a trimmed, sorted output of ROM/RAMs, their usage and optionally the Areas located in them.
Runs on Linux, Windows and MacOS, it can be used with GBDK 2020, ZGB v2020+ and RGBDS. If map or noi file output is not already enabled, use either -debug with lcc or -m with sdldgb directly.
Examples of color output. -sRe with -sRp for percentage based color on row ends with -g small graphs. -sRd for section based color with center columns dimmed.
romusage input_file.[map|noi|ihx|cdb|.gb[c]|.pocket|.duck|.gg|.sms] [options]
version 1.2.9, by bbbbbr
Options
-h : Show this help
-p:SMS_GG : Set platform to GBDK SMS/Game Gear (changes memory map templates)
-a : Show Areas in each Bank. Optional sort by, address:"-aA" or size:"-aS"
-g : Show a small usage graph per bank (-gA for ascii style)
-G : Show a large usage graph per bank (-GA for ascii style)
-B : Brief (summarized) output for banked regions. Auto scales max bank
shows [Region]_[Max Used Bank] / [auto-sized Max Bank Num]
-F : Force Max ROM and SRAM bank num for -B. (0 based) -F:ROM:SRAM (ex: -F:255:15)
-m : Manually specify an Area -m:NAME:HEXADDR:HEXLENGTH
-e : Manually specify an Area that should not overlap -e:NAME:HEXADDR:HEXLENGTH
-E : All areas are exclusive (except HEADERs), warn for any overlaps
-q : Quiet, no output except warnings and errors
-Q : Suppress output of warnings and errors
-R : Return error code for Area warnings and errors
-sR : [Rainbow] Color output (-sRe for Row Ends, -sRd for Center Dimmed, -sRp % based)
-sP : Custom Color Palette. Colon separated entries are decimal VT100 color codes
-sP:DEFAULT:ROM:VRAM:SRAM:WRAM:HRAM (section based color only)
-sC : Show Compact Output, hide non-essential columns
-sH : Show HEADER Areas (normally hidden)
-smROM : Show Merged ROM_0 and ROM_1 output (i.e. bare 32K ROM)
-smWRAM : Show Merged WRAM_0 and WRAM_1 output (i.e DMG/MGB not CGB)
-sm* compatible with banked ROM_x or WRAM_x when used with -B
-sJ : Show JSON output. Some options not applicable. When used, -Q recommended
-nB : Hide warning banner (for .cdb output)
-nA : Hide areas (shown by default in .cdb output)
-z : Hide areas smaller than SIZE -z:DECSIZE
-nMEM : Hide banks matching case sensitive substring (ex hide all RAM: -nMEM:RAM)
Use: Read a .map, .noi, .cdb or .ihx file to display area sizes
Example 1: "romusage build/MyProject.map"
Example 2: "romusage build/MyProject.noi -a -e:STACK:DEFF:100 -e:SHADOW_OAM:C000:A0"
Example 3: "romusage build/MyProject.ihx -g"
Example 4: "romusage build/MyProject.map -q -R"
Example 5: "romusage build/MyProject.noi -sR -sP:90:32:90:35:33:36"
Example 6: "romusage build/MyProject.map -sRp -g -B -F:255:15 -smROM -smWRAM"
Notes:
* GBDK / RGBDS map file format detection is automatic.
* Estimates are as close as possible, but may not be complete.
Unless specified with -m/-e they *do not* factor regions lacking
complete ranges in the Map/Noi/Ihx file, for example Shadow OAM and Stack.
* IHX files can only detect overlaps, not detect memory region overflows.
* CDB file output ONLY counts (most) data from C sources.
It cannot count functions and data from ASM and LIBs,
so bank totals may be incorrect/missing.
* GB/GBC/ROM files are just guessing, no promises.
The usage calculation will attempt to merge overlapping areas to avoid counting shared space multiple times (such as HEADER areas). Optionally it can warn of overlap in exclusive areas, such as the Stack.
IHX Files:
- For .ihx files bank overflow can only be guessed at (aside from duplicate writes). It's often not possible to tell the difference two banks with data that perfectly aligns on a shared boundary and a single bank that spills over into the unused area of a following bank. It's better to use .map and .noi files to check for overflow.
- Due to their nature, RAM estimates are unavailable with .ihx files
CDB Files:
- To enable .cdb output use the additional debug flags
-Wl-ywithlccor-ywithsdldgbdirectly. - For .cdb files the calculated output ONLY reports (most) data from C source files. It cannot count functions and data from ASM sources and LIBs, so bank totals may be incorrect/missing. It's main use is finding the size of individual functions and variables (what's using up space), not estimating the free/used space of banks.
ROM Files (.gb / .gbc / .pocket / .duck / gg / sms) :
- No overflow detection
- Usage estimates can only attempt to distinguish between "empty space" (0xFF's) and data that looks like empty space (0xFF's). It may be inaccurate.
Example output with a small graph (-g) for a 32k non-banked ROM, called after completion of the link stage. Manually specify Shadow OAM and Stack as exclusive ranges (-e). Reading from the .map file.
$ romusage.exe /ReleaseColor/Petris.map -g -e:STACK:DEFF:100 -e:SHADOW_OAM:C000:A0
Bank Range Size Used Used% Free Free%
---------- ---------------- ----- ----- ----- ----- -----
ROM 0x0000 -> 0x3FFF 16384 15989 97% 395 2% |-###########################|
ROM_0 0x4000 -> 0x7FFF 16384 12843 78% 3541 21% |#####################-......|
WRAM 0xC000 -> 0xCFFF 4096 4096 100% 0 0% |############################|
WRAM_1_0 0xD000 -> 0xDFFF 4096 2150 52% 1946 47% |#############.............-#|
Example of quiet mode (-q) that just reports errors and warnings, and can return an error on exit (-R) if any are present.
romusage banks.map -R -q
* WARNING: Area _DATA at c0a0 -> 115a4 extends past end of address space at ffff (Underflow error by 5541 bytes)
* WARNING: Area _DATA at c0a0 -> 115a4 extends past end of memory region at dfff (Overflow by 13733 bytes)
* WARNING: Area _CODE_1 at 14000 -> 1c023 extends past end of memory region at 17fff (Overflow by 16420 bytes)
* WARNING: Area _CODE_12 at c4000 -> c801f extends past end of memory region at c7fff (Overflow by 32 bytes)
And another example, with display of areas in the banks enabled. Reading from the .noi file.
romusage gbdk/examples/gb/new_banks.noi -a
Bank Range Size Used Used% Free Free%
---------- ---------------- ----- ----- ----- ----- -----
ROM 0x0000 -> 0x3FFF 16384 8211 50% 8173 49%
|
+_CODE 0x0200 -> 0x111A 3867
+_HOME 0x111B -> 0x1286 364
+_BASE 0x1287 -> 0x20F2 3692
+_GSINIT 0x20F3 -> 0x219C 170
+_GSINITTAIL 0x219D -> 0x219D 1
ROM_1 0x4000 -> 0x7FFF 16384 19 0% 16365 99%
|
+_CODE_1 0x4000 -> 0x4012 19
ROM_2 0x4000 -> 0x7FFF 16384 19 0% 16365 99%
|
+_CODE_2 0x4000 -> 0x4012 19
XRAM_1 0xA000 -> 0xBFFF 8192 22 0% 8170 99%
|
+_DATA_1 0xA000 -> 0xA015 22
XRAM_2 0xA000 -> 0xBFFF 8192 28 0% 8164 99%
|
+_DATA_2 0xA000 -> 0xA01B 28
WRAM 0xC000 -> 0xCFFF 4096 102 2% 3994 97%
|
+_DATA 0xC0A0 -> 0xC0B5 22
+_BSS 0xC0B6 -> 0xC105 80
What's taking up space? Example of .cdb file output showing which functions and variables area larger than 500 bytes (-z:500), with cdb banner noticed suppressed (-nB).
$ romusage Petris_Debug.cdb -z:500 -nB
Bank Range Size Used Used% Free Free%
---------- ---------------- ----- ----- ----- ----- -----
ROM 0x0000 -> 0x3FFF 16384 16383 99% 1 0%
|
| Name Start -> End Size
| --------------------- ---------------- -----
+ -?- 0x1E32 -> 0x2937 2822
+ intro_screen_tiles 0x0FB0 -> 0x145F 1200
+ twilight_drive_mod 0x15A2 -> 0x1909 872
+ font_tiles 0x06D0 -> 0x099F 720
+ pet_tiles 0x0A50 -> 0x0CDF 656
+ freeost_charselect_mod 0x1BE7 -> 0x1E31 587
+ villainsofhiphop_mod 0x1924 -> 0x1B5C 569
+ -?- 0x0001 -> 0x01FF 511
+ (102 items < 500 hidden = 8446 total bytes)
ROM_0 0x4000 -> 0x7FFF 16384 11001 67% 5383 32%
|
| Name Start -> End Size
| --------------------- ---------------- -----
+ board_check_completed_pet_xy 0x65DB -> 0x6843 617
+ hinting_petlength_add 0x5807 -> 0x59FB 501
+ (106 items < 500 hidden = 9883 total bytes)
WRAM 0xC000 -> 0xCFFF 4096 4095 99% 1 0%
|
| Name Start -> End Size
| --------------------- ---------------- -----
+ music_decompressed 0xC0ED -> 0xCD08 3100
+ (16 items < 500 hidden = 995 total bytes)
WRAM_1_0 0xD000 -> 0xDFFF 4096 1827 44% 2269 55%
|
| Name Start -> End Size
| --------------------- ---------------- -----
+ (24 items < 500 hidden = 1827 total bytes)
Example output with a large graph (-G) for a 32k non-banked ROM, called after completion of the link stage. Manually specify Shadow OAM and Stack as exclusive ranges (-e). Reading from the .map file.
$ romusage.exe /ReleaseColor/Petris.map -G -e:STACK:DEFF:100 -e:SHADOW_OAM:C000:A0
Bank Range Size Used Used% Free Free%
---------- ---------------- ----- ----- ----- ----- -----
ROM 0x0000 -> 0x3FFF 16384 15989 97% 395 2%
ROM_0 0x4000 -> 0x7FFF 16384 12843 78% 3541 21%
WRAM 0xC000 -> 0xCFFF 4096 4096 100% 0 0%
WRAM_1_0 0xD000 -> 0xDFFF 4096 2150 52% 1946 47%
Start: ROM 0x0000 -> 0x3FFF
#######-........................################################
################################################################
################################################################
################################################################
################################################################
################################################################
################################################################
################################################################
################################################################
################################################################
################################################################
################################################################
################################################################
################################################################
################################################################
################################################################
End: ROM
Start: ROM_0 0x4000 -> 0x7FFF
################################################################
################################################################
################################################################
################################################################
################################################################
################################################################
################################################################
################################################################
################################################################
################################################################
################################################################
################################################################
##################################-.............................
................................................................
................................................................
................................................................
End: ROM_0
Start: WRAM 0xC000 -> 0xCFFF
################################################################
################################################################
################################################################
################################################################
End: WRAM
Start: WRAM_1_0 0xD000 -> 0xDFFF
################################################################
######################################################-.........
................................................................
................................................################
End: WRAM_1_0