From b33f4a5a1bf5542c38ae07eef4244289dac7f186 Mon Sep 17 00:00:00 2001
From: Entrpi <133157614+Entrpi@users.noreply.github.com>
Date: Sat, 31 Oct 2026 01:28:06 +1100
Subject: [PATCH] docs: correct the raw ARM example and document a Cortex-M
 language override (#7483)

* docs(raw-binary): replace the STM32-style ARM example

The headline raw example opened ecu.bin at 0x8000000, an STM32 flash
address, while the arm lane decodes in ARM state. Map a 32-bit ARM-state
image at 0x8000 instead, and state beside the example that Thumb-only
images, including Cortex-M firmware, are not supported.

* docs(ghidra): document an interim Cortex-M language override

Ghidra imports little-endian ARM ELF files as ARM:LE:32:v8, which
defaults to ARM state and marks Thumb code only from $t mapping symbols
and odd function-symbol addresses. Unpinned arm ELF already admits
REA_GHIDRA_LANGUAGE_ID, so document ARM:LE:32:Cortex (ARMv6-M, ARMv7-M,
ARMv7E-M) and ARM:LE:32:v8-m (ARMv8-M) as an unverified interim.

State the override's full effect while it is set: raw-binary, DOS, DOL,
PSP and language-pinned lanes such as RISC-V refuse it, and REA asks
Ghidra to import every other target in the ARM language, because it does
not check the override's processor against the target.
---
 docs/installation.md | 27 +++++++++++++++++++++++++++
 docs/raw-binary.md   | 14 +++++++++-----
 2 files changed, 36 insertions(+), 5 deletions(-)

diff --git a/docs/installation.md b/docs/installation.md
index dcd6cbfbdf..dfcdf42fa3 100644
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -1417,6 +1417,33 @@ REA passes `-processor`/`-cspec`, checks both against the installation's `.ldefs
 
 Language definitions must be well-formed XML encoded as UTF-8 or BOM-marked UTF-16, with any encoding declaration matching the bytes. Literal Unicode replacement characters (U+FFFD) are accepted; malformed source bytes are rejected.
 
+Ghidra imports little-endian ARM ELF files, including Cortex-M
+(`arm-none-eabi`) firmware, as `ARM:LE:32:v8`. That language defaults to ARM
+state, and its ELF loader marks code as Thumb only where `$t` mapping symbols
+or odd function-symbol addresses say so. Cortex-M cores run only Thumb code, so
+the gap matters mainly for code without those markers, such as stripped images
+and handlers reached only through the vector table. REA has no M-profile ARM
+lane. As an unverified interim, select an M-profile language, which decodes in
+Thumb state by default. For ARMv6-M, ARMv7-M and ARMv7E-M cores:
+
+```bash
+export REA_GHIDRA_LANGUAGE_ID="ARM:LE:32:Cortex"
+```
+
+For ARMv8-M cores, use `ARM:LE:32:v8-m` instead. REA has not verified either
+language for Cortex-M analysis. While the variable is set, it applies to every
+Ghidra import in the REA server:
+
+- raw-binary, DOS, GameCube DOL and PSP opens are refused, as are opens in
+  lanes that reject a different language, such as RISC-V;
+- REA asks Ghidra to import everything else in the selected ARM language,
+  including x86, x86-64, arm64, PowerPC and Hexagon ELF files and PE and
+  Mach-O files, because it does not check that the override's processor
+  matches the target.
+
+Restart REA without the variable before you analyze other targets. A future
+M-profile lane may refuse it; remove the setting then.
+
 To seed code that auto-analysis cannot reach (computed jumps, pointers in data):
 
 ```bash
diff --git a/docs/raw-binary.md b/docs/raw-binary.md
index 09f44710df..8ff3f1967e 100644
--- a/docs/raw-binary.md
+++ b/docs/raw-binary.md
@@ -10,24 +10,28 @@ inferred from a `.bin` suffix or from unrecognized bytes.
 ## Open and inspect
 
 ```bash
-rea inspect /absolute/path/to/ecu.bin --target-format raw-binary --architecture arm --entry-point 0x8000000 --provider ghidra --json
-rea function /absolute/path/to/ecu.bin 0x8000000 --target-format raw-binary --architecture arm --entry-point 0x8000000 --provider ghidra --json
-rea inspect-native-load-image /absolute/path/to/ecu.bin --target-format raw-binary --architecture arm --entry-point 0x8000000 --provider ghidra --json
+rea inspect /absolute/path/to/kernel.img --target-format raw-binary --architecture arm --entry-point 0x8000 --provider ghidra --json
+rea function /absolute/path/to/kernel.img 0x8000 --target-format raw-binary --architecture arm --entry-point 0x8000 --provider ghidra --json
+rea inspect-native-load-image /absolute/path/to/kernel.img --target-format raw-binary --architecture arm --entry-point 0x8000 --provider ghidra --json
 ```
 
 ```json
 {
   "name": "open_binary",
   "arguments": {
-    "path": "/absolute/path/to/ecu.bin",
+    "path": "/absolute/path/to/kernel.img",
     "format": "raw-binary",
     "architecture": "arm",
-    "entry_point": "0x8000000",
+    "entry_point": "0x8000",
     "provider_id": "ghidra"
   }
 }
 ```
 
+The example maps a 32-bit ARM-state image at `0x8000`. For `arm`, decoding
+starts at the entry in ARM (A32) state, so Thumb-only images, including Cortex-M
+firmware, are not supported. See [Limitations](#limitations).
+
 `architecture` is one of `x86`, `x86_64`, `arm`, `arm64`, `6502`, or `m68k`. `entry_point` is a
 hexadecimal address of the form `0x…`. The complete file is mapped starting at
 that address, and Ghidra seeds an `entry` function there before auto-analysis.