1 /* SPDX-License-Identifier: GPL-2.0 */ 2 /* 3 * Memory pools library, Public interface 4 * 5 * API Overview 6 * 7 * This package provides a memory allocation subsystem based on pools of 8 * homogenous objects. 9 * 10 * Instrumentation is available for reporting memory utilization both 11 * on a per-data-structure basis and system wide. 12 * 13 * There are two main types defined in this API. 14 * 15 * pool manager: A singleton object that acts as a factory for 16 * pool allocators. It also is used for global 17 * instrumentation, such as reporting all blocks 18 * in use across all data structures. The pool manager 19 * creates and provides individual memory pools 20 * upon request to application code. 21 * 22 * memory pool: An object for allocating homogenous memory blocks. 23 * 24 * Global identifiers in this module use the following prefixes: 25 * bcm_mpm_* Memory pool manager 26 * bcm_mp_* Memory pool 27 * 28 * There are two main types of memory pools: 29 * 30 * prealloc: The contiguous memory block of objects can either be supplied 31 * by the client or malloc'ed by the memory manager. The objects are 32 * allocated out of a block of memory and freed back to the block. 33 * 34 * heap: The memory pool allocator uses the heap (malloc/free) for memory. 35 * In this case, the pool allocator is just providing statistics 36 * and instrumentation on top of the heap, without modifying the heap 37 * allocation implementation. 38 * 39 * Copyright (C) 1999-2019, Broadcom. 40 * 41 * Unless you and Broadcom execute a separate written software license 42 * agreement governing use of this software, this software is licensed to you 43 * under the terms of the GNU General Public License version 2 (the "GPL"), 44 * available at http://www.broadcom.com/licenses/GPLv2.php, with the 45 * following added to such license: 46 * 47 * As a special exception, the copyright holders of this software give you 48 * permission to link this software with independent modules, and to copy and 49 * distribute the resulting executable under terms of your choice, provided that 50 * you also meet, for each linked independent module, the terms and conditions of 51 * the license of that module. An independent module is a module which is not 52 * derived from this software. The special exception does not apply to any 53 * modifications of the software. 54 * 55 * Notwithstanding the above, under no circumstances may you combine this 56 * software in any way with any other Broadcom software provided under a license 57 * other than the GPL, without Broadcom's express prior written consent. 58 * 59 * 60 * <<Broadcom-WL-IPTag/Open:>> 61 * 62 * $Id: bcm_mpool_pub.h 535090 2015-02-17 04:49:01Z $ 63 */ 64 65 #ifndef _BCM_MPOOL_PUB_H 66 #define _BCM_MPOOL_PUB_H 1 67 68 #include <typedefs.h> /* needed for uint16 */ 69 70 /* 71 ************************************************************************** 72 * 73 * Type definitions, handles 74 * 75 ************************************************************************** 76 */ 77 78 /* Forward declaration of OSL handle. */ 79 struct osl_info; 80 81 /* Forward declaration of string buffer. */ 82 struct bcmstrbuf; 83 84 /* 85 * Opaque type definition for the pool manager handle. This object is used for global 86 * memory pool operations such as obtaining a new pool, deleting a pool, iterating and 87 * instrumentation/debugging. 88 */ 89 struct bcm_mpm_mgr; 90 typedef struct bcm_mpm_mgr *bcm_mpm_mgr_h; 91 92 /* 93 * Opaque type definition for an instance of a pool. This handle is used for allocating 94 * and freeing memory through the pool, as well as management/instrumentation on this 95 * specific pool. 96 */ 97 struct bcm_mp_pool; 98 typedef struct bcm_mp_pool *bcm_mp_pool_h; 99 100 /* 101 * To make instrumentation more readable, every memory 102 * pool must have a readable name. Pool names are up to 103 * 8 bytes including '\0' termination. (7 printable characters.) 104 */ 105 #define BCM_MP_NAMELEN 8 106 107 /* 108 * Type definition for pool statistics. 109 */ 110 typedef struct bcm_mp_stats { 111 char name[BCM_MP_NAMELEN]; /* Name of this pool. */ 112 unsigned int objsz; /* Object size allocated in this pool */ 113 uint16 nobj; /* Total number of objects in this pool */ 114 uint16 num_alloc; /* Number of objects currently allocated */ 115 uint16 high_water; /* Max number of allocated objects. */ 116 uint16 failed_alloc; /* Failed allocations. */ 117 } bcm_mp_stats_t; 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 * bcm_mpm_deinit() - de-initialize the whole memory pool system. 143 * 144 * Parameters: 145 * mgr: INPUT Pointer to pool manager handle. 146 * 147 * Returns: 148 * BCME_OK Memory pool manager successfully de-initialized. 149 * other Indicated error occured during de-initialization. 150 */ 151 int bcm_mpm_deinit(bcm_mpm_mgr_h *mgrp); 152 153 /* 154 * bcm_mpm_create_prealloc_pool() - Create a new pool for fixed size objects. The 155 * pool uses a contiguous block of pre-alloced 156 * memory. The memory block may either be provided 157 * by the client or dynamically allocated by the 158 * pool manager. 159 * 160 * Parameters: 161 * mgr: INPUT The handle to the pool manager 162 * obj_sz: INPUT Size of objects that will be allocated by the new pool 163 * Must be >= sizeof(void *). 164 * nobj: INPUT Maximum number of concurrently existing objects to support 165 * memstart INPUT Pointer to the memory to use, or NULL to malloc() 166 * memsize INPUT Number of bytes referenced from memstart (for error checking). 167 * Must be 0 if 'memstart' is NULL. 168 * poolname INPUT For instrumentation, the name of the pool 169 * newp: OUTPUT The handle for the new pool, if creation is successful 170 * 171 * Returns: 172 * BCME_OK Pool created ok. 173 * other Pool not created due to indicated error. newpoolp set to NULL. 174 * 175 * 176 */ 177 int bcm_mpm_create_prealloc_pool(bcm_mpm_mgr_h mgr, 178 unsigned int obj_sz, 179 int nobj, 180 void *memstart, 181 unsigned int memsize, 182 const char poolname[BCM_MP_NAMELEN], 183 bcm_mp_pool_h *newp); 184 185 /* 186 * bcm_mpm_delete_prealloc_pool() - Delete a memory pool. This should only be called after 187 * all memory objects have been freed back to the pool. 188 * 189 * Parameters: 190 * mgr: INPUT The handle to the pools manager 191 * pool: INPUT The handle of the pool to delete 192 * 193 * Returns: 194 * BCME_OK Pool deleted ok. 195 * other Pool not deleted due to indicated error. 196 * 197 */ 198 int bcm_mpm_delete_prealloc_pool(bcm_mpm_mgr_h mgr, bcm_mp_pool_h *poolp); 199 200 /* 201 * bcm_mpm_create_heap_pool() - Create a new pool for fixed size objects. The memory 202 * pool allocator uses the heap (malloc/free) for memory. 203 * In this case, the pool allocator is just providing 204 * statistics and instrumentation on top of the heap, 205 * without modifying the heap allocation implementation. 206 * 207 * Parameters: 208 * mgr: INPUT The handle to the pool manager 209 * obj_sz: INPUT Size of objects that will be allocated by the new pool 210 * poolname INPUT For instrumentation, the name of the pool 211 * newp: OUTPUT The handle for the new pool, if creation is successful 212 * 213 * Returns: 214 * BCME_OK Pool created ok. 215 * other Pool not created due to indicated error. newpoolp set to NULL. 216 * 217 * 218 */ 219 int bcm_mpm_create_heap_pool(bcm_mpm_mgr_h mgr, unsigned int obj_sz, 220 const char poolname[BCM_MP_NAMELEN], 221 bcm_mp_pool_h *newp); 222 223 /* 224 * bcm_mpm_delete_heap_pool() - Delete a memory pool. This should only be called after 225 * all memory objects have been freed back to the pool. 226 * 227 * Parameters: 228 * mgr: INPUT The handle to the pools manager 229 * pool: INPUT The handle of the pool to delete 230 * 231 * Returns: 232 * BCME_OK Pool deleted ok. 233 * other Pool not deleted due to indicated error. 234 * 235 */ 236 int bcm_mpm_delete_heap_pool(bcm_mpm_mgr_h mgr, bcm_mp_pool_h *poolp); 237 238 /* 239 * bcm_mpm_stats() - Return stats for all pools 240 * 241 * Parameters: 242 * mgr: INPUT The handle to the pools manager 243 * stats: OUTPUT Array of pool statistics. 244 * nentries: MOD Max elements in 'stats' array on INPUT. Actual number 245 * of array elements copied to 'stats' on OUTPUT. 246 * 247 * Returns: 248 * BCME_OK Ok 249 * other Error getting stats. 250 * 251 */ 252 int bcm_mpm_stats(bcm_mpm_mgr_h mgr, bcm_mp_stats_t *stats, int *nentries); 253 254 /* 255 * bcm_mpm_dump() - Display statistics on all pools 256 * 257 * Parameters: 258 * mgr: INPUT The handle to the pools manager 259 * b: OUTPUT Output buffer. 260 * 261 * Returns: 262 * BCME_OK Ok 263 * other Error during dump. 264 * 265 */ 266 int bcm_mpm_dump(bcm_mpm_mgr_h mgr, struct bcmstrbuf *b); 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 * API Routines on a specific pool. 293 * 294 *************************************************************************** 295 */ 296 297 /* 298 * bcm_mp_alloc() - Allocate a memory pool object. 299 * 300 * Parameters: 301 * pool: INPUT The handle to the pool. 302 * 303 * Returns: 304 * A pointer to the new object. NULL on error. 305 * 306 */ 307 void* bcm_mp_alloc(bcm_mp_pool_h pool); 308 309 /* 310 * bcm_mp_free() - Free a memory pool object. 311 * 312 * Parameters: 313 * pool: INPUT The handle to the pool. 314 * objp: INPUT A pointer to the object to free. 315 * 316 * Returns: 317 * BCME_OK Ok 318 * other Error during free. 319 * 320 */ 321 int bcm_mp_free(bcm_mp_pool_h pool, void *objp); 322 323 /* 324 * bcm_mp_stats() - Return stats for this pool 325 * 326 * Parameters: 327 * pool: INPUT The handle to the pool 328 * stats: OUTPUT Pool statistics 329 * 330 * Returns: 331 * BCME_OK Ok 332 * other Error getting statistics. 333 * 334 */ 335 void bcm_mp_stats(bcm_mp_pool_h pool, bcm_mp_stats_t *stats); 336 337 /* 338 * bcm_mp_dump() - Dump a pool 339 * 340 * Parameters: 341 * pool: INPUT The handle to the pool 342 * b OUTPUT Output buffer 343 * 344 * Returns: 345 * BCME_OK Ok 346 * other Error during dump. 347 * 348 */ 349 int bcm_mp_dump(bcm_mp_pool_h pool, struct bcmstrbuf *b); 350 351 #endif /* _BCM_MPOOL_PUB_H */ 352