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) 1999-2013, Broadcom Corporation
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. */
70 struct osl_info;
71 
72 /* Forward declaration of string buffer. */
73 struct 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  */
80 struct bcm_mpm_mgr;
81 typedef 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  */
88 struct bcm_mp_pool;
89 typedef 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  */
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 *
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  */
133 int 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  */
146 int 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  */
172 int 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                                  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  */
194 int 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  */
215 int bcm_mpm_create_heap_pool(bcm_mpm_mgr_h mgr, unsigned int obj_sz,
216                              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  */
233 int 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  */
250 int 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  */
265 int 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  */
287 int 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  */
309 void* 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  */
323 int 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  */
337 int 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  */
352 int bcm_mp_dump(bcm_mp_pool_h pool, struct bcmstrbuf *b);
353 
354 
355 #endif /* _BCM_MPOOL_PUB_H */
356