{"id":15649257,"url":"https://github.com/aarant/luvdis","last_synced_at":"2025-12-13T21:02:28.327Z","repository":{"id":62577169,"uuid":"242243923","full_name":"aarant/luvdis","owner":"aarant","description":"Pure-Python Game Boy Advance Disassembler","archived":false,"fork":false,"pushed_at":"2021-06-29T02:03:14.000Z","size":1444,"stargazers_count":40,"open_issues_count":4,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-11-29T20:53:56.036Z","etag":null,"topics":["disassembler","gba","gba-development","python3"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aarant.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-02-21T22:47:03.000Z","updated_at":"2024-10-23T08:45:45.000Z","dependencies_parsed_at":"2022-11-03T19:04:57.685Z","dependency_job_id":null,"html_url":"https://github.com/aarant/luvdis","commit_stats":null,"previous_names":["arantonitis/luvdis"],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aarant%2Fluvdis","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aarant%2Fluvdis/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aarant%2Fluvdis/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aarant%2Fluvdis/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aarant","download_url":"https://codeload.github.com/aarant/luvdis/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227944147,"owners_count":17845152,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["disassembler","gba","gba-development","python3"],"created_at":"2024-10-03T12:29:02.474Z","updated_at":"2025-12-13T21:02:21.878Z","avatar_url":"https://github.com/aarant.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Luvdis\n[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/luvdis?logo=python\u0026style=for-the-badge)](https://www.python.org/downloads/)\n[![PyPI](https://img.shields.io/pypi/v/luvdis?logo=pypi\u0026logoColor=yellow\u0026style=for-the-badge)](https://pypi.org/project/Luvdis/)\n[![GitHub](https://img.shields.io/github/license/arantonitis/luvdis?style=for-the-badge)](https://github.com/arantonitis/luvdis/blob/master/LICENSE)\n![GitHub Workflow Status](https://img.shields.io/github/workflow/status/arantonitis/luvdis/test-build-publish?style=for-the-badge)\n\nA smart Pure-Python GBA (Game Boy Advance) disassembler.\n\nLuvdis is a tool for disassembling GBA ROMs, mostly for the purpose of creating buildable, matching disassemblies.\n\nFeatures include:\n* **Configurable output**: Disassemble to `stdout`, a single file, or separate output into modules based on configuration.\n* **Platform accuracy**: Other disassembly engines like Capstone recognize instructions that are not legal in ARMv4 on the GBA's processor. Luvdis' custom decoder \u0026 disassembler solves this problem by attempting to replicate hardware behavior as closely as possible and only supporting ARMv4.\n* **Function discovery**: Detect likely THUMB functions and differentiate between code and data.\n* **Matching output**: Even if something goes wrong and a label overlaps with data, etc, Luvdis' disassembled output should assemble identically to the original ROM.\n* **ROM detection**: Unsure if you have a good copy of a ROM? Luvdis can let you know with `luvdis info`!\n\n### Contents\n\n- [Installation](#installation)\n   - [From PyPI](#from-pypi)\n   - [From Releases](#from-releases)\n   - [From latest source](#from-latest-source)\n- [Usage](#usage)\n  - [FAQ](#faq)\n  - [Options](#options)\n  - [ROM detection](#rom-detection)\n\n\n## Installation\n\n### From PyPI\nLuvdis requires Python 3.6 or later.\n\n```sh\n$ python3 -m pip install luvdis --user\n```\n\n### From Releases\nArbitrary stable [releases](https://github.com/arantonitis/luvdis/releases/latest) can be downloaded from GitHub and installed:\n```sh\n$ python3 -m pip install \u003cpath-to-zip\u003e --user\n```\n\nFor Windows users, [prebuilt binaries](https://github.com/arantonitis/luvdis/releases/latest) are also available.\n\n### From latest source\n```sh\n$ python3 -m pip install git+git://https://github.com/arantonitis/luvdis#egg=luvdis\n```\n\n## Usage\nThe simplest way to use Luvdis is to simply give it a ROM and output file:\n```sh\n$ luvdis \u003cpath-to-rom\u003e -o rom.s\n```\n\nTo assist in function discovery/labeling, a list of functions can be provided:\n```sh\n$ luvdis -c functions.cfg rom.gba -o rom.s\n```\n\nThis list should have the following structure:\n```\n# '#' starts a comment line.\n# Function names are not mandatory; unknown funcs are named sub_\u003cADDRESS\u003e when output.\narm_func 0x80000D0\nthumb_func 0x800024C AgbMain\n# If 'thumb_func' or 'arm_func' is omitted, the type is assumed to be 'thumb_func'.\n# A module path may also be provided. Each time a new module is encountered, output switches to that path.\n# Omitting the module will continue outputting to the same path.\n0x80003b0 main.s CallCallbacks\n```\n\nTo disassemble only part of a ROM, say, up to the start of read-only data, provide start and stop addresses:\n```sh\n$ luvdis rom.gba --start 0x0800024C --stop 0x0x81b32b4 -o rom.s\n```\n\n### FAQ\n\n#### How can I get rid of large blocks of raw bytes in the disassembly?\n\nBy default, Luvdis treats areas of a ROM that it can't determine are executable as byte data. You can change this behavior\nwith the `default_mode` option:\n\n```sh\n$ luvdis rom.gba --default_mode THUMB -o rom.s\n```\n\n### Options\n\n```\nUsage: luvdis disasm [OPTIONS] ROM\n\n  Analyze and disassemble a GBA ROM.\n\nOptions:\n  --version                   Show the version and exit.\n  -o, --output FILE           Disassembly output path. If configuration\n                              contains module information, this is only the\n                              initial output path.\n  -c, --config FILE           Function configuration file.\n\n  -co, --config-out FILE      Output configuration. If any functions are\n                              'guessed' by Luvdis, they will appear here.\n  -D, --debug                 Turn on/off debugging behavior.\n  --start INTEGER             Starting address to disassemble. Defaults to\n                              0x8000000 (the start of the ROM).\n  --stop INTEGER              Stop disassembly at this address. Defaults to\n                              0x9FFFFFF (maximum ROM address).\n  --macros FILE               Assembler macro file to '.include' in\n                              disassembly. If not specified, default macros\n                              are embedded.\n  --guess / --no-guess        Turn on/off function guessing \u0026 discovery.\n                              Default is to perform guessing.\n  --min-calls INTEGER RANGE   Minimum number of calls to a function required\n                              in order to 'guess' it. Must be at least 1,\n                              defaults to 2.\n  --min-length INTEGER RANGE  Minimum valid instruction length required in\n                              order to 'guess' a function. Must be at least 1,\n                              defaults to 3.\n  --default-mode [THUMB|BYTE|WORD]\n                              Default disassembly mode when the nature of\n                              an address is unknown. Defaults to 'BYTE'.\n  --help                      Show this message and exit.\n```\n\n### ROM Detection\nTo display information about a ROM and check if its hash is in the database:\n```\n$ luvdis info unknown_rom.gba\nROM detected: 'Pocket Monsters - Ruby (Japan)' ✔\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faarant%2Fluvdis","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faarant%2Fluvdis","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faarant%2Fluvdis/lists"}