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 * Portions of this code are copyright (c) 2021 Cypress Semiconductor Corporation 39 * 40 * Copyright (C) 1999-2017, Broadcom Corporation 41 * 42 * Unless you and Broadcom execute a separate written software license 43 * agreement governing use of this software, this software is licensed to you 44 * under the terms of the GNU General Public License version 2 (the "GPL"), 45 * available at http://www.broadcom.com/licenses/GPLv2.php, with the 46 * following added to such license: 47 * 48 * As a special exception, the copyright holders of this software give you 49 * permission to link this software with independent modules, and to copy and 50 * distribute the resulting executable under terms of your choice, provided that 51 * you also meet, for each linked independent module, the terms and conditions of 52 * the license of that module. An independent module is a module which is not 53 * derived from this software. The special exception does not apply to any 54 * modifications of the software. 55 * 56 * Notwithstanding the above, under no circumstances may you combine this 57 * software in any way with any other Broadcom software provided under a license 58 * other than the GPL, without Broadcom's express prior written consent. 59 * 60 * 61 * <<Broadcom-WL-IPTag/Open:>> 62 * 63 * $Id: bcm_mpool_pub.h 535090 2015-02-17 04:49:01Z $ 64 */ 65 66 #ifndef _BCM_MPOOL_PUB_H 67 #define _BCM_MPOOL_PUB_H 1 68 69 #include <typedefs.h> /* needed for uint16 */ 70 71 /* 72 ************************************************************************** 73 * 74 * Type definitions, handles 75 * 76 ************************************************************************** 77 */ 78 79 /* Forward declaration of OSL handle. */ 80 struct osl_info; 81 82 /* Forward declaration of string buffer. */ 83 struct bcmstrbuf; 84 85 /* 86 * Opaque type definition for the pool manager handle. This object is used for global 87 * memory pool operations such as obtaining a new pool, deleting a pool, iterating and 88 * instrumentation/debugging. 89 */ 90 struct bcm_mpm_mgr; 91 typedef struct bcm_mpm_mgr *bcm_mpm_mgr_h; 92 93 /* 94 * Opaque type definition for an instance of a pool. This handle is used for allocating 95 * and freeing memory through the pool, as well as management/instrumentation on this 96 * specific pool. 97 */ 98 struct bcm_mp_pool; 99 typedef struct bcm_mp_pool *bcm_mp_pool_h; 100 101 /* 102 * To make instrumentation more readable, every memory 103 * pool must have a readable name. Pool names are up to 104 * 8 bytes including '\0' termination. (7 printable characters.) 105 */ 106 #define BCM_MP_NAMELEN 8 107 108 /* 109 * Type definition for pool statistics. 110 */ 111 typedef struct bcm_mp_stats { 112 char name[BCM_MP_NAMELEN]; /* Name of this pool. */ 113 unsigned int objsz; /* Object size allocated in this pool */ 114 uint16 nobj; /* Total number of objects in this pool */ 115 uint16 num_alloc; /* Number of objects currently allocated */ 116 uint16 high_water; /* Max number of allocated objects. */ 117 uint16 failed_alloc; /* Failed allocations. */ 118 } bcm_mp_stats_t; 119 120 /* 121 ************************************************************************** 122 * 123 * API Routines on the pool manager. 124 * 125 ************************************************************************** 126 */ 127 128 /* 129 * bcm_mpm_init() - initialize the whole memory pool system. 130 * 131 * Parameters: 132 * osh: INPUT Operating system handle. Needed for heap memory allocation. 133 * max_pools: INPUT Maximum number of mempools supported. 134 * mgr: OUTPUT The handle is written with the new pools manager object/handle. 135 * 136 * Returns: 137 * BCME_OK Object initialized successfully. May be used. 138 * BCME_NOMEM Initialization failed due to no memory. Object must not be used. 139 */ 140 int bcm_mpm_init(struct osl_info *osh, int max_pools, bcm_mpm_mgr_h *mgrp); 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 const char poolname[BCM_MP_NAMELEN], 184 bcm_mp_pool_h *newp); 185 186 /* 187 * bcm_mpm_delete_prealloc_pool() - Delete a memory pool. This should only be called after 188 * all memory objects have been freed back to the pool. 189 * 190 * Parameters: 191 * mgr: INPUT The handle to the pools manager 192 * pool: INPUT The handle of the pool to delete 193 * 194 * Returns: 195 * BCME_OK Pool deleted ok. 196 * other Pool not deleted due to indicated error. 197 * 198 */ 199 int bcm_mpm_delete_prealloc_pool(bcm_mpm_mgr_h mgr, bcm_mp_pool_h *poolp); 200 201 /* 202 * bcm_mpm_create_heap_pool() - Create a new pool for fixed size objects. The memory 203 * pool allocator uses the heap (malloc/free) for memory. 204 * In this case, the pool allocator is just providing 205 * statistics and instrumentation on top of the heap, 206 * without modifying the heap allocation implementation. 207 * 208 * Parameters: 209 * mgr: INPUT The handle to the pool manager 210 * obj_sz: INPUT Size of objects that will be allocated by the new pool 211 * poolname INPUT For instrumentation, the name of the pool 212 * newp: OUTPUT The handle for the new pool, if creation is successful 213 * 214 * Returns: 215 * BCME_OK Pool created ok. 216 * other Pool not created due to indicated error. newpoolp set to NULL. 217 * 218 * 219 */ 220 int bcm_mpm_create_heap_pool(bcm_mpm_mgr_h mgr, unsigned int obj_sz, 221 const char poolname[BCM_MP_NAMELEN], 222 bcm_mp_pool_h *newp); 223 224 /* 225 * bcm_mpm_delete_heap_pool() - Delete a memory pool. This should only be called after 226 * all memory objects have been freed back to the pool. 227 * 228 * Parameters: 229 * mgr: INPUT The handle to the pools manager 230 * pool: INPUT The handle of the pool to delete 231 * 232 * Returns: 233 * BCME_OK Pool deleted ok. 234 * other Pool not deleted due to indicated error. 235 * 236 */ 237 int bcm_mpm_delete_heap_pool(bcm_mpm_mgr_h mgr, bcm_mp_pool_h *poolp); 238 239 /* 240 * bcm_mpm_stats() - Return stats for all pools 241 * 242 * Parameters: 243 * mgr: INPUT The handle to the pools manager 244 * stats: OUTPUT Array of pool statistics. 245 * nentries: MOD Max elements in 'stats' array on INPUT. Actual number 246 * of array elements copied to 'stats' on OUTPUT. 247 * 248 * Returns: 249 * BCME_OK Ok 250 * other Error getting stats. 251 * 252 */ 253 int bcm_mpm_stats(bcm_mpm_mgr_h mgr, bcm_mp_stats_t *stats, int *nentries); 254 255 /* 256 * bcm_mpm_dump() - Display statistics on all pools 257 * 258 * Parameters: 259 * mgr: INPUT The handle to the pools manager 260 * b: OUTPUT Output buffer. 261 * 262 * Returns: 263 * BCME_OK Ok 264 * other Error during dump. 265 * 266 */ 267 int bcm_mpm_dump(bcm_mpm_mgr_h mgr, struct bcmstrbuf *b); 268 269 /* 270 * bcm_mpm_get_obj_size() - The size of memory objects may need to be padded to 271 * compensate for alignment requirements of the objects. 272 * This function provides the padded object size. If clients 273 * pre-allocate a memory slab for a memory pool, the 274 * padded object size should be used by the client to allocate 275 * the memory slab (in order to provide sufficent space for 276 * the maximum number of objects). 277 * 278 * Parameters: 279 * mgr: INPUT The handle to the pools manager. 280 * obj_sz: INPUT Input object size. 281 * padded_obj_sz: OUTPUT Padded object size. 282 * 283 * Returns: 284 * BCME_OK Ok 285 * BCME_BADARG Bad arguments. 286 * 287 */ 288 int bcm_mpm_get_obj_size(bcm_mpm_mgr_h mgr, unsigned int obj_sz, unsigned int *padded_obj_sz); 289 290 /* 291 *************************************************************************** 292 * 293 * API Routines on a specific pool. 294 * 295 *************************************************************************** 296 */ 297 298 /* 299 * bcm_mp_alloc() - Allocate a memory pool object. 300 * 301 * Parameters: 302 * pool: INPUT The handle to the pool. 303 * 304 * Returns: 305 * A pointer to the new object. NULL on error. 306 * 307 */ 308 void* bcm_mp_alloc(bcm_mp_pool_h pool); 309 310 /* 311 * bcm_mp_free() - Free a memory pool object. 312 * 313 * Parameters: 314 * pool: INPUT The handle to the pool. 315 * objp: INPUT A pointer to the object to free. 316 * 317 * Returns: 318 * BCME_OK Ok 319 * other Error during free. 320 * 321 */ 322 int bcm_mp_free(bcm_mp_pool_h pool, void *objp); 323 324 /* 325 * bcm_mp_stats() - Return stats for this pool 326 * 327 * Parameters: 328 * pool: INPUT The handle to the pool 329 * stats: OUTPUT Pool statistics 330 * 331 * Returns: 332 * BCME_OK Ok 333 * other Error getting statistics. 334 * 335 */ 336 void bcm_mp_stats(bcm_mp_pool_h pool, bcm_mp_stats_t *stats); 337 338 /* 339 * bcm_mp_dump() - Dump a pool 340 * 341 * Parameters: 342 * pool: INPUT The handle to the pool 343 * b OUTPUT Output buffer 344 * 345 * Returns: 346 * BCME_OK Ok 347 * other Error during dump. 348 * 349 */ 350 int bcm_mp_dump(bcm_mp_pool_h pool, struct bcmstrbuf *b); 351 352 #endif /* _BCM_MPOOL_PUB_H */ 353