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