OpenAMP · arnopo · Mar 31, 2026 · Feb 16, 2026 · Feb 16, 2026 · Feb 16, 2026
diff --git a/examples/legacy_apps/README.md b/examples/legacy_apps/README.md
@@ -1,10 +1,12 @@
-# Summary
+# System Reference Legacy Apps Build Overview
 
-This directory contains legacy applications and tests examples.
-These applications were moved from open-amp repository.
+This page details how to setup and build the
+[OpenAMP System Reference](https://github.com/OpenAMP/openamp-system-reference/) legacy apps
+and test examples found in the examples/legacy_apps directory.
+These applications were moved from the [OpenAMP repository](https://github.com/OpenAMP/open-amp).
 
 
-# Initialization
+## Initialization
 
 The first step is to initialize the workspace folder (``my-workspace``) where
 the examples and all Zephyr modules will be cloned. You can do
@@ -18,49 +20,33 @@ cd my-workspace
 west update
 ```
 
-# Build
+## Build
 
-Following steps to build legacy apps on host machine.
+The following steps are to build legacy apps on a host machine.
 
-```
+```shell
 export PROJECT_ROOT=$PWD
 ```
 
-## Build libmetal
+### Build libmetal
 ```shell
-  $ cd $PROJECT_ROOT/libmetal
-  $ cmake . -Bbuild -DCMAKE_INSTALL_PREFIX=$PROJECT_ROOT/target
-  $ make -C build VERBOSE=1 install
+cd $PROJECT_ROOT/libmetal
+cmake . -Bbuild -DCMAKE_INSTALL_PREFIX=$PROJECT_ROOT/target
+make -C build VERBOSE=1 install
 ```
 
-## Build open_amp
+### Build open_amp
 ```shell
-  $ cd $PROJECT_ROOT/open-amp
-  $ cmake . -Bbuild -DCMAKE_INCLUDE_PATH=$PROJECT_ROOT/libmetal/build/lib/include/   -DCMAKE_LIBRARY_PATH=$PROJECT_ROOT/libmetal/build/lib/ -DCMAKE_INSTALL_PREFIX=$PROJECT_ROOT/target
-  $ make -C build VERBOSE=1 install
+cd $PROJECT_ROOT/open-amp
+cmake . -Bbuild -DCMAKE_INCLUDE_PATH=$PROJECT_ROOT/libmetal/build/lib/include/   -DCMAKE_LIBRARY_PATH=$PROJECT_ROOT/libmetal/build/lib/ -DCMAKE_INSTALL_PREFIX=$PROJECT_ROOT/target
+make -C build VERBOSE=1 install
 ```
-## Build legacy Apps
+### Build legacy Apps
 ```shell
-  $ cd $PROJECT_ROOT/openamp-system-reference/examples/legacy_apps
-  $ cmake -Bbuild \
+cd $PROJECT_ROOT/openamp-system-reference/examples/legacy_apps
+cmake -Bbuild \
 -DCMAKE_INCLUDE_PATH="$PROJECT_ROOT/libmetal/build/lib/include/;$PROJECT_ROOT/open-amp/build/lib/include/" \
 -DCMAKE_LIBRARY_PATH="$PROJECT_ROOT/libmetal/build/lib/;$PROJECT_ROOT/open-amp/build/lib/" \
 -DCMAKE_INSTALL_PREFIX=$PROJECT_ROOT/target
-  $ make -C build VERBOSE=1 install
-```
-
-## Run application on a Linux PC
-It is possible to run application on a Linux PC to communicate between two Linux processes.
-
-```shell
-  $ cd $PROJECT_ROOT/target
-  $ echo "################### run ping test #####################"
-  $ LD_LIBRARY_PATH=./lib  ./bin/rpmsg-echo-static &
-  $ sleep 1
-  $ LD_LIBRARY_PATH=./lib  ./bin//msg-test-rpmsg-ping-static 1
-
-  $ echo "################### run ping test #####################"
-  $ LD_LIBRARY_PATH=./lib  ./bin/rpmsg-nocopy-echo-static &
-  $ sleep 1
-  $ LD_LIBRARY_PATH=./lib  ./bin//rpmsg-nocopy-ping-static  1
+make -C build VERBOSE=1 install
 ```
diff --git a/examples/legacy_apps/examples/echo/README.rst b/examples/legacy_apps/examples/echo/README.rst
@@ -8,7 +8,11 @@ back the message. The processor that sends the message will verify the echoed me
 Compilation
 ***********
 
-See `README.md <../../README.md>`_ for details.
+.. include:: ../../README.md
+   :parser: myst_parser.sphinx_
+
+If you are perusing the github repository refer to the `legacy_apps README.md <../../README.md>`_
+for compilation information.
 
 Run demonstration on a Linux PC
 *******************************

diff --git a/examples/legacy_apps/examples/linux_rpc_demo/README.rst b/examples/legacy_apps/examples/linux_rpc_demo/README.rst
@@ -1,3 +1,6 @@
+Overview
+********
+
 This readme is about the OpenAMP linux_rpc_demo.
 
 The linux_rpc_demo is about remote procedure calls between linux host and a linux
@@ -9,7 +12,11 @@ Compilation
 ***********
 Add cmake option `-DWITH_PROXY_APPS=ON` to build the system reference demonstration applications.
 
-See `README.md <../../README.md>`_ for details.
+.. include:: ../../README.md
+   :parser: myst_parser.sphinx_
+
+If you are perusing the github repository refer to the `legacy_apps README.md <../../README.md>`_
+for compilation information.
 
 Run demonstration on a Linux PC
 *******************************
@@ -31,7 +38,7 @@ Run demonstration on a Linux PC
 Enter the inputs on the host side the same gets printed on the remote side. You will see
 communication between the host and remote process using rpmsg calls.
 
-Note:
-*****
-`sudo` is required to run the OpenAMP demos between Linux processes, as it doesn't work on
-some systems if you are normal users.
+.. note::
+
+   `sudo` is required to run the OpenAMP demos between Linux processes, as it doesn't work on
+   some systems if you are normal users.
diff --git a/examples/legacy_apps/examples/matrix_multiply/README.rst b/examples/legacy_apps/examples/matrix_multiply/README.rst
@@ -8,7 +8,11 @@ The other processor calculates the matrix multiplication and returns the result
 Compilation
 ***********
 
-See `README.md <../../README.md>`_ for details.
+.. include:: ../../README.md
+   :parser: myst_parser.sphinx_
+
+If you are perusing the github repository refer to the `legacy_apps README.md <../../README.md>`_
+for compilation information.
 
 Run demonstration on a Linux PC
 *******************************

diff --git a/examples/legacy_apps/examples/rpc_demo/README.rst b/examples/legacy_apps/examples/rpc_demo/README.rst
@@ -1,3 +1,6 @@
+Overview
+********
+
 This readme is about the OpenAMP rpc_demo demo.
 The rpc_demo is about one processor uses the UART on the other processor and creates file on
 the other processor's filesystem with file operations.
@@ -19,7 +22,13 @@ Here is an example to generate the to generate the `rpc_demo` application:
 
     cmake -DCMAKE_TOOLCHAIN_FILE=zynqmp_r5_generic -DWITH_APPS=ON -DWITH_PROXY=ON
 
-See `README.md <../../README.md>`_ to generate the `rpc_demod` application.
+
+.. include:: ../../README.md
+   :parser: myst_parser.sphinx_
+
+If you are perusing the github repository refer to the `legacy_apps README.md <../../README.md>`_
+for compilation information.
+
 
 Linux Compilation
 =================

diff --git a/examples/legacy_apps/machine/xlnx/README.md b/examples/legacy_apps/machine/xlnx/README.md
@@ -5,7 +5,7 @@ Dependencies:
 2. System Device Tree generated from design : https://docs.amd.com/r/en-US/ug1647-porting-embeddedsw-components/Generating-a-System-Device-Tree-Using-SDTGen
 
 Below is sample run for Versal Gen 1 platform
-### Generate OpenAMP RPU Device Tree
+## Generate OpenAMP RPU Device Tree
 
 SDT is the System Device Tree generated from design
 ```sh
@@ -21,7 +21,7 @@ python3 lopper.py -f --enhanced \
 ```
 The above Device Tree "rpu.dts" will be used for configuration of the app's interrupts, shared memory and linker script.
 
-### Generate OpenAMP App config header
+## Generate OpenAMP App config header
 
 ```sh
 export LOPPER_DTC_FLAGS="-b 0 -@"
@@ -37,7 +37,7 @@ cd -
 The output amd_platform_info.h needs to be in the location denoted above of "openamp-system-reference/examples/legacy_apps/machine/zynqmp_r5" BEFORE
 cmake configure step.
 
-### Generate RPU Application Linker config object
+## Generate RPU Application Linker config object
 
 ```sh
 export LOPPER_DTC_FLAGS="-b 0 -@"

diff --git a/examples/libmetal/machine/remote/amd_rpu/system/generic/README.md b/examples/libmetal/machine/remote/amd_rpu/system/generic/README.md
@@ -1,4 +1,5 @@
 AMD RPU Baremetal System Port
+=============================
 
 This directory holds the minimal OS layer that lets the remote IRQ
 shared-memory demo run without an RTOS on the AMD RPU.

diff --git a/examples/linux/dts/xilinx/README.md b/examples/linux/dts/xilinx/README.md
@@ -1,5 +1,5 @@
 
-#### Building DTBs
+# Building DTBs
   - You will need a copy of the Linux source tree
   - For consitency use the same kernel version as the OpenAMP-CI Builds is using
   - Below we assume the kernel source is at ~/my-dir/kernel-source

diff --git a/examples/zephyr/README.md b/examples/zephyr/README.md
@@ -1,15 +1,6 @@
 # Zephyr Example Application
 
-This repository contains Zephyr example applications. The main purpose of this
-repository is to provide references and demo on the use of OpenAMP on Zephyr based applications. features demonstrated in this example are:
-
-- [rpmsg multi service][rms_app] application
-- [dual qemu ivshmem][dqi_app] application
-
-
-
-[rms_app]: #rpmsg_multi_services/README.md
-[dqi_app]: #dual_qemu_ivshmem/README.md
+Building of the Zephyr example applications is detailed below.
 
 ## Getting Started
 

diff --git a/examples/zephyr/dual_qemu_ivshmem/README.rst b/examples/zephyr/dual_qemu_ivshmem/README.rst
@@ -20,7 +20,7 @@ Note:
 *****
 
 * The Vendor-ID 0x1AF4 is being used from all other Zephyr in-tree samples, currently there
-is no Vendor allocated with the selected number.
+  is no Vendor allocated with the selected number.
 
 ivshmem-server needs to be available and running. The server is available in
 Zephyr SDK or pre-built in some distributions. Otherwise, it is available in