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

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.