1 /* 2 * Copyright (c) 2023 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 memory 18 * @{ 19 * 20 * @brief provides memory management capabilities 21 * 22 * provides features include operations such as memory alloction, memory free, and so on 23 * 24 * @since 10 25 * @version 1.0 26 */ 27 28 /** 29 * @file purgeable_memory.h 30 * 31 * @brief provides memory management capabilities of purgeable memory. 32 * 33 * provides features include create, begin read ,end read, begin write, end write, rebuild, and so on. 34 * when using, it is necessary to link libpurgeable_memory_ndk.z.so 35 * 36 * @library libpurgeablemem.z.so 37 * @syscap SystemCapability.Kernel.Memory 38 * @kit KernelEnhanceKit 39 * @since 10 40 * @version 1.0 41 */ 42 43 #ifndef OHOS_UTILS_MEMORY_LIBPURGEABLEMEM_C_INCLUDE_PURGEABLE_MEMORY_H 44 #define OHOS_UTILS_MEMORY_LIBPURGEABLEMEM_C_INCLUDE_PURGEABLE_MEMORY_H 45 46 #include <stdbool.h> /* bool */ 47 #include <stddef.h> /* size_t */ 48 49 #ifdef __cplusplus 50 extern "C" { 51 #endif /* End of #ifdef __cplusplus */ 52 53 /** 54 * @brief Purgeable mem struct 55 * 56 * @since 10 57 * @version 1.0 58 */ 59 typedef struct PurgMem OH_PurgeableMemory; 60 61 /** 62 * @brief: function pointer, it points to a function which is used to build content of a PurgMem obj. 63 * 64 * 65 * @param void *: data ptr, points to start address of a PurgMem obj's content. 66 * @param size_t Data size of the content. 67 * @param void *: other private parameters. 68 * @return: build content result, true means success, while false is fail. 69 * 70 * @since 10 71 * @version 1.0 72 */ 73 typedef bool (*OH_PurgeableMemory_ModifyFunc)(void *, size_t, void *); 74 75 /** 76 * @brief: create a PurgMem obj. 77 * 78 * 79 * @param size Data size of a PurgMem obj's content. 80 * @param func Function pointer, it is used to recover data when the PurgMem obj's content is purged. 81 * @param funcPara Parameters used by @func. 82 * @return: a PurgMem obj. 83 * 84 * @since 10 85 * @version 1.0 86 */ 87 OH_PurgeableMemory *OH_PurgeableMemory_Create( 88 size_t size, OH_PurgeableMemory_ModifyFunc func, void *funcPara); 89 90 /** 91 * @brief: destroy a PurgMem obj. 92 * 93 * 94 * @param purgObj A PurgMem obj to be destroyed. 95 * @return: true is success, while false is fail. return true if @purgObj is NULL. 96 * If return true, @purgObj will be set to NULL to avoid Use-After-Free. 97 * 98 * @since 10 99 * @version 1.0 100 */ 101 bool OH_PurgeableMemory_Destroy(OH_PurgeableMemory *purgObj); 102 103 /** 104 * @brief: begin read a PurgMem obj. 105 * 106 * 107 * @param purgObj A PurgMem obj. 108 * @return: return true if @purgObj's content is present. 109 * If content is purged(no present), system will recover its data, 110 * return false if content is purged and recovered failed. 111 * While return true if content recover success. 112 * OS cannot reclaim the memory of @purgObj's content when this 113 * function return true, until PurgMemEndRead() is called. 114 * 115 * @since 10 116 * @version 1.0 117 */ 118 bool OH_PurgeableMemory_BeginRead(OH_PurgeableMemory *purgObj); 119 120 /** 121 * @brief: end read a PurgMem obj. 122 * 123 * 124 * @param purgObj A PurgMem obj. 125 * OS may reclaim the memory of @purgObj's content 126 * at a later time when this function returns. 127 * 128 * @since 10 129 * @version 1.0 130 */ 131 void OH_PurgeableMemory_EndRead(OH_PurgeableMemory *purgObj); 132 133 /** 134 * @brief: begin write a PurgMem obj. 135 * 136 * 137 * @param purgObj A PurgMem obj. 138 * @return: return true if @purgObj's content is present. 139 * if content is purged(no present), system will recover its data, 140 * return false if content is purged and recovered failed. 141 * While return true if content is successfully recovered. 142 * OS cannot reclaim the memory of @purgObj's content when this 143 * function return true, until PurgMemEndWrite() is called. 144 * 145 * @since 10 146 * @version 1.0 147 */ 148 bool OH_PurgeableMemory_BeginWrite(OH_PurgeableMemory *purgObj); 149 150 /** 151 * @brief: end write a PurgMem obj. 152 * 153 * 154 * @param purgObj A PurgMem obj. 155 * OS may reclaim the memory of @purgObj's content 156 * at a later time when this function returns. 157 * 158 * @since 10 159 * @version 1.0 160 */ 161 void OH_PurgeableMemory_EndWrite(OH_PurgeableMemory *purgObj); 162 163 /** 164 * @brief: get content ptr of a PurgMem obj. 165 * 166 * 167 * @param purgObj A PurgMem obj. 168 * @return: return start address of a PurgMem obj's content. 169 * Return NULL if @purgObj is NULL. 170 * This function should be protect by PurgMemBeginRead()/PurgMemEndRead() 171 * or PurgMemBeginWrite()/PurgMemEndWrite() 172 * 173 * @since 10 174 * @version 1.0 175 */ 176 void *OH_PurgeableMemory_GetContent(OH_PurgeableMemory *purgObj); 177 178 /** 179 * @brief: get content size of a PurgMem obj. 180 * 181 * 182 * @param purgObj A PurgMem obj. 183 * @return: return content size of @purgObj. 184 * Return 0 if @purgObj is NULL. 185 * 186 * @since 10 187 * @version 1.0 188 */ 189 size_t OH_PurgeableMemory_ContentSize(OH_PurgeableMemory *purgObj); 190 191 /** 192 * @brief: append a modify to a PurgMem obj. 193 * 194 * 195 * @param purgObj A PurgMem obj. 196 * @param func Function pointer, it will modify content of @PurgMem. 197 * @param funcPara Parameters used by @func. 198 * @return: append result, true is success, while false is fail. 199 * 200 * @since 10 201 * @version 1.0 202 */ 203 bool OH_PurgeableMemory_AppendModify(OH_PurgeableMemory *purgObj, 204 OH_PurgeableMemory_ModifyFunc func, void *funcPara); 205 206 #ifdef __cplusplus 207 } 208 #endif /* End of #ifdef __cplusplus */ 209 #endif /* OHOS_UTILS_MEMORY_LIBPURGEABLEMEM_C_INCLUDE_PURGEABLE_MEMORY_H */ 210 /** @} */