1 /* SPDX-License-Identifier: BSD-3-Clause */ 2 /* Copyright(c) 2007-2022 Intel Corporation */ 3 /** 4 *************************************************************************** 5 * @file lac_buffer_desc.h 6 * 7 * @defgroup LacBufferDesc Buffer Descriptors 8 * 9 * @ingroup LacCommon 10 * 11 * Functions which handle updating a user supplied buffer with the QAT 12 * descriptor representation. 13 * 14 ***************************************************************************/ 15 16 /***************************************************************************/ 17 18 #ifndef LAC_BUFFER_DESC_H 19 #define LAC_BUFFER_DESC_H 20 21 /*************************************************************************** 22 * Include header files 23 ***************************************************************************/ 24 #include "cpa.h" 25 #include "icp_buffer_desc.h" 26 #include "cpa_cy_sym.h" 27 #include "lac_common.h" 28 29 /** 30 ******************************************************************************* 31 * @ingroup LacBufferDesc 32 * Write the buffer descriptor in QAT friendly format. 33 * 34 * @description 35 * Updates the Meta Data associated with the pUserBufferList CpaBufferList 36 * This function will also return the (aligned) physical address 37 * associated with this CpaBufferList. 38 * 39 * @param[in] pUserBufferList A pointer to the buffer list to 40 * create the meta data for the QAT. 41 * @param[out] pBufferListAlignedPhyAddr The pointer to the aligned physical 42 * address. 43 * @param[in] isPhysicalAddress Type of address 44 * @param[in] pService Pointer to generic service 45 * 46 *****************************************************************************/ 47 CpaStatus LacBuffDesc_BufferListDescWrite(const CpaBufferList *pUserBufferList, 48 Cpa64U *pBufferListAlignedPhyAddr, 49 CpaBoolean isPhysicalAddress, 50 sal_service_t *pService); 51 52 /** 53 ******************************************************************************* 54 * @ingroup LacBufferDesc 55 * Write the buffer descriptor in QAT friendly format. 56 * 57 * @description 58 * Updates the Meta Data associated with the pUserBufferList CpaBufferList 59 * This function will also return the (aligned) physical address 60 * associated with this CpaBufferList. Zero length buffers are allowed. 61 * Should be used for CHA-CHA-POLY and GCM algorithms. 62 * 63 * @param[in] pUserBufferList A pointer to the buffer list to 64 * create the meta data for the QAT. 65 * @param[out] pBufferListAlignedPhyAddr The pointer to the aligned physical 66 * address. 67 * @param[in] isPhysicalAddress Type of address 68 * @param[in] pService Pointer to generic service 69 * 70 *****************************************************************************/ 71 CpaStatus LacBuffDesc_BufferListDescWriteAndAllowZeroBuffer( 72 const CpaBufferList *pUserBufferList, 73 Cpa64U *pBufferListAlignedPhyAddr, 74 CpaBoolean isPhysicalAddress, 75 sal_service_t *pService); 76 77 /** 78 ******************************************************************************* 79 * @ingroup LacBufferDesc 80 * Write the buffer descriptor in QAT friendly format. 81 * 82 * @description 83 * Updates the Meta Data associated with the PClientList CpaBufferList 84 * This function will also return the (aligned) physical address 85 * associated with this CpaBufferList and the total data length of the 86 * buffer list. 87 * 88 * @param[in] pUserBufferList A pointer to the buffer list to 89 * create the meta data for the QAT. 90 * @param[out] pBufListAlignedPhyAddr The pointer to the aligned physical 91 * address. 92 * @param[in] isPhysicalAddress Type of address 93 * @param[out] totalDataLenInBytes The pointer to the total data length 94 * of the buffer list 95 * @param[in] pService Pointer to generic service 96 * 97 *****************************************************************************/ 98 CpaStatus 99 LacBuffDesc_BufferListDescWriteAndGetSize(const CpaBufferList *pUserBufferList, 100 Cpa64U *pBufListAlignedPhyAddr, 101 CpaBoolean isPhysicalAddress, 102 Cpa64U *totalDataLenInBytes, 103 sal_service_t *pService); 104 105 /** 106 ******************************************************************************* 107 * @ingroup LacBufferDesc 108 * Ensure the CpaFlatBuffer is correctly formatted. 109 * 110 * @description 111 * Ensures the CpaFlatBuffer is correctly formatted 112 * This function will also return the total size of the buffers 113 * in the scatter gather list. 114 * 115 * @param[in] pUserFlatBuffer A pointer to the flat buffer to 116 * validate. 117 * @param[out] pPktSize The total size of the packet. 118 * @param[in] alignmentShiftExpected The expected alignment shift of each 119 * of the elements of the scatter gather 120 * 121 * @retval CPA_STATUS_INVALID_PARAM BufferList failed checks 122 * @retval CPA_STATUS_SUCCESS Function executed successfully 123 * 124 *****************************************************************************/ 125 CpaStatus 126 LacBuffDesc_FlatBufferVerify(const CpaFlatBuffer *pUserFlatBuffer, 127 Cpa64U *pPktSize, 128 lac_aligment_shift_t alignmentShiftExpected); 129 130 /** 131 ******************************************************************************* 132 * @ingroup LacBufferDesc 133 * Ensure the CpaFlatBuffer is correctly formatted. 134 * This function will allow a size of zero bytes to any of the Flat 135 * buffers. 136 * 137 * @description 138 * Ensures the CpaFlatBuffer is correctly formatted 139 * This function will also return the total size of the buffers 140 * in the scatter gather list. 141 * 142 * @param[in] pUserFlatBuffer A pointer to the flat buffer to 143 * validate. 144 * @param[out] pPktSize The total size of the packet. 145 * @param[in] alignmentShiftExpected The expected alignment shift of each 146 * of the elements of the scatter gather 147 * 148 * @retval CPA_STATUS_INVALID_PARAM BufferList failed checks 149 * @retval CPA_STATUS_SUCCESS Function executed successfully 150 * 151 *****************************************************************************/ 152 CpaStatus 153 LacBuffDesc_FlatBufferVerifyNull(const CpaFlatBuffer *pUserFlatBuffer, 154 Cpa64U *pPktSize, 155 lac_aligment_shift_t alignmentShiftExpected); 156 157 /** 158 ******************************************************************************* 159 * @ingroup LacBufferDesc 160 * Ensure the CpaBufferList is correctly formatted. 161 * 162 * @description 163 * Ensures the CpaBufferList pUserBufferList is correctly formatted 164 * including the user supplied metaData. 165 * This function will also return the total size of the buffers 166 * in the scatter gather list. 167 * 168 * @param[in] pUserBufferList A pointer to the buffer list to 169 * validate. 170 * @param[out] pPktSize The total size of the buffers in the 171 * scatter gather list. 172 * @param[in] alignmentShiftExpected The expected alignment shift of each 173 * of the elements of the scatter gather 174 * list. 175 * @retval CPA_STATUS_INVALID_PARAM BufferList failed checks 176 * @retval CPA_STATUS_SUCCESS Function executed successfully 177 * 178 *****************************************************************************/ 179 CpaStatus 180 LacBuffDesc_BufferListVerify(const CpaBufferList *pUserBufferList, 181 Cpa64U *pPktSize, 182 lac_aligment_shift_t alignmentShiftExpected); 183 184 /** 185 ******************************************************************************* 186 * @ingroup LacBufferDesc 187 * Ensure the CpaBufferList is correctly formatted. 188 * 189 * @description 190 * Ensures the CpaBufferList pUserBufferList is correctly formatted 191 * including the user supplied metaData. 192 * This function will also return the total size of the buffers 193 * in the scatter gather list. 194 * 195 * @param[in] pUserBufferList A pointer to the buffer list to 196 * validate. 197 * @param[out] pPktSize The total size of the buffers in the 198 * scatter gather list. 199 * @param[in] alignmentShiftExpected The expected alignment shift of each 200 * of the elements of the scatter gather 201 * list. 202 * @retval CPA_STATUS_INVALID_PARAM BufferList failed checks 203 * @retval CPA_STATUS_SUCCESS Function executed successfully 204 * 205 *****************************************************************************/ 206 CpaStatus 207 LacBuffDesc_BufferListVerifyNull(const CpaBufferList *pUserBufferList, 208 Cpa64U *pPktSize, 209 lac_aligment_shift_t alignmentShiftExpected); 210 211 /** 212 ******************************************************************************* 213 * @ingroup LacBufferDesc 214 * Get the total size of a CpaBufferList. 215 * 216 * @description 217 * This function returns the total size of the buffers 218 * in the scatter gather list. 219 * 220 * @param[in] pUserBufferList A pointer to the buffer list to 221 * calculate the total size for. 222 * @param[out] pPktSize The total size of the buffers in the 223 * scatter gather list. 224 * 225 *****************************************************************************/ 226 void LacBuffDesc_BufferListTotalSizeGet(const CpaBufferList *pUserBufferList, 227 Cpa64U *pPktSize); 228 229 /** 230 ******************************************************************************* 231 * @ingroup LacBufferDesc 232 * Zero some of the CpaBufferList. 233 * 234 * @description 235 * Zero a section of data within the CpaBufferList from an offset for 236 * a specific length. 237 * 238 * @param[in] pBuffList A pointer to the buffer list to 239 * zero an area of. 240 * @param[in] offset Number of bytes from start of buffer to where 241 * to start zeroing. 242 * 243 * @param[in] lenToZero Number of bytes that will be set to zero 244 * after the call to this function. 245 *****************************************************************************/ 246 247 void LacBuffDesc_BufferListZeroFromOffset(CpaBufferList *pBuffList, 248 Cpa32U offset, 249 Cpa32U lenToZero); 250 251 #endif /* LAC_BUFFER_DESC_H */ 252