blob: c8c00245ae2298b6ab09ea6427600582ec02bc75 [file] [log] [blame]
Valerio Setti4f4ade92024-05-03 17:28:04 +02001/* PSA Firmware Framework service header for psasim. */
2
3/*
4 * Copyright The Mbed TLS Contributors
5 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
6 */
7
8#ifndef __PSA_SERVICE_H__
9#define __PSA_SERVICE_H__
10
11#ifdef __cplusplus
12extern "C" {
13#endif
14#include <stdlib.h>
15#include <stdint.h>
16#include <stddef.h>
17
18#include "psa/common.h"
19
20/********************** PSA Secure Partition Macros and Types ****************/
21
22/* PSA wait timeouts */
23#define PSA_POLL (0x00000000u)
24#define PSA_BLOCK (0x80000000u)
25
26/* A mask value that includes all Secure Partition signals */
27#define PSA_WAIT_ANY (~0u)
28
29/* Doorbell signal */
30#define PSA_DOORBELL (0x00000008u)
31
32/* PSA message types */
33#define PSA_IPC_CONNECT (-1)
34#define PSA_IPC_DISCONNECT (-2)
35
36/* Return code from psa_get() */
37#define PSA_ERR_NOMSG (INT32_MIN + 3)
38
39/* Store a set of one or more Secure Partition signals */
40typedef uint32_t psa_signal_t;
41
42/**
43 * Describe a message received by an RoT Service after calling \ref psa_get().
44 */
45typedef struct psa_msg_t {
46 uint32_t type; /* One of the following values:
47 * \ref PSA_IPC_CONNECT
48 * \ref PSA_IPC_CALL
49 * \ref PSA_IPC_DISCONNECT
50 */
51 psa_handle_t handle; /* A reference generated by the SPM to the
52 * message returned by psa_get().
53 */
54 int32_t client_id; /* Partition ID of the sender of the message */
55 void *rhandle; /* Be useful for binding a connection to some
56 * application-specific data or function
57 * pointer within the RoT Service
58 * implementation.
59 */
60 size_t in_size[PSA_MAX_IOVEC]; /* Provide the size of each client input
61 * vector in bytes.
62 */
63 size_t out_size[PSA_MAX_IOVEC];/* Provide the size of each client output
64 * vector in bytes.
65 */
66} psa_msg_t;
67
68/************************* PSA Secure Partition API **************************/
69
70/**
71 * \brief Return the Secure Partition interrupt signals that have been asserted
72 * from a subset of signals provided by the caller.
73 *
74 * \param[in] signal_mask A set of signals to query. Signals that are not
75 * in this set will be ignored.
76 * \param[in] timeout Specify either blocking \ref PSA_BLOCK or
77 * polling \ref PSA_POLL operation.
78 *
79 * \retval >0 At least one signal is asserted.
80 * \retval 0 No signals are asserted. This is only seen when
81 * a polling timeout is used.
82 */
83psa_signal_t psa_wait(psa_signal_t signal_mask, uint32_t timeout);
84
85/**
86 * \brief Retrieve the message which corresponds to a given RoT Service signal
87 * and remove the message from the RoT Service queue.
88 *
89 * \param[in] signal The signal value for an asserted RoT Service.
90 * \param[out] msg Pointer to \ref psa_msg_t object for receiving
91 * the message.
92 *
93 * \retval PSA_SUCCESS Success, *msg will contain the delivered
94 * message.
95 * \retval PSA_ERR_NOMSG Message could not be delivered.
96 * \retval "Does not return" The call is invalid because one or more of the
97 * following are true:
98 * \arg signal has more than a single bit set.
99 * \arg signal does not correspond to an RoT Service.
100 * \arg The RoT Service signal is not currently
101 * asserted.
102 * \arg The msg pointer provided is not a valid memory
103 * reference.
104 */
105psa_status_t psa_get(psa_signal_t signal, psa_msg_t *msg);
106
107/**
108 * \brief Associate some RoT Service private data with a client connection.
109 *
110 * \param[in] msg_handle Handle for the client's message.
111 * \param[in] rhandle Reverse handle allocated by the RoT Service.
112 *
113 * \retval void Success, rhandle will be provided with all
114 * subsequent messages delivered on this
115 * connection.
116 * \retval "Does not return" msg_handle is invalid.
117 */
118void psa_set_rhandle(psa_handle_t msg_handle, void *rhandle);
119
120/**
121 * \brief Read a message parameter or part of a message parameter from a client
122 * input vector.
123 *
124 * \param[in] msg_handle Handle for the client's message.
125 * \param[in] invec_idx Index of the input vector to read from. Must be
126 * less than \ref PSA_MAX_IOVEC.
127 * \param[out] buffer Buffer in the Secure Partition to copy the
128 * requested data to.
129 * \param[in] num_bytes Maximum number of bytes to be read from the
130 * client input vector.
131 *
132 * \retval >0 Number of bytes copied.
133 * \retval 0 There was no remaining data in this input
134 * vector.
135 * \retval "Does not return" The call is invalid, one or more of the
136 * following are true:
137 * \arg msg_handle is invalid.
138 * \arg msg_handle does not refer to a
139 * \ref PSA_IPC_CALL message.
140 * \arg invec_idx is equal to or greater than
141 * \ref PSA_MAX_IOVEC.
142 * \arg the memory reference for buffer is invalid or
143 * not writable.
144 */
145size_t psa_read(psa_handle_t msg_handle, uint32_t invec_idx,
146 void *buffer, size_t num_bytes);
147
148/**
149 * \brief Skip over part of a client input vector.
150 *
151 * \param[in] msg_handle Handle for the client's message.
152 * \param[in] invec_idx Index of input vector to skip from. Must be
153 * less than \ref PSA_MAX_IOVEC.
154 * \param[in] num_bytes Maximum number of bytes to skip in the client
155 * input vector.
156 *
157 * \retval >0 Number of bytes skipped.
158 * \retval 0 There was no remaining data in this input
159 * vector.
160 * \retval "Does not return" The call is invalid, one or more of the
161 * following are true:
162 * \arg msg_handle is invalid.
163 * \arg msg_handle does not refer to a
164 * \ref PSA_IPC_CALL message.
165 * \arg invec_idx is equal to or greater than
166 * \ref PSA_MAX_IOVEC.
167 */
168size_t psa_skip(psa_handle_t msg_handle, uint32_t invec_idx, size_t num_bytes);
169
170/**
171 * \brief Write a message response to a client output vector.
172 *
173 * \param[in] msg_handle Handle for the client's message.
174 * \param[out] outvec_idx Index of output vector in message to write to.
175 * Must be less than \ref PSA_MAX_IOVEC.
176 * \param[in] buffer Buffer with the data to write.
177 * \param[in] num_bytes Number of bytes to write to the client output
178 * vector.
179 *
180 * \retval void Success
181 * \retval "Does not return" The call is invalid, one or more of the
182 * following are true:
183 * \arg msg_handle is invalid.
184 * \arg msg_handle does not refer to a
185 * \ref PSA_IPC_CALL message.
186 * \arg outvec_idx is equal to or greater than
187 * \ref PSA_MAX_IOVEC.
188 * \arg The memory reference for buffer is invalid.
189 * \arg The call attempts to write data past the end
190 * of the client output vector.
191 */
192void psa_write(psa_handle_t msg_handle, uint32_t outvec_idx,
193 const void *buffer, size_t num_bytes);
194
195/**
196 * \brief Complete handling of a specific message and unblock the client.
197 *
198 * \param[in] msg_handle Handle for the client's message.
199 * \param[in] status Message result value to be reported to the
200 * client.
201 *
202 * \retval void Success.
203 * \retval "Does not return" The call is invalid, one or more of the
204 * following are true:
205 * \arg msg_handle is invalid.
206 * \arg An invalid status code is specified for the
207 * type of message.
208 */
209void psa_reply(psa_handle_t msg_handle, psa_status_t status);
210
211/**
212 * \brief Send a PSA_DOORBELL signal to a specific Secure Partition.
213 *
214 * \param[in] partition_id Secure Partition ID of the target partition.
215 *
216 * \retval void Success.
217 * \retval "Does not return" partition_id does not correspond to a Secure
218 * Partition.
219 */
220void psa_notify(int32_t partition_id);
221
222/**
223 * \brief Clear the PSA_DOORBELL signal.
224 *
225 * \retval void Success.
226 * \retval "Does not return" The Secure Partition's doorbell signal is not
227 * currently asserted.
228 */
229void psa_clear(void);
230
231/**
232 * \brief Inform the SPM that an interrupt has been handled (end of interrupt).
233 *
234 * \param[in] irq_signal The interrupt signal that has been processed.
235 *
236 * \retval void Success.
237 * \retval "Does not return" The call is invalid, one or more of the
238 * following are true:
239 * \arg irq_signal is not an interrupt signal.
240 * \arg irq_signal indicates more than one signal.
241 * \arg irq_signal is not currently asserted.
242 */
243void psa_eoi(psa_signal_t irq_signal);
244
245#define psa_panic(X) abort();
246
247#ifdef __cplusplus
248}
249#endif
250
251#endif /* __PSA_SERVICE_H__ */