Pure-Python Game Boy Advance Disassembler
Project description
Luvdis
A smart Pure-Python GBA (Game Boy Advance) disassembler.
Luvdis is a tool for disassembling GBA ROMs. Features include:
- Configurable output: Disassemble to
stdout
, a single file, or separate output into modules based on configuration. - Platform accuracy: Other disassembly engines like Capstone recognize instructions that are not legal in ARMv4 on the GBA's processor. Luvdis' custom decoder & disassembler solves this problem by attempting to replicate hardware behavior as closely as possible and only supporting ARMv4.
- Function discovery: Detect likely THUMB functions and differentiate between code and data.
- Matching output: Even if something goes wrong and a label overlaps with data, etc, Luvdis' disassembled output should assemble identically to the original ROM.
- ROM detection: Unsure if you have a good copy of a ROM? Luvdis can let you know with
luvdis info
!
Contents
Installation
From PyPI
Luvdis requires Python 3.6 or later.
$ python3 -m pip install luvdis --user
From Releases
Arbitrary stable releases can be downloaded from GitHub and installed:
$ python3 -m pip install <path-to-zip> --user
For Windows users, prebuilt binaries are also available.
From latest source
$ python3 -m pip install git+git://https://github.com/arantonitis/luvdis#egg=luvdis
Usage
The simplest way to use Luvdis is to simply give it a ROM and output file:
$ luvdis <path-to-rom> -o rom.s
To assist in function discovery/labeling, a list of functions can be provided:
$ luvdis -c functions.cfg rom.gba -o rom.s
This list should have the following structure:
# '#' starts a comment line.
# Function names are not mandatory; unknown funcs are named sub_<ADDRESS> when output.
arm_func 0x80000D0
thumb_func 0x800024C AgbMain
# If 'thumb_func' or 'arm_func' is omitted, the type is assumed to be 'thumb_func'.
# A module path may also be provided. Each time a new module is encountered, output switches to that path.
# Omitting the module will continue outputting to the same path.
0x80003b0 main.s CallCallbacks
To disassemble only part of a ROM, say, up to the start of read-only data, provide start and stop addresses:
$ luvdis rom.gba --start 0x0800024C --stop 0x0x81b32b4 -o rom.s
FAQ
How can I get rid of large blocks of raw bytes in the disassembly?
By default, Luvdis treats areas of a ROM that it can't determine are executable as byte data. You can change this behavior
with the default_mode
option:
$ luvdis rom.gba --default_mode THUMB -o rom.s
Options
Usage: luvdis disasm [OPTIONS] ROM
Analyze and disassemble a GBA ROM.
Options:
--version Show the version and exit.
-o, --output FILE Disassembly output path. If configuration
contains module information, this is only the
initial output path.
-c, --config FILE Function configuration file.
-co, --config-out FILE Output configuration. If any functions are
'guessed' by Luvdis, they will appear here.
-D, --debug Turn on/off debugging behavior.
--start INTEGER Starting address to disassemble. Defaults to
0x8000000 (the start of the ROM).
--stop INTEGER Stop disassembly at this address. Defaults to
0x9FFFFFF (maximum ROM address).
--macros FILE Assembler macro file to '.include' in
disassembly. If not specified, default macros
are embedded.
--guess / --no-guess Turn on/off function guessing & discovery.
Default is to perform guessing.
--min-calls INTEGER RANGE Minimum number of calls to a function required
in order to 'guess' it. Must be at least 1,
defaults to 2.
--min-length INTEGER RANGE Minimum valid instruction length required in
order to 'guess' a function. Must be at least 1,
defaults to 3.
--default-mode [THUMB|BYTE|WORD]
Default disassembly mode when the nature of
an address is unknown. Defaults to 'BYTE'.
--help Show this message and exit.
ROM Detection
To display information about a ROM and check if its hash is in the database:
$ luvdis info unknown_rom.gba
ROM detected: 'Pocket Monsters - Ruby (Japan)' ✔
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file Luvdis-0.8.0.tar.gz
.
File metadata
- Download URL: Luvdis-0.8.0.tar.gz
- Upload date:
- Size: 304.0 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/3.2.0 pkginfo/1.6.1 requests/2.24.0 setuptools/49.2.1 requests-toolbelt/0.9.1 tqdm/4.51.0 CPython/3.9.0
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5df5e7754d4231ce2daf3d2462a1bf8cdc9159537b428abfc524dcc86e0d743d |
|
MD5 | a3ba4a51fb43035b3aa87fd1039322d3 |
|
BLAKE2b-256 | 722332c3313f9378d9a9529dcbd7cfdc40fc861dd6c8ba2c48efe7a2c421abf7 |
File details
Details for the file Luvdis-0.8.0-py3-none-any.whl
.
File metadata
- Download URL: Luvdis-0.8.0-py3-none-any.whl
- Upload date:
- Size: 306.7 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/3.2.0 pkginfo/1.6.1 requests/2.24.0 setuptools/49.2.1 requests-toolbelt/0.9.1 tqdm/4.51.0 CPython/3.9.0
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | ed9a7499a39a3c4a528ff4d4ec9b147ecc7bed9d629e4de99a2bc57c727d2f57 |
|
MD5 | ea4e7cac0921e0b798f1f3ef35fde014 |
|
BLAKE2b-256 | cbba110bb2795f8a389e6a5d6fab3b0b2b6eb9fbe4bf303461a9df20d216613c |