1 /* 2 * Copyright (c) 2024 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 #ifndef TEE_MEM_MGMT_API_H 18 #define TEE_MEM_MGMT_API_H 19 20 /** 21 * @addtogroup TeeTrusted 22 * @{ 23 * 24 * @brief TEE(Trusted Excution Environment) API. 25 * Provides security capability APIs such as trusted storage, encryption and decryption, 26 * and trusted time for trusted application development. 27 * 28 * @since 12 29 */ 30 31 /** 32 * @file tee_mem_mgmt_api.h 33 * 34 * @brief Provides APIs for memory management. 35 * 36 * @library NA 37 * @kit TEEKit 38 * @syscap SystemCapability.Tee.TeeClient 39 * @since 12 40 * @version 1.0 41 */ 42 43 #include "tee_defines.h" 44 #include "tee_mem_monitoring_api.h" 45 46 #ifdef __cplusplus 47 extern "C" { 48 #endif 49 50 /* 51 * The definitions below are defined by Global Platform or Platform SDK released previously 52 * for compatibility. 53 * Do not make any change to the content below. 54 */ 55 #ifndef ZERO_SIZE_PTR 56 #define ZERO_SIZE_PTR ((void *)16) 57 #define zero_or_null_ptr(x) ((unsigned long)(x) <= (unsigned long)ZERO_SIZE_PTR) 58 #endif 59 60 enum MALLOC_HINT { 61 ZERO = 0, 62 NOT_ZERO = 1, 63 ALIGN_004 = 0x80000002, 64 /* Buffer alignment */ 65 ALIGN_008 = 0x80000003, 66 ALIGN_016 = 0x80000004, 67 ALIGN_032 = 0x80000005, 68 ALIGN_064 = 0x80000006, 69 ALIGN_128 = 0x80000007, 70 ALIGN_256 = 0x80000008, 71 ALIGN_004_ZERO = 0x80000012, 72 /* The buffer is 8-byte aligned and initialized to zeros. */ 73 ALIGN_008_ZERO = 0x80000013, 74 ALIGN_016_ZERO = 0x80000014, 75 ALIGN_032_ZERO = 0x80000015, 76 ALIGN_064_ZERO = 0x80000016, 77 ALIGN_128_ZERO = 0x80000017, 78 ALIGN_256_ZERO = 0x80000018, 79 }; 80 81 #define TEE_MALLOC_FILL_ZERO 0x00000000 82 #define TEE_MALLOC_NO_FILL 0x00000001 83 #define TEE_MALLOC_NO_SHARE 0x00000002 84 85 #define TEE_MEMORY_ACCESS_READ 0x00000001 86 #define TEE_MEMORY_ACCESS_WRITE 0x00000002 87 #define TEE_MEMORY_ACCESS_ANY_OWNER 0x00000004 88 89 #if defined(API_LEVEL) && (API_LEVEL >= API_LEVEL1_2) 90 /** 91 * @brief Fills <b>x</b> into the first <b>size</b> bytes of the buffer. 92 * 93 * @param buffer Indicates the pointer to the buffer. 94 * @param x Indicates the value to fill. 95 * @param size Indicates the number of bytes to fill. 96 * 97 * @since 12 98 * @version 1.0 99 */ 100 void TEE_MemFill(void *buffer, uint8_t x, size_t size); 101 #else 102 /** 103 * @brief Fills <b>x</b> into the first <b>size</b> bytes of the buffer. 104 * 105 * @param buffer Indicates the pointer to the buffer. 106 * @param x Indicates the value to fill. 107 * @param size Indicates the number of bytes to fill. 108 * 109 * @since 12 110 * @version 1.0 111 */ 112 void TEE_MemFill(void *buffer, uint32_t x, size_t size); 113 #endif 114 115 /** 116 * @brief Copies bytes. 117 * 118 * @param dest Indicates the pointer to the buffer that holds the bytes copied. 119 * @param src Indicates the pointer to the buffer that holds the bytes to copy. 120 * @param size Indicates the number of bytes to copy. 121 * 122 * @since 12 123 * @version 1.0 124 */ 125 void TEE_MemMove(void *dest, const void *src, size_t size); 126 127 /** 128 * @brief Allocates space of the specified size for an object. 129 * 130 * @param size Indicates the size of the memory to be allocated. 131 * @param hint Indicates a hint to the allocator. The value <b>0</b> indicates that the memory block 132 * returned is filled with "\0". 133 * 134 * @return Returns a pointer to the newly allocated space if the operation is successful. 135 * @return Returns a <b>NULL</b> pointer if the allocation fails. 136 * 137 * @since 12 138 * @version 1.0 139 */ 140 void *TEE_Malloc(size_t size, uint32_t hint); 141 142 /** 143 * @brief Releases the memory allocated by <b>TEE_Malloc</b>. 144 * 145 * If the buffer is a <b>NULL</b> pointer, <b>TEE_Free</b> does nothing. 146 * The buffer to be released must have been allocated by <b>TEE_Malloc</b> or <b>TEE_Realloc</b> and cannot be 147 * released repeatedly. Otherwise, unexpected result may be caused. 148 * 149 * @param buffer Indicates the pointer to the memory to release. 150 * 151 * @since 12 152 * @version 1.0 153 */ 154 void TEE_Free(void *buffer); 155 156 /** 157 * @brief Reallocates memory. 158 * 159 * If <b>new_size</b> is greater than the old size, the content of the original memory does not change 160 * and the space in excess of the old size contains unspecified content. 161 * If the new size of the memory object requires movement of the object, the space for the previous 162 * instantiation of the object is deallocated. 163 * If the space cannot be allocated, the original object remains allocated and this function 164 * returns a <b>NULL</b> pointer. 165 * If the buffer is <b>NULL</b>, this function is equivalent to <b>TEE_Malloc</b>. 166 * 167 * @param buffer Indicates the pointer to the memory to reallocate. 168 * @param new_size Indicates the new size required. 169 * 170 * @return Returns a pointer to the allocated memory if the operation is successful. 171 * @return Returns a <b>NULL</b> pointer if the operation fails. 172 * 173 * @since 12 174 * @version 1.0 175 */ 176 void *TEE_Realloc(void *buffer, size_t new_size); 177 178 /** 179 * @brief Compares memory content from the beginning. 180 * 181 * @param buffer1 Indicates the pointer to the first buffer. 182 * @param buffer2 Indicates the pointer to the second buffer. 183 * @param size Indicates the number of the bytes to compare. 184 * 185 * @return Returns <b>–1</b> if buffer1 < buffer2. 186 * @return Returns <b>0</b> if buffer1 == buffer2. 187 * @return Returns <b>1</b> if buffer1 > buffer2. 188 * 189 * @since 12 190 * @version 1.0 191 */ 192 int32_t TEE_MemCompare(const void *buffer1, const void *buffer2, size_t size); 193 194 /** 195 * @brief Checks whether this TA has the requested permissions to access a buffer. 196 * 197 * @param accessFlags Indicates the access permissions to check. 198 * @param buffer Indicates the pointer to the target buffer. 199 * @param size Indicates the size of the buffer to check. 200 * 201 * @return Returns <b>TEE_SUCCESS</b> if the TA has the requested permissions. 202 * @return Returns <b>TEE_ERROR_ACCESS_DENIED</b> otherwise. 203 */ 204 TEE_Result TEE_CheckMemoryAccessRights(uint32_t accessFlags, const void *buffer, size_t size); 205 206 /** 207 * @brief Sets the TA instance data pointer. 208 * 209 * @param instanceData Indicates the pointer to the global TA instance data. 210 * 211 * @since 12 212 * @version 1.0 213 */ 214 void TEE_SetInstanceData(void *instanceData); 215 216 /** 217 * @brief Obtains the instance data pointer set by the TA using <b>TEE_SetInstanceData</b>. 218 * 219 * @return Returns the pointer to the instance data set by <b>TEE_SetInstanceData</b> 220 * @return or <b>NULL</b> if no instance data pointer has been set. 221 * 222 * @since 12 223 * @version 1.0 224 */ 225 void *TEE_GetInstanceData(void); 226 227 #ifdef __cplusplus 228 } 229 #endif 230 /** @} */ 231 #endif