1 /*
2  * Copyright (c) 2018-2024, 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 #ifndef IOVEC_LEN
17 #define IOVEC_LEN(arr) ((uint32_t)(sizeof(arr)/sizeof(arr[0])))
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. Only part of features of FF-M v1.1 have been implemented. FF-M v1.1
25  * is compatible with v1.0.
26  */
27 #define PSA_FRAMEWORK_VERSION	(0x0101u)
28 
29 /**
30  * Return value from psa_version() if the requested RoT Service is not present
31  * in the system.
32  */
33 #define PSA_VERSION_NONE	(0u)
34 
35 /**
36  * The zero-value null handle can be assigned to variables used in clients and
37  * RoT Services, indicating that there is no current connection or message.
38  */
39 #define PSA_NULL_HANDLE		((psa_handle_t)0)
40 
41 /**
42  * Tests whether a handle value returned by psa_connect() is valid.
43  */
44 #define PSA_HANDLE_IS_VALID(handle)	((psa_handle_t)(handle) > 0)
45 
46 /**
47  * Converts the handle value returned from a failed call psa_connect() into
48  * an error code.
49  */
50 #define PSA_HANDLE_TO_ERROR(handle)	((psa_status_t)(handle))
51 
52 /**
53  * Maximum number of input and output vectors for a request to psa_call().
54  */
55 #define PSA_MAX_IOVEC		(4u)
56 
57 /**
58  * The minimum and maximum value that can be passed
59  * as the type parameter in a call to psa_call().
60  */
61 #define PSA_CALL_TYPE_MIN	(0)
62 #define PSA_CALL_TYPE_MAX	(INT16_MAX)
63 
64 /**
65  * An IPC message type that indicates a generic client request.
66  */
67 #define PSA_IPC_CALL		(0)
68 typedef int32_t psa_handle_t;
69 
70 /**
71  * A read-only input memory region provided to an RoT Service.
72  */
73 typedef struct psa_invec {
74 	const void *base;	/*!< the start address of the memory buffer */
75 	size_t len;		/*!< the size in bytes                      */
76 } psa_invec;
77 
78 /**
79  * A writable output memory region provided to an RoT Service.
80  */
81 typedef struct psa_outvec {
82 	void *base;		/*!< the start address of the memory buffer */
83 	size_t len;		/*!< the size in bytes                      */
84 } psa_outvec;
85 
86 /**
87  * Call an RoT Service on an established connection.
88  *
89  * handle	A handle to an established connection.
90  * type		The request type. Must be zero(PSA_IPC_CALL) or positive.
91  * in_vec	Array of input psa_invec structures.
92  * in_len	Number of input psa_invec structures.
93  * out_vec	Array of output psa_outvec structures.
94  * out_len	Number of output psa_outvec structures.
95  *
96  * Return value >=0	RoT Service-specific status value.
97  * Return value <0	RoT Service-specific error code.
98  *
99  * PSA_ERROR_PROGRAMMER_ERROR:
100  *	- The connection has been terminated by the RoT Service.
101  *
102  * The call is a PROGRAMMER ERROR if one or more of the following are true:
103  *	- An invalid handle was passed.
104  *	- The connection is already handling a request.
105  *	- type < 0.
106  *	- An invalid memory reference was provided.
107  *	- in_len + out_len > PSA_MAX_IOVEC.
108  *	- The message is unrecognized by the RoT.
109  *	- Service or incorrectly formatted.
110  */
111 psa_status_t psa_call(psa_handle_t handle,
112 		      int32_t type,
113 		      const psa_invec *in_vec,
114 		      size_t in_len,
115 		      psa_outvec *out_vec,
116 		      size_t out_len);
117 
118 #endif /* PSA_CLIENT_H */
119