aboutsummaryrefslogtreecommitdiff
path: root/interface/include/tfm_ns_mailbox.h
blob: 6b64443fa0aec47cd20e4a17793f62a563d5fb08 (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
237
238
239
240
241
242
243
244
245
246
247
248
249
/*
 * Copyright (c) 2019-2021, 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 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);

/**
 * \brief Send PSA client call to SPE via mailbox. Wait and fetch PSA client
 *        call result.
 *
 * \param[in] call_type         PSA client call type
 * \param[in] params            Parameters 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.
 * \param[out] reply            The buffer written with PSA client call result.
 *
 * \retval MAILBOX_SUCCESS      The PSA client call is completed successfully.
 * \retval Other return code    Operation failed with an error code.
 */
int32_t tfm_ns_mailbox_client_call(uint32_t call_type,
                                   const struct psa_client_params_t *params,
                                   int32_t client_id,
                                   int32_t *reply);

/**
 * \brief Go through mailbox messages already replied by SPE mailbox and
 *        wake up the owner tasks of replied mailbox messages.
 *        This function is intended to be called inside platform specific
 *        notification IRQ handler.
 *
 * \return MAILBOX_SUCCESS       The tasks of replied mailbox messages
 *                               were found and wake-up signals were sent.
 * \return MAILBOX_NO_PEND_EVENT No replied mailbox message is found.
 * \return Other return code     Failed with an error code
 */
int32_t tfm_ns_mailbox_wake_reply_owner_isr(void);

/**
 * \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 FORWARD_PROT_MSG
static inline int32_t tfm_ns_mailbox_os_lock_init(void)
{
    return MAILBOX_SUCCESS;
}

static inline uint32_t tfm_ns_mailbox_os_lock_acquire(void)
{
    return MAILBOX_SUCCESS;
}

static inline uint32_t tfm_ns_mailbox_os_lock_release(void)
{
    return MAILBOX_SUCCESS;
}
#else /* FORWARD_PROT_MSG */
/**
 * \brief Initialize the multi-core lock for synchronizing PSA client call(s)
 *        The actual implementation depends on the non-secure use scenario.
 *
 * \return \ref MAILBOX_SUCCESS on success
 * \return \ref MAILBOX_GENERIC_ERROR on error
 */
int32_t tfm_ns_mailbox_os_lock_init(void);

/**
 * \brief Acquire the multi-core lock for synchronizing PSA client call(s)
 *        The actual implementation depends on the non-secure use scenario.
 *
 * \return \ref MAILBOX_SUCCESS on success
 * \return \ref MAILBOX_GENERIC_ERROR on error
 */
int32_t tfm_ns_mailbox_os_lock_acquire(void);

/**
 * \brief Release the multi-core lock for synchronizing PSA client call(s)
 *        The actual implementation depends on the non-secure use scenario.
 *
 * \return \ref MAILBOX_SUCCESS on success
 * \return \ref MAILBOX_GENERIC_ERROR on error
 */
int32_t tfm_ns_mailbox_os_lock_release(void);
#endif /* FORWARD_PROT_MSG */

#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 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_os_get_task_handle(void);

/**
 * \brief Performs use scenario and NS OS specific waiting mechanism to wait for
 *        the reply to be returned from SPE.
 *
 * \note This function is implemented by NS OS specific waiting mechanism
 *       according to use scenario.
 */
void tfm_ns_mailbox_os_wait_reply(void);

/*
 * \brief Performs use scenario and NS OS specific mechanism in a mailbox IRQ
 *        handler, to wake up a sleeping task which is waiting for its mailbox
 *        message reply.
 *
 * \note The underlying NS OS specific function called inside this function
 *       should be able to work in an IRQ handler.
 *
 * \note This function is implemented by NS OS specific waiting
 *       mechanism according to use scenario.
 *
 * \param[in] task_handle       The handle to the task to be woken up.
 */
void tfm_ns_mailbox_os_wake_task_isr(const void *task_handle);
#else /* TFM_MULTI_CORE_MULTI_CLIENT_CALL */
#define tfm_ns_mailbox_os_wait_reply()         do {} while (0)

static inline const void *tfm_ns_mailbox_os_get_task_handle(void)
{
    return NULL;
}

#define tfm_ns_mailbox_os_wake_task_isr(task)  do {} while (0)
#endif /* TFM_MULTI_CORE_MULTI_CLIENT_CALL */

#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__ */