diff --git a/docs/porting_guide.rst b/docs/porting_guide.rst index 464e076..1a41092 100644 --- a/docs/porting_guide.rst +++ b/docs/porting_guide.rst @@ -4,6 +4,145 @@ Porting GuideLine ================= +******** +Hardware +******** + +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. + +This setup typically includes defining a shared memory region for +:ref:`RPMsg` based +:ref:`Interprocessor Communications (IPC)`, with or without interrupts for +asynchronous inter-core notification and defining the firmware execution flow either independently +or with :ref:`Remoteproc` and associated +:ref:`Resource Table`. + +Memory and interrupt assignments are critical design choices for any port. For a broader overview, refer to +:doc:`../protocol_details/system_considerations`. + + +Shared Memory +============= + +Shared memory forms the :ref:`physical layer` 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. + +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. + +If the resource table is not embedded in the remote firmware image, additional shared memory +may be required for a dynamic table. + +Remoteproc can also use shared memory for optional trace buffers. + + +Memory Protection +----------------- + +Because this is shared memory, appropriate hardware memory protection should be configured +on both processors. + +Depending on the memory type, this may involve configuring the Memory Management Unit (MMU), +Memory Protection Unit (MPU), or Input-Output Memory Management Unit (IOMMU) to enforce +correct access permissions. + +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 Remoteproc resource table. + + +Notification +------------ + +RPMsg uses :ref:`ring buffers` in shared memory, so either processor can +poll for incoming messages. However, asynchronous notification via interrupts is recommended. + +Most heterogeneous SoCs include a built‑in inter‑core interrupt mechanism, often called a +mailbox. These implementations typically combine shared memory with interrupt signaling and +may be managed through an Inter‑Processor Communication Controller (IPCC). + +If no dedicated hardware is available — or it is reserved for other purposes — +software‑generated interrupts can be used instead. + + +*************** +Porting Options +*************** + +OpenAMP consists of two major components: Remoteproc and RPMsg. These can be ported +independently or together, at either the driver level or the device level. + +Driver level ports integrate with an operating system’s existing frameworks, +while device level ports implement the functionality directly on bare metal without +leveraging OS‑provided drivers. + +libmetal provides the :ref:`hardware abstraction layer` for both. + +The main porting approaches include: + +- Remoteproc on the remote processor only, with the main processor using an existing + Remoteproc implementation (e.g., Linux Remoteproc) and no IPC. + +- RPMsg on the remote processor only, with the main processor using an existing RPMsg + stack (e.g., Linux RPMsg) and no remote firmware management. + +- Custom device‑level implementation of Remoteproc and/or RPMsg for both processors. + + +Driver Lifecycle Management via Remoteproc +========================================== + +Some systems do not require IPC or use an alternative IPC mechanism. In these cases, only +Remoteproc may be ported (or reused, as on Linux) on both the main and remote processors. + +The main processor uses driver level Remoteproc to load, start, stop, and manage remote +firmware. +This approach is useful when the remote firmware must be externally controlled or when +multiple firmware images may be deployed depending on runtime needs. +Thie configuration is common in custom or bare‑metal remote environments. + +- Pros: Full remote firmware management +- Cons: No IPC. Larger software footprint + +Driver to Remote IPC via RPMsg +============================== + +If the remote firmware is static and starts at boot, or if another framework manages +firmware loading, only RPMsg needs to be ported. +In this model, the remote processor runs its firmware autonomously, and the main processor +interacts with it solely through the RPMsg communication channel, without any involvement +in firmware lifecycle control. This approach suits systems where the remote environment is +minimal or bare‑metal, and where the primary requirement is efficient message‑based +IPC rather than external management of the remote core. + +- Pros: Lightweight. Provides IPC. +- Cons: No remote firmware management. + +Device Level Custom Remoteproc and/or RPMsg +=========================================== + +In highly customized or bare‑metal only environments, a port of Remoteproc and/or RPMsg may be +required without any driver‑level abstraction. +In this case, one or all of the full Remoteproc and RPMsg mechanism must be implemented +directly on both the main and remote processors, ensuring that each core provides the necessary +firmware lifecycle management, messaging, shared‑memory handling, and notification logic without +relying on OS‑level drivers or frameworks. + +- Pros: Lightweight. +- Cons: Highly custom and less portable. + + +.. _hardware-abstraction: + +******************** +Hardware Abstraction +******************** + The `OpenAMP Framework `_ uses `libmetal `_ to provide abstractions that allows for porting of the OpenAMP Framework to various software environments (operating systems and bare metal @@ -132,23 +271,8 @@ Platform Specific Porting to Use Remoteproc to Manage Remote Processor ********************************************************************** With the platform specific :ref:`remoteproc driver functions` -implemented by the port, the user can use remoteproc APIs to run application on a remote processor. - -.. doxygenfunction:: remoteproc_init - :project: openamp_doc_embed - -.. doxygenfunction:: remoteproc_remove - -.. doxygenfunction:: remoteproc_mmap - -.. doxygenfunction:: remoteproc_config - -.. doxygenfunction:: remoteproc_start - -.. doxygenfunction:: remoteproc_stop - -.. doxygenfunction:: remoteproc_shutdown - +implemented by the port, the user can use remoteproc APIs to run application on a remote processor, +as detailed in the :ref:`Remote User APIs` section of the Remote Proc Design. The following code snippet is an example execution. diff --git a/openamp/glossary.rst b/openamp/glossary.rst index 02b03bc..189f1d5 100644 --- a/openamp/glossary.rst +++ b/openamp/glossary.rst @@ -8,12 +8,20 @@ Glossary AMP, `Asymmentric Multiprocessing `_ API, Application Interface + DDR (RAM), Double Data Rate (Random Access Memory) GPL, `GNU General Public License `_ + HAL, Hardware Abstraction Layer + IOMMU, Input-Output Memory Management Unit IPC, `Inter-Processor Communications `_ + IPCC, Inter-Processor Communication Controller LCM, Life-Cycle Management + MMU, Memory Management Unit + MPU, Memory Protection Unit + RAM, Random Access Memory RPC, :ref:`Remote Procedure Calls (RPC)` RTOS, Real Time Operating System RPMsg, `Remote Processor Messaging `_ SMP, `Symmetric Multiprocessing (SMP) `_ SoC, System on Chip + SRAM, Static RAM Virtio, Virtual Input Output diff --git a/protocol_details/lifecyclemgmt_creation.rst b/protocol_details/lifecyclemgmt_creation.rst index d84c52d..dd90f65 100644 --- a/protocol_details/lifecyclemgmt_creation.rst +++ b/protocol_details/lifecyclemgmt_creation.rst @@ -24,7 +24,7 @@ Resource Table Procedure As an example, please refer to the resource table defined in the bare metal remote echo test application at - `rsc_table.c `_. + `rsc_table.c `_. The resource table contains entries for memory carve-out and virtio device resources. The memory carve-out entry contains info like firmware ELF image start address and size. The virtio device resource contains virtio device features, vring addresses, size, and alignment information. The diff --git a/protocol_details/resource_tbl.rst b/protocol_details/resource_tbl.rst index 6861b98..a291314 100644 --- a/protocol_details/resource_tbl.rst +++ b/protocol_details/resource_tbl.rst @@ -14,6 +14,7 @@ at the offset location of each entry. Directly following the header are the reso themselves, each of which has a 32 bit type. These in remote context will likely be memory carveouts for locations of parts of the remote system and virtio device definitions. + +--------------+--------------------------------------------------------------------------------+ | Item | Description | +==============+================================================================================+ @@ -30,14 +31,24 @@ for locations of parts of the remote system and virtio device definitions. | | can correctly extract the information. | +--------------+--------------------------------------------------------------------------------+ -The fw_resource_type's are listed in the -`remoteproc header `_. +The resource table is essentially a list of resource definitions, with each entry describing +a specific :ref:`resource structure`. The Remoteproc framework is +responsible for configuring the appropriate drivers and/or bare‑metal hardware based on +these entries. + +The available resource types are defined in the +`Remoteproc Header `_ +and are described in more detail in the :ref:`resource-types` section below. + + Compatibility with Linux kernel ------------------------------- -The resource table should maintain compatibility with that of -`remoteproc `_. +Since Linux is a major full‑stack operating system in the embedded device space, +the resource table should remain compatible with the +`Linux Remoteproc `_ +format. :: @@ -45,3 +56,42 @@ The resource table should maintain compatibility with that of Related documentation can be found under the Linux kernel's remoteproc documentation: `Binary Firmware Structure `_. + + +.. _resource-types: + +Resource Types +************** + +Each of the resources in the :ref:`resource-table` is defined by a type (fw_resource_type) and +its corresponding :ref:`structure`. + +.. doxygenenum:: fw_resource_type + :project: openamp_doc_embed + + +.. _resource-structures: + +Resource Structure Definitions +------------------------------ + +The following structures correspond to each of the :ref:`resource-types` (fw_resource_type). + +.. doxygenstruct:: fw_rsc_carveout + :project: openamp_doc_embed + +.. doxygenstruct:: fw_rsc_devmem + :project: openamp_doc_embed + +.. doxygenstruct:: fw_rsc_trace + :project: openamp_doc_embed + +.. doxygenstruct:: fw_rsc_vdev + :project: openamp_doc_embed + + +In addition to the predefined :ref:`resource-types` vendors can define their +own with types between RSC_VENDOR_START and RSC_VENDOR_END. + +.. doxygenstruct:: fw_rsc_vendor + :project: openamp_doc_embed