adsp219x-re/docs/GETTING_STARTED.md

# Getting Started (Air-Gapped Deployment)

## Prerequisites

- Radare2 5.8.0+ (built from source on the target machine)
- GCC (to compile the plugin)
- Python 3 (optional, for test ROM generation)

## Setup

1. Copy the entire `adsp219x-re/` directory to the air-gapped machine.

2. Build and install the radare2 plugin:

        cd r2plugin
        make
        make install

3. Verify installation:

        r2 -a adsp219x -b 24 -q -c "pd 10" examples/isa_test.bin

   You should see decoded instructions (NOP, AX0 = 0x1234, etc.).

## Loading a ROM Dump

For a raw 24-bit packed binary (3 bytes per instruction, big-endian):

    r2 -a adsp219x -b 24 firmware.bin

For a padded 32-bit dump (4 bytes per instruction with leading 0x00),
strip the padding first or adjust the base offset manually.

## Useful r2 Commands

    pd 100          # Disassemble 100 instructions
    s 0x200         # Seek to PM address 0x200 (byte offset 0x600)
    /x 1c           # Search for JUMP opcodes (Type 10a prefix)
    axt @@ sym.*    # Cross-references (after analysis)

## Validation

Compare your disassembly against the reference examples in
`examples/`. The `isa_test.bin` was assembled with the open21xx
toolchain and contains verified opcodes for all major instruction
types.

## Reference Documentation

The `docs/` directory contains the original Analog Devices
instruction set reference chapters (PDF and text extracts):

- `9x_opcodes.*`   - Opcode definitions and mnemonics
- `9x_ALUops.*`    - ALU operations
- `9x_mltops.*`    - Multiplier/MAC operations
- `9x_shftops.*`   - Shifter operations
- `9x_flowops.*`   - Flow control (jumps, loops, returns)
- `9x_moveops.*`   - Data move operations
- `9x_multiops.*`  - Multifunction operations

## Large ROM Workflow

For a practical step-by-step workflow for analyzing a large raw
ADSP-219x ROM image, including how to separate likely code from likely
data and when to use graph analysis, see:

- `LARGE_ROM_ANALYSIS_WORKFLOW.md`