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) 2013, Broadcom Corporation. All Rights Reserved.
39 *
40 * Permission to use, copy, modify, and/or distribute this software for any
41 * purpose with or without fee is hereby granted, provided that the above
42 * copyright notice and this permission notice appear in all copies.
43 *
44 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
45 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
46 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
47 * SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
48 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
49 * OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
50 * CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
51 *
52 * $Id$
53 */
54
55#ifndef _BCM_MPOOL_PUB_H
56#define _BCM_MPOOL_PUB_H 1
57
58#include <typedefs.h> /* needed for uint16 */
59
60
61/*
62**************************************************************************
63*
64* Type definitions, handles
65*
66**************************************************************************
67*/
68
69/* Forward declaration of OSL handle. */
70struct osl_info;
71
72/* Forward declaration of string buffer. */
73struct bcmstrbuf;
74
75/*
76 * Opaque type definition for the pool manager handle. This object is used for global
77 * memory pool operations such as obtaining a new pool, deleting a pool, iterating and
78 * instrumentation/debugging.
79 */
80struct bcm_mpm_mgr;
81typedef struct bcm_mpm_mgr *bcm_mpm_mgr_h;
82
83/*
84 * Opaque type definition for an instance of a pool. This handle is used for allocating
85 * and freeing memory through the pool, as well as management/instrumentation on this
86 * specific pool.
87 */
88struct bcm_mp_pool;
89typedef struct bcm_mp_pool *bcm_mp_pool_h;
90
91
92/*
93 * To make instrumentation more readable, every memory
94 * pool must have a readable name. Pool names are up to
95 * 8 bytes including '\0' termination. (7 printable characters.)
96 */
97#define BCM_MP_NAMELEN 8
98
99
100/*
101 * Type definition for pool statistics.
102 */
103typedef 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*
116* API Routines on the pool manager.
117*
118**************************************************************************
119*/
120
121/*
122 * bcm_mpm_init() - initialize the whole memory pool system.
123 *
124 * Parameters:
125 *    osh:       INPUT  Operating system handle. Needed for heap memory allocation.
126 *    max_pools: INPUT Maximum number of mempools supported.
127 *    mgr:       OUTPUT The handle is written with the new pools manager object/handle.
128 *
129 * Returns:
130 *    BCME_OK     Object initialized successfully. May be used.
131 *    BCME_NOMEM  Initialization failed due to no memory. Object must not be used.
132 */
133int bcm_mpm_init(struct osl_info *osh, int max_pools, bcm_mpm_mgr_h *mgrp);
134
135
136/*
137 * bcm_mpm_deinit() - de-initialize the whole memory pool system.
138 *
139 * Parameters:
140 *    mgr:     INPUT  Pointer to pool manager handle.
141 *
142 * Returns:
143 *    BCME_OK  Memory pool manager successfully de-initialized.
144 *    other    Indicated error occured during de-initialization.
145 */
146int bcm_mpm_deinit(bcm_mpm_mgr_h *mgrp);
147
148/*
149 * bcm_mpm_create_prealloc_pool() - Create a new pool for fixed size objects. The
150 *                                  pool uses a contiguous block of pre-alloced
151 *                                  memory. The memory block may either be provided
152 *                                  by the client or dynamically allocated by the
153 *                                  pool manager.
154 *
155 * Parameters:
156 *    mgr:      INPUT  The handle to the pool manager
157 *    obj_sz:   INPUT  Size of objects that will be allocated by the new pool
158 *                     Must be >= sizeof(void *).
159 *    nobj:     INPUT  Maximum number of concurrently existing objects to support
160 *    memstart  INPUT  Pointer to the memory to use, or NULL to malloc()
161 *    memsize   INPUT  Number of bytes referenced from memstart (for error checking).
162 *                     Must be 0 if 'memstart' is NULL.
163 *    poolname  INPUT  For instrumentation, the name of the pool
164 *    newp:     OUTPUT The handle for the new pool, if creation is successful
165 *
166 * Returns:
167 *    BCME_OK   Pool created ok.
168 *    other     Pool not created due to indicated error. newpoolp set to NULL.
169 *
170 *
171 */
172int bcm_mpm_create_prealloc_pool(bcm_mpm_mgr_h mgr,
173                                 unsigned int obj_sz,
174                                 int nobj,
175                                 void *memstart,
176                                 unsigned int memsize,
177                                 const char poolname[BCM_MP_NAMELEN],
178                                 bcm_mp_pool_h *newp);
179
180
181/*
182 * bcm_mpm_delete_prealloc_pool() - Delete a memory pool. This should only be called after
183 *                                  all memory objects have been freed back to the pool.
184 *
185 * Parameters:
186 *    mgr:     INPUT The handle to the pools manager
187 *    pool:    INPUT The handle of the  pool to delete
188 *
189 * Returns:
190 *    BCME_OK   Pool deleted ok.
191 *    other     Pool not deleted due to indicated error.
192 *
193 */
194int bcm_mpm_delete_prealloc_pool(bcm_mpm_mgr_h mgr, bcm_mp_pool_h *poolp);
195
196/*
197 * bcm_mpm_create_heap_pool() - Create a new pool for fixed size objects. The memory
198 *                              pool allocator uses the heap (malloc/free) for memory.
199 *                              In this case, the pool allocator is just providing
200 *                              statistics and instrumentation on top of the heap,
201 *                              without modifying the heap allocation implementation.
202 *
203 * Parameters:
204 *    mgr:      INPUT  The handle to the pool manager
205 *    obj_sz:   INPUT  Size of objects that will be allocated by the new pool
206 *    poolname  INPUT  For instrumentation, the name of the pool
207 *    newp:     OUTPUT The handle for the new pool, if creation is successful
208 *
209 * Returns:
210 *    BCME_OK   Pool created ok.
211 *    other     Pool not created due to indicated error. newpoolp set to NULL.
212 *
213 *
214 */
215int bcm_mpm_create_heap_pool(bcm_mpm_mgr_h mgr, unsigned int obj_sz,
216                             const char poolname[BCM_MP_NAMELEN],
217                             bcm_mp_pool_h *newp);
218
219
220/*
221 * bcm_mpm_delete_heap_pool() - Delete a memory pool. This should only be called after
222 *                              all memory objects have been freed back to the pool.
223 *
224 * Parameters:
225 *    mgr:     INPUT The handle to the pools manager
226 *    pool:    INPUT The handle of the  pool to delete
227 *
228 * Returns:
229 *    BCME_OK   Pool deleted ok.
230 *    other     Pool not deleted due to indicated error.
231 *
232 */
233int bcm_mpm_delete_heap_pool(bcm_mpm_mgr_h mgr, bcm_mp_pool_h *poolp);
234
235
236/*
237 * bcm_mpm_stats() - Return stats for all pools
238 *
239 * Parameters:
240 *    mgr:         INPUT   The handle to the pools manager
241 *    stats:       OUTPUT  Array of pool statistics.
242 *    nentries:    MOD     Max elements in 'stats' array on INPUT. Actual number
243 *                         of array elements copied to 'stats' on OUTPUT.
244 *
245 * Returns:
246 *    BCME_OK   Ok
247 *    other     Error getting stats.
248 *
249 */
250int bcm_mpm_stats(bcm_mpm_mgr_h mgr, bcm_mp_stats_t *stats, int *nentries);
251
252
253/*
254 * bcm_mpm_dump() - Display statistics on all pools
255 *
256 * Parameters:
257 *    mgr:     INPUT  The handle to the pools manager
258 *    b:       OUTPUT Output buffer.
259 *
260 * Returns:
261 *    BCME_OK   Ok
262 *    other     Error during dump.
263 *
264 */
265int bcm_mpm_dump(bcm_mpm_mgr_h mgr, struct bcmstrbuf *b);
266
267
268/*
269 * bcm_mpm_get_obj_size() - The size of memory objects may need to be padded to
270 *                          compensate for alignment requirements of the objects.
271 *                          This function provides the padded object size. If clients
272 *                          pre-allocate a memory slab for a memory pool, the
273 *                          padded object size should be used by the client to allocate
274 *                          the memory slab (in order to provide sufficent space for
275 *                          the maximum number of objects).
276 *
277 * Parameters:
278 *    mgr:            INPUT   The handle to the pools manager.
279 *    obj_sz:         INPUT   Input object size.
280 *    padded_obj_sz:  OUTPUT  Padded object size.
281 *
282 * Returns:
283 *    BCME_OK      Ok
284 *    BCME_BADARG  Bad arguments.
285 *
286 */
287int bcm_mpm_get_obj_size(bcm_mpm_mgr_h mgr, unsigned int obj_sz, unsigned int *padded_obj_sz);
288
289
290/*
291***************************************************************************
292*
293* API Routines on a specific pool.
294*
295***************************************************************************
296*/
297
298
299/*
300 * bcm_mp_alloc() - Allocate a memory pool object.
301 *
302 * Parameters:
303 *    pool:    INPUT    The handle to the pool.
304 *
305 * Returns:
306 *    A pointer to the new object. NULL on error.
307 *
308 */
309void* bcm_mp_alloc(bcm_mp_pool_h pool);
310
311/*
312 * bcm_mp_free() - Free a memory pool object.
313 *
314 * Parameters:
315 *    pool:  INPUT   The handle to the pool.
316 *    objp:  INPUT   A pointer to the object to free.
317 *
318 * Returns:
319 *    BCME_OK   Ok
320 *    other     Error during free.
321 *
322 */
323int bcm_mp_free(bcm_mp_pool_h pool, void *objp);
324
325/*
326 * bcm_mp_stats() - Return stats for this pool
327 *
328 * Parameters:
329 *    pool:     INPUT    The handle to the pool
330 *    stats:    OUTPUT   Pool statistics
331 *
332 * Returns:
333 *    BCME_OK   Ok
334 *    other     Error getting statistics.
335 *
336 */
337int bcm_mp_stats(bcm_mp_pool_h pool, bcm_mp_stats_t *stats);
338
339
340/*
341 * bcm_mp_dump() - Dump a pool
342 *
343 * Parameters:
344 *    pool:    INPUT    The handle to the pool
345 *    b        OUTPUT   Output buffer
346 *
347 * Returns:
348 *    BCME_OK   Ok
349 *    other     Error during dump.
350 *
351 */
352int bcm_mp_dump(bcm_mp_pool_h pool, struct bcmstrbuf *b);
353
354
355#endif /* _BCM_MPOOL_PUB_H */
356