Commit | Line | Data |
---|---|---|
1b4a7c03 LJ |
1 | /* |
2 | * Memory pools library, Public interface | |
3 | * | |
4 | * API Overview | |
5 | * | |
6 | * This package provides a memory allocation subsystem based on pools of | |
7 | * homogenous objects. | |
8 | * | |
9 | * Instrumentation is available for reporting memory utilization both | |
10 | * on a per-data-structure basis and system wide. | |
11 | * | |
12 | * There are two main types defined in this API. | |
13 | * | |
14 | * pool manager: A singleton object that acts as a factory for | |
15 | * pool allocators. It also is used for global | |
16 | * instrumentation, such as reporting all blocks | |
17 | * in use across all data structures. The pool manager | |
18 | * creates and provides individual memory pools | |
19 | * upon request to application code. | |
20 | * | |
21 | * memory pool: An object for allocating homogenous memory blocks. | |
22 | * | |
23 | * Global identifiers in this module use the following prefixes: | |
24 | * bcm_mpm_* Memory pool manager | |
25 | * bcm_mp_* Memory pool | |
26 | * | |
27 | * There are two main types of memory pools: | |
28 | * | |
29 | * prealloc: The contiguous memory block of objects can either be supplied | |
30 | * by the client or malloc'ed by the memory manager. The objects are | |
31 | * allocated out of a block of memory and freed back to the block. | |
32 | * | |
33 | * heap: The memory pool allocator uses the heap (malloc/free) for memory. | |
34 | * In this case, the pool allocator is just providing statistics | |
35 | * and instrumentation on top of the heap, without modifying the heap | |
36 | * allocation implementation. | |
37 | * | |
38 | * Copyright (C) 2020, Broadcom. | |
39 | * | |
40 | * Unless you and Broadcom execute a separate written software license | |
41 | * agreement governing use of this software, this software is licensed to you | |
42 | * under the terms of the GNU General Public License version 2 (the "GPL"), | |
43 | * available at http://www.broadcom.com/licenses/GPLv2.php, with the | |
44 | * following added to such license: | |
45 | * | |
46 | * As a special exception, the copyright holders of this software give you | |
47 | * permission to link this software with independent modules, and to copy and | |
48 | * distribute the resulting executable under terms of your choice, provided that | |
49 | * you also meet, for each linked independent module, the terms and conditions of | |
50 | * the license of that module. An independent module is a module which is not | |
51 | * derived from this software. The special exception does not apply to any | |
52 | * modifications of the software. | |
53 | * | |
54 | * | |
55 | * <<Broadcom-WL-IPTag/Dual:>> | |
56 | */ | |
57 | ||
58 | #ifndef _BCM_MPOOL_PUB_H | |
59 | #define _BCM_MPOOL_PUB_H 1 | |
60 | ||
61 | #include <typedefs.h> /* needed for uint16 */ | |
62 | ||
63 | /* | |
64 | ************************************************************************** | |
65 | * | |
66 | * Type definitions, handles | |
67 | * | |
68 | ************************************************************************** | |
69 | */ | |
70 | ||
71 | /* Forward declaration of OSL handle. */ | |
72 | struct osl_info; | |
73 | ||
74 | /* Forward declaration of string buffer. */ | |
75 | struct bcmstrbuf; | |
76 | ||
77 | /* | |
78 | * Opaque type definition for the pool manager handle. This object is used for global | |
79 | * memory pool operations such as obtaining a new pool, deleting a pool, iterating and | |
80 | * instrumentation/debugging. | |
81 | */ | |
82 | struct bcm_mpm_mgr; | |
83 | typedef struct bcm_mpm_mgr *bcm_mpm_mgr_h; | |
84 | ||
85 | /* | |
86 | * Opaque type definition for an instance of a pool. This handle is used for allocating | |
87 | * and freeing memory through the pool, as well as management/instrumentation on this | |
88 | * specific pool. | |
89 | */ | |
90 | struct bcm_mp_pool; | |
91 | typedef struct bcm_mp_pool *bcm_mp_pool_h; | |
92 | ||
93 | /* | |
94 | * To make instrumentation more readable, every memory | |
95 | * pool must have a readable name. Pool names are up to | |
96 | * 8 bytes including '\0' termination. (7 printable characters.) | |
97 | */ | |
98 | #define BCM_MP_NAMELEN 8 | |
99 | ||
100 | /* | |
101 | * Type definition for pool statistics. | |
102 | */ | |
103 | typedef struct bcm_mp_stats { | |
104 | char name[BCM_MP_NAMELEN]; /* Name of this pool. */ | |
105 | unsigned int objsz; /* Object size allocated in this pool */ | |
106 | uint16 nobj; /* Total number of objects in this pool */ | |
107 | uint16 num_alloc; /* Number of objects currently allocated */ | |
108 | uint16 high_water; /* Max number of allocated objects. */ | |
109 | uint16 failed_alloc; /* Failed allocations. */ | |
110 | } bcm_mp_stats_t; | |
111 | ||
112 | /* | |
113 | ************************************************************************** | |
114 | * | |
115 | * API Routines on the pool manager. | |
116 | * | |
117 | ************************************************************************** | |
118 | */ | |
119 | ||
120 | /* | |
121 | * bcm_mpm_init() - initialize the whole memory pool system. | |
122 | * | |
123 | * Parameters: | |
124 | * osh: INPUT Operating system handle. Needed for heap memory allocation. | |
125 | * max_pools: INPUT Maximum number of mempools supported. | |
126 | * mgr: OUTPUT The handle is written with the new pools manager object/handle. | |
127 | * | |
128 | * Returns: | |
129 | * BCME_OK Object initialized successfully. May be used. | |
130 | * BCME_NOMEM Initialization failed due to no memory. Object must not be used. | |
131 | */ | |
132 | int bcm_mpm_init(struct osl_info *osh, int max_pools, bcm_mpm_mgr_h *mgrp); | |
133 | ||
134 | /* | |
135 | * bcm_mpm_deinit() - de-initialize the whole memory pool system. | |
136 | * | |
137 | * Parameters: | |
138 | * mgr: INPUT Pointer to pool manager handle. | |
139 | * | |
140 | * Returns: | |
141 | * BCME_OK Memory pool manager successfully de-initialized. | |
142 | * other Indicated error occured during de-initialization. | |
143 | */ | |
144 | int bcm_mpm_deinit(bcm_mpm_mgr_h *mgrp); | |
145 | ||
146 | /* | |
147 | * bcm_mpm_create_prealloc_pool() - Create a new pool for fixed size objects. The | |
148 | * pool uses a contiguous block of pre-alloced | |
149 | * memory. The memory block may either be provided | |
150 | * by the client or dynamically allocated by the | |
151 | * pool manager. | |
152 | * | |
153 | * Parameters: | |
154 | * mgr: INPUT The handle to the pool manager | |
155 | * obj_sz: INPUT Size of objects that will be allocated by the new pool | |
156 | * Must be >= sizeof(void *). | |
157 | * nobj: INPUT Maximum number of concurrently existing objects to support | |
158 | * memstart INPUT Pointer to the memory to use, or NULL to malloc() | |
159 | * memsize INPUT Number of bytes referenced from memstart (for error checking). | |
160 | * Must be 0 if 'memstart' is NULL. | |
161 | * poolname INPUT For instrumentation, the name of the pool | |
162 | * newp: OUTPUT The handle for the new pool, if creation is successful | |
163 | * | |
164 | * Returns: | |
165 | * BCME_OK Pool created ok. | |
166 | * other Pool not created due to indicated error. newpoolp set to NULL. | |
167 | * | |
168 | * | |
169 | */ | |
170 | int bcm_mpm_create_prealloc_pool(bcm_mpm_mgr_h mgr, | |
171 | unsigned int obj_sz, | |
172 | int nobj, | |
173 | void *memstart, | |
174 | unsigned int memsize, | |
175 | const char poolname[BCM_MP_NAMELEN], | |
176 | bcm_mp_pool_h *newp); | |
177 | ||
178 | /* | |
179 | * bcm_mpm_delete_prealloc_pool() - Delete a memory pool. This should only be called after | |
180 | * all memory objects have been freed back to the pool. | |
181 | * | |
182 | * Parameters: | |
183 | * mgr: INPUT The handle to the pools manager | |
184 | * pool: INPUT The handle of the pool to delete | |
185 | * | |
186 | * Returns: | |
187 | * BCME_OK Pool deleted ok. | |
188 | * other Pool not deleted due to indicated error. | |
189 | * | |
190 | */ | |
191 | int bcm_mpm_delete_prealloc_pool(bcm_mpm_mgr_h mgr, bcm_mp_pool_h *poolp); | |
192 | ||
193 | /* | |
194 | * bcm_mpm_create_heap_pool() - Create a new pool for fixed size objects. The memory | |
195 | * pool allocator uses the heap (malloc/free) for memory. | |
196 | * In this case, the pool allocator is just providing | |
197 | * statistics and instrumentation on top of the heap, | |
198 | * without modifying the heap allocation implementation. | |
199 | * | |
200 | * Parameters: | |
201 | * mgr: INPUT The handle to the pool manager | |
202 | * obj_sz: INPUT Size of objects that will be allocated by the new pool | |
203 | * poolname INPUT For instrumentation, the name of the pool | |
204 | * newp: OUTPUT The handle for the new pool, if creation is successful | |
205 | * | |
206 | * Returns: | |
207 | * BCME_OK Pool created ok. | |
208 | * other Pool not created due to indicated error. newpoolp set to NULL. | |
209 | * | |
210 | * | |
211 | */ | |
212 | int bcm_mpm_create_heap_pool(bcm_mpm_mgr_h mgr, unsigned int obj_sz, | |
213 | const char poolname[BCM_MP_NAMELEN], | |
214 | bcm_mp_pool_h *newp); | |
215 | ||
216 | /* | |
217 | * bcm_mpm_delete_heap_pool() - Delete a memory pool. This should only be called after | |
218 | * all memory objects have been freed back to the pool. | |
219 | * | |
220 | * Parameters: | |
221 | * mgr: INPUT The handle to the pools manager | |
222 | * pool: INPUT The handle of the pool to delete | |
223 | * | |
224 | * Returns: | |
225 | * BCME_OK Pool deleted ok. | |
226 | * other Pool not deleted due to indicated error. | |
227 | * | |
228 | */ | |
229 | int bcm_mpm_delete_heap_pool(bcm_mpm_mgr_h mgr, bcm_mp_pool_h *poolp); | |
230 | ||
231 | /* | |
232 | * bcm_mpm_stats() - Return stats for all pools | |
233 | * | |
234 | * Parameters: | |
235 | * mgr: INPUT The handle to the pools manager | |
236 | * stats: OUTPUT Array of pool statistics. | |
237 | * nentries: MOD Max elements in 'stats' array on INPUT. Actual number | |
238 | * of array elements copied to 'stats' on OUTPUT. | |
239 | * | |
240 | * Returns: | |
241 | * BCME_OK Ok | |
242 | * other Error getting stats. | |
243 | * | |
244 | */ | |
245 | int bcm_mpm_stats(bcm_mpm_mgr_h mgr, bcm_mp_stats_t *stats, int *nentries); | |
246 | ||
247 | /* | |
248 | * bcm_mpm_dump() - Display statistics on all pools | |
249 | * | |
250 | * Parameters: | |
251 | * mgr: INPUT The handle to the pools manager | |
252 | * b: OUTPUT Output buffer. | |
253 | * | |
254 | * Returns: | |
255 | * BCME_OK Ok | |
256 | * other Error during dump. | |
257 | * | |
258 | */ | |
259 | int bcm_mpm_dump(bcm_mpm_mgr_h mgr, struct bcmstrbuf *b); | |
260 | ||
261 | /* | |
262 | * bcm_mpm_get_obj_size() - The size of memory objects may need to be padded to | |
263 | * compensate for alignment requirements of the objects. | |
264 | * This function provides the padded object size. If clients | |
265 | * pre-allocate a memory slab for a memory pool, the | |
266 | * padded object size should be used by the client to allocate | |
267 | * the memory slab (in order to provide sufficent space for | |
268 | * the maximum number of objects). | |
269 | * | |
270 | * Parameters: | |
271 | * mgr: INPUT The handle to the pools manager. | |
272 | * obj_sz: INPUT Input object size. | |
273 | * padded_obj_sz: OUTPUT Padded object size. | |
274 | * | |
275 | * Returns: | |
276 | * BCME_OK Ok | |
277 | * BCME_BADARG Bad arguments. | |
278 | * | |
279 | */ | |
280 | int bcm_mpm_get_obj_size(bcm_mpm_mgr_h mgr, unsigned int obj_sz, unsigned int *padded_obj_sz); | |
281 | ||
282 | /* | |
283 | *************************************************************************** | |
284 | * | |
285 | * API Routines on a specific pool. | |
286 | * | |
287 | *************************************************************************** | |
288 | */ | |
289 | ||
290 | /* | |
291 | * bcm_mp_alloc() - Allocate a memory pool object. | |
292 | * | |
293 | * Parameters: | |
294 | * pool: INPUT The handle to the pool. | |
295 | * | |
296 | * Returns: | |
297 | * A pointer to the new object. NULL on error. | |
298 | * | |
299 | */ | |
300 | void* bcm_mp_alloc(bcm_mp_pool_h pool); | |
301 | ||
302 | /* | |
303 | * bcm_mp_free() - Free a memory pool object. | |
304 | * | |
305 | * Parameters: | |
306 | * pool: INPUT The handle to the pool. | |
307 | * objp: INPUT A pointer to the object to free. | |
308 | * | |
309 | * Returns: | |
310 | * BCME_OK Ok | |
311 | * other Error during free. | |
312 | * | |
313 | */ | |
314 | int bcm_mp_free(bcm_mp_pool_h pool, void *objp); | |
315 | ||
316 | /* | |
317 | * bcm_mp_stats() - Return stats for this pool | |
318 | * | |
319 | * Parameters: | |
320 | * pool: INPUT The handle to the pool | |
321 | * stats: OUTPUT Pool statistics | |
322 | * | |
323 | * Returns: | |
324 | * BCME_OK Ok | |
325 | * other Error getting statistics. | |
326 | * | |
327 | */ | |
328 | void bcm_mp_stats(bcm_mp_pool_h pool, bcm_mp_stats_t *stats); | |
329 | ||
330 | /* | |
331 | * bcm_mp_dump() - Dump a pool | |
332 | * | |
333 | * Parameters: | |
334 | * pool: INPUT The handle to the pool | |
335 | * b OUTPUT Output buffer | |
336 | * | |
337 | * Returns: | |
338 | * BCME_OK Ok | |
339 | * other Error during dump. | |
340 | * | |
341 | */ | |
342 | int bcm_mp_dump(bcm_mp_pool_h pool, struct bcmstrbuf *b); | |
343 | ||
344 | #endif /* _BCM_MPOOL_PUB_H */ |