release/src-rt-6.x.4708/include/bcm_mpool_pub.h

   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) 2012, Broadcom Corporation. All Rights Reserved.
  39  *
  40  * Permission to use, copy, modify, and/or distribute this software for any
  41  * purpose with or without fee is hereby granted, provided that the above
  42  * copyright notice and this permission notice appear in all copies.
  43  *
  44  * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  45  * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  46  * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
  47  * SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  48  * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
  49  * OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
  50  * CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  51  *
  52  * $Id$
  53  */
  54
  55 #ifndef _BCM_MPOOL_PUB_H
  56 #define _BCM_MPOOL_PUB_H 1
  57
  58 #include <typedefs.h> /* needed for uint16 */
  59
  60
  61 /*
  62 **************************************************************************
  63 *
  64 * Type definitions, handles
  65 *
  66 **************************************************************************
  67 */
  68
  69 /* Forward declaration of OSL handle. */
  70 struct osl_info;
  71
  72 /* Forward declaration of string buffer. */
  73 struct bcmstrbuf;
  74
  75 /*
  76  * Opaque type definition for the pool manager handle. This object is used for global
  77  * memory pool operations such as obtaining a new pool, deleting a pool, iterating and
  78  * instrumentation/debugging.
  79  */
  80 struct bcm_mpm_mgr;
  81 typedef struct bcm_mpm_mgr *bcm_mpm_mgr_h;
  82
  83 /*
  84  * Opaque type definition for an instance of a pool. This handle is used for allocating
  85  * and freeing memory through the pool, as well as management/instrumentation on this
  86  * specific pool.
  87  */
  88 struct bcm_mp_pool;
  89 typedef struct bcm_mp_pool *bcm_mp_pool_h;
  90
  91
  92 /*
  93  * To make instrumentation more readable, every memory
  94  * pool must have a readable name. Pool names are up to
  95  * 8 bytes including '\0' termination. (7 printable characters.)
  96  */
  97 #define BCM_MP_NAMELEN 8
  98
  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 *
 116 * API Routines on the pool manager.
 117 *
 118 **************************************************************************
 119 */
 120
 121 /*
 122  * bcm_mpm_init() - initialize the whole memory pool system.
 123  *
 124  * Parameters:
 125  *    osh:       INPUT  Operating system handle. Needed for heap memory allocation.
 126  *    max_pools: INPUT Maximum number of mempools supported.
 127  *    mgr:       OUTPUT The handle is written with the new pools manager object/handle.
 128  *
 129  * Returns:
 130  *    BCME_OK     Object initialized successfully. May be used.
 131  *    BCME_NOMEM  Initialization failed due to no memory. Object must not be used.
 132  */
 133 int bcm_mpm_init(struct osl_info *osh, int max_pools, bcm_mpm_mgr_h *mgrp);
 134
 135
 136 /*
 137  * bcm_mpm_deinit() - de-initialize the whole memory pool system.
 138  *
 139  * Parameters:
 140  *    mgr:     INPUT  Pointer to pool manager handle.
 141  *
 142  * Returns:
 143  *    BCME_OK  Memory pool manager successfully de-initialized.
 144  *    other    Indicated error occured during de-initialization.
 145  */
 146 int bcm_mpm_deinit(bcm_mpm_mgr_h *mgrp);
 147
 148 /*
 149  * bcm_mpm_create_prealloc_pool() - Create a new pool for fixed size objects. The
 150  *                                  pool uses a contiguous block of pre-alloced
 151  *                                  memory. The memory block may either be provided
 152  *                                  by the client or dynamically allocated by the
 153  *                                  pool manager.
 154  *
 155  * Parameters:
 156  *    mgr:      INPUT  The handle to the pool manager
 157  *    obj_sz:   INPUT  Size of objects that will be allocated by the new pool
 158  *                     Must be >= sizeof(void *).
 159  *    nobj:     INPUT  Maximum number of concurrently existing objects to support
 160  *    memstart  INPUT  Pointer to the memory to use, or NULL to malloc()
 161  *    memsize   INPUT  Number of bytes referenced from memstart (for error checking).
 162  *                     Must be 0 if 'memstart' is NULL.
 163  *    poolname  INPUT  For instrumentation, the name of the pool
 164  *    newp:     OUTPUT The handle for the new pool, if creation is successful
 165  *
 166  * Returns:
 167  *    BCME_OK   Pool created ok.
 168  *    other     Pool not created due to indicated error. newpoolp set to NULL.
 169  *
 170  *
 171  */
 172 int bcm_mpm_create_prealloc_pool(bcm_mpm_mgr_h mgr,
 173                                  unsigned int obj_sz,
 174                                  int nobj,
 175                                  void *memstart,
 176                                  unsigned int memsize,
 177                                  const char poolname[BCM_MP_NAMELEN],
 178                                  bcm_mp_pool_h *newp);
 179
 180
 181 /*
 182  * bcm_mpm_delete_prealloc_pool() - Delete a memory pool. This should only be called after
 183  *                                  all memory objects have been freed back to the pool.
 184  *
 185  * Parameters:
 186  *    mgr:     INPUT The handle to the pools manager
 187  *    pool:    INPUT The handle of the  pool to delete
 188  *
 189  * Returns:
 190  *    BCME_OK   Pool deleted ok.
 191  *    other     Pool not deleted due to indicated error.
 192  *
 193  */
 194 int bcm_mpm_delete_prealloc_pool(bcm_mpm_mgr_h mgr, bcm_mp_pool_h *poolp);
 195
 196 /*
 197  * bcm_mpm_create_heap_pool() - Create a new pool for fixed size objects. The memory
 198  *                              pool allocator uses the heap (malloc/free) for memory.
 199  *                              In this case, the pool allocator is just providing
 200  *                              statistics and instrumentation on top of the heap,
 201  *                              without modifying the heap allocation implementation.
 202  *
 203  * Parameters:
 204  *    mgr:      INPUT  The handle to the pool manager
 205  *    obj_sz:   INPUT  Size of objects that will be allocated by the new pool
 206  *    poolname  INPUT  For instrumentation, the name of the pool
 207  *    newp:     OUTPUT The handle for the new pool, if creation is successful
 208  *
 209  * Returns:
 210  *    BCME_OK   Pool created ok.
 211  *    other     Pool not created due to indicated error. newpoolp set to NULL.
 212  *
 213  *
 214  */
 215 int bcm_mpm_create_heap_pool(bcm_mpm_mgr_h mgr, unsigned int obj_sz,
 216                              const char poolname[BCM_MP_NAMELEN],
 217                              bcm_mp_pool_h *newp);
 218
 219
 220 /*
 221  * bcm_mpm_delete_heap_pool() - Delete a memory pool. This should only be called after
 222  *                              all memory objects have been freed back to the pool.
 223  *
 224  * Parameters:
 225  *    mgr:     INPUT The handle to the pools manager
 226  *    pool:    INPUT The handle of the  pool to delete
 227  *
 228  * Returns:
 229  *    BCME_OK   Pool deleted ok.
 230  *    other     Pool not deleted due to indicated error.
 231  *
 232  */
 233 int bcm_mpm_delete_heap_pool(bcm_mpm_mgr_h mgr, bcm_mp_pool_h *poolp);
 234
 235
 236 /*
 237  * bcm_mpm_stats() - Return stats for all pools
 238  *
 239  * Parameters:
 240  *    mgr:         INPUT   The handle to the pools manager
 241  *    stats:       OUTPUT  Array of pool statistics.
 242  *    nentries:    MOD     Max elements in 'stats' array on INPUT. Actual number
 243  *                         of array elements copied to 'stats' on OUTPUT.
 244  *
 245  * Returns:
 246  *    BCME_OK   Ok
 247  *    other     Error getting stats.
 248  *
 249  */
 250 int bcm_mpm_stats(bcm_mpm_mgr_h mgr, bcm_mp_stats_t *stats, int *nentries);
 251
 252
 253 /*
 254  * bcm_mpm_dump() - Display statistics on all pools
 255  *
 256  * Parameters:
 257  *    mgr:     INPUT  The handle to the pools manager
 258  *    b:       OUTPUT Output buffer.
 259  *
 260  * Returns:
 261  *    BCME_OK   Ok
 262  *    other     Error during dump.
 263  *
 264  */
 265 int bcm_mpm_dump(bcm_mpm_mgr_h mgr, struct bcmstrbuf *b);
 266
 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 *
 293 * API Routines on a specific pool.
 294 *
 295 ***************************************************************************
 296 */
 297
 298
 299 /*
 300  * bcm_mp_alloc() - Allocate a memory pool object.
 301  *
 302  * Parameters:
 303  *    pool:    INPUT    The handle to the pool.
 304  *
 305  * Returns:
 306  *    A pointer to the new object. NULL on error.
 307  *
 308  */
 309 void* bcm_mp_alloc(bcm_mp_pool_h pool);
 310
 311 /*
 312  * bcm_mp_free() - Free a memory pool object.
 313  *
 314  * Parameters:
 315  *    pool:  INPUT   The handle to the pool.
 316  *    objp:  INPUT   A pointer to the object to free.
 317  *
 318  * Returns:
 319  *    BCME_OK   Ok
 320  *    other     Error during free.
 321  *
 322  */
 323 int bcm_mp_free(bcm_mp_pool_h pool, void *objp);
 324
 325 /*
 326  * bcm_mp_stats() - Return stats for this pool
 327  *
 328  * Parameters:
 329  *    pool:     INPUT    The handle to the pool
 330  *    stats:    OUTPUT   Pool statistics
 331  *
 332  * Returns:
 333  *    BCME_OK   Ok
 334  *    other     Error getting statistics.
 335  *
 336  */
 337 int bcm_mp_stats(bcm_mp_pool_h pool, bcm_mp_stats_t *stats);
 338
 339
 340 /*
 341  * bcm_mp_dump() - Dump a pool
 342  *
 343  * Parameters:
 344  *    pool:    INPUT    The handle to the pool
 345  *    b        OUTPUT   Output buffer
 346  *
 347  * Returns:
 348  *    BCME_OK   Ok
 349  *    other     Error during dump.
 350  *
 351  */
 352 int bcm_mp_dump(bcm_mp_pool_h pool, struct bcmstrbuf *b);
 353
 354
 355 #endif /* _BCM_MPOOL_PUB_H */