tee_drv.h 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510
  1. /* SPDX-License-Identifier: GPL-2.0-only */
  2. /*
  3. * Copyright (c) 2015-2022 Linaro Limited
  4. */
  5. #ifndef __TEE_DRV_H
  6. #define __TEE_DRV_H
  7. #include <linux/device.h>
  8. #include <linux/idr.h>
  9. #include <linux/kref.h>
  10. #include <linux/list.h>
  11. #include <linux/mod_devicetable.h>
  12. #include <linux/tee.h>
  13. #include <linux/types.h>
  14. #include <linux/uuid.h>
  15. /*
  16. * The file describes the API provided by the generic TEE driver to the
  17. * specific TEE driver.
  18. */
  19. #define TEE_SHM_DYNAMIC BIT(0) /* Dynamic shared memory registered */
  20. /* in secure world */
  21. #define TEE_SHM_USER_MAPPED BIT(1) /* Memory mapped in user space */
  22. #define TEE_SHM_POOL BIT(2) /* Memory allocated from pool */
  23. #define TEE_SHM_PRIV BIT(3) /* Memory private to TEE driver */
  24. struct device;
  25. struct tee_device;
  26. struct tee_shm;
  27. struct tee_shm_pool;
  28. /**
  29. * struct tee_context - driver specific context on file pointer data
  30. * @teedev: pointer to this drivers struct tee_device
  31. * @list_shm: List of shared memory object owned by this context
  32. * @data: driver specific context data, managed by the driver
  33. * @refcount: reference counter for this structure
  34. * @releasing: flag that indicates if context is being released right now.
  35. * It is needed to break circular dependency on context during
  36. * shared memory release.
  37. * @supp_nowait: flag that indicates that requests in this context should not
  38. * wait for tee-supplicant daemon to be started if not present
  39. * and just return with an error code. It is needed for requests
  40. * that arises from TEE based kernel drivers that should be
  41. * non-blocking in nature.
  42. * @cap_memref_null: flag indicating if the TEE Client support shared
  43. * memory buffer with a NULL pointer.
  44. */
  45. struct tee_context {
  46. struct tee_device *teedev;
  47. void *data;
  48. struct kref refcount;
  49. bool releasing;
  50. bool supp_nowait;
  51. bool cap_memref_null;
  52. };
  53. struct tee_param_memref {
  54. size_t shm_offs;
  55. size_t size;
  56. struct tee_shm *shm;
  57. };
  58. struct tee_param_value {
  59. u64 a;
  60. u64 b;
  61. u64 c;
  62. };
  63. struct tee_param {
  64. u64 attr;
  65. union {
  66. struct tee_param_memref memref;
  67. struct tee_param_value value;
  68. } u;
  69. };
  70. /**
  71. * struct tee_driver_ops - driver operations vtable
  72. * @get_version: returns version of driver
  73. * @open: called when the device file is opened
  74. * @release: release this open file
  75. * @open_session: open a new session
  76. * @close_session: close a session
  77. * @invoke_func: invoke a trusted function
  78. * @cancel_req: request cancel of an ongoing invoke or open
  79. * @supp_recv: called for supplicant to get a command
  80. * @supp_send: called for supplicant to send a response
  81. * @shm_register: register shared memory buffer in TEE
  82. * @shm_unregister: unregister shared memory buffer in TEE
  83. */
  84. struct tee_driver_ops {
  85. void (*get_version)(struct tee_device *teedev,
  86. struct tee_ioctl_version_data *vers);
  87. int (*open)(struct tee_context *ctx);
  88. void (*release)(struct tee_context *ctx);
  89. int (*open_session)(struct tee_context *ctx,
  90. struct tee_ioctl_open_session_arg *arg,
  91. struct tee_param *param);
  92. int (*close_session)(struct tee_context *ctx, u32 session);
  93. int (*invoke_func)(struct tee_context *ctx,
  94. struct tee_ioctl_invoke_arg *arg,
  95. struct tee_param *param);
  96. int (*cancel_req)(struct tee_context *ctx, u32 cancel_id, u32 session);
  97. int (*supp_recv)(struct tee_context *ctx, u32 *func, u32 *num_params,
  98. struct tee_param *param);
  99. int (*supp_send)(struct tee_context *ctx, u32 ret, u32 num_params,
  100. struct tee_param *param);
  101. int (*shm_register)(struct tee_context *ctx, struct tee_shm *shm,
  102. struct page **pages, size_t num_pages,
  103. unsigned long start);
  104. int (*shm_unregister)(struct tee_context *ctx, struct tee_shm *shm);
  105. };
  106. /**
  107. * struct tee_desc - Describes the TEE driver to the subsystem
  108. * @name: name of driver
  109. * @ops: driver operations vtable
  110. * @owner: module providing the driver
  111. * @flags: Extra properties of driver, defined by TEE_DESC_* below
  112. */
  113. #define TEE_DESC_PRIVILEGED 0x1
  114. struct tee_desc {
  115. const char *name;
  116. const struct tee_driver_ops *ops;
  117. struct module *owner;
  118. u32 flags;
  119. };
  120. /**
  121. * tee_device_alloc() - Allocate a new struct tee_device instance
  122. * @teedesc: Descriptor for this driver
  123. * @dev: Parent device for this device
  124. * @pool: Shared memory pool, NULL if not used
  125. * @driver_data: Private driver data for this device
  126. *
  127. * Allocates a new struct tee_device instance. The device is
  128. * removed by tee_device_unregister().
  129. *
  130. * @returns a pointer to a 'struct tee_device' or an ERR_PTR on failure
  131. */
  132. struct tee_device *tee_device_alloc(const struct tee_desc *teedesc,
  133. struct device *dev,
  134. struct tee_shm_pool *pool,
  135. void *driver_data);
  136. /**
  137. * tee_device_register() - Registers a TEE device
  138. * @teedev: Device to register
  139. *
  140. * tee_device_unregister() need to be called to remove the @teedev if
  141. * this function fails.
  142. *
  143. * @returns < 0 on failure
  144. */
  145. int tee_device_register(struct tee_device *teedev);
  146. /**
  147. * tee_device_unregister() - Removes a TEE device
  148. * @teedev: Device to unregister
  149. *
  150. * This function should be called to remove the @teedev even if
  151. * tee_device_register() hasn't been called yet. Does nothing if
  152. * @teedev is NULL.
  153. */
  154. void tee_device_unregister(struct tee_device *teedev);
  155. /**
  156. * tee_session_calc_client_uuid() - Calculates client UUID for session
  157. * @uuid: Resulting UUID
  158. * @connection_method: Connection method for session (TEE_IOCTL_LOGIN_*)
  159. * @connectuon_data: Connection data for opening session
  160. *
  161. * Based on connection method calculates UUIDv5 based client UUID.
  162. *
  163. * For group based logins verifies that calling process has specified
  164. * credentials.
  165. *
  166. * @return < 0 on failure
  167. */
  168. int tee_session_calc_client_uuid(uuid_t *uuid, u32 connection_method,
  169. const u8 connection_data[TEE_IOCTL_UUID_LEN]);
  170. /**
  171. * struct tee_shm - shared memory object
  172. * @ctx: context using the object
  173. * @paddr: physical address of the shared memory
  174. * @kaddr: virtual address of the shared memory
  175. * @size: size of shared memory
  176. * @offset: offset of buffer in user space
  177. * @pages: locked pages from userspace
  178. * @num_pages: number of locked pages
  179. * @refcount: reference counter
  180. * @flags: defined by TEE_SHM_* in tee_drv.h
  181. * @id: unique id of a shared memory object on this device, shared
  182. * with user space
  183. * @sec_world_id:
  184. * secure world assigned id of this shared memory object, not
  185. * used by all drivers
  186. *
  187. * This pool is only supposed to be accessed directly from the TEE
  188. * subsystem and from drivers that implements their own shm pool manager.
  189. */
  190. struct tee_shm {
  191. struct tee_context *ctx;
  192. phys_addr_t paddr;
  193. void *kaddr;
  194. size_t size;
  195. unsigned int offset;
  196. struct page **pages;
  197. size_t num_pages;
  198. refcount_t refcount;
  199. u32 flags;
  200. int id;
  201. u64 sec_world_id;
  202. };
  203. /**
  204. * struct tee_shm_pool - shared memory pool
  205. * @ops: operations
  206. * @private_data: private data for the shared memory manager
  207. */
  208. struct tee_shm_pool {
  209. const struct tee_shm_pool_ops *ops;
  210. void *private_data;
  211. };
  212. /**
  213. * struct tee_shm_pool_ops - shared memory pool operations
  214. * @alloc: called when allocating shared memory
  215. * @free: called when freeing shared memory
  216. * @destroy_pool: called when destroying the pool
  217. */
  218. struct tee_shm_pool_ops {
  219. int (*alloc)(struct tee_shm_pool *pool, struct tee_shm *shm,
  220. size_t size, size_t align);
  221. void (*free)(struct tee_shm_pool *pool, struct tee_shm *shm);
  222. void (*destroy_pool)(struct tee_shm_pool *pool);
  223. };
  224. /*
  225. * tee_shm_pool_alloc_res_mem() - Create a shm manager for reserved memory
  226. * @vaddr: Virtual address of start of pool
  227. * @paddr: Physical address of start of pool
  228. * @size: Size in bytes of the pool
  229. *
  230. * @returns pointer to a 'struct tee_shm_pool' or an ERR_PTR on failure.
  231. */
  232. struct tee_shm_pool *tee_shm_pool_alloc_res_mem(unsigned long vaddr,
  233. phys_addr_t paddr, size_t size,
  234. int min_alloc_order);
  235. /**
  236. * tee_shm_pool_free() - Free a shared memory pool
  237. * @pool: The shared memory pool to free
  238. *
  239. * The must be no remaining shared memory allocated from this pool when
  240. * this function is called.
  241. */
  242. static inline void tee_shm_pool_free(struct tee_shm_pool *pool)
  243. {
  244. pool->ops->destroy_pool(pool);
  245. }
  246. /**
  247. * tee_get_drvdata() - Return driver_data pointer
  248. * @returns the driver_data pointer supplied to tee_register().
  249. */
  250. void *tee_get_drvdata(struct tee_device *teedev);
  251. struct tee_shm *tee_shm_alloc_priv_buf(struct tee_context *ctx, size_t size);
  252. struct tee_shm *tee_shm_alloc_kernel_buf(struct tee_context *ctx, size_t size);
  253. struct tee_shm *tee_shm_register_kernel_buf(struct tee_context *ctx,
  254. void *addr, size_t length);
  255. /**
  256. * tee_shm_is_dynamic() - Check if shared memory object is of the dynamic kind
  257. * @shm: Shared memory handle
  258. * @returns true if object is dynamic shared memory
  259. */
  260. static inline bool tee_shm_is_dynamic(struct tee_shm *shm)
  261. {
  262. return shm && (shm->flags & TEE_SHM_DYNAMIC);
  263. }
  264. /**
  265. * tee_shm_free() - Free shared memory
  266. * @shm: Handle to shared memory to free
  267. */
  268. void tee_shm_free(struct tee_shm *shm);
  269. /**
  270. * tee_shm_put() - Decrease reference count on a shared memory handle
  271. * @shm: Shared memory handle
  272. */
  273. void tee_shm_put(struct tee_shm *shm);
  274. /**
  275. * tee_shm_get_va() - Get virtual address of a shared memory plus an offset
  276. * @shm: Shared memory handle
  277. * @offs: Offset from start of this shared memory
  278. * @returns virtual address of the shared memory + offs if offs is within
  279. * the bounds of this shared memory, else an ERR_PTR
  280. */
  281. void *tee_shm_get_va(struct tee_shm *shm, size_t offs);
  282. /**
  283. * tee_shm_get_pa() - Get physical address of a shared memory plus an offset
  284. * @shm: Shared memory handle
  285. * @offs: Offset from start of this shared memory
  286. * @pa: Physical address to return
  287. * @returns 0 if offs is within the bounds of this shared memory, else an
  288. * error code.
  289. */
  290. int tee_shm_get_pa(struct tee_shm *shm, size_t offs, phys_addr_t *pa);
  291. /**
  292. * tee_shm_get_size() - Get size of shared memory buffer
  293. * @shm: Shared memory handle
  294. * @returns size of shared memory
  295. */
  296. static inline size_t tee_shm_get_size(struct tee_shm *shm)
  297. {
  298. return shm->size;
  299. }
  300. /**
  301. * tee_shm_get_pages() - Get list of pages that hold shared buffer
  302. * @shm: Shared memory handle
  303. * @num_pages: Number of pages will be stored there
  304. * @returns pointer to pages array
  305. */
  306. static inline struct page **tee_shm_get_pages(struct tee_shm *shm,
  307. size_t *num_pages)
  308. {
  309. *num_pages = shm->num_pages;
  310. return shm->pages;
  311. }
  312. /**
  313. * tee_shm_get_page_offset() - Get shared buffer offset from page start
  314. * @shm: Shared memory handle
  315. * @returns page offset of shared buffer
  316. */
  317. static inline size_t tee_shm_get_page_offset(struct tee_shm *shm)
  318. {
  319. return shm->offset;
  320. }
  321. /**
  322. * tee_shm_get_id() - Get id of a shared memory object
  323. * @shm: Shared memory handle
  324. * @returns id
  325. */
  326. static inline int tee_shm_get_id(struct tee_shm *shm)
  327. {
  328. return shm->id;
  329. }
  330. /**
  331. * tee_shm_get_from_id() - Find shared memory object and increase reference
  332. * count
  333. * @ctx: Context owning the shared memory
  334. * @id: Id of shared memory object
  335. * @returns a pointer to 'struct tee_shm' on success or an ERR_PTR on failure
  336. */
  337. struct tee_shm *tee_shm_get_from_id(struct tee_context *ctx, int id);
  338. /**
  339. * tee_client_open_context() - Open a TEE context
  340. * @start: if not NULL, continue search after this context
  341. * @match: function to check TEE device
  342. * @data: data for match function
  343. * @vers: if not NULL, version data of TEE device of the context returned
  344. *
  345. * This function does an operation similar to open("/dev/teeX") in user space.
  346. * A returned context must be released with tee_client_close_context().
  347. *
  348. * Returns a TEE context of the first TEE device matched by the match()
  349. * callback or an ERR_PTR.
  350. */
  351. struct tee_context *
  352. tee_client_open_context(struct tee_context *start,
  353. int (*match)(struct tee_ioctl_version_data *,
  354. const void *),
  355. const void *data, struct tee_ioctl_version_data *vers);
  356. /**
  357. * tee_client_close_context() - Close a TEE context
  358. * @ctx: TEE context to close
  359. *
  360. * Note that all sessions previously opened with this context will be
  361. * closed when this function is called.
  362. */
  363. void tee_client_close_context(struct tee_context *ctx);
  364. /**
  365. * tee_client_get_version() - Query version of TEE
  366. * @ctx: TEE context to TEE to query
  367. * @vers: Pointer to version data
  368. */
  369. void tee_client_get_version(struct tee_context *ctx,
  370. struct tee_ioctl_version_data *vers);
  371. /**
  372. * tee_client_open_session() - Open a session to a Trusted Application
  373. * @ctx: TEE context
  374. * @arg: Open session arguments, see description of
  375. * struct tee_ioctl_open_session_arg
  376. * @param: Parameters passed to the Trusted Application
  377. *
  378. * Returns < 0 on error else see @arg->ret for result. If @arg->ret
  379. * is TEEC_SUCCESS the session identifier is available in @arg->session.
  380. */
  381. int tee_client_open_session(struct tee_context *ctx,
  382. struct tee_ioctl_open_session_arg *arg,
  383. struct tee_param *param);
  384. /**
  385. * tee_client_close_session() - Close a session to a Trusted Application
  386. * @ctx: TEE Context
  387. * @session: Session id
  388. *
  389. * Return < 0 on error else 0, regardless the session will not be
  390. * valid after this function has returned.
  391. */
  392. int tee_client_close_session(struct tee_context *ctx, u32 session);
  393. /**
  394. * tee_client_invoke_func() - Invoke a function in a Trusted Application
  395. * @ctx: TEE Context
  396. * @arg: Invoke arguments, see description of
  397. * struct tee_ioctl_invoke_arg
  398. * @param: Parameters passed to the Trusted Application
  399. *
  400. * Returns < 0 on error else see @arg->ret for result.
  401. */
  402. int tee_client_invoke_func(struct tee_context *ctx,
  403. struct tee_ioctl_invoke_arg *arg,
  404. struct tee_param *param);
  405. /**
  406. * tee_client_cancel_req() - Request cancellation of the previous open-session
  407. * or invoke-command operations in a Trusted Application
  408. * @ctx: TEE Context
  409. * @arg: Cancellation arguments, see description of
  410. * struct tee_ioctl_cancel_arg
  411. *
  412. * Returns < 0 on error else 0 if the cancellation was successfully requested.
  413. */
  414. int tee_client_cancel_req(struct tee_context *ctx,
  415. struct tee_ioctl_cancel_arg *arg);
  416. static inline bool tee_param_is_memref(struct tee_param *param)
  417. {
  418. switch (param->attr & TEE_IOCTL_PARAM_ATTR_TYPE_MASK) {
  419. case TEE_IOCTL_PARAM_ATTR_TYPE_MEMREF_INPUT:
  420. case TEE_IOCTL_PARAM_ATTR_TYPE_MEMREF_OUTPUT:
  421. case TEE_IOCTL_PARAM_ATTR_TYPE_MEMREF_INOUT:
  422. return true;
  423. default:
  424. return false;
  425. }
  426. }
  427. extern struct bus_type tee_bus_type;
  428. /**
  429. * struct tee_client_device - tee based device
  430. * @id: device identifier
  431. * @dev: device structure
  432. */
  433. struct tee_client_device {
  434. struct tee_client_device_id id;
  435. struct device dev;
  436. };
  437. #define to_tee_client_device(d) container_of(d, struct tee_client_device, dev)
  438. /**
  439. * struct tee_client_driver - tee client driver
  440. * @id_table: device id table supported by this driver
  441. * @driver: driver structure
  442. */
  443. struct tee_client_driver {
  444. const struct tee_client_device_id *id_table;
  445. struct device_driver driver;
  446. };
  447. #define to_tee_client_driver(d) \
  448. container_of(d, struct tee_client_driver, driver)
  449. /**
  450. * teedev_open() - Open a struct tee_device
  451. * @teedev: Device to open
  452. *
  453. * @return a pointer to struct tee_context on success or an ERR_PTR on failure.
  454. */
  455. struct tee_context *teedev_open(struct tee_device *teedev);
  456. /**
  457. * teedev_close_context() - closes a struct tee_context
  458. * @ctx: The struct tee_context to close
  459. */
  460. void teedev_close_context(struct tee_context *ctx);
  461. #endif /*__TEE_DRV_H*/