README.tee 4.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112
  1. =============
  2. TEE uclass
  3. =============
  4. This document describes the TEE uclass in U-Boot
  5. A TEE (Trusted Execution Environment) is a trusted OS running in some
  6. secure environment, for example, TrustZone on ARM CPUs, or a separate
  7. secure co-processor etc. A TEE driver handles the details needed to
  8. communicate with the TEE.
  9. This uclass deals with:
  10. - Registration of TEE drivers
  11. - Managing shared memory between U-Boot and the TEE
  12. - Providing a generic API to the TEE
  13. The TEE interface
  14. =================
  15. include/tee.h defines the generic interface to a TEE.
  16. A client finds the TEE device via tee_find_device(). Other important functions
  17. when interfacing with a TEE are:
  18. - tee_shm_alloc(), tee_shm_register() and tee_shm_free() to manage shared
  19. memory objects often needed when communicating with the TEE.
  20. - tee_get_version() lets the client know which the capabilities of the TEE
  21. device.
  22. - tee_open_session() opens a session to a Trusted Application
  23. - tee_invoke_func() invokes a function in a Trusted Application
  24. - tee_close_session() closes a session to a Trusted Application
  25. Much of the communication between clients and the TEE is opaque to the
  26. driver. The main job for the driver is to receive requests from the
  27. clients, forward them to the TEE and send back the results.
  28. OP-TEE driver
  29. =============
  30. The OP-TEE driver handles OP-TEE [1] based TEEs. Currently it is only the ARM
  31. TrustZone based OP-TEE solution that is supported.
  32. Lowest level of communication with OP-TEE builds on ARM SMC Calling
  33. Convention (SMCCC) [2], which is the foundation for OP-TEE's SMC interface
  34. [3] used internally by the driver. Stacked on top of that is OP-TEE Message
  35. Protocol [4].
  36. OP-TEE SMC interface provides the basic functions required by SMCCC and some
  37. additional functions specific for OP-TEE. The most interesting functions are:
  38. - OPTEE_SMC_FUNCID_CALLS_UID (part of SMCCC) returns the version information
  39. which is then returned by TEE_IOC_VERSION
  40. - OPTEE_SMC_CALL_GET_OS_UUID returns the particular OP-TEE implementation, used
  41. to tell, for instance, a TrustZone OP-TEE apart from an OP-TEE running on a
  42. separate secure co-processor.
  43. - OPTEE_SMC_CALL_WITH_ARG drives the OP-TEE message protocol
  44. - OPTEE_SMC_GET_SHM_CONFIG lets the driver and OP-TEE agree on which memory
  45. range to used for shared memory between Linux and OP-TEE.
  46. The GlobalPlatform TEE Client API [5] is implemented on top of the generic
  47. TEE API.
  48. Picture of the relationship between the different components in the
  49. OP-TEE architecture:
  50. U-Boot Secure world
  51. ~~~~~~ ~~~~~~~~~~~~
  52. +------------+ +-------------+
  53. | Client | | Trusted |
  54. | | | Application |
  55. +------------+ +-------------+
  56. /\ /\
  57. || ||
  58. \/ \/
  59. +------------+ +-------------+
  60. | TEE | | TEE Internal|
  61. | uclass | | API |
  62. +------------+ +-------------+
  63. | OP-TEE | | OP-TEE |
  64. | driver | | Trusted OS |
  65. +------------+-----------+-------------+
  66. | OP-TEE MSG |
  67. | SMCCC (OPTEE_SMC_CALL_*) |
  68. +--------------------------------------+
  69. RPC (Remote Procedure Call) are requests from secure world to the driver.
  70. An RPC is identified by a special range of SMCCC return values from
  71. OPTEE_SMC_CALL_WITH_ARG.
  72. References
  73. ==========
  74. [1] https://github.com/OP-TEE/optee_os
  75. [2] http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html
  76. [3] drivers/tee/optee/optee_smc.h
  77. [4] drivers/tee/optee/optee_msg.h
  78. [5] http://www.globalplatform.org/specificationsdevice.asp look for
  79. "TEE Client API Specification v1.0" and click download.