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>

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>

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:43:01Z

+:ref:`Resource Table<resource-table>`.
+
+Memory and interrupt assignments are critical design choices for any port. For a broader overview, refer to
+:doc:`../protocol_details/system_considerations`.


From hardware perspective the OpenAMP require

a shared memory for

the RPmsg buffer

the virtio rings

the resource table (optioal if the rpmsg host is not the Linux kernel)

an optional mailboxes ( burt recommanded ) acting a a ring bell interrupt on processors to inform about message reception

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

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

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

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: regerence)
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

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)

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

Sipke Vriend added 6 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>

docs: add high level overview of hardware and porting options

b89d954

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

b154c0f

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

0778cc5

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 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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve the porting guide page#86

Improve the porting guide page#86
sipke wants to merge 6 commits into
OpenAMP:mainfrom
sipke:feature/improve-the-porting-guide-page

sipke commented May 1, 2026

Uh oh!

sipke commented Jun 1, 2026

Uh oh!

arnopo left a comment

Uh oh!

arnopo May 5, 2026

Uh oh!

arnopo May 5, 2026

Uh oh!

arnopo May 5, 2026

Uh oh!

arnopo May 5, 2026

Uh oh!

arnopo Jun 2, 2026

Uh oh!

arnopo Jun 2, 2026

Uh oh!

arnopo Jun 2, 2026

Uh oh!

arnopo Jun 2, 2026

Uh oh!

arnopo Jun 2, 2026

Uh oh!

arnopo Jun 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		.. _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.

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!

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