| /* |
| * Memory pools library, Public interface |
| * |
| * API Overview |
| * |
| * This package provides a memory allocation subsystem based on pools of |
| * homogenous objects. |
| * |
| * Instrumentation is available for reporting memory utilization both |
| * on a per-data-structure basis and system wide. |
| * |
| * There are two main types defined in this API. |
| * |
| * pool manager: A singleton object that acts as a factory for |
| * pool allocators. It also is used for global |
| * instrumentation, such as reporting all blocks |
| * in use across all data structures. The pool manager |
| * creates and provides individual memory pools |
| * upon request to application code. |
| * |
| * memory pool: An object for allocating homogenous memory blocks. |
| * |
| * Global identifiers in this module use the following prefixes: |
| * bcm_mpm_* Memory pool manager |
| * bcm_mp_* Memory pool |
| * |
| * There are two main types of memory pools: |
| * |
| * prealloc: The contiguous memory block of objects can either be supplied |
| * by the client or malloc'ed by the memory manager. The objects are |
| * allocated out of a block of memory and freed back to the block. |
| * |
| * heap: The memory pool allocator uses the heap (malloc/free) for memory. |
| * In this case, the pool allocator is just providing statistics |
| * and instrumentation on top of the heap, without modifying the heap |
| * allocation implementation. |
| * |
| * Copyright (C) 1999-2012, Broadcom Corporation |
| * |
| * Permission to use, copy, modify, and/or distribute this software for any |
| * purpose with or without fee is hereby granted, provided that the above |
| * copyright notice and this permission notice appear in all copies. |
| * |
| * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES |
| * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF |
| * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY |
| * SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES |
| * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION |
| * OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN |
| * CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. |
| * |
| * $Id$ |
| */ |
| |
| #ifndef _BCM_MPOOL_PUB_H |
| #define _BCM_MPOOL_PUB_H 1 |
| |
| #include <typedefs.h> /* needed for uint16 */ |
| |
| |
| /* |
| ************************************************************************** |
| * |
| * Type definitions, handles |
| * |
| ************************************************************************** |
| */ |
| |
| /* Forward declaration of OSL handle. */ |
| struct osl_info; |
| |
| /* Forward declaration of string buffer. */ |
| struct bcmstrbuf; |
| |
| /* |
| * Opaque type definition for the pool manager handle. This object is used for global |
| * memory pool operations such as obtaining a new pool, deleting a pool, iterating and |
| * instrumentation/debugging. |
| */ |
| struct bcm_mpm_mgr; |
| typedef struct bcm_mpm_mgr *bcm_mpm_mgr_h; |
| |
| /* |
| * Opaque type definition for an instance of a pool. This handle is used for allocating |
| * and freeing memory through the pool, as well as management/instrumentation on this |
| * specific pool. |
| */ |
| struct bcm_mp_pool; |
| typedef struct bcm_mp_pool *bcm_mp_pool_h; |
| |
| |
| /* |
| * To make instrumentation more readable, every memory |
| * pool must have a readable name. Pool names are up to |
| * 8 bytes including '\0' termination. (7 printable characters.) |
| */ |
| #define BCM_MP_NAMELEN 8 |
| |
| |
| /* |
| * Type definition for pool statistics. |
| */ |
| typedef struct bcm_mp_stats { |
| char name[BCM_MP_NAMELEN]; /* Name of this pool. */ |
| unsigned int objsz; /* Object size allocated in this pool */ |
| uint16 nobj; /* Total number of objects in this pool */ |
| uint16 num_alloc; /* Number of objects currently allocated */ |
| uint16 high_water; /* Max number of allocated objects. */ |
| uint16 failed_alloc; /* Failed allocations. */ |
| } bcm_mp_stats_t; |
| |
| |
| /* |
| ************************************************************************** |
| * |
| * API Routines on the pool manager. |
| * |
| ************************************************************************** |
| */ |
| |
| /* |
| * bcm_mpm_init() - initialize the whole memory pool system. |
| * |
| * Parameters: |
| * osh: INPUT Operating system handle. Needed for heap memory allocation. |
| * max_pools: INPUT Maximum number of mempools supported. |
| * mgr: OUTPUT The handle is written with the new pools manager object/handle. |
| * |
| * Returns: |
| * BCME_OK Object initialized successfully. May be used. |
| * BCME_NOMEM Initialization failed due to no memory. Object must not be used. |
| */ |
| int bcm_mpm_init(struct osl_info *osh, int max_pools, bcm_mpm_mgr_h *mgrp); |
| |
| |
| /* |
| * bcm_mpm_deinit() - de-initialize the whole memory pool system. |
| * |
| * Parameters: |
| * mgr: INPUT Pointer to pool manager handle. |
| * |
| * Returns: |
| * BCME_OK Memory pool manager successfully de-initialized. |
| * other Indicated error occured during de-initialization. |
| */ |
| int bcm_mpm_deinit(bcm_mpm_mgr_h *mgrp); |
| |
| /* |
| * bcm_mpm_create_prealloc_pool() - Create a new pool for fixed size objects. The |
| * pool uses a contiguous block of pre-alloced |
| * memory. The memory block may either be provided |
| * by the client or dynamically allocated by the |
| * pool manager. |
| * |
| * Parameters: |
| * mgr: INPUT The handle to the pool manager |
| * obj_sz: INPUT Size of objects that will be allocated by the new pool |
| * Must be >= sizeof(void *). |
| * nobj: INPUT Maximum number of concurrently existing objects to support |
| * memstart INPUT Pointer to the memory to use, or NULL to malloc() |
| * memsize INPUT Number of bytes referenced from memstart (for error checking). |
| * Must be 0 if 'memstart' is NULL. |
| * poolname INPUT For instrumentation, the name of the pool |
| * newp: OUTPUT The handle for the new pool, if creation is successful |
| * |
| * Returns: |
| * BCME_OK Pool created ok. |
| * other Pool not created due to indicated error. newpoolp set to NULL. |
| * |
| * |
| */ |
| int bcm_mpm_create_prealloc_pool(bcm_mpm_mgr_h mgr, |
| unsigned int obj_sz, |
| int nobj, |
| void *memstart, |
| unsigned int memsize, |
| char poolname[BCM_MP_NAMELEN], |
| bcm_mp_pool_h *newp); |
| |
| |
| /* |
| * bcm_mpm_delete_prealloc_pool() - Delete a memory pool. This should only be called after |
| * all memory objects have been freed back to the pool. |
| * |
| * Parameters: |
| * mgr: INPUT The handle to the pools manager |
| * pool: INPUT The handle of the pool to delete |
| * |
| * Returns: |
| * BCME_OK Pool deleted ok. |
| * other Pool not deleted due to indicated error. |
| * |
| */ |
| int bcm_mpm_delete_prealloc_pool(bcm_mpm_mgr_h mgr, bcm_mp_pool_h *poolp); |
| |
| /* |
| * bcm_mpm_create_heap_pool() - Create a new pool for fixed size objects. The memory |
| * pool allocator uses the heap (malloc/free) for memory. |
| * In this case, the pool allocator is just providing |
| * statistics and instrumentation on top of the heap, |
| * without modifying the heap allocation implementation. |
| * |
| * Parameters: |
| * mgr: INPUT The handle to the pool manager |
| * obj_sz: INPUT Size of objects that will be allocated by the new pool |
| * poolname INPUT For instrumentation, the name of the pool |
| * newp: OUTPUT The handle for the new pool, if creation is successful |
| * |
| * Returns: |
| * BCME_OK Pool created ok. |
| * other Pool not created due to indicated error. newpoolp set to NULL. |
| * |
| * |
| */ |
| int bcm_mpm_create_heap_pool(bcm_mpm_mgr_h mgr, unsigned int obj_sz, |
| char poolname[BCM_MP_NAMELEN], |
| bcm_mp_pool_h *newp); |
| |
| |
| /* |
| * bcm_mpm_delete_heap_pool() - Delete a memory pool. This should only be called after |
| * all memory objects have been freed back to the pool. |
| * |
| * Parameters: |
| * mgr: INPUT The handle to the pools manager |
| * pool: INPUT The handle of the pool to delete |
| * |
| * Returns: |
| * BCME_OK Pool deleted ok. |
| * other Pool not deleted due to indicated error. |
| * |
| */ |
| int bcm_mpm_delete_heap_pool(bcm_mpm_mgr_h mgr, bcm_mp_pool_h *poolp); |
| |
| |
| /* |
| * bcm_mpm_stats() - Return stats for all pools |
| * |
| * Parameters: |
| * mgr: INPUT The handle to the pools manager |
| * stats: OUTPUT Array of pool statistics. |
| * nentries: MOD Max elements in 'stats' array on INPUT. Actual number |
| * of array elements copied to 'stats' on OUTPUT. |
| * |
| * Returns: |
| * BCME_OK Ok |
| * other Error getting stats. |
| * |
| */ |
| int bcm_mpm_stats(bcm_mpm_mgr_h mgr, bcm_mp_stats_t *stats, int *nentries); |
| |
| |
| /* |
| * bcm_mpm_dump() - Display statistics on all pools |
| * |
| * Parameters: |
| * mgr: INPUT The handle to the pools manager |
| * b: OUTPUT Output buffer. |
| * |
| * Returns: |
| * BCME_OK Ok |
| * other Error during dump. |
| * |
| */ |
| int bcm_mpm_dump(bcm_mpm_mgr_h mgr, struct bcmstrbuf *b); |
| |
| |
| /* |
| * bcm_mpm_get_obj_size() - The size of memory objects may need to be padded to |
| * compensate for alignment requirements of the objects. |
| * This function provides the padded object size. If clients |
| * pre-allocate a memory slab for a memory pool, the |
| * padded object size should be used by the client to allocate |
| * the memory slab (in order to provide sufficent space for |
| * the maximum number of objects). |
| * |
| * Parameters: |
| * mgr: INPUT The handle to the pools manager. |
| * obj_sz: INPUT Input object size. |
| * padded_obj_sz: OUTPUT Padded object size. |
| * |
| * Returns: |
| * BCME_OK Ok |
| * BCME_BADARG Bad arguments. |
| * |
| */ |
| int bcm_mpm_get_obj_size(bcm_mpm_mgr_h mgr, unsigned int obj_sz, unsigned int *padded_obj_sz); |
| |
| |
| /* |
| *************************************************************************** |
| * |
| * API Routines on a specific pool. |
| * |
| *************************************************************************** |
| */ |
| |
| |
| /* |
| * bcm_mp_alloc() - Allocate a memory pool object. |
| * |
| * Parameters: |
| * pool: INPUT The handle to the pool. |
| * |
| * Returns: |
| * A pointer to the new object. NULL on error. |
| * |
| */ |
| void* bcm_mp_alloc(bcm_mp_pool_h pool); |
| |
| /* |
| * bcm_mp_free() - Free a memory pool object. |
| * |
| * Parameters: |
| * pool: INPUT The handle to the pool. |
| * objp: INPUT A pointer to the object to free. |
| * |
| * Returns: |
| * BCME_OK Ok |
| * other Error during free. |
| * |
| */ |
| int bcm_mp_free(bcm_mp_pool_h pool, void *objp); |
| |
| /* |
| * bcm_mp_stats() - Return stats for this pool |
| * |
| * Parameters: |
| * pool: INPUT The handle to the pool |
| * stats: OUTPUT Pool statistics |
| * |
| * Returns: |
| * BCME_OK Ok |
| * other Error getting statistics. |
| * |
| */ |
| int bcm_mp_stats(bcm_mp_pool_h pool, bcm_mp_stats_t *stats); |
| |
| |
| /* |
| * bcm_mp_dump() - Dump a pool |
| * |
| * Parameters: |
| * pool: INPUT The handle to the pool |
| * b OUTPUT Output buffer |
| * |
| * Returns: |
| * BCME_OK Ok |
| * other Error during dump. |
| * |
| */ |
| int bcm_mp_dump(bcm_mp_pool_h pool, struct bcmstrbuf *b); |
| |
| |
| #endif /* _BCM_MPOOL_PUB_H */ |
