include/trustzone/kree/mem.h

   1 /*
   2  * Header files for KREE memory related functions.
   3  */
   4
   5 #ifndef __KREE_MEM_H__
   6 #define __KREE_MEM_H__
   7
   8 #ifdef CONFIG_MTK_IN_HOUSE_TEE_SUPPORT
   9
  10 #include "trustzone/tz_cross/trustzone.h"
  11
  12
  13 /// KREE session handle type.
  14 typedef void* KREE_SESSION_HANDLE;
  15
  16 #define KREE_SESSION_HANDLE_NULL    ((KREE_SESSION_HANDLE)0)
  17 #define KREE_SESSION_HANDLE_FAIL    ((KREE_SESSION_HANDLE)-1)
  18
  19 /**
  20  * Memory handle define
  21  *
  22  * Handle is used to communicate with normal world:
  23  * 1. Memory information can not expose to normal world. (Major, important!)
  24  * 2. Too many informations, and thet can be grouped by handle.
  25  *
  26  * All kinds of memory use the same handle define.
  27  * According to their different purpose, they are redefined to specific name.
  28  * Just for easy programming.
  29  */
  30
  31 // Shared memory handle define
  32 typedef uint32_t KREE_SHAREDMEM_HANDLE;
  33
  34 // Secure memory handle define
  35 typedef uint32_t KREE_SECUREMEM_HANDLE;
  36
  37 // Secure chunk memory handle define
  38 typedef uint32_t KREE_SECURECM_HANDLE;
  39
  40 // Release Secure chunk memory handle define
  41 typedef uint32_t KREE_RELEASECM_HANDLE;
  42
  43 /**
  44  * Shared memory parameter
  45  *
  46  * It defines the types for shared memory.
  47  *
  48  * @param buffer    A pointer to shared memory buffer
  49  * @param size    shared memory size in bytes
  50  */
  51 typedef struct {
  52     void* buffer;
  53     uint32_t size;
  54 } KREE_SHAREDMEM_PARAM;
  55
  56 // map_p: 0 = no remap, 1 = remap
  57 TZ_RESULT kree_register_sharedmem (KREE_SESSION_HANDLE session, KREE_SHAREDMEM_HANDLE *mem_handle,
  58     uint32_t start, uint32_t size, uint32_t map_p);
  59
  60 TZ_RESULT kree_unregister_sharedmem (KREE_SESSION_HANDLE session, KREE_SHAREDMEM_HANDLE mem_handle);
  61
  62 /**
  63  * Shared memory
  64  *
  65  * A shared memory is normal memory, which can be seen by Normal world and Secure world.
  66  * It is used to create the comminicattion between two worlds.
  67  * Currently, zero-copy data transfer is supportted, for simple and efficient design.
  68  *
  69  * The shared memory lifetime:
  70  * 1. CA (Client Application at REE) prepares memory
  71  * 2. CA registers it to TEE scope.
  72  * 3. A handle is returned. CA can use it to communicate with TEE.
  73  * 4. If shared memory is not used, CA unregisters it.
  74  * 5. CA frees memory.
  75  *
  76  * Because it is zero-copy shared memory, the memory characteritics is inherited.
  77  * If the shared memory will be used for HW, CA must allocate physical continuous memory.
  78  *
  79  * Note: Because shared memory can be seen by both Normal and Secure world.
  80  * It is a possible weakpoint to bed attacked or leak secure data.
  81  *
  82  * Note: ONLY support memory allocated by kmalloc!!!
  83  */
  84
  85 /**
  86  * Register shared memory
  87  *
  88  * @param session    The session handle.
  89  * @param shm_handle    [out] A pointer to shared memory handle.
  90  * @param param    A pointer to shared memory parameters.
  91  * @return    return code.
  92  */
  93 TZ_RESULT KREE_RegisterSharedmem (    KREE_SESSION_HANDLE session,
  94     KREE_SHAREDMEM_HANDLE *shm_handle, KREE_SHAREDMEM_PARAM *param);
  95
  96
  97 /**
  98  * Unregister shared memory
  99  *
 100  * @param session    The session handle.
 101  * @param shm_handle    The shared memory handle.
 102  * @return    return code.
 103  */
 104 TZ_RESULT KREE_UnregisterSharedmem (KREE_SESSION_HANDLE session, KREE_SHAREDMEM_HANDLE shm_handle);
 105
 106 /**
 107  * Secure memory
 108  *
 109  * A secure memory can be seen only in Secure world.
 110  * Secure memory, here, is defined as external memory (ex: DRAM) protected by trustzone.
 111  * It can protect from software attack very well, but can not protect from physical attack, like memory probe.
 112  * CA (Client Application at REE) can ask TEE for a secure buffer, then control it:
 113  * to reference, or to free...etc.
 114  *
 115  * Secure memory spec.:
 116  * 1. Protected by trustzone (NS = 0).
 117  * 2. External memory (ex: external DRAM).
 118  * 3. With cache.
 119  */
 120
 121 /**
 122  * Secure memory allocation
 123  *
 124  * Allocate one memory.
 125  * If memory is allocated successfully, a handle will be provided.
 126  *
 127  * Memory lifetime:
 128  * 1. Allocate memory, and get the handle.
 129  * 2. If other process wants to use the same memory, reference it.
 130  * 3. If they stop to use it, unreference it.
 131  * 4. Free it (by unreference), if it is not used.
 132  *
 133  * Simple rules:
 134  * 1. start by allocate, end by unreference (for free).
 135  * 2. start by reference, end by unreference.
 136  *
 137  * @param session    The session handle.
 138  * @param mem_handle    [out] A pointer to secure memory handle.
 139  * @param alignment    Memory alignment in bytes.
 140  * @param size    The size of the buffer to be allocated in bytes.
 141  * @return    return code.
 142  */
 143 TZ_RESULT KREE_AllocSecuremem (KREE_SESSION_HANDLE session,
 144     KREE_SECUREMEM_HANDLE *mem_handle, uint32_t alignment, uint32_t size);
 145
 146 /**
 147  * Secure memory reference
 148  *
 149  * Reference memory.
 150  * Referen count will be increased by 1 after reference.
 151  *
 152  * Reference lifetime:
 153  * 1. Reference the memory before using it, if the memory is allocated by other process.
 154  * 2. Unreference it if it is not used.
 155  *
 156  * @param session    The session handle.
 157  * @param mem_handle    The secure memory handle.
 158  * @param return    return code.
 159  */
 160 TZ_RESULT KREE_ReferenceSecuremem (KREE_SESSION_HANDLE session, KREE_SECUREMEM_HANDLE mem_handle);
 161
 162 /**
 163  * Secure memory unreference
 164  *
 165  * Unreference memory.
 166  * Reference count will be decreased by 1 after unreference.
 167  * Once reference count is zero, memory will be freed.
 168  *
 169  * @param session    The session handle.
 170  * @param mem_handle    The secure memory handle.
 171  * @param return    return code.
 172  */
 173 TZ_RESULT KREE_UnreferenceSecuremem (KREE_SESSION_HANDLE session, KREE_SECUREMEM_HANDLE mem_handle);
 174
 175 /**
 176  * Secure chunk memory
 177  *
 178  * A secure chunk memory can be seen only in Secure world.
 179  * It is a kind of secure memory but with difference characteristic:
 180  * 1. It is designed and optimized for chunk memory usage.
 181  * 2. For future work, it can be released as normal memory for more flexible memory usage.
 182  *
 183  * Secure chunk memory spec.:
 184  * 1. Protected by trustzone (NS = 0).
 185  * 2. External memory (ex: external DRAM).
 186  * 3. With cache.
 187  * 4. For future, it can be released to normal world.
 188  */
 189
 190 /**
 191  * Secure chunk memory allocation
 192  *
 193  * Allocate one memory.
 194  * If memory is allocated successfully, a handle will be provided.
 195  *
 196  * Memory lifetime:
 197  * 1. Allocate memory, and get the handle.
 198  * 2. If other process wants to use the same memory, reference it.
 199  * 3. If they stop to use it, unreference it.
 200  * 4. Free it (by unreference), if it is not used.
 201  *
 202  * Simple rules:
 203  * 1. start by allocate, end by unreference (for free).
 204  * 2. start by reference, end by unreference.
 205  *
 206  * @param session    The session handle.
 207  * @param cm_handle    [out] A pointer to secure chunk memory handle.
 208  * @param alignment    Memory alignment in bytes.
 209  * @param size    The size of the buffer to be allocated in bytes.
 210
 211  * @return    return code.
 212  */
 213 TZ_RESULT KREE_AllocSecurechunkmem (KREE_SESSION_HANDLE session,
 214     KREE_SECURECM_HANDLE *cm_handle, uint32_t alignment, uint32_t size);
 215
 216 /**
 217  * Secure chunk memory reference
 218  *
 219  * Reference memory.
 220  * Referen count will be increased by 1 after reference.
 221  *
 222  * Reference lifetime:
 223  * 1. Reference the memory before using it, if the memory is allocated by other process.
 224  * 2. Unreference it if it is not used.
 225  *
 226  * @param session    The session handle.
 227  * @param cm_handle    The secure chunk memory handle.
 228  * @param return    return code.
 229  */
 230 TZ_RESULT KREE_ReferenceSecurechunkmem (KREE_SESSION_HANDLE session, KREE_SECURECM_HANDLE cm_handle);
 231
 232 /**
 233  * Secure chunk memory unreference
 234  *
 235  * Unreference memory.
 236  * Reference count will be decreased by 1 after unreference.
 237  * Once reference count is zero, memory will be freed.
 238  *
 239  * @param session    The session handle.
 240  * @param cm_handle    The secure chunk memory handle.
 241  * @param return    return code.
 242  */
 243 TZ_RESULT KREE_UnreferenceSecurechunkmem (KREE_SESSION_HANDLE session, KREE_SECURECM_HANDLE cm_handle);
 244
 245 /**
 246  * Released secure chunk memory Read
 247  *
 248  * Read release secure chunk memory for normal world usage.
 249  *
 250  * @param session    The session handle.
 251  * @param offset    offset in bytes.
 252  * @param size    size in bytes.
 253  * @param buffer    The pointer to read buffer.
 254  * @param return    return code.
 255  */
 256 TZ_RESULT KREE_ReadSecurechunkmem (KREE_SESSION_HANDLE session, uint32_t offset, uint32_t size, void *buffer);
 257
 258 /**
 259  * Released secure chunk memory Write
 260  *
 261  * Write release secure chunk memory for normal world usage.
 262  *
 263  * @param session    The session handle.
 264  * @param offset    offset in bytes.
 265  * @param size    size in bytes.
 266  * @param buffer    The pointer to write buffer.
 267  * @param return    return code.
 268  */
 269 TZ_RESULT KREE_WriteSecurechunkmem (KREE_SESSION_HANDLE session, uint32_t offset, uint32_t size, void *buffer);
 270
 271 /**
 272  * Released secure chunk memory get size
 273  *
 274  * Get released secure chunk memory for normal world usage size.
 275  *
 276  * @param session    The session handle.
 277  * @param size    [out] The pointer to size in bytes.
 278  * @param return    return code.
 279  */
 280 TZ_RESULT KREE_GetSecurechunkReleaseSize (KREE_SESSION_HANDLE session, uint32_t *size);
 281
 282
 283 /**
 284  * Get TEE memory size
 285  *
 286  * Get the total memory size of trusted execution environment
 287  *
 288  * @param session    The session handle.
 289  * @param size    [out] The pointer to size in bytes.
 290  * @param return    return code.
 291  */
 292 TZ_RESULT KREE_GetTEETotalSize (KREE_SESSION_HANDLE session, uint32_t *size);
 293
 294 #endif /* CONFIG_MTK_IN_HOUSE_TEE_SUPPORT */
 295 #endif /* __KREE_MEM_H__ */