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 */ 345