Improve the porting guide page

[arnopo]

Improve the page: https://openamp.readthedocs.io/en/latest/docs/porting_guide.html

1. List the hardware needed (shared memory, mailbox)

Clearly enumerate the essential hardware components:

• Shared Memory:

  • Explain its role or reference page that explans it (used for inter-processor communication).
  • Specify typical requirements (address range, size, access permissions).
  • Provide code examples based on baremetal interface (e.g., SRAM, DDR, or dedicated memory region).

• Mailbox/Interrupt Mechanism:

  • Describe its role (used for signaling between processors).
  • List common implementations (hardware mailbox, software interrupt, etc.).

2. List the porting options:

• For each porting option, provide:

  • Description
  • Typical use case
  • Pros/cons
  • cmake configuration
  • link to code example when possible

• Driver with remoteproc device loading

  • Description: Uses remoteproc framework to load and manage remote processor firmware.
  • Use case: Custom or bare-metal environments, when the firmware needs to supports remoteproc.
  • Pros: remote firmware management.
  • Cons: increase footprint.

• Drivers role with RPMsg only

  • Description: Implements only RPMsg communication, without remoteproc.
  • Use case: When remote firmware loading is handled externally.
  • Pros: Lightweight.
  • Cons: no remote firmware management.

• Device role with RPMsg Device

  • Description: Minimal port, only device-level integration.
  • Use case: Custom or bare-metal environments.
  • list associated cmake configuration

• Resource table usage

  • Description:
    Explains how to use and format resource tables for device and driver role.
    Explain need for Linux compatibility.
    Explain how to implement RPMSg without it (see Zephyr example)
  • Use case: Required for remoteproc and RPMsg integration with Linux, else optional

3. provide more information on the metal initialization part

[sipke]

As it happens, the Duplicate C++ declaration warnings produced by sphinx are in the porting_guide and the remoteproc_design. So I propose as part of the change for this issue, we can fix the warnings by dropping the embedded doxygen from the porting guide and reference instead the remoteproc_design page. If needed we can mention in the porting guide that said functions are required to be ported but only embed that function in the remoteproc_design page, which makes sense as its detailing the design.
Refer #81 (comment) for background.

[arnopo]

As it happens, the Duplicate C++ declaration warnings produced by sphinx are in the porting_guide and the remoteproc_design. So I propose as part of the change for this issue, we can fix the warnings by dropping the embedded doxygen from the porting guide and reference instead the remoteproc_design page. If needed we can mention in the porting guide that said functions are required to be ported but only embed that function in the remoteproc_design page, which makes sense as its detailing the design. Refer #81 (comment) for background.

Right it is not necessary that the porting guide contains the detailed descriptions of the APIs

[sipke]

a. I think the last bullet point of item 2 above is missing a heading so I'm not quite sure what you meant.
b. I created a draft PR for this with an overview but haven't filled in examples yet. Not having done a port it would be helpful and save me some time digging, if you know what examples you'd like integrated if you could point at them.
c. For the "Device role with RPMsg Device" did you mean to single this out to RPMsg only or is there a scenario where both RPMsg and Remoteproc would be implemented as baremetal on both sides?

[arnopo]

a. I think the last bullet point of item 2 above is missing a heading so I'm not quite sure what you meant.

I fix the formating, please tel me if still need clarification.

b. I created a draft PR for this with an overview but haven't filled in examples yet. Not having done a port it would be helpful and save me some time digging, if you know what examples you'd like integrated if you could point at them.

sure, I will have a look

c. For the "Device role with RPMsg Device" did you mean to single this out to RPMsg only or is there a scenario where both RPMsg and Remoteproc would be implemented as baremetal on both sides?

Both could be documented, as a first step you can refer to pmsg_multi_services