1 /*
2  * Copyright (c) 2019-2021, Arm Limited. All rights reserved.
3  * Copyright (c) 2022 Cypress Semiconductor Corporation. All rights reserved.
4  *
5  * SPDX-License-Identifier: BSD-3-Clause
6  *
7  */
8 
9 /*
10  * This is header file of common mailbox objects shared by NSPE and SPE.
11  * Please refer to tfm_ns_mailbox.h for the definitions only used in NSPE
12  * mailbox library.
13  * Please refer to tfm_spe_mailbox.h for the SPE specific definitions and APIs.
14  */
15 
16 #ifndef __TFM_MAILBOX_H__
17 #define __TFM_MAILBOX_H__
18 
19 #include <stdbool.h>
20 #include <stdint.h>
21 #include <stddef.h>
22 
23 #include "psa/client.h"
24 #include "tfm_mailbox_config.h"
25 
26 #ifdef __cplusplus
27 extern "C" {
28 #endif
29 
30 /* PSA client call type value */
31 #define MAILBOX_PSA_FRAMEWORK_VERSION       (0x1)
32 #define MAILBOX_PSA_VERSION                 (0x2)
33 #define MAILBOX_PSA_CONNECT                 (0x3)
34 #define MAILBOX_PSA_CALL                    (0x4)
35 #define MAILBOX_PSA_CLOSE                   (0x5)
36 
37 /* Return code of mailbox APIs */
38 #define MAILBOX_SUCCESS                     (0)
39 #define MAILBOX_QUEUE_FULL                  (INT32_MIN + 1)
40 #define MAILBOX_INVAL_PARAMS                (INT32_MIN + 2)
41 #define MAILBOX_NO_PERMS                    (INT32_MIN + 3)
42 #define MAILBOX_NO_PEND_EVENT               (INT32_MIN + 4)
43 #define MAILBOX_CHAN_BUSY                   (INT32_MIN + 5)
44 #define MAILBOX_CALLBACK_REG_ERROR          (INT32_MIN + 6)
45 #define MAILBOX_INIT_ERROR                  (INT32_MIN + 7)
46 #define MAILBOX_GENERIC_ERROR               (INT32_MIN + 8)
47 
48 /*
49  * This structure holds the parameters used in a PSA client call.
50  */
51 struct psa_client_params_t {
52     union {
53         struct {
54             uint32_t        sid;
55         } psa_version_params;
56 
57         struct {
58             uint32_t        sid;
59             uint32_t        version;
60         } psa_connect_params;
61 
62         struct {
63             psa_handle_t    handle;
64             int32_t         type;
65             const psa_invec *in_vec;
66             size_t          in_len;
67             psa_outvec      *out_vec;
68             size_t          out_len;
69         } psa_call_params;
70 
71         struct {
72             psa_handle_t    handle;
73         } psa_close_params;
74     };
75 };
76 
77 /* Mailbox message passed from NSPE to SPE to deliver a PSA client call */
78 struct mailbox_msg_t {
79     uint32_t                    call_type; /* PSA client call type */
80     struct psa_client_params_t  params;    /* Contain parameters used in PSA
81                                             * client call
82                                             */
83 
84     int32_t                     client_id; /* Optional client ID of the
85                                             * non-secure caller.
86                                             * It is required to identify the
87                                             * non-secure task when NSPE OS
88                                             * enforces non-secure task isolation
89                                             */
90 };
91 
92 /*
93  * Mailbox reply structure in non-secure memory
94  * to hold the PSA client call return result from SPE
95  */
96 struct mailbox_reply_t {
97     int32_t    return_val;
98     const void *owner;                      /* Handle of owner task. */
99     int32_t    *reply;                      /* Address of reply value belonging
100                                              * to owner task.
101                                              */
102 #ifdef TFM_MULTI_CORE_NS_OS_MAILBOX_THREAD
103     uint8_t    *woken_flag;                 /* Indicate that owner task has been
104                                              * or should be woken up, after the
105                                              * reply is received.
106                                              */
107 #else
108     bool        is_woken;                   /* Indicate that owner task has been
109                                              * or should be woken up, after the
110                                              * reply is received.
111                                              */
112 #endif
113 };
114 
115 /* A single slot structure in NSPE mailbox queue */
116 struct ns_mailbox_slot_t {
117     struct mailbox_msg_t   msg;
118     struct mailbox_reply_t reply;
119 };
120 
121 typedef uint32_t   mailbox_queue_status_t;
122 
123 /* NSPE mailbox queue */
124 struct ns_mailbox_queue_t {
125     mailbox_queue_status_t   empty_slots;       /* Bitmask of empty slots */
126     mailbox_queue_status_t   pend_slots;        /* Bitmask of slots pending
127                                                  * for SPE handling
128                                                  */
129     mailbox_queue_status_t   replied_slots;     /* Bitmask of active slots
130                                                  * containing PSA client call
131                                                  * return result
132                                                  */
133 
134     struct ns_mailbox_slot_t queue[NUM_MAILBOX_QUEUE_SLOT];
135 
136 #ifdef TFM_MULTI_CORE_TEST
137     uint32_t                 nr_tx;             /* The total number of
138                                                  * submission of NS PSA Client
139                                                  * calls from NS task via
140                                                  * mailbox.
141                                                  */
142     uint32_t                 nr_used_slots;     /* The total number of used
143                                                  * mailbox queue slots each time
144                                                  * NS thread requests a mailbox
145                                                  * queue slot.
146                                                  */
147 #endif
148 
149     bool                     is_full;           /* Queue if full */
150 };
151 
152 #ifdef __cplusplus
153 }
154 #endif
155 
156 #endif /* __TFM_MAILBOX_H__ */
157