Hi Anton, Hi Kevin,

Thanks for starting this discussion.  Let me give you my view on it.

I think the problem can be structured in these parts:

• Give documentation a better overall structure
• Clearly separate single core v8M from dual core v7M
• Describe the overall structure of the files and configuration options of TF-M
• Describe resource requirements of TF-M core
• Describe platform interfaces and provide templates
• Describe how a Service is added to TF-M
• Describe the tools/utilities that are used for TF-M

While the debugging aspect raised by Kevin is relevant, it is a generic problem for all v8-M projects, not just for TF-M.  I’m supportive to provide tools like pyOCD, but we need proper resourcing for it (maybe a separate project).  It should be also noted that the industry works typically with tools like EWARM, MDK, or vendor specific tools like STCube or MCUxpresso.  Hence we should not directly add too much tool-specific information to TF-M itself.

Now let me give more context to each of the above topics.

----

Give documentation a better overall structure

The Trusted Firmware-M documentation starts here:

https://ci.trustedfirmware.org/job/tf-m-build-test-nightly/lastSuccessfulBuild/artifact/build-docs/tf-m_documents/install/doc/user_guide/html/index.html

While this is already a User’s Guide, it contains two more user’s guides

https://ci.trustedfirmware.org/job/tf-m-build-test-nightly/lastSuccessfulBuild/artifact/build-docs/tf-m_documents/install/doc/user_guide/html/docs/user_guides/index.html

https://ci.trustedfirmware.org/job/tf-m-build-test-nightly/lastSuccessfulBuild/artifact/build-docs/tf-m_documents/install/doc/user_guide/html/docs/user_guides/tfm_user_guide.html

For an outsider it is unclear where to start.

Clearly separate single core v8M from dual core v7M

This seems to be somewhat better now as it seems that below only refers to v8M single core: https://ci.trustedfirmware.org/job/tf-m-build-test-nightly/lastSuccessfulBuild/artifact/build-docs/tf-m_documents/install/doc/user_guide/html/docs/user_guides/index.html

Describe the overall structure of the files and configuration options of TF-M

I was looking for something like this:

https://arm-software.github.io/CMSIS_5/RTOS2/html/pDirectory_Files.html

https://arm-software.github.io/CMSIS_5/RTOS2/html/config_rtx5.html

Describe resource requirements of TF-M core

Take a look here to understand that request

https://arm-software.github.io/CMSIS_5/RTOS2/html/pHardwareRequirements.html

Important is also to document the interrupt behaviour (for both the secure and non-secure side).  I know that this is tricky.

For RTX we have this here: https://arm-software.github.io/CMSIS_5/RTOS2/html/cre_rtx_proj.html#cre_UsingIRQs

For TF-M this depends on a lot of other parameters.

Describe platform interfaces and provide templates

What I mean by that are the functions itself that are called by TF_M core.

This is an example of the OS_Tick interface that RTX is using.  TF-M core has similar interfaces to setup MPC, PPC, SAU, etc.

https://arm-software.github.io/CMSIS_5/RTOS2/html/group__CMSIS__RTOS__TickAPI.html

Describe how a Service is added to TF-M

Assume I have functions currently used in NS.  What would be the process to move this functions into TF-M as a service.

How does the API interface change, what modifications do I need (ideally I would like to have the same API interface after it).
Are the any rules for the API interface itself.

You could also provide an example for that, i.e. functions that read a PIN number from an secure keypad or open a DOOR depending on a verification.

I know making a good product is hard and takes time.  CMSIS is not perfect either. Let me know if you have any questions.

Reinhard