aboutsummaryrefslogtreecommitdiff
path: root/interface/include/tfm_ns_mailbox.h
blob: ba902aa97740ef5e18c65329fc42f949726c1b50 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
/*
 * Copyright (c) 2019-2020, Arm Limited. All rights reserved.
 *
 * SPDX-License-Identifier: BSD-3-Clause
 *
 */

/* Data types and API definitions in NSPE mailbox library */

#ifndef __TFM_NS_MAILBOX_H__
#define __TFM_NS_MAILBOX_H__

#include <stdbool.h>
#include <stdint.h>
#include "tfm_mailbox.h"

#ifdef __cplusplus
extern "C" {
#endif

#ifdef TFM_MULTI_CORE_TEST
/**
 * \brief The structure to hold the statistics result of NSPE mailbox
 */
struct ns_mailbox_stats_res_t {
    uint8_t avg_nr_slots;               /* The value before the decimal point
                                         * in the average number of NSPE
                                         * mailbox slots in use.
                                         */
    uint8_t avg_nr_slots_tenths;        /* The first digit value after the
                                         * decimal point in the average
                                         * number of NSPE mailbox slots in use.
                                         */
};
#endif

/**
 * \brief Prepare and send PSA client request to SPE via mailbox.
 *
 * \param[in] call_type         PSA client call type
 * \param[in] params            Parmaters used for PSA client call
 * \param[in] client_id         Optional client ID of non-secure caller.
 *                              It is required to identify the non-secure caller
 *                              when NSPE OS enforces non-secure task isolation.
 *
 * \retval >= 0                 The handle to the mailbox message assigned.
 * \retval < 0                  Operation failed with an error code.
 */
mailbox_msg_handle_t tfm_ns_mailbox_tx_client_req(uint32_t call_type,
                                       const struct psa_client_params_t *params,
                                       int32_t client_id);

/**
 * \brief Fetch PSA client return result.
 *
 * \param[in] handle            The handle to the mailbox message
 * \param[out] reply            The address to be written with return result.
 *
 * \retval MAILBOX_SUCCESS      Successfully get PSA client call return result.
 * \retval Other return code    Operation failed with an error code.
 */
int32_t tfm_ns_mailbox_rx_client_reply(mailbox_msg_handle_t handle,
                                       int32_t *reply);

/**
 * \brief Check whether a specific mailbox message has been replied.
 *
 * \param[in] handle            The handle to the mailbox message
 *
 * \retval true                 The PSA client call return value is replied.
 * \retval false                The PSA client call return value is not
 *                              replied yet.
 */
bool tfm_ns_mailbox_is_msg_replied(mailbox_msg_handle_t handle);

/**
 * \brief NSPE mailbox initialization
 *
 * \param[in] queue             The base address of NSPE mailbox queue to be
 *                              initialized.
 *
 * \retval MAILBOX_SUCCESS      Operation succeeded.
 * \retval Other return code    Operation failed with an error code.
 */
int32_t tfm_ns_mailbox_init(struct ns_mailbox_queue_t *queue);

#ifdef TFM_MULTI_CORE_MULTI_CLIENT_CALL
/**
 * \brief Get the handle of the current non-secure task executing mailbox
 *        functionalities
 *
 * \note This function should be implemented according to platform, NS OS
 *       and actual use scenario.
 *       This function can be ignored or return NULL if sleep/wake-up mechanism
 *       is not required in PSA Client API implementation.
 *
 * \return Return the handle of task.
 */
const void *tfm_ns_mailbox_get_task_handle(void);
#else
static inline const void *tfm_ns_mailbox_get_task_handle(void)
{
    return NULL;
}
#endif

/**
 * \brief Fetch the handle to the first replied mailbox message in the NSPE
 *        mailbox queue.
 *        This function is intended to be called inside platform specific
 *        notification IRQ handler.
 *
 * \note The replied status of the fetched mailbox message will be cleaned after
 *       the message is fetched. When this function is called again, it fetches
 *       the next replied mailbox message from the NSPE mailbox queue.
 *
 * \return Return the handle to the first replied mailbox message in the
 *         queue.
 *         Return \ref MAILBOX_MSG_NULL_HANDLE if no mailbox message is replied.
 */
mailbox_msg_handle_t tfm_ns_mailbox_fetch_reply_msg_isr(void);

/**
 * \brief Return the handle of owner task of a mailbox message according to the
 *        \ref mailbox_msg_handle_t
 *
 * \param[in] handle            The handle of mailbox message.
 *
 * \return Return the handle value of the owner task.
 */
const void *tfm_ns_mailbox_get_msg_owner(mailbox_msg_handle_t handle);

#ifdef TFM_MULTI_CORE_MULTI_CLIENT_CALL
/**
 * \brief Wait for the reply returned from SPE to the mailbox message specified
 *        by handle
 *
 * \param[in] handle            The handle of mailbox message.
 *
 * \retval MAILBOX_SUCCESS      Return from waiting successfully.
 * \retval Other return code    Failed to wait with an error code.
 */
int32_t tfm_ns_mailbox_wait_reply(mailbox_msg_handle_t handle);
#endif

/**
 * \brief Platform specific NSPE mailbox initialization.
 *        Invoked by \ref tfm_ns_mailbox_init().
 *
 * \param[in] queue             The base address of NSPE mailbox queue to be
 *                              initialized.
 *
 * \retval MAILBOX_SUCCESS      Operation succeeded.
 * \retval Other return code    Operation failed with an error code.
 */
int32_t tfm_ns_mailbox_hal_init(struct ns_mailbox_queue_t *queue);

/**
 * \brief Notify SPE to deal with the PSA client call sent via mailbox
 *
 * \note The implementation depends on platform specific hardware and use case.
 *
 * \retval MAILBOX_SUCCESS      Operation succeeded.
 * \retval Other return code    Operation failed with an error code.
 */
int32_t tfm_ns_mailbox_hal_notify_peer(void);

/**
 * \brief Enter critical section of NSPE mailbox.
 *
 * \note The implementation depends on platform specific hardware and use case.
 */
void tfm_ns_mailbox_hal_enter_critical(void);

/**
 * \brief Exit critical section of NSPE mailbox.
 *
 * \note The implementation depends on platform specific hardware and use case.
 */
void tfm_ns_mailbox_hal_exit_critical(void);

/**
 * \brief Enter critical section of NSPE mailbox in IRQ handler.
 *
 * \note The implementation depends on platform specific hardware and use case.
 */
void tfm_ns_mailbox_hal_enter_critical_isr(void);

/**
 * \brief Enter critical section of NSPE mailbox in IRQ handler
 *
 * \note The implementation depends on platform specific hardware and use case.
 */
void tfm_ns_mailbox_hal_exit_critical_isr(void);

#ifdef TFM_MULTI_CORE_MULTI_CLIENT_CALL
/**
 * \brief Performs platform and NS OS specific waiting mechanism to wait for
 *        the reply of the specified mailbox message to be returned from SPE.
 *
 * \note This function is implemented by platform and NS OS specific waiting
 *       mechanism accroding to use scenario.
 *
 * \param[in] handle            The handle of mailbox message.
 */
void tfm_ns_mailbox_hal_wait_reply(mailbox_msg_handle_t handle);
#endif

#ifdef TFM_MULTI_CORE_TEST
/**
 * \brief Initialize the statistics module in TF-M NSPE mailbox.
 *
 * \note This function is only available when multi-core tests are enabled.
 */
void tfm_ns_mailbox_tx_stats_init(void);

/**
 * \brief Calculate the average number of used NS mailbox queue slots each time
 *        NS task requires a queue slot to submit mailbox message, which is
 *        recorded in NS mailbox statisitics module.
 *
 * \note This function is only available when multi-core tests are enabled.
 *
 * \param[in] stats_res         The buffer to be written with
 *                              \ref ns_mailbox_stats_res_t.
 *
 * \return Return the calculation result.
 */
void tfm_ns_mailbox_stats_avg_slot(struct ns_mailbox_stats_res_t *stats_res);
#endif

#ifdef __cplusplus
}
#endif

#endif /* __TFM_NS_MAILBOX_H__ */