aboutsummaryrefslogtreecommitdiff
path: root/interface/include/tfm_mailbox.h
blob: 71f8ae77a951cd10714ccf32a1f613ac5f42fac4 (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
/*
 * Copyright (c) 2019-2021, Arm Limited. All rights reserved.
 *
 * SPDX-License-Identifier: BSD-3-Clause
 *
 */

/*
 * This is header file of common mailbox objects shared by NSPE and SPE.
 * Please refer to tfm_ns_mailbox.h for the definitions only used in NSPE
 * mailbox library.
 * Please refer to tfm_spe_mailbox.h for the SPE specific definitions and APIs.
 */

#ifndef __TFM_MAILBOX_H__
#define __TFM_MAILBOX_H__

#include <stdbool.h>
#include <stdint.h>
#include <stddef.h>
#ifdef TFM_MULTI_CORE_MULTI_CLIENT_CALL
#include "device_cfg.h"
#endif
#include "psa/client.h"

#ifdef __cplusplus
extern "C" {
#endif

/*
 * If multiple outstanding NS PSA Client calls is enabled, multi-core platform
 * should define the number of mailbox queue slots NUM_MAILBOX_QUEUE_SLOT in
 * platform device_cfg.h.
 * Otherwise, NUM_MAILBOX_QUEUE_SLOT is defined as 1.
 */
#ifdef TFM_MULTI_CORE_MULTI_CLIENT_CALL
#ifndef NUM_MAILBOX_QUEUE_SLOT
#error "Error: Platform doesn't define NUM_MAILBOX_QUEUE_SLOT for mailbox queue"
#endif

#if (NUM_MAILBOX_QUEUE_SLOT < 2)
#error "Error: Invalid NUM_MAILBOX_QUEUE_SLOT. The value should be more than 1"
#endif

/*
 * The number of slots should be no more than the number of bits in
 * mailbox_queue_status_t.
 * Here the value is hardcoded. A better way is to define a sizeof() to
 * calculate the bits in mailbox_queue_status_t and dump it with pragma message.
 */
#if (NUM_MAILBOX_QUEUE_SLOT > 32)
#error "Error: Invalid NUM_MAILBOX_QUEUE_SLOT. The value should be no more than 32"
#endif
#else /* TFM_MULTI_CORE_MULTI_CLIENT_CALL */
/* Force the number of mailbox queue slots as 1. */
#undef NUM_MAILBOX_QUEUE_SLOT
#define NUM_MAILBOX_QUEUE_SLOT              (1)
#endif /* TFM_MULTI_CORE_MULTI_CLIENT_CALL */

/* PSA client call type value */
#define MAILBOX_PSA_FRAMEWORK_VERSION       (0x1)
#define MAILBOX_PSA_VERSION                 (0x2)
#define MAILBOX_PSA_CONNECT                 (0x3)
#define MAILBOX_PSA_CALL                    (0x4)
#define MAILBOX_PSA_CLOSE                   (0x5)

/* Return code of mailbox APIs */
#define MAILBOX_SUCCESS                     (0)
#define MAILBOX_QUEUE_FULL                  (INT32_MIN + 1)
#define MAILBOX_INVAL_PARAMS                (INT32_MIN + 2)
#define MAILBOX_NO_PERMS                    (INT32_MIN + 3)
#define MAILBOX_NO_PEND_EVENT               (INT32_MIN + 4)
#define MAILBOX_CHAN_BUSY                   (INT32_MIN + 5)
#define MAILBOX_CALLBACK_REG_ERROR          (INT32_MIN + 6)
#define MAILBOX_INIT_ERROR                  (INT32_MIN + 7)
#define MAILBOX_GENERIC_ERROR               (INT32_MIN + 8)

/*
 * This structure holds the parameters used in a PSA client call.
 */
struct psa_client_params_t {
    union {
        struct {
            uint32_t        sid;
        } psa_version_params;

        struct {
            uint32_t        sid;
            uint32_t        version;
        } psa_connect_params;

        struct {
            psa_handle_t    handle;
            int32_t         type;
            const psa_invec *in_vec;
            size_t          in_len;
            psa_outvec      *out_vec;
            size_t          out_len;
        } psa_call_params;

        struct {
            psa_handle_t    handle;
        } psa_close_params;
    };
};

/* Mailbox message passed from NSPE to SPE to deliver a PSA client call */
struct mailbox_msg_t {
    uint32_t                    call_type; /* PSA client call type */
    struct psa_client_params_t  params;    /* Contain parameters used in PSA
                                            * client call
                                            */

    int32_t                     client_id; /* Optional client ID of the
                                            * non-secure caller.
                                            * It is required to identify the
                                            * non-secure task when NSPE OS
                                            * enforces non-secure task isolation
                                            */
};

/* A handle to a mailbox message in use */
typedef int32_t    mailbox_msg_handle_t;

#define MAILBOX_MSG_NULL_HANDLE          ((mailbox_msg_handle_t)0)

/*
 * Mailbox reply structure in non-secure memory
 * to hold the PSA client call return result from SPE
 */
struct mailbox_reply_t {
    int32_t return_val;
};

/* A single slot structure in NSPE mailbox queue */
struct ns_mailbox_slot_t {
    struct mailbox_msg_t   msg;
    struct mailbox_reply_t reply;
    const void             *owner;          /* Handle of the owner task of this
                                             * slot
                                             */
    bool                   is_woken;        /* Indicate that owner task has been
                                             * or should be woken up, after the
                                             * replied is received.
                                             */
};

typedef uint32_t   mailbox_queue_status_t;

/* NSPE mailbox queue */
struct ns_mailbox_queue_t {
    mailbox_queue_status_t   empty_slots;       /* Bitmask of empty slots */
    mailbox_queue_status_t   pend_slots;        /* Bitmask of slots pending
                                                 * for SPE handling
                                                 */
    mailbox_queue_status_t   replied_slots;     /* Bitmask of active slots
                                                 * containing PSA client call
                                                 * return result
                                                 */

    struct ns_mailbox_slot_t queue[NUM_MAILBOX_QUEUE_SLOT];

#ifdef TFM_MULTI_CORE_TEST
    uint32_t                 nr_tx;             /* The total number of
                                                 * submission of NS PSA Client
                                                 * calls from NS task via
                                                 * mailbox.
                                                 */
    uint32_t                 nr_used_slots;     /* The total number of used
                                                 * mailbox queue slots each time
                                                 * NS thread requests a mailbox
                                                 * queue slot.
                                                 */
#endif
};

#ifdef __cplusplus
}
#endif

#endif /* __TFM_MAILBOX_H__ */