AmpRelay

English | 简体中文

AmpRelay is a QEMU-first AMP bring-up lab for Linux remoteproc and rpmsg. It is a small, focused embedded systems project for booting a remote core from Linux, exchanging messages with remote firmware, and validating crash detection and recovery in a reproducible setup.

Table Of Contents

• AmpRelay
  • Table Of Contents
  • What This Project Is
  • What Problem It Tries To Solve
  • What This First Version Focuses On
  • Why QEMU-First
  • Current Status
  • Planned Architecture
  • Repository Structure
  • Quick Start
    • 1. Clone The Repository
    • 2. Read The Entry Docs
    • 3. Pick A Workstream
  • Near-Term Roadmap
  • License

What This Project Is

AmpRelay is not a generic application stack or a broad robotics platform. It is a narrow embedded systems repository centered on the lower layers of heterogeneous multicore systems:

• remoteproc platform integration
• rpmsg communication
• remote firmware lifecycle
• shared-memory transport and notification flow
• fault injection, crash handling, and recovery validation

The goal is to make this path easy to inspect, reproduce, test, and extend.

What Problem It Tries To Solve

Linux remoteproc and rpmsg are practical and widely used, but real projects often run into a few recurring problems:

• the bring-up path is strongly tied to one vendor board or SoC
• communication demos usually stop at simple echo traffic
• crash handling and recovery are less often shown as a clean, reproducible workflow
• documentation for the full path from Linux host to remote firmware is often fragmented

AmpRelay is meant to reduce that friction by building one compact reference path that stays focused on:

• boot
• message exchange
• fault injection
• crash detection
• recovery

What This First Version Focuses On

The first usable version is intentionally small. It aims to provide:

• a QEMU-based reference setup
• a Linux-side bring-up path for remoteproc and rpmsg
• a minimal remote firmware image
• one or more message channels such as echo, command, or telemetry
• fault injection and recovery demonstrations
• testable and documented execution steps

It does not try to be:

• a full SoC emulation platform
• a board support package for many vendors
• a generic middleware framework
• a polished end-user product

Why QEMU-First

The project is intentionally QEMU-first because reproducibility matters more than hardware volume in the first stage.

This approach makes it easier to:

• bring up the system without requiring a specific board
• inspect behavior with logs and controlled test inputs
• iterate on Linux-side integration and remote firmware behavior quickly
• turn the project into something others can clone and run

Physical hardware is still valuable, but it is not required to make the first version technically useful.

Current Status

Planning / bootstrap

Right now the repository is focused on:

• project structure
• initial documentation
• licensing
• workstream separation for kernel, firmware, qemu, tools, and tests

The actual bring-up code and first runnable path will be added incrementally.

Planned Architecture

The intended first architecture is straightforward:

• qemu/: launch helpers, machine or device-model work, and reproducible run configuration
• kernel/: Linux-side remoteproc integration, rpmsg helpers, and configuration notes
• firmware/: remote-core firmware, resource table definitions, endpoint setup, and fault hooks
• tools/: host-side helper scripts for launching, collecting logs, and parsing results
• tests/: smoke tests, message-flow tests, and crash/recovery validation

The first milestone does not depend on a large feature set. It only needs one narrow path that can demonstrate:

1. Linux boots
2. the remote core is started
3. one rpmsg channel works
4. a forced remote failure is detected
5. recovery behavior is observable and repeatable

Repository Structure

.
|-- docs/                    # Architecture notes, bring-up logs, and design docs
|-- firmware/                # Remote-core firmware and related support code
|-- kernel/                  # Linux-side drivers, configs, and integration notes
|-- qemu/                    # QEMU device model notes, launch helpers, and configs
|-- tests/                   # Reproducible test cases and regression scenarios
|-- tools/                   # Host-side helper tools and scripts
|-- .gitignore
|-- COPYRIGHT
|-- LICENSE
|-- README.md
`-- README.zh-CN.md

Quick Start

1. Clone The Repository

git clone https://github.com/Zw-awa/AmpRelay.git
cd AmpRelay

2. Read The Entry Docs

Start with:

• README.md
• docs/README.md
• kernel/README.md
• firmware/README.md
• qemu/README.md

3. Pick A Workstream

• Interested in Linux-side bring-up: start in kernel/
• Interested in remote firmware: start in firmware/
• Interested in emulation and runtime setup: start in qemu/
• Interested in automation and validation: start in tests/ and tools/

Near-Term Roadmap

1. Bring up a minimal QEMU path with a Linux guest and a remote firmware image.
2. Establish one working rpmsg channel.
3. Add remote-side fault injection and Linux-side crash handling.
4. Automate the basic test flow and capture reproducible logs.
5. Document the first full recovery walkthrough.

License

This repository is licensed under GPL-2.0-only. See LICENSE and COPYRIGHT.