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