1################################
2TF-M Inter-Process Communication
3################################
4
5:Authors: Ken Liu, Mingyang Sun
6:Organization: Arm Limited
7:Contact: ken.liu@arm.com, mingyang.sun@arm.com
8
9***********
10Terminology
11***********
12
13IPC - Inter-Process Communication
14
15For more terminology please check Reference_ document.
16
17***************
18Design Overview
19***************
20Components for implementing IPC:
21
22- SPM – for partition information and isolation actions
23- Core – for exception handling
24- Memory pool
25- Message manager
26- Thread
27- Synchronization objects
28- PSA API
29
30**********************
31Implementation Details
32**********************
33Listed modules are all internal modules except PSA API. Prototypes and
34definitions are not listed for internal modules in this document. For PSA
35API definitions, check them in PSA Firmware Framework specification in the
36reference chapter.
37
38SPM and Core
39============
40SPM manages Secure Partition information. Enhancements need to be done in SPM
41data structure for Secure Partition for IPC due to:
42
43- IPC model requires each Secure Partition has its own stack area.
44- Multiple services are holding in same Secure Partition and each service
45  has its own information like message queue, SID and priority.
46- Changed information related manifest items need to be changed, too.
47
48Modifications in Core:
49
50- More SVC calls need to be added into list since PSA API are implemented as
51  SVC calls in TF-M.
52- New PendSV handler for thread scheduling.
53- Arch-related context stacking and switching.
54
55Memory Pool
56===========
57Handles of connection and messages for Secure Partition needs to be allocated
58dynamically. A memory pool is provided in the system to handle dynamic
59allocation. Each memory pool item contains below information:
60
61- A list iterator to chain all of memory pool items.
62- An information member to record information like size and types.
63- The memory item body for caller usage.
64
65A memory area needs to be provided in SPM for the memory pool. It could be an
66array of memory areas defined in the linker script. Two chains are available to
67manage the items: free chain and used chain. And an LRU (Last recent used)
68mechanism is applied for fast seeking while item allocating and destroying.
69
70Message Manager
71===============
72Message Manager handles message creating, pushing, retrieving and destroy. A
73message contains below information:
74
75- Message sender and destination
76- Message status
77- IO vectors for service
78- 'psa_msg_t' for service
79
80A checking needs to be performed in SPM before creating a message to detect if
81a message with the same sender and destination is ongoing. This avoids repeat
82messages are available in the queue.
83
84Thread
85======
86Each Secure Partition has a thread as execution environment. Secure Partition
87is defined statically in TF-M manifest, which indicates that a number of
88threads are statically defined. Threads are chained in SPM and sorted with
89its priority, and there is an extra indicator point to first running thread
90with the highest priority. This helps fast seeking of running threads while
91the scheduler is switching threads.
92
93Thread context contains below information:
94
95- Priority
96- Status
97- Stack pointer
98- Stack pointer limitation
99- Entry
100- Parameter
101- Entry return value
102- Context
103- List iterator
104
105Thread API provides below functions:
106
107- Thread creating and destroying
108- Thread status retrieving and changing
109- Current thread retrieving
110- Thread context switching
111
112PendSV exception in TF-M core is the place thread context APIs been called.
113Before thread switching taking place, isolation status needs to be changed
114based on Secure Partition change and current isolation level – a thread is a
115member of partition which means thread switching caused a partition switching.
116
117Synchronization API
118===================
119A first synchronization object is an event. This could be applied into event
120waiting in the partition, and message response handling in IPC. The event
121object contains below members:
122
123- Owner thread who is waiting for this event
124- Event status (Ready or Not-Ready)
125- List iterator for synchronization objects management
126
127Event API Limitation: could be waited by one thread only.
128
129PSA API
130=======
131This chapter describes the PSA API in an implementation manner.
132
133- API type: could be Client API and Service Partition API
134- Block-able: Block-able API may block caller thread; Non-Block API does not
135  block caller thread.
136- Description: The functionality description and important comments.
137
138.. code-block:: c
139
140    uint32_t psa_framework_version(void);
141    uint32_t psa_version(uint32_t sid);
142
143- Client API
144- Non-Block API
145- These 2 functions are finally handled in SPM and return the framework version
146  or version to the caller.
147
148.. code-block:: c
149
150    psa_handle_t psa_connect(uint32_t sid, uint32_t version);
151    psa_status_t psa_call(psa_handle_t handle, int32_t type,
152                          const psa_invec *in_vec, size_t in_len,
153                          psa_outvec *out_vec, size_t out_len);
154    void psa_close(psa_handle_t handle);
155
156- Client API
157- Block-able API
158- These 3 APIs are implemented in the same manner and just different
159  parameters. SPM converts each call into a corresponding message with a
160  parameter in the message body and pushes the message into service queue to
161  wait for the response. Scheduler switches to a specified thread (partition)
162  and makes Secure Partition to have chance retrieving and process message.
163  After a message response is returned to the caller, the waiting caller gets
164  to go and get the result.
165
166.. code-block:: c
167
168    psa_signal_t psa_wait(psa_signal_t signal_mask, uint32_t timeout);
169
170- Secure Partition API
171- Block-able API
172- This API blocks caller partition if there is no expected event for it. This
173  function is implemented based on event API.
174
175.. code-block:: c
176
177    void psa_set_rhandle(psa_handle_t msg_handle, void *rhandle);
178    psa_status_t psa_get(psa_signal_t signal, psa_msg_t *msg);
179    size_t psa_read(psa_handle_t msg_handle, uint32_t invec_idx,
180                    void *buffer, size_t num_bytes);
181    size_t psa_skip(psa_handle_t msg_handle, uint32_t invec_idx,
182                    size_t num_bytes);
183    void psa_write(psa_handle_t msg_handle, uint32_t outvec_idx,
184                   const void *buffer, size_t num_bytes);
185    void psa_reply(psa_handle_t msg_handle, psa_status_t status);
186    void psa_clear(void);
187    void psa_eoi(psa_signal_t irq_signal);
188
189- Secure Partition API
190- Non-Block
191- These APIs do not take the initiative to change caller status. They process
192  data and return the processed data back to the caller.
193
194.. code-block:: c
195
196    void psa_notify(int32_t partition_id);
197
198- Secure Partition API
199- Non-Block
200- This API sets DOORBELL bit in destination partition's event. This API does
201  not take the initiative to change caller status.
202
203.. code-block:: c
204
205    void psa_panic(void);
206
207- Secure Partition API
208- Block-able API
209- This function will terminate execution within the calling Secure Partition
210  and will not return.
211
212*********
213Reference
214*********
215
216| `PSA Firmware Framework specification URL`_
217
218.. _PSA Firmware Framework specification URL:
219  https://www.arm.com/architecture/security-features/platform-security
220
221--------------
222
223*Copyright (c) 2019-2022, Arm Limited. All rights reserved.*
224