TF-M Reference Manual  1.2.0
TrustedFirmware-M
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
tfm_mailbox.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2019-2020, Arm Limited. All rights reserved.
3  *
4  * SPDX-License-Identifier: BSD-3-Clause
5  *
6  */
7 
8 /*
9  * This is header file of common mailbox objects shared by NSPE and SPE.
10  * Please refer to tfm_ns_mailbox.h for the definitions only used in NSPE
11  * mailbox library.
12  * Please refer to tfm_spe_mailbox.h for the SPE specific definitions and APIs.
13  */
14 
15 #ifndef __TFM_MAILBOX_H__
16 #define __TFM_MAILBOX_H__
17 
18 #include <stdbool.h>
19 #include <stdint.h>
20 #include <stddef.h>
21 #ifdef TFM_MULTI_CORE_MULTI_CLIENT_CALL
22 #include "device_cfg.h"
23 #endif
24 #include "psa/client.h"
25 
26 #ifdef __cplusplus
27 extern "C" {
28 #endif
29 
30 /*
31  * If multiple outstanding NS PSA Client calls is enabled, multi-core platform
32  * should define the number of mailbox queue slots NUM_MAILBOX_QUEUE_SLOT in
33  * platform device_cfg.h.
34  * Otherwise, NUM_MAILBOX_QUEUE_SLOT is defined as 1.
35  */
36 #ifdef TFM_MULTI_CORE_MULTI_CLIENT_CALL
37 #ifndef NUM_MAILBOX_QUEUE_SLOT
38 #error "Error: Platform doesn't define NUM_MAILBOX_QUEUE_SLOT for mailbox queue"
39 #endif
40 
41 #if (NUM_MAILBOX_QUEUE_SLOT < 2)
42 #error "Error: Invalid NUM_MAILBOX_QUEUE_SLOT. The value should be more than 1"
43 #endif
44 
45 /*
46  * The number of slots should be no more than the number of bits in
47  * mailbox_queue_status_t.
48  * Here the value is hardcoded. A better way is to define a sizeof() to
49  * calculate the bits in mailbox_queue_status_t and dump it with pragma message.
50  */
51 #if (NUM_MAILBOX_QUEUE_SLOT > 32)
52 #error "Error: Invalid NUM_MAILBOX_QUEUE_SLOT. The value should be no more than 32"
53 #endif
54 #else /* TFM_MULTI_CORE_MULTI_CLIENT_CALL */
55 /* Force the number of mailbox queue slots as 1. */
56 #undef NUM_MAILBOX_QUEUE_SLOT
57 #define NUM_MAILBOX_QUEUE_SLOT (1)
58 #endif /* TFM_MULTI_CORE_MULTI_CLIENT_CALL */
59 
60 /* PSA client call type value */
61 #define MAILBOX_PSA_FRAMEWORK_VERSION (0x1)
62 #define MAILBOX_PSA_VERSION (0x2)
63 #define MAILBOX_PSA_CONNECT (0x3)
64 #define MAILBOX_PSA_CALL (0x4)
65 #define MAILBOX_PSA_CLOSE (0x5)
66 
67 /* Return code of mailbox APIs */
68 #define MAILBOX_SUCCESS (0)
69 #define MAILBOX_QUEUE_FULL (INT32_MIN + 1)
70 #define MAILBOX_INVAL_PARAMS (INT32_MIN + 2)
71 #define MAILBOX_NO_PERMS (INT32_MIN + 3)
72 #define MAILBOX_NO_PEND_EVENT (INT32_MIN + 4)
73 #define MAILBOX_CHAN_BUSY (INT32_MIN + 5)
74 #define MAILBOX_CALLBACK_REG_ERROR (INT32_MIN + 6)
75 #define MAILBOX_INIT_ERROR (INT32_MIN + 7)
76 
77 /*
78  * This structure holds the parameters used in a PSA client call.
79  */
81  union {
82  struct {
83  uint32_t sid;
85 
86  struct {
87  uint32_t sid;
88  uint32_t version;
90 
91  struct {
93  int32_t type;
94  const psa_invec *in_vec;
95  size_t in_len;
97  size_t out_len;
99 
100  struct {
103  };
104 };
105 
106 /* Mailbox message passed from NSPE to SPE to deliver a PSA client call */
108  uint32_t call_type; /* PSA client call type */
109  struct psa_client_params_t params; /* Contain parameters used in PSA
110  * client call
111  */
112 
113  int32_t client_id; /* Optional client ID of the
114  * non-secure caller.
115  * It is required to identify the
116  * non-secure task when NSPE OS
117  * enforces non-secure task isolation
118  */
119 };
120 
121 /* A handle to a mailbox message in use */
122 typedef int32_t mailbox_msg_handle_t;
123 
124 #define MAILBOX_MSG_NULL_HANDLE ((mailbox_msg_handle_t)0)
125 
126 /*
127  * Mailbox reply structure in non-secure memory
128  * to hold the PSA client call return result from SPE
129  */
131  int32_t return_val;
132 };
133 
134 /* A single slot structure in NSPE mailbox queue */
138  const void *owner; /* Handle of the owner task of this
139  * slot
140  */
141  bool is_woken; /* Indicate that owner task has been
142  * or should be woken up, after the
143  * replied is received.
144  */
145 };
146 
147 typedef uint32_t mailbox_queue_status_t;
148 
149 /* NSPE mailbox queue */
151  mailbox_queue_status_t empty_slots; /* Bitmask of empty slots */
152  mailbox_queue_status_t pend_slots; /* Bitmask of slots pending
153  * for SPE handling
154  */
155  mailbox_queue_status_t replied_slots; /* Bitmask of active slots
156  * containing PSA client call
157  * return result
158  */
159 
161 
162 #ifdef TFM_MULTI_CORE_TEST
163  uint32_t nr_tx; /* The total number of
164  * submission of NS PSA Client
165  * calls from NS task via
166  * mailbox.
167  */
168  uint32_t nr_used_slots; /* The total number of used
169  * mailbox queue slots each time
170  * NS thread requests a mailbox
171  * queue slot.
172  */
173 #endif
174 };
175 
176 #ifdef __cplusplus
177 }
178 #endif
179 
180 #endif /* __TFM_MAILBOX_H__ */
struct mailbox_reply_t reply
Definition: tfm_mailbox.h:137
psa_handle_t handle
Definition: tfm_mailbox.h:92
psa_outvec * out_vec
Definition: tfm_mailbox.h:96
struct psa_client_params_t::@2::@7 psa_close_params
mailbox_queue_status_t replied_slots
Definition: tfm_mailbox.h:155
struct psa_client_params_t::@2::@6 psa_call_params
struct psa_client_params_t params
Definition: tfm_mailbox.h:109
mailbox_queue_status_t empty_slots
Definition: tfm_mailbox.h:151
uint32_t call_type
Definition: tfm_mailbox.h:108
mailbox_queue_status_t pend_slots
Definition: tfm_mailbox.h:152
int32_t client_id
Definition: tfm_mailbox.h:113
struct ns_mailbox_slot_t queue[(1)]
Definition: tfm_mailbox.h:160
#define NUM_MAILBOX_QUEUE_SLOT
Definition: tfm_mailbox.h:57
uint32_t mailbox_queue_status_t
Definition: tfm_mailbox.h:147
int32_t mailbox_msg_handle_t
Definition: tfm_mailbox.h:122
const psa_invec * in_vec
Definition: tfm_mailbox.h:94
int32_t return_val
Definition: tfm_mailbox.h:131
int32_t psa_handle_t
Definition: client.h:61
struct mailbox_msg_t msg
Definition: tfm_mailbox.h:136
struct psa_client_params_t::@2::@5 psa_connect_params
const void * owner
Definition: tfm_mailbox.h:138
struct psa_client_params_t::@2::@4 psa_version_params