optee_msg.h 15 KB

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