Mistake on this page?
Report an issue in GitHub or email us
TARGET_TFM_V1_0/include/tfm_ns_mailbox.h
1 /*
2  * Copyright (c) 2019-2020, Arm Limited. All rights reserved.
3  *
4  * SPDX-License-Identifier: BSD-3-Clause
5  *
6  */
7 
8 /* Data types and API definitions in NSPE mailbox library */
9 
10 #ifndef __TFM_NS_MAILBOX_H__
11 #define __TFM_NS_MAILBOX_H__
12 
13 #include <stdbool.h>
14 #include <stdint.h>
15 #include "tfm_mailbox.h"
16 
17 #ifdef __cplusplus
18 extern "C" {
19 #endif
20 
21 #ifdef TFM_MULTI_CORE_TEST
22 /**
23  * \brief The structure to hold the statistics result of NSPE mailbox
24  */
25 struct ns_mailbox_stats_res_t {
26  uint8_t avg_nr_slots; /* The value before the decimal point
27  * in the average number of NSPE
28  * mailbox slots in use.
29  */
30  uint8_t avg_nr_slots_tenths; /* The first digit value after the
31  * decimal point in the average
32  * number of NSPE mailbox slots in use.
33  */
34 };
35 #endif
36 
37 /**
38  * \brief Prepare and send PSA client request to SPE via mailbox.
39  *
40  * \param[in] call_type PSA client call type
41  * \param[in] params Parmaters used for PSA client call
42  * \param[in] client_id Optional client ID of non-secure caller.
43  * It is required to identify the non-secure caller
44  * when NSPE OS enforces non-secure task isolation.
45  *
46  * \retval >= 0 The handle to the mailbox message assigned.
47  * \retval < 0 Operation failed with an error code.
48  */
49 mailbox_msg_handle_t tfm_ns_mailbox_tx_client_req(uint32_t call_type,
50  const struct psa_client_params_t *params,
51  int32_t client_id);
52 
53 /**
54  * \brief Fetch PSA client return result.
55  *
56  * \param[in] handle The handle to the mailbox message
57  * \param[out] reply The address to be written with return result.
58  *
59  * \retval MAILBOX_SUCCESS Successfully get PSA client call return result.
60  * \retval Other return code Operation failed with an error code.
61  */
62 int32_t tfm_ns_mailbox_rx_client_reply(mailbox_msg_handle_t handle,
63  int32_t *reply);
64 
65 /**
66  * \brief Check whether a specific mailbox message has been replied.
67  *
68  * \param[in] handle The handle to the mailbox message
69  *
70  * \retval true The PSA client call return value is replied.
71  * \retval false The PSA client call return value is not
72  * replied yet.
73  */
74 bool tfm_ns_mailbox_is_msg_replied(mailbox_msg_handle_t handle);
75 
76 /**
77  * \brief NSPE mailbox initialization
78  *
79  * \param[in] queue The base address of NSPE mailbox queue to be
80  * initialized.
81  *
82  * \retval MAILBOX_SUCCESS Operation succeeded.
83  * \retval Other return code Operation failed with an error code.
84  */
85 int32_t tfm_ns_mailbox_init(struct ns_mailbox_queue_t *queue);
86 
87 #ifdef TFM_MULTI_CORE_MULTI_CLIENT_CALL
88 /**
89  * \brief Get the handle of the current non-secure task executing mailbox
90  * functionalities
91  *
92  * \note This function should be implemented according to platform, NS OS
93  * and actual use scenario.
94  * This function can be ignored or return NULL if sleep/wake-up mechanism
95  * is not required in PSA Client API implementation.
96  *
97  * \return Return the handle of task.
98  */
99 const void *tfm_ns_mailbox_get_task_handle(void);
100 #else
101 static inline const void *tfm_ns_mailbox_get_task_handle(void)
102 {
103  return NULL;
104 }
105 #endif
106 
107 /**
108  * \brief Fetch the handle to the first replied mailbox message in the NSPE
109  * mailbox queue.
110  * This function is intended to be called inside platform specific
111  * notification IRQ handler.
112  *
113  * \note The replied status of the fetched mailbox message will be cleaned after
114  * the message is fetched. When this function is called again, it fetches
115  * the next replied mailbox message from the NSPE mailbox queue.
116  *
117  * \return Return the handle to the first replied mailbox message in the
118  * queue.
119  * Return \ref MAILBOX_MSG_NULL_HANDLE if no mailbox message is replied.
120  */
121 mailbox_msg_handle_t tfm_ns_mailbox_fetch_reply_msg_isr(void);
122 
123 /**
124  * \brief Return the handle of owner task of a mailbox message according to the
125  * \ref mailbox_msg_handle_t
126  *
127  * \param[in] handle The handle of mailbox message.
128  *
129  * \return Return the handle value of the owner task.
130  */
131 const void *tfm_ns_mailbox_get_msg_owner(mailbox_msg_handle_t handle);
132 
133 #ifdef TFM_MULTI_CORE_MULTI_CLIENT_CALL
134 /**
135  * \brief Wait for the reply returned from SPE to the mailbox message specified
136  * by handle
137  *
138  * \param[in] handle The handle of mailbox message.
139  *
140  * \retval MAILBOX_SUCCESS Return from waiting successfully.
141  * \retval Other return code Failed to wait with an error code.
142  */
143 int32_t tfm_ns_mailbox_wait_reply(mailbox_msg_handle_t handle);
144 #endif
145 
146 /**
147  * \brief Platform specific NSPE mailbox initialization.
148  * Invoked by \ref tfm_ns_mailbox_init().
149  *
150  * \param[in] queue The base address of NSPE mailbox queue to be
151  * initialized.
152  *
153  * \retval MAILBOX_SUCCESS Operation succeeded.
154  * \retval Other return code Operation failed with an error code.
155  */
156 int32_t tfm_ns_mailbox_hal_init(struct ns_mailbox_queue_t *queue);
157 
158 /**
159  * \brief Notify SPE to deal with the PSA client call sent via mailbox
160  *
161  * \note The implementation depends on platform specific hardware and use case.
162  *
163  * \retval MAILBOX_SUCCESS Operation succeeded.
164  * \retval Other return code Operation failed with an error code.
165  */
166 int32_t tfm_ns_mailbox_hal_notify_peer(void);
167 
168 /**
169  * \brief Enter critical section of NSPE mailbox.
170  *
171  * \note The implementation depends on platform specific hardware and use case.
172  */
173 void tfm_ns_mailbox_hal_enter_critical(void);
174 
175 /**
176  * \brief Exit critical section of NSPE mailbox.
177  *
178  * \note The implementation depends on platform specific hardware and use case.
179  */
180 void tfm_ns_mailbox_hal_exit_critical(void);
181 
182 /**
183  * \brief Enter critical section of NSPE mailbox in IRQ handler.
184  *
185  * \note The implementation depends on platform specific hardware and use case.
186  */
187 void tfm_ns_mailbox_hal_enter_critical_isr(void);
188 
189 /**
190  * \brief Enter critical section of NSPE mailbox in IRQ handler
191  *
192  * \note The implementation depends on platform specific hardware and use case.
193  */
194 void tfm_ns_mailbox_hal_exit_critical_isr(void);
195 
196 #ifdef TFM_MULTI_CORE_MULTI_CLIENT_CALL
197 /**
198  * \brief Performs platform and NS OS specific waiting mechanism to wait for
199  * the reply of the specified mailbox message to be returned from SPE.
200  *
201  * \note This function is implemented by platform and NS OS specific waiting
202  * mechanism accroding to use scenario.
203  *
204  * \param[in] handle The handle of mailbox message.
205  */
206 void tfm_ns_mailbox_hal_wait_reply(mailbox_msg_handle_t handle);
207 #endif
208 
209 #ifdef TFM_MULTI_CORE_TEST
210 /**
211  * \brief Initialize the statistics module in TF-M NSPE mailbox.
212  *
213  * \note This function is only available when multi-core tests are enabled.
214  */
215 void tfm_ns_mailbox_tx_stats_init(void);
216 
217 /**
218  * \brief Calculate the average number of used NS mailbox queue slots each time
219  * NS task requires a queue slot to submit mailbox message, which is
220  * recorded in NS mailbox statisitics module.
221  *
222  * \note This function is only available when multi-core tests are enabled.
223  *
224  * \param[in] stats_res The buffer to be written with
225  * \ref ns_mailbox_stats_res_t.
226  *
227  * \return Return the calculation result.
228  */
229 void tfm_ns_mailbox_stats_avg_slot(struct ns_mailbox_stats_res_t *stats_res);
230 #endif
231 
232 #ifdef __cplusplus
233 }
234 #endif
235 
236 #endif /* __TFM_NS_MAILBOX_H__ */
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.