1 | /* SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) */ |
2 | /* |
3 | * Copyright (c) 2015-2021, Linaro Limited |
4 | */ |
5 | #ifndef _OPTEE_MSG_H |
6 | #define _OPTEE_MSG_H |
7 | |
8 | #include <linux/bitops.h> |
9 | #include <linux/types.h> |
10 | |
11 | /* |
12 | * This file defines the OP-TEE message protocol (ABI) used to communicate |
13 | * with an instance of OP-TEE running in secure world. |
14 | * |
15 | * This file is divided into two sections. |
16 | * 1. Formatting of messages. |
17 | * 2. Requests from normal world |
18 | */ |
19 | |
20 | /***************************************************************************** |
21 | * Part 1 - formatting of messages |
22 | *****************************************************************************/ |
23 | |
24 | #define OPTEE_MSG_ATTR_TYPE_NONE 0x0 |
25 | #define OPTEE_MSG_ATTR_TYPE_VALUE_INPUT 0x1 |
26 | #define OPTEE_MSG_ATTR_TYPE_VALUE_OUTPUT 0x2 |
27 | #define OPTEE_MSG_ATTR_TYPE_VALUE_INOUT 0x3 |
28 | #define OPTEE_MSG_ATTR_TYPE_RMEM_INPUT 0x5 |
29 | #define OPTEE_MSG_ATTR_TYPE_RMEM_OUTPUT 0x6 |
30 | #define OPTEE_MSG_ATTR_TYPE_RMEM_INOUT 0x7 |
31 | #define OPTEE_MSG_ATTR_TYPE_FMEM_INPUT OPTEE_MSG_ATTR_TYPE_RMEM_INPUT |
32 | #define OPTEE_MSG_ATTR_TYPE_FMEM_OUTPUT OPTEE_MSG_ATTR_TYPE_RMEM_OUTPUT |
33 | #define OPTEE_MSG_ATTR_TYPE_FMEM_INOUT OPTEE_MSG_ATTR_TYPE_RMEM_INOUT |
34 | #define OPTEE_MSG_ATTR_TYPE_TMEM_INPUT 0x9 |
35 | #define OPTEE_MSG_ATTR_TYPE_TMEM_OUTPUT 0xa |
36 | #define OPTEE_MSG_ATTR_TYPE_TMEM_INOUT 0xb |
37 | |
38 | #define OPTEE_MSG_ATTR_TYPE_MASK GENMASK(7, 0) |
39 | |
40 | /* |
41 | * Meta parameter to be absorbed by the Secure OS and not passed |
42 | * to the Trusted Application. |
43 | * |
44 | * Currently only used with OPTEE_MSG_CMD_OPEN_SESSION. |
45 | */ |
46 | #define OPTEE_MSG_ATTR_META BIT(8) |
47 | |
48 | /* |
49 | * Pointer to a list of pages used to register user-defined SHM buffer. |
50 | * Used with OPTEE_MSG_ATTR_TYPE_TMEM_*. |
51 | * buf_ptr should point to the beginning of the buffer. Buffer will contain |
52 | * list of page addresses. OP-TEE core can reconstruct contiguous buffer from |
53 | * that page addresses list. Page addresses are stored as 64 bit values. |
54 | * Last entry on a page should point to the next page of buffer. |
55 | * Every entry in buffer should point to a 4k page beginning (12 least |
56 | * significant bits must be equal to zero). |
57 | * |
58 | * 12 least significant bits of optee_msg_param.u.tmem.buf_ptr should hold |
59 | * page offset of user buffer. |
60 | * |
61 | * So, entries should be placed like members of this structure: |
62 | * |
63 | * struct page_data { |
64 | * uint64_t pages_array[OPTEE_MSG_NONCONTIG_PAGE_SIZE/sizeof(uint64_t) - 1]; |
65 | * uint64_t next_page_data; |
66 | * }; |
67 | * |
68 | * Structure is designed to exactly fit into the page size |
69 | * OPTEE_MSG_NONCONTIG_PAGE_SIZE which is a standard 4KB page. |
70 | * |
71 | * The size of 4KB is chosen because this is the smallest page size for ARM |
72 | * architectures. If REE uses larger pages, it should divide them to 4KB ones. |
73 | */ |
74 | #define OPTEE_MSG_ATTR_NONCONTIG BIT(9) |
75 | |
76 | /* |
77 | * Memory attributes for caching passed with temp memrefs. The actual value |
78 | * used is defined outside the message protocol with the exception of |
79 | * OPTEE_MSG_ATTR_CACHE_PREDEFINED which means the attributes already |
80 | * defined for the memory range should be used. If optee_smc.h is used as |
81 | * bearer of this protocol OPTEE_SMC_SHM_* is used for values. |
82 | */ |
83 | #define OPTEE_MSG_ATTR_CACHE_SHIFT 16 |
84 | #define OPTEE_MSG_ATTR_CACHE_MASK GENMASK(2, 0) |
85 | #define OPTEE_MSG_ATTR_CACHE_PREDEFINED 0 |
86 | |
87 | /* |
88 | * Same values as TEE_LOGIN_* from TEE Internal API |
89 | */ |
90 | #define OPTEE_MSG_LOGIN_PUBLIC 0x00000000 |
91 | #define OPTEE_MSG_LOGIN_USER 0x00000001 |
92 | #define OPTEE_MSG_LOGIN_GROUP 0x00000002 |
93 | #define OPTEE_MSG_LOGIN_APPLICATION 0x00000004 |
94 | #define OPTEE_MSG_LOGIN_APPLICATION_USER 0x00000005 |
95 | #define OPTEE_MSG_LOGIN_APPLICATION_GROUP 0x00000006 |
96 | |
97 | /* |
98 | * Page size used in non-contiguous buffer entries |
99 | */ |
100 | #define OPTEE_MSG_NONCONTIG_PAGE_SIZE 4096 |
101 | |
102 | #define OPTEE_MSG_FMEM_INVALID_GLOBAL_ID 0xffffffffffffffff |
103 | |
104 | /** |
105 | * struct optee_msg_param_tmem - temporary memory reference parameter |
106 | * @buf_ptr: Address of the buffer |
107 | * @size: Size of the buffer |
108 | * @shm_ref: Temporary shared memory reference, pointer to a struct tee_shm |
109 | * |
110 | * Secure and normal world communicates pointers as physical address |
111 | * instead of the virtual address. This is because secure and normal world |
112 | * have completely independent memory mapping. Normal world can even have a |
113 | * hypervisor which need to translate the guest physical address (AKA IPA |
114 | * in ARM documentation) to a real physical address before passing the |
115 | * structure to secure world. |
116 | */ |
117 | struct optee_msg_param_tmem { |
118 | u64 buf_ptr; |
119 | u64 size; |
120 | u64 shm_ref; |
121 | }; |
122 | |
123 | /** |
124 | * struct optee_msg_param_rmem - registered memory reference parameter |
125 | * @offs: Offset into shared memory reference |
126 | * @size: Size of the buffer |
127 | * @shm_ref: Shared memory reference, pointer to a struct tee_shm |
128 | */ |
129 | struct optee_msg_param_rmem { |
130 | u64 offs; |
131 | u64 size; |
132 | u64 shm_ref; |
133 | }; |
134 | |
135 | /** |
136 | * struct optee_msg_param_fmem - ffa memory reference parameter |
137 | * @offs_lower: Lower bits of offset into shared memory reference |
138 | * @offs_upper: Upper bits of offset into shared memory reference |
139 | * @internal_offs: Internal offset into the first page of shared memory |
140 | * reference |
141 | * @size: Size of the buffer |
142 | * @global_id: Global identifier of Shared memory |
143 | */ |
144 | struct optee_msg_param_fmem { |
145 | u32 offs_low; |
146 | u16 offs_high; |
147 | u16 internal_offs; |
148 | u64 size; |
149 | u64 global_id; |
150 | }; |
151 | |
152 | /** |
153 | * struct optee_msg_param_value - opaque value parameter |
154 | * |
155 | * Value parameters are passed unchecked between normal and secure world. |
156 | */ |
157 | struct optee_msg_param_value { |
158 | u64 a; |
159 | u64 b; |
160 | u64 c; |
161 | }; |
162 | |
163 | /** |
164 | * struct optee_msg_param - parameter used together with struct optee_msg_arg |
165 | * @attr: attributes |
166 | * @tmem: parameter by temporary memory reference |
167 | * @rmem: parameter by registered memory reference |
168 | * @fmem: parameter by ffa registered memory reference |
169 | * @value: parameter by opaque value |
170 | * @octets: parameter by octet string |
171 | * |
172 | * @attr & OPTEE_MSG_ATTR_TYPE_MASK indicates if tmem, rmem or value is used in |
173 | * the union. OPTEE_MSG_ATTR_TYPE_VALUE_* indicates value or octets, |
174 | * OPTEE_MSG_ATTR_TYPE_TMEM_* indicates @tmem and |
175 | * OPTEE_MSG_ATTR_TYPE_RMEM_* or the alias PTEE_MSG_ATTR_TYPE_FMEM_* indicates |
176 | * @rmem or @fmem depending on the conduit. |
177 | * OPTEE_MSG_ATTR_TYPE_NONE indicates that none of the members are used. |
178 | */ |
179 | struct optee_msg_param { |
180 | u64 attr; |
181 | union { |
182 | struct optee_msg_param_tmem tmem; |
183 | struct optee_msg_param_rmem rmem; |
184 | struct optee_msg_param_fmem fmem; |
185 | struct optee_msg_param_value value; |
186 | u8 octets[24]; |
187 | } u; |
188 | }; |
189 | |
190 | /** |
191 | * struct optee_msg_arg - call argument |
192 | * @cmd: Command, one of OPTEE_MSG_CMD_* or OPTEE_MSG_RPC_CMD_* |
193 | * @func: Trusted Application function, specific to the Trusted Application, |
194 | * used if cmd == OPTEE_MSG_CMD_INVOKE_COMMAND |
195 | * @session: In parameter for all OPTEE_MSG_CMD_* except |
196 | * OPTEE_MSG_CMD_OPEN_SESSION where it's an output parameter instead |
197 | * @cancel_id: Cancellation id, a unique value to identify this request |
198 | * @ret: return value |
199 | * @ret_origin: origin of the return value |
200 | * @num_params: number of parameters supplied to the OS Command |
201 | * @params: the parameters supplied to the OS Command |
202 | * |
203 | * All normal calls to Trusted OS uses this struct. If cmd requires further |
204 | * information than what these fields hold it can be passed as a parameter |
205 | * tagged as meta (setting the OPTEE_MSG_ATTR_META bit in corresponding |
206 | * attrs field). All parameters tagged as meta have to come first. |
207 | */ |
208 | struct optee_msg_arg { |
209 | u32 cmd; |
210 | u32 func; |
211 | u32 session; |
212 | u32 cancel_id; |
213 | u32 pad; |
214 | u32 ret; |
215 | u32 ret_origin; |
216 | u32 num_params; |
217 | |
218 | /* num_params tells the actual number of element in params */ |
219 | struct optee_msg_param params[]; |
220 | }; |
221 | |
222 | /** |
223 | * OPTEE_MSG_GET_ARG_SIZE - return size of struct optee_msg_arg |
224 | * |
225 | * @num_params: Number of parameters embedded in the struct optee_msg_arg |
226 | * |
227 | * Returns the size of the struct optee_msg_arg together with the number |
228 | * of embedded parameters. |
229 | */ |
230 | #define OPTEE_MSG_GET_ARG_SIZE(num_params) \ |
231 | (sizeof(struct optee_msg_arg) + \ |
232 | sizeof(struct optee_msg_param) * (num_params)) |
233 | |
234 | /***************************************************************************** |
235 | * Part 2 - requests from normal world |
236 | *****************************************************************************/ |
237 | |
238 | /* |
239 | * Return the following UID if using API specified in this file without |
240 | * further extensions: |
241 | * 384fb3e0-e7f8-11e3-af63-0002a5d5c51b. |
242 | * Represented in 4 32-bit words in OPTEE_MSG_UID_0, OPTEE_MSG_UID_1, |
243 | * OPTEE_MSG_UID_2, OPTEE_MSG_UID_3. |
244 | * |
245 | * In the case where the OP-TEE image is loaded by the kernel, this will |
246 | * initially return an alternate UID to reflect that we are communicating with |
247 | * the TF-A image loading service at that time instead of OP-TEE. That UID is: |
248 | * a3fbeab1-1246-315d-c7c4-06b9c03cbea4. |
249 | * Represented in 4 32-bit words in OPTEE_MSG_IMAGE_LOAD_UID_0, |
250 | * OPTEE_MSG_IMAGE_LOAD_UID_1, OPTEE_MSG_IMAGE_LOAD_UID_2, |
251 | * OPTEE_MSG_IMAGE_LOAD_UID_3. |
252 | */ |
253 | #define OPTEE_MSG_UID_0 0x384fb3e0 |
254 | #define OPTEE_MSG_UID_1 0xe7f811e3 |
255 | #define OPTEE_MSG_UID_2 0xaf630002 |
256 | #define OPTEE_MSG_UID_3 0xa5d5c51b |
257 | #define OPTEE_MSG_IMAGE_LOAD_UID_0 0xa3fbeab1 |
258 | #define OPTEE_MSG_IMAGE_LOAD_UID_1 0x1246315d |
259 | #define OPTEE_MSG_IMAGE_LOAD_UID_2 0xc7c406b9 |
260 | #define OPTEE_MSG_IMAGE_LOAD_UID_3 0xc03cbea4 |
261 | #define OPTEE_MSG_FUNCID_CALLS_UID 0xFF01 |
262 | |
263 | /* |
264 | * Returns 2.0 if using API specified in this file without further |
265 | * extensions. Represented in 2 32-bit words in OPTEE_MSG_REVISION_MAJOR |
266 | * and OPTEE_MSG_REVISION_MINOR |
267 | */ |
268 | #define OPTEE_MSG_REVISION_MAJOR 2 |
269 | #define OPTEE_MSG_REVISION_MINOR 0 |
270 | #define OPTEE_MSG_FUNCID_CALLS_REVISION 0xFF03 |
271 | |
272 | /* |
273 | * Get UUID of Trusted OS. |
274 | * |
275 | * Used by non-secure world to figure out which Trusted OS is installed. |
276 | * Note that returned UUID is the UUID of the Trusted OS, not of the API. |
277 | * |
278 | * Returns UUID in 4 32-bit words in the same way as |
279 | * OPTEE_MSG_FUNCID_CALLS_UID described above. |
280 | */ |
281 | #define OPTEE_MSG_OS_OPTEE_UUID_0 0x486178e0 |
282 | #define OPTEE_MSG_OS_OPTEE_UUID_1 0xe7f811e3 |
283 | #define OPTEE_MSG_OS_OPTEE_UUID_2 0xbc5e0002 |
284 | #define OPTEE_MSG_OS_OPTEE_UUID_3 0xa5d5c51b |
285 | #define OPTEE_MSG_FUNCID_GET_OS_UUID 0x0000 |
286 | |
287 | /* |
288 | * Get revision of Trusted OS. |
289 | * |
290 | * Used by non-secure world to figure out which version of the Trusted OS |
291 | * is installed. Note that the returned revision is the revision of the |
292 | * Trusted OS, not of the API. |
293 | * |
294 | * Returns revision in 2 32-bit words in the same way as |
295 | * OPTEE_MSG_CALLS_REVISION described above. |
296 | */ |
297 | #define OPTEE_MSG_FUNCID_GET_OS_REVISION 0x0001 |
298 | |
299 | /* |
300 | * Do a secure call with struct optee_msg_arg as argument |
301 | * The OPTEE_MSG_CMD_* below defines what goes in struct optee_msg_arg::cmd |
302 | * |
303 | * OPTEE_MSG_CMD_OPEN_SESSION opens a session to a Trusted Application. |
304 | * The first two parameters are tagged as meta, holding two value |
305 | * parameters to pass the following information: |
306 | * param[0].u.value.a-b uuid of Trusted Application |
307 | * param[1].u.value.a-b uuid of Client |
308 | * param[1].u.value.c Login class of client OPTEE_MSG_LOGIN_* |
309 | * |
310 | * OPTEE_MSG_CMD_INVOKE_COMMAND invokes a command a previously opened |
311 | * session to a Trusted Application. struct optee_msg_arg::func is Trusted |
312 | * Application function, specific to the Trusted Application. |
313 | * |
314 | * OPTEE_MSG_CMD_CLOSE_SESSION closes a previously opened session to |
315 | * Trusted Application. |
316 | * |
317 | * OPTEE_MSG_CMD_CANCEL cancels a currently invoked command. |
318 | * |
319 | * OPTEE_MSG_CMD_REGISTER_SHM registers a shared memory reference. The |
320 | * information is passed as: |
321 | * [in] param[0].attr OPTEE_MSG_ATTR_TYPE_TMEM_INPUT |
322 | * [| OPTEE_MSG_ATTR_NONCONTIG] |
323 | * [in] param[0].u.tmem.buf_ptr physical address (of first fragment) |
324 | * [in] param[0].u.tmem.size size (of first fragment) |
325 | * [in] param[0].u.tmem.shm_ref holds shared memory reference |
326 | * |
327 | * OPTEE_MSG_CMD_UNREGISTER_SHM unregisters a previously registered shared |
328 | * memory reference. The information is passed as: |
329 | * [in] param[0].attr OPTEE_MSG_ATTR_TYPE_RMEM_INPUT |
330 | * [in] param[0].u.rmem.shm_ref holds shared memory reference |
331 | * [in] param[0].u.rmem.offs 0 |
332 | * [in] param[0].u.rmem.size 0 |
333 | * |
334 | * OPTEE_MSG_CMD_DO_BOTTOM_HALF does the scheduled bottom half processing |
335 | * of a driver. |
336 | * |
337 | * OPTEE_MSG_CMD_STOP_ASYNC_NOTIF informs secure world that from now is |
338 | * normal world unable to process asynchronous notifications. Typically |
339 | * used when the driver is shut down. |
340 | */ |
341 | #define OPTEE_MSG_CMD_OPEN_SESSION 0 |
342 | #define OPTEE_MSG_CMD_INVOKE_COMMAND 1 |
343 | #define OPTEE_MSG_CMD_CLOSE_SESSION 2 |
344 | #define OPTEE_MSG_CMD_CANCEL 3 |
345 | #define OPTEE_MSG_CMD_REGISTER_SHM 4 |
346 | #define OPTEE_MSG_CMD_UNREGISTER_SHM 5 |
347 | #define OPTEE_MSG_CMD_DO_BOTTOM_HALF 6 |
348 | #define OPTEE_MSG_CMD_STOP_ASYNC_NOTIF 7 |
349 | #define OPTEE_MSG_FUNCID_CALL_WITH_ARG 0x0004 |
350 | |
351 | #endif /* _OPTEE_MSG_H */ |
352 | |