1 /* SPDX-License-Identifier: BSD-3-Clause */ 2 /* Copyright(c) 2007-2022 Intel Corporation */ 3 /** 4 *************************************************************************** 5 * @file lac_mem_pools.h 6 * 7 * @defgroup LacMemPool Memory Pool Mgmt 8 * 9 * @ingroup LacCommon 10 * 11 * Memory Pool creation and mgmt functions 12 * 13 * @lld_start 14 * @lld_overview 15 * This component is designed as a set of utility functions for the 16 * creation of pre-allocated memory pools. Each pool will be created using OS 17 * memory with a user specified number of elements, element size and element 18 * alignment(alignmnet is at byte granularity). 19 * @lld_dependencies 20 * These utilities rely on QAT Utils for locking mechanisms and memory 21 *allocation 22 * @lld_initialisation 23 * Pool creation needs to be done by each component. There is no specific 24 * initialisation required for this feature. 25 * @lld_module_algorithms 26 * The following is a diagram of how the memory is layed out for each block 27 * in a pool. Each element must be aligned on the boundary requested for in the 28 * create call. In order to hide the management of the pools from the user, 29 * the memory block data is hidden prior to the 30 * data pointer. This way it can be accessed easily on a free call with pointer 31 * arithmatic. The Padding at the start is simply there for alignment and is 32 * unused in the pools. 33 * 34 * ------------------------------------------------------- 35 * 36 * |Padding |lac_mem_blk_t | client memory | 37 * 38 * @lld_process_context 39 * @lld_end 40 ***************************************************************************/ 41 42 /** 43 ******************************************************************************* 44 * @ingroup LacMemPool 45 * 46 * 47 ******************************************************************************/ 48 49 /***************************************************************************/ 50 51 #ifndef LAC_MEM_POOLS_H 52 #define LAC_MEM_POOLS_H 53 54 #include "cpa.h" 55 #include "lac_common.h" 56 struct lac_mem_pool_hdr_s; 57 /**< @ingroup LacMemPool 58 * This is a forward declaration of the structure type lac_mem_pool_hdr_s */ 59 60 typedef LAC_ARCH_UINT lac_memory_pool_id_t; 61 /**< @ingroup LacMemPool 62 * Pool ID type to be used by all clients */ 63 64 /**< @ingroup LacMemPool 65 * This structure is used to link each memory block in the created pool 66 * together and contain the necessary information for deletion of the block 67 */ 68 typedef struct lac_mem_blk_s { 69 CpaPhysicalAddr physDataPtr; 70 /**< physical address of data pointer for client */ 71 void *pMemAllocPtr; 72 /**< virtual address of the memory block actually allocated */ 73 CpaBoolean isInUse; 74 /**< indicates if the pool item is in use */ 75 struct lac_mem_blk_s *pNext; 76 /**< link to next blcok in the pool */ 77 struct lac_mem_pool_hdr_s *pPoolID; 78 /**< identifier of the pool that this block was allocated from */ 79 } lac_mem_blk_t; 80 81 #define LAC_MEM_POOL_VIRT_TO_PHYS(pVirtAddr) \ 82 (((lac_mem_blk_t *)((LAC_ARCH_UINT)pVirtAddr - sizeof(lac_mem_blk_t))) \ 83 ->physDataPtr) 84 /**< @ingroup LacMemPool 85 * macro for retreiving the physical address of the memory block. */ 86 87 #define LAC_MEM_POOL_INIT_POOL_ID 0 88 /**< @ingroup LacMemPool 89 * macro which defines the valid initialisation value for a pool ID. This is 90 * used as a level of abstraction for the user of this interface */ 91 92 /** 93 ******************************************************************************* 94 * @ingroup LacMemPool 95 * This function creates a memory pool containing a specified number of 96 * elements of specific size and byte alignment. This function is not reentrant 97 * or thread safe and is only intended to be called during initialisation. 98 * 99 * @blocking 100 * Yes 101 * @reentrant 102 * No 103 * @threadSafe 104 * No 105 * @param[out] poolID on successful creation of a pool this will 106 * be the ID used for all subsequent accesses 107 * @param[in] poolName The name of the memory pool 108 * @param[in] numElementsInPool number of elements to provision in the pool 109 * @param[in] blkSizeInBytes size in bytes of each element in the pool 110 * @param[in] blkAlignmentInBytes byte alignment required for each element 111 * @param[in] trackMemory track the memory in use by this pool 112 * @param[in] node node to allocate from 113 * 114 * @retval CPA_STATUS_INVALID_PARAM invalid input parameter 115 * @retval CPA_STATUS_RESOURCE error in provisioning resources 116 * @retval CPA_STATUS_SUCCESS function executed successfully 117 * 118 ******************************************************************************/ 119 CpaStatus Lac_MemPoolCreate(lac_memory_pool_id_t *poolID, 120 char *poolName, 121 unsigned int numElementsInPool, 122 unsigned int blkSizeInBytes, 123 unsigned int blkAlignmentInBytes, 124 CpaBoolean trackMemory, 125 Cpa32U node); 126 127 /** 128 ******************************************************************************* 129 * @ingroup LacMemPool 130 * This function will destroy the memory pool in it's current state. All memory 131 * blocks which have been returned to the memory pool will be de-allocated and 132 * the pool indetifier will be freed and assigned to NULL. It is the 133 * responsibility of the pool creators to return all memory before a destroy or 134 * memory will be leaked. 135 * 136 * @blocking 137 * Yes 138 * @reentrant 139 * No 140 * @threadSafe 141 * No 142 143 * @param[in] poolID Pointer to the memory pool to destroy 144 * 145 ******************************************************************************/ 146 void Lac_MemPoolDestroy(lac_memory_pool_id_t poolID); 147 148 /** 149 ******************************************************************************* 150 * @ingroup LacMemPool 151 * This function allocates a block from the pool which has been previously 152 * created. It does not check the validity of the pool Id prior to accessing the 153 * pool. It is up to the calling code to ensure the value is correct. 154 * 155 * @blocking 156 * Yes 157 * @reentrant 158 * Yes 159 * @threadSafe 160 * Yes 161 * @param[in] poolID ID of the pool to allocate memory from 162 * 163 * @retval pointer to the memory which has been allocated from the pool 164 * 165 ******************************************************************************/ 166 void *Lac_MemPoolEntryAlloc(lac_memory_pool_id_t poolID); 167 168 /** 169 ******************************************************************************* 170 * @ingroup LacMemPool 171 * This function de-allocates the memory passed in back to the pool from which 172 * it was allocated. 173 * 174 * @blocking 175 * Yes 176 * @reentrant 177 * Yes 178 * @threadSafe 179 * Yes 180 * @param[in] entry memory address of the block to be freed 181 * 182 ******************************************************************************/ 183 void Lac_MemPoolEntryFree(void *entry); 184 185 /** 186 ******************************************************************************* 187 * @ingroup LacMemPool 188 * This function returns the number of available entries in a particular pool 189 * 190 * @blocking 191 * No 192 * @reentrant 193 * No 194 * @threadSafe 195 * No 196 * @param[in] poolID ID of the pool 197 * 198 * @retval number of elements left for allocation from the pool 199 * 200 ******************************************************************************/ 201 unsigned int Lac_MemPoolAvailableEntries(lac_memory_pool_id_t poolID); 202 203 /** 204 ******************************************************************************* 205 * @ingroup LacMemPool 206 * This function displays the stats associated with the memory pools 207 * 208 * @blocking 209 * No 210 * @reentrant 211 * No 212 * @threadSafe 213 * No 214 * 215 ******************************************************************************/ 216 void Lac_MemPoolStatsShow(void); 217 218 /** 219 ******************************************************************************* 220 * @ingroup LacMemPool 221 * This function initialises the physical addresses of the symmetric cookie 222 * 223 * @blocking 224 * No 225 * @reentrant 226 * No 227 * @threadSafe 228 * No 229 * @param[in] poolID ID of the pool 230 * 231 * @retval CPA_STATUS_FAIL function failed 232 * @retval CPA_STATUS_SUCCESS function executed successfully 233 * 234 ******************************************************************************/ 235 CpaStatus Lac_MemPoolInitSymCookiesPhyAddr(lac_memory_pool_id_t poolID); 236 237 /** 238 ******************************************************************************* 239 * @ingroup LacMemPool 240 * This function populates all PKE requests with instance constant parameters 241 * 242 * @blocking 243 * No 244 * @reentrant 245 * No 246 * @threadSafe 247 * No 248 * @param[in] poolID ID of the pool 249 * @param[in] instanceHandle instanceHandle 250 * 251 * @retval CPA_STATUS_FAIL function failed 252 * @retval CPA_STATUS_SUCCESS function executed successfully 253 * 254 ******************************************************************************/ 255 CpaStatus Lac_MemPoolInitAsymCookies(lac_memory_pool_id_t poolID, 256 CpaInstanceHandle instanceHandle); 257 258 /** 259 ******************************************************************************* 260 * @ingroup LacMemPool 261 * This function initialises the physical addresses of the compression cookie 262 * 263 * @blocking 264 * No 265 * @reentrant 266 * No 267 * @threadSafe 268 * No 269 * @param[in] poolID ID of the pool 270 * 271 * @retval CPA_STATUS_FAIL function failed 272 * @retval CPA_STATUS_SUCCESS function executed successfully 273 * 274 ******************************************************************************/ 275 CpaStatus Lac_MemPoolInitDcCookiePhyAddr(lac_memory_pool_id_t poolID); 276 277 #endif /*LAC_MEM_POOLS_H*/ 278