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