Keil Studio Cloud
Mistake on this page?
Report an issue in GitHub or email us
TARGET_TFM_LATEST/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 /**
88  * \brief Get the handle of the current non-secure task executing mailbox
89  * functionalities
90  *
91  * \note This function should be implemented according to platform, NS OS
92  * and actual use scenario.
93  * This function can be ignored or return NULL if sleep/wake-up mechanism
94  * is not required in PSA Client API implementation.
95  *
96  * \return Return the handle of task.
97  */
98 const void *tfm_ns_mailbox_get_task_handle(void);
99 
100 /**
101  * \brief Fetch the handle to the first replied mailbox message in the NSPE
102  * mailbox queue.
103  * This function is intended to be called inside platform specific
104  * notification IRQ handler.
105  *
106  * \note The replied status of the fetched mailbox message will be cleaned after
107  * the message is fetched. When this function is called again, it fetches
108  * the next replied mailbox message from the NSPE mailbox queue.
109  *
110  * \return Return the handle to the first replied mailbox message in the
111  * queue.
112  * Return \ref MAILBOX_MSG_NULL_HANDLE if no mailbox message is replied.
113  */
114 mailbox_msg_handle_t tfm_ns_mailbox_fetch_reply_msg_isr(void);
115 
116 /**
117  * \brief Return the handle of owner task of a mailbox message according to the
118  * \ref mailbox_msg_handle_t
119  *
120  * \param[in] handle The handle of mailbox message.
121  *
122  * \return Return the handle value of the owner task.
123  */
124 const void *tfm_ns_mailbox_get_msg_owner(mailbox_msg_handle_t handle);
125 
126 #ifdef TFM_MULTI_CORE_MULTI_CLIENT_CALL
127 /**
128  * \brief Wait for the reply returned from SPE to the mailbox message specified
129  * by handle
130  *
131  * \param[in] handle The handle of mailbox message.
132  *
133  * \retval MAILBOX_SUCCESS Return from waiting successfully.
134  * \retval Other return code Failed to wait with an error code.
135  */
136 int32_t tfm_ns_mailbox_wait_reply(mailbox_msg_handle_t handle);
137 #endif
138 
139 /**
140  * \brief Platform specific NSPE mailbox initialization.
141  * Invoked by \ref tfm_ns_mailbox_init().
142  *
143  * \param[in] queue The base address of NSPE mailbox queue to be
144  * initialized.
145  *
146  * \retval MAILBOX_SUCCESS Operation succeeded.
147  * \retval Other return code Operation failed with an error code.
148  */
149 int32_t tfm_ns_mailbox_hal_init(struct ns_mailbox_queue_t *queue);
150 
151 /**
152  * \brief Notify SPE to deal with the PSA client call sent via mailbox
153  *
154  * \note The implementation depends on platform specific hardware and use case.
155  *
156  * \retval MAILBOX_SUCCESS Operation succeeded.
157  * \retval Other return code Operation failed with an error code.
158  */
159 int32_t tfm_ns_mailbox_hal_notify_peer(void);
160 
161 /**
162  * \brief Enter critical section of NSPE mailbox.
163  *
164  * \note The implementation depends on platform specific hardware and use case.
165  */
166 void tfm_ns_mailbox_hal_enter_critical(void);
167 
168 /**
169  * \brief Exit 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_exit_critical(void);
174 
175 /**
176  * \brief Enter critical section of NSPE mailbox in IRQ handler.
177  *
178  * \note The implementation depends on platform specific hardware and use case.
179  */
180 void tfm_ns_mailbox_hal_enter_critical_isr(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_exit_critical_isr(void);
188 
189 #ifdef TFM_MULTI_CORE_MULTI_CLIENT_CALL
190 /**
191  * \brief Performs platform and NS OS specific waiting mechanism to wait for
192  * the reply of the specified mailbox message to be returned from SPE.
193  *
194  * \note This function is implemented by platform and NS OS specific waiting
195  * mechanism accroding to use scenario.
196  *
197  * \param[in] handle The handle of mailbox message.
198  */
199 void tfm_ns_mailbox_hal_wait_reply(mailbox_msg_handle_t handle);
200 #endif
201 
202 #ifdef TFM_MULTI_CORE_TEST
203 /**
204  * \brief Initialize the statistics module in TF-M NSPE mailbox.
205  *
206  * \note This function is only available when multi-core tests are enabled.
207  */
208 void tfm_ns_mailbox_tx_stats_init(void);
209 
210 /**
211  * \brief Calculate the average number of used NS mailbox queue slots each time
212  * NS task requires a queue slot to submit mailbox message, which is
213  * recorded in NS mailbox statisitics module.
214  *
215  * \note This function is only available when multi-core tests are enabled.
216  *
217  * \param[in] stats_res The buffer to be written with
218  * \ref ns_mailbox_stats_res_t.
219  *
220  * \return Return the calculation result.
221  */
222 void tfm_ns_mailbox_stats_avg_slot(struct ns_mailbox_stats_res_t *stats_res);
223 #endif
224 
225 #ifdef __cplusplus
226 }
227 #endif
228 
229 #endif /* __TFM_NS_MAILBOX_H__ */
psa_client_params_t
Definition: TARGET_TFM_LATEST/include/tfm_mailbox.h:80
ns_mailbox_queue_t
Definition: TARGET_TFM_LATEST/include/tfm_mailbox.h:150
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.