diff --git a/.gitmodules b/.gitmodules index d62f42f..194d219 100644 --- a/.gitmodules +++ b/.gitmodules @@ -1,18 +1,18 @@ [submodule "open-amp"] path = open-amp - url = https://github.com/OpenAMP/open-amp.git + url = https://github.com/sipke/open-amp.git [submodule "hypervisorless_virtio_zcu102"] path = hypervisorless_virtio_zcu102 - url = https://github.com/danmilea/hypervisorless_virtio_zcu102.git + url = https://github.com/sipke/hypervisorless_virtio_zcu102.git [submodule "lopper"] path = lopper - url = https://github.com/devicetree-org/lopper.git + url = https://github.com/sipke/lopper.git [submodule "openamp-system-reference"] path = openamp-system-reference - url = https://github.com/OpenAMP/openamp-system-reference.git + url = https://github.com/sipke/openamp-system-reference.git [submodule "libmetal"] path = libmetal - url = https://github.com/OpenAMP/libmetal.git + url = https://github.com/sipke/libmetal.git [submodule "awesome"] path = _doxygen/awesome url = https://github.com/jothepro/doxygen-awesome-css.git diff --git a/conf.py b/conf.py index 3c336c6..af52ac6 100644 --- a/conf.py +++ b/conf.py @@ -119,7 +119,8 @@ html_logo = '_static/images/openAMP_combox_dark_trim.svg' html_theme_options = { - 'logo_only': True + 'logo_only': True, + 'includehidden': False } # below copied / hacked from Zephyr projects' zephyr/doc/conf.py diff --git a/demos/echo.rst b/demos/echo.rst index da2e375..9c1b583 100644 --- a/demos/echo.rst +++ b/demos/echo.rst @@ -117,3 +117,14 @@ This Echo Test Sample is demonstrated in the following reference implementations * :ref:`Docker Images` as demo1A * :ref:`AMD-Xilinx platforms` * :ref:`Inter Process Demos` + + +*************************** +Echo Test Build Information +*************************** + +.. toctree:: + :maxdepth: 2 + :titlesonly: + + ../openamp-system-reference/examples/legacy_apps/examples/echo/README \ No newline at end of file diff --git a/demos/hvl_virtio.rst b/demos/hvl_virtio.rst index 5ae94dd..e24790a 100644 --- a/demos/hvl_virtio.rst +++ b/demos/hvl_virtio.rst @@ -99,6 +99,17 @@ This Hypervisorless Virtio Samples are demonstrated in the following reference i For information on building and running the demonstrations for zcu102 refer to .. toctree:: - :maxdepth: 2 + :maxdepth: 1 ../hypervisorless_virtio_zcu102/README_demo + ../hypervisorless_virtio_zcu102/README + ../hypervisorless_virtio_zcu102/zephyr_r5/README + ../hypervisorless_virtio_zcu102/zephyr_r5/hello_r5/README + +For more information on Hypervisorless Virtio and associated OpenAMP support refer to + +.. toctree:: + :maxdepth: 1 + + ../hypervisorless_virtio_zcu102/README_hypervisorless_virtio.md + ../hypervisorless_virtio_zcu102/README_openamp_virtio.md diff --git a/demos/linux_rpc.rst b/demos/linux_rpc.rst index 349e163..de6b061 100644 --- a/demos/linux_rpc.rst +++ b/demos/linux_rpc.rst @@ -102,8 +102,25 @@ This Linux RPC Sample is demonstrated in the following reference implementations * :ref:`Linux Inter Process ` + +******************************** +Linux RPC Demo Build Information +******************************** + .. toctree:: - :maxdepth: 1 - :caption: Demo Compile and Execution Instructions + :maxdepth: 2 ../openamp-system-reference/examples/legacy_apps/examples/linux_rpc_demo/README + + +********************************************* +Alternate Bare Metal Remote Build Information +********************************************* + +The following sections detail how to build a baremetal remote if you wish to run this example +on a remote processor rather than secondary linux process. + +.. toctree:: + :maxdepth: 2 + + ../openamp-system-reference/examples/legacy_apps/examples/rpc_demo/README diff --git a/demos/matrix_multiply.rst b/demos/matrix_multiply.rst index f61dc38..464eaf9 100644 --- a/demos/matrix_multiply.rst +++ b/demos/matrix_multiply.rst @@ -131,3 +131,14 @@ This Matrix Multiply Sample is demonstrated in the following reference implement * :ref:`Docker Images` as demo1B * :ref:`AMD-Xilinx platforms` * :ref:`Inter Process Demos` + + +********************************* +Matrix Multiply Build Information +********************************* + +.. toctree:: + :maxdepth: 2 + :titlesonly: + + ../openamp-system-reference/examples/legacy_apps/examples/matrix_multiply/README diff --git a/demos/reference_boards.rst b/demos/reference_boards.rst index 1fc58c4..4d6c6c9 100644 --- a/demos/reference_boards.rst +++ b/demos/reference_boards.rst @@ -19,3 +19,4 @@ number of examples. Additional supporting code is located in the system_reference-NXP system_reference-TI inter_process + ../openamp-system-reference/examples/legacy_apps/README \ No newline at end of file diff --git a/demos/rpmsg_multi_services.rst b/demos/rpmsg_multi_services.rst index 04a3f0f..68503d0 100644 --- a/demos/rpmsg_multi_services.rst +++ b/demos/rpmsg_multi_services.rst @@ -216,3 +216,14 @@ This RPMsg Multi Services Sample is demonstrated in the following reference impl * :ref:`Texas Instruments ` * Refer to `Zephyr Build Instructions `_. + + +************************************** +RPMsg Multi Services Build Information +************************************** + +.. toctree:: + :maxdepth: 2 + :titlesonly: + + ../openamp-system-reference/examples/zephyr/rpmsg_multi_services/README diff --git a/demos/system_reference-AMD-Xilinx.rst b/demos/system_reference-AMD-Xilinx.rst index 9e0b4ae..136792d 100644 --- a/demos/system_reference-AMD-Xilinx.rst +++ b/demos/system_reference-AMD-Xilinx.rst @@ -15,3 +15,10 @@ The following Reference Samples and Demos are implemented using the ../openamp-system-reference/examples/linux/rpmsg-echo-test/README.md ../openamp-system-reference/examples/linux/rpmsg-mat-mul/README.md ../openamp-system-reference/examples/linux/rpmsg-proxy-app/README.md + ../openamp-system-reference/examples/libmetal/machine/host/amd_linux_userspace/README + ../openamp-system-reference/examples/libmetal/machine/remote/amd_rpu/README + ../openamp-system-reference/examples/libmetal/machine/remote/amd_rpu/system/freertos/README + ../openamp-system-reference/examples/libmetal/machine/remote/amd_rpu/system/generic/README + ../openamp-system-reference/examples/legacy_apps/machine/xlnx/README + ../openamp-system-reference/examples/legacy_apps/machine/xlnx/microblaze_generic/README + ../openamp-system-reference/examples/linux/dts/xilinx/README diff --git a/hypervisorless_virtio_zcu102 b/hypervisorless_virtio_zcu102 index f2f5f79..d3c6321 160000 --- a/hypervisorless_virtio_zcu102 +++ b/hypervisorless_virtio_zcu102 @@ -1 +1 @@ -Subproject commit f2f5f7992da9a9c87d5e547537ba2e96be2d6ded +Subproject commit d3c6321d9df4af2b61889a36489ed44cfe76db92 diff --git a/index.rst b/index.rst index 30b19e7..36bced8 100644 --- a/index.rst +++ b/index.rst @@ -17,3 +17,52 @@ Welcome to the OpenAMP Project Documentation protocol_details/index docs/porting_guide openamp/glossary + + +.. + TOC entries used to suppress warnings we accept for files not included in a table of contents. + WARNING: document isn't included in any toctree [toc.not_included] + Note that each library's (e.g. open-amp) readme file is included via the REFERENCE section links + in the navigation bar on the left. + +.. toctree:: + :hidden: + + README + openamp-system-reference/README + openamp-system-reference/LICENSE + open-amp/.github/actions/build_ci/README + open-amp/README + open-amp/MAINTAINERS + open-amp/LICENSE + libmetal/.github/actions/build_ci/README + libmetal/README + libmetal/MAINTAINERS + libmetal/LICENSE + lopper/LICENSE + lopper/specification/README + lopper/tests/MIGRATION_GUIDE + lopper/tests/README + lopper/README + lopper/README-architecture + lopper/specification/source/index + lopper/docs/amd/linux/source/index + lopper/docs/amd/zephyr/source/index + lopper/demos/openamp/README.md + +.. + TOC entries for examples which do not have readthedocs descriptions so suppressing to avoid the + warning: + WARNING: document isn't included in any toctree [toc.not_included] + If readthedocs description is added, these should be integrated into that description. + +.. toctree:: + :hidden: + + openamp-system-reference/examples/legacy_apps/examples/nocopy_echo/README + openamp-system-reference/examples/legacy_apps/examples/rpmsg_sample_echo/README + openamp-system-reference/examples/libmetal/README + openamp-system-reference/examples/libmetal/demos/irq_shmem_demo/README + openamp-system-reference/examples/libmetal/demos/irq_shmem_demo/host/README + openamp-system-reference/examples/libmetal/demos/irq_shmem_demo/remote/README + openamp-system-reference/examples/zephyr/dual_qemu_ivshmem/README diff --git a/libmetal b/libmetal index ece95f0..d59b83a 160000 --- a/libmetal +++ b/libmetal @@ -1 +1 @@ -Subproject commit ece95f0e71811c44a4c23d9a1514f338ccf60c75 +Subproject commit d59b83a800d24c1c4213a5e305f71312471e63bf diff --git a/lopper b/lopper index 2440a0c..2c9142c 160000 --- a/lopper +++ b/lopper @@ -1 +1 @@ -Subproject commit 2440a0ce358031a5b2874b31e4dbf7adf50392b8 +Subproject commit 2c9142cacaa00cde1fac5f7d000652f407c92547 diff --git a/open-amp b/open-amp index 59e843f..07d5036 160000 --- a/open-amp +++ b/open-amp @@ -1 +1 @@ -Subproject commit 59e843f3efd788c181436066298a3e03273bc4a1 +Subproject commit 07d50365fc5fc31dd3f78eeabd1c50185dcdd073 diff --git a/openamp-system-reference b/openamp-system-reference index 3eec8f8..12a89a3 160000 --- a/openamp-system-reference +++ b/openamp-system-reference @@ -1 +1 @@ -Subproject commit 3eec8f826a2f7fd5b3028bfdbe8253e00ec87f0c +Subproject commit 12a89a3f5b2310cec703fccaee470e057ce948a0 diff --git a/openamp/overview.rst b/openamp/overview.rst index 49f68b4..397711d 100644 --- a/openamp/overview.rst +++ b/openamp/overview.rst @@ -283,17 +283,19 @@ This is achieved through the OpenAMP library which: (`See OpenAMP repository `_) - works on different system thanks to the `libmetal `_ adaptation layer: + - Bare Metal (No OS) - Multiple RTOS's, including `FreeRTOS `_, `NuttX `_, `Zephyr `_, `VxWorks `_, and more + - OS's on top of hypervisors - Within hypervisors - is compatible with different compilers such as gcc, clang, armcc and more - maintains compatibility with the Linux kernel by leveraging the following frameworks: `remoteproc `_, `RPMsg `_ and - `Virtio `_ frameworks. + `Virtio Driver `_ frameworks. .. _governance-work-label: diff --git a/tools/index.rst b/tools/index.rst index 4ad12ff..73ce45a 100644 --- a/tools/index.rst +++ b/tools/index.rst @@ -4,11 +4,10 @@ OpenAMP Supporting Tools ========================= +Lopper +------ + .. toctree:: :maxdepth: 2 - :caption: Contents: lopper - ../lopper/demos/openamp/README.md - -* Run the Lopper Demonstration as demo5 in :ref:`Docker Images`. diff --git a/tools/lopper.rst b/tools/lopper.rst index c75e2cb..2680e6a 100644 --- a/tools/lopper.rst +++ b/tools/lopper.rst @@ -1,44 +1,6 @@ -=================== -OpenAMP Lopper Tool -=================== -.. _lopper-tool-intro: -*************** -Lopper Intro -*************** +.. toctree:: + :maxdepth: 1 -System Device Trees (S-DT) are used to describe resources of `heterogeneous `_ embedded environments. - -Their intent is to be the industry standard method for defining how computing resources are divided into independent :ref:`runtime domains`. - -Examples of domains are - -* a computing unit, e.g. RTOS on R5s -* an operating environment at a specific execution level (e.g. `OPTEE `_) -* a virtual machine (e.g. `Xen `_) - -For those familiar with `Device Trees (DTS) `_ think of the S-DT as a combination of multiple device trees to define sub-systems. DTS' define resources seen from one address space, whereas S-DT's define the topology of the full system. - -The `Lopper Tool `_ provides a way to generate sub-system DTS' from S-DT's and manipulate, inspect or verify the S-DT for correctness. - -.. image:: ../images/tools/lopper-intro.svg - - -The `Lopper Tool `_ is a data driven tool written in Python, and supports inputs in dts, dtb and yaml format. Actions, which are used to manipulate the input data, are provided as unit operations (lops) as DTS formatted files. These are small transformation commands, inline Python source or for more complex scenarios `lopper assists `_ Python modules. - -The diagram below shows an example of three transformations performed by lopper through three independent DTS files which define the actions to perform. - -.. image:: ../images/tools/lopper-actions.svg - -Lopper is built on top of device tree tools, `Device Tree Compiler (DTC) `_ and `libfdt `_. - - -References -^^^^^^^^^^ - -:ref:`Lopper Architecture Readme` - -`Linaro Connect 2020 - System Device Tree & Lopper Slide Set `_ - -`Open Source Summit 2022 Slide Set `_ + lopper_intro diff --git a/tools/lopper_intro.rst b/tools/lopper_intro.rst new file mode 100644 index 0000000..d2fd976 --- /dev/null +++ b/tools/lopper_intro.rst @@ -0,0 +1,43 @@ + +.. _lopper-tool-intro: + +==================== +OpenAMP Lopper Intro +==================== + +System Device Trees (S-DT) are used to describe resources of `heterogeneous `_ embedded environments. + +Their intent is to be the industry standard method for defining how computing resources are divided into independent :ref:`runtime domains`. + +Examples of domains are + +* a computing unit, e.g. RTOS on R5s +* an operating environment at a specific execution level (e.g. `OPTEE `_) +* a virtual machine (e.g. `Xen `_) + +For those familiar with `Device Trees (DTS) `_ think of the S-DT as a combination of multiple device trees to define sub-systems. DTS' define resources seen from one address space, whereas S-DT's define the topology of the full system. + +The `Lopper Tool `_ provides a way to generate sub-system DTS' from S-DT's and manipulate, inspect or verify the S-DT for correctness. + +.. image:: ../images/tools/lopper-intro.svg + + +The `Lopper Tool `_ is a data driven tool written in Python, and supports inputs in dts, dtb and yaml format. Actions, which are used to manipulate the input data, are provided as unit operations (lops) as DTS formatted files. These are small transformation commands, inline Python source or for more complex scenarios `lopper assists `_ Python modules. + +The diagram below shows an example of three transformations performed by lopper through three independent DTS files which define the actions to perform. + +.. image:: ../images/tools/lopper-actions.svg + +Lopper is built on top of device tree tools, `Device Tree Compiler (DTC) `_ and `libfdt `_. + +Run the Lopper Demonstration as demo5 in :ref:`Docker Images`. + + +References +^^^^^^^^^^ + +`Linaro Connect 2020 - System Device Tree & Lopper Slide Set `_ + +`Open Source Summit 2022 Slide Set `_ + +`Lopper Repository `_