├── .gitignore ├── images ├── lcm.jpg ├── vrings.jpg ├── lcm_boot.jpg ├── rpmsg_flow.jpg ├── rpmsg_flags.jpg ├── rpmsg_header.jpg ├── memory_layout.jpg ├── protocol_layers.jpg ├── rpmsg_endpoint.jpg ├── vring_descriptor.jpg ├── openamp_components.jpg ├── vrings_used_buffers.jpg ├── core_to_core_interrupt.jpg ├── vring_descriptor_flags.jpg ├── vrings_used_buffers_flags.jpg └── design │ ├── img │ ├── coprocessor-rpmsg-ns.png │ ├── rproc-lcm-state-machine.png │ ├── coprocessor-rpmsg-ns-dynamic.png │ └── coprocessor-rpmsg-static-ep.png │ └── img-src │ ├── rproc-lcm-state-machine.gv │ ├── gen-graph.py │ ├── coprocessor-rpmsg-static-ep.gv │ ├── coprocessor-rpmsg-ns.gv │ └── coprocessor-rpmsg-ns-dynamic.gv ├── _static ├── images │ ├── header-bg.jpg │ ├── linaro-logo.png │ ├── strap_image.png │ ├── openAMP_LOGOMARKX.png │ ├── openAMP_combobox.png │ ├── openAMP_share_image.png │ ├── triangle_background.png │ ├── openAMP_LOGOMARKX.svg │ ├── openAMP_WORDMARKX.svg │ ├── openAMP_combox.svg │ ├── openAMP_combox_trim.svg │ ├── openAMP_combox_dark.svg │ └── openAMP_combox_dark_trim.svg └── css │ └── mystyle.css ├── requirements.txt ├── docs ├── data_structures.rst ├── index.rst ├── data_structures_content.rst ├── rpmsg_design.rst ├── remoteproc_design.rst └── porting_guide.rst ├── protocol_details ├── design_docs.rst ├── lifecyclemgmt.rst ├── index.rst ├── rpmsg.rst ├── resource_tbl.rst ├── asymmetric_mp.rst ├── components.rst ├── rpmsg_comms.rst ├── lifecyclemgmt_creation.rst ├── lifecyclemgmt_overview.rst ├── system_considerations.rst └── rpmsg_protocol.rst ├── openamp ├── meeting_notes.rst ├── index.rst ├── links.rst ├── glossary.rst └── contributing.rst ├── tools ├── index.rst └── lopper.rst ├── demos ├── index.rst ├── reference_boards.rst ├── system_reference-AMD-Xilinx.rst ├── inter_process.rst ├── system_reference-TI.rst ├── replicate_firmware.rst ├── split_mode.rst ├── linux_rpc.rst ├── system_reference-NXP.rst ├── hvl_virtio.rst ├── echo.rst ├── matrix_multiply.rst ├── rpmsg_multi_services.rst └── system_reference-ST.rst ├── _doxygen └── openamp │ ├── doxygen-awesome-openamp.js │ ├── footer.html │ ├── Doxyfile-openamp.in │ ├── header.html │ ├── doxygen-awesome-openamp.css │ └── layout.xml ├── index.rst ├── .readthedocs.yaml ├── .gitmodules ├── make.bat ├── _templates └── layout.html ├── .github └── workflows │ └── sync-submodules.yml ├── Makefile ├── LICENSE ├── conf.py └── README.md /.gitignore: -------------------------------------------------------------------------------- 1 | /.vscode 2 | /_build 3 | /.venv 4 | -------------------------------------------------------------------------------- /images/lcm.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OpenAMP/openamp-docs/HEAD/images/lcm.jpg -------------------------------------------------------------------------------- /images/vrings.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OpenAMP/openamp-docs/HEAD/images/vrings.jpg -------------------------------------------------------------------------------- /images/lcm_boot.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OpenAMP/openamp-docs/HEAD/images/lcm_boot.jpg -------------------------------------------------------------------------------- /images/rpmsg_flow.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OpenAMP/openamp-docs/HEAD/images/rpmsg_flow.jpg -------------------------------------------------------------------------------- /images/rpmsg_flags.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OpenAMP/openamp-docs/HEAD/images/rpmsg_flags.jpg -------------------------------------------------------------------------------- /images/rpmsg_header.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OpenAMP/openamp-docs/HEAD/images/rpmsg_header.jpg -------------------------------------------------------------------------------- /images/memory_layout.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OpenAMP/openamp-docs/HEAD/images/memory_layout.jpg -------------------------------------------------------------------------------- /images/protocol_layers.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OpenAMP/openamp-docs/HEAD/images/protocol_layers.jpg -------------------------------------------------------------------------------- /images/rpmsg_endpoint.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OpenAMP/openamp-docs/HEAD/images/rpmsg_endpoint.jpg -------------------------------------------------------------------------------- /_static/images/header-bg.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OpenAMP/openamp-docs/HEAD/_static/images/header-bg.jpg -------------------------------------------------------------------------------- /images/vring_descriptor.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OpenAMP/openamp-docs/HEAD/images/vring_descriptor.jpg -------------------------------------------------------------------------------- /_static/images/linaro-logo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OpenAMP/openamp-docs/HEAD/_static/images/linaro-logo.png -------------------------------------------------------------------------------- /_static/images/strap_image.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OpenAMP/openamp-docs/HEAD/_static/images/strap_image.png -------------------------------------------------------------------------------- /images/openamp_components.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OpenAMP/openamp-docs/HEAD/images/openamp_components.jpg -------------------------------------------------------------------------------- /images/vrings_used_buffers.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OpenAMP/openamp-docs/HEAD/images/vrings_used_buffers.jpg -------------------------------------------------------------------------------- /images/core_to_core_interrupt.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OpenAMP/openamp-docs/HEAD/images/core_to_core_interrupt.jpg -------------------------------------------------------------------------------- /images/vring_descriptor_flags.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OpenAMP/openamp-docs/HEAD/images/vring_descriptor_flags.jpg -------------------------------------------------------------------------------- /_static/images/openAMP_LOGOMARKX.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OpenAMP/openamp-docs/HEAD/_static/images/openAMP_LOGOMARKX.png -------------------------------------------------------------------------------- /_static/images/openAMP_combobox.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OpenAMP/openamp-docs/HEAD/_static/images/openAMP_combobox.png -------------------------------------------------------------------------------- /images/vrings_used_buffers_flags.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OpenAMP/openamp-docs/HEAD/images/vrings_used_buffers_flags.jpg -------------------------------------------------------------------------------- /_static/images/openAMP_share_image.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OpenAMP/openamp-docs/HEAD/_static/images/openAMP_share_image.png -------------------------------------------------------------------------------- /_static/images/triangle_background.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OpenAMP/openamp-docs/HEAD/_static/images/triangle_background.png -------------------------------------------------------------------------------- /images/design/img/coprocessor-rpmsg-ns.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OpenAMP/openamp-docs/HEAD/images/design/img/coprocessor-rpmsg-ns.png -------------------------------------------------------------------------------- /images/design/img/rproc-lcm-state-machine.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OpenAMP/openamp-docs/HEAD/images/design/img/rproc-lcm-state-machine.png -------------------------------------------------------------------------------- /images/design/img/coprocessor-rpmsg-ns-dynamic.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OpenAMP/openamp-docs/HEAD/images/design/img/coprocessor-rpmsg-ns-dynamic.png -------------------------------------------------------------------------------- /images/design/img/coprocessor-rpmsg-static-ep.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OpenAMP/openamp-docs/HEAD/images/design/img/coprocessor-rpmsg-static-ep.png -------------------------------------------------------------------------------- /requirements.txt: -------------------------------------------------------------------------------- 1 | sphinxcontrib-plantuml 2 | sphinx_rtd_theme 3 | sphinx 4 | rst2pdf 5 | myst_parser 6 | sphinxcontrib.jquery 7 | sphinxcontrib-doxylink 8 | breathe -------------------------------------------------------------------------------- /docs/data_structures.rst: -------------------------------------------------------------------------------- 1 | Data Structures 2 | =============== 3 | 4 | .. toctree:: 5 | :maxdepth: 1 6 | :caption: Contents: 7 | 8 | ./data_structures_content 9 | 10 | -------------------------------------------------------------------------------- /protocol_details/design_docs.rst: -------------------------------------------------------------------------------- 1 | OpenAMP Design Docs 2 | =================== 3 | 4 | .. toctree:: 5 | :maxdepth: 1 6 | :caption: Contents: 7 | 8 | ../docs/data_structures 9 | ../docs/remoteproc_design 10 | ../docs/rpmsg_design 11 | 12 | -------------------------------------------------------------------------------- /openamp/meeting_notes.rst: -------------------------------------------------------------------------------- 1 | .. _meeting-notes-work-label: 2 | 3 | ============= 4 | Meeting Notes 5 | ============= 6 | 7 | Meeting_Notes_ 8 | 9 | .. _Meeting_Notes: https://github.com/OpenAMP/open-amp/wiki/Meeting-Notes 10 | 11 | TODO - Move notes to google doc drive? It may be arduous to post notes to this page -------------------------------------------------------------------------------- /tools/index.rst: -------------------------------------------------------------------------------- 1 | 2 | .. _tools_label: 3 | 4 | OpenAMP Supporting Tools 5 | ========================= 6 | 7 | .. toctree:: 8 | :maxdepth: 2 9 | :caption: Contents: 10 | 11 | lopper 12 | ../lopper/demos/openamp/README.md 13 | 14 | * Run the Lopper Demonstration as demo5 in :ref:`Docker Images`. 15 | -------------------------------------------------------------------------------- /demos/index.rst: -------------------------------------------------------------------------------- 1 | 2 | .. _demos-reference-samples: 3 | 4 | OpenAMP Samples and Demos 5 | ========================= 6 | 7 | .. toctree:: 8 | :maxdepth: 2 9 | :caption: Contents: 10 | 11 | echo 12 | rpmsg_multi_services 13 | matrix_multiply 14 | linux_rpc 15 | hvl_virtio 16 | split_mode 17 | replicate_firmware 18 | -------------------------------------------------------------------------------- /docs/index.rst: -------------------------------------------------------------------------------- 1 | .. OpenAMP documentation master file, created by 2 | sphinx-quickstart on Wed Oct 5 10:21:26 2022. 3 | You can adapt this file completely to your liking, but it should at least 4 | contain the root `toctree` directive. 5 | 6 | OpenAMP Libraries User Guide 7 | =========================== 8 | 9 | .. toctree:: 10 | :maxdepth: 1 11 | :caption: Contents: 12 | 13 | porting_guide 14 | 15 | -------------------------------------------------------------------------------- /openamp/index.rst: -------------------------------------------------------------------------------- 1 | .. OpenAMP documentation master file, created by 2 | sphinx-quickstart on Wed Oct 5 10:21:26 2022. 3 | You can adapt this file completely to your liking, but it should at least 4 | contain the root `toctree` directive. 5 | 6 | OpenAMP Project 7 | =============== 8 | 9 | .. toctree:: 10 | :maxdepth: 2 11 | :caption: Contents: 12 | 13 | overview 14 | contributing 15 | links 16 | -------------------------------------------------------------------------------- /_doxygen/openamp/doxygen-awesome-openamp.js: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2021 Nordic Semiconductor ASA 3 | * SPDX-License-Identifier: Apache-2.0 4 | */ 5 | 6 | window.addEventListener('DOMContentLoaded', (event) => { 7 | /* re-inject project version at a custom location */ 8 | let version = document.getElementById('projectnumber').innerText 9 | let titleTable = document.querySelector('#titlearea table'); 10 | let cell = titleTable.insertRow(1).insertCell(0); 11 | cell.innerHTML = '
' + version + '
'; 12 | }); 13 | -------------------------------------------------------------------------------- /images/design/img-src/rproc-lcm-state-machine.gv: -------------------------------------------------------------------------------- 1 | // Remoteproc Life Cycle Management State Machine 2 | 3 | digraph G { 4 | rankdir="LR" 5 | st_offline [label="Offline"] 6 | st_configured [label="Configured"] 7 | st_ready [label="Ready"] 8 | st_running [label="Running"] 9 | st_stopped [label="Stopped"] 10 | 11 | st_offline -> st_configured 12 | st_configured -> st_ready 13 | st_ready -> st_running 14 | st_ready -> st_stopped 15 | st_stopped -> st_offline 16 | st_running -> st_stopped 17 | 18 | {rank=same; st_configured; st_ready; st_running} 19 | } 20 | -------------------------------------------------------------------------------- /index.rst: -------------------------------------------------------------------------------- 1 | .. OpenAMP documentation master file, created by 2 | sphinx-quickstart on Wed Oct 5 10:21:26 2022. 3 | You can adapt this file completely to your liking, but it should at least 4 | contain the root `toctree` directive. 5 | 6 | Welcome to the OpenAMP Project Documentation 7 | ============================================ 8 | 9 | .. toctree:: 10 | :maxdepth: 2 11 | :caption: Contents: 12 | 13 | openamp/index 14 | demos/index 15 | demos/reference_boards 16 | tools/index 17 | protocol_details/index 18 | docs/porting_guide 19 | openamp/glossary 20 | -------------------------------------------------------------------------------- /protocol_details/lifecyclemgmt.rst: -------------------------------------------------------------------------------- 1 | .. _lcm-work-label: 2 | 3 | ======================================== 4 | Life Cycle Management through RemoteProc 5 | ======================================== 6 | 7 | The LCM (Life Cycle Management) component of OpenAMP is known as remoteproc. Remoteproc APIs 8 | provided by the OpenAMP Framework allow software applications running on the host processor to 9 | manage the life cycle of a remote processor and its software context. A complete description of the 10 | remoteproc workflow and APIs are provided. 11 | 12 | .. toctree:: 13 | :maxdepth: 2 14 | 15 | lifecyclemgmt_overview 16 | lifecyclemgmt_creation 17 | resource_tbl 18 | -------------------------------------------------------------------------------- /.readthedocs.yaml: -------------------------------------------------------------------------------- 1 | version: 2 2 | formats: all 3 | sphinx: 4 | configuration: ./conf.py 5 | build: 6 | os: "ubuntu-22.04" 7 | tools: 8 | python: "3.10" 9 | apt_packages: 10 | - cmake 11 | - libhugetlbfs-dev 12 | - libsysfs-dev 13 | jobs: 14 | post_checkout: 15 | - git submodule sync 16 | - git submodule update --init --force --recursive 17 | post_install: 18 | - python -m pip install --exists-action=w --no-cache-dir -r requirements.txt 19 | pre_build: 20 | - echo "READTHEDOCS_OUTPUT=$READTHEDOCS_OUTPUT" 21 | - make BUILDDIR=$READTHEDOCS_OUTPUT doxygen 22 | post_build: 23 | - make BUILDDIR=$READTHEDOCS_OUTPUT doxygen_copy 24 | -------------------------------------------------------------------------------- /.gitmodules: -------------------------------------------------------------------------------- 1 | [submodule "open-amp"] 2 | path = open-amp 3 | url = https://github.com/OpenAMP/open-amp.git 4 | [submodule "hypervisorless_virtio_zcu102"] 5 | path = hypervisorless_virtio_zcu102 6 | url = https://github.com/danmilea/hypervisorless_virtio_zcu102.git 7 | [submodule "lopper"] 8 | path = lopper 9 | url = https://github.com/devicetree-org/lopper.git 10 | [submodule "openamp-system-reference"] 11 | path = openamp-system-reference 12 | url = https://github.com/OpenAMP/openamp-system-reference.git 13 | [submodule "libmetal"] 14 | path = libmetal 15 | url = https://github.com/OpenAMP/libmetal.git 16 | [submodule "awesome"] 17 | path = _doxygen/awesome 18 | url = https://github.com/jothepro/doxygen-awesome-css.git 19 | -------------------------------------------------------------------------------- /openamp/links.rst: -------------------------------------------------------------------------------- 1 | ===== 2 | Links 3 | ===== 4 | 5 | - The OpenAMP project home page: https://www.openampproject.org/ 6 | - The OpenAMP mailing lists: https://lists.openampproject.org/mailman3/lists 7 | Note: Before getting the mailing lists, we used this 8 | `OpenAMP Google Group `_. The Google Group is only 9 | listed here for reference to older content. Please use the mailing lists. 10 | - The OpenAMP Source Repositories: https://github.com/OpenAMP 11 | - `OpenAMP and Heterogenous Processing Project Webinar (December 2022) `_ 12 | - `OpenAMP Elevator Pitch Slideset (2024) `_ 13 | -------------------------------------------------------------------------------- /protocol_details/index.rst: -------------------------------------------------------------------------------- 1 | .. OpenAMP documentation master file, created by 2 | sphinx-quickstart on Wed Oct 5 10:21:26 2022. 3 | You can adapt this file completely to your liking, but it should at least 4 | contain the root `toctree` directive. 5 | 6 | OpenAMP Design Details 7 | ====================== 8 | 9 | This section provides an introduction to 10 | `Asymmetric Multiprocessing (AMP) `_ and 11 | detailed design of the OpenAMP architecture components. For an introduction please refer to 12 | :ref:`OpenAMP Architecture` section. 13 | 14 | .. toctree:: 15 | :maxdepth: 3 16 | :caption: Contents: 17 | 18 | asymmetric_mp 19 | components 20 | system_considerations 21 | design_docs 22 | -------------------------------------------------------------------------------- /demos/reference_boards.rst: -------------------------------------------------------------------------------- 1 | 2 | OpenAMP Reference Boards 3 | ======================== 4 | 5 | :ref:`OpenAMP Samples and Demos` are provided on a number of boards and 6 | virtual machines to demonstrate the implementation of each. 7 | 8 | In general the OpenAMP feature being exemplified is found in the 9 | `OpenAMP source repository `_ through a 10 | number of examples. Additional supporting code is located in the 11 | `OpenAMP System Reference examples `_ 12 | 13 | .. toctree:: 14 | :maxdepth: 2 15 | 16 | docker_images 17 | system_reference-AMD-Xilinx 18 | system_reference-ST 19 | system_reference-NXP 20 | system_reference-TI 21 | inter_process 22 | -------------------------------------------------------------------------------- /_doxygen/openamp/footer.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 10 | 11 | 12 |
13 | $generatedby doxygen $doxygenversion 14 |
15 | 16 | 17 | 18 | -------------------------------------------------------------------------------- /demos/system_reference-AMD-Xilinx.rst: -------------------------------------------------------------------------------- 1 | .. _demos-AMD-work-label: 2 | 3 | ============================================================= 4 | System Reference Samples and Demos on the AMD-Xilinx platform 5 | ============================================================= 6 | 7 | The following Reference Samples and Demos are implemented using the 8 | 9 | * AMD `ZCU102 Evaluation Board `_ 10 | * `QEMU `_ ZCU102 Virtual Machine in the :ref:`Docker Images References` 11 | 12 | .. toctree:: 13 | :maxdepth: 2 14 | 15 | ../openamp-system-reference/examples/linux/rpmsg-echo-test/README.md 16 | ../openamp-system-reference/examples/linux/rpmsg-mat-mul/README.md 17 | ../openamp-system-reference/examples/linux/rpmsg-proxy-app/README.md 18 | -------------------------------------------------------------------------------- /openamp/glossary.rst: -------------------------------------------------------------------------------- 1 | ======== 2 | Glossary 3 | ======== 4 | 5 | .. csv-table:: Glossary 6 | :header: "Acronym", "Description" 7 | :widths: 20, 200 8 | 9 | AMP, `Asymmentric Multiprocessing `_ 10 | API, Application Interface 11 | GPL, `GNU General Public License `_ 12 | IPC, `Inter-Processor Communications `_ 13 | LCM, Life-Cycle Management 14 | RPC, :ref:`Remote Procedure Calls (RPC)` 15 | RTOS, Real Time Operating System 16 | RPMsg, `Remote Processor Messaging `_ 17 | SMP, `Symmetric Multiprocessing (SMP) `_ 18 | SoC, System on Chip 19 | Virtio, Virtual Input Output 20 | -------------------------------------------------------------------------------- /make.bat: -------------------------------------------------------------------------------- 1 | @ECHO OFF 2 | 3 | pushd %~dp0 4 | 5 | REM Command file for Sphinx documentation 6 | 7 | if "%SPHINXBUILD%" == "" ( 8 | set SPHINXBUILD=sphinx-build 9 | ) 10 | set SOURCEDIR=. 11 | set BUILDDIR=_build 12 | 13 | if "%1" == "" goto help 14 | 15 | %SPHINXBUILD% >NUL 2>NUL 16 | if errorlevel 9009 ( 17 | echo. 18 | echo.The 'sphinx-build' command was not found. Make sure you have Sphinx 19 | echo.installed, then set the SPHINXBUILD environment variable to point 20 | echo.to the full path of the 'sphinx-build' executable. Alternatively you 21 | echo.may add the Sphinx directory to PATH. 22 | echo. 23 | echo.If you don't have Sphinx installed, grab it from 24 | echo.http://sphinx-doc.org/ 25 | exit /b 1 26 | ) 27 | 28 | %SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% 29 | goto end 30 | 31 | :help 32 | %SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% 33 | 34 | :end 35 | popd 36 | -------------------------------------------------------------------------------- /protocol_details/rpmsg.rst: -------------------------------------------------------------------------------- 1 | .. _rpmsg-protocol-work-label: 2 | 3 | ========================================================= 4 | Inter Process Communications (IPC) through RPMsg Protocol 5 | ========================================================= 6 | 7 | In asymmetric multiprocessor systems, the most common way for different cores to cooperate is to 8 | use a shared memory-based communication. There are many custom implementations, which means that 9 | the considered systems cannot be directly interconnected. Therefore, OpenAMP's aim is to offer a 10 | standardization of this communication based on existing components (RPMsg, VirtIO). 11 | 12 | OpenAMP's implementation of RPMsg is through shared memory utlizing a ring buffer, with optional 13 | inter-core interrupts, using Virtio devices as the system level abstraction layer. 14 | 15 | 16 | .. toctree:: 17 | :maxdepth: 2 18 | 19 | rpmsg_protocol 20 | rpmsg_comms 21 | -------------------------------------------------------------------------------- /_static/css/mystyle.css: -------------------------------------------------------------------------------- 1 | @import "theme.css"; 2 | 3 | /* override table no-wrap */ 4 | .wy-table-responsive table td, .wy-table-responsive table th { 5 | white-space: normal; 6 | } 7 | 8 | .wy-side-nav-search { 9 | background: #000000; 10 | background-image: url('../images/triangle_background.png'); 11 | height: 280px; 12 | } 13 | 14 | .wy-nav-top { 15 | background: #000000; 16 | background-image: url('../images/triangle_background.png'); 17 | } 18 | 19 | .wy-side-nav-search .wy-dropdown>a img.logo, .wy-side-nav-search>a img.logo { 20 | height: 150px; 21 | width: 150px; 22 | } 23 | 24 | .wy-side-nav-search>div.version { 25 | color: #ffffff; 26 | } 27 | 28 | .wy-menu-vertical header, .wy-menu-vertical p.caption { 29 | color: #e86060; 30 | } 31 | 32 | /* The version header inserted by RTDs */ 33 | .rst-versions .rst-current-version, .rst-versions .rst-current-version .fa { 34 | color: #201010; 35 | background-color: #e86060; 36 | } 37 | -------------------------------------------------------------------------------- /_static/images/openAMP_LOGOMARKX.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 5 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | -------------------------------------------------------------------------------- /openamp/contributing.rst: -------------------------------------------------------------------------------- 1 | .. _openamp-maintenance-work-label: 2 | 3 | =================================== 4 | Contributing to the OpenAMP Project 5 | =================================== 6 | 7 | You are encouraged to contribute to the OpenAMP project to help create a successful solution 8 | through a vibrant and engaged community. 9 | 10 | High-level development process and workflow are provided in the project's 11 | `Governance Page `_. 12 | 13 | You can contribute: 14 | 15 | * through pull requests, directly to the main `OpenAMP libraries `_. 16 | * by participating in openAMP meetings. 17 | * by proposing your platform as a reference platform if compatible with the open-amp system 18 | reference demonstrations. 19 | 20 | Any specific contribution requirements will be given in the "How to contribute" section of the 21 | repository's README. 22 | 23 | If you want to contribute by porting OpenAMP to your platform read more about OpenAMP porting 24 | :ref:`here`. 25 | -------------------------------------------------------------------------------- /_templates/layout.html: -------------------------------------------------------------------------------- 1 | {% extends "!layout.html" %} 2 | {% block document %} 3 | {% if is_release %} 4 |
5 | The latest development version 6 | of this page may be more current than this released {{ version }} version. 7 |
8 | {% else %} 9 |
10 | This is the documentation for the latest (main) development branch. 11 | If you are looking for the documentation of previous releases, use 12 | the drop-down menu on the left and select the desired version. 13 |
14 | {% endif %} 15 | {{ super() }} 16 | {% endblock %} 17 | {% block menu %} 18 | {{ super() }} 19 | {% if reference_links %} 20 |
21 |

Reference

22 |
    23 | {% for title, url in reference_links.items() %} 24 |
  • 25 | {{ title }} 26 |
    • 27 | {% endfor %} 28 |
29 |
30 | {% endif %} 31 | {% endblock %} 32 | -------------------------------------------------------------------------------- /demos/inter_process.rst: -------------------------------------------------------------------------------- 1 | .. _inter-process-reference-label: 2 | 3 | =================================== 4 | Running Demos as Processes on Linux 5 | =================================== 6 | 7 | The `OpenAMP project examples `_ 8 | are intended to execute on the remote of a reference board but can also be demonstrated by 9 | implementing as a process on the main controller, effectively emulating a remote. 10 | 11 | This can be useful for demonstration purposes, but can also be leveraged for component testing, even 12 | as part of a continuous integration setup. 13 | 14 | Effectively the `OpenAMP Library `_ and 15 | `reference examples `_ are built for 16 | the main controller system along with the 17 | `main controller examples `_. 18 | 19 | To build and execute on a Linux system, refer to the 20 | :ref:`example to compile OpenAMP for communication between Linux processes`. 21 | -------------------------------------------------------------------------------- /.github/workflows/sync-submodules.yml: -------------------------------------------------------------------------------- 1 | name: 'Submodules Sync' 2 | 3 | on: 4 | # Allows you to run this workflow manually from the Actions tab or through HTTP API 5 | workflow_dispatch: 6 | # run on Sunday at 4:10 AM UTC (11:10 PM US eastern, 8:10 PM US western) 7 | schedule: 8 | - cron: '10 4 * * 0' 9 | 10 | jobs: 11 | sync: 12 | name: 'Submodules Sync' 13 | runs-on: ubuntu-latest 14 | 15 | # Use the Bash shell regardless whether the GitHub Actions runner is ubuntu-latest, macos-latest, or windows-latest 16 | defaults: 17 | run: 18 | shell: bash 19 | 20 | steps: 21 | # Checkout the repository to the GitHub Actions runner 22 | - name: Checkout 23 | uses: actions/checkout@v3 24 | with: 25 | token: ${{ secrets.GITHUB_TOKEN }} 26 | submodules: true 27 | 28 | # Update references 29 | - name: Git Sumbodule Update 30 | run: | 31 | git pull --recurse-submodules 32 | git submodule update --remote --recursive 33 | 34 | - name: Commit update 35 | run: | 36 | git config --global user.name 'GH actions' 37 | git config --global user.email 'bot@noreply.github.com' 38 | git remote set-url origin https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }} 39 | git commit -am "Auto updated submodule references" && git push || echo "No changes to commit" 40 | -------------------------------------------------------------------------------- /_doxygen/openamp/Doxyfile-openamp.in: -------------------------------------------------------------------------------- 1 | # Doxygen level overrides when building as part of OpenAMP-docs 2 | 3 | # Test cmake rebuild 4 | 5 | GENERATE_TREEVIEW = YES 6 | TREEVIEW_WIDTH = 400 7 | 8 | # Maybe go in base, or also in base? 9 | ALWAYS_DETAILED_SEC = YES 10 | JAVADOC_AUTOBRIEF = YES 11 | QT_AUTOBRIEF = YES 12 | 13 | HTML_DYNAMIC_MENUS = YES 14 | HTML_DYNAMIC_SECTIONS = NO 15 | 16 | DISABLE_INDEX = NO 17 | FULL_SIDEBAR = NO 18 | HTML_COLORSTYLE = LITE 19 | HTML_EXTRA_STYLESHEET = \ 20 | @OAMP_DOX_DIR@/../awesome/doxygen-awesome.css \ 21 | @OAMP_DOX_DIR@/../awesome/doxygen-awesome-sidebar-only.css \ 22 | @OAMP_DOX_DIR@/doxygen-awesome-openamp.css 23 | 24 | HTML_EXTRA_FILES = \ 25 | @OAMP_DOX_DIR@/doxygen-awesome-openamp.js \ 26 | @OAMP_DOX_DIR@/../../_static/images/triangle_background.png 27 | 28 | # For the toggle button (do we want it?) 29 | # even w/o the toggle button the page honors the system level preference 30 | HTML_EXTRA_STYLESHEET += \ 31 | @OAMP_DOX_DIR@/../awesome/doxygen-awesome-sidebar-only-darkmode-toggle.css 32 | HTML_EXTRA_FILES += \ 33 | @OAMP_DOX_DIR@/../awesome/doxygen-awesome-darkmode-toggle.js 34 | 35 | HTML_HEADER = @OAMP_DOX_DIR@/header.html 36 | HTML_FOOTER = @OAMP_DOX_DIR@/footer.html 37 | LAYOUT_FILE = @OAMP_DOX_DIR@/layout.xml 38 | 39 | PROJECT_LOGO = \ 40 | @OAMP_DOX_DIR@/../../_static/images/openAMP_combox_dark_trim.svg 41 | 42 | PROJECT_NUMBER = "@VERSION_NAME@" 43 | -------------------------------------------------------------------------------- /images/design/img-src/gen-graph.py: -------------------------------------------------------------------------------- 1 | import argparse 2 | import os 3 | import pydot 4 | import sys 5 | import warnings 6 | 7 | def gen_graph_from_gv(ifile, odir, oformat="png"): 8 | (graph,) = pydot.graph_from_dot_file(ifile) 9 | gen_graph_func = getattr(graph, "write_" + oformat) 10 | filename = os.path.basename(ifile) 11 | ofile = odir + "/" + os.path.splitext(filename)[0] + "." + oformat 12 | gen_graph_func(ofile) 13 | 14 | parser = argparse.ArgumentParser(description='Process some integers.') 15 | parser.add_argument('-i', "--infile", action="append", 16 | help="graphviz file path") 17 | parser.add_argument('-o', '--outdir', 18 | help='sum the integers (default: find the max)') 19 | parser.add_argument('-f', '--outformat', default="png", 20 | help='output image format (default: png)') 21 | 22 | args = parser.parse_args() 23 | 24 | # Image source directory 25 | img_src_dir = os.path.dirname(os.path.realpath(sys.argv[0])) 26 | 27 | img_files = [] 28 | if args.infile: 29 | for f in args.infile: 30 | if not os.path.isfile(f): 31 | f = img_src_dir + "/" + f 32 | if not os.path.isfile(f): 33 | warnings.warn("Input file: " + f + " doesn't exist.") 34 | else: 35 | img_files.append(f) 36 | else: 37 | for f in os.listdir(img_src_dir): 38 | if f.endswith(".gv"): 39 | img_files.append(img_src_dir + "/" + f) 40 | 41 | if not img_files: 42 | sys.exit("ERROR: no found image files.") 43 | 44 | oformat = args.outformat 45 | 46 | if args.outdir: 47 | odir = args.outdir 48 | if not os.path.isdir(odir): 49 | sys.exit("--outdir " + odir + "doesn't exist") 50 | else: 51 | odir = os.path.dirname(img_src_dir) + "/img" 52 | 53 | for f in img_files: 54 | print("Generating " + oformat + " for " + f + " ...") 55 | gen_graph_from_gv(f, odir, oformat) 56 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | # Minimal makefile for Sphinx documentation 2 | # 3 | 4 | # You can set these variables from the command line, and also 5 | # from the environment for the first two. 6 | SPHINXOPTS ?= 7 | SPHINXBUILD ?= sphinx-build 8 | READTHEDOCS_VERSION_NAME ?= "desk check" 9 | SOURCEDIR = . 10 | BUILDDIR = _build 11 | 12 | #IMG_SRC_DIR = uml 13 | #IMG_TGTS = $(patsubst %.txt,%.eps,$(wildcard $(IMG_SRC_DIR)/*.txt)) 14 | 15 | # Put it first so that "make" without argument is like "make help". 16 | help: 17 | @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) 18 | 19 | .PHONY: help clean doxygen doxygen_libmetal doxygen_openamp doxygen_copy 20 | 21 | .NOTPARALLEL: 22 | 23 | #%.txt:; 24 | 25 | #%.eps: %.txt 26 | #plantuml -config uml/plantuml.cfg -o ../_build/html/uml/ uml/*.txt 27 | 28 | #images: ${IMG_TGTS}; 29 | 30 | doxygen: doxygen_libmetal doxygen_openamp 31 | 32 | doxygen_libmetal: 33 | cmake -B${BUILDDIR}/libmetal -DVERSION_NAME=${READTHEDOCS_VERSION_NAME} \ 34 | -DWITH_DOC=true libmetal 35 | make -C ${BUILDDIR}/libmetal doc 36 | 37 | doxygen_openamp: 38 | cmake -B${BUILDDIR}/openamp -DVERSION_NAME=${READTHEDOCS_VERSION_NAME} \ 39 | -DWITH_LIBMETAL_FIND=false -DWITH_DOC=true open-amp 40 | make -C ${BUILDDIR}/openamp doc 41 | 42 | # using hard coded name here to avoid bad things if BUILDDIR is ever empty or / 43 | clean: 44 | rm -rf _build/* 45 | 46 | html: doxygen html-fast doxygen_copy 47 | @echo Done with full html target 48 | 49 | doxygen_copy: 50 | rm -rf ${BUILDDIR}/doxygen || true 51 | mkdir -p ${BUILDDIR}/html/doxygen/libmetal 52 | mkdir -p ${BUILDDIR}/html/doxygen/openamp 53 | cp -a ${BUILDDIR}/libmetal/doc/html/* ${BUILDDIR}/html/doxygen/libmetal/ 54 | cp -a ${BUILDDIR}/openamp/doc/html/* ${BUILDDIR}/html/doxygen/openamp/ 55 | 56 | html-fast: 57 | @$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) 58 | 59 | # Catch-all target: route all unknown targets to Sphinx using the new 60 | # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). 61 | %: #images 62 | @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) 63 | -------------------------------------------------------------------------------- /_doxygen/openamp/header.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | $projectname: $title 10 | $title 11 | 12 | 13 | 14 | 15 | 16 | $treeview 17 | $search 18 | $mathjax 19 | 20 | $extrastylesheet 21 | 24 | 25 | 26 |
27 | 28 | 29 |
30 | 31 | 32 | 33 | 34 | 39 | 40 | 41 | 47 | 48 | 49 | 50 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 |
42 |
$projectname 43 |  $projectnumber 44 |
45 |
$projectbrief
46 | 		51 |
$projectbrief
52 | 		$searchbox
63 |
64 | 65 | 66 | -------------------------------------------------------------------------------- /tools/lopper.rst: -------------------------------------------------------------------------------- 1 | =================== 2 | OpenAMP Lopper Tool 3 | =================== 4 | 5 | .. _lopper-tool-intro: 6 | 7 | *************** 8 | Lopper Intro 9 | *************** 10 | 11 | System Device Trees (S-DT) are used to describe resources of `heterogeneous `_ embedded environments. 12 | 13 | Their intent is to be the industry standard method for defining how computing resources are divided into independent :ref:`runtime domains`. 14 | 15 | Examples of domains are 16 | 17 | * a computing unit, e.g. RTOS on R5s 18 | * an operating environment at a specific execution level (e.g. `OPTEE `_) 19 | * a virtual machine (e.g. `Xen `_) 20 | 21 | 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. 22 | 23 | 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. 24 | 25 | .. image:: ../images/tools/lopper-intro.svg 26 | 27 | 28 | 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. 29 | 30 | The diagram below shows an example of three transformations performed by lopper through three independent DTS files which define the actions to perform. 31 | 32 | .. image:: ../images/tools/lopper-actions.svg 33 | 34 | Lopper is built on top of device tree tools, `Device Tree Compiler (DTC) `_ and `libfdt `_. 35 | 36 | 37 | References 38 | ^^^^^^^^^^ 39 | 40 | :ref:`Lopper Architecture Readme` 41 | 42 | `Linaro Connect 2020 - System Device Tree & Lopper Slide Set `_ 43 | 44 | `Open Source Summit 2022 Slide Set `_ 45 | -------------------------------------------------------------------------------- /protocol_details/resource_tbl.rst: -------------------------------------------------------------------------------- 1 | .. _resource-table: 2 | 3 | ============== 4 | Resource Table 5 | ============== 6 | 7 | Overview 8 | ******** 9 | 10 | The resource table is a key part of resource assignment of remoteproc life cycle management. 11 | 12 | The table consists of a header detailing a version, number of resource entries and an array pointing 13 | at the offset location of each entry. Directly following the header are the resource entries 14 | themselves, each of which has a 32 bit type. These in remote context will likely be memory carveouts 15 | for locations of parts of the remote system and virtio device definitions. 16 | 17 | +--------------+--------------------------------------------------------------------------------+ 18 | | Item | Description | 19 | +==============+================================================================================+ 20 | | ver | RemoteProc version number | 21 | +--------------+--------------------------------------------------------------------------------+ 22 | | num | Number of resource entries following the header | 23 | +--------------+--------------------------------------------------------------------------------+ 24 | | reserved | Unused but should be set to zero until used | 25 | +--------------+--------------------------------------------------------------------------------+ 26 | | offset | Array of values pointing to the offset location of each resource entry | 27 | +--------------+--------------------------------------------------------------------------------+ 28 | | resources | Structures which define each of the resource entries (up to num count), at | 29 | | | given offset, with each starting with a type (fw_resource_type) so the parser | 30 | | | can correctly extract the information. | 31 | +--------------+--------------------------------------------------------------------------------+ 32 | 33 | The fw_resource_type's are listed in the 34 | `remoteproc header `_. 35 | 36 | Compatibility with Linux kernel 37 | ------------------------------- 38 | 39 | The resource table should maintain compatibility with that of 40 | `remoteproc `_. 41 | 42 | :: 43 | 44 | Evolution should be done in cooperation with Linux remoteproc community. 45 | 46 | Related documentation can be found under the Linux kernel's remoteproc documentation: 47 | `Binary Firmware Structure `_. 48 | -------------------------------------------------------------------------------- /docs/data_structures_content.rst: -------------------------------------------------------------------------------- 1 | Remoteproc data structures 2 | =========================== 3 | 4 | Remoteproc 5 | ---------- 6 | 7 | .. doxygenstruct:: remoteproc 8 | :members: 9 | 10 | Refer also :openamp_doc_link:`remoteproc ` documentation and `remoteproc code implementation `_. 11 | 12 | Virtio Structure for Remoteproc 13 | ------------------------------- 14 | 15 | .. doxygenstruct:: remoteproc_virtio 16 | :members: 17 | 18 | Refer also :openamp_doc_link:`remoteproc_virtio ` documentation and `remoteproc code implementation `_. 19 | 20 | Virtio Data Structures 21 | =========================== 22 | 23 | Virtio Device 24 | ------------- 25 | 26 | .. doxygenstruct:: virtio_device 27 | :members: 28 | 29 | Refer also :openamp_doc_link:`virtio_device ` documentation and `virtio_device code implementation `_. 30 | 31 | Virtqueue local context 32 | ----------------------- 33 | 34 | .. doxygenstruct:: virtqueue 35 | :members: 36 | 37 | Refer also :openamp_doc_link:`virtqueue ` documentation and `virtqueue code implementation `_. 38 | 39 | 40 | Shared virtqueue structure 41 | -------------------------- 42 | 43 | Representation of a shared virtqueue structure defined in `Virtual I/O Device (VIRTIO) Standard virtqueue `_. 44 | 45 | .. doxygenstruct:: vring 46 | :members: 47 | 48 | Refer also :openamp_doc_link:`vring ` documentation and `vring code implementation `_. 49 | 50 | 51 | RPMsg virtio Data struct 52 | =========================== 53 | 54 | .. doxygenstruct:: rpmsg_virtio_device 55 | :members: 56 | 57 | Refer also :openamp_doc_link:`rpmsg_virtio_device ` documentation and `rpmsg_virtio_device code implementation `_. 58 | 59 | 60 | RPMsg Data struct 61 | ================= 62 | 63 | .. doxygenstruct:: rpmsg_device 64 | :members: 65 | 66 | Refer also :openamp_doc_link:`rpmsg_device ` documentation and `rpmsg_device code implementation `_. 67 | 68 | 69 | Local RPMsg Endpoint 70 | -------------------- 71 | 72 | .. doxygenstruct:: rpmsg_endpoint 73 | :members: 74 | 75 | Refer also :openamp_doc_link:`rpmsg_endpoint ` documentation and `rpmsg_endpoint code implementation `_. 76 | -------------------------------------------------------------------------------- /demos/system_reference-TI.rst: -------------------------------------------------------------------------------- 1 | .. _reference_board_TI: 2 | 3 | ================================== 4 | Texas Instruments Reference Boards 5 | ================================== 6 | 7 | A number of the `OpenAMP project examples `_ 8 | can be executed on TI Reference boards. 9 | 10 | The `Zephyr `_ demo 11 | `OpenAMP using resource table `_ 12 | can be built for the following boards: 13 | 14 | +--------------------------------------------------------+------------------------------+------------------------+ 15 | | Board | Zephyr Identifier | Deploy Firmware Name | 16 | +========================================================+==============================+========================+ 17 | | `TI SK-AM64B | ``sk_am64/am6442/m4`` | ``am64-mcu-m4f0_0-fw`` | 18 | | `_ | | | 19 | +--------------------------------------------------------+------------------------------+------------------------+ 20 | | `BeagleBoard PocketBeagle 2 | ``sk_am64/am6442/m4`` | ``am64-mcu-m4f0_0-fw`` | 21 | | `_ | | | 22 | +--------------------------------------------------------+------------------------------+------------------------+ 23 | 24 | Use the Zephyr `Getting Started Guide `_ 25 | to setup the build environment. Then build the OpenAMP example firmware with: 26 | 27 | .. code-block:: console 28 | 29 | west build -p -b samples/subsys/ipc/openamp_rsc_table 30 | 31 | This will produce a firmware named ``zephyr_openamp_rsc_table.elf`` which can be deployed to the 32 | board. Then copy or symlink it to the expected name in the firmware directory: 33 | 34 | .. code-block:: console 35 | 36 | ln -s zephyr_openamp_rsc_table.elf /lib/firmware/ 37 | 38 | Either restart the board so the kernel can load it on boot, or restart the remote processor manually: 39 | 40 | .. code-block:: console 41 | 42 | # check remote processor state 43 | cat /sys/class/remoteproc/remoteproc0/state 44 | 45 | # Stop remote processor if running 46 | echo stop > /sys/class/remoteproc/remoteproc0/state 47 | 48 | # Load and start target firmware onto remote processor 49 | echo start > /sys/class/remoteproc/remoteproc0/state 50 | 51 | .. note:: 52 | 53 | The remote processor number (remoteproc0) may be different depending on driver probe order. To 54 | check which remote processor the number belongs to print out the default firmware name 55 | (:code:`cat /sys/class/remoteproc/remoteproc0/firmware`) and match that to the 56 | ``Deploy Firmware Name`` above. 57 | -------------------------------------------------------------------------------- /_doxygen/openamp/doxygen-awesome-openamp.css: -------------------------------------------------------------------------------- 1 | /* 2 | * This file contains color customizations that follow OpenAMP branding 3 | * This file was originally copied from the Zephyr project and modified 4 | * The original copyright and license are maintained below 5 | * 6 | * Copyright (c) 2021 Nordic Semiconductor ASA 7 | * Copyright (c) 2023 Linaro Ltd 8 | * SPDX-License-Identifier: Apache-2.0 9 | */ 10 | 11 | html { 12 | --primary-color: #e86060; 13 | --primary-dark-color: #d04040; 14 | --primary-light-color: #c0c0c0; 15 | --primary-lighter-color: #e0e0e0; 16 | --primary-lightest-color: #f0f0f0; 17 | 18 | --side-nav-background: #343131; 19 | --side-nav-foreground: #c0c0c0; 20 | 21 | --searchbar-background: var(--page-background-color); 22 | --searchbar-foreground: var(--page-foreground-color); 23 | 24 | --link-color: #2980b9; 25 | --param-color: #b71c1c; 26 | 27 | --side-nav-fixed-width: 300px; 28 | --top-height: 280px; 29 | } 30 | 31 | @media (prefers-color-scheme: dark) { 32 | html:not(.light-mode) { 33 | color-scheme: dark; 34 | 35 | --primary-color: #af7fe4; 36 | --primary-dark-color: #cb99f6; 37 | --primary-light-color: #7929d2; 38 | --primary-lighter-color: #191e21; 39 | --primary-lightest-color: #191a1c; 40 | 41 | --side-nav-background: #343131; 42 | --side-nav-foreground: var(--page-foreground-color); 43 | 44 | --param-color: #ef9a9a; 45 | } 46 | } 47 | 48 | html.dark-mode { 49 | color-scheme: dark; 50 | 51 | --primary-color: #e86060; 52 | --primary-dark-color: #d04040; 53 | --primary-light-color: #707070; 54 | --primary-lighter-color: #191e21; 55 | --primary-lightest-color: #191a1c; 56 | 57 | --side-nav-background: #343131; 58 | --side-nav-foreground: var(--page-foreground-color); 59 | 60 | --param-color: #ef9a9a; 61 | } 62 | 63 | a:link, a:visited, a:hover, a:focus, a:active { 64 | color: var(--link-color) !important; 65 | } 66 | 67 | .paramname { 68 | color: var(--param-color); 69 | } 70 | 71 | dl.section dd, dl.bug dd, dl.deprecated dd { 72 | margin-inline-start: revert; 73 | } 74 | 75 | /* adjust top and title to ~match Sphinx docs */ 76 | #top { 77 | background: var(--side-nav-background); 78 | background-image: url("triangle_background.png"); 79 | } 80 | 81 | #titlearea { 82 | padding-bottom: 0; 83 | } 84 | 85 | #titlearea table { 86 | width: 100%; 87 | } 88 | 89 | #projectlogo img { 90 | width: 150px; 91 | height: 150px; 92 | max-height: none !important; 93 | padding-top: 12px; 94 | } 95 | 96 | #projectalign { 97 | display: none; 98 | } 99 | 100 | @media screen and (min-width: 767px) { 101 | #doc-content { 102 | padding-top: calc(var(--top-height) - 220px); 103 | } 104 | } 105 | 106 | /* style for re-injected version */ 107 | #projectversion { 108 | color: var(--side-nav-foreground); 109 | padding-top: 25px; 110 | text-align: center; 111 | color: #ffffff; 112 | } 113 | 114 | #nav-sync { 115 | visibility: hidden; 116 | } 117 | -------------------------------------------------------------------------------- /protocol_details/asymmetric_mp.rst: -------------------------------------------------------------------------------- 1 | .. _asymmetric-multiprocessing-work-label: 2 | 3 | ====================================== 4 | Asymmetric Multiprocessing (AMP) Intro 5 | ====================================== 6 | 7 | An embedded AMP system is characterized by multiple homogeneous and/or heterogeneous processing 8 | cores integrated into one System-on-a-Chip (SoC). Examples include: 9 | 10 | - The AMD Zynq UltraScale+ MPSoCs that utilize four ARM Cortex-A53, two ARM Cortex-R5, and 11 | potentially a number of MicroBlaze cores. 12 | - The NXP i.MX6SoloX/i.MX7d SoCs that utilize ARM Cortex-A9 and ARM Cortex-M4F cores 13 | - The Texas Instruments Sitara AM625 SoCs that utilize ARM Cortex-A53, ARM Cortex-M4F, ARM 14 | Cortex-R5F, and PRU-ICSS cores. 15 | - The ST STM32MP15x SoCs that utilize ARM Cortex-A7 and ARM Cortex-M4 cores. 16 | 17 | These cores typically run independent instances of homogeneous and/or heterogeneous software 18 | environments, such as Linux, RTOS, and Bare Metal that work together to achieve the design goals of 19 | the end application. While Symmetric Multiprocessing (SMP) operating systems allow load balancing 20 | of application workload across homogeneous processors present in such AMP SoCs, asymmetric 21 | multiprocessing design paradigms are required to leverage parallelism from the heterogeneous cores 22 | present in the system. 23 | 24 | Increasingly, today’s multicore applications require heterogeneous processing power. Heterogeneous 25 | multicore SoCs often have one or more general purpose CPUs (for example, ARM Cortex-A cores) with 26 | DSPs (such as TI C7x cores) and/or smaller CPUs (such as ARM Cortex-M and Cortex-R cores) and/or 27 | soft IP (such as AMD MicroBlaze cores). These specialized CPUs, as compared to the general purpose 28 | CPUs, are typically dedicated for demand-driven offload of specialized application functionality to 29 | achieve maximum system performance. Systems developed using these types of SoCs, characterized by 30 | heterogeneity in both hardware and software, are generally termed as AMP systems. 31 | 32 | Other reasons to run heterogeneous software environments (e.g. multi-OS) include: 33 | 34 | - Needs for multiple environments with different characteristics 35 | * Real-time (RTOS) and general purpose (i.e. Linux) 36 | * Safe/Secure environment and regular environment 37 | * GPL and non-GPL environments 38 | - Integration of code written for multiple environments 39 | * Legacy OS and new OS 40 | 41 | In AMP systems, it is typical for software running on a host to bring up software/firmware contexts 42 | on a remote on a demand-driven basis and communicate with them using IPC mechanisms to offload work 43 | during runtime. The participating host and remote processors may be homogeneous or heterogeneous in 44 | nature. The remote can also be started automatically, on boot, which may be required where the 45 | remote is part of a safety critical system. 46 | 47 | A host is defined as the CPU/software that is booted first and is responsible for managing other 48 | CPUs and their software contexts present in an AMP system. A remote is defined as the CPU/software 49 | context managed by the host software context present. 50 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Software License Agreement (BSD 3-Clause License) 2 | 3 | Copyright (c) 2014, Mentor Graphics Corporation. All rights reserved. Copyright (c) 2015 - 2016 Xilinx, Inc. All rights reserved. Copyright (c) 2016 Freescale Semiconductor, Inc. All rights reserved 4 | 5 | Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 6 | 7 | Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 8 | 9 | Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 10 | 11 | Neither the name of nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. 12 | 13 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 14 | BSD 2-Clause License 15 | 16 | Copyright (c) . All rights reserved. 17 | 18 | Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 19 | 20 | Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 21 | 22 | Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 23 | 24 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 25 | Notes 26 | 27 | Use the following tag instead of the full license text in the individual files: 28 | 29 | SPDX-License-Identifier: BSD-3-Clause 30 | SPDX-License-Identifier: BSD-2-Clause 31 | 32 | This enables machine processing of license information based on the SPDX License Identifiers that are here available: http://spdx.org/licenses/ 33 | -------------------------------------------------------------------------------- /_static/images/openAMP_WORDMARKX.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 5 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 19 | 23 | 26 | 29 | 32 | 36 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | -------------------------------------------------------------------------------- /demos/replicate_firmware.rst: -------------------------------------------------------------------------------- 1 | =============================== 2 | OpenAMP Replicate Firmware Demo 3 | =============================== 4 | 5 | .. _replicate-firmware-intro: 6 | 7 | ************************ 8 | Replicate Firmware Intro 9 | ************************ 10 | 11 | The Replicate Firmware Demo is provided to demonstrate the use of two remote processors each loaded with the same firmware. 12 | 13 | .. image:: ../images/demos/replicate-firmware-intro.svg 14 | 15 | .. _replicate-firmware-components: 16 | 17 | ***************************** 18 | Replicate Firmware Components 19 | ***************************** 20 | 21 | This demonstration uses a single application, sent independently to the two remotes, utilising a demo script on the main controller. 22 | 23 | The underlying OpenAMP architectural components used by these applications are 24 | 25 | * :ref:`Remoteproc` 26 | * :ref:`Resource Table` 27 | * :ref:`Libmetal` 28 | 29 | The following architecture diagram shows the components involved in the demonstration. 30 | 31 | .. image:: ../images/demos/replicate-firmware-components.svg 32 | 33 | The top-level control flow is shown in the following message diagram. 34 | 35 | .. _replicate-firmware-control-flow: 36 | 37 | .. image:: ../images/demos/replicate-firmware-control-flow.svg 38 | 39 | .. _replicate-firmware-remote-app: 40 | 41 | Replicate Firmware Remote Application 42 | ===================================== 43 | 44 | The remote application is a hello world application, which once loaded calls printf. The output of 45 | printf is directed to a UART. 46 | 47 | .. _replicate-firmware-linux-script: 48 | 49 | Replicate Firmware Main Script 50 | ============================== 51 | 52 | The main controller is responsible for loading the firmware and starting the remote processors by 53 | writing start and stop to /sys/class/remoteproc/remoteproc0 and /sys/class/remoteproc/remoteproc1 alternately. 54 | 55 | The same firmware is loaded, and this is made possible as the system uses 56 | `Tightly Coupled Memory `_, 57 | so each processor is assigned its own bank of memory. 58 | 59 | The script is available in the :ref:`Demo Docker Images` as demo3. 60 | 61 | Replicate Firmware Main Configuration 62 | ===================================== 63 | 64 | The remoteproc configuration binding 65 | `cluster-mode `_ 66 | is set to 0 for split-mode as per the 67 | `system reference implementation `_. 68 | 69 | ******************************************** 70 | Replicate Firmware Remote Application Source 71 | ******************************************** 72 | 73 | Replicate Firmware Zephyr OS Source 74 | =================================== 75 | 76 | The application is implemented for Zephyr OS as `hello_world `_. 77 | 78 | ******************************* 79 | Reference Board Implementations 80 | ******************************* 81 | 82 | This Replicate Firmware Samples are demonstrated in the following reference implementations. 83 | 84 | * :ref:`Docker Images` as demo3 85 | -------------------------------------------------------------------------------- /demos/split_mode.rst: -------------------------------------------------------------------------------- 1 | ======================= 2 | OpenAMP Split Mode Demo 3 | ======================= 4 | 5 | .. _split-mode-intro: 6 | 7 | **************** 8 | Split Mode Intro 9 | **************** 10 | 11 | The `Split Mode Demo `_ is provided to demonstrate the use of two remote processors independently. The example utilises two R5 processors in AMD Ultrascale's `split-mode `_, as compared to the default `lock-step mode `_ of the `RPU CPU Configuration `_. 12 | 13 | .. image:: ../images/demos/split-mode-intro.svg 14 | 15 | .. _split-mode-components: 16 | 17 | ********************* 18 | Split Mode Components 19 | ********************* 20 | 21 | This demonstration uses a single application, sent independently to the two remotes, utilising a demo script on the main controller. 22 | 23 | The underlying OpenAMP architectural components used by these applications are 24 | 25 | * :ref:`Remoteproc` 26 | * :ref:`Resource Table` 27 | * :ref:`Libmetal` 28 | 29 | The following architecture diagram shows the components involved in the demonstration. 30 | 31 | .. image:: ../images/demos/split-mode-components.svg 32 | 33 | The top-level control flow is shown in the following message diagram. 34 | 35 | .. _split-mode-control-flow: 36 | 37 | .. image:: ../images/demos/split-mode-control-flow.svg 38 | 39 | .. _split-mode-remote-app: 40 | 41 | Split Mode Remote Application 42 | ============================= 43 | 44 | The remote application is a simple application which once loaded calls printf to write to the main 45 | controller console, interleaved with other main controller console output. 46 | 47 | .. _split-mode-linux-script: 48 | 49 | Split Mode Main Script 50 | ====================== 51 | 52 | The main controller is responsible for loading the firmware and starting the remote processors by 53 | writing start and stop to /sys/class/remoteproc/remoteproc0 and /sys/class/remoteproc/remoteproc1 alternately. 54 | 55 | The script is available in the 56 | :ref:`Demo Docker Images` as 57 | `demo2 `_. 58 | 59 | Split Mode Main Configuration 60 | ============================= 61 | 62 | The remoteproc configuration binding 63 | `cluster-mode `_ 64 | is set to 0 for split-mode as per the 65 | `system reference implementation `_. 66 | 67 | ************************************ 68 | Split Mode Remote Application Source 69 | ************************************ 70 | 71 | The application is deployed as binary in the :ref:`Demo Docker Images` 72 | repository, and the source is derived from the 73 | `echo-test `_ 74 | application, leaving out the RPMsg creation step and simply using LPRINTF to print the starting 75 | message "Starting application on RPU0 and waiting for stop...". 76 | 77 | ******************************* 78 | Reference Board Implementations 79 | ******************************* 80 | 81 | This Split Mode Samples are demonstrated in the following reference implementations. 82 | 83 | * :ref:`Docker Images` as demo2 84 | -------------------------------------------------------------------------------- /protocol_details/components.rst: -------------------------------------------------------------------------------- 1 | .. _openamp-components-work-label: 2 | 3 | =========================== 4 | Components and Capabilities 5 | =========================== 6 | 7 | The key components, and the capabilities they provide, of the OpenAMP Framework include: 8 | 9 | .. toctree:: 10 | :maxdepth: 2 11 | 12 | lifecyclemgmt 13 | rpmsg 14 | 15 | +-------------------+--------------------------------------------------------------------------------+ 16 | | AMP Key Component | Description | 17 | +===================+================================================================================+ 18 | | remoteproc | This component allows for the Life Cycle Management (LCM) of remote processors | 19 | | | from software running on a host processor. The remoteproc API provided by the | 20 | | | OpenAMP Framework is compliant with the remoteproc infrastructure present in | 21 | | | upstream Linux 3.4.x kernel onward. | 22 | +-------------------+--------------------------------------------------------------------------------+ 23 | | RPMsg | The RPMsg API enables | 24 | | | `Inter Processor Communications (IPC) | 25 | | | `_ | 26 | | | between independent software contexts running on homogeneous or | 27 | | | `heterogeneous `_ cores | 28 | | | present in an AMP system. This API is compliant with the RPMsg bus | 29 | | | infrastructure present in upstream Linux 3.4.x kernel onward. The Linux RPMsg | 30 | | | bus and API infrastructure was first implemented by Texas Instruments | 31 | +-------------------+--------------------------------------------------------------------------------+ 32 | 33 | 34 | ********** 35 | Topologies 36 | ********** 37 | 38 | The following figure shows the various software environments/configurations supported by the OpenAMP 39 | Framework. As shown in this illustration, the OpenAMP Framework can be used with RTOS or bare metal 40 | contexts on a remote processor to communicate with Linux applications (in kernel space or user 41 | space) or other RTOS/bare metal-based applications running on the host processor through the 42 | remoteproc and RPMsg components. 43 | 44 | .. image:: ../images/openamp_components.svg 45 | 46 | The OpenAMP Framework also serves as a stand-alone library that enables RTOS and bare metal 47 | applications on a host processor to manage the life cycle of remote processor/firmware and 48 | communicate with them using RPMsg. 49 | 50 | ************* 51 | Proxy and RPC 52 | ************* 53 | 54 | In addition to providing a software framework/API for LCM and IPC, the OpenAMP Framework supplies a 55 | proxy infrastructure that provides a transparent interface to remote contexts from Linux user space 56 | applications running on the host processor. The proxy application hides all the logistics involved 57 | in bringing-up the remote software context and its shutdown sequence. In addition, it supports 58 | RPMsg-based Remote Procedure Calls (RPCs) from the remote context. A retargeting API available 59 | from the remote context allows C library system calls such as "_open", "_close", "_read", and 60 | "_write" to be forwarded to the proxy application on the host for service. 61 | 62 | *********** 63 | Abstraction 64 | *********** 65 | 66 | In addition to the core capabilities, the OpenAMP Framework contains abstraction layers 67 | (porting layer) for migration to different software environments and new 68 | target processors/platforms, through its libmetal library. 69 | -------------------------------------------------------------------------------- /_static/images/openAMP_combox.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 5 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 27 | 31 | 34 | 37 | 40 | 44 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | -------------------------------------------------------------------------------- /_static/images/openAMP_combox_trim.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 5 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 27 | 31 | 34 | 37 | 40 | 44 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | -------------------------------------------------------------------------------- /_static/images/openAMP_combox_dark.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 5 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 30 | 34 | 37 | 40 | 43 | 47 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | -------------------------------------------------------------------------------- /_static/images/openAMP_combox_dark_trim.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 5 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 30 | 34 | 37 | 40 | 43 | 47 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | -------------------------------------------------------------------------------- /docs/rpmsg_design.rst: -------------------------------------------------------------------------------- 1 | RPMsg Design Document 2 | ===================== 3 | RPMsg is a framework to allow communication between two processors. 4 | RPMsg implementation in OpenAMP library is based on virtio. It complies 5 | the RPMsg Linux kernel implementation. It defines the handshaking on 6 | setting up and tearing down the communication between applications 7 | running on two processors. 8 | 9 | RPMsg User API Flow Charts 10 | -------------------------- 11 | 12 | RPMsg Static Endpoint 13 | ^^^^^^^^^^^^^^^^^^^^^ 14 | 15 | .. image:: ../images/design/img/coprocessor-rpmsg-static-ep.png 16 | 17 | Binding Endpoint Dynamically with Name Service 18 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 19 | .. image:: ../images/design/img/coprocessor-rpmsg-ns.png 20 | 21 | Creating Endpoint Dynamically with Name Service 22 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 23 | .. image:: ../images/design/img/coprocessor-rpmsg-ns-dynamic.png 24 | 25 | RPMsg User APIs 26 | --------------- 27 | 28 | .. doxygenfunction:: rpmsg_virtio_init_shm_pool 29 | :project: openamp_doc_embed 30 | 31 | .. doxygenfunction:: rpmsg_init_vdev 32 | :project: openamp_doc_embed 33 | 34 | .. doxygenfunction:: rpmsg_deinit_vdev 35 | :project: openamp_doc_embed 36 | 37 | .. doxygenfunction:: rpmsg_virtio_get_rpmsg_device 38 | :project: openamp_doc_embed 39 | 40 | RPMsg virtio endpoint APIs 41 | ^^^^^^^^^^^^^^^^^^^^^^^^^^ 42 | 43 | .. doxygenfunction:: rpmsg_create_ept 44 | :project: openamp_doc_embed 45 | 46 | .. doxygenfunction:: rpmsg_destroy_ept 47 | :project: openamp_doc_embed 48 | 49 | .. doxygenfunction:: is_rpmsg_ept_ready 50 | :project: openamp_doc_embed 51 | 52 | RPMsg messaging APIs 53 | ^^^^^^^^^^^^^^^^^^^^ 54 | 55 | .. doxygenfunction:: rpmsg_send 56 | :project: openamp_doc_embed 57 | 58 | .. doxygenfunction:: rpmsg_sendto 59 | :project: openamp_doc_embed 60 | 61 | .. doxygenfunction:: rpmsg_send_offchannel 62 | :project: openamp_doc_embed 63 | 64 | .. doxygenfunction:: rpmsg_trysend 65 | :project: openamp_doc_embed 66 | 67 | .. doxygenfunction:: rpmsg_trysendto 68 | :project: openamp_doc_embed 69 | 70 | .. doxygenfunction:: rpmsg_trysend_offchannel 71 | :project: openamp_doc_embed 72 | 73 | .. doxygenfunction:: rpmsg_hold_rx_buffer 74 | :project: openamp_doc_embed 75 | 76 | .. doxygenfunction:: rpmsg_release_rx_buffer 77 | :project: openamp_doc_embed 78 | 79 | .. doxygenfunction:: rpmsg_get_tx_payload_buffer 80 | :project: openamp_doc_embed 81 | 82 | .. doxygenfunction:: rpmsg_send_nocopy 83 | :project: openamp_doc_embed 84 | 85 | .. doxygenfunction:: rpmsg_sendto_nocopy 86 | :project: openamp_doc_embed 87 | 88 | .. doxygenfunction:: rpmsg_send_offchannel_nocopy 89 | :project: openamp_doc_embed 90 | 91 | .. doxygenfunction:: rpmsg_release_tx_buffer 92 | :project: openamp_doc_embed 93 | 94 | RPMsg User Defined Callbacks 95 | ---------------------------- 96 | 97 | * RPMsg endpoint message received callback: 98 | 99 | .. doxygentypedef:: rpmsg_ept_cb 100 | :project: openamp_doc_embed 101 | 102 | * RPMsg name service binding callback. If user defines such callback, when 103 | there is a name service announcement arrives, if there is no registered 104 | endpoint found to bind to this name service, it will call this callback. 105 | If this callback is not defined, it will drop this name service.: 106 | 107 | .. doxygentypedef:: rpmsg_ns_bind_cb 108 | :project: openamp_doc_embed 109 | 110 | * RPMsg name service unbind callback. If user defines such callback, when 111 | there is name service destroy arrives, it will call this callback.: 112 | 113 | .. doxygentypedef:: rpmsg_ns_unbind_cb 114 | :project: openamp_doc_embed 115 | 116 | * RPMsg endpoint name service unbind callback. If user defines such callback, 117 | when there is name service destroy arrives, it will call this callback to 118 | notify the user application about the remote has destroyed the service.: 119 | 120 | .. doxygentypedef:: rpmsg_ns_unbind_cb 121 | :project: openamp_doc_embed 122 | -------------------------------------------------------------------------------- /demos/linux_rpc.rst: -------------------------------------------------------------------------------- 1 | 2 | ====================== 3 | OpenAMP Linux RPC Demo 4 | ====================== 5 | 6 | .. _linux-rpc-intro: 7 | 8 | *************** 9 | Linux RPC Intro 10 | *************** 11 | 12 | The RPMsg Multi Services reference sample demonstrates OpenAMP 13 | :ref:`Remote Procedure Call (RPC)` components between two linux 14 | processors, one as the main controller and the other as remote. 15 | 16 | .. image:: ../images/demos/linux-rpc-intro.svg 17 | 18 | 19 | .. _linux-rpc-components: 20 | 21 | ******************** 22 | Linux RPC Components 23 | ******************** 24 | 25 | This demonstration shows how the :ref:`Remote Procedure Call (RPC)` 26 | component is a shim over RPMSg providing the familiar Input/Output (IO) commands like open, read, 27 | write, close both for files and standard input/output. 28 | 29 | The underlying OpenAMP architectural components used by these applications are 30 | 31 | * :ref:`Remoteproc` 32 | * :ref:`Resource Table` 33 | * :ref:`RPMsg` 34 | * :ref:`Virtio` 35 | * :ref:`RPC` 36 | * :ref:`Libmetal` 37 | 38 | The Linux file and stdio access is performed in the 39 | `linux_rpc_demod application `_. 40 | 41 | The following architecture diagram shows the primary components involved in the demonstration. 42 | 43 | .. image:: ../images/demos/linux-rpc-components.svg 44 | 45 | .. _linux-rpc-control-flow: 46 | 47 | The top-level control flow is shown in the following message diagram. 48 | 49 | .. image:: ../images/demos/linux-rpc-control-flow.svg 50 | 51 | 52 | .. _linux-rpc-server: 53 | 54 | Linux RPC Server 55 | ================ 56 | 57 | The Linux RPC Server application is a file handling server and achieves this by providing a shim 58 | over the RPC component of OpenAMP, with pointers, and associated identifiers for each of the file IO 59 | functions like open, close, read write, and input for stdio. 60 | 61 | Whenever the server receives an RPMsg on this end point with the associated identifier it will 62 | perform the file IO on behalf of the client/remote. 63 | 64 | .. _linux-rpc-client: 65 | 66 | Linux RPC Client 67 | ================ 68 | 69 | The Linux RPC Client application is a remote/client application requiring file handling, but lacking 70 | a file system. Instead it relies on a main server to provide the file handling via RPMsg. It 71 | initializes an RPC client, associated through the server identifiers. For each IO handler it will 72 | send an RPMsg on the associated endpoint. 73 | 74 | The OpenAMP RPC client does not block to await the RPMsg response, leaving this to the application 75 | to perform. In the sample client this is performed for each of the input output functions. 76 | 77 | 78 | ********************* 79 | Linux RPC Demo Source 80 | ********************* 81 | 82 | 83 | Linux RPC Server Source 84 | ======================= 85 | 86 | The current implementation is a Linux process 87 | `linux_rpc_demod `_, 88 | which can be run as a daemon to provide the main controller/driver side of the demonstration. 89 | 90 | Linux RPC Client Source 91 | ======================= 92 | 93 | The current implementation is a Linux process 94 | `linux_rpc_demo `_ 95 | 96 | 97 | ******************************* 98 | Reference Board Implementations 99 | ******************************* 100 | 101 | This Linux RPC Sample is demonstrated in the following reference implementations. 102 | 103 | * :ref:`Linux Inter Process ` 104 | 105 | .. toctree:: 106 | :maxdepth: 1 107 | :caption: Demo Compile and Execution Instructions 108 | 109 | ../open-amp/apps/examples/linux_rpc_demo/README 110 | -------------------------------------------------------------------------------- /protocol_details/rpmsg_comms.rst: -------------------------------------------------------------------------------- 1 | ========================= 2 | RPMsg Communication Flow 3 | ========================= 4 | 5 | This section details the communication flow for the :ref:`media access layer` 6 | of RPMsg Protocol, between the main and the remote processor. 7 | 8 | Two :ref:`VRINGs` are used, each with its own available and used 9 | ring buffers and associated descriptors, VRING1 and VRING0. 10 | 11 | The 12 | `Virtio RPMsg bus vring allocation `_, 13 | is an example implementation where the main core is running the Linux kernel and where VRING0 is vqs[0] 14 | or the receive (rvq) VRING and VRING1 is vqs[1] or the transmit/send (svq) VRING. 15 | 16 | Main to Remote RPMsg Flow 17 | ------------------------- 18 | 19 | For the transmission of RPMsgs from the main core to the remote, the following actions 20 | are performed against VRING1, as detailed in the top of the flow chart 21 | below: 22 | 23 | The main core 24 | 25 | * Gets a transmission buffer from the used queue of VRING1. 26 | * Writes the RPMsg header and payload of this buffer. 27 | * Enqueues this buffer containing the RPMsg to the available queue of VRING1 by setting the head 28 | index. 29 | * Optionally triggers an interrupt to inform remote of message availability 30 | (if F_NO_NOTIFY flag is not set in available ring buffer). 31 | 32 | The remote then 33 | 34 | * Gets the received buffer from the available queue of VRING1. 35 | * Passes the buffer to the endpoint callback, which would handle the message. 36 | * Enqueues the freed buffer to the used queue of VRING1, to make it available again for 37 | future transmissions from the main core. 38 | * Optionally triggers an interrupt to inform main core of freed buffer 39 | (if F_NO_NOTIFY flag is not set in used ring buffer). 40 | 41 | 42 | .. image:: ../images/rpmsg_flow.jpg 43 | 44 | 45 | Remote to Main RPMsg Flow 46 | ------------------------- 47 | 48 | For the transmission of RPMsgs from the remote to the main core the 49 | following actions are performed on VRING0, as detailed in the lower part 50 | of the flow chart above. 51 | 52 | The remote 53 | 54 | * Gets a transmission buffer, provided by main core, from the available queue of VRING0. 55 | * Writes the RPMsg header and payload of this buffer. 56 | * Enqueues this buffer containing the RPMsg to the used queue of VRING0 by setting the head 57 | index. 58 | * Optionally triggers an interrupt to inform the main core of message availability 59 | (if F_NO_NOTIFY flag is not set in used ring buffer). 60 | 61 | The main core then 62 | 63 | * Gets the received buffer from the used queue of VRING0. 64 | * Passes the buffer to the endpoint callback, which would handle the message. 65 | * Enqueues the freed buffer to the available queue of VRING0, to make it available again for 66 | future transmissions from the remote. 67 | * Optionally triggers an interrupt to inform the remote of freed buffer 68 | (if F_NO_NOTIFY flag is not set in used ring buffer). 69 | 70 | Vring queue and buffer allocation 71 | --------------------------------- 72 | 73 | The remote gets the received RPMsg buffer from the available ring buffer, processes it and 74 | then returns it back to the used ring buffer. When the remote is sending a message to the 75 | main core, available and used ring buffer roles are swapped. 76 | 77 | The reason for swapping the roles of the ring buffers stems from the main core being the 78 | buffer provider. The main core is in charge of the shared memory allocation. 79 | 80 | When the main core, or buffer provider, does not fill the available ring buffer of 81 | VRING0, the remote is unable to send a message to the main core. 82 | This can be used to throttle the communication generated by the remote. 83 | 84 | It is to be noticed, that the main core always dequeues from the used ring buffer and 85 | enqueues to the available ring buffer. 86 | 87 | The triggering of interrupts is optional. It is governed by the F_NO_NOTIFY flag in used and 88 | available ring buffer flags. The use of notification interrupts is recommended for 89 | performance reasons, and defaults to this as the flag is clear. The user can overwrite 90 | this by setting this flag if there are particular reasons to poll for messages rather than use 91 | interrupts. 92 | -------------------------------------------------------------------------------- /protocol_details/lifecyclemgmt_creation.rst: -------------------------------------------------------------------------------- 1 | ===================================================== 2 | Creation and Boot of Remote Firmware Using remoteproc 3 | ===================================================== 4 | 5 | You can create and boot remote firmware for Linux, RTOS, and bare metal-based remote applications 6 | using remoteproc. The following procedure provides general steps for creating and executing remote 7 | firmware on a supported platform. 8 | 9 | The following figure illustrates the remote firmware creation process. 10 | 11 | .. image:: ../images/lcm_boot.jpg 12 | 13 | Defining the Resource Table and Creating the Remote ELF Image 14 | ------------------------------------------------------------- 15 | 16 | Creating a remote image through remoteproc begins by defining the resource table and creating the 17 | remote ELF image. 18 | 19 | Procedure 20 | ~~~~~~~~~ 21 | 22 | 1. Define the :ref:`resource table` structure in the application. The resource 23 | table must minimally contain carve-out and VirtIO device information for IPC. 24 | 25 | As an example, please refer to the resource table defined in the bare metal remote echo test 26 | application at 27 | `rsc_table.c `_. 28 | The resource table contains entries for memory carve-out and virtio device resources. The memory 29 | carve-out entry contains info like firmware ELF image start address and size. The virtio device 30 | resource contains virtio device features, vring addresses, size, and alignment information. The 31 | resource table data structure is placed in the resource table section of remote firmware ELF 32 | image using compiler directives. 33 | 34 | 2. After defining the resource table and creating the OpenAMP Framework library, link the 35 | remote application with the RTOS or bare metal library and the OpenAMP Framework library to 36 | create a remote firmware ELF image capable of in-place execution from its pre-determined memory 37 | region. (The pre-determined memory region is determined according to guidelines provided by 38 | section.) 39 | 40 | 3. For remote Linux, step 1 describes modifications to be made to the resource table. The 41 | previous flow figures shows the high level steps involved in creation of the remote Linux 42 | firmware image. The flow shows to create a Linux Flat Image Tree (FIT) image that encapsulates 43 | the Linux kernel image, Device Tree Blob (DTB), and initramfs. 44 | 45 | The user applications and kernel drivers required on the remote Linux context could be built 46 | into the initramfs or moved to the remote root file system as needed after boot. The FIT image 47 | is linked along with a boot strap package provided within the OpenAMP Framework. The bootstrap 48 | implements the functionality required to decode the FIT image (using libfdt), uncompress the 49 | Linux kernel image (using zlib) and locate the kernel image, initramfs, and DTB in RAM. It can 50 | also set up the ARM general purpose registers with arguments to boot Linux, and transfer control 51 | to the Linux entry point. 52 | 53 | Making Remote Firmware Accessible to the Host 54 | ----------------------------------------------- 55 | 56 | After creating the remote firmware’s ELF image, you need to make it accessible to remoteproc in the 57 | host context. 58 | 59 | Procedure 60 | ~~~~~~~~~ 61 | 62 | 1. If the RTOS- or bare metal-based host software context has a file system, place this firmware 63 | ELF image in the file system. 64 | 2. Implement the remoteproc APIs to load the remote firmware. 65 | 3. For AMP use cases with Linux as host, place the firmware application in the root file system 66 | for use by Linux remoteproc platform drivers. 67 | 68 | In the OpenAMP Framework reference port to Zynq ZC702EVK, the bare metal library used by the host 69 | software applications does not include a file system. Therefore, the remote image is packaged along 70 | with the host ELF image. The remote ELF image is converted to an object file using “objcopy” 71 | available in the “GCC bin-utils”. This object file is further linked with the host ELF image. 72 | 73 | The remoteproc component on the host uses the start and end symbols from the remote object files to 74 | get the remote ELF image base and size. 75 | 76 | You can now use the remoteproc APIs. 77 | -------------------------------------------------------------------------------- /demos/system_reference-NXP.rst: -------------------------------------------------------------------------------- 1 | 2 | 3 | .. _reference_board_NXP: 4 | 5 | ==================== 6 | NXP Reference Boards 7 | ==================== 8 | 9 | A number of the `OpenAMP project examples 10 | `_ 11 | can be executed on NXP Reference boards. 12 | 13 | Board setup 14 | ------------ 15 | 16 | The `i.MX 8M Plus Evaluation Kit Quick Start Guide (IMX8MPLUSQSG) 17 | `_ 18 | contains basic information on the board and how to 19 | set it up. 20 | In `AN13970 Running Zephyr RTOS on Cadence Tensilica HiFi 4 DSP 21 | `_ 22 | application note provides instructions on how to launch the samples on 23 | the HiFi4 DSP. 24 | 25 | Generate the Zephyr rpmsg multi service example 26 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 27 | 28 | Initialize the Zephyr environment 29 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 30 | 31 | Refer to :ref:`zephyr example readme` article. 32 | 33 | 34 | Build the Zephyr image 35 | ^^^^^^^^^^^^^^^^^^^^^^ 36 | 37 | From the openamp-system-reference directory 38 | 39 | .. code-block:: console 40 | 41 | west build -p -b imx8mp_evk//adsp -s examples/zephyr/rpmsg_multi_services/ 42 | 43 | For details refer to 44 | :ref:`rpmsg_multi_services readme ` article. 45 | 46 | Install the Zephyr binary on the sdcard 47 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 48 | 49 | The Zephyr sample binary is available in the sub-folder of build directory 50 | openamp-system-reference/build/zephyr/rpmsg_multi_services.elf. 51 | It needs to be installed on the "rootfs" partition of the sdcard 52 | 53 | .. code-block:: console 54 | 55 | sudo cp build/zephyr/rpmsg_multi_services.elf /rootfs/lib/firmware/ 56 | 57 | Don't forget to properly unmount the sdcard partitions. 58 | 59 | .. code-block:: console 60 | 61 | sudo eject /dev/ 62 | 63 | Demos 64 | ----- 65 | 66 | Start the demo environment 67 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ 68 | 69 | Power on the i.MX8M Plus EVK, and wait login prompt on your serial terminal 70 | 71 | .. code-block:: console 72 | 73 | imx8mpevk login: root 74 | root@imx8mpevk:~# 75 | 76 | 77 | Start the coprocessor using Linux remoteproc framework 78 | 79 | .. code-block:: console 80 | 81 | root@imx8mpevk:~# cat /sys/class/remoteproc/remoteproc0/state 82 | offline 83 | root@imx8mpevk:~# echo rpmsg_multi_services.elf > /sys/class/remoteproc/remoteproc0/firmware 84 | root@imx8mpevk:~# echo start >/sys/class/remoteproc/remoteproc0/state 85 | root@imx8mpevk:~# cat /sys/class/remoteproc/remoteproc0/state 86 | running 87 | 88 | The communication with the coprocessor is not initialized, following traces on console 89 | are observed: 90 | 91 | .. code-block:: console 92 | 93 | root@imx8mpevk:~# 94 | [ 199.756694] virtio_rpmsg_bus virtio0: rpmsg host is online 95 | [ 199.756756] rproc-virtio rproc-virtio.2.auto: registered virtio0 (type 7) 96 | [ 199.756764] remoteproc remoteproc0: remote processor imx-dsp-rproc is now up 97 | [ 199.757099] virtio_rpmsg_bus virtio0: creating channel rpmsg-client-sample addr 0x400 98 | [ 199.757259] virtio_rpmsg_bus virtio0: creating channel rpmsg-tty addr 0x401 99 | [ 199.757425] virtio_rpmsg_bus virtio0: creating channel rpmsg-raw addr 0x402 100 | [ 199.817974] rpmsg_client_sample virtio0.rpmsg-client-sample.-1.1024: new channel: 0x402 -> 0x400! 101 | [ 199.818049] rpmsg_client_sample virtio0.rpmsg-client-sample.-1.1024: incoming msg 1 (src: 0x400) 102 | [ 199.818089] rpmsg_client_sample virtio0.rpmsg-client-sample.-1.1024: incoming msg 2 (src: 0x400) 103 | [ 199.818290] rpmsg_client_sample virtio0.rpmsg-client-sample.-1.1024: incoming msg 3 (src: 0x400) 104 | [ 199.818325] rpmsg_client_sample virtio0.rpmsg-client-sample.-1.1024: incoming msg 4 (src: 0x400) 105 | [ 199.818354] rpmsg_client_sample virtio0.rpmsg-client-sample.-1.1024: incoming msg 5 (src: 0x400) 106 | ... 107 | 108 | This informs that following rpmsg channels devices have been created: 109 | 110 | - a rpmsg-client-sample device 111 | - a rpmsg-tty device 112 | - a rpmsg-raw device 113 | 114 | 115 | Run the multi RPMsg services demo 116 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 117 | 118 | Refer to 119 | :ref:`rpmsg_multi_services ` article. 120 | -------------------------------------------------------------------------------- /images/design/img-src/coprocessor-rpmsg-static-ep.gv: -------------------------------------------------------------------------------- 1 | // RPMsg static endpoints 2 | 3 | digraph G { 4 | rankdir="LR"; 5 | 6 | subgraph roles { 7 | node [style="filled", fillcolor="lightblue"]; 8 | host [label="Host"]; 9 | remote [label="Remote"]; 10 | } 11 | 12 | subgraph m_comment_nodes { 13 | node [group=m_comment, shape="note", style="filled", fillcolor="yellow"]; 14 | rank="same"; 15 | m_remoteproc_init_comment [label="this is initialize rproc call"]; 16 | m_remoteproc_boot_comment [label="it will setup vdev before booting the remote"]; 17 | m_rpmsg_vdev_init_comment [label="\l* It will initialize vrings with the shared memory\l* As vdev doesn't support name service, it will not create name service endpoint;\l* it sets vdev status to DRVIER_READY, And will notify remote.\l"]; 18 | m_rpmsg_create_ep_comment [label="\lAs vdev doesn't supports name service,\lit will not send out name service.\l"]; 19 | } 20 | 21 | subgraph m_flow_nodes { 22 | node [shape="box"]; 23 | rank="same"; 24 | m_remoteproc_init [label="rproc = remoteproc_init(&remoteproc_ops, &arg);"]; 25 | m_remoteproc_load [label="calls remoteproc_load() to load application"]; 26 | m_remoteproc_boot [shape="box", label="ret=remoteproc_boot(&rproc)"]; 27 | m_remoteproc_get_vdev [label="vdev=remoteproc_create_virtio(rproc, rpmsg_vdev_id, VIRTIO_DEV_DRIVER, NULL);"]; 28 | m_rpmsg_shmpool_init[label="rpmsg_virtio_init_shm_pool(shpool, shbuf, shbuf_pool_size);"]; 29 | m_rpmsg_vdev_init [label="rpdev=rpmsg_init_vdev(rpvdev, vdev, ns_bind_cb, &shm_io, shpool);"]; 30 | m_rpmsg_create_ep [label="\lept=rpmsg_create_ept(ept, rdev, ept_name, ept_addr, dest_addr, \lendpoint_cb, ns_unbind_cb);\l"]; 31 | m_rpmsg_send [label="rpmsg_send(ept,data)"]; 32 | m_rpmsg_rx_cb [label="rpmsg_rx_callback()"]; 33 | m_ep_cb [label="endpoint_cb(ept, data, size, src_addr)"]; 34 | m_rpmsg_destroy_ep [label="rpmsg_destroy_endpoint(ept)"]; 35 | 36 | m_remoteproc_init -> m_remoteproc_load -> m_remoteproc_boot -> m_remoteproc_get_vdev -> 37 | m_rpmsg_shmpool_init -> m_rpmsg_vdev_init -> m_rpmsg_create_ep -> m_rpmsg_send; 38 | m_rpmsg_send -> m_rpmsg_rx_cb -> m_ep_cb -> 39 | m_rpmsg_destroy_ep [dir="none", style="dashed"]; 40 | } 41 | 42 | subgraph s_flow_nodes { 43 | rank="same"; 44 | node [shape="box"]; 45 | s_remoteproc_init [label="rproc = remoteproc_init(&remoteproc_ops, &arg);"]; 46 | 47 | s_remoteproc_parse_rsc [label="ret = remoteproc_set_rsc_table(rproc, &rsc_table, rsc_size)"]; 48 | s_remoteproc_get_vdev [label="vdev=remoteproc_create_virtio(rproc, rpmsg_vdev_id, VIRTIO_DEV_DEVICE, rst_cb);"]; 49 | s_rpmsg_vdev_init [label="rpdev=rpmsg_init_vdev(rpvdev, vdev, ns_bind_cb, &shm_io, NULL);"]; 50 | s_rpmsg_create_ep [label="\lept=rpmsg_create_ept(ept, rdev, ept_name, ept_addr, dest_addr, \lendpoint_cb, ns_unbind_cb);\l"]; 51 | s_rpmsg_send [label="rpmsg_send(ept,data)"]; 52 | s_rpmsg_rx_cb [label="rpmsg_rx_callback()"]; 53 | s_ep_cb [label="endpoint_cb(ept, data, size, src_addr)"]; 54 | s_rpmsg_destroy_ep [label="rpmsg_destroy_endpoint(ept)"]; 55 | 56 | s_remoteproc_init -> s_remoteproc_parse_rsc -> s_remoteproc_get_vdev -> 57 | s_rpmsg_vdev_init -> s_rpmsg_create_ep; 58 | s_rpmsg_create_ep -> s_rpmsg_rx_cb -> 59 | s_ep_cb -> s_rpmsg_send -> s_rpmsg_destroy_ep [dir="none", style="dash"]; 60 | 61 | } 62 | 63 | subgraph s_comment_nodes { 64 | node [group=s_comment, shape="note", style="filled", fillcolor="yellow"]; 65 | rank="same"; 66 | s_rpmsg_vdev_init_comment [label="\l* As vdev doesn't support name service, it will not create name service endpoint;\l* It will not return until the host set status to DRIVER READY\l"]; 67 | s_rpmsg_rx_cb_comment [label="\l* It will look for the endpoint which matches the destination address.\lIf no endpoint has found, it will drop the message.\l"]; 68 | } 69 | 70 | host -> m_remoteproc_init [dir="none"]; 71 | remote -> s_remoteproc_init [dir="none"]; 72 | m_rpmsg_send -> s_rpmsg_rx_cb [label="RPMsg data"]; 73 | s_rpmsg_send -> m_rpmsg_rx_cb [label="RPMsg data"]; 74 | 75 | m_remoteproc_init_comment -> m_remoteproc_init [dir="none"]; 76 | m_remoteproc_boot_comment -> m_remoteproc_boot [dir="none"]; 77 | m_rpmsg_vdev_init_comment -> m_rpmsg_vdev_init [dir="none"]; 78 | m_rpmsg_create_ep_comment -> m_rpmsg_create_ep [dir="none"]; 79 | 80 | s_rpmsg_vdev_init -> s_rpmsg_vdev_init_comment [dir="none"]; 81 | s_rpmsg_rx_cb -> s_rpmsg_rx_cb_comment [dir="none"]; 82 | 83 | {rank=same; host; m_remoteproc_init} 84 | {rank=same; remote; s_remoteproc_init} 85 | 86 | } 87 | 88 | -------------------------------------------------------------------------------- /demos/hvl_virtio.rst: -------------------------------------------------------------------------------- 1 | ============================= 2 | OpenAMP Hypervisorless Virtio 3 | ============================= 4 | 5 | .. _hvl-virtio-intro: 6 | 7 | *************************** 8 | Hypervisorless Virtio Intro 9 | *************************** 10 | 11 | There are a number of 12 | `hypervisorless virtio demos `_. 13 | Their intent is to demonstrate the use of the :ref:`Virtio` component and associated drivers. 14 | 15 | This section details the sample for 16 | `hypervisorless virtio with entropy and network devices (hvl_net_rng_reloc) `_. 17 | 18 | All demonstrations are run on a remote running `Zephyr Operating System (OS) `_. 19 | 20 | .. image:: ../images/demos/hvl-virtio-intro.svg 21 | 22 | .. _hvl-virtio-components: 23 | 24 | ******************************** 25 | Hypervisorless Virtio Components 26 | ******************************** 27 | 28 | This demonstration uses a single application on the remote and a setup and demo script on the main 29 | controller. 30 | 31 | The underlying OpenAMP architectural components used by these applications are 32 | 33 | * :ref:`Remoteproc` 34 | * :ref:`Resource Table` 35 | * :ref:`Virtio` 36 | * :ref:`Libmetal` 37 | 38 | The following architecture diagram shows the components involved in the demonstration. 39 | 40 | .. image:: ../images/demos/hvl-virtio-components.svg 41 | 42 | The top-level control flow is shown in the following message diagram. 43 | 44 | .. _hvl-virtio-control-flow: 45 | 46 | .. image:: ../images/demos/hvl-virtio-control-flow.svg 47 | 48 | .. _hvl-virtio-remote-app: 49 | 50 | Hypervisorless Virtio Remote Application 51 | ======================================== 52 | 53 | The remote application is the core of the demonstration. It is a simple application utilising a 54 | number of Virtio devices. 55 | 56 | The remote application when started initially calls on the 57 | `Virtio Entropy Device `_ 58 | to obtain entropy values to print to the UART console. Subsequently, it sets up 59 | `Virtio Network Device `_ 60 | to provide communications between the main controller at 192.168.200.254 and remote at 192.168.200.2. 61 | 62 | Hypervisorless Virtio Main Script 63 | ================================= 64 | 65 | The main controller is responsible for setting up a 66 | `virtual/tap network `_, loading the firmware containing the 67 | :ref:`Hypervisorless Virtio Application` and starting the remote processor 68 | using :ref:`Remoteproc`. 69 | 70 | The scripts are available in the :ref:`Demo Docker Images` as 71 | `demo4 `_ 72 | and `setup.sh `_. 73 | 74 | **************************** 75 | Hypervisorless Virtio Source 76 | **************************** 77 | 78 | Hypervirsorless Virtio Zephyr Source 79 | ==================================== 80 | 81 | The hypervisorless Virtio application is available as a Zephyr solution in the 82 | `zephyr-openamp-staging Repository `_. 83 | 84 | It is a CMake application and can be built for any remote as long as the relevant 85 | :ref:`OS/HW abstraction layer` components like libmetal are ported for 86 | that platform. 87 | 88 | .. _hvl-virtio-linux-script: 89 | 90 | ******************************* 91 | Reference Board Implementations 92 | ******************************* 93 | 94 | This Hypervisorless Virtio Samples are demonstrated in the following reference implementations. 95 | 96 | * :ref:`Docker Images` as demo4 97 | * :ref:`AMD-Xilinx platforms` 98 | 99 | For information on building and running the demonstrations for zcu102 refer to 100 | 101 | .. toctree:: 102 | :maxdepth: 2 103 | 104 | ../hypervisorless_virtio_zcu102/README_demo 105 | -------------------------------------------------------------------------------- /protocol_details/lifecyclemgmt_overview.rst: -------------------------------------------------------------------------------- 1 | ============ 2 | LCM Overview 3 | ============ 4 | 5 | The remoteproc APIs provide life cycle management of remote processors by performing five essential 6 | functions. 7 | 8 | - Allow the host software applications to load the code and data sections of the remote firmware 9 | image to appropriate locations in memory for in-place execution 10 | - Release the remote processor from reset to start execution of the remote firmware 11 | - Establish RPMsg communication channels for runtime communications with the remote context 12 | - Shut down the remote software context and processor when its services are not needed 13 | - Provide an API for use in the remote application context that allows the remote applications 14 | to seamlessly initialize the remoteproc system and establish communication channels with the 15 | host context 16 | 17 | The remoteproc component currently supports Executable and Linkable Format (ELF) for the remote 18 | firmware; however, the framework can be easily extended to support other image formats. The remote 19 | firmware image publishes the system resources it requires to remoteproc on the host using a 20 | statically linked resource table data structure. The resource table data structure contains entries 21 | that define the system resources required by the remote firmware (for example, contiguous memory 22 | carve-outs required by remote firmware’s code and data sections), and features/functionality 23 | supported by the remote firmware (like virtio devices and their configuration information required 24 | for RPMsg-based IPC). 25 | 26 | The remoteproc APIs on the host processor use the information published through the firmware 27 | resource table to allocate appropriate system resources and to create virtio devices for IPC with 28 | the remote software context. The following figure illustrates the resource table usage. 29 | 30 | .. image:: ../images/lcm.jpg 31 | 32 | When the application on the host calls to the remoteproc_init API, it performs the following: 33 | 34 | - Causes remoteproc to fetch the firmware ELF image and decode it 35 | - Obtains the resource table and parses it to handle entries 36 | - Carves out memory for remote firmware before creating virtio devices for communications with 37 | remote context 38 | 39 | The host application then performs the following actions: 40 | 41 | 1. Calls the remoteproc_boot API to boot the remote context 42 | 2. Locates the code and data sections of the remote firmware image 43 | 3. Releases the remote processor to start execution of the remote firmware. 44 | 45 | After the remote application is running on the remote processor, the remote application calls the 46 | remoteproc_resource_init API to create the virtio/RPMsg devices required for IPC with the host 47 | context. Invocation of this API causes remoteproc on the remote context to use the rpmsg name 48 | service announcement feature to advertise the rpmsg channels served by the remote application. 49 | 50 | The host receives the advertisement messages and performs the following tasks: 51 | 52 | 1. Invokes the channel created callback registered by the host application 53 | 2. Responds to remote context with a name service acknowledgement message 54 | 55 | After the acknowledgement is received from host, remoteproc on the remote side invokes the RPMsg 56 | channel-created callback registered by the remote application. The RPMsg channel is established at 57 | this point. All RPMsg APIs can be used subsequently on both sides for runtime communications between 58 | the host and remote software contexts. 59 | 60 | To shut down the remote processor/firmware, the remoteproc_shutdown API is to be used from the host 61 | context. Invoking this API with the desired remoteproc instance handle asynchronously shuts down the 62 | remote processor. Using this API directly does not allow for graceful shutdown of remote context. 63 | 64 | Gracefully bringing down the remote context is not part of the remoteproc LCM, but can be 65 | implemented by the applications using the following steps: 66 | 67 | 1. The host application sends an application-specific shutdown message to the remote context 68 | 2. The remote application cleans up application resources, sends a shutdown acknowledge to host, 69 | and invokes remoteproc_resource_deinit API to deinitialize remoteproc on the remote side. 70 | 3. On receiving the shutdown acknowledge message, the host application invokes the 71 | remoteproc_shutdown API to shut down the remote processor and de-initialize remoteproc using 72 | remoteproc_deinit on its side. 73 | 74 | The OpenAMP samples and demos exemplify the use of an application specific message to perform 75 | graceful shutdown before the hard remoteproc_shutdown is performed. For an example, see the Shutdown 76 | Packet in the `Echo Test Messaging Flow diagram` which is implemented as the 77 | SHUTDOWN_MSG in the source 78 | `open-amp Repository `_. 79 | -------------------------------------------------------------------------------- /demos/echo.rst: -------------------------------------------------------------------------------- 1 | ======================== 2 | OpenAMP Echo Test Sample 3 | ======================== 4 | 5 | .. _echo-test-intro: 6 | 7 | *************** 8 | Echo Test Intro 9 | *************** 10 | 11 | The echo test reference sample, as the name suggests, demonstrates OpenAMP 12 | :ref:`Interprocessor Communications (IPC)` components by providing an echo 13 | application on a remote which simply returns (echoes) packets as they are received at an 14 | :ref:`RPMsg endpoint ` from the main controller. The main controller then verifies 15 | the returned packet for integrity. 16 | 17 | .. image:: ../images/demos/echo-test-intro.svg 18 | 19 | .. _echo-test-components: 20 | 21 | ******************** 22 | Echo Test Components 23 | ******************** 24 | 25 | There are two applications involved in this demonstration. 26 | The :ref:`remote application` runs as an echo service, which returns packets 27 | it receives on an :ref:`RPMsg endpoint `. 28 | The :ref:`main controller application` is the test application sending packets 29 | to the echo service and monitoring for their return. 30 | 31 | The underlying OpenAMP architectural components used by these applications are 32 | 33 | * :ref:`Remoteproc` 34 | * :ref:`Resource Table` 35 | * :ref:`RPMsg` 36 | * :ref:`Virtio` 37 | * :ref:`Libmetal` 38 | 39 | The following architecture diagram shows the components involved in the demonstration. 40 | 41 | .. image:: ../images/demos/echo-test-components.svg 42 | 43 | The top-level control flow is shown in the following message diagram. 44 | 45 | .. _echo-test-control-flow: 46 | 47 | .. image:: ../images/demos/echo-test-control-flow.svg 48 | 49 | .. _echo-test-remote-app: 50 | 51 | RPMsg Echo Remote Application 52 | ============================= 53 | 54 | The remote application, rpmsg-echo, is the core of the demonstration. It is a simple application 55 | serving a :ref:`RPMsg endpoint ` running as the main task on the remote processor. 56 | 57 | 58 | .. _echo-test-host-app: 59 | 60 | Echo Test Main Application 61 | ========================== 62 | 63 | The echo_test application forms the main controller side of the demonstration. It repeatedly writes 64 | an increasing length payload of 0xA5's up to the maximum data size (packet size minus header) to the 65 | RPMsg endpoint. Following each packet send, it reads from the same endpoint and verifies the 66 | returned packet for correctness. The application will stop and report on the first corruption found. 67 | 68 | Echo Test Main Script 69 | ===================== 70 | 71 | The main controller is also responsible for loading the firmware containing the 72 | :ref:`RPMsg Echo Remote Application` and starting the remote processor using 73 | :ref:`Remoteproc`. 74 | 75 | For main controllers, like Linux, a script can be used to pipe the firmware to the exposed 76 | remoteproc system, followed by the execution of the user space echo_test application. For 77 | controllers without scripting capability, like baremetal and RTOS (Real Time Operating systems), 78 | this would be achieved in the code. 79 | 80 | In the :ref:`Demo Docker Images` this is script demo1A. 81 | 82 | **************** 83 | Echo Test Source 84 | **************** 85 | 86 | RPMsg Echo Baremetal Source 87 | =========================== 88 | 89 | The RPMsg Echo service application is available as a baremetal solution in the 90 | `open-amp Repository `_ 91 | 92 | It is a CMake application and can be built for any remote as long as the relevant 93 | :ref:`OS/HW abstraction layer` components like libmetal are ported for 94 | that platform. 95 | 96 | .. _echo-test-linux-app: 97 | 98 | Echo Test Linux Source 99 | ====================== 100 | 101 | The echo test Linux application is executed on the Linux main controller as a user space application. 102 | The application is available in the 103 | `OpenAMP System Reference repository `_. 104 | 105 | It is a Makefile application and can be built using the 106 | `Yocto rpmsg-echo-test recipe `_ 107 | 108 | An example main control script is given in the 109 | :ref:`echo test readme` 110 | 111 | ******************************* 112 | Reference Board Implementations 113 | ******************************* 114 | 115 | This Echo Test Sample is demonstrated in the following reference implementations. 116 | 117 | * :ref:`Docker Images` as demo1A 118 | * :ref:`AMD-Xilinx platforms` 119 | * :ref:`Inter Process Demos` 120 | -------------------------------------------------------------------------------- /protocol_details/system_considerations.rst: -------------------------------------------------------------------------------- 1 | ========================== 2 | System Wide Considerations 3 | ========================== 4 | 5 | AMP systems could either be supervised (using a hypervisor to enforce isolation and resource 6 | virtualization) or unsupervised (modifying each participating software context to ensure best- 7 | effort isolation and cooperative usage of shared resources). With unsupervised AMP systems, there is 8 | no strict isolation or supervision of shared resource usage. 9 | 10 | Take the following system-wide considerations into account to develop unsupervised AMP systems 11 | using the OpenAMP framework. 12 | 13 | Determine system topology 14 | ------------------------- 15 | 16 | The OpenAMP framework implicitly assumes a host controller to remote system architecture. The 17 | `topology`for this architecture should be determined; either star, chain, or a combination. The 18 | following figure shows some simple use cases. 19 | 20 | * Case 1 — A single host controller software context on processor 1 controlling life cycle and 21 | communicating with two independent remote software contexts on processors 2 and 3, in star 22 | topology, 23 | 24 | * Case 2 — Host controller software context 1 on processor 1 brings up remote software 25 | context 1 on processor 2. This context acts as the host software context 2 for remote 26 | software context 2 on processor 3, in chain topology. 27 | 28 | .. image:: ../images/topo-types.svg 29 | 30 | Determine system and IO resource partitioning 31 | --------------------------------------------- 32 | 33 | Various OSs, RTOSs, and bare metal environments have their own preferred mechanisms for 34 | discovering platform-specific information such as available RAM memory, available peripheral IO 35 | resources (their memory-mapped IO region), clocks, interrupt resources, and so forth. 36 | 37 | For example, the Linux kernel uses device trees and bare metal environment typically define 38 | platform-specific device information in headers or dedicated data structures that would be 39 | compiled into the application. 40 | 41 | To ensure mutually-exclusive usage of unshared system (memory) and IO resources (peripherals) 42 | between the participating software environments in an AMP system, you are required to partition 43 | the resources so that each software environment is only aware of the resources that are available 44 | to it. This would involve, for example, removing unused resource nodes and modifying the 45 | available memory definitions from the device tree sources, platform definition files, headers, 46 | and so forth, to ensure best-effort partitioning of system resources. 47 | 48 | Determine memory layout 49 | ----------------------- 50 | 51 | For the purpose of this description, assume you are using the Zynq SOC used in AMP system 52 | architecture with SMP Linux running on the dual Cortex A9 cores, and a RTOS on one instance of 53 | Microblaze soft core, and bare metal on another instance of Microblaze soft core in the fabric. 54 | 55 | To develop an AMP system using the OpenAMP Framework, it is important to determine the memory 56 | regions that would be owned and shared between each of the participating software environments in 57 | the AMP system. For example, in a configuration such as this, the memory address ranges owned 58 | (for code/data/bss/heap) by each participating OS or bare metal context, and the shared memory 59 | regions to be used by IPC mechanisms (virtio rings and memory for data buffers) need to be 60 | determined. Memory alignment requirements should be taken into consideration while making this 61 | determination. 62 | 63 | The following image illustrates the memory layout for Linux host/RTOS-based remote application, 64 | and RTOS-based host/bare metal-based remote application in chain configuration. 65 | 66 | .. image:: ../images/memory_layout.jpg 67 | 68 | Ensure cooperative usage of shared resources between software environments in the AMP system 69 | -------------------------------------------------------------------------------------------- 70 | 71 | For the purpose of this discussion, assume you are using a Linux host/bare metal- based remote 72 | system configuration. 73 | 74 | The interrupt controller is typically a shared resource in multicore SoCs. It is general practice 75 | for OSs to reset and initialize (clear and disable all interrupts) the interrupt controller 76 | during their boot sequence given the general assumption that the OS would own the entire system. 77 | This will not work in AMP systems; if an OS in remote software context resets and initializes the 78 | interrupt controller, it would catastrophically break the host controller software context's 79 | runtime since the host context could already be using the interrupt controller to manage its 80 | interrupt resources. 81 | 82 | Therefore, remote software environments should be patched such that they 83 | cooperatively use the interrupt controller (for example, do not reset/clear/disable all 84 | interrupts blindly but initialize only the interrupts that belong to the remote context). Ensure 85 | the timer peripheral used by the remote OS/RTOS context is different from the one used by the 86 | host controller software context so the individual runtimes do not interfere with each other. 87 | 88 | -------------------------------------------------------------------------------- /images/design/img-src/coprocessor-rpmsg-ns.gv: -------------------------------------------------------------------------------- 1 | // RPMsg dynamic endpoints binding 2 | 3 | digraph G { 4 | rankdir="LR"; 5 | 6 | subgraph roles { 7 | node [style="filled", fillcolor="lightblue"]; 8 | host [label="Host"]; 9 | remote [label="Remote"]; 10 | } 11 | 12 | subgraph m_comment_nodes { 13 | node [group=m_comment, shape="note", style="filled", fillcolor="yellow"]; 14 | rank="same"; 15 | m_remoteproc_init_comment [label="this is initialize rproc call"]; 16 | m_remoteproc_boot_comment [label="it will setup vdev before booting the remote"]; 17 | m_rpmsg_vdev_init_comment [label="\l* It will initialize vrings with the shared memory\l* As vdev doesn't support name service, it will not create name service endpoint;\l* it sets vdev status to DRVIER_READY, And will notify remote.\l"]; 18 | m_rpmsg_create_ep_comment [label="\lIf vdev supports name service,\lit will send out name service.\l"]; 19 | m_rpmsg_send_comment [label="\lIf endpoint hasn't binded, it fail\lreturn failure to indicate ep hasn't been binded.\l"]; 20 | 21 | } 22 | 23 | subgraph m_flow_nodes { 24 | node [shape="box"]; 25 | rank="same"; 26 | m_remoteproc_init [label="rproc = remoteproc_init(&remoteproc_ops, &arg);"] 27 | m_remoteproc_load [label="calls remoteproc_load() to load application"]; 28 | m_remoteproc_boot [shape="box", label="ret=remoteproc_boot(&rproc)"]; 29 | m_remoteproc_get_vdev [label="vdev=remoteproc_create_virtio(rproc, rpmsg_vdev_id, VIRTIO_DEV_DRIVER, NULL);"]; 30 | m_rpmsg_shmpool_init[label="rpmsg_virtio_init_shm_pool(shpool, shbuf, shbuf_pool_size);"]; 31 | m_rpmsg_vdev_init [label="rpdev=rpmsg_init_vdev(rpvdev, vdev, ns_bind_cb, &shm_io, shpool);"]; 32 | m_rpmsg_ns_cb [label="\lrpmsg_ns_callback() will see if there is a local ep registered.\lIf yes, bind the ep; otherwise, call ns_bind_cb.\l"]; 33 | m_rpmsg_create_ep [label="\lept=rpmsg_create_ept(ept, rdev, ept_name, ept_addr, dest_addr, \lendpoint_cb, ns_unbind_cb);\l"]; 34 | m_rpmsg_send [label="rpmsg_send(ept,data)"]; 35 | m_rpmsg_rx_cb [label="rpmsg_rx_callback()"]; 36 | m_ep_cb [label="endpoint_cb(ept, data, size, src_addr)"]; 37 | m_rpmsg_destroy_ep [label="rpmsg_destroy_endpoint(ept)"]; 38 | 39 | m_remoteproc_init -> m_remoteproc_load -> m_remoteproc_boot -> m_remoteproc_get_vdev -> 40 | m_rpmsg_shmpool_init -> m_rpmsg_vdev_init -> m_rpmsg_ns_cb -> m_rpmsg_create_ep -> m_rpmsg_send; 41 | m_rpmsg_send -> m_rpmsg_rx_cb -> m_ep_cb -> 42 | m_rpmsg_destroy_ep [dir="none", style="dashed"]; 43 | } 44 | 45 | subgraph s_flow_nodes { 46 | rank="same"; 47 | node [shape="box"]; 48 | s_remoteproc_init [label="rproc = remoteproc_init(&remoteproc_ops, &arg);"]; 49 | 50 | s_remoteproc_parse_rsc [label="ret = remoteproc_set_rsc_table(rproc, &rsc_table, rsc_size)"]; 51 | s_remoteproc_get_vdev [label="vdev=remoteproc_create_virtio(rproc, rpmsg_vdev_id, VIRTIO_DEV_DEVICE, rst_cb);"]; 52 | s_rpmsg_vdev_init [label="rpdev=rpmsg_init_vdev(rpvdev, vdev, ns_bind_cb, &shm_io, NULL);"]; 53 | s_rpmsg_create_ep [label="\lept=rpmsg_create_ept(ept, rdev, ept_name, ept_addr, dest_addr, \lendpoint_cb, ns_unbind_cb);\l"]; 54 | s_rpmsg_ns_cb [label="\lrpmsg_ns_callback() will see if there is a local ep registered.\lIf yes, bind the ep; otherwise, call ns_binc_cb.\l"]; 55 | s_rpmsg_send [label="rpmsg_send(ept,data)"]; 56 | s_rpmsg_rx_cb [label="rpmsg_rx_callback()"]; 57 | s_ep_cb [label="endpoint_cb(ept, data, size, src_addr)"]; 58 | s_rpmsg_ns_unbind_cb [label="\lrpmsg_ns_callback() will call the previous\lregistered endpoint unbind callback\l"]; 59 | 60 | s_remoteproc_init -> s_remoteproc_parse_rsc -> s_remoteproc_get_vdev -> 61 | s_rpmsg_vdev_init -> s_rpmsg_create_ep; 62 | s_rpmsg_create_ep -> s_rpmsg_ns_cb -> s_rpmsg_rx_cb -> 63 | s_ep_cb -> s_rpmsg_send -> s_rpmsg_ns_unbind_cb [dir="none", style="dash"]; 64 | 65 | } 66 | 67 | subgraph s_comment_nodes { 68 | node [group=s_comment, shape="note", style="filled", fillcolor="yellow"]; 69 | rank="same"; 70 | s_rpmsg_vdev_init_comment [label="\l* If vdev supports name service, it will create name service endpoint;\l* It will not return until the host set status to DRIVER READY\l"]; 71 | s_rpmsg_rx_cb_comment [label="\l* It will look for the endpoint which matches the destination address.\lIf the two endpoints hasn't binded yet,\lit will set the local endpoint's destination address with the source address in the message\l"]; 72 | } 73 | 74 | host -> m_remoteproc_init [dir="none"]; 75 | remote -> s_remoteproc_init [dir="none"]; 76 | s_rpmsg_create_ep -> m_rpmsg_ns_cb [label="NS announcement"]; 77 | m_rpmsg_create_ep -> s_rpmsg_ns_cb [label="NS announcement"]; 78 | m_rpmsg_send -> s_rpmsg_rx_cb [label="RPMsg data"]; 79 | s_rpmsg_send -> m_rpmsg_rx_cb [label="RPMsg data"]; 80 | m_rpmsg_destroy_ep -> s_rpmsg_ns_unbind_cb [label="Endpoint destroy NS"]; 81 | 82 | m_remoteproc_init_comment -> m_remoteproc_init [dir="none"]; 83 | m_remoteproc_boot_comment -> m_remoteproc_boot [dir="none"]; 84 | m_rpmsg_vdev_init_comment -> m_rpmsg_vdev_init [dir="none"]; 85 | m_rpmsg_create_ep_comment -> m_rpmsg_create_ep [dir="none"]; 86 | m_rpmsg_send_comment -> m_rpmsg_send [dir="none"]; 87 | 88 | s_rpmsg_vdev_init -> s_rpmsg_vdev_init_comment [dir="none"]; 89 | s_rpmsg_rx_cb -> s_rpmsg_rx_cb_comment [dir="none"]; 90 | 91 | {rank=same; host; m_remoteproc_init} 92 | {rank=same; remote; s_remoteproc_init} 93 | 94 | } 95 | 96 | -------------------------------------------------------------------------------- /images/design/img-src/coprocessor-rpmsg-ns-dynamic.gv: -------------------------------------------------------------------------------- 1 | // RPMsg dynamic endpoint creation 2 | 3 | digraph G { 4 | rankdir="LR"; 5 | 6 | subgraph roles { 7 | node [style="filled", fillcolor="lightblue"]; 8 | host [label="Host"]; 9 | remote [label="Remote"]; 10 | } 11 | 12 | subgraph m_comment_nodes { 13 | node [group=m_comment, shape="note", style="filled", fillcolor="yellow"]; 14 | rank="same"; 15 | m_remoteproc_init_comment [label="this is initialize rproc call"]; 16 | m_remoteproc_boot_comment [label="it will setup vdev before booting the remote"]; 17 | m_rpmsg_vdev_init_comment [label="\l* It will initialize vrings with the shared memory\l* If vdev supports name service, it will create name service endpoint;\l* it sets vdev status to DRVIER_READY, And will notify remote.\l"]; 18 | m_rpmsg_create_ep_comment [label="\if vdev supports name service,\lit will send out name service.\l"]; 19 | m_rpmsg_send_comment [label="\lIf endpoint hasn't binded, it fail\lreturn failure to indicate ep hasn't been binded.\l"]; 20 | 21 | } 22 | 23 | subgraph m_flow_nodes { 24 | node [shape="box"]; 25 | rank="same"; 26 | m_remoteproc_init [label="rproc = remoteproc_init(&remoteproc_ops, &arg);"] 27 | m_remoteproc_load [label="calls remoteproc_load() to load application"]; 28 | m_remoteproc_boot [shape="box", label="ret=remoteproc_boot(&rproc)"]; 29 | m_remoteproc_get_vdev [label="vdev=remoteproc_create_virtio(rproc, rpmsg_vdev_id, VIRTIO_DEV_DRIVER, NULL);"]; 30 | m_rpmsg_shmpool_init[label="rpmsg_virtio_init_shm_pool(shpool, shbuf, shbuf_pool_size);"]; 31 | m_rpmsg_vdev_init [label="rpdev=rpmsg_init_vdev(rpvdev, vdev, ns_bind_cb, &shm_io, shpool);"]; 32 | m_rpmsg_ns_cb [label="\lrpmsg_ns_callback() will see if there is a local ep registered.\lIf yes, bind the ep; otherwise, call ns_bind_cb.\l"]; 33 | m_rpmsg_create_ep [label="\lept=rpmsg_create_ept(ept, rdev, ept_name, ept_addr, dest_addr, \lendpoint_cb, ns_unbind_cb);\l"]; 34 | m_rpmsg_send [label="rpmsg_send(ept,data)"]; 35 | m_rpmsg_rx_cb [label="rpmsg_rx_callback()"]; 36 | m_ep_cb [label="endpoint_cb(ept, data, size, src_addr)"]; 37 | m_rpmsg_destroy_ep [label="rpmsg_destroy_endpoint(ept)"]; 38 | 39 | m_remoteproc_init -> m_remoteproc_load -> m_remoteproc_boot -> m_remoteproc_get_vdev -> 40 | m_rpmsg_shmpool_init -> m_rpmsg_vdev_init -> m_rpmsg_create_ep -> m_rpmsg_ns_cb -> m_rpmsg_send; 41 | m_rpmsg_send -> m_rpmsg_rx_cb -> m_ep_cb -> 42 | m_rpmsg_destroy_ep [dir="none", style="dashed"]; 43 | } 44 | 45 | subgraph s_flow_nodes { 46 | rank="same"; 47 | node [shape="box"]; 48 | s_remoteproc_init [label="rproc = remoteproc_init(&remoteproc_ops, &arg);"]; 49 | 50 | s_remoteproc_parse_rsc [label="ret = remoteproc_set_rsc_table(rproc, &rsc_table, rsc_size)"]; 51 | s_remoteproc_get_vdev [label="vdev=remoteproc_create_virtio(rproc, rpmsg_vdev_id, VIRTIO_DEV_DEVICE, rst_cb);"]; 52 | s_rpmsg_vdev_init [label="rpdev=rpmsg_init_vdev(rpvdev, vdev, ns_bind_cb, &shm_io, NULL);"]; 53 | s_rpmsg_ns_cb [label="\lrpmsg_ns_callback() will see if there is a local ep registered.\lIf yes, bind the ep; otherwise, it will call ns_bind_cb()."]; 54 | s_rpmsg_ns_bind_cb [label="s_rpsmg_ns_bind_cb(ept_name, remote_addr)"]; 55 | s_rpmsg_create_ep [label="\lept=rpmsg_create_endpoint(ept, rdev, ept_name, ept_addr, remote_addr,\lendpoint_cb, ns_unbind_cb);\l"]; 56 | s_rpmsg_send [label="rpmsg_send(ept,data)"]; 57 | s_rpmsg_rx_cb [label="rpmsg_rx_callback()"]; 58 | s_ep_cb [label="endpoint_cb(ept, data, size, src_addr)"]; 59 | s_rpmsg_ns_unbind_cb [label="\lrpmsg_ns_callback() will call the previous\lregistered endpoint unbind callback\l"]; 60 | 61 | s_remoteproc_init -> s_remoteproc_parse_rsc -> s_remoteproc_get_vdev -> 62 | s_rpmsg_vdev_init -> s_rpmsg_ns_cb -> s_rpmsg_ns_bind_cb -> 63 | s_rpmsg_create_ep; 64 | s_rpmsg_create_ep-> s_rpmsg_rx_cb -> s_ep_cb -> s_rpmsg_send -> 65 | s_rpmsg_ns_unbind_cb [dir="none", style="dash"]; 66 | 67 | } 68 | 69 | subgraph s_comment_nodes { 70 | node [group=s_comment, shape="note", style="filled", fillcolor="yellow"]; 71 | rank="same"; 72 | s_rpmsg_vdev_init_comment [label="\l* If vdev supports name service, it will create name service endpoint;\l* It will not return until the host set status to DRIVER READY\l"]; 73 | s_rpmsg_rx_cb_comment [label="\l* It will look for the endpoint which matches the destination address.\lIf the two endpoints hasn't binded yet,\lit will set the local endpoint's destination address with the source address in the message\l"]; 74 | } 75 | 76 | host -> m_remoteproc_init [dir="none"]; 77 | remote -> s_remoteproc_init [dir="none"]; 78 | s_rpmsg_create_ep -> m_rpmsg_ns_cb [label="NS announcement"]; 79 | m_rpmsg_create_ep -> s_rpmsg_ns_cb [label="NS announcement"]; 80 | m_rpmsg_send -> s_rpmsg_rx_cb [label="RPMsg data"]; 81 | s_rpmsg_send -> m_rpmsg_rx_cb [label="RPMsg data"]; 82 | m_rpmsg_destroy_ep -> s_rpmsg_ns_unbind_cb [label="Endpoint destroy NS"]; 83 | 84 | m_remoteproc_init_comment -> m_remoteproc_init [dir="none"]; 85 | m_remoteproc_boot_comment -> m_remoteproc_boot [dir="none"]; 86 | m_rpmsg_vdev_init_comment -> m_rpmsg_vdev_init [dir="none"]; 87 | m_rpmsg_create_ep_comment -> m_rpmsg_create_ep [dir="none"]; 88 | m_rpmsg_send_comment -> m_rpmsg_send [dir="none"]; 89 | 90 | s_rpmsg_vdev_init -> s_rpmsg_vdev_init_comment [dir="none"]; 91 | s_rpmsg_rx_cb -> s_rpmsg_rx_cb_comment [dir="none"]; 92 | 93 | {rank=same; host; m_remoteproc_init} 94 | {rank=same; remote; s_remoteproc_init} 95 | 96 | } 97 | 98 | -------------------------------------------------------------------------------- /docs/remoteproc_design.rst: -------------------------------------------------------------------------------- 1 | Remoteproc Design Document 2 | =========================== 3 | 4 | Remoteproc provides abstraction to manage the life cycle of a remote 5 | application. For now, it only provides APIs on bringing up and 6 | tearing down the remote application, and parsing resource table. 7 | It will extend to crash detection, suspend and resume. 8 | 9 | Remoteproc LCM States 10 | --------------------- 11 | 12 | .. csv-table:: 13 | :header: "State", "State Description" 14 | :widths: 50, 200 15 | 16 | Offline, "Initial state of a remoteproc instance. The remote presented by the remoteproc instance and its resource has been powered off." 17 | Configured, "The remote presented by the remoteproc instance has been configured. And ready to load application." 18 | Ready, "The remote presented by the remoteproc instance has application loaded, and ready to run." 19 | Stopped, "The remote presented by the remoteproc instance has stopped from running. But the remote is still powered on. And the remote's resource hasn't been released." 20 | 21 | .. image:: ../images/design/img/rproc-lcm-state-machine.png 22 | 23 | 24 | State Transition 25 | ---------------- 26 | 27 | .. csv-table:: 28 | :header: "State Transition", "Transition Trigger" 29 | :widths: 50, 200 30 | 31 | Offline -> Configured, "Configure the remote to make it able to load application :ref:`remoteproc_config`" 32 | Configured -> Ready, "load firmware :ref:`remoteproc_load`" 33 | Ready -> Running, "start the processor :ref:`remoteproc_start`" 34 | Ready -> Stopped, "stop the processor :ref:`remoteproc_stop`, :ref:`remoteproc_shutdown` (Stopped is the intermediate state of shutdown operation)" 35 | Running -> Stopped, "stop the processor :ref:`remoteproc_stop`, :ref:`remoteproc_shutdown`" 36 | Stopped -> Offline, "shutdown the processor :ref:`remoteproc_shutdown`" 37 | 38 | Remote User APIs 39 | ---------------- 40 | .. _remoteproc_config: 41 | Configure remote 42 | ^^^^^^^^^^^^^^^^ 43 | 44 | .. doxygenfunction:: remoteproc_config 45 | :project: openamp_doc_embed 46 | 47 | Initialize remoteproc instance 48 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 49 | 50 | .. doxygenfunction:: remoteproc_init 51 | :project: openamp_doc_embed 52 | 53 | Release remoteproc instance 54 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^ 55 | 56 | .. doxygenfunction:: remoteproc_remove 57 | :project: openamp_doc_embed 58 | 59 | Add memory to remoteproc 60 | ^^^^^^^^^^^^^^^^^^^^^^^^ 61 | 62 | .. doxygenfunction:: remoteproc_add_mem 63 | :project: openamp_doc_embed 64 | 65 | Get memory libmetal I/O region from remoteproc specifying memory name 66 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 67 | 68 | .. doxygenfunction:: remoteproc_get_io_with_name 69 | :project: openamp_doc_embed 70 | 71 | Get memory libmetal I/O region from remoteproc specifying physical address 72 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 73 | 74 | .. doxygenfunction:: remoteproc_get_io_with_pa 75 | :project: openamp_doc_embed 76 | 77 | Get memory libmetal I/O region from remoteproc specifying virtual address 78 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 79 | 80 | .. doxygenfunction:: remoteproc_get_io_with_va 81 | :project: openamp_doc_embed 82 | 83 | Map memory and add the memory to the remoteproc instance 84 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 85 | 86 | .. doxygenfunction:: remoteproc_mmap 87 | :project: openamp_doc_embed 88 | 89 | Set resource table to remoteproc 90 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 91 | 92 | .. doxygenfunction:: remoteproc_set_rsc_table 93 | :project: openamp_doc_embed 94 | 95 | Configure the remote presented by the remoteproc instance to make it able to load application 96 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 97 | 98 | .. doxygenfunction:: remoteproc_config 99 | :project: openamp_doc_embed 100 | 101 | Load application to the remote presented by the remoteproc instance to make it ready to run 102 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 103 | 104 | .. _remoteproc_load: 105 | .. doxygenfunction:: remoteproc_load 106 | :project: openamp_doc_embed 107 | 108 | Run application on the remote presented by the remoteproc instance 109 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 110 | .. _remoteproc_start: 111 | .. doxygenfunction:: remoteproc_start 112 | :project: openamp_doc_embed 113 | 114 | Stop application on remote presented by the remoteproc instance 115 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 116 | .. _remoteproc_stop: 117 | .. doxygenfunction:: remoteproc_stop 118 | :project: openamp_doc_embed 119 | 120 | Shutdown the remote presented by the remoteproc instance 121 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 122 | .. _remoteproc_shutdown: 123 | .. doxygenfunction:: remoteproc_shutdown 124 | :project: openamp_doc_embed 125 | 126 | Create virtio device from the resource table vdev resource, and add it to the remoteproc instance 127 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 128 | 129 | .. doxygenfunction:: remoteproc_create_virtio 130 | :project: openamp_doc_embed 131 | 132 | Remove virtio device from the remoteproc instance 133 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 134 | 135 | .. doxygenfunction:: remoteproc_remove_virtio 136 | :project: openamp_doc_embed 137 | -------------------------------------------------------------------------------- /conf.py: -------------------------------------------------------------------------------- 1 | # Configuration file for the Sphinx documentation builder. 2 | # 3 | # This file only contains a selection of the most common options. For a full 4 | # list see the documentation: 5 | # https://www.sphinx-doc.org/en/master/usage/configuration.html 6 | 7 | # -- Work flow context ------------------------------------------------------- 8 | import os 9 | import subprocess 10 | from datetime import datetime 11 | 12 | pwd = os.getcwd() 13 | readthedocs_dir = os.environ.get('READTHEDOCS_OUTPUT', f'{pwd}/_build') 14 | url_base = os.environ.get('READTHEDOCS_CANONICAL_URL', "file:" + readthedocs_dir + "/html/") 15 | if not url_base.endswith("/"): 16 | url_base = url_base + "/" 17 | 18 | version = os.environ.get('READTHEDOCS_VERSION', "desk check") 19 | is_release = version.startswith(("v", "V")) 20 | is_pr = not is_release and version != "latest" 21 | latest_url = "https://openamp.readthedocs.io/en/latest/" 22 | 23 | #print(f"url_base: {url_base} version: {version} is_release: {is_release} is_pr: {is_pr}") 24 | 25 | # -- Path setup -------------------------------------------------------------- 26 | 27 | # If extensions (or modules to document with autodoc) are in another directory, 28 | # add these directories to sys.path here. If the directory is relative to the 29 | # documentation root, use os.path.abspath to make it absolute, like shown here. 30 | # 31 | # import sys 32 | # sys.path.insert(0, os.path.abspath('.')) 33 | 34 | 35 | # -- Project information ----------------------------------------------------- 36 | 37 | # Get the commit year of the head commit 38 | ts = subprocess.check_output(['git', 'show', '--no-patch', '--no-notes', '--format=%ct', 'HEAD']) 39 | ts = int(ts) 40 | year = datetime.utcfromtimestamp(ts).strftime('%Y') 41 | copyright = year + ", OpenAMP project" 42 | 43 | project = 'OpenAMP' 44 | author = 'OpenAMP Project' 45 | 46 | # The full version, including alpha/beta/rc tags 47 | release = '' 48 | 49 | 50 | # -- General configuration --------------------------------------------------- 51 | 52 | # Add any Sphinx extension module names here, as strings. They can be 53 | # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom 54 | # ones. 55 | extensions = [ 56 | "sphinxcontrib.jquery", 57 | 'sphinx.ext.autosectionlabel', 58 | 'sphinxcontrib.plantuml', 59 | 'sphinx.ext.viewcode', 60 | 'sphinx.ext.graphviz', 61 | 'sphinx.ext.todo', 62 | 'rst2pdf.pdfbuilder', 63 | 'myst_parser', 64 | 'sphinxcontrib.doxylink', 65 | 'breathe' 66 | ] 67 | 68 | # Name doxylink "links" to library repositories _doc_link as it is a 69 | # link to doxygen pages 70 | doxylink = { 71 | 'openamp_doc_link': (f'{readthedocs_dir}/openamp/doc/openamp_lib.tag', f'{url_base}doxygen/openamp'), 72 | 'libmetal_doc_link': (f'{readthedocs_dir}/libmetal/doc/libmetal.tag', f'{url_base}doxygen/libmetal') 73 | } 74 | 75 | # Name breathe projects "embedded" content _doc_embed as doxygen 76 | # content is embedded into sphinx pages 77 | breathe_projects = { 78 | "openamp_doc_embed": f'{readthedocs_dir}/openamp/doc/xml', 79 | "libmetal_doc_embed": f'{readthedocs_dir}/libmetal/doc/xml' 80 | } 81 | breathe_default_project = "openamp_doc_embed" 82 | 83 | pdf_documents = [('index', u'openamppdf', u'Sample openamppdf doc', u'Tammy Leino'),] 84 | 85 | #plantuml = '/usr/bin/plantuml -Djava.awt.headless=true -config uml/plantuml.cfg ' 86 | 87 | # Add any paths that contain templates here, relative to this directory. 88 | templates_path = ['_templates'] 89 | 90 | # The suffix(es) of source filenames. 91 | # You can specify multiple suffix as a list of string: 92 | # 93 | # source_suffix = ['.rst', '.md'] 94 | source_suffix = '.rst' 95 | 96 | # The master toctree document. 97 | master_doc = 'index' 98 | # List of patterns, relative to source directory, that match files and 99 | # directories to ignore when looking for source files. 100 | # This pattern also affects html_static_path and html_extra_path. 101 | exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '.git'] 102 | 103 | # The name of the Pygments (syntax highlighting) style to use. 104 | pygments_style = 'sphinx' 105 | 106 | 107 | # -- Options for HTML output ------------------------------------------------- 108 | 109 | # The theme to use for HTML and HTML Help pages. See the documentation for 110 | # a list of builtin themes. 111 | # 112 | html_theme = 'sphinx_rtd_theme' 113 | 114 | # Add any paths that contain custom static files (such as style sheets) here, 115 | # relative to this directory. They are copied after the builtin static files, 116 | # so a file named "default.css" will overwrite the builtin "default.css". 117 | html_static_path = ['_static'] 118 | html_style = 'css/mystyle.css' 119 | html_logo = '_static/images/openAMP_combox_dark_trim.svg' 120 | 121 | html_theme_options = { 122 | 'logo_only': True 123 | } 124 | 125 | # below copied / hacked from Zephyr projects' zephyr/doc/conf.py 126 | docs_title = "Docs / {}".format(version if is_release else "Latest") 127 | html_context = { 128 | "show_license": True, 129 | "docs_title": docs_title, 130 | "is_release": is_release, 131 | "is_pr": is_pr, 132 | "current_version": version, 133 | "html_base": url_base, 134 | "latest_url": latest_url, 135 | "display_vcs_link": False, 136 | "reference_links": { 137 | "open-amp API": f"{url_base}doxygen/openamp/index.html", 138 | "libmetal API": f"{url_base}doxygen/libmetal/index.html", 139 | "System Devicetree Spec": f"{url_base}lopper/specification/source/index.html", 140 | } 141 | } 142 | 143 | # Set automatically generated heading anchors to 4 levels, i.e. h1,h2,h3,h4 144 | myst_heading_anchors = 4 145 | autosectionlabel_prefix_document = True 146 | 147 | print(f"url_base: {url_base} version: {version} is_release: {is_release} is_pr: {is_pr}") 148 | print(f"html_context: {html_context}") 149 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # openamp_docs 2 | OpenAMP Documentation sources for Sphinx 3 | 4 | If you are looking for the end-user version of the documentation, you can 5 | find [the OpenAMP Readthedocs site here](https://openamp.readthedocs.io/en/latest/index.html "OpenAMP Readthedocs site"). 6 | 7 | ## How to Contribute 8 | 9 | The OpenAMP Documentation is an open source project and welcomes community contributions. 10 | 11 | We use standard Github mechanism for a pull request (PR). Please refer to github documentation 12 | for help. 13 | 14 | We recommend you verify your changes locally using the 15 | [Desktop Build and Review](#desktop-build-and-review) before submitting 16 | for an [Online Pull Request and Review](#online-pull-request-and-review) 17 | 18 | ## Documentation Guidelines 19 | 20 | The following are guidelines to follow as part of your contribution. 21 | 22 | * Documentation should use Restructured Text files ending in .rst for consumption by 23 | [Sphinx](https://www.sphinx-doc.org/en/master/index.html) 24 | * Maintain a document source line length of 100 characters when possible 25 | * For cross-references to documentation in source code submodules use 26 | [auto-generated anchors](#cross-referencing-to-markdown-files) 27 | * To link to source code you should use 28 | [embedded doxygen content or a hyperlink](#linking-to-source-code) 29 | * For tables use 30 | * [Grid Tables](https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#grid-tables) 31 | when possible, for clearer reading in the document source or 32 | * [CSV Tables](https://docutils.sourceforge.io/docs/ref/rst/directives.html#csv-table) 33 | 34 | ## Online Pull Request and Review 35 | 36 | Creating a PR for openamp/openamp-docs will build the new docs and they can be reviewed in the PR. 37 | 38 | You can locate the Sphinx rendered documentation for the PR by 39 | * Opening the pull request in 40 | [Github OpenAMP Pull Requests](https://github.com/OpenAMP/openamp-docs/pulls) 41 | * Clicking the down arrow next to the **All checks have passed** at the 42 | bottom of the PR 43 | * Clicking on the link to **docs/readthedocs.org:openamp** 44 | 45 | ## Desktop Build and Review 46 | 47 | If you wish to build the documents on the desktop, you can do as follows. 48 | 49 | ### Setup for Ubuntu (only the first time) 50 | 51 | Setup Linux system requirements: 52 | 53 | $ sudo apt update 54 | $ sudo apt install cmake doxygen libhugetlbfs-dev libsysfs-dev 55 | $ sudo apt install python3-pip git 56 | 57 | Setup the document repository on your machine: 58 | 59 | $ git clone --recurse https://github.com/openAMP/openamp-docs.git 60 | $ cd openamp-docs 61 | $ git submodule update 62 | 63 | ### Building using virtual environment 64 | 65 | When possible it is recommended to use a 66 | [Python virtual environment](https://docs.python.org/3/library/venv.html) 67 | (Python 3.3 and higher, required by Ubuntu 24.04 or higher): 68 | 69 | $ python3 -m venv .venv 70 | $ . .venv/bin/activate 71 | 72 | Install pip modules 73 | 74 | $ python3 -m pip install -r requirements.txt 75 | 76 | #### Activate the virtual environment for build session 77 | 78 | When using a virtual environment activate it before each build session: 79 | 80 | $ cd openamp-docs 81 | $ . .venv/bin/activate 82 | 83 | ### Build and view the html documents 84 | 85 | $ make html 86 | $ xdg-open _build/html/index.html 87 | 88 | ### Build and view the pdf 89 | 90 | $ make pdf 91 | $ xdg-open _build/pdf/openamppdf.pdf 92 | 93 | Notes: 94 | * The build process currently produces many warnings 95 | * The doxygen content is not included in the pdf 96 | * The doxygen content is not styled like the rest of the html documents 97 | * The doxygen context does not integrate into the menu structure; use the browser back button 98 | to get back. 99 | 100 | ## Cross-Referencing to Markdown files 101 | 102 | When making a cross-reference from a Restructured text (rst) file to a Markdown file (md), 103 | usually in a source code repository like open-amp or libmetal, you should do so by leveraging the 104 | [auto-generated header anchors](https://myst-parser.readthedocs.io/en/stable/syntax/optional.html#syntax-header-anchors). 105 | 106 | For example this example is a reference to a markdown file within the git submodule lopper's 107 | README-architecture.md file section 'Lopper Processing Flow' 108 | 109 | ``` 110 | :ref:`Lopper Architecture Readme` 111 | ``` 112 | 113 | This will ensure that references are to the version of git submodule being described by the 114 | documentation. 115 | 116 | ## Linking to Source Code 117 | 118 | When cross-referencing to source code there are two methods you can use. 119 | You can embed the source code 'item', be it a struct or function etc, within your documentation, 120 | or provide a link to within the full doxygen generated documentation. 121 | 122 | ### Embedding Source Code Documentation 123 | 124 | Embedding doxygen generated documentation from the source code repository is achieved using the 125 | [Breathe Sphinx extension](https://breathe.readthedocs.io). 126 | 127 | The following are examples of embedding the doxygen content. Two projects are defined for the 128 | open-amp and libmetal repositories, named openamp_doc_embed and libmetal_doc_embed respectively. 129 | 130 | * libmetal function "metal_allocate_memory" 131 | 132 | ``` 133 | .. doxygenfunction:: metal_allocate_memory 134 | :project: libmetal_doc_embed 135 | ``` 136 | 137 | * open-amp type definition "rpmsg_ns_unbind_cb" 138 | 139 | ``` 140 | .. doxygentypedef:: rpmsg_ns_unbind_cb 141 | :project: openamp_doc_embed 142 | ``` 143 | 144 | * open-amp structure "remoteproc_virtio", including the members of the struct 145 | 146 | ``` 147 | .. doxygenstruct:: remoteproc_virtio 148 | :members: 149 | ``` 150 | 151 | Note on the last example the project is not named, so the default openamp_doc_embed project 152 | is used. 153 | 154 | ### Linking to Source Code Documentation 155 | 156 | It is also possible to create a hyperlink to the doxygen generated documentation of the source. 157 | This is achieved using the [Doxylink extension](https://sphinxcontrib-doxylink.readthedocs.io). 158 | 159 | The following are examples of creating hyperlinks to the doxygen generated documentation. 160 | 161 | * open-amp rpmsg_device structure 162 | ``` 163 | :openamp_doc_link:`rpmsg_device ` 164 | ``` 165 | 166 | * libmetal metal_sys_init function 167 | ``` 168 | :libmetal_doc_link:`metal_sys_init ` 169 | ``` 170 | -------------------------------------------------------------------------------- /demos/matrix_multiply.rst: -------------------------------------------------------------------------------- 1 | ============================== 2 | OpenAMP Matrix Multiply Sample 3 | ============================== 4 | 5 | .. _matrix-multiply-intro: 6 | 7 | ********************* 8 | Matrix Multiply Intro 9 | ********************* 10 | 11 | The matrix multiply reference sample, as the name suggests, demonstrates OpenAMP 12 | :ref:`Interprocessor Communications (IPC)` components through matrix multiplication. 13 | The demonstration uses a main controller client, which generates random matrices. It sends them to a 14 | service/daemon on a remote which performs a matrix calculation and returns the result via a 15 | :ref:`RPMsg endpoint `. The main controller then writes the matrix result to console 16 | output. 17 | 18 | .. image:: ../images/demos/matrix-multiply-intro.svg 19 | 20 | .. _matrix-multiply-components: 21 | 22 | ************************** 23 | Matrix Multiply Components 24 | ************************** 25 | 26 | There are two applications involved in this demonstration. 27 | The :ref:`remote application` runs as an daemon/service which performs a 28 | matrix calculation and returns the result on an :ref:`RPMsg endpoint `. 29 | The :ref:`main controller application` is the client application sending 30 | two matrices as a packet to the daemon/service and monitoring for the return result. 31 | 32 | The underlying OpenAMP architectural components used by these applications are 33 | 34 | * :ref:`Remoteproc` 35 | * :ref:`Resource Table` 36 | * :ref:`RPMsg` 37 | * :ref:`Virtio` 38 | * :ref:`Libmetal` 39 | 40 | The following architecture diagram shows the components involved in the demonstration. 41 | 42 | .. image:: ../images/demos/matrix-multiply-components.svg 43 | 44 | The top-level control flow is shown in the following message diagram. 45 | 46 | .. image:: ../images/demos/matrix-multiply-control-flow.svg 47 | 48 | .. _matrix-multiply-remote-app: 49 | 50 | RPMsg Matrix Multiply Remote Application 51 | ======================================== 52 | 53 | The remote application, 54 | `matrix_multiplyd `_, 55 | is the core of the demonstration. It is a simple application serving a 56 | :ref:`RPMsg endpoint ` running as the main task on the remote processor. 57 | 58 | 59 | .. _matrix-multiply-host-app: 60 | 61 | Matrix Multiply Main Application 62 | ================================ 63 | 64 | The main controller application generates two matrices into a structure with size and 6x6 matrix, 65 | sequentially into a RPMsg packet. It then waits for matrix sized bytes to be returned and prints the 66 | resultant matrix as calculated by the remote. 67 | 68 | There are two implementations. The 69 | `mat_mul_demo `_ 70 | application forms the main controller side of the demonstration, as a linux user space client 71 | application. The 72 | `matrix_multiply `_ 73 | application forms the main controller side of the demonstration, as a baremetal client application. 74 | 75 | 76 | Matrix Multiply Main Script 77 | =========================== 78 | 79 | The main controller is also responsible for loading the firmware containing the 80 | :ref:`RPMsg Matrix Multiply Remote Application` and starting the remote 81 | processor using :ref:`Remoteproc`. 82 | 83 | For main controllers, like Linux, a script can be used to pipe the firmware to the exposed 84 | remoteproc system, followed by the execution of the user space mat_mul_demo application. For 85 | controllers without scripting capability, like baremetal and RTOS (Real Time Operating systems), 86 | this would be achieved in the code. 87 | 88 | ********************** 89 | Matrix Multiply Source 90 | ********************** 91 | 92 | RPMsg Matrix Multiply Baremetal Sources 93 | ======================================= 94 | 95 | There are two baremetal applications, a daemon/service to run on the remote and a main controller 96 | application which is the matrix multiply client requesting the calculations. 97 | 98 | The RPMsg Matrix Multiply daemon/service application is available as a baremetal solution in the 99 | `OpenAMP Repository `_. 100 | Take note of the d for daemon at the end of the file. 101 | 102 | The RPMsg Matrix Multiple main controller client application is available as a baremetal solution in 103 | the `OpenAMP Repository `_. 104 | 105 | Both are CMake applications and can be built for any remote as long as the relevant 106 | :ref:`OS/HW abstraction layer` components like libmetal are ported for that 107 | platform. 108 | 109 | .. _matrix-multiply-linux-app: 110 | 111 | Matrix Multiply Linux Source 112 | ============================ 113 | 114 | The matrix multiply Linux application is executed on the Linux main controller as a user space 115 | application. 116 | The application is available in the 117 | `OpenAMP System Reference repository `_. 118 | 119 | It is a Makefile application and can be built using the 120 | `Yocto rpmsg-mat-mul recipe `_. 121 | 122 | An example main control script is given in the 123 | `matrix multiply readme `_. 124 | 125 | ******************************* 126 | Reference Board Implementations 127 | ******************************* 128 | 129 | This Matrix Multiply Sample is demonstrated in the following reference implementations. 130 | 131 | * :ref:`Docker Images` as demo1B 132 | * :ref:`AMD-Xilinx platforms` 133 | * :ref:`Inter Process Demos` 134 | -------------------------------------------------------------------------------- /_doxygen/openamp/layout.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 | 66 | 67 | 68 | 69 | 70 | 71 | 72 | 73 | 74 | 75 | 76 | 77 | 78 | 79 | 80 | 81 | 82 | 83 | 84 | 85 | 86 | 87 | 88 | 89 | 90 | 91 | 92 | 93 | 94 | 95 | 96 | 97 | 98 | 99 | 100 | 101 | 102 | 103 | 104 | 105 | 106 | 107 | 108 | 109 | 110 | 111 | 112 | 113 | 114 | 115 | 116 | 117 | 118 | 119 | 120 | 121 | 122 | 123 | 124 | 125 | 126 | 127 | 128 | 129 | 130 | 131 | 132 | 133 | 134 | 135 | 136 | 137 | 138 | 139 | 140 | 141 | 142 | 143 | 144 | 145 | 146 | 147 | 148 | 149 | 150 | 151 | 152 | 153 | 154 | 155 | 156 | 157 | 158 | 159 | 160 | 161 | 162 | 163 | 164 | 165 | 166 | 167 | 168 | 169 | 170 | 171 | 172 | 173 | 174 | 175 | 176 | 177 | 178 | 179 | 180 | 181 | 182 | 183 | 184 | 185 | 186 | 187 | 188 | 189 | 190 | 191 | 192 | 193 | 194 | 195 | 196 | 197 | 198 | 199 | 200 | 201 | 202 | 203 | 204 | 205 | 206 | 207 | 208 | 209 | 210 | 211 | 212 | 213 | 214 | 215 | 216 | 217 | 218 | 219 | 220 | 221 | 222 | 223 | 224 | 225 | 226 | 227 | 228 | -------------------------------------------------------------------------------- /protocol_details/rpmsg_protocol.rst: -------------------------------------------------------------------------------- 1 | .. _rpmsg-protocol-work-label: 2 | 3 | ===================== 4 | RPMsg Protocol Layers 5 | ===================== 6 | 7 | The whole communication implementation can be separated in three different ISO/OSI layers 8 | 9 | - Transport, 10 | - Media Access Control, 11 | - Physical layer. 12 | 13 | Each of them can be implemented separately and for example multiple implementations of the 14 | Transport Layer can share the same implementation of the MAC Layer (VirtIO) and the Physical Layer. 15 | Each layer is described in the following sections. 16 | 17 | .. image:: ../images/protocol_layers.jpg 18 | 19 | Physical Layer – Shared Memory 20 | ------------------------------ 21 | 22 | The solution proposed in this document requires only two basic hardware components 23 | 24 | - shared memory (accessible by both communicating sides) 25 | - inter-core interrupts (optional in a specific configuration). The minimum configuration requires 26 | one interrupt line per communicating core meaning two interrupts in total. 27 | 28 | This configuration is briefly presented in the figure at the beginning of this section. It is to be 29 | noticed that no inter-core synchronization hardware element such as inter-core semaphore, inter-core 30 | queue or inter-core mutex is needed! This is thanks to the nature of the 31 | `virtqueue `_, 32 | which uses single-writer-single-reader circular buffering. (As defined in the next subsection). 33 | 34 | 35 | The use of interrupts by the ring buffers is optional and can be suppressed using a bit set in their 36 | configuration flags field - in such a configuration, the interrupts are not necessary. However both 37 | cores need to poll these ring buffers for new incoming messages, which may not be optimal. 38 | 39 | .. image:: ../images/core_to_core_interrupt.jpg 40 | 41 | 42 | .. _rpmsg-protocol-mac: 43 | 44 | Media Access Layer - VirtIO 45 | --------------------------- 46 | 47 | This layer is the key part of the whole solution - thanks to this layer, there is no need for 48 | inter-core synchronization. This is achieved by a technique called single-writer single-reader 49 | circular buffering, which is a data structure enabling multiple asynchronous contexts to 50 | interchange data. 51 | 52 | .. _rpmsg-protocol-figure-vring: 53 | 54 | .. image:: ../images/vrings.jpg 55 | 56 | This technique is however applicable only in core-to-core configuration, not in core-to-multicore 57 | configuration, since in such a case, there would be multiple writers to the “IN” ring buffer. 58 | This would require a synchronization element, [such as a semaphore?], which is not desirable. 59 | 60 | The above shown picture describes the vring component. The Vring is composed of three elementary 61 | parts - buffer descriptor pool, the available ring buffer and the used ring buffer. All three 62 | elements are physically stored in the shared memory. 63 | 64 | Each buffer descriptor contains a 64-bit buffer address, which holds an address to a buffer stored 65 | in the shared memory (as seen physically by the “receiver” or host of this vring), its length as a 66 | 32-bit variable, 16-bit flags field and 16-bit link to the next buffer descriptor. The link is used 67 | to chain unused buffer descriptors and to chain descriptors, which have the F_NEXT bit set in the 68 | flags field to the next descriptor in the chain. 69 | 70 | Note that the available and used ring buffer areas contain pointers to buffers, rather than the 71 | buffers themselves. Later versions of the 72 | `Virtio virtqueue `_ 73 | have changed the naming of these three sections to Descriptor Table, Driver Area and Device Area. 74 | 75 | .. image:: ../images/vring_descriptor.jpg 76 | 77 | The available ring buffer contains its own flags field, where only the 0th bit is used - if it is 78 | set, the “writer” side should not be notified, when the “reader” side consumes a buffer from the 79 | available ring buffer. By default the bit is not set, so after the reader consumes a buffer, the 80 | writer should be notified by triggering an interrupt. The next field of the available ring buffer 81 | is the index of the head, which is updated by the writer, after a buffer index containing a new 82 | message is written in the ring[x] field. 83 | 84 | .. figure:: ../images/vring_descriptor_flags.jpg 85 | 86 | Flags (16 bit) Fields of Available Ring Buffer Descriptor 87 | 88 | The last part of the vring is the used ring buffer. It contains also a flags field and only the 0th 89 | bit is used - if set, the writer side will not be notified when the reader updates the head index of 90 | this used ring buffer. The following picture shows the ring buffer structure. The used ring buffer 91 | differs from the available ring buffer. For each entry, the length of the buffer is stored as well. 92 | 93 | .. image:: ../images/vrings_used_buffers.jpg 94 | 95 | Both used and available ring buffers have a flags field. Its purpose is mainly to tell the writer 96 | whether he should interrupt the other core when updating the head of the ring. The same bit is used 97 | for this purpose in both used and available ring buffers: 98 | 99 | .. image:: ../images/vrings_used_buffers_flags.jpg 100 | 101 | Transport Layer - RPMsg 102 | ----------------------- 103 | RPMsg Header Definition 104 | ~~~~~~~~~~~~~~~~~~~~~~~ 105 | 106 | Each RPMsg message is contained in a buffer, which is present in the shared memory. This buffer is 107 | pointed to by the address field of a buffer descriptor from the vring’s buffer descriptor pool. The 108 | first 16 bytes of this buffer are used internally by the transport layer (RPMsg layer). The first 109 | word (32bits) is used as an address of the sender or source endpoint, the next word is the address 110 | of the receiver or destination endpoint. There is a reserved field for alignment reasons (RPMsg 111 | header is thus 16 bytes aligned). The last two fields of the header are the length of the payload 112 | (16bit) and a 16-bit flags field. The reserved field is not used to transmit data between cores and 113 | can be used internally in the RPMsg implementation. The user payload follows the RPMsg header. 114 | 115 | .. image:: ../images/rpmsg_header.jpg 116 | 117 | Special consideration should be taken if an alignment greater than 16 bytes is required; however, 118 | this is not typical for a shared memory, which should be fast and is therefore often not cached 119 | (alignment greater than 8 bytes is not needed at all). 120 | 121 | Flags Field 122 | ~~~~~~~~~~~ 123 | 124 | The flags field of the RPMsg header is currently unused by RPMsg and is reserved. Any propositions 125 | for what this field could be used for are welcome. It could be released for application use, but 126 | this can be considered as inconsistent - RPMsg header would not be aligned and the reserved field 127 | would be therefore useless. 128 | 129 | .. image:: ../images/rpmsg_flags.jpg 130 | 131 | RPMsg Channel 132 | ~~~~~~~~~~~~~ 133 | 134 | Every remote core in the RPMsg component is represented by an RPMsg device that provides a 135 | communication channel between the host and the remote, hence RPMsg devices are also known as 136 | channels. The RPMsg channel is identified by the textual name and local (source) and destination 137 | address. The RPMsg framework keeps track of channels using their names. 138 | 139 | .. _rpmsg-endpoint: 140 | 141 | RPMsg Endpoint 142 | ~~~~~~~~~~~~~~ 143 | 144 | RPMsg endpoints provide logical connections on top of an RPMsg channel. They allow the user to bind 145 | multiple rx callbacks on the same channel. 146 | 147 | Every RPMsg endpoint has a unique src address and associated call back function. When an application 148 | creates an endpoint with the local address, all further inbound messages with the destination 149 | address equal to the local address of endpoint are routed to that callback function. Every channel 150 | has a default endpoint which enables applications to communicate without even creating new endpoints. 151 | 152 | .. image:: ../images/rpmsg_endpoint.jpg 153 | 154 | ************************** 155 | RPMsg Protocol Limitations 156 | ************************** 157 | 158 | The RPMSG document has the concept of the static channel but it is not implemented in upstream 159 | Linux and OpenAMP. Please see https://www.kernel.org/doc/Documentation/rpmsg.txt. The protocol 160 | must define the connection sequence when the channel is created statically. 161 | No synchronization point is defined by the RPMsg framework after which both sides can 162 | communicate reliably with each other. In the current protocol, at startup, the host sends a 163 | notification to the remote to let it know that it can receive name service announcements. 164 | However, the host does not consider whether the remote is ready to handle notification at this 165 | point in time. 166 | -------------------------------------------------------------------------------- /demos/rpmsg_multi_services.rst: -------------------------------------------------------------------------------- 1 | 2 | ================================= 3 | OpenAMP RPMsg Multi Services Demo 4 | ================================= 5 | 6 | .. _rpmsg-multi-services-intro: 7 | 8 | ************************** 9 | RPMsg Multi Services Intro 10 | ************************** 11 | 12 | The RPMsg Multi Services reference sample demonstrates OpenAMP 13 | :ref:`Interprocessor Communications (IPC)` components by providing multiple services 14 | on a single remote. 15 | 16 | Three channel types are demonstrated. 17 | 18 | * Direct RPMsg Channel 19 | * Raw `character device `_ Channel 20 | * `tty Device `_ Channel 21 | 22 | The main controller side is implemented in Linux as client drivers to the remote services. The 23 | Direct RPMsg driver is a dedicated demo driver and the character and tty RPMsg drivers are generic 24 | character drivers that can be used by any user space application through their respective device 25 | files. 26 | 27 | .. image:: ../images/demos/rpmsg-multi-services-intro.svg 28 | 29 | 30 | The remote sets up three RPMsg channels, one for each service, starting at address 31 | RPMSG_RESERVED_ADDRESSES, which is 0x400 (1024). These channels are multiplexed on a single Virtio 32 | device. 33 | 34 | .. _rpmsg-multi-services-components: 35 | 36 | ******************************* 37 | RPMsg Multi Services Components 38 | ******************************* 39 | 40 | The three :ref:`Interprocessor Communications (IPC)` paths in this demonstration 41 | provide an identical application flow, namely a main controller based client sending packets via 42 | RPMsg to the remote which echoes the packet. 43 | 44 | The main target of the demonstration is to show the different RPMsg types as supported by Linux 45 | drivers, namely 'direct', 'character' and 'tty' driver. 46 | 47 | The underlying OpenAMP architectural components used by these applications are 48 | 49 | * :ref:`Remoteproc` 50 | * :ref:`Resource Table` 51 | * :ref:`RPMsg` 52 | * :ref:`Virtio` 53 | * :ref:`Libmetal` 54 | 55 | The supporting Linux architectural components used by the drivers on the main controller side are 56 | 57 | * `RPMsg character device `_ 58 | * `tty device `_ 59 | 60 | The following architecture diagram shows the components involved in the demonstration. 61 | 62 | .. image:: ../images/demos/rpmsg-multi-services-components.svg 63 | 64 | .. _rpmsg-control-flow-label: 65 | 66 | The top-level control flow is shown in the following message diagram. The control flow for each 67 | service is exemplified in the three boxes labeled A, B and C for the drivers direct, tty and 68 | character/raw. 69 | The remote threads are shown sequentially for clarity of diagram but could be executed in parallel. 70 | 71 | 72 | .. image:: ../images/demos/rpmsg-multi-services-control-flow.svg 73 | 74 | 75 | .. _rpmsg-client-sample-label: 76 | 77 | RPMsg Client Sample 78 | =================== 79 | 80 | The Linux rpmsg_client_sample driver begins sending 'hello world!' messages on a rpmsg_driver probe, 81 | initiated by a name service announcement from the remote. This is repeated a predefined count times 82 | for each response from the remote. The response from the remote application is to return the same 83 | packet received at the :ref:`RPMsg endpoint ` of the main controller. 84 | 85 | When the count (100) responses have been sent, the endpoint is destroyed by the remote. 86 | 87 | Refer to box A (direct) in :ref:`flow control diagram`. 88 | 89 | .. _rpmsg-character-driver-sample-label: 90 | 91 | Character Driver Samples 92 | ======================== 93 | 94 | The Linux character and tty driver are demonstrated by sending messages to the rpmsg_char and 95 | rpmsg_tty driver respectively by a user space command writing to the respective /dev/rpmsg? and 96 | /dev/ttyRPMSG? device files. The response is output by using the Linux cat command. 97 | 98 | Writing data to the zeroth index /dev/rpmsg0 and /dev/ttyRPMSG0 files will result in an RPMsg being 99 | sent to the channel's address, which start at 0x400 (1024) and are allocated by the remote 100 | sequentially on channel creation. 101 | 102 | Writing data to indexed driver files will result in an RPMsg being sent the Linux endpoint address, 103 | which has a corresponding address on the remote side in either a one to one or many to one 104 | relationship as detailed in the following sections. 105 | 106 | .. _rpmsg-raw-driver-label: 107 | 108 | Raw Character Driver Sample 109 | --------------------------- 110 | 111 | When started, the character/raw remote service (app_rpmsg_raw thread) creates two RPMsg endpoints. 112 | The first with the special RPMSG_ADDR_ANY (-1) address which sets up the RPMsg channel and the 113 | second with destination and source address set to 1. 114 | 115 | In addition to demonstrating the use of the raw character driver, this application demonstrates the 116 | use of an arbitrary number of Linux side RPMsg endpoints, all connected to a single endpoint on the 117 | remote side (with address 1). The Linux side end points are created using the 118 | `rpmsg-utils rpmsg_export_ept utility `_, 119 | and establish a many to one connectivity between main controller and remote endpoints. 120 | 121 | Although there are many endpoints on the Linux side, the remote has only two endpoints. 122 | 123 | Refer to box C (char) in :ref:`flow control diagram`. 124 | 125 | .. _rpmsg-tty-driver-label: 126 | 127 | Tty Driver Sample 128 | ----------------- 129 | 130 | When started, the tty remote service (app_rpmsg_tty thread) initially creates only a single RPMsg 131 | channel by creating the special RPMSG_ADDR_ANY (-1) end point. 132 | 133 | The management thread (rpmsg_mng_task) also sets up a 'New Service Callback' (new_service_cb) which 134 | monitors for new 'rpmsg-tty' requests. On receipt of such a request the application creates a new 135 | 136 | This application demonstrates the creation and release of RPMsg channels using the 137 | `rpmsg-utils rpmsg_export_dev utility `_, 138 | which exercise the ioctl commands RPMSG_CREATE_DEV_IOCTL and RPMSG_RELEASE_DEV_IOCTL. 139 | 140 | Refer to box B (tty) in :ref:`flow control diagram`. 141 | 142 | ******************************** 143 | RPMsg Multi Services Demo Source 144 | ******************************** 145 | 146 | 147 | RPMsg Multi Services Remote Source 148 | ================================== 149 | 150 | The RPMSg implementation need not be on an RTOS (Real Time Operation System) but as there are 151 | multiple services being exposed, an RTOS is suitable as tasks or threads can be used for each service. 152 | If bare metal implementation is required, a round robin scheme could be used instead. 153 | 154 | The current implementation is for the `Zephyr RTOS `_. 155 | 156 | RPMsg Multi Services Zephyr Source 157 | ---------------------------------- 158 | 159 | The remote services are implemented as a single application, 160 | `main_remote.c `_, 161 | to run on the remote, with each service being a thread. 162 | 163 | There are four threads. Three threads, one for each of the services ... 164 | 165 | * app_rpmsg_client_sample 166 | * app_rpmsg_tty 167 | * app_rpmsg_raw 168 | 169 | ... and a main thread which starts the three service threads and monitors for requests for new end 170 | points on the "rpmsg-tty" channel. 171 | 172 | * rpmsg_mng_task 173 | 174 | RPMsg Multi Services Linux Source 175 | ================================= 176 | 177 | The direct RPMsg client is a 178 | `dedicated Linux sample driver `_ 179 | specifically for demonstrations. 180 | 181 | The raw character 'client' is The 182 | `RPMsg character driver `_ 183 | provided in the Linux source, and becomes available on a name service announcement from the remote 184 | whence the driver module is loaded and available at the /dev/rpmsg? device file. To exercise the 185 | demonstration, characters can be sent to the device file using the 186 | `rpmsg-utils/rpmsg_ping `_ 187 | command. The RPMsg device id name is "rpmsg-raw". 188 | 189 | The tty 'client' is the `PRMsg tty driver `_ 190 | provided in the Linux source, and becomes available on a name service announcement from the remote 191 | whence the driver module is loaded and available at the /dev/ttyRPMSG? device file. To exercise the 192 | demonstration, characters can be sent to the device file using the echo or cat Linux command. 193 | 194 | The RPMsg ioctl (IO control) is performed through 195 | `rpmsg_ctrl `_ provided in 196 | the Linux source and is used by the 197 | `rpmsg-utils rpmsg_export_dev utility `_, 198 | which exercise the ioctl commands RPMSG_CREATE_DEV_IOCTL and RPMSG_RELEASE_DEV_IOCTL. 199 | 200 | 201 | ******************************* 202 | Reference Board Implementations 203 | ******************************* 204 | 205 | This RPMsg Multi Services Sample is demonstrated in the following reference implementations. 206 | 207 | * :ref:`ST Micro Platforms` 208 | 209 | * Refer to `Zephyr Build Instructions `_. 210 | * Refer to `example demo script `_. 211 | 212 | * :ref:`NXP ` 213 | 214 | * Refer to Application Note `AN13970 Running Zephyr RTOS `_ 215 | 216 | * :ref:`Texas Instruments ` 217 | 218 | * Refer to `Zephyr Build Instructions `_. 219 | -------------------------------------------------------------------------------- /demos/system_reference-ST.rst: -------------------------------------------------------------------------------- 1 | .. _demos-ST-work-label: 2 | 3 | ============================================================= 4 | System Reference Samples and Demos on STM32MP157C/F-DK2 board 5 | ============================================================= 6 | 7 | Based on a fork of the yocto [meta-st-stm32mp-oss] 8 | (https://github.com/STMicroelectronics/meta-st-stm32mp-oss) environment,designed to update and test 9 | upstream code on STM32MP boards, 10 | 11 | Prerequisite 12 | ------------ 13 | 14 | Some specifics package could be needed to build the ST images. For details refer to 15 | 16 | `STMPU wiki PC prerequisite `_ 17 | 18 | Installation 19 | ------------ 20 | 21 | Create the structure of the project 22 | 23 | .. code-block:: console 24 | 25 | mkdir stm32mp15-demo 26 | cd stm32mp15-demo 27 | mkdir stm32mp1_distrib_oss 28 | mkdir zephy_rpmsg_multi_services 29 | 30 | At this step you should see following folder hierarchy: 31 | 32 | .. code-block:: console 33 | 34 | stm32mp15-demo 35 | |___ stm32mp1_distrib_oss 36 | |___ zephy_rpmsg_multi_services 37 | 38 | Generate the stm32mp15 image 39 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 40 | 41 | Install stm32mp1_distrib_oss Nanbield 42 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 43 | 44 | From the stm32mp15-demo directory 45 | 46 | .. code-block:: console 47 | 48 | export YOCTO_VER=scarthgap 49 | cd stm32mp1_distrib_oss 50 | mkdir -p layers/meta-st 51 | 52 | git clone https://git.yoctoproject.org/git/poky layers/poky 53 | cd layers/poky 54 | git checkout -b WORKING origin/$YOCTO_VER 55 | cd - 56 | 57 | git clone https://github.com/openembedded/meta-openembedded.git layers/meta-openembedded 58 | cd layers/meta-openembedded 59 | git checkout -b WORKING origin/$YOCTO_VER 60 | cd - 61 | 62 | git clone https://github.com/STMicroelectronics/meta-st-stm32mp-oss.git layers/meta-st/meta-st-stm32mp-oss 63 | cd layers/meta-st/meta-st-stm32mp-oss 64 | git checkout -b WORKING origin/$YOCTO_VER 65 | cd - 66 | 67 | Initialize the Open Embedded build environment 68 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 69 | 70 | The OpenEmbedded environment setup script must be run once in each new working terminal in which you 71 | use the BitBake or devtool tools (see later) from stm32mp15-demo/stm32mp1_distrib_oss directory 72 | 73 | .. code-block:: console 74 | 75 | source ./layers/poky/oe-init-build-env build-stm32mp15-disco-oss 76 | 77 | bitbake-layers add-layer ../layers/meta-openembedded/meta-oe 78 | bitbake-layers add-layer ../layers/meta-openembedded/meta-perl 79 | bitbake-layers add-layer ../layers/meta-openembedded/meta-python 80 | bitbake-layers add-layer ../layers/meta-st/meta-st-stm32mp-oss 81 | 82 | echo "MACHINE = \"stm32mp15-disco-oss\"" >> conf/local.conf 83 | echo "DISTRO = \"nodistro\"" >> conf/local.conf 84 | echo "PACKAGE_CLASSES = \"package_deb\" " >> conf/local.conf 85 | 86 | Build stm32mp1_distrib_oss image 87 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 88 | 89 | From stm32mp15-demo/stm32mp1_distrib_oss/build-stm32mp15-disco-oss/ directory 90 | 91 | .. code-block:: console 92 | 93 | bitbake core-image-base 94 | 95 | Note that 96 | 97 | - to build around 30 GB is needed 98 | - building the distribution can take more than 2 hours depending on performance of the PC. 99 | 100 | Install stm32mp1_distrib_oss 101 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 102 | 103 | From 'stm32mp15-demo/stm32mp1_distrib_oss/build-stm32mp15-disco-oss/' directory,populate your 104 | microSD card inserted on your HOST PC using command 105 | 106 | .. code-block:: console 107 | 108 | cd tmp-glibc/deploy/images/stm32mp15-disco-oss/ 109 | # Unmount potential media mounted from the sdcard. Replace by mmcblk (X = 0,1..) or 110 | #sd( Y = b,c,d,..) depending on the connection 111 | sudo eject /dev/ 112 | # Flash wic image on your sdcard. Replace by mmcblk (X = 0,1..) or 113 | #sd( Y = b,c,d,..) depending on the connection 114 | sudo dd if=core-image-base-stm32mp15-disco-oss.rootfs.wic of=/dev/ bs=8M conv=fdatasync status=progress 115 | 116 | 117 | Generate the Zephyr rpmsg multi service example 118 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 119 | 120 | Initialize the Zephyr environment 121 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 122 | 123 | Refer to 124 | :ref:`zephyr example readme` article. 125 | 126 | Build the Zephyr image 127 | ^^^^^^^^^^^^^^^^^^^^^^ 128 | 129 | From the zephy_rpmsg_multi_services directory 130 | 131 | .. code-block:: console 132 | 133 | west build -b stm32mp157c_dk2 openamp-system-reference/examples/zephyr/rpmsg_multi_services 134 | 135 | For details refer to 136 | :ref:`rpmsg_multi_services readme` article. 137 | 138 | 139 | Install the Zephyr binary on the sdcard 140 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 141 | 142 | The Zephyr sample binary is available in the sub-folder of build directory 143 | stm32mp15-demo/zephy_rpmsg_multi_services/build/zephyr/rpmsg_multi_services.elf. 144 | It needs to be installed on the "rootfs" partition of the sdcard 145 | 146 | .. code-block:: console 147 | 148 | sudo cp build/zephyr/rpmsg_multi_services.elf /rootfs/lib/firmware/ 149 | 150 | Don't forget to properly unmoumt the sdcard partitions. 151 | 152 | .. code-block:: console 153 | 154 | sudo eject /dev/ 155 | 156 | Build and install the rpmsg-utils tools 157 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 158 | This chapter explains how to build and install the 159 | `rpmsg-utils `_ 160 | for the STM32MP157C/F-DK2 board. 161 | 162 | 163 | 164 | Download XXXX-none-linux-gnu AArch32 GNU/Linux target cross toolchains from: 165 | `arm developer page `_. 166 | 167 | Build the rpmsg-utils binaries: 168 | 169 | .. code-block:: console 170 | 171 | # has to be updated by the path of the arm toolchain. 172 | export CC="/bin/arm-none-linux-gnueabihf-gcc -mthumb -mfpu=neon-vfpv4 -mfloat-abi=hard -mcpu=cortex-a7" 173 | make 174 | 175 | Install the tools on the sdcard 176 | .. code-block:: console 177 | 178 | sudo cp rpmsg_destroy_ept rpmsg_export_dev rpmsg_export_ept rpmsg_ping /rootfs/usr/bin/ 179 | 180 | Don't forget to properly unmoumt the sdcard partitions. 181 | 182 | .. code-block:: console 183 | 184 | sudo eject /dev/ 185 | 186 | 187 | Demos 188 | ----- 189 | 190 | Start the demo environment 191 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ 192 | 193 | - Power on the 194 | `stm32mp157C/F-dk2 board `_, 195 | and wait login prompt on your serial terminal 196 | 197 | .. code-block:: console 198 | 199 | stm32mp15-disco-oss login: root 200 | 201 | 202 | There are 2 ways to start the coprocessor: 203 | 204 | * During the runtime, by the Linux remoteproc framework 205 | 206 | .. code-block:: console 207 | 208 | root@stm32mp15-disco-oss:~# cat /sys/class/remoteproc/remoteproc0/state 209 | offline 210 | root@stm32mp15-disco-oss:~# echo rpmsg_multi_services.elf > /sys/class/remoteproc/remoteproc0/firmware 211 | root@stm32mp15-disco-oss:~# echo start >/sys/class/remoteproc/remoteproc0/state 212 | root@stm32mp15-disco-oss:~# cat /sys/class/remoteproc/remoteproc0/state 213 | running 214 | 215 | * In the boot stages, by the U-Boot remoteproc framework 216 | 217 | - Prerequisite 218 | Copy the firmware in the bootfs partition 219 | 220 | .. code-block:: console 221 | 222 | root@stm32mp15-disco-oss:~# cp /lib/firmware/rpmsg_multi_services.elf /boot/ 223 | root@stm32mp15-disco-oss:~# sync 224 | 225 | - Boot the board and go in U-Boot console 226 | 227 | .. code-block:: console 228 | 229 | root@stm32mp15-disco-oss:~# reboot 230 | 231 | Enter in the U-boot console by interrupting the boot with any keyboard key. 232 | 233 | .. code-block:: console 234 | 235 | STM32MP> 236 | 237 | - Load and start the Coprocessor firmware: 238 | 239 | .. code-block:: console 240 | 241 | STM32MP> load mmc 0#bootfs ${kernel_addr_r} rpmsg_multi_services.elf 242 | 816776 bytes read in 148 ms (5.3 MiB/s) 243 | STM32MP> rproc init 244 | STM32MP> rproc load 0 ${kernel_addr_r} ${filesize} 245 | Load Remote Processor 0 with data@addr=0xc2000000 816776 bytes: Success! 246 | STM32MP> rproc start 0 247 | STM32MP> run bootcmd 248 | 249 | To automatically load the firmware by U-Boot, refer to the 250 | `STMicorelectronics wiki `_. 251 | 252 | 253 | - Check that the remoteproc state is "detached" 254 | 255 | .. code-block:: console 256 | 257 | root@stm32mp15-disco-oss:~# cat /sys/class/remoteproc/remoteproc0/state 258 | detached 259 | 260 | - Attach the Linux remoteproc framework to the Zephyr 261 | 262 | .. code-block:: console 263 | 264 | root@stm32mp15-disco-oss:~# echo start >/sys/class/remoteproc/remoteproc0/state 265 | root@stm32mp15-disco-oss:~# cat /sys/class/remoteproc/remoteproc0/state 266 | attached 267 | 268 | The communication with the coprocessor is not initialized, following traces on console 269 | are observed: 270 | 271 | .. code-block:: console 272 | 273 | root@stm32mp15-disco-oss:~# 274 | [ 54.495343] virtio_rpmsg_bus virtio0: rpmsg host is online 275 | [ 54.500044] virtio_rpmsg_bus virtio0: creating channel rpmsg-client-sample addr 0x400 276 | [ 54.507923] virtio_rpmsg_bus virtio0: creating channel rpmsg-tty addr 0x401 277 | [ 54.514795] virtio_rpmsg_bus virtio0: creating channel rpmsg-raw addr 0x402 278 | [ 54.548954] rpmsg_client_sample virtio0.rpmsg-client-sample.-1.1024: new channel: 0x402 -> 0x400! 279 | [ 54.557337] rpmsg_client_sample virtio0.rpmsg-client-sample.-1.1024: incoming msg 1 (src: 0x400) 280 | [ 54.565532] rpmsg_client_sample virtio0.rpmsg-client-sample.-1.1024: incoming msg 2 (src: 0x400) 281 | [ 54.581090] rpmsg_client_sample virtio0.rpmsg-client-sample.-1.1024: incoming msg 3 (src: 0x400) 282 | [ 54.588699] rpmsg_client_sample virtio0.rpmsg-client-sample.-1.1024: incoming msg 4 (src: 0x400) 283 | [ 54.599424] rpmsg_client_sample virtio0.rpmsg-client-sample.-1.1024: incoming msg 5 (src: 0x400) 284 | ... 285 | 286 | This informs that following rpmsg channels devices have been created: 287 | 288 | - a rpmsg-client-sample device 289 | - a rpmsg-tty device 290 | - a rpmsg-raw device 291 | 292 | 293 | Run the multi RPMsg services demo 294 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 295 | 296 | Refer to 297 | :ref:`rpmsg multi service ` article. 298 | -------------------------------------------------------------------------------- /docs/porting_guide.rst: -------------------------------------------------------------------------------- 1 | .. _porting-guide-work-label: 2 | 3 | ================= 4 | Porting GuideLine 5 | ================= 6 | 7 | The `OpenAMP Framework `_ uses 8 | `libmetal `_ to provide abstractions that allows for porting 9 | of the OpenAMP Framework to various software environments (operating systems and bare metal 10 | environments) and machines (processors/platforms). To port OpenAMP for your platform, you will 11 | need to: 12 | 13 | - add your system environment support to :ref:`libmetal`, 14 | - optionally implement a platform specific :ref:`remoteproc driver`. 15 | - define your shared memory layout and specify it in a :ref:`resource table`. 16 | 17 | .. _port-libmetal: 18 | 19 | ************************************** 20 | Add System/Machine Support in Libmetal 21 | ************************************** 22 | 23 | User will need to add system/machine support to 24 | `lib/system// `_ directory in 25 | libmetal repository. OpenAMP requires the following libmetal primitives: 26 | 27 | alloc 28 | ===== 29 | 30 | Memory allocation and memory free as defined in 31 | `alloc.h `_, which call the 32 | functions of equivalent names with double underscore which are the ported functions 33 | (__metal_allocate_memory, __metal_free_memory). 34 | 35 | .. doxygenfunction:: metal_allocate_memory 36 | :project: libmetal_doc_embed 37 | 38 | .. doxygenfunction:: metal_free_memory 39 | :project: libmetal_doc_embed 40 | 41 | 42 | io 43 | == 44 | 45 | Memory mapping as used by `io.h `_, 46 | in order to access vrings and carved out memory. 47 | 48 | :libmetal_doc_link:`metal_sys_io_mem_map ` and 49 | :libmetal_doc_link:`metal_machine_io_mem_map ` functions. 50 | 51 | mutex 52 | ===== 53 | 54 | Mutex functions as used by `mutex.h `_ 55 | which call the functions of equivalent names with double underscore which are the ported functions 56 | (e.g. __metal_mutex_init). 57 | 58 | .. doxygenfunction:: metal_mutex_init 59 | :project: libmetal_doc_embed 60 | 61 | .. doxygenfunction:: metal_mutex_deinit 62 | :project: libmetal_doc_embed 63 | 64 | .. doxygenfunction:: metal_mutex_try_acquire 65 | :project: libmetal_doc_embed 66 | 67 | .. doxygenfunction:: metal_mutex_acquire 68 | :project: libmetal_doc_embed 69 | 70 | .. doxygenfunction:: metal_mutex_release 71 | :project: libmetal_doc_embed 72 | 73 | .. doxygenfunction:: metal_mutex_is_acquired 74 | :project: libmetal_doc_embed 75 | 76 | sleep 77 | ===== 78 | 79 | At the moment, OpenAMP only requires microseconds sleep as when OpenAMP fails to get a buffer to 80 | send messages, it will call this function to sleep and then try again. 81 | 82 | The __metal_sleep_usec to be implemented by the port is wrapped in 83 | `sleep.h `_. 84 | 85 | .. doxygenfunction:: metal_sleep_usec 86 | :project: libmetal_doc_embed 87 | 88 | init 89 | ==== 90 | 91 | Init is ported for libmetal initialization for 92 | `sys.h `_. 93 | 94 | 95 | :libmetal_doc_link:`metal_sys_init ` and 96 | :libmetal_doc_link:`metal_sys_finish ` functions. 97 | 98 | 99 | Please refer to 100 | `lib/system/generic/ `_ 101 | when adding RTOS support to libmetal. 102 | 103 | libmetal uses C11/C++11 stdatomics interface for atomic operations, if you use a different 104 | compiler to GNU gcc, you may need to implement the atomic operations defined in 105 | `lib/compiler/gcc/atomic.h `_. 106 | 107 | 108 | .. _port-remoteproc-driver: 109 | 110 | *********************************** 111 | Platform Specific Remoteproc Driver 112 | *********************************** 113 | 114 | An OpenAMP port could need a platform specific remoteproc driver to use remoteproc 115 | life cycle management (LCM) APIs. The remoteproc driver platform specific functions are defined 116 | in `lib/include/openamp/remoteproc.h `_ and provided through the :openamp_doc_link:`remoteproc_ops data structure `. 117 | 118 | The remoteproc LCM APIs use these platform specific implementation of init, remove, mmap, 119 | handle_rsc, config, start, stop, shutdown and notify. These functions are passed to remoteproc 120 | via the remoteproc_ops structure which contains function pointers to each. 121 | 122 | .. doxygenstruct:: remoteproc_ops 123 | :members: 124 | 125 | The remoteproc_init API receives this structure, and its function pointers, which are then used 126 | by the other APIs. 127 | 128 | .. _port-remoteproc: 129 | 130 | ********************************************************************** 131 | Platform Specific Porting to Use Remoteproc to Manage Remote Processor 132 | ********************************************************************** 133 | 134 | With the platform specific :ref:`remoteproc driver functions` 135 | implemented by the port, the user can use remoteproc APIs to run application on a remote processor. 136 | 137 | .. doxygenfunction:: remoteproc_init 138 | :project: openamp_doc_embed 139 | 140 | .. doxygenfunction:: remoteproc_remove 141 | 142 | .. doxygenfunction:: remoteproc_mmap 143 | 144 | .. doxygenfunction:: remoteproc_config 145 | 146 | .. doxygenfunction:: remoteproc_start 147 | 148 | .. doxygenfunction:: remoteproc_stop 149 | 150 | .. doxygenfunction:: remoteproc_shutdown 151 | 152 | 153 | The following code snippet is an example execution. 154 | 155 | 156 | .. code-block:: c 157 | 158 | #include 159 | 160 | /* User defined remoteproc operations */ 161 | extern struct remoteproc_ops rproc_ops; 162 | 163 | /* User defined image store operations, such as open the image file, read 164 | * image from storage, and close the image file. 165 | */ 166 | 167 | extern struct image_store_ops img_store_ops; 168 | /* Pointer to keep the image store information. It will be passed to user 169 | * defined image store operations by the remoteproc loading application 170 | * function. Its structure is defined by user. 171 | */ 172 | void *img_store_info; 173 | 174 | struct remoteproc rproc; 175 | 176 | void main(void) 177 | { 178 | /* Instantiate the remoteproc instance */ 179 | remoteproc_init(&rproc, &rproc_ops, &private_data); 180 | 181 | /* Optional, required, if user needs to configure the remote before 182 | * loading applications. 183 | */ 184 | remoteproc_config(&rproc, &platform_config); 185 | 186 | /* Load Application. It only supports ELF for now. */ 187 | remoteproc_load(&rproc, img_path, img_store_info, &img_store_ops, NULL); 188 | 189 | /* Start the processor to run the application. */ 190 | remoteproc_start(&rproc); 191 | 192 | /* ... */ 193 | 194 | /* Optional. Stop the processor, but the processor is not powered 195 | * down. 196 | */ 197 | remoteproc_stop(&rproc); 198 | 199 | /* Shutdown the processor. The processor is supposed to be powered 200 | * down. 201 | */ 202 | remoteproc_shutdown(&rproc); 203 | 204 | /* Destroy the remoteproc instance */ 205 | remoteproc_remove(&rproc); 206 | } 207 | 208 | .. _port-rpmsg: 209 | 210 | ************************************** 211 | Platform Specific Porting to Use RPMsg 212 | ************************************** 213 | 214 | RPMsg in OpenAMP implementation uses `VirtIO `_ 215 | to manage the shared buffers. OpenAMP library provides 216 | `remoteproc VirtIO backend implementation `_. 217 | You don't have to use remoteproc backend. You can implement your VirtIO backend with the VirtIO 218 | and RPMsg implementation in OpenAMP. If you want to implement your own VirtIO backend, you can 219 | refer to the 220 | `remoteproc VirtIO backend implementation `_. 221 | 222 | Here are the steps to use OpenAMP for RPMsg communication: 223 | 224 | 225 | .. code-block:: c 226 | 227 | #include 228 | #include 229 | #include 230 | 231 | /* User defined remoteproc operations for communication */ 232 | sturct remoteproc rproc_ops = { 233 | .init = local_rproc_init; 234 | .mmap = local_rproc_mmap; 235 | .notify = local_rproc_notify; 236 | .remove = local_rproc_remove; 237 | }; 238 | 239 | /* Remoteproc instance. If you don't use Remoteproc VirtIO backend, 240 | * you don't need to define the remoteproc instance. 241 | */ 242 | struct remoteproc rproc; 243 | 244 | /* RPMsg VirtIO device instance. */ 245 | struct rpmsg_virtio_device rpmsg_vdev; 246 | 247 | /* RPMsg device */ 248 | struct rpmsg_device *rpmsg_dev; 249 | 250 | /* Resource Table. Resource table is used by remoteproc to describe 251 | * the shared resources such as vdev(VirtIO device) and other shared memory. 252 | * Resource table resources definition is in the remoteproc.h. 253 | * Examples of the resource table can be found in the OpenAMP repo: 254 | * - apps/machine/zynqmp/rsc_table.c 255 | * - apps/machine/zynqmp_r5/rsc_table.c 256 | * - apps/machine/zynq7/rsc_table.c 257 | */ 258 | void *rsc_table = &resource_table; 259 | 260 | /* Size of the resource table */ 261 | int rsc_size = sizeof(resource_table); 262 | 263 | /* Shared memory metal I/O region. It will be used by OpenAMP library 264 | * to access the memory. You can have more than one shared memory regions 265 | * in your application. 266 | */ 267 | struct metal_io_region *shm_io; 268 | 269 | /* VirtIO device */ 270 | struct virtio_device *vdev; 271 | 272 | /* RPMsg shared buffers pool */ 273 | struct rpmsg_virtio_shm_pool shpool; 274 | 275 | /* Shared buffers */ 276 | void *shbuf; 277 | 278 | /* RPMsg endpoint */ 279 | struct rpmsg_endpoint ept; 280 | 281 | /* User defined RPMsg name service callback. This callback is called 282 | * when there is no registered RPMsg endpoint is found for this name 283 | * service. User can create RPMsg endpoint in this callback. */ 284 | void ns_bind_cb(struct rpmsg_device *rdev, const char *name, uint32_t dest); 285 | 286 | /* User defined RPMsg endpoint received message callback */ 287 | void rpmsg_ept_cb(struct rpmsg_endpoint *ept, void *data, size_t len, 288 | uint32_t src, void *priv); 289 | 290 | /* User defined RPMsg name service unbind request callback */ 291 | void ns_unbind_cb(struct rpmsg_device *rdev, const char *name, uint32_t dest); 292 | 293 | void main(void) 294 | { 295 | /* Instantiate remoteproc instance */ 296 | remoteproc_init(&rproc, &rproc_ops); 297 | 298 | /* Mmap shared memories so that they can be used */ 299 | remoteproc_mmap(&rproc, &physical_address, NULL, size, 300 | , &shm_io); 301 | 302 | /* Parse resource table to remoteproc */ 303 | remoteproc_set_rsc_table(&rproc, rsc_table, rsc_size); 304 | 305 | /* Create VirtIO device from remoteproc. 306 | * VirtIO device main controller will initiate the VirtIO rings, and assign 307 | * shared buffers. If you running the application as VirtIO device, you 308 | * set the role as VIRTIO_DEV_DEVICE. 309 | * If you don't use remoteproc, you will need to define your own VirtIO 310 | * device. 311 | */ 312 | vdev = remoteproc_create_virtio(&rproc, 0, VIRTIO_DEV_DRIVER, NULL); 313 | 314 | /* This step is only required if you are VirtIO device main controller. 315 | * Initialize the shared buffers pool. 316 | */ 317 | shbuf = metal_io_phys_to_virt(shm_io, SHARED_BUF_PA); 318 | rpmsg_virtio_init_shm_pool(&shpool, shbuf, SHARED_BUFF_SIZE); 319 | 320 | /* Initialize RPMsg VirtIO device with the VirtIO device */ 321 | /* If it is VirtIO device, it will not return until the main 322 | * controller side sets the VirtIO device DRIVER OK status bit. 323 | */ 324 | rpmsg_init_vdev(&rpmsg_vdev, vdev, ns_bind_cb, io, shm_io, &shpool); 325 | 326 | /* Get RPMsg device from RPMsg VirtIO device */ 327 | rpmsg_dev = rpmsg_virtio_get_rpmsg_device(&rpmsg_vdev); 328 | 329 | /* Create RPMsg endpoint. */ 330 | rpmsg_create_ept(&ept, rdev, RPMSG_SERVICE_NAME, RPMSG_ADDR_ANY, 331 | rpmsg_ept_cb, ns_unbind_cb); 332 | 333 | /* If it is VirtIO device main controller, it sends the first message */ 334 | while (!is_rpmsg_ept_read(&ept)) { 335 | /* check if the endpoint has binded. 336 | * If not, wait for notification. If local endpoint hasn't 337 | * been bound with the remote endpoint, it will fail to 338 | * send the message to the remote. 339 | */ 340 | /* If you prefer to use interrupt, you can wait for 341 | * interrupt here, and call the VirtIO notified function 342 | * in the interrupt handling task. 343 | */ 344 | rproc_virtio_notified(vdev, RSC_NOTIFY_ID_ANY); 345 | } 346 | /* Send RPMsg */ 347 | rpmsg_send(&ept, data, size); 348 | 349 | do { 350 | /* If you prefer to use interrupt, you can wait for 351 | * interrupt here, and call the VirtIO notified function 352 | * in the interrupt handling task. 353 | * If vdev is notified, the endpoint callback will be 354 | * called. 355 | */ 356 | rproc_virtio_notified(vdev, RSC_NOTIFY_ID_ANY); 357 | } while(!ns_unbind_cb_is_called && !user_decided_to_end_communication); 358 | 359 | /* End of communication, destroy the endpoint */ 360 | rpmsg_destroy_ept(&ept); 361 | 362 | rpmsg_deinit_vdev(&rpmsg_vdev); 363 | 364 | remoteproc_remove_virtio(&rproc, vdev); 365 | 366 | remoteproc_remove(&rproc); 367 | } 368 | 369 | . --------------------------------------------------------------------------------