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 47extern "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 60enum 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 */ 100void 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 */ 112void 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 */ 125void 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 */ 140void *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 */ 154void 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 */ 176void *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 */ 192int32_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 */ 204TEE_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 */ 214void 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 */ 225void *TEE_GetInstanceData(void); 226 227#ifdef __cplusplus 228} 229#endif 230/** @} */ 231#endif