optee_msg.h 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425
  1. /* SPDX-License-Identifier: BSD-2-Clause */
  2. /*
  3. * Copyright (c) 2015-2018, Linaro Limited
  4. */
  5. #ifndef _OPTEE_MSG_H
  6. #define _OPTEE_MSG_H
  7. #include <linux/bitops.h>
  8. #include <linux/types.h>
  9. /*
  10. * This file defines the OP-TEE message protocol used to communicate with
  11. * an instance of OP-TEE running in secure world. This file is based on
  12. * https://github.com/OP-TEE/optee_os/blob/master/core/include/optee_msg.h
  13. * and may need to be updated when introducing new features.
  14. *
  15. * This file is divided into three sections.
  16. * 1. Formatting of messages.
  17. * 2. Requests from normal world
  18. * 3. Requests from secure world, Remote Procedure Call (RPC), handled by
  19. * tee-supplicant.
  20. */
  21. /*****************************************************************************
  22. * Part 1 - formatting of messages
  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_TMEM_INPUT 0x9
  32. #define OPTEE_MSG_ATTR_TYPE_TMEM_OUTPUT 0xa
  33. #define OPTEE_MSG_ATTR_TYPE_TMEM_INOUT 0xb
  34. #define OPTEE_MSG_ATTR_TYPE_MASK GENMASK(7, 0)
  35. /*
  36. * Meta parameter to be absorbed by the Secure OS and not passed
  37. * to the Trusted Application.
  38. *
  39. * Currently only used with OPTEE_MSG_CMD_OPEN_SESSION.
  40. */
  41. #define OPTEE_MSG_ATTR_META BIT(8)
  42. /*
  43. * Pointer to a list of pages used to register user-defined SHM buffer.
  44. * Used with OPTEE_MSG_ATTR_TYPE_TMEM_*.
  45. * buf_ptr should point to the beginning of the buffer. Buffer will contain
  46. * list of page addresses. OP-TEE core can reconstruct contiguous buffer from
  47. * that page addresses list. Page addresses are stored as 64 bit values.
  48. * Last entry on a page should point to the next page of buffer.
  49. * Every entry in buffer should point to a 4k page beginning (12 least
  50. * significant bits must be equal to zero).
  51. *
  52. * 12 least significant bints of optee_msg_param.u.tmem.buf_ptr should hold page
  53. * offset of the user buffer.
  54. *
  55. * So, entries should be placed like members of this structure:
  56. *
  57. * struct page_data {
  58. * uint64_t pages_array[OPTEE_MSG_NONCONTIG_PAGE_SIZE/sizeof(uint64_t) - 1];
  59. * uint64_t next_page_data;
  60. * };
  61. *
  62. * Structure is designed to exactly fit into the page size
  63. * OPTEE_MSG_NONCONTIG_PAGE_SIZE which is a standard 4KB page.
  64. *
  65. * The size of 4KB is chosen because this is the smallest page size for ARM
  66. * architectures. If REE uses larger pages, it should divide them to 4KB ones.
  67. */
  68. #define OPTEE_MSG_ATTR_NONCONTIG BIT(9)
  69. /*
  70. * Memory attributes for caching passed with temp memrefs. The actual value
  71. * used is defined outside the message protocol with the exception of
  72. * OPTEE_MSG_ATTR_CACHE_PREDEFINED which means the attributes already
  73. * defined for the memory range should be used. If optee_smc.h is used as
  74. * bearer of this protocol OPTEE_SMC_SHM_* is used for values.
  75. */
  76. #define OPTEE_MSG_ATTR_CACHE_SHIFT 16
  77. #define OPTEE_MSG_ATTR_CACHE_MASK GENMASK(2, 0)
  78. #define OPTEE_MSG_ATTR_CACHE_PREDEFINED 0
  79. /*
  80. * Same values as TEE_LOGIN_* from TEE Internal API
  81. */
  82. #define OPTEE_MSG_LOGIN_PUBLIC 0x00000000
  83. #define OPTEE_MSG_LOGIN_USER 0x00000001
  84. #define OPTEE_MSG_LOGIN_GROUP 0x00000002
  85. #define OPTEE_MSG_LOGIN_APPLICATION 0x00000004
  86. #define OPTEE_MSG_LOGIN_APPLICATION_USER 0x00000005
  87. #define OPTEE_MSG_LOGIN_APPLICATION_GROUP 0x00000006
  88. /*
  89. * Page size used in non-contiguous buffer entries
  90. */
  91. #define OPTEE_MSG_NONCONTIG_PAGE_SIZE 4096
  92. /**
  93. * struct optee_msg_param_tmem - temporary memory reference parameter
  94. * @buf_ptr: Address of the buffer
  95. * @size: Size of the buffer
  96. * @shm_ref: Temporary shared memory reference, pointer to a struct tee_shm
  97. *
  98. * Secure and normal world communicates pointers as physical address
  99. * instead of the virtual address. This is because secure and normal world
  100. * have completely independent memory mapping. Normal world can even have a
  101. * hypervisor which need to translate the guest physical address (AKA IPA
  102. * in ARM documentation) to a real physical address before passing the
  103. * structure to secure world.
  104. */
  105. struct optee_msg_param_tmem {
  106. u64 buf_ptr;
  107. u64 size;
  108. u64 shm_ref;
  109. };
  110. /**
  111. * struct optee_msg_param_rmem - registered memory reference parameter
  112. * @offs: Offset into shared memory reference
  113. * @size: Size of the buffer
  114. * @shm_ref: Shared memory reference, pointer to a struct tee_shm
  115. */
  116. struct optee_msg_param_rmem {
  117. u64 offs;
  118. u64 size;
  119. u64 shm_ref;
  120. };
  121. /**
  122. * struct optee_msg_param_value - opaque value parameter
  123. *
  124. * Value parameters are passed unchecked between normal and secure world.
  125. */
  126. struct optee_msg_param_value {
  127. u64 a;
  128. u64 b;
  129. u64 c;
  130. };
  131. /**
  132. * struct optee_msg_param - parameter used together with struct optee_msg_arg
  133. * @attr: attributes
  134. * @tmem: parameter by temporary memory reference
  135. * @rmem: parameter by registered memory reference
  136. * @value: parameter by opaque value
  137. *
  138. * @attr & OPTEE_MSG_ATTR_TYPE_MASK indicates if tmem, rmem or value is used in
  139. * the union. OPTEE_MSG_ATTR_TYPE_VALUE_* indicates value,
  140. * OPTEE_MSG_ATTR_TYPE_TMEM_* indicates @tmem and
  141. * OPTEE_MSG_ATTR_TYPE_RMEM_* indicates @rmem,
  142. * OPTEE_MSG_ATTR_TYPE_NONE indicates that none of the members are used.
  143. */
  144. struct optee_msg_param {
  145. u64 attr;
  146. union {
  147. struct optee_msg_param_tmem tmem;
  148. struct optee_msg_param_rmem rmem;
  149. struct optee_msg_param_value value;
  150. } u;
  151. };
  152. /**
  153. * struct optee_msg_arg - call argument
  154. * @cmd: Command, one of OPTEE_MSG_CMD_* or OPTEE_MSG_RPC_CMD_*
  155. * @func: Trusted Application function, specific to the Trusted Application,
  156. * used if cmd == OPTEE_MSG_CMD_INVOKE_COMMAND
  157. * @session: In parameter for all OPTEE_MSG_CMD_* except
  158. * OPTEE_MSG_CMD_OPEN_SESSION where it's an output parameter instead
  159. * @cancel_id: Cancellation id, a unique value to identify this request
  160. * @ret: return value
  161. * @ret_origin: origin of the return value
  162. * @num_params: number of parameters supplied to the OS Command
  163. * @params: the parameters supplied to the OS Command
  164. *
  165. * All normal calls to Trusted OS uses this struct. If cmd requires further
  166. * information than what these field holds it can be passed as a parameter
  167. * tagged as meta (setting the OPTEE_MSG_ATTR_META bit in corresponding
  168. * attrs field). All parameters tagged as meta has to come first.
  169. *
  170. * Temp memref parameters can be fragmented if supported by the Trusted OS
  171. * (when optee_smc.h is bearer of this protocol this is indicated with
  172. * OPTEE_SMC_SEC_CAP_UNREGISTERED_SHM). If a logical memref parameter is
  173. * fragmented then has all but the last fragment the
  174. * OPTEE_MSG_ATTR_FRAGMENT bit set in attrs. Even if a memref is fragmented
  175. * it will still be presented as a single logical memref to the Trusted
  176. * Application.
  177. */
  178. struct optee_msg_arg {
  179. u32 cmd;
  180. u32 func;
  181. u32 session;
  182. u32 cancel_id;
  183. u32 pad;
  184. u32 ret;
  185. u32 ret_origin;
  186. u32 num_params;
  187. /* num_params tells the actual number of element in params */
  188. struct optee_msg_param params[0];
  189. };
  190. /**
  191. * OPTEE_MSG_GET_ARG_SIZE - return size of struct optee_msg_arg
  192. *
  193. * @num_params: Number of parameters embedded in the struct optee_msg_arg
  194. *
  195. * Returns the size of the struct optee_msg_arg together with the number
  196. * of embedded parameters.
  197. */
  198. #define OPTEE_MSG_GET_ARG_SIZE(num_params) \
  199. (sizeof(struct optee_msg_arg) + \
  200. sizeof(struct optee_msg_param) * (num_params))
  201. /*****************************************************************************
  202. * Part 2 - requests from normal world
  203. *****************************************************************************/
  204. /*
  205. * Return the following UID if using API specified in this file without
  206. * further extensions:
  207. * 384fb3e0-e7f8-11e3-af63-0002a5d5c51b.
  208. * Represented in 4 32-bit words in OPTEE_MSG_UID_0, OPTEE_MSG_UID_1,
  209. * OPTEE_MSG_UID_2, OPTEE_MSG_UID_3.
  210. */
  211. #define OPTEE_MSG_UID_0 0x384fb3e0
  212. #define OPTEE_MSG_UID_1 0xe7f811e3
  213. #define OPTEE_MSG_UID_2 0xaf630002
  214. #define OPTEE_MSG_UID_3 0xa5d5c51b
  215. #define OPTEE_MSG_FUNCID_CALLS_UID 0xFF01
  216. /*
  217. * Returns 2.0 if using API specified in this file without further
  218. * extensions. Represented in 2 32-bit words in OPTEE_MSG_REVISION_MAJOR
  219. * and OPTEE_MSG_REVISION_MINOR
  220. */
  221. #define OPTEE_MSG_REVISION_MAJOR 2
  222. #define OPTEE_MSG_REVISION_MINOR 0
  223. #define OPTEE_MSG_FUNCID_CALLS_REVISION 0xFF03
  224. /*
  225. * Get UUID of Trusted OS.
  226. *
  227. * Used by non-secure world to figure out which Trusted OS is installed.
  228. * Note that returned UUID is the UUID of the Trusted OS, not of the API.
  229. *
  230. * Returns UUID in 4 32-bit words in the same way as
  231. * OPTEE_MSG_FUNCID_CALLS_UID described above.
  232. */
  233. #define OPTEE_MSG_OS_OPTEE_UUID_0 0x486178e0
  234. #define OPTEE_MSG_OS_OPTEE_UUID_1 0xe7f811e3
  235. #define OPTEE_MSG_OS_OPTEE_UUID_2 0xbc5e0002
  236. #define OPTEE_MSG_OS_OPTEE_UUID_3 0xa5d5c51b
  237. #define OPTEE_MSG_FUNCID_GET_OS_UUID 0x0000
  238. /*
  239. * Get revision of Trusted OS.
  240. *
  241. * Used by non-secure world to figure out which version of the Trusted OS
  242. * is installed. Note that the returned revision is the revision of the
  243. * Trusted OS, not of the API.
  244. *
  245. * Returns revision in 2 32-bit words in the same way as
  246. * OPTEE_MSG_CALLS_REVISION described above.
  247. */
  248. #define OPTEE_MSG_FUNCID_GET_OS_REVISION 0x0001
  249. /*
  250. * Do a secure call with struct optee_msg_arg as argument
  251. * The OPTEE_MSG_CMD_* below defines what goes in struct optee_msg_arg::cmd
  252. *
  253. * OPTEE_MSG_CMD_OPEN_SESSION opens a session to a Trusted Application.
  254. * The first two parameters are tagged as meta, holding two value
  255. * parameters to pass the following information:
  256. * param[0].u.value.a-b uuid of Trusted Application
  257. * param[1].u.value.a-b uuid of Client
  258. * param[1].u.value.c Login class of client OPTEE_MSG_LOGIN_*
  259. *
  260. * OPTEE_MSG_CMD_INVOKE_COMMAND invokes a command a previously opened
  261. * session to a Trusted Application. struct optee_msg_arg::func is Trusted
  262. * Application function, specific to the Trusted Application.
  263. *
  264. * OPTEE_MSG_CMD_CLOSE_SESSION closes a previously opened session to
  265. * Trusted Application.
  266. *
  267. * OPTEE_MSG_CMD_CANCEL cancels a currently invoked command.
  268. *
  269. * OPTEE_MSG_CMD_REGISTER_SHM registers a shared memory reference. The
  270. * information is passed as:
  271. * [in] param[0].attr OPTEE_MSG_ATTR_TYPE_TMEM_INPUT
  272. * [| OPTEE_MSG_ATTR_FRAGMENT]
  273. * [in] param[0].u.tmem.buf_ptr physical address (of first fragment)
  274. * [in] param[0].u.tmem.size size (of first fragment)
  275. * [in] param[0].u.tmem.shm_ref holds shared memory reference
  276. * ...
  277. * The shared memory can optionally be fragmented, temp memrefs can follow
  278. * each other with all but the last with the OPTEE_MSG_ATTR_FRAGMENT bit set.
  279. *
  280. * OPTEE_MSG_CMD_UNREGISTER_SHM unregisteres a previously registered shared
  281. * memory reference. The information is passed as:
  282. * [in] param[0].attr OPTEE_MSG_ATTR_TYPE_RMEM_INPUT
  283. * [in] param[0].u.rmem.shm_ref holds shared memory reference
  284. * [in] param[0].u.rmem.offs 0
  285. * [in] param[0].u.rmem.size 0
  286. */
  287. #define OPTEE_MSG_CMD_OPEN_SESSION 0
  288. #define OPTEE_MSG_CMD_INVOKE_COMMAND 1
  289. #define OPTEE_MSG_CMD_CLOSE_SESSION 2
  290. #define OPTEE_MSG_CMD_CANCEL 3
  291. #define OPTEE_MSG_CMD_REGISTER_SHM 4
  292. #define OPTEE_MSG_CMD_UNREGISTER_SHM 5
  293. #define OPTEE_MSG_FUNCID_CALL_WITH_ARG 0x0004
  294. /*****************************************************************************
  295. * Part 3 - Requests from secure world, RPC
  296. *****************************************************************************/
  297. /*
  298. * All RPC is done with a struct optee_msg_arg as bearer of information,
  299. * struct optee_msg_arg::arg holds values defined by OPTEE_MSG_RPC_CMD_* below
  300. *
  301. * RPC communication with tee-supplicant is reversed compared to normal
  302. * client communication desribed above. The supplicant receives requests
  303. * and sends responses.
  304. */
  305. /*
  306. * Load a TA into memory, defined in tee-supplicant
  307. */
  308. #define OPTEE_MSG_RPC_CMD_LOAD_TA 0
  309. /*
  310. * Reserved
  311. */
  312. #define OPTEE_MSG_RPC_CMD_RPMB 1
  313. /*
  314. * File system access, defined in tee-supplicant
  315. */
  316. #define OPTEE_MSG_RPC_CMD_FS 2
  317. /*
  318. * Get time
  319. *
  320. * Returns number of seconds and nano seconds since the Epoch,
  321. * 1970-01-01 00:00:00 +0000 (UTC).
  322. *
  323. * [out] param[0].u.value.a Number of seconds
  324. * [out] param[0].u.value.b Number of nano seconds.
  325. */
  326. #define OPTEE_MSG_RPC_CMD_GET_TIME 3
  327. /*
  328. * Wait queue primitive, helper for secure world to implement a wait queue.
  329. *
  330. * If secure world need to wait for a secure world mutex it issues a sleep
  331. * request instead of spinning in secure world. Conversely is a wakeup
  332. * request issued when a secure world mutex with a thread waiting thread is
  333. * unlocked.
  334. *
  335. * Waiting on a key
  336. * [in] param[0].u.value.a OPTEE_MSG_RPC_WAIT_QUEUE_SLEEP
  337. * [in] param[0].u.value.b wait key
  338. *
  339. * Waking up a key
  340. * [in] param[0].u.value.a OPTEE_MSG_RPC_WAIT_QUEUE_WAKEUP
  341. * [in] param[0].u.value.b wakeup key
  342. */
  343. #define OPTEE_MSG_RPC_CMD_WAIT_QUEUE 4
  344. #define OPTEE_MSG_RPC_WAIT_QUEUE_SLEEP 0
  345. #define OPTEE_MSG_RPC_WAIT_QUEUE_WAKEUP 1
  346. /*
  347. * Suspend execution
  348. *
  349. * [in] param[0].value .a number of milliseconds to suspend
  350. */
  351. #define OPTEE_MSG_RPC_CMD_SUSPEND 5
  352. /*
  353. * Allocate a piece of shared memory
  354. *
  355. * Shared memory can optionally be fragmented, to support that additional
  356. * spare param entries are allocated to make room for eventual fragments.
  357. * The spare param entries has .attr = OPTEE_MSG_ATTR_TYPE_NONE when
  358. * unused. All returned temp memrefs except the last should have the
  359. * OPTEE_MSG_ATTR_FRAGMENT bit set in the attr field.
  360. *
  361. * [in] param[0].u.value.a type of memory one of
  362. * OPTEE_MSG_RPC_SHM_TYPE_* below
  363. * [in] param[0].u.value.b requested size
  364. * [in] param[0].u.value.c required alignment
  365. *
  366. * [out] param[0].u.tmem.buf_ptr physical address (of first fragment)
  367. * [out] param[0].u.tmem.size size (of first fragment)
  368. * [out] param[0].u.tmem.shm_ref shared memory reference
  369. * ...
  370. * [out] param[n].u.tmem.buf_ptr physical address
  371. * [out] param[n].u.tmem.size size
  372. * [out] param[n].u.tmem.shm_ref shared memory reference (same value
  373. * as in param[n-1].u.tmem.shm_ref)
  374. */
  375. #define OPTEE_MSG_RPC_CMD_SHM_ALLOC 6
  376. /* Memory that can be shared with a non-secure user space application */
  377. #define OPTEE_MSG_RPC_SHM_TYPE_APPL 0
  378. /* Memory only shared with non-secure kernel */
  379. #define OPTEE_MSG_RPC_SHM_TYPE_KERNEL 1
  380. /*
  381. * Free shared memory previously allocated with OPTEE_MSG_RPC_CMD_SHM_ALLOC
  382. *
  383. * [in] param[0].u.value.a type of memory one of
  384. * OPTEE_MSG_RPC_SHM_TYPE_* above
  385. * [in] param[0].u.value.b value of shared memory reference
  386. * returned in param[0].u.tmem.shm_ref
  387. * above
  388. */
  389. #define OPTEE_MSG_RPC_CMD_SHM_FREE 7
  390. #endif /* _OPTEE_MSG_H */