FPBInject - Cortex-M Runtime Code Injection

Runtime function hooking for ARM Cortex-M3/M4 using the FPB hardware unit. Inject custom code without modifying Flash.

Features

• ✅ Zero Flash Modification - Runtime injection to RAM
• ✅ Hardware Redirection - FPB unit for zero-overhead patching
• ✅ Dual Modes - REMAP (M3/M4) and DebugMonitor (ARMv8-M)
• ✅ 6 Simultaneous Hooks - Multiple active patches
• ✅ Reversible - Restore original behavior instantly

Quick Start

Build

git clone https://github.com/FASTSHIFT/FPBInject.git
cd FPBInject

cmake -B build -DAPP_SELECT=3 -DCMAKE_TOOLCHAIN_FILE=cmake/arm-none-eabi-gcc.cmake
cmake --build build

Flash

st-flash write build/FPBInject.bin 0x08000000

Inject via CLI

cd Tools/WebServer
pip install pyserial

# Analyze target function
python fpb_cli.py analyze build/FPBInject.elf digitalWrite

# Inject patch
python fpb_cli.py --port /dev/ttyACM0 --elf build/FPBInject.elf \
    --compile-commands build/compile_commands.json \
    inject digitalWrite patch.c

Tools

Tool	Description
fpb_cli.py	CLI for AI integration (JSON output)
WebServer	Web UI with file monitoring

Writing Patches

// patch_digitalWrite.c
#include <Arduino.h>

__attribute__((used, section(".text.inject")))
void inject_digitalWrite(uint8_t pin, uint8_t value) {
    Serial.printf("Hooked: pin=%d val=%d\n", pin, value);
    value ? digitalWrite_HIGH(pin) : digitalWrite_LOW(pin);
}

CMake Options

Option	Default	Description
APP_SELECT	1	Application (3=func_loader)
FL_ALLOC_MODE	STATIC	Memory: STATIC/LIBC/UMM
FPB_NO_DEBUGMON	OFF	Disable DebugMonitor

Hardware

• MCU: STM32F103C8T6 or other Cortex-M3/M4
• Debugger: ST-Link V2
• Serial: USB-to-Serial or USB CDC

Documentation

• CLI Tool Guide
• WebServer Guide
• Architecture Details
• AI Skills

Project Structure

FPBInject/
├── App/                    # Applications and inject examples
├── Source/                 # FPB driver and function loader
├── Project/                # Platform HAL and Arduino API
├── Tools/
│   └── WebServer/          # CLI and Web tools
└── Docs/                   # Documentation

Limitations

• FPB patches Code region only (0x00000000 - 0x1FFFFFFF)
• 6 comparators on STM32F103
• Thumb/Thumb-2 instructions only
• Debuggers may conflict with FPB

License

MIT License - See LICENSE

References

• ARM Cortex-M3 TRM
• STM32F103 Reference Manual