1 /* 2 * Copyright (c) 2025 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"), 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 /** 17 * @addtogroup TeeTrusted 18 * @{ 19 * 20 * @brief TEE(Trusted Excution Environment) API. 21 * Provides security capability APIs such as trusted storage, encryption and decryption, 22 * and trusted time for trusted application development. 23 * 24 * @since 20 25 */ 26 27 /** 28 * @file tee_mem_mgmt_api.h 29 * 30 * @brief Provides APIs for memory management. 31 * 32 * @library NA 33 * @kit TEEKit 34 * @syscap SystemCapability.Tee.TeeClient 35 * @since 20 36 */ 37 38 #ifndef TEE_MEM_MGMT_API_H 39 #define TEE_MEM_MGMT_API_H 40 41 #include "tee_defines.h" 42 43 #ifdef __cplusplus 44 extern "C" { 45 #endif 46 47 /** 48 * The definitions below are defined by Global Platform or Platform SDK released previously 49 * for compatibility. 50 * Do not make any change to the content below. 51 */ 52 #ifndef ZERO_SIZE_PTR 53 54 /** 55 * @brief Represents a zero-size pointer. 56 * 57 * @since 20 58 */ 59 #define ZERO_SIZE_PTR ((void *)16) 60 61 /** 62 * @brief Checks if the pointer is either zero-size or NULL. 63 * 64 * @since 20 65 */ 66 #define zero_or_null_ptr(x) ((unsigned long)(x) <= (unsigned long)ZERO_SIZE_PTR) 67 #endif 68 69 /** 70 * @brief Defines the enumeration values for memory allocation hints. 71 * 72 * @since 20 73 */ 74 enum MALLOC_HINT { 75 /** Uninitialized buffer. */ 76 ZERO = 0, 77 /** Non-zero initialized buffer. */ 78 NOT_ZERO = 1, 79 /** 4-byte aligned buffer. */ 80 ALIGN_004 = 0x80000002, 81 /** 8-byte aligned buffer. */ 82 ALIGN_008 = 0x80000003, 83 /** 16-byte aligned buffer. */ 84 ALIGN_016 = 0x80000004, 85 /** 32-byte aligned buffer. */ 86 ALIGN_032 = 0x80000005, 87 /** 64-byte aligned buffer. */ 88 ALIGN_064 = 0x80000006, 89 /** 128-byte aligned buffer. */ 90 ALIGN_128 = 0x80000007, 91 /** 256-byte aligned buffer. */ 92 ALIGN_256 = 0x80000008, 93 /** 4-byte aligned buffer initialized to zero. */ 94 ALIGN_004_ZERO = 0x80000012, 95 /** 8-byte aligned buffer initialized to zero. */ 96 ALIGN_008_ZERO = 0x80000013, 97 /** 16-byte aligned buffer initialized to zero. */ 98 ALIGN_016_ZERO = 0x80000014, 99 /** 32-byte aligned buffer initialized to zero. */ 100 ALIGN_032_ZERO = 0x80000015, 101 /** 64-byte aligned buffer initialized to zero. */ 102 ALIGN_064_ZERO = 0x80000016, 103 /** 128-byte aligned buffer initialized to zero. */ 104 ALIGN_128_ZERO = 0x80000017, 105 /** 256-byte aligned buffer initialized to zero. */ 106 ALIGN_256_ZERO = 0x80000018, 107 }; 108 109 /** 110 * @brief Allocated memory filled with zeros. 111 * 112 * @since 20 113 */ 114 #define TEE_MALLOC_FILL_ZERO 0x00000000 115 116 /** 117 * @brief Allocated memory with no filling. 118 * 119 * @since 20 120 */ 121 #define TEE_MALLOC_NO_FILL 0x00000001 122 123 /** 124 * @brief Allocated memory that is not shareable. 125 * 126 * @since 20 127 */ 128 #define TEE_MALLOC_NO_SHARE 0x00000002 129 130 /** 131 * @brief Grants read access to memory. 132 * 133 * @since 20 134 */ 135 #define TEE_MEMORY_ACCESS_READ 0x00000001 136 137 /** 138 * @brief Grants write access to memory. 139 * 140 * @since 20 141 */ 142 #define TEE_MEMORY_ACCESS_WRITE 0x00000002 143 144 /** 145 * @brief Grants access to memory by any owner. 146 * 147 * @since 20 148 */ 149 #define TEE_MEMORY_ACCESS_ANY_OWNER 0x00000004 150 151 /** 152 * @brief Fills <b>x</b> into the first <b>size</b> bytes of the buffer. 153 * 154 * @param buffer Indicates the pointer to the buffer. 155 * @param x Indicates the value to fill. 156 * @param size Indicates the number of bytes to fill. 157 * 158 * @since 20 159 */ 160 void TEE_MemFill(void *buffer, uint8_t x, size_t size); 161 162 /** 163 * @brief Copies bytes. 164 * 165 * @param dest Indicates the pointer to the buffer that holds the bytes copied. 166 * @param src Indicates the pointer to the buffer that holds the bytes to copy. 167 * @param size Indicates the number of bytes to copy. 168 * 169 * @since 20 170 */ 171 void TEE_MemMove(void *dest, const void *src, size_t size); 172 173 /** 174 * @brief Allocates space of the specified size for an object. 175 * 176 * @param size Indicates the size of the memory to be allocated. 177 * @param hint Indicates a hint to the allocator. The value <b>0</b> indicates that the memory block 178 * returned is filled with "\0". 179 * 180 * @return Returns a pointer to the newly allocated space if the operation is successful. 181 * @return Returns a <b>NULL</b> pointer if the allocation fails. 182 * 183 * @since 20 184 */ 185 void *TEE_Malloc(size_t size, uint32_t hint); 186 187 /** 188 * @brief Releases the memory allocated by <b>TEE_Malloc</b>. 189 * 190 * If the buffer is a <b>NULL</b> pointer, <b>TEE_Free</b> does nothing. 191 * The buffer to be released must have been allocated by <b>TEE_Malloc</b> or <b>TEE_Realloc</b> and cannot be 192 * released repeatedly. Otherwise, unexpected result may be caused. 193 * 194 * @param buffer Indicates the pointer to the memory to release. 195 * 196 * @since 20 197 */ 198 void TEE_Free(void *buffer); 199 200 /** 201 * @brief Reallocates memory. 202 * 203 * If <b>new_size</b> is greater than the old size, the content of the original memory does not change 204 * and the space in excess of the old size contains unspecified content. 205 * If the new size of the memory object requires movement of the object, the space for the previous 206 * instantiation of the object is deallocated. 207 * If the space cannot be allocated, the original object remains allocated and this function 208 * returns a <b>NULL</b> pointer. 209 * If the buffer is <b>NULL</b>, this function is equivalent to <b>TEE_Malloc</b>. 210 * 211 * @param buffer Indicates the pointer to the memory to reallocate. 212 * @param new_size Indicates the new size required. 213 * 214 * @return Returns a pointer to the allocated memory if the operation is successful. 215 * @return Returns a <b>NULL</b> pointer if the operation fails. 216 * 217 * @since 20 218 */ 219 void *TEE_Realloc(void *buffer, size_t new_size); 220 221 /** 222 * @brief Compares memory content from the beginning. 223 * 224 * @param buffer1 Indicates the pointer to the first buffer. 225 * @param buffer2 Indicates the pointer to the second buffer. 226 * @param size Indicates the number of the bytes to compare. 227 * 228 * @return Returns <b>–1</b> if buffer1 < buffer2. 229 * @return Returns <b>0</b> if buffer1 == buffer2. 230 * @return Returns <b>1</b> if buffer1 > buffer2. 231 * 232 * @since 20 233 */ 234 int32_t TEE_MemCompare(const void *buffer1, const void *buffer2, size_t size); 235 236 /** 237 * @brief Checks whether this TA has the requested permissions to access a buffer. 238 * 239 * @param accessFlags Indicates the access permissions to check. 240 * @param buffer Indicates the pointer to the target buffer. 241 * @param size Indicates the size of the buffer to check. 242 * 243 * @return Returns <b>TEE_SUCCESS</b> if the TA has the requested permissions. 244 * @return Returns <b>TEE_ERROR_ACCESS_DENIED</b> otherwise. 245 * 246 * @since 20 247 */ 248 TEE_Result TEE_CheckMemoryAccessRights(uint32_t accessFlags, const void *buffer, size_t size); 249 250 /** 251 * @brief Sets the TA instance data pointer. 252 * 253 * @param instanceData Indicates the pointer to the global TA instance data. 254 * 255 * @since 20 256 */ 257 void TEE_SetInstanceData(void *instanceData); 258 259 /** 260 * @brief Obtains the instance data pointer set by the TA using <b>TEE_SetInstanceData</b>. 261 * 262 * @return Returns the pointer to the instance data set by <b>TEE_SetInstanceData</b> 263 * @return or <b>NULL</b> if no instance data pointer has been set. 264 * 265 * @since 20 266 */ 267 void *TEE_GetInstanceData(void); 268 269 #ifdef __cplusplus 270 } 271 #endif 272 273 #endif 274 /** @} */