Cordio Stack and Cordio Profiles  r2p3-02rel0
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  * Arm Ltd. confidential and proprietary.
9  *
10  * IMPORTANT. Your use of this file is governed by a Software License Agreement
11  * ("Agreement") that must be accepted in order to download or otherwise receive a
12  * copy of this file. You may not use or copy this file for any purpose other than
13  * as described in the Agreement. If you do not agree to all of the terms of the
14  * Agreement do not use this file and delete all copies in your possession or control;
15  * if you do not have a copy of the Agreement, you must contact Arm Ltd. prior
16  * to any use, copying or further distribution of this software.
17  */
18 /*************************************************************************************************/
19 #ifndef WSF_BUF_H
20 #define WSF_BUF_H
21 
22 #ifdef __cplusplus
23 extern "C" {
24 #endif
25 
26 /*! \addtogroup WSF_BUF_API
27  * \{ */
28 
29 /**************************************************************************************************
30  Configuration
31 **************************************************************************************************/
32 
33 /*! \brief check if trying to free a buffer that is already free */
34 #ifndef WSF_BUF_FREE_CHECK
35 #define WSF_BUF_FREE_CHECK TRUE
36 #endif
37 
38 /*! \brief assert on best-fit buffer allocation failure */
39 #ifndef WSF_BUF_ALLOC_BEST_FIT_FAIL_ASSERT
40 #define WSF_BUF_ALLOC_BEST_FIT_FAIL_ASSERT FALSE
41 #endif
42 
43 /*! \brief assert on buffer allocation failure */
44 #ifndef WSF_BUF_ALLOC_FAIL_ASSERT
45 #define WSF_BUF_ALLOC_FAIL_ASSERT TRUE
46 #endif
47 
48 /*! \brief buffer histogram stats */
49 #ifndef WSF_BUF_STATS_HIST
50 #define WSF_BUF_STATS_HIST FALSE
51 #endif
52 
53 /**************************************************************************************************
54  Macros
55 **************************************************************************************************/
56 
57 /*! \brief Length of the buffer statistics array */
58 #define WSF_BUF_STATS_MAX_LEN 128
59 
60 /*! \brief Max number of pools can allocate */
61 #define WSF_BUF_STATS_MAX_POOL 32
62 
63 /*! \brief Failure Codes */
64 #define WSF_BUF_ALLOC_FAILED 0x01
65 
66 #ifndef WSF_BUF_STATS
67 /*! \brief Enable buffer allocation statistics. */
68 #define WSF_BUF_STATS FALSE
69 #endif
70 
71 /**************************************************************************************************
72  Data Types
73 **************************************************************************************************/
74 
75 /*! \brief Buffer pool descriptor structure */
76 typedef struct
77 {
78  uint16_t len; /*!< \brief length of buffers in pool */
79  uint8_t num; /*!< \brief number of buffers in pool */
81 
82 /*! \brief Pool statistics */
83 typedef struct
84 {
85  uint16_t bufSize; /*!< \brief Pool buffer size. */
86  uint8_t numBuf; /*!< \brief Total number of buffers. */
87  uint8_t numAlloc; /*!< \brief Number of outstanding allocations. */
88  uint8_t maxAlloc; /*!< \brief High allocation watermark. */
89  uint16_t maxReqLen; /*!< \brief Maximum requested buffer length. */
91 
92 /*! \brief WSF buffer diagnostics - buffer allocation failure */
93 typedef struct
94 {
95  uint8_t taskId; /*!< \brief Task handler ID where failure occured */
96  uint16_t len; /*!< \brief Length of buffer being allocated */
98 
99 /*! \brief WSF buffer diagnostics message */
100 typedef struct
101 {
102  union
103  {
104  wsfBufDiagAllocFail_t alloc; /*!< \brief Buffer allocation failure */
105  } param; /*!< \brief Union of diagnostic data types. */
106 
107  uint8_t type; /*!< \brief Type of error */
108 } WsfBufDiag_t;
109 
110 /**************************************************************************************************
111  Callback Function Datatypes
112 **************************************************************************************************/
113 
114 /*************************************************************************************************/
115 /*!
116  * \brief Callback providing WSF buffer diagnostic messages.
117  *
118  * \param pInfo Diagnostics message
119  *
120  * \return None.
121  */
122 /*************************************************************************************************/
123 typedef void (*wsfBufDiagCback_t)(WsfBufDiag_t *pInfo);
124 
125 /**************************************************************************************************
126  Function Declarations
127 **************************************************************************************************/
128 
129 /*************************************************************************************************/
130 /*!
131  * \brief Initialize the buffer pool service. This function should only be called once
132  * upon system initialization.
133  *
134  * \param bufMemLen Length in bytes of memory pointed to by pBufMem.
135  * \param pBufMem Memory in which to store the pools used by the buffer pool service.
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 or 0 for failures.
140  */
141 /*************************************************************************************************/
142 uint32_t WsfBufInit(uint32_t bufMemLen, uint8_t *pBufMem, uint8_t numPools, wsfBufPoolDesc_t *pDesc);
143 
144 /*************************************************************************************************/
145 /*!
146  * \brief Allocate a buffer.
147  *
148  * \param len Length of buffer to allocate.
149  *
150  * \return Pointer to allocated buffer or NULL if allocation fails.
151  */
152 /*************************************************************************************************/
153 void *WsfBufAlloc(uint16_t len);
154 
155 /*************************************************************************************************/
156 /*!
157  * \brief Free a buffer.
158  *
159  * \param pBuf Buffer to free.
160  *
161  * \return None.
162  */
163 /*************************************************************************************************/
164 void WsfBufFree(void *pBuf);
165 
166 /*************************************************************************************************/
167 /*!
168  * \brief Diagnostic function to get the buffer allocation statistics.
169  *
170  * \return Buffer allocation statistics array.
171  */
172 /*************************************************************************************************/
174 
175 /*************************************************************************************************/
176 /*!
177  * \brief Diagnostic function to get the number of overflow times for each pool.
178  *
179  * \return Overflow times statistics array
180  */
181 /*************************************************************************************************/
183 
184 /*************************************************************************************************/
185 /*!
186  * \brief Get number of pools.
187  *
188  * \return Number of pools.
189  */
190 /*************************************************************************************************/
192 
193 /*************************************************************************************************/
194 /*!
195  * \brief Get statistics for each pool.
196  *
197  * \param pStat Buffer to store the statistics.
198  * \param numPool Number of pool elements.
199  *
200  * \return Pool statistics.
201  */
202 /*************************************************************************************************/
203 void WsfBufGetPoolStats(WsfBufPoolStat_t *pStat, uint8_t numPool);
204 
205 /*************************************************************************************************/
206 /*!
207  * \brief Called to register the buffer diagnostics callback function.
208  *
209  * \param callback Pointer to the callback function.
210  *
211  * \return None.
212  */
213 /*************************************************************************************************/
215 
216 /*! \} */ /* WSF_BUF_API */
217 
218 #ifdef __cplusplus
219 };
220 #endif
221 
222 #endif /* WSF_BUF_H */
uint8_t type
Type of error.
Definition: wsf_buf.h:107
uint16_t bufSize
Pool buffer size.
Definition: wsf_buf.h:85
uint8_t taskId
Task handler ID where failure occured.
Definition: wsf_buf.h:95
Buffer pool descriptor structure.
Definition: wsf_buf.h:76
uint8_t * WsfBufGetPoolOverFlowStats(void)
Diagnostic function to get the number of overflow times for each pool.
uint32_t WsfBufInit(uint32_t bufMemLen, uint8_t *pBufMem, uint8_t numPools, wsfBufPoolDesc_t *pDesc)
Initialize the buffer pool service. This function should only be called once upon system initializati...
uint8_t * WsfBufGetAllocStats(void)
Diagnostic function to get the buffer allocation statistics.
void WsfBufDiagRegister(wsfBufDiagCback_t callback)
Called to register the buffer diagnostics callback function.
uint8_t numAlloc
Number of outstanding allocations.
Definition: wsf_buf.h:87
WSF buffer diagnostics - buffer allocation failure.
Definition: wsf_buf.h:93
void WsfBufGetPoolStats(WsfBufPoolStat_t *pStat, uint8_t numPool)
Get statistics for each pool.
uint8_t numBuf
Total number of buffers.
Definition: wsf_buf.h:86
uint16_t maxReqLen
Maximum requested buffer length.
Definition: wsf_buf.h:89
uint8_t maxAlloc
High allocation watermark.
Definition: wsf_buf.h:88
unsigned long uint32_t
Unsigned 32-bit value.
Definition: wsf_types.h:71
uint8_t WsfBufGetNumPool(void)
Get number of pools.
WSF buffer diagnostics message.
Definition: wsf_buf.h:100
uint16_t len
Length of buffer being allocated.
Definition: wsf_buf.h:96
unsigned short uint16_t
Unsigned 16-bit value.
Definition: wsf_types.h:67
void(* wsfBufDiagCback_t)(WsfBufDiag_t *pInfo)
Callback providing WSF buffer diagnostic messages.
Definition: wsf_buf.h:123
uint16_t len
length of buffers in pool
Definition: wsf_buf.h:78
Pool statistics.
Definition: wsf_buf.h:83
wsfBufDiagAllocFail_t alloc
Buffer allocation failure.
Definition: wsf_buf.h:104
uint8_t num
number of buffers in pool
Definition: wsf_buf.h:79
void * WsfBufAlloc(uint16_t len)
Allocate a buffer.
unsigned char uint8_t
Unsigned 8-bit value.
Definition: wsf_types.h:63
void WsfBufFree(void *pBuf)
Free a buffer.