Skip to content

Commit a9d4851

Browse files
danny4478danny4478
committed
Add PSA-SPM porting guide
1 parent cbd784f commit a9d4851

File tree

1 file changed

+167
-0
lines changed

1 file changed

+167
-0
lines changed

‎docs/porting/psa/spm.md

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
<h2 id="blockdevice-port">PSA SPM</h2>
2+
3+
SPM (Secure Partition Manager) is a part of the PSA Firmware Framework that is responsible for isolating software in Partitions, managing the execution of software within Partitions, and providing IPC between Partitions.
4+
5+
For more information about SPM, refer to [TODO: WHEN READY, SPM OVERVIEW PAGE LINK]
6+
7+
**This page gives guidelines for silicon partners wishing to have Secure Partition Manager capabilities**
8+
9+
10+
## Linker Scripts
11+
12+
Silicon partners must edit the secure and non-secure linker scripts to define sections for RAM, FLASH and SHARED_RAM.
13+
14+
Linker scripts guidelines:
15+
- *__shared_memory_start* symbol is used in SPM code so it must be set with the start address of the shared memory
16+
- *__shared_memory_start* must be 4 bytes aligned
17+
- *__shared_memory_end* symbol is used in SPM code so it must be set with the end address of the shared memory
18+
- SHARED_RAM must have Read/Write permissions from secure and non-secure cores
19+
- SHARED_RAM address must be 4 bytes aligned
20+
- SHARED_RAM must be given a minimum memory space of 256 bytes
21+
- Secure RAM base address must be 4 bytes aligned and have Read/Write permissions only from secure core
22+
- Secure FLASH base address must be 4 bytes aligned and have Read/Write/Execute permissions only from secure core
23+
- Non-Secure RAM base address must be 4 bytes aligned and have Read/Write permissions from secure and non-secure cores
24+
- Non-Secure FLASH base address must be 4 bytes aligned; must have Read permissions from secure and non-secure cores, and Execute permissions from non-secure core; May have Write permissions from secure and non-secure cores
25+
26+
This is an example of the relevant parts inside the linker scripts:
27+
28+
#### SECURE Core Linker Script
29+
30+
```
31+
...
32+
...
33+
MEMORY
34+
{
35+
/* The ram and flash regions control RAM and flash memory allocation for the SECURE core.
36+
* You can change the memory allocation by editing the 'ram' and 'flash' regions.
37+
* Your changes must be aligned with the corresponding memory regions for the NON-SECURE core in the
38+
* NON-SECURE linker script.
39+
*/
40+
ram (rwx) : ORIGIN = 0x08000000, LENGTH = 0x10000
41+
shared_ram (rw) : ORIGIN = 0x08010000, LENGTH = 0x1000
42+
flash (rx) : ORIGIN = 0x10000000, LENGTH = 0x78000
43+
44+
...
45+
...
46+
}
47+
48+
...
49+
...
50+
51+
/* .shared_mem section contains memory shared between SECURE core and NON-SECURE core */
52+
.shared_mem :
53+
{
54+
__shared_memory_start = .;
55+
. += 0x1000;
56+
__shared_memory_end = .;
57+
58+
/* Check if section is 4 bytes aligned */
59+
ASSERT (((__shared_memory_start % 4) == 0), "Error: shared_mem section is not 4 bytes aligned!!");
60+
} > shared_ram
61+
62+
...
63+
...
64+
```
65+
66+
#### NON-SECURE Core Linker Script
67+
```
68+
...
69+
...
70+
MEMORY
71+
{
72+
/* The ram and flash regions control RAM and flash memory allocation for the NON-SECURE core.
73+
* You can change the memory allocation by editing the 'ram' and 'flash' regions.
74+
* Your changes must be aligned with the corresponding memory regions for the SECURE core in the
75+
* SECURE linker script.
76+
*/
77+
ram (rwx) : ORIGIN = 0x08011000, LENGTH = 0x36800
78+
flash (rx) : ORIGIN = 0x10080000, LENGTH = 0x78000
79+
80+
...
81+
...
82+
}
83+
84+
...
85+
...
86+
```
87+
88+
89+
## Mailbox
90+
91+
Mailbox is the SPM mechanism in charge of Inter Processor Communication, and is **relevant for multi-core systems only**.
92+
93+
#### Concepts
94+
The mailbox mechanism is based on message queues and dispatcher threads.
95+
Each core has a single dispatcher thread, and a single message queue.
96+
The dispatcher thread waits on a mailbox event. Once this event occurs, the dispatcher thread reads and runs "tasks" accumulated on its local message queue.
97+
98+
#### Requirements
99+
The SPM mailbox mechanism requires that the platform should have the following capabilities:
100+
* Inter Processor Communication capabilities - The ability to notify the peer processor about an event (usually implemented with interrupts)
101+
* Ability to set a RAM section which is shared between the cores
102+
103+
#### Porting
104+
These are the guidelines which should be followed by silicon partners with multi-core systems:
105+
- For each core, initialize, configure and enable the a mailbox event (usually an interrupt) at SystemInit()
106+
- For each core, implement the mailbox event handler (usually interrupt handler):
107+
- This handler must call an ARM callback function. This is explained in more details in the [HAL Functions section](#hal-functions)
108+
- It is the silicon partner's responsibility to clear the mailbox event. This can be done in the event handler.
109+
- For each core, implement the HAL function which notifies the peer processor about a mailbox event occurrence. This is a part of the HAL, and explained in more details in the [HAL Functions section](#hal-functions)
110+
111+
112+
## HAL Functions
113+
114+
Target specific code of silicon partners who wish to have SPM capabilities must:
115+
- Implement a list of functions which are being called by SPM code
116+
- Call other functions supplied by ARM
117+
118+
The HAL can be logically divided into 3 different fields:
119+
120+
#### Addresses
121+
This part of HAL allows the silicon partner to share the addresses set in the linker scripts with the SPM code. The SPM uses these addresses mostly to enforce access permissions.
122+
123+
#### Mailbox
124+
This part of HAL allows the silicon partner to implement a thin layer of the mailbox mechanism which is specific to their platform.
125+
It must be implemented only by silicon partners with multi-core systems.
126+
127+
#### Secure Processing Environment
128+
This part of HAL allows the silicon partner to apply their specific memory protection scheme.
129+
130+
A list of these functions can be found here [TODO: WHEN READY, ADD LINK TO DOXYGEN FILES OF HAL FUNCTIONS]
131+
132+
133+
## Memory Protection
134+
135+
As explained in the [HAL Functions section](#hal-functions), target specific code must implement the function *spm_hal_memory_protection_init()* called on SPM initialization.
136+
This function should apply memory protection schemes to ensure secure memory can only be accessed from secure-state.
137+
138+
The implementation of this function, must be aligned with the SPM general guidelines as described in the table below.
139+
140+
This table describes the allowed operations (Read / Write / Execute) on the Secure and Non-Secure RAM and FLASH by each core:
141+
142+
- X means No Access
143+
- V means Must Be Able to Access
144+
- ? means it is up to the target
145+
- X? means it is up to the target, preferably No Access
146+
147+
Processor Access |Secure RAM |Secure FLASH|Non Secure RAM |Non Secure FLASH
148+
--------------------|------------------|------------|-------------------|----------------
149+
`Non Secure Read` | X | X | V | V
150+
`Non Secure Write` | X | X | V | ?
151+
`Non Secure Execute`| X | X | X? | V
152+
`Secure Read` | V | V | V | V
153+
`Secure Write` | V | V | V | ?
154+
`Secure Execute` | X? | V | X | ?
155+
156+
157+
## Testing
158+
159+
ARM provides a list of tests to make sure the HAL functions are implemented according to requirements, and the porting is done correctly.
160+
161+
After finalizing the porting, the following tests should be executed:
162+
- [TODO: WHEN READY, ADD TEST NAME]
163+
- [TODO: WHEN READY, ADD TEST NAME]
164+
- ...
165+
166+
It is recommended to leave the memory protection part [*spm_hal_memory_protection_init()* implementation] to the end of the porting.
167+
First implement and test other HAL functions, and after these tests pass, implement *spm_hal_memory_protection_init()* and run the entire test suite again, including the memory protection related tests.

0 commit comments

Comments
 (0)