xref: /linux/drivers/tee/optee/optee_smc.h (revision bfd5bb6f90af092aa345b15cd78143956a13c2a8)
1 /*
2  * Copyright (c) 2015-2016, Linaro Limited
3  * All rights reserved.
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions are met:
7  *
8  * 1. Redistributions of source code must retain the above copyright notice,
9  * this list of conditions and the following disclaimer.
10  *
11  * 2. Redistributions in binary form must reproduce the above copyright notice,
12  * this list of conditions and the following disclaimer in the documentation
13  * and/or other materials provided with the distribution.
14  *
15  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
16  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
18  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
19  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
20  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
21  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
22  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
23  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
24  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
25  * POSSIBILITY OF SUCH DAMAGE.
26  */
27 #ifndef OPTEE_SMC_H
28 #define OPTEE_SMC_H
29 
30 #include <linux/arm-smccc.h>
31 #include <linux/bitops.h>
32 
33 #define OPTEE_SMC_STD_CALL_VAL(func_num) \
34 	ARM_SMCCC_CALL_VAL(ARM_SMCCC_STD_CALL, ARM_SMCCC_SMC_32, \
35 			   ARM_SMCCC_OWNER_TRUSTED_OS, (func_num))
36 #define OPTEE_SMC_FAST_CALL_VAL(func_num) \
37 	ARM_SMCCC_CALL_VAL(ARM_SMCCC_FAST_CALL, ARM_SMCCC_SMC_32, \
38 			   ARM_SMCCC_OWNER_TRUSTED_OS, (func_num))
39 
40 /*
41  * Function specified by SMC Calling convention.
42  */
43 #define OPTEE_SMC_FUNCID_CALLS_COUNT	0xFF00
44 #define OPTEE_SMC_CALLS_COUNT \
45 	ARM_SMCCC_CALL_VAL(OPTEE_SMC_FAST_CALL, SMCCC_SMC_32, \
46 			   SMCCC_OWNER_TRUSTED_OS_END, \
47 			   OPTEE_SMC_FUNCID_CALLS_COUNT)
48 
49 /*
50  * Normal cached memory (write-back), shareable for SMP systems and not
51  * shareable for UP systems.
52  */
53 #define OPTEE_SMC_SHM_CACHED		1
54 
55 /*
56  * a0..a7 is used as register names in the descriptions below, on arm32
57  * that translates to r0..r7 and on arm64 to w0..w7. In both cases it's
58  * 32-bit registers.
59  */
60 
61 /*
62  * Function specified by SMC Calling convention
63  *
64  * Return one of the following UIDs if using API specified in this file
65  * without further extentions:
66  * 65cb6b93-af0c-4617-8ed6-644a8d1140f8
67  * see also OPTEE_SMC_UID_* in optee_msg.h
68  */
69 #define OPTEE_SMC_FUNCID_CALLS_UID OPTEE_MSG_FUNCID_CALLS_UID
70 #define OPTEE_SMC_CALLS_UID \
71 	ARM_SMCCC_CALL_VAL(ARM_SMCCC_FAST_CALL, ARM_SMCCC_SMC_32, \
72 			   ARM_SMCCC_OWNER_TRUSTED_OS_END, \
73 			   OPTEE_SMC_FUNCID_CALLS_UID)
74 
75 /*
76  * Function specified by SMC Calling convention
77  *
78  * Returns 2.0 if using API specified in this file without further extentions.
79  * see also OPTEE_MSG_REVISION_* in optee_msg.h
80  */
81 #define OPTEE_SMC_FUNCID_CALLS_REVISION OPTEE_MSG_FUNCID_CALLS_REVISION
82 #define OPTEE_SMC_CALLS_REVISION \
83 	ARM_SMCCC_CALL_VAL(ARM_SMCCC_FAST_CALL, ARM_SMCCC_SMC_32, \
84 			   ARM_SMCCC_OWNER_TRUSTED_OS_END, \
85 			   OPTEE_SMC_FUNCID_CALLS_REVISION)
86 
87 struct optee_smc_calls_revision_result {
88 	unsigned long major;
89 	unsigned long minor;
90 	unsigned long reserved0;
91 	unsigned long reserved1;
92 };
93 
94 /*
95  * Get UUID of Trusted OS.
96  *
97  * Used by non-secure world to figure out which Trusted OS is installed.
98  * Note that returned UUID is the UUID of the Trusted OS, not of the API.
99  *
100  * Returns UUID in a0-4 in the same way as OPTEE_SMC_CALLS_UID
101  * described above.
102  */
103 #define OPTEE_SMC_FUNCID_GET_OS_UUID OPTEE_MSG_FUNCID_GET_OS_UUID
104 #define OPTEE_SMC_CALL_GET_OS_UUID \
105 	OPTEE_SMC_FAST_CALL_VAL(OPTEE_SMC_FUNCID_GET_OS_UUID)
106 
107 /*
108  * Get revision of Trusted OS.
109  *
110  * Used by non-secure world to figure out which version of the Trusted OS
111  * is installed. Note that the returned revision is the revision of the
112  * Trusted OS, not of the API.
113  *
114  * Returns revision in a0-1 in the same way as OPTEE_SMC_CALLS_REVISION
115  * described above. May optionally return a 32-bit build identifier in a2,
116  * with zero meaning unspecified.
117  */
118 #define OPTEE_SMC_FUNCID_GET_OS_REVISION OPTEE_MSG_FUNCID_GET_OS_REVISION
119 #define OPTEE_SMC_CALL_GET_OS_REVISION \
120 	OPTEE_SMC_FAST_CALL_VAL(OPTEE_SMC_FUNCID_GET_OS_REVISION)
121 
122 struct optee_smc_call_get_os_revision_result {
123 	unsigned long major;
124 	unsigned long minor;
125 	unsigned long build_id;
126 	unsigned long reserved1;
127 };
128 
129 /*
130  * Call with struct optee_msg_arg as argument
131  *
132  * Call register usage:
133  * a0	SMC Function ID, OPTEE_SMC*CALL_WITH_ARG
134  * a1	Upper 32bit of a 64bit physical pointer to a struct optee_msg_arg
135  * a2	Lower 32bit of a 64bit physical pointer to a struct optee_msg_arg
136  * a3	Cache settings, not used if physical pointer is in a predefined shared
137  *	memory area else per OPTEE_SMC_SHM_*
138  * a4-6	Not used
139  * a7	Hypervisor Client ID register
140  *
141  * Normal return register usage:
142  * a0	Return value, OPTEE_SMC_RETURN_*
143  * a1-3	Not used
144  * a4-7	Preserved
145  *
146  * OPTEE_SMC_RETURN_ETHREAD_LIMIT return register usage:
147  * a0	Return value, OPTEE_SMC_RETURN_ETHREAD_LIMIT
148  * a1-3	Preserved
149  * a4-7	Preserved
150  *
151  * RPC return register usage:
152  * a0	Return value, OPTEE_SMC_RETURN_IS_RPC(val)
153  * a1-2	RPC parameters
154  * a3-7	Resume information, must be preserved
155  *
156  * Possible return values:
157  * OPTEE_SMC_RETURN_UNKNOWN_FUNCTION	Trusted OS does not recognize this
158  *					function.
159  * OPTEE_SMC_RETURN_OK			Call completed, result updated in
160  *					the previously supplied struct
161  *					optee_msg_arg.
162  * OPTEE_SMC_RETURN_ETHREAD_LIMIT	Number of Trusted OS threads exceeded,
163  *					try again later.
164  * OPTEE_SMC_RETURN_EBADADDR		Bad physcial pointer to struct
165  *					optee_msg_arg.
166  * OPTEE_SMC_RETURN_EBADCMD		Bad/unknown cmd in struct optee_msg_arg
167  * OPTEE_SMC_RETURN_IS_RPC()		Call suspended by RPC call to normal
168  *					world.
169  */
170 #define OPTEE_SMC_FUNCID_CALL_WITH_ARG OPTEE_MSG_FUNCID_CALL_WITH_ARG
171 #define OPTEE_SMC_CALL_WITH_ARG \
172 	OPTEE_SMC_STD_CALL_VAL(OPTEE_SMC_FUNCID_CALL_WITH_ARG)
173 
174 /*
175  * Get Shared Memory Config
176  *
177  * Returns the Secure/Non-secure shared memory config.
178  *
179  * Call register usage:
180  * a0	SMC Function ID, OPTEE_SMC_GET_SHM_CONFIG
181  * a1-6	Not used
182  * a7	Hypervisor Client ID register
183  *
184  * Have config return register usage:
185  * a0	OPTEE_SMC_RETURN_OK
186  * a1	Physical address of start of SHM
187  * a2	Size of of SHM
188  * a3	Cache settings of memory, as defined by the
189  *	OPTEE_SMC_SHM_* values above
190  * a4-7	Preserved
191  *
192  * Not available register usage:
193  * a0	OPTEE_SMC_RETURN_ENOTAVAIL
194  * a1-3 Not used
195  * a4-7	Preserved
196  */
197 #define OPTEE_SMC_FUNCID_GET_SHM_CONFIG	7
198 #define OPTEE_SMC_GET_SHM_CONFIG \
199 	OPTEE_SMC_FAST_CALL_VAL(OPTEE_SMC_FUNCID_GET_SHM_CONFIG)
200 
201 struct optee_smc_get_shm_config_result {
202 	unsigned long status;
203 	unsigned long start;
204 	unsigned long size;
205 	unsigned long settings;
206 };
207 
208 /*
209  * Exchanges capabilities between normal world and secure world
210  *
211  * Call register usage:
212  * a0	SMC Function ID, OPTEE_SMC_EXCHANGE_CAPABILITIES
213  * a1	bitfield of normal world capabilities OPTEE_SMC_NSEC_CAP_*
214  * a2-6	Not used
215  * a7	Hypervisor Client ID register
216  *
217  * Normal return register usage:
218  * a0	OPTEE_SMC_RETURN_OK
219  * a1	bitfield of secure world capabilities OPTEE_SMC_SEC_CAP_*
220  * a2-7	Preserved
221  *
222  * Error return register usage:
223  * a0	OPTEE_SMC_RETURN_ENOTAVAIL, can't use the capabilities from normal world
224  * a1	bitfield of secure world capabilities OPTEE_SMC_SEC_CAP_*
225  * a2-7 Preserved
226  */
227 /* Normal world works as a uniprocessor system */
228 #define OPTEE_SMC_NSEC_CAP_UNIPROCESSOR		BIT(0)
229 /* Secure world has reserved shared memory for normal world to use */
230 #define OPTEE_SMC_SEC_CAP_HAVE_RESERVED_SHM	BIT(0)
231 /* Secure world can communicate via previously unregistered shared memory */
232 #define OPTEE_SMC_SEC_CAP_UNREGISTERED_SHM	BIT(1)
233 
234 /*
235  * Secure world supports commands "register/unregister shared memory",
236  * secure world accepts command buffers located in any parts of non-secure RAM
237  */
238 #define OPTEE_SMC_SEC_CAP_DYNAMIC_SHM		BIT(2)
239 
240 #define OPTEE_SMC_FUNCID_EXCHANGE_CAPABILITIES	9
241 #define OPTEE_SMC_EXCHANGE_CAPABILITIES \
242 	OPTEE_SMC_FAST_CALL_VAL(OPTEE_SMC_FUNCID_EXCHANGE_CAPABILITIES)
243 
244 struct optee_smc_exchange_capabilities_result {
245 	unsigned long status;
246 	unsigned long capabilities;
247 	unsigned long reserved0;
248 	unsigned long reserved1;
249 };
250 
251 /*
252  * Disable and empties cache of shared memory objects
253  *
254  * Secure world can cache frequently used shared memory objects, for
255  * example objects used as RPC arguments. When secure world is idle this
256  * function returns one shared memory reference to free. To disable the
257  * cache and free all cached objects this function has to be called until
258  * it returns OPTEE_SMC_RETURN_ENOTAVAIL.
259  *
260  * Call register usage:
261  * a0	SMC Function ID, OPTEE_SMC_DISABLE_SHM_CACHE
262  * a1-6	Not used
263  * a7	Hypervisor Client ID register
264  *
265  * Normal return register usage:
266  * a0	OPTEE_SMC_RETURN_OK
267  * a1	Upper 32bit of a 64bit Shared memory cookie
268  * a2	Lower 32bit of a 64bit Shared memory cookie
269  * a3-7	Preserved
270  *
271  * Cache empty return register usage:
272  * a0	OPTEE_SMC_RETURN_ENOTAVAIL
273  * a1-7	Preserved
274  *
275  * Not idle return register usage:
276  * a0	OPTEE_SMC_RETURN_EBUSY
277  * a1-7	Preserved
278  */
279 #define OPTEE_SMC_FUNCID_DISABLE_SHM_CACHE	10
280 #define OPTEE_SMC_DISABLE_SHM_CACHE \
281 	OPTEE_SMC_FAST_CALL_VAL(OPTEE_SMC_FUNCID_DISABLE_SHM_CACHE)
282 
283 struct optee_smc_disable_shm_cache_result {
284 	unsigned long status;
285 	unsigned long shm_upper32;
286 	unsigned long shm_lower32;
287 	unsigned long reserved0;
288 };
289 
290 /*
291  * Enable cache of shared memory objects
292  *
293  * Secure world can cache frequently used shared memory objects, for
294  * example objects used as RPC arguments. When secure world is idle this
295  * function returns OPTEE_SMC_RETURN_OK and the cache is enabled. If
296  * secure world isn't idle OPTEE_SMC_RETURN_EBUSY is returned.
297  *
298  * Call register usage:
299  * a0	SMC Function ID, OPTEE_SMC_ENABLE_SHM_CACHE
300  * a1-6	Not used
301  * a7	Hypervisor Client ID register
302  *
303  * Normal return register usage:
304  * a0	OPTEE_SMC_RETURN_OK
305  * a1-7	Preserved
306  *
307  * Not idle return register usage:
308  * a0	OPTEE_SMC_RETURN_EBUSY
309  * a1-7	Preserved
310  */
311 #define OPTEE_SMC_FUNCID_ENABLE_SHM_CACHE	11
312 #define OPTEE_SMC_ENABLE_SHM_CACHE \
313 	OPTEE_SMC_FAST_CALL_VAL(OPTEE_SMC_FUNCID_ENABLE_SHM_CACHE)
314 
315 /*
316  * Resume from RPC (for example after processing a foreign interrupt)
317  *
318  * Call register usage:
319  * a0	SMC Function ID, OPTEE_SMC_CALL_RETURN_FROM_RPC
320  * a1-3	Value of a1-3 when OPTEE_SMC_CALL_WITH_ARG returned
321  *	OPTEE_SMC_RETURN_RPC in a0
322  *
323  * Return register usage is the same as for OPTEE_SMC_*CALL_WITH_ARG above.
324  *
325  * Possible return values
326  * OPTEE_SMC_RETURN_UNKNOWN_FUNCTION	Trusted OS does not recognize this
327  *					function.
328  * OPTEE_SMC_RETURN_OK			Original call completed, result
329  *					updated in the previously supplied.
330  *					struct optee_msg_arg
331  * OPTEE_SMC_RETURN_RPC			Call suspended by RPC call to normal
332  *					world.
333  * OPTEE_SMC_RETURN_ERESUME		Resume failed, the opaque resume
334  *					information was corrupt.
335  */
336 #define OPTEE_SMC_FUNCID_RETURN_FROM_RPC	3
337 #define OPTEE_SMC_CALL_RETURN_FROM_RPC \
338 	OPTEE_SMC_STD_CALL_VAL(OPTEE_SMC_FUNCID_RETURN_FROM_RPC)
339 
340 #define OPTEE_SMC_RETURN_RPC_PREFIX_MASK	0xFFFF0000
341 #define OPTEE_SMC_RETURN_RPC_PREFIX		0xFFFF0000
342 #define OPTEE_SMC_RETURN_RPC_FUNC_MASK		0x0000FFFF
343 
344 #define OPTEE_SMC_RETURN_GET_RPC_FUNC(ret) \
345 	((ret) & OPTEE_SMC_RETURN_RPC_FUNC_MASK)
346 
347 #define OPTEE_SMC_RPC_VAL(func)		((func) | OPTEE_SMC_RETURN_RPC_PREFIX)
348 
349 /*
350  * Allocate memory for RPC parameter passing. The memory is used to hold a
351  * struct optee_msg_arg.
352  *
353  * "Call" register usage:
354  * a0	This value, OPTEE_SMC_RETURN_RPC_ALLOC
355  * a1	Size in bytes of required argument memory
356  * a2	Not used
357  * a3	Resume information, must be preserved
358  * a4-5	Not used
359  * a6-7	Resume information, must be preserved
360  *
361  * "Return" register usage:
362  * a0	SMC Function ID, OPTEE_SMC_CALL_RETURN_FROM_RPC.
363  * a1	Upper 32bits of 64bit physical pointer to allocated
364  *	memory, (a1 == 0 && a2 == 0) if size was 0 or if memory can't
365  *	be allocated.
366  * a2	Lower 32bits of 64bit physical pointer to allocated
367  *	memory, (a1 == 0 && a2 == 0) if size was 0 or if memory can't
368  *	be allocated
369  * a3	Preserved
370  * a4	Upper 32bits of 64bit Shared memory cookie used when freeing
371  *	the memory or doing an RPC
372  * a5	Lower 32bits of 64bit Shared memory cookie used when freeing
373  *	the memory or doing an RPC
374  * a6-7	Preserved
375  */
376 #define OPTEE_SMC_RPC_FUNC_ALLOC	0
377 #define OPTEE_SMC_RETURN_RPC_ALLOC \
378 	OPTEE_SMC_RPC_VAL(OPTEE_SMC_RPC_FUNC_ALLOC)
379 
380 /*
381  * Free memory previously allocated by OPTEE_SMC_RETURN_RPC_ALLOC
382  *
383  * "Call" register usage:
384  * a0	This value, OPTEE_SMC_RETURN_RPC_FREE
385  * a1	Upper 32bits of 64bit shared memory cookie belonging to this
386  *	argument memory
387  * a2	Lower 32bits of 64bit shared memory cookie belonging to this
388  *	argument memory
389  * a3-7	Resume information, must be preserved
390  *
391  * "Return" register usage:
392  * a0	SMC Function ID, OPTEE_SMC_CALL_RETURN_FROM_RPC.
393  * a1-2	Not used
394  * a3-7	Preserved
395  */
396 #define OPTEE_SMC_RPC_FUNC_FREE		2
397 #define OPTEE_SMC_RETURN_RPC_FREE \
398 	OPTEE_SMC_RPC_VAL(OPTEE_SMC_RPC_FUNC_FREE)
399 
400 /*
401  * Deliver foreign interrupt to normal world.
402  *
403  * "Call" register usage:
404  * a0	OPTEE_SMC_RETURN_RPC_FOREIGN_INTR
405  * a1-7	Resume information, must be preserved
406  *
407  * "Return" register usage:
408  * a0	SMC Function ID, OPTEE_SMC_CALL_RETURN_FROM_RPC.
409  * a1-7	Preserved
410  */
411 #define OPTEE_SMC_RPC_FUNC_FOREIGN_INTR		4
412 #define OPTEE_SMC_RETURN_RPC_FOREIGN_INTR \
413 	OPTEE_SMC_RPC_VAL(OPTEE_SMC_RPC_FUNC_FOREIGN_INTR)
414 
415 /*
416  * Do an RPC request. The supplied struct optee_msg_arg tells which
417  * request to do and the parameters for the request. The following fields
418  * are used (the rest are unused):
419  * - cmd		the Request ID
420  * - ret		return value of the request, filled in by normal world
421  * - num_params		number of parameters for the request
422  * - params		the parameters
423  * - param_attrs	attributes of the parameters
424  *
425  * "Call" register usage:
426  * a0	OPTEE_SMC_RETURN_RPC_CMD
427  * a1	Upper 32bit of a 64bit Shared memory cookie holding a
428  *	struct optee_msg_arg, must be preserved, only the data should
429  *	be updated
430  * a2	Lower 32bit of a 64bit Shared memory cookie holding a
431  *	struct optee_msg_arg, must be preserved, only the data should
432  *	be updated
433  * a3-7	Resume information, must be preserved
434  *
435  * "Return" register usage:
436  * a0	SMC Function ID, OPTEE_SMC_CALL_RETURN_FROM_RPC.
437  * a1-2	Not used
438  * a3-7	Preserved
439  */
440 #define OPTEE_SMC_RPC_FUNC_CMD		5
441 #define OPTEE_SMC_RETURN_RPC_CMD \
442 	OPTEE_SMC_RPC_VAL(OPTEE_SMC_RPC_FUNC_CMD)
443 
444 /* Returned in a0 */
445 #define OPTEE_SMC_RETURN_UNKNOWN_FUNCTION 0xFFFFFFFF
446 
447 /* Returned in a0 only from Trusted OS functions */
448 #define OPTEE_SMC_RETURN_OK		0x0
449 #define OPTEE_SMC_RETURN_ETHREAD_LIMIT	0x1
450 #define OPTEE_SMC_RETURN_EBUSY		0x2
451 #define OPTEE_SMC_RETURN_ERESUME	0x3
452 #define OPTEE_SMC_RETURN_EBADADDR	0x4
453 #define OPTEE_SMC_RETURN_EBADCMD	0x5
454 #define OPTEE_SMC_RETURN_ENOMEM		0x6
455 #define OPTEE_SMC_RETURN_ENOTAVAIL	0x7
456 #define OPTEE_SMC_RETURN_IS_RPC(ret)	__optee_smc_return_is_rpc((ret))
457 
458 static inline bool __optee_smc_return_is_rpc(u32 ret)
459 {
460 	return ret != OPTEE_SMC_RETURN_UNKNOWN_FUNCTION &&
461 	       (ret & OPTEE_SMC_RETURN_RPC_PREFIX_MASK) ==
462 			OPTEE_SMC_RETURN_RPC_PREFIX;
463 }
464 
465 #endif /* OPTEE_SMC_H */
466