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