Documentation Update and Restructure

demos/demos_index.rst

@@ -0,0 +1,13 @@
+
+.. _demos-reference-samples:
+
+OpenAMP Samples and Demos
+=========================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   echo
+   matrix_multiply
+   rpmsg_multi_services

demos/docker_images.rst

@@ -1,3 +1,5 @@
+.. _docker-images-label:
+
 ==========================
 OpenAMP Demo Docker images
 ==========================

demos/echo.rst

@@ -0,0 +1,94 @@
+========================
+OpenAMP Echo Test Sample
+========================
+
+.. _echo-test-intro:
+
+***************
+Echo Test Intro
+***************
+
+The echo test reference sample, as the name suggests, demonstrates OpenAMP :ref:`Interprocessor Communications (IPC)<ipc-work-label>` components by providing an echo application on a remote which simply returns (echoes) packets as they are received at an :ref:`RPmsg endpoint <rpmsg-endpoint>` from the host controller. The host controller then verifies the returned packet for integrity.
+
+..  image::  ../images/demos/echo-test-intro.svg
+
+.. _echo-test-components:
+
+********************
+Echo Test Components
+********************
+
+There are two applications involved in this demonstration.
+The :ref:`remote application<echo-test-remote-app>` runs as an echo service, which returns packets it receives on an :ref:`RPmsg endpoint <rpmsg-endpoint>`.
+The :ref:`host application<echo-test-host-app>` is the test application sending packets to the echo service and monitoring for their return.
+
+The underlying OpenAMP architectural components used by these applications are
+
+* :ref:`Remoteproc<overview-remoteproc-work-label>`
+* :ref:`Resource Table<overview-remoteproc-work-label>`
+* :ref:`RPMsg<overview-rpmsg-work-label>`
+* :ref:`Virtio<overview-rpmsg-work-label>`
+* :ref:`Libmetal<overview-proxy-libmetal-label>`
+
+The following architecture diagram shows the components involved in the demonstration.
+
+..  image::  ../images/demos/echo-test-components.svg
+
+The top-level control flow is shown in the following message diagram.
+
+..  image::  ../images/demos/echo-test-control-flow.svg
+
+.. _echo-test-remote-app:
+
+RPmsg Echo Remote Application
+=============================
+
+The remote application, rpmsg-echo, is the core of the demonstration. It is a simple application serving a :ref:`RPmsg endpoint <rpmsg-endpoint>` running as the main task on the remote processor, once loaded and started using :ref:`Remoteproc<overview-remoteproc-work-label>`.
+
+
+.. _echo-test-host-app:
+
+Echo Test Host Application
+==========================
+
+The echo_test application forms the host controller side of the demonstration. It repeatedly writes an increasing length payload of 0xA5's up to the maximum data size (packet size minus header) to the RPmsg endpoint. Following each packet send, it reads from the same endpoint and verifies the returned packet for correctness. The application will stop and report on the first corruption found.
+
+Echo Test Host Script
+=====================
+
+The host is also responsible for loading the firmware containing the :ref:`RPmsg Echo Remote Application<echo-test-remote-app>` and starting the remote processor using :ref:`Remoteproc<overview-remoteproc-work-label>`.
+
+For host controllers, like Linux, a script can be used to pipe the firmware to the exposed remoteproc system, followed by the execution of the user space echo_test application. For controllers without scripting capability, like baremetal and RTOS (Real Time Operating systems), this would be achieved in the code.
+
+****************
+Echo Test Source
+****************
+
+RPMsg Echo Baremetal Source
+===========================
+
+The RPMsg Echo service application is available as a baremetal solution in the `open-amp Repository <https://github.com/OpenAMP/open-amp/blob/main/apps/examples/echo/rpmsg-echo.c>`_
+
+It is a CMake application and can be built for any remote as long as the relevant :ref:`OS/HW abstraction layer<porting-guide-work-label>` components like libmetal are ported for that platform.
+
+.. _echo-test-linux-app:
+
+Echo Test Linux Source
+======================
+
+The echo test Linux application is executed on the Linux host controller as a user space application.
+The application is available in the `OpenAMP System Reference repository <https://github.com/OpenAMP/openamp-system-reference/blob/main/examples/linux/rpmsg-echo-test/echo_test.c>`_.
+
+It is a Makefile application and can be built using the `Yocto rpmsg-echo-test recipe <https://github.com/OpenAMP/meta-openamp/blob/master/recipes-openamp/rpmsg-examples/rpmsg-echo-test_1.0.bb>`_
+
+An example host control script is given in the `echo test readme <https://github.com/OpenAMP/openamp-system-reference/blob/main/examples/linux/rpmsg-echo-test/README.md#run-the-demo>`_
+
+*******************************
+Reference Board Implementations
+*******************************
+
+This Echo Test Sample is demonstrated in the following reference implementations.
+
+* :ref:`Docker Images<docker-images-label>` as demo1A
+* :ref:`AMD-Xilinx platforms<demos-AMD-work-label>`
+* :ref:`Inter Process Demos<inter-process-reference-label>`

demos/index.rst

@@ -10,10 +10,7 @@ Samples and Demos
    :maxdepth: 1
    :caption: Contents:
 
-   system_reference-AMD-Xilinx
-   system_reference-ST
    ../open-amp/apps/examples/linux_rpc_demo/README
-   docker_images
    ../hypervisorless_virtio_zcu102/README_demo
    ../lopper/demos/openamp/README.md
 

demos/inter-process.rst

@@ -0,0 +1,16 @@
+.. _inter-process-reference-label:
+
+===========================
+OpenAMP Inter Process Demos
+===========================
+
+The `OpenAMP project examples <https://github.com/OpenAMP/open-amp/tree/main/apps/examples>`_
+are intended to execute on the remote of a reference board but can also be demonstrated by implementing as a process on the host, effectively emulating a remote.
+
+This can be useful for demonstration purposes, but can also be leveraged for component testing, even as part of a continuous integration setup.
+
+Effectively the `OpenAMP Library <https://github.com/OpenAMP/open-amp/tree/main/lib>`_ and `reference examples <https://github.com/OpenAMP/open-amp/tree/main/apps/examples>`_ are built for the host system along with the `host examples <https://github.com/OpenAMP/openamp-system-reference/tree/main/examples/linux>`_.
+
+To build and execute on a Linux system, refer to:
+
+* ../open-amp/README.md

demos/matrix_multiply.rst

@@ -0,0 +1,101 @@
+==============================
+OpenAMP Matrix Multiply Sample
+==============================
+
+.. _matrix-multiply-intro:
+
+*********************
+Matrix Multiply Intro
+*********************
+
+The matrix multiply reference sample, as the name suggests, demonstrates OpenAMP :ref:`Interprocessor Communications (IPC)<ipc-work-label>` components through matrix multiplication. The demonstration uses a host client, which generates random matrixes. It sends them to a service/daemon on a remote which performs a matrix calculation and returns the result via a :ref:`RPmsg endpoint <rpmsg-endpoint>`. The host controller then writes the matrix result to console output.
+
+..  image::  ../images/demos/matrix-multiply-intro.svg
+
+.. _matrix-multiply-components:
+
+**************************
+Matrix Multiply Components
+**************************
+
+There are two applications involved in this demonstration.
+The :ref:`remote application<matrix-multiply-remote-app>` runs as an daemon/service which performs a matrix calculation and returns the result on an :ref:`RPmsg endpoint <rpmsg-endpoint>`.
+The :ref:`host application<matrix-multiply-host-app>` is the client application sending two matrixes as a packet to the daemon/service and monitoring for the return result.
+
+The underlying OpenAMP architectural components used by these applications are
+
+* :ref:`Remoteproc<overview-remoteproc-work-label>`
+* :ref:`Resource Table<overview-remoteproc-work-label>`
+* :ref:`RPMsg<overview-rpmsg-work-label>`
+* :ref:`Virtio<overview-rpmsg-work-label>`
+* :ref:`Libmetal<overview-proxy-libmetal-label>`
+
+The following architecture diagram shows the components involved in the demonstration.
+
+..  image::  ../images/demos/matrix-multiply-components.svg
+
+The top-level control flow is shown in the following message diagram.
+
+..  image::  ../images/demos/matrix-multiply-control-flow.svg
+
+.. _matrix-multiply-remote-app:
+
+RPmsg Matrix Multiply Remote Application
+========================================
+
+The remote application, `matrix_multiplyd <https://github.com/OpenAMP/open-amp/blob/main/apps/examples/matrix_multiply/matrix_multiplyd.c>`_, is the core of the demonstration. It is a simple application serving a :ref:`RPmsg endpoint <rpmsg-endpoint>` running as the main task on the remote processor, once loaded and started using :ref:`Remoteproc<overview-remoteproc-work-label>`.
+
+
+.. _matrix-multiply-host-app:
+
+Matrix Multiply Host Application
+================================
+
+The host application generates two matrices into a structure with size and 6x6 matrix, sequentially into a RPMsg packet. It then waits for matrix sized bytes to be returned and prints the resultant matrix as calculated by the remote.
+
+There are two implementations. The `mat_mul_demo <https://github.com/OpenAMP/openamp-system-reference/blob/main/examples/linux/rpmsg-mat-mul/mat_mul_demo.c>`_ application forms the host controller side of the demonstration, as a linux user space client application. The `matrix_multiply <https://github.com/OpenAMP/open-amp/blob/main/apps/examples/matrix_multiply/matrix_multiply.c>`_ application forms the host controller side of the demonstration, as a baremetal client application.
+
+
+Matrix Multiply Host Script
+===========================
+
+The host is also responsible for loading the firmware containing the :ref:`RPmsg Matrix Multiply Remote Application<matrix-multiply-remote-app>` and starting the remote processor using :ref:`Remoteproc<overview-remoteproc-work-label>`.
+
+For host controllers, like Linux, a script can be used to pipe the firmware to the exposed remoteproc system, followed by the execution of the user space mat_mul_demo application. For controllers without scripting capability, like baremetal and RTOS (Real Time Operating systems), this would be achieved in the code.
+
+**********************
+Matrix Multiply Source
+**********************
+
+RPmsg Matrix Multiply Baremetal Sources
+=======================================
+
+There are two baremetal applications, a daemon/service to run on the remote and a host/controller application which is the matrix multiply client requesting the calculations.
+
+The RPmsg Matrix Multiply daemon/service application is available as a baremetal solution in the `OpenAMP Repository <https://github.com/OpenAMP/open-amp/blob/main/apps/examples/matrix_multiply/matrix_multiplyd.c>`_. Take note of the d for daemon at the end of the file.
+
+The RPmsg Matrix Multiple host client application is available as a baremetal solution in the `OpenAMP Repository <https://github.com/OpenAMP/open-amp/blob/main/apps/examples/matrix_multiply/matrix_multiply.c>`_
+
+Both are CMake application and can be built for any remote as long as the relevant :ref:`OS/HW abstraction layer<porting-guide-work-label>` components like libmetal are ported for that platform.
+
+.. _matrix-multiply-linux-app:
+
+Matrix Multiply Linux Source
+============================
+
+The matrix multiply Linux application is executed on the Linux host controller as a user space application.
+The application is available in the `OpenAMP System Reference repository <https://github.com/OpenAMP/openamp-system-reference/blob/main/examples/linux/rpmsg-mat-mul/mat_mul_demo.c>`_.
+
+It is a Makefile application and can be built using the `Yocto rpmsg-mat-mul recipe <https://github.com/OpenAMP/meta-openamp/blob/master/recipes-openamp/rpmsg-examples/rpmsg-mat-mul_1.0.bb>`_
+
+An example host control script is given in the `matrix multiply readme <https://github.com/OpenAMP/openamp-system-reference/tree/main/examples/linux/rpmsg-mat-mul#run-the-demo>`_
+
+*******************************
+Reference Board Implementations
+*******************************
+
+This Matrix Multiply Sample is demonstrated in the following reference implementations.
+
+* :ref:`Docker Images<docker-images-label>` as demo1B
+* :ref:`AMD-Xilinx platforms<demos-AMD-work-label>`
+* :ref:`Inter Process Demos<inter-process-reference-label>`

demos/reference_boards.rst

@@ -0,0 +1,15 @@
+
+OpenAMP Reference Boards
+========================
+
+:ref:`OpenAMP Samples and Demos<demos-reference-samples>` are provided on a number of boards and virtual machines to demonstrate the implementation of each.
+
+In general the OpenAMP feature being exemplified is found in the `OpenAMP source repository <https://github.com/OpenAMP/open-amp/tree/main/apps/examples>`_ through a number of examples. Additional supporting code is located in the `OpenAMP System Reference examples <https://github.com/OpenAMP/openamp-system-reference/tree/main/examples>`_
+
+.. toctree::
+   :maxdepth: 2
+
+   docker_images
+   system_reference-AMD-Xilinx
+   system_reference-ST
+   inter-process