Skip to main content

Pure-Python Game Boy Advance Disassembler

Project description

Luvdis

PyPI - Python Version PyPI GitHub

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


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

Luvdis-0.8.0.tar.gz (304.0 kB view details)

Uploaded Source

Built Distribution

Luvdis-0.8.0-py3-none-any.whl (306.7 kB view details)

Uploaded Python 3

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

Hashes for Luvdis-0.8.0.tar.gz
Algorithm Hash digest
SHA256 5df5e7754d4231ce2daf3d2462a1bf8cdc9159537b428abfc524dcc86e0d743d
MD5 a3ba4a51fb43035b3aa87fd1039322d3
BLAKE2b-256 722332c3313f9378d9a9529dcbd7cfdc40fc861dd6c8ba2c48efe7a2c421abf7

See more details on using hashes here.

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

Hashes for Luvdis-0.8.0-py3-none-any.whl
Algorithm Hash digest
SHA256 ed9a7499a39a3c4a528ff4d4ec9b147ecc7bed9d629e4de99a2bc57c727d2f57
MD5 ea4e7cac0921e0b798f1f3ef35fde014
BLAKE2b-256 cbba110bb2795f8a389e6a5d6fab3b0b2b6eb9fbe4bf303461a9df20d216613c

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page