diff --git a/demos/inter_process.rst b/demos/inter_process.rst index f85389f..7b98da8 100644 --- a/demos/inter_process.rst +++ b/demos/inter_process.rst @@ -4,7 +4,7 @@ Running Demos as Processes on Linux =================================== -The `OpenAMP project examples <https://github.com/OpenAMP/open-amp/tree/main/apps/examples>`_ +The `OpenAMP project examples <https://github.com/OpenAMP/openamp-system-reference/tree/main/examples>`_ are intended to execute on the remote of a reference board but can also be demonstrated by implementing as a process on the main controller, effectively emulating a remote. This can be useful for demonstration purposes, but can also be leveraged for component testing, even as part of a continuous integration setup. diff --git a/demos/reference_boards.rst b/demos/reference_boards.rst index 89e5b3b..d233413 100644 --- a/demos/reference_boards.rst +++ b/demos/reference_boards.rst @@ -12,4 +12,5 @@ In general the OpenAMP feature being exemplified is found in the `OpenAMP source docker_images system_reference-AMD-Xilinx system_reference-ST + system_reference-NXP inter_process diff --git a/demos/rpmsg_multi_services.rst b/demos/rpmsg_multi_services.rst index 9b5b7ed..77bdd08 100644 --- a/demos/rpmsg_multi_services.rst +++ b/demos/rpmsg_multi_services.rst @@ -157,3 +157,7 @@ This RPMsg Multi Services Sample is demonstrated in the following reference impl * Refer to `Zephyr Build Instructions <https://github.com/OpenAMP/openamp-system-reference/tree/main/examples/zephyr/rpmsg_multi_services>`_. * Refer to `example demo script <https://github.com/OpenAMP/openamp-demo/blob/main/demos/demo-stm32mp157c-dk2/my-extra-stuff/home/root/demo1>`_. + +* :ref:`NXP <reference_board_NXP>` + + * Refer to Application Note `AN13970 Running Zephyr RTOS <https://www.nxp.com/docs/en/application-note/AN13970.pdf>`_ diff --git a/demos/system_reference-NXP.rst b/demos/system_reference-NXP.rst new file mode 100644 index 0000000..c247f1a --- /dev/null +++ b/demos/system_reference-NXP.rst @@ -0,0 +1,13 @@ + + +.. _reference_board_NXP: + +==================== +NXP Reference Boards +==================== + +A number of the `OpenAMP project examples <https://github.com/OpenAMP/openamp-system-reference/tree/main/examples>`_ can be executed on NXP Reference boards. + +* NXP `8MPLUSLPD4-EVK <https://www.nxp.com/design/design-center/development-boards-and-designs/8MPLUSLPD4-EVK>`_. + +The `AN13970 Running Zephyr RTOS on Cadence Tensilica HiFi 4 DSP <https://www.nxp.com/docs/en/application-note/AN13970.pdf>`_ application note provides instructions for setting up the evaluation board. diff --git a/index.rst b/index.rst index 8d850f1..b41a399 100644 --- a/index.rst +++ b/index.rst @@ -16,6 +16,7 @@ Welcome to the OpenAMP Project Documentation tools/index protocol_details/index docs/index + openamp/glossary Indices and tables ================== diff --git a/openamp/contributing.rst b/openamp/contributing.rst index dacbf44..6abd571 100644 --- a/openamp/contributing.rst +++ b/openamp/contributing.rst @@ -4,6 +4,8 @@ Contributing to the OpenAMP Project =================================== +If you want to contribute and port OpenAMP to your platform read more about OpenAMP porting :ref:`here<porting-guide-work-label>`. + Release Cycle ------------- - Release branch (feature freeze) cut 1 month before release target diff --git a/openamp/glossary.rst b/openamp/glossary.rst new file mode 100644 index 0000000..892d092 --- /dev/null +++ b/openamp/glossary.rst @@ -0,0 +1,22 @@ +======== +Glossary +======== + +.. csv-table:: Glossary + :header: "Acronym", "Description" + :widths: 20, 200 + + AMP, `Asymmentric Multiprocessing <https://en.wikipedia.org/wiki/Asymmetric_multiprocessing>`_ + API, Application Interface + GPL, `GNU General Public License <https://en.wikipedia.org/wiki/GNU_General_Public_License>`_ + IPC, `Inter-Processor Communications <https://en.wikipedia.org/wiki/Inter-process_communication>`_ + LCM, Life-Cycle Management + OALK, OpenAMP Linux Kernel + OAOS, `OpenAMP Open Source Project <https://github.com/OpenAMP>`_ + OAPI, OpenAMP Proprietary Implementations + RPC, :ref:`Remote Procedure Calls (RPC)<overview-proxy-rpc-work-label>` + RTOS, Real Time Operating System + RPMsg, `Remote Processor Messaging <https://en.wikipedia.org/wiki/RPMsg>`_ + SMP, `Symmetric Multiprocessing (SMP) <https://en.wikipedia.org/wiki/Symmetric_multiprocessing>`_ + SoC, System on Chip + Virtio, Virtual Input Output diff --git a/openamp/overview.rst b/openamp/overview.rst index c7e123b..277a0a6 100644 --- a/openamp/overview.rst +++ b/openamp/overview.rst @@ -8,28 +8,37 @@ OpenAMP Intro `Asymmetric Multiprocessing (AMP) <https://en.wikipedia.org/wiki/Asymmetric_multiprocessing>`_ involves the management, control and communication of multi-core computer systems, where processors have independent tasks and are often in a `heterogeneous <https://en.wikipedia.org/wiki/Heterogeneous_computing>`_ embedded environment where there are different types of processors. This is in contrast to `Symmetric Multiprocessing (SMP) <https://en.wikipedia.org/wiki/Symmetric_multiprocessing>`_ which involves central control and load sharing using identical processor cores and is common place in servers and desktop computers. -The **OpenAMP** project is a community effort that is standardizing and implementing how these multiple embedded systems interact with each other in an AMP environment. It provides conventions and standards as well as an open source implementation to facilitate AMP development for embedded systems. +The **OpenAMP** project is a community effort that is promoting and implementing how these multiple embedded systems interact with each other in an AMP environment. It provides conventions and open source implementation to facilitate AMP development for embedded systems. The vision is that regardless of the operating environment/operating system, it should be possible to use identical interfaces to interact with other operating environments in the same system. -Furthermore, these operating environments can interoperate over a standardized protocol, making it possible to mix and match any two or more operating systems in the same device. +Furthermore, these operating environments can interoperate over a common protocol, making it possible to mix and match any two or more operating systems in the same device. Read more about Asymmetric Multiprocessing :ref:`here<asymmetric-multiprocessing-work-label>`. +******* +History +******* + +Texas Instruments’ remoteproc and RPMsg infrastructure available in the upstream Linux kernel enable the Linux applications running on a host processor to manage the life cycle of remote processor/firmware and perform IPC with them. However, there was no open- source API/software available that provided similar functionality and interfaces for other possible software contexts (RTOS- or bare metal-based applications) running on the remote processor to communicate with the Linux host. Also, AMP applications may require RTOS- or bare metal-based applications to run on the host processor and be able to manage and communicate with various software environments (RTOS, bare metal, or even Linux) on the remote processor. + +The OpenAMP Framework fills these gaps. It provides the required LCM and IPC infrastructure from the RTOS and bare metal environments with the API conformity and functional symmetry available in the upstream Linux kernel. As in upstream Linux, the OpenAMP Framework's remoteproc and RPMsg infrastructure uses virtio as the transport layer/abstraction. + + ************ Project Aims ************ To provide a solution to cover the :ref:`AMP Fundamentals<openamp-fundamentals-work-label>`, the OpenAMP project is divided into the following efforts: - * A standardization group under Linaro Community Projects - - Standardizing the low-level protocol that allows systems to interact (:ref:`more info here<rpmsg-protocol-work-label>`) - + Built on top of the `Virtio Open Standard <https://docs.oasis-open.org/virtio/virtio/v1.3/virtio-v1.3.html>`_ - - Standardizing on the user level APIs that allow applications to be portable + * A guidance group under Linaro Community Projects + - Provides guidance for the low-level protocol that allows systems to interact (:ref:`more info here<rpmsg-protocol-work-label>`) + + Built on top of the `Virtio Open Standard <https://docs.oasis-open.org/virtio/virtio>`_ + - Maintaining common user level APIs that allow applications to be portable + :ref:`RPMSG<rpmsg-protocol-work-label>` + :ref:`remoteproc<lcm-work-label>` - - **Standardizing on the low-level** :ref:`OS/HW abstraction layer<porting-guide-work-label>` **that abstracts the open source implementation from the underlying OS and hardware, simplifying the porting to new environments** + - **Provide low-level** :ref:`OS/HW abstraction layer<porting-guide-work-label>` APIs **that abstracts the open source implementation from the underlying OS and hardware, simplifying the porting to new environments** * An open source project that implements a clean-room implementation of OpenAMP - Runs in :ref:`multiple environments<operating-environments-work-label>` @@ -152,9 +161,9 @@ RemoteProc RPMsg and Virtio ================ -Standardization of the IPC is promoted by the OpenAMP project through the use of :ref:`RPMsg <rpmsg-protocol-work-label>`, using `Open Standard Virtio Devices <https://docs.oasis-open.org/virtio/virtio/v1.3/virtio-v1.3.html>`_ as a HW abstraction or MAC layer. +Standardization of the IPC is promoted by the OpenAMP project through the use of :ref:`RPMsg <rpmsg-protocol-work-label>`, using `Open Standard Virtio Devices <https://docs.oasis-open.org/virtio/virtio>`_ as a HW abstraction or MAC layer. -This abstraction, using virtio, means that the implementer can optionally use :ref:`resource isolation<resource-isolation-work-label>` (e.g. using a hypervisor or secure context), which is exemplified by the first processor in the architecture diagram. The other two remotes are in what is referred to as a hypervisorless-virtio setup because they are using virtio (virtual io) as an abstraction layer but without a hypervisor. +This abstraction, using virtio, means that the implementer can optionally use :ref:`resource isolation<resource-isolation-work-label>` (e.g. using a hypervisor or secure context), which is exemplified by the first processor in the architecture diagram. .. image:: ../images/architecture/overview-architecture-rpmsg.svg @@ -195,7 +204,7 @@ OpenAMP aims to provide components which are portable and aim to be environment The result is that OpenAMP is supported in various operating environments through - an `OpenAMP open source project <https://github.com/OpenAMP>`_ (OAOS), - - a Linux kernel project (OALK), coming through the regular `remoteproc <https://www.kernel.org/doc/html/latest/staging/remoteproc.html>`_/`RPMsg <https://www.kernel.org/doc/html/latest/staging/rpmsg.html>`_/`Virtio <https://docs.kernel.org/driver-api/virtio/virtio.html>`_ efforts in the kernel. + - an OpenAMP Linux Kernel (OALK) project, coming through the regular `remoteproc <https://www.kernel.org/doc/html/latest/staging/remoteproc.html>`_/`RPMsg <https://www.kernel.org/doc/html/latest/staging/rpmsg.html>`_/`Virtio <https://docs.kernel.org/driver-api/virtio/virtio.html>`_ efforts in the kernel. - multiple proprietary implementations (OAPI). The operating environments that OpenAMP supports include: @@ -220,12 +229,10 @@ There are a few guiding principles that governs OpenAMP: - Provide a clean-room implementation of OpenAMP with business friendly APIs and licensing * Allow for compatible proprietary implementations and products - Base as much as possible on existing technologies/open source projects/standards - * In particular :ref:`remoteproc<lcm-work-label>`, :ref:`RPMsg <rpmsg-protocol-work-label>` and virtio + * In particular :ref:`remoteproc<lcm-work-label>`, :ref:`RPMsg <rpmsg-protocol-work-label>` and `virtio <https://docs.oasis-open.org/virtio/virtio>`_ - **Never standardize on anything unless there is an open source implementation that can prove it** - Always be backwards compatible (unless there is a really, really good reason to change) - * In particular make sure to be compatible with the Linux kernel implementation of :ref:`remoteproc<lcm-work-label>`/:ref:`RPMsg <rpmsg-protocol-work-label>`/virtio + * In particular make sure to be compatible with the Linux kernel implementation of :ref:`remoteproc<lcm-work-label>`/:ref:`RPMsg <rpmsg-protocol-work-label>`/`Virtio <https://docs.oasis-open.org/virtio/virtio>`_ There are a number of project members as outlined in `OpenAMP Project Page <https://www.openampproject.org/about/>`_ as well as many community members, so please join the :ref:`OpenAMP open source project<openamp-maintenance-work-label>`! - See https://github.com/OpenAMP/open-amp - -If you want to contribute and port OpenAMP to your platform read more about OpenAMP porting :ref:`here<porting-guide-work-label>`. diff --git a/protocol_details/components.rst b/protocol_details/components.rst index adcd322..1f9b5c2 100644 --- a/protocol_details/components.rst +++ b/protocol_details/components.rst @@ -20,15 +20,6 @@ The key components, and the capabilities they provide, of the OpenAMP Framework remoteproc, This component allows for the Life Cycle Management (LCM) of remote processors from software running on a host processor. The remoteproc API provided by the OpenAMP Framework is compliant with the remoteproc infrastructure present in upstream Linux 3.4.x kernel onward. The Linux remoteproc infrastructure and API was first implemented by Texas Instruments. RPMsg, The RPMsg API enables `Inter Processor Communications (IPC) <https://en.wikipedia.org/wiki/Inter-process_communication>`_ between independent software contexts running on homogeneous or `heterogeneous <https://en.wikipedia.org/wiki/Heterogeneous_computing>`_ cores present in an AMP system. This API is compliant with the RPMsg bus infrastructure present in upstream Linux 3.4.x kernel onward. The Linux RPMsg bus and API infrastructure was first implemented by Texas Instruments. - -******* -History -******* - -Texas Instruments’ remoteproc and RPMsg infrastructure available in the upstream Linux kernel enable the Linux applications running on a host processor to manage the life cycle of remote processor/firmware and perform IPC with them. However, there was no open- source API/software available that provided similar functionality and interfaces for other possible software contexts (RTOS- or bare metal-based applications) running on the remote processor to communicate with the Linux host. Also, AMP applications may require RTOS- or bare metal-based applications to run on the host processor and be able to manage and communicate with various software environments (RTOS, bare metal, or even Linux) on the remote processor. - -The OpenAMP Framework fills these gaps. It provides the required LCM and IPC infrastructure from the RTOS and bare metal environments with the API conformity and functional symmetry available in the upstream Linux kernel. As in upstream Linux, the OpenAMP Framework's remoteproc and RPMsg infrastructure uses virtio as the transport layer/abstraction. - ********** Topologies ********** diff --git a/protocol_details/rpmsg_protocol.rst b/protocol_details/rpmsg_protocol.rst index fb85709..ee344e1 100644 --- a/protocol_details/rpmsg_protocol.rst +++ b/protocol_details/rpmsg_protocol.rst @@ -27,7 +27,7 @@ This layer is the key part of the whole solution - thanks to this layer, there i This technique is however applicable only in core-to-core configuration, not in core-to-multicore configuration, since in such a case, there would be multiple writers to the “IN” ring buffer. This would require a synchronization element, [such as a semaphore?], which is not desirable. -The above shown picture describes the vring component. The Vring is composed of three elementary parts - buffer descriptor pool, the “available” ring buffer (or input ring buffer) and the “used” ring buffer (or free ring buffer). All three elements are physically stored in the shared memory. +The above shown picture describes the vring component. The Vring is composed of three elementary parts - buffer descriptor pool, the available ring buffer and the used ring buffer. All three elements are physically stored in the shared memory. Each buffer descriptor contains a 64-bit buffer address, which holds an address to a buffer stored in the shared memory (as seen physically by the “receiver” or host of this vring), its length as a 32-bit variable, 16-bit flags field and 16-bit link to the next buffer descriptor. The link is used to chain unused buffer descriptors and to chain descriptors, which have the F_NEXT bit set in the flags field to the next descriptor in the chain. @@ -35,15 +35,17 @@ Note that the available and used ring buffer areas contain pointers to buffers, .. image:: ../images/vring_descriptor.jpg -The input ring buffer contains its own flags field, where only the 0th bit is used - if it is set, the “writer” side should not be notified, when the “reader” side consumes a buffer from the input or “avail” ring buffer. By default the bit is not set, so after the reader consumes a buffer, the writer should be notified by triggering an interrupt. The next field of the input ring buffer is the index of the head, which is updated by the writer, after a buffer index containing a new message is written in the ring[x] field. +The available ring buffer contains its own flags field, where only the 0th bit is used - if it is set, the “writer” side should not be notified, when the “reader” side consumes a buffer from the available ring buffer. By default the bit is not set, so after the reader consumes a buffer, the writer should be notified by triggering an interrupt. The next field of the available ring buffer is the index of the head, which is updated by the writer, after a buffer index containing a new message is written in the ring[x] field. -.. image:: ../images/vring_descriptor_flags.jpg +.. figure:: ../images/vring_descriptor_flags.jpg -The last part of the vring is the “used” ring buffer. It contains also a flags field and only the 0th bit is used - if set, the writer side will not be notified when the reader updates the head index of this free ring buffer. The following picture shows the ring buffer structure. The used ring buffer differs from the avail ring buffer. For each entry, the length of the buffer is stored as well. + Flags (16 bit) Fields of Available Ring Buffer Descriptor + +The last part of the vring is the used ring buffer. It contains also a flags field and only the 0th bit is used - if set, the writer side will not be notified when the reader updates the head index of this used ring buffer. The following picture shows the ring buffer structure. The used ring buffer differs from the available ring buffer. For each entry, the length of the buffer is stored as well. .. image:: ../images/vrings_used_buffers.jpg -Both “used” and “avail” ring buffers have a flags field. Its purpose is mainly to tell the writer whether he should interrupt the other core when updating the head of the ring. The same bit is used for this purpose in both “used” and “avail” ring buffers: +Both used and available ring buffers have a flags field. Its purpose is mainly to tell the writer whether he should interrupt the other core when updating the head of the ring. The same bit is used for this purpose in both used and available ring buffers: .. image:: ../images/vrings_used_buffers_flags.jpg