Aira Force
==========

Advanced/Amiga Interactive ReAssembler. For reverse engineering Amiga 680x0
software.

The primary goal of this project is to provide a graphical user
interface to accelerate the iterative reverse-engineering workflow.

Aira Force implements "reassembly" using the Ira disassembler and the VASM
assembler.

First ira transforms the source executable or raw binary into
assembly language source code, then vasm assembles the source code. The output
binary should be identical (or equivalent) to the input binary.

This allows the user to analyse and annotate the source code
efficiently, before make any required changes to the generated
disassembly and building a patched binary. It may be useful for fixing
bugs, adding features, optimising the code, or academic software
archeology.

Features:
- Disassemble Amiga executables (hunk Load Modules)
- Disassemble raw Amiga binaries, e.g. bootblocks, non-DOS programs
- Interactively convert disassembly to code, data or text
- Efficient code navigation
- Menu and keyboard driven UI
- Runs on Windows, Linux and macOS (sorry, no Amiga version)
- Rename and add labels
- Add comments and banners
- Define pointers and equates
- Search for potential pointers, equates and code
- Hex viewer
- Reassemble disassembled code and compare against source
- Dockable windows and multi-viewports (native OS windows) with Dear
    ImGui


Installing
----------

Prerequisites: OpenGL 3 drivers are required to run.

Windows: Extract the zip file to a folder and run AiraForce.exe
Mac: Mount the DMG and drag the application icon into appliations
Linux: Extract the archive or install the .deb file


Usage
-----

Familiarity with the command line ira tool is not essential, but may be
beneficial in understanding the workflow and terminology. The reader is
referred to ira2.doc and ira_config.doc in the ira release archive, 
available on Aminet.

Essentially, Aira Force aims to remove the need for the user to manually
modify the ira config (.cnf) file that guides the disassembler.

The high level interactive disassembly workflow is as follows:

-   Use File > New Disassembly... to begin analysis of a new binary
-   Use File > Continue Disassembly... with to load a previously disassembled
    binary
-   Check the output window for any errors or warnings
-   Identify code, data and text areas
-   Identify missing labels required to allow the code to be reassembled
    correctly
-   Rename labels and and comments to aid user code analysis
-   Use the Actions window to help identify pointers and equates
    e.g. system calls and custom hardware registers
-   Use the final disassembly as required e.g. to fix bugs, add features
    or optimise

The GUI is implemented using the Dear ImGui docking branch. This allows
ImGui windows be docked within the primary native window, and also
transformed into native OS windows just by dragging out of the main
window. For an overview please read the Dear ImGui documentation: -
Dockable windows - Multi-viewports


Common keyboard shortcuts
=========================

Most actions are performed in the disassembly window using the main
menu, the right-click context menu or keyboard shortcuts.

Keyboard shortcuts can be found by looking in the main menu. Here are
some of the most commonly used commands:

-----------------------------------------------------------------------
Shortcut                            Action
----------------------------------- -----------------------------------
Up                                  Select previous line
Down                                Select next line
Page Up                             Move up one page
Page Down                           Move down one page
G                                   Goto (context sensitive)
Ctrl+G                              Goto address/symbol/line
Left                                Navigate backwards
Right                               Navigate forwards
C                                   Convert to Code
D                                   Convert to Data
T                                   Convert to Text
R                                   Rename label
L                                   Add label
;                                   Add comment above selected line
                                    (lines can have multiple comments)
F2                                  Edit comment on selected line
B                                   Add banner
P                                   Define pointer
E                                   Define equate
Delete                              Delete label/comment/banner/pointer
                                    (context sensitive)
Esc                                 Close dialogue popup
Ctrl+F                              Find
Ctrl+Tab                            Switch window
-----------------------------------------------------------------------

Command line options
====================

-----------------------------------------------------------------------
Option(s)                            Action
-----------------------------------------------------------------------
–help                               Show usage

–log-level                          Specify log level: 
                                    2 (trace)
                                    1 (debug)
                                    0 (info)
                                    -1 (warn)
                                    -2 (error)
                                    -3 (none)
                                    Default: 0 (info)

-d --display-index                  Window display (monitor) index
                                    Default = 0 (primary)

-w –window-width                    Window width. Default: 1920
-h –window-height                   Window height. Default: 1080
-w --window-width                   Window width. Default: 75% display
-h --window-height                  Window height. Default: 75% display
-m --maximised                      Window maximised. Default: false
-f –fullscreen                      Full screen
-ignore-ini-file                    Don't load AiraForceOptions.ini
-----------------------------------------------------------------------


Configuration
=============

Two ini files are saved and loaded by the application:

1. AiraForceOptions.ini contains application-specific options
2. imgui.ini contains imgui-specific options

AiraForceOptions.ini can be found in the user and application "pref" 
directory, as returned by SDL_GetPrefPath:

- Windows: C:\Users\<username>\AppData\Roaming\TTE\AiraForce\
- Linux: /home/<username>/.local/share/TTE/AiraForce/
- Mac: /Users/<username>/Library/Application Support/TTE/AiraForce/
 
imgui.ini can be found next to the executable.

These files can be edited/deleted if the window layout or application gets
into a bad state. 


Credits
=======

- djh0ffman and TTE for making this happen 
  https://www.twitch.tv/djh0ffman

- ira reassembler by Tim Ruehsen, Frank Wille and Nicolas Bastien
  https://aminet.net/package/dev/asm/ira

- VASM assembler by Volker Barthelmann and Frank Wille
  http://sun.hasenbraten.de/vasm/

- vlink (c)1997-2024 by Frank Wille
  http://sun.hasenbraten.de/vasm/

- Dear ImGui by Omar Cornut and contributors
  https://github.com/ocornut/imgui/tree/docking

- Amiga NDK Copyright (C) 2019 Hyperion Entertainment CVBA
  https://www.hyperion-entertainment.com/

- Portable File Dialogs by Sam Hocevar
  https://github.com/samhocevar/portable-file-dialogs

- Simple DirectMedia Layer (SDL2) by Sam Lantinga and contributors
  https://www.libsdl.org/

- tinyxml2 by Lee Thomason
  https://github.com/leethomason/tinyxml2

- cleanCppProject by kracejic
  https://github.com/kracejic/cleanCppProject

- imgui_markdown by Juliette Foucaut & Doug Binks
  https://github.com/juliettef/imgui_markdown

- "Squizz" icon by gerbil/TTE

- "proggy_fonts by Tristan Grimmer\n"
  https://github.com/bluescan/proggyfonts
  License: MIT

- topaz-unicode by Screwtape
  https://gitlab.com/Screwtapello/topaz-unicode
  License: Other

- 680x0 SingleStepTests by Tom Harte
  https://github.com/SingleStepTests/680x0

- m68000 SingleStepTests by raddad772
  https://github.com/SingleStepTests/m68000

- All the helpful folk on the EAB forum and EmuDev Discord

License
=======

This project is licensed under the MIT License. See LICENSE for details.


Contributing
============

  In the meantime

The tool is currently pre-ALPHA and not all features are implemented.
Source code will be released when all core features are implemented or
if I stop working on this project. In the meantime, please provide 
feedback and bug reports at:
- https://eab.abime.net/showthread.php?t=117667
- https://howprice.itch.io/aira-force

Thanks
Howard
