Add PSA-SPM porting guide

[danny4478]

The document is currently Work In Progress but its structure and most of its contents is here.
It is loaded as a PR so it can be reviewed by tech-writers.
Current gaps:

• Doxygen should be generated once SPM HAL is finalized, and then corresponding links will be added.
• HAL tests names will be updated once finalized.
• New sections might be added.

[danny4478]

CC @alzix

[alzix]

@danny4478, please note that linker scripts part will probably change, according to HAL integration review meeting minutes.
mailbox integration part is missing completely

[AnotherButler]

This looks like great content. Could you please add a section about defined and undefined behavior if relevant?

[AnotherButler]

Also, please add a dependency section that lists any dependencies if relevant.

[danny4478]

CC @amiraloosh

[danny4478]

@alzix, you have mentioned mailbox integration is missing. This is all covered in the HAL which will eventually point to our Doxygen.
Do you want to add a new section for it? What would its content be?
I think the right thing to do here is maybe elaborate some about the HAL functions inside the HAL Functions section, describing the 3 HAL "subjects" but not listing the entire functions list - what do you think?

[alzix]

consider yourself an integrator wishing to port mbed-os to your target.
will you, without any prior knowledge, be able to understand what is required by only looking at the header file?
i highly doubt it.

[danny4478]

@alzix, please see what I have suggested. Is this ok by you?

[AnotherButler]

Adding OOB and HAL reviewers because this seems relevant to them

[danny4478]

@AnotherButler , Regarding your suggestion to add defined and undefined behavior sections, and section that lists any dependencies if relevant:
They seem irrelevant here. I cannot see anything that can naturally fit into these sections.

[danny4478]

@AnotherButler , should we add somewhere a link or a reference to this Porting Guide?
We saw in 5.10 [https://os.mbed.com/docs/v5.10/porting/index.html], a table with porting guide references.

[AnotherButler]

@danny4478 We encourage linking to other parts of the documentation over duplicating content, so I say yes. Also, we have this porting guide, which is still in editing but will go live by 5.11.

[danny4478]

@AnotherButler , we could not find the place to add a link/reference to our new Porting Guide.
We just saw this table I have mentioned but could not find the page in the repository which needs to be edited.

[AnotherButler]

What's the status of the content reviews on this? Is it ready for docs review?

[danny4478]

The content is currently under modifications by @alzix

[alzix]

done modifying
@danny4478 @AnotherButler can you please review?

[AnotherButler]

I've left reminders to complete the todos. Otherwise, this looks good 👍

[AnotherButler]

Please add this link.

[AnotherButler]

I can help find this link, but I'm not sure what you want to link to. Could you please elaborate?

[danny4478]

@AnotherButler This Doxygen was not generated yet (at least its final version). We are waiting for some PRs to be merged into mbed-os, then I will send you the information to generate the Doxygen with, and you can generate them and send me the link.

[danny4478]

@alzix:
Since silicon partners have to add a new target to targets.json, I think the section headline should be called targets.json editing (or something lie that).
In this section we will describe the targets.json required modification.
Memory addresses and sizes (the "overrides" part) are a part of this, and memory layout explanation can be a sub-section here.
Except for "overrides" and the "inherits" parts (which you have mentioned) we should mention:

• "extra_labels_add" part
• "components_add" part (mailbox)
• "deliver_to_target"
  What do you think?

[AnotherButler]

This PR is waiting on engineering approval, a link to some HAL Doxygen and two code dependencies.

[AnotherButler]

Depends on ARMmbed/mbed-os#8745 and ARMmbed/mbed-os#8744

[alzix]

@AnotherButler what is the right way of writing, nonsecure or non-secure?
If it is a single word we probably need to change our configuration symbols.
In PSA FF specs the dash version (non-secure) is used.

[danny4478]

@AnotherButler The document is ready for final mbed-docs team review.
Please note we have inconsistency regarding the 2 items below:

1. nonsecure / non-secure
2. Arm / ARM / arm

TODO: Doxygen link - Currently pending on PSA core team to send the sources fro the Doxygen.

[AnotherButler]

@danny4478 Great questions. Please see my answers below:

1. nonsecure
2. Arm

[danny4478]

@alzix Can you please see if you have any other comments and approve if everything is ok by you?

Current status:

• We are waiting for PSA Secure partition manager and services mbed-os#8744 (Add new target future sequana PSA mbed-os#8745 will not be merged).
• Then we will have to generate a Doxygen file and add a link to it.

C @AnotherButler

[c1728p9]

You may want to link to the bootstrap page with linker script templates since it contains a lot of this content:
https://github.com/ARMmbed/mbed-os-5-docs/blob/development/docs/porting/target/bootstrap.md

[MarceloSalazar]

This is concerning. The doc is including references to the target FUTURE_SEQUANA but the target support has been scheduled for 5.11.1 - ARMmbed/mbed-os#8745

[danny4478]

This is concerning. The doc is including references to the target FUTURE_SEQUANA but the target support has been scheduled for 5.11.1 - ARMmbed/mbed-os#8745

This is only an example demonstrating how the structure should look like, and which fields have to be there. The target name, and the regions' values do not have to be real, so I am fine with it as it is now.
If you still think it is better to use another target name, just let me know and we will fix it.

[MarceloSalazar]

Sorry, I'm not fine with this, as it's misleading.
Let's leave the target name issue aside for now.
Our priority is to make sure there is consistency, the feature can be evaluated during OOB with real hardware, using an application and running tests as explained here.

[MarceloSalazar]

I don't think we're ready to merge this until we have a FUTURE_SEQUANA platform available with Mbed OS that works with PSA

[AnotherButler]

What's the result of the above conversation? Are we waiting until a future patch release to include documentation for this feature because an example references a target we don't support? Can we remove the example and move forward with this documentation?

[danny4478]

Depends on ARMmbed/mbed-os#8873

[AnotherButler]

Merging because code has merged.