Improve the porting guide page by sipke · Pull Request #86 · OpenAMP/openamp-docs

sipke · 2026-05-01T06:58:16Z

Changes to address #85

Added high level overview attempting to address suggestions in the issue to get feedback on direction.
Also added some questions to the issue to get more input for future changes to this PR.

having duplicated embedded doxygen content results in the warning WARNING: Duplicate C++ declaration As these APIs are already detailed in the remoteproc documentation make a reference to them rather than repeat the embed. Signed-off-by: Sipke Vriend <sipke@direktembedded.com>

add some hw acronymns that will be used in porting guide changes to the glossary. Signed-off-by: Sipke Vriend <sipke@direktembedded.com>

sipke · 2026-06-01T07:22:55Z

During review note also the comment for 47ae5ad which includes a snippet from source in openamp-system-reference. If we think this is a good direction for other snippets, it would be better to use the start and end tags as detailed in that comment, rather than line numbers.

arnopo

Hi @sipke

Please find some comments. As mentioned in one of my comments, this pull request might need a few iterations and must be reviewed by other project members.

arnopo · 2026-05-05T15:35:53Z

+Shared memory forms the :ref:`physical layer<rpmsg-layers-work-label>` for
+:doc:`RPMsg <../docs/rpmsg_design>` protocol.
+The specific memory type and layout are implementation dependent, but should be a dedicated
+SRAM or DDR region accessible by both cores, with caching disabled.


open-amp supports cache management

arnopo · 2026-05-05T15:38:12Z

+********
+
+The porting of OpenAMP to a new :doc:`multicore system <../openamp/overview>` requires
+configuring the hardware on each core so it aligns with the OpenAMP architecture.


Proposal ```suggestion
The porting of OpenAMP to a new :doc:multicore system <../openamp/overview> requires
some hardware for inter-processor communication.

arnopo · 2026-05-05T15:51:22Z

+Memory requirements are generally modest because RPMsg is a control‑oriented protocol
+rather than a high‑bandwidth streaming channel. For example, using the Linux RPMsg packet
+size of 512 bytes, a 64kB shared memory region can hold roughly 128 messages — sufficient
+for most applications. Larger or smaller allocations can be chosen based on system needs.


you need also memory for the virtio rings , with Linux you should add 2* 4K for the vrings.. for other can be less

arnopo · 2026-06-02T09:30:19Z

+Shared memory forms the :ref:`physical layer<rpmsg-layers-work-label>` for
+:doc:`RPMsg <../docs/rpmsg_design>` protocol.
+The specific memory type and layout are implementation dependent, but should be a dedicated
+SRAM or DDR region accessible by both cores, with caching disabled.


it work with or without cache. the cache management can be enabled in open-amp using the WITH_DCACHE cmake configuration

arnopo · 2026-06-02T10:13:56Z

+
+.. _driver-lcm-remoteproc:
+
+Driver Lifecycle Management via Remoteproc


Suggested change

Driver Lifecycle Management via Remoteproc

Remote processor Lifecycle Management via Remoteproc

not updated?

arnopo · 2026-06-02T10:17:52Z

+Driver Lifecycle Management via Remoteproc
+==========================================
+
+Some systems do not require IPC or use an alternative IPC mechanism. In these cases, only


to remove the remoteproc framework is independent from the rpmsg

not quite sure here that what is written is opposite to your point. will re-think and re-visit as part of rewrite

if no IPC no remoteproc needed on remote processors

arnopo · 2026-06-02T10:19:31Z

+
+Some systems do not require IPC or use an alternative IPC mechanism. In these cases, only
+:ref:`Remoteproc<overview-remoteproc-work-label>` may be ported (or reused, as on Linux)
+on both the main and remote processors.


the remoteproc framework is optional

need on main processor if it need to manage the remote processor live cyccle

can be used on remoteprocessor to manage the resource table for IPC

ditto to previous

arnopo · 2026-06-02T13:07:49Z

+
+- Pros: Very lightweight.
+- Cons: Highly custom and less portable.
+


I wonder if we should not restructure the chapters.. here is a proposal (from .. _driver-lcm-remoteproc: reference)
i just put titles and list content

Don't hesitate to challenge this , it look to me that we woill probably need few iterations with some other reviewers to land to a good porting guide

Remoteproc framework ==================== - remote processor management - resource table management driver role --------------- - remoteprocessor livecycle management - resource table discovery - example: https://github.com/OpenAMP/openamp-system-reference/tree/main/examples/legacy_apps/examples/load_fw device role --------------- - optional - can be use for the resource table management example: https://github.com/OpenAMP/openamp-system-reference/blob/main/examples/legacy_apps/machine/xlnx/zynqmp_r5/platform_info.c - alternative is to managea static resource table directly example https://github.com/OpenAMP/openamp-system-reference/blob/main/examples/zephyr/rpmsg_multi_services/src/main_remote.c Remoteproc virtio framework ======================== This is the virtio transport layer ( virtio MMIO is another) driver role --------------- - get resource table information and configure it - create virtio driver device role --------------- - get resource table information filled by the virtio driver - create virtio device example https://github.com/OpenAMP/openamp-system-reference/blob/main/examples/zephyr/rpmsg_multi_services/src/main_remote.c RPMsg framework =============== - IPC - based on VirtIO - remoteproc virtio - static vring transport layer example:https://github.com/zephyrproject-rtos/zephyr/tree/main/samples/subsys/ipc/openamp reference to https://github.com/OpenAMP/openamp-system-reference examples for the driver and devices implementation

ok will revisit and see.

Addressed the simpler items, but for the more major ones not sure at this point exactly how to proceed. Also wondering if some of the suggestion belong in the porting page or should they be in a design page as we might be crossing boundaries between porting and implementation options?

In my view, for this pages users will likely approach this with a requirement to implement either the driver or the device topology. With this approach, our role would be to guide them in identifying the appropriate topology (driver or device) and then selecting the assets to integrate, depending on the topology, the presence of Linux on main processor and the required features.

arnopo · 2026-06-02T13:10:27Z

-`remoteproc header <https://github.com/OpenAMP/open-amp/blob/main/lib/include/openamp/remoteproc.h>`_.
+The resource table is effectively a list of resource definitions, with each entry detailed by the
+corresponding :ref:`resource structure<resource-structure>`, and the Remoteproc framework
+is responsible for configuring the relevant drivers and/or bare metal hardware.


is responsible for configuring the resource need by the remote processor ( shared memory, traces buffers, vendor specific resources)

different implementation will use varying combinations of hardware, RPMsg and Remoteproc so provide an overview of these. Signed-off-by: Sipke Vriend <sipke@direktembedded.com>

To further detail what a resource table contains, embed the doxygen from the remoteproc.h structure definitions. Signed-off-by: Sipke Vriend <sipke@direktembedded.com>

Use sphinx's literalinclude to add code snippets from examples rather than having code in the documentation. This helps in the documentation being updated when the code is and shows the user where an example can be studied further. This uses line numbers, which may need adjusting each release, but there would be an option to change code to include start and end tags as follows to avoid line updates. e.g. .. literalinclude:: example.py :start-after: "# start function_x" :end-before: "# end function_y" Signed-off-by: Sipke Vriend <sipke@direktembedded.com>

Reword this section slightly and link to an example rather than include a code snippet. Signed-off-by: Sipke Vriend <sipke@direktembedded.com>

arnopo · 2026-06-30T08:51:43Z

+control‑oriented protocol rather than a high‑bandwidth streaming channel. For example, using
+the Linux RPMsg packet size of 512 bytes, a 64kB shared memory region can hold roughly 128
+messages — sufficient for most applications. Larger or smaller allocations can be chosen based
+on system needs.


64 KB is very big for some system . limit to 16 messages -> 8 KB

"Larger or smaller allocations can be chosen based
on system needs"
-> explain instead that the size and the number of messgae can be tuned based on the system needs and constraints

arnopo · 2026-06-30T09:18:08Z

+on system needs.
+
+In addition to the messages, the Virtio ring structures need memory allocated. For Linux
+this equates to 2*4k but likely less for other implementations.


for linux the size of the allocated vering is aligned on a linux kernel Page ( usually 4K)

arnopo · 2026-06-30T09:21:53Z

+
+On systems running an advanced OS — such as Linux on the main
+processor — these protections may be applied through OS mechanisms like the device tree or
+via the :ref:`Remoteproc<overview-remoteproc-work-label>` :ref:`Resource Table<resource-table>`.


Confusing, I would remove this sentence. protections can not be applied trough resource table and are platform dependent. this can be done by some other mechanisms

arnopo · 2026-06-30T09:40:57Z

+- :ref:`Remoteproc<overview-remoteproc-work-label>` on the remote processor only,
+  with the main processor using an existing
+  :ref:`Remoteproc<overview-remoteproc-work-label>` implementation (e.g., Linux Remoteproc)
+  and no IPC.


One criticism of OpenAMP is that the remote processor framework is required on the remote device side. that why I would split remoteproc in 3 feature:

remote processor live cycle management ( implemented on main processor)

remoteproc virtio : the transport layer of the virtio protocol

the resource table

In fact, on the remote side, the full remote processor framework is not required. Only the remote processor virtio transport layer is required. the resource table is also only mandatory for communication with Linux.
In addition, if no inter-process communication (IPC) is implemented, the remote side does not need the remote processor framework.

see my proposal in comment https://github.com/OpenAMP/openamp-docs/pull/86/changes#r3340380433

arnopo · 2026-06-30T09:42:14Z

+Driver Lifecycle Management via Remoteproc
+==========================================
+
+Some systems do not require IPC or use an alternative IPC mechanism. In these cases, only


if no IPC no remoteproc needed on remote processors

arnopo · 2026-06-30T09:46:32Z

+
+.. _driver-lcm-remoteproc:
+
+Driver Lifecycle Management via Remoteproc


not updated?

arnopo · 2026-06-30T12:18:17Z

+
+This configuration is common in custom or bare‑metal remote environments.
+
+- Pros: Full IPC and remote firmware management


This is one main point that is not necessarily true for the remote processor side. We try to minimize the footprint on the remote side even in this topology.
For me, there is usually a mix-up between the remoteproc virtio, which is the virtio transport layer, and the remoteproc that manages the load and lifecycle of the remote processor.

i would like try to have a more explicit split for the remote proc framework.

arnopo · 2026-06-30T12:37:08Z

+
+- Pros: Very lightweight.
+- Cons: Highly custom and less portable.
+


In my view, for this pages users will likely approach this with a requirement to implement either the driver or the device topology. With this approach, our role would be to guide them in identifying the appropriate topology (driver or device) and then selecting the assets to integrate, depending on the topology, the presence of Linux on main processor and the required features.

sipke force-pushed the feature/improve-the-porting-guide-page branch from d959cdc to 3dcae1d Compare May 11, 2026 04:58

Sipke Vriend added 2 commits June 1, 2026 17:08

glossary: add hardware definitions used for porting page changes

1040096

add some hw acronymns that will be used in porting guide changes to the glossary. Signed-off-by: Sipke Vriend <sipke@direktembedded.com>

sipke force-pushed the feature/improve-the-porting-guide-page branch from 3dcae1d to 0778cc5 Compare June 1, 2026 07:19

sipke marked this pull request as ready for review June 1, 2026 07:21

arnopo requested review from arnopo, edmooring, tnmysh and wmamills June 2, 2026 09:10

arnopo added this to the Release V2026.10 milestone Jun 2, 2026

arnopo reviewed Jun 2, 2026

View reviewed changes

sipke force-pushed the feature/improve-the-porting-guide-page branch from 0778cc5 to ad38d12 Compare June 29, 2026 04:57

Sipke Vriend added 4 commits June 29, 2026 15:34

docs: add high level overview of hardware and porting options

2f403d6

different implementation will use varying combinations of hardware, RPMsg and Remoteproc so provide an overview of these. Signed-off-by: Sipke Vriend <sipke@direktembedded.com>

protocol_details: expand resource table to include embedded structures

8d2f773

To further detail what a resource table contains, embed the doxygen from the remoteproc.h structure definitions. Signed-off-by: Sipke Vriend <sipke@direktembedded.com>

docs: reword RPMsg porting section and remove code snippet

85ebc56

Reword this section slightly and link to an example rather than include a code snippet. Signed-off-by: Sipke Vriend <sipke@direktembedded.com>

sipke force-pushed the feature/improve-the-porting-guide-page branch from ad38d12 to 85ebc56 Compare June 29, 2026 05:35

arnopo reviewed Jun 30, 2026

View reviewed changes


		.. _driver-lcm-remoteproc:

		Driver Lifecycle Management via Remoteproc

	Driver Lifecycle Management via Remoteproc
	Remote processor Lifecycle Management via Remoteproc


		- Pros: Very lightweight.
		- Cons: Highly custom and less portable.


		This configuration is common in custom or bare‑metal remote environments.

		- Pros: Full IPC and remote firmware management

Uh oh!

Conversation

sipke commented May 1, 2026

Uh oh!

sipke commented Jun 1, 2026

Uh oh!

arnopo left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

arnopo Jun 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

arnopo Jun 2, 2026 •

edited

Loading