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

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.