Skip to content

Commit c8e1d22

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

File tree

1 file changed

+127
-0
lines changed

1 file changed

+127
-0
lines changed

‎docs/porting/psa/spm.md

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
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+
**This page gives guidelines for silicon partners wishing to have Secure Partition Manager capabilities**
6+
7+
## Linker Scripts
8+
9+
Silicon partners must edit the secure and non-secure linker scripts to define sections for RAM, FLASH and SHARED_RAM.
10+
11+
Linker scripts guidelines:
12+
- *__shared_memory_start* symbol is used in SPM code so it must be set with the start address of the shared memory
13+
- *__shared_memory_start* must be 4 bytes aligned
14+
- *__shared_memory_end* symbol is used in SPM code so it must be set with the end address of the shared memory
15+
- SHARED_RAM must have Read/Write permissions from secure and non-secure cores
16+
- SHARED_RAM address must be 4 bytes aligned
17+
- SHARED_RAM must be given a minimum memory space of 256 bytes
18+
- Secure RAM base address must be 4 bytes aligned and have Read/Write permissions only from secure core
19+
- Secure FLASH base address must be 4 bytes aligned and have Read/Write/Execute permissions only from secure core
20+
- Non-Secure RAM base address must be 4 bytes aligned and have Read/Write permissions from secure and non-secure cores
21+
- 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
22+
23+
This is an example of the relevant parts inside the linker scripts:
24+
25+
#### SECURE Core Linker Script
26+
27+
```
28+
...
29+
...
30+
MEMORY
31+
{
32+
/* The ram and flash regions control RAM and flash memory allocation for the SECURE core.
33+
* You can change the memory allocation by editing the 'ram' and 'flash' regions.
34+
* Your changes must be aligned with the corresponding memory regions for the NON-SECURE core in the
35+
* NON-SECURE linker script.
36+
*/
37+
ram (rwx) : ORIGIN = 0x08000000, LENGTH = 0x10000
38+
shared_ram (rw) : ORIGIN = 0x08010000, LENGTH = 0x1000
39+
flash (rx) : ORIGIN = 0x10000000, LENGTH = 0x78000
40+
41+
...
42+
...
43+
}
44+
45+
...
46+
...
47+
48+
/* .shared_mem section contains memory shared between SECURE core and NON-SECURE core */
49+
.shared_mem :
50+
{
51+
__shared_memory_start = .;
52+
. += 0x1000;
53+
__shared_memory_end = .;
54+
55+
/* Check if section is 4 bytes aligned */
56+
ASSERT (((__shared_memory_start % 4) == 0), "Error: shared_mem section is not 4 bytes aligned!!");
57+
} > shared_ram
58+
59+
...
60+
...
61+
```
62+
63+
#### NON-SECURE Core Linker Script
64+
```
65+
...
66+
...
67+
MEMORY
68+
{
69+
/* The ram and flash regions control RAM and flash memory allocation for the NON-SECURE core.
70+
* You can change the memory allocation by editing the 'ram' and 'flash' regions.
71+
* Your changes must be aligned with the corresponding memory regions for the SECURE core in the
72+
* SECURE linker script.
73+
*/
74+
ram (rwx) : ORIGIN = 0x08011000, LENGTH = 0x36800
75+
flash (rx) : ORIGIN = 0x10080000, LENGTH = 0x78000
76+
77+
...
78+
...
79+
}
80+
81+
...
82+
...
83+
```
84+
85+
## HAL Functions
86+
87+
Target specific code of silicon partners who wish to have SPM capabilities must:
88+
- Implement a list of functions which are being called by SPM code
89+
- Call other functions supplied by ARM
90+
91+
A list of these functions can be found here [TODO: WHEN READY, ADD LINK TO DOXYGEN FILES OF HAL FUNCTIONS]
92+
93+
94+
## Memory Protection
95+
96+
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.
97+
This function should apply memory protection schemes to ensure secure memory can only be accessed from secure-state.
98+
99+
The implementation of this function, must be aligned with the SPM general guidelines as described in the table below.
100+
101+
This table describes the allowed operations (Read / Write / Execute) on the Secure and Non-Secure RAM and FLASH by each core:
102+
103+
- X means No Access
104+
- V means Must Be Able to Access
105+
- ? means it is up to the target
106+
107+
Processor Access |Secure RAM |Secure FLASH|Non Secure RAM |Non Secure FLASH
108+
--------------------|------------------|------------|-------------------|----------------
109+
`Non Secure Read` | X | X | V | V
110+
`Non Secure Write` | X | X | V | ?
111+
`Non Secure Execute`| X | X | ? (preferably X) | V
112+
`Secure Read` | V | V | V | V
113+
`Secure Write` | V | V | V | ?
114+
`Secure Execute` | ? (preferably X) | V | X | ?
115+
116+
117+
## Testing
118+
119+
ARM provides a list of tests to make sure the HAL functions are implemented according to requirements, and the porting is done correctly.
120+
121+
After finalizing the porting, the following tests should be executed:
122+
- [TODO: WHEN READY, ADD TEST NAME]
123+
- [TODO: WHEN READY, ADD TEST NAME]
124+
- ...
125+
126+
It is recommended to leave the memory protection part [*spm_hal_memory_protection_init()* implementation] to the end of the porting.
127+
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)