1 /****************************************************************************** 2 * Copyright (c) 2022 Telink Semiconductor (Shanghai) Co., Ltd. ("TELINK") 3 * All rights reserved. 4 * 5 * Licensed under the Apache License, Version 2.0 (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 * 17 *****************************************************************************/ 18 /*************************************************************************************************/ 19 /*! 20 * \file my_buf.h 21 * 22 * \brief Buffer pool service. 23 * 24 * Copyright (c) 2009-2018 Arm Ltd. All Rights Reserved. 25 * 26 * Copyright (c) 2019-2020 Packetcraft, Inc. 27 * 28 * Licensed under the Apache License, Version 2.0 (the "License"); 29 * you may not use this file except in compliance with the License. 30 * You may obtain a copy of the License at 31 * 32 * http://www.apache.org/licenses/LICENSE-2.0 33 * 34 * Unless required by applicable law or agreed to in writing, software 35 * distributed under the License is distributed on an "AS IS" BASIS, 36 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 37 * See the License for the specific language governing permissions and 38 * limitations under the License. 39 */ 40 /*************************************************************************************************/ 41 #ifndef MY_BUF_H 42 #define MY_BUF_H 43 44 #ifdef __cplusplus 45 extern "C" { 46 #endif 47 48 #include "common/compiler.h" 49 #include "common/types.h" 50 51 /*! \addtogroup MY_BUF_API 52 * \{ */ 53 54 /************************************************************************************************** 55 Configuration 56 **************************************************************************************************/ 57 58 /*! \brief Check if trying to free a buffer that is already free */ 59 #ifndef MY_BUF_FREE_CHECK_ASSERT 60 #define MY_BUF_FREE_CHECK_ASSERT TRUE 61 #endif 62 63 /*! \brief Assert on best-fit buffer allocation failure */ 64 #ifndef MY_BUF_ALLOC_BEST_FIT_FAIL_ASSERT 65 #define MY_BUF_ALLOC_BEST_FIT_FAIL_ASSERT TRUE // FALSE 66 #endif 67 68 /*! \brief Assert on buffer allocation failure */ 69 #ifndef MY_BUF_ALLOC_FAIL_ASSERT 70 #define MY_BUF_ALLOC_FAIL_ASSERT TRUE 71 #endif 72 73 /*! \brief Buffer histogram stats */ 74 #ifndef MY_BUF_STATS_HIST 75 #define MY_BUF_STATS_HIST FALSE // TRUE 76 #endif 77 78 /************************************************************************************************** 79 Macros 80 **************************************************************************************************/ 81 82 /*! \brief Length of the buffer statistics array */ 83 #define MY_BUF_STATS_MAX_LEN 128 84 85 /*! \brief Max number of pools can allocate */ 86 #define MY_BUF_STATS_MAX_POOL 32 87 88 /*! \brief Failure Codes */ 89 #define MY_BUF_ALLOC_FAILED 1 90 91 #ifndef MY_BUF_STATS 92 /*! \brief Enable buffer allocation statistics. */ 93 #define MY_BUF_STATS FALSE // TRUE 94 #endif 95 96 /************************************************************************************************** 97 Data Types 98 **************************************************************************************************/ 99 100 /*! \brief Buffer pool descriptor structure */ 101 typedef struct { 102 u16 len; /*!< \brief Length of buffers in pool */ 103 u8 num; /*!< \brief Number of buffers in pool */ 104 } myBufPoolDesc_t; 105 106 /*! \brief Pool statistics */ 107 typedef struct { 108 u16 bufSize; /*!< \brief Pool buffer size. */ 109 u8 numBuf; /*!< \brief Total number of buffers. */ 110 u8 numAlloc; /*!< \brief Number of outstanding allocations. */ 111 u8 maxAlloc; /*!< \brief High allocation watermark. */ 112 u16 maxReqLen; /*!< \brief Maximum requested buffer length. */ 113 } myBufPoolStat_t; 114 115 /*! \brief MY buffer diagnostics - buffer allocation failure */ 116 typedef struct { 117 u8 taskId; /*!< \brief Task handler ID where failure occured */ 118 u16 len; /*!< \brief Length of buffer being allocated */ 119 } myBufDiagAllocFail_t; 120 121 /*! \brief MY buffer diagnostics message */ 122 typedef struct { 123 union { 124 myBufDiagAllocFail_t alloc; /*!< \brief Buffer allocation failure */ 125 } param; /*!< \brief Union of diagnostic data types. */ 126 127 u8 type; /*!< \brief Type of error */ 128 } myBufDiag_t; 129 130 /************************************************************************************************** 131 Callback Function Datatypes 132 **************************************************************************************************/ 133 134 /*! 135 * \brief Callback providing MY buffer diagnostic messages. 136 * 137 * \param pInfo Diagnostics message. 138 */ 139 typedef void (*myBufDiagCback_t)(myBufDiag_t *pInfo); 140 141 /************************************************************************************************** 142 Function Declarations 143 **************************************************************************************************/ 144 145 /*! 146 * \brief Calculate size required by the buffer pool. 147 * 148 * \param numPools Number of buffer pools. 149 * \param pDesc Array of buffer pool descriptors, one for each pool. 150 * 151 * \return Amount of pBufMem used. 152 */ 153 u32 myBufCalcSize(u8 numPools, myBufPoolDesc_t *pDesc); 154 155 /*! 156 * \brief Initialize the buffer pool service. This function should only be called once 157 * upon system initialization. 158 * 159 * \param numPools Number of buffer pools. 160 * \param pDesc Array of buffer pool descriptors, one for each pool. 161 * 162 * \return Amount of pBufMem used or 0 for failures. 163 */ 164 u32 myBufInit(u8 numPools, myBufPoolDesc_t *pDesc); 165 166 /*! 167 * \brief Allocate a buffer. 168 * 169 * \param len Length of buffer to allocate. 170 * 171 * \return Pointer to allocated buffer or NULL if allocation fails. 172 */ 173 void *myBufAlloc(u16 len); 174 175 /*! 176 * \brief Free a buffer. 177 * 178 * \param pBuf Buffer to free. 179 */ 180 void myBufFree(void *pBuf); 181 182 /*! 183 * \brief Diagnostic function to get the buffer allocation statistics. 184 * 185 * \return Buffer allocation statistics array. 186 */ 187 u8 *myBufGetAllocStats(void); 188 189 /*! 190 * \brief Diagnostic function to get the number of overflow times for each pool. 191 * 192 * \return Overflow times statistics array 193 */ 194 u8 *myBufGetPoolOverFlowStats(void); 195 196 /*! 197 * \brief Get number of pools. 198 * 199 * \return Number of pools. 200 */ 201 u8 myBufGetNumPool(void); 202 203 /*! 204 * \brief Get statistics for each pool. 205 * 206 * \param pStat Buffer to store the statistics. 207 * \param numPool Number of pool elements. 208 * 209 * \return Pool statistics. 210 */ 211 void myBufGetPoolStats(myBufPoolStat_t *pStat, u8 numPool); 212 213 /*! 214 * \brief Called to register the buffer diagnostics callback function. 215 * 216 * \param callback Pointer to the callback function. 217 */ 218 void myBufDiagRegister(myBufDiagCback_t callback); 219 220 /*! \} */ /* MY_BUF_API */ 221 222 #ifdef __cplusplus 223 }; 224 #endif 225 226 #endif /* MY_BUF_H */ 227