1 /* 2 * SPDX-FileCopyrightText: Copyright The TrustedFirmware-M Contributors 3 * 4 * SPDX-License-Identifier: BSD-3-Clause 5 * 6 */ 7 8 #ifndef __PSA_CLIENT_H__ 9 #define __PSA_CLIENT_H__ 10 11 #include <stddef.h> 12 #include <stdint.h> 13 14 #include "psa/api_broker.h" 15 #include "psa/error.h" 16 17 #ifdef __cplusplus 18 extern "C" { 19 #endif 20 21 #ifndef IOVEC_LEN 22 #define IOVEC_LEN(arr) ((uint32_t)(sizeof(arr)/sizeof(arr[0]))) 23 #endif 24 25 /** 26 * Type definitions equivalent to size_t as defined in the RoT Service 27 * environment. 28 */ 29 typedef uint32_t rot_size_t; 30 #define ROT_SIZE_MAX UINT32_MAX 31 32 /*********************** PSA Client Macros and Types *************************/ 33 34 /** 35 * The version of the PSA Framework API that is being used to build the calling 36 * firmware. Only part of features of FF-M v1.1 have been implemented. FF-M v1.1 37 * is compatible with v1.0. 38 */ 39 #define PSA_FRAMEWORK_VERSION (0x0101u) 40 41 /** 42 * Return value from psa_version() if the requested RoT Service is not present 43 * in the system. 44 */ 45 #define PSA_VERSION_NONE (0u) 46 47 /** 48 * The zero-value null handle can be assigned to variables used in clients and 49 * RoT Services, indicating that there is no current connection or message. 50 */ 51 #define PSA_NULL_HANDLE ((psa_handle_t)0) 52 53 /** 54 * Tests whether a handle value returned by psa_connect() is valid. 55 */ 56 #define PSA_HANDLE_IS_VALID(handle) ((psa_handle_t)(handle) > 0) 57 58 /** 59 * Converts the handle value returned from a failed call psa_connect() into 60 * an error code. 61 */ 62 #define PSA_HANDLE_TO_ERROR(handle) ((psa_status_t)(handle)) 63 64 /** 65 * Maximum number of input and output vectors for a request to psa_call(). 66 */ 67 #define PSA_MAX_IOVEC (4u) 68 69 70 /** 71 * The minimum and maximum value in THIS implementation that can be passed 72 * as the type parameter in a call to psa_call(). 73 */ 74 75 #define PSA_CALL_TYPE_MIN (0) 76 #define PSA_CALL_TYPE_MAX (INT16_MAX) 77 78 /** 79 * An IPC message type that indicates a generic client request. 80 */ 81 #define PSA_IPC_CALL (0) 82 83 typedef int32_t psa_handle_t; 84 85 /** 86 * A read-only input memory region provided to an RoT Service. 87 */ 88 typedef struct psa_invec { 89 const void *base; /*!< the start address of the memory buffer */ 90 size_t len; /*!< the size in bytes */ 91 } psa_invec; 92 93 /** 94 * A writable output memory region provided to an RoT Service. 95 */ 96 typedef struct psa_outvec { 97 void *base; /*!< the start address of the memory buffer */ 98 size_t len; /*!< the size in bytes */ 99 } psa_outvec; 100 101 /*************************** PSA Client API **********************************/ 102 103 /** 104 * \brief Retrieve the version of the PSA Framework API that is implemented. 105 * 106 * \return version The version of the PSA Framework implementation 107 * that is providing the runtime services to the 108 * caller. The major and minor version are encoded 109 * as follows: 110 * \arg version[15:8] -- major version number. 111 * \arg version[7:0] -- minor version number. 112 */ 113 uint32_t psa_framework_version(void); 114 115 /** 116 * \brief Retrieve the version of an RoT Service or indicate that it is not 117 * present on this system. 118 * 119 * \param[in] sid ID of the RoT Service to query. 120 * 121 * \retval PSA_VERSION_NONE The RoT Service is not implemented, or the 122 * caller is not permitted to access the service. 123 * \retval > 0 The version of the implemented RoT Service. 124 */ 125 uint32_t psa_version(uint32_t sid); 126 127 /** 128 * \brief Connect to an RoT Service by its SID. 129 * 130 * \param[in] sid ID of the RoT Service to connect to. 131 * \param[in] version Requested version of the RoT Service. 132 * 133 * \retval > 0 A handle for the connection. 134 * \retval PSA_ERROR_CONNECTION_REFUSED The SPM or RoT Service has refused the 135 * connection. 136 * \retval PSA_ERROR_CONNECTION_BUSY The SPM or RoT Service cannot make the 137 * connection at the moment. 138 * \retval "PROGRAMMER ERROR" The call is a PROGRAMMER ERROR if one or more 139 * of the following are true: 140 * \arg The RoT Service ID is not present. 141 * \arg The RoT Service version is not supported. 142 * \arg The caller is not allowed to access the RoT 143 * service. 144 */ 145 psa_handle_t psa_connect(uint32_t sid, uint32_t version); 146 147 /** 148 * \brief Call an RoT Service on an established connection. 149 * 150 * \note FF-M 1.0 proposes 6 parameters for psa_call but the secure gateway ABI 151 * support at most 4 parameters. TF-M chooses to encode 'in_len', 152 * 'out_len', and 'type' into a 32-bit integer to improve efficiency. 153 * Compared with struct-based encoding, this method saves extra memory 154 * check and memory copy operation. The disadvantage is that the 'type' 155 * range has to be reduced into a 16-bit integer. So with this encoding, 156 * the valid range for 'type' is 0-32767. 157 * 158 * \param[in] handle A handle to an established connection. 159 * \param[in] type The request type. 160 * Must be zero( \ref PSA_IPC_CALL) or positive. 161 * \param[in] in_vec Array of input \ref psa_invec structures. 162 * \param[in] in_len Number of input \ref psa_invec structures. 163 * \param[in,out] out_vec Array of output \ref psa_outvec structures. 164 * \param[in] out_len Number of output \ref psa_outvec structures. 165 * 166 * \retval >=0 RoT Service-specific status value. 167 * \retval <0 RoT Service-specific error code. 168 * \retval PSA_ERROR_PROGRAMMER_ERROR The connection has been terminated by the 169 * RoT Service. The call is a PROGRAMMER ERROR if 170 * one or more of the following are true: 171 * \arg An invalid handle was passed. 172 * \arg The connection is already handling a request. 173 * \arg type < 0. 174 * \arg An invalid memory reference was provided. 175 * \arg in_len + out_len > PSA_MAX_IOVEC. 176 * \arg The message is unrecognized by the RoT 177 * Service or incorrectly formatted. 178 */ 179 psa_status_t psa_call(psa_handle_t handle, int32_t type, 180 const psa_invec *in_vec, 181 size_t in_len, 182 psa_outvec *out_vec, 183 size_t out_len); 184 185 /** 186 * \brief Close a connection to an RoT Service. 187 * 188 * \param[in] handle A handle to an established connection, or the 189 * null handle. 190 * 191 * \note The call is a PROGRAMMER ERROR if one or more of the following occurs: 192 * - An invalid handle was provided that is not the null handle. 193 * - The connection is currently handling a request. 194 */ 195 void psa_close(psa_handle_t handle); 196 197 #ifdef __cplusplus 198 } 199 #endif 200 201 #endif /* __PSA_CLIENT_H__ */ 202