release/src-rt-6.x.4708/shared/bcm_mpool_pri.h

   1 /*
   2  *
   3  * Memory pool type definitions
   4  *
   5  * Prealloc memory pools:
   6  *    These memory pools are memory allocators based on subdividing a single
   7  *    block of memory into homogenous objects. It's suitable for data structures
   8  *    with a statically configured maximum # of objects, such as using tunable
   9  *    parameters. It's not suitable for heterogenous data structures nor for
  10  *    data structures where the maximum count is unbounded.
  11  *
  12  *    Since the memory for all the objects is preallocated during initialization,
  13  *    that memory is unavailable to the rest of the system. This is appropriate both for
  14  *    small data structures, and for medium/large data structures where the peak and average
  15  *    utilization are similar. For data structures where average utilization is low but peak
  16  *    is very high, it's better to use the real heap so the memory gets freed when it's
  17  *    not in use.
  18  *
  19  *    Each individual memory pool can obtain it's memory from the user/client
  20  *    code or from the heap, as desired.
  21  *
  22  *
  23  * Heap memory pools:
  24  *    The memory pool allocator uses the heap (malloc/free) for memory.
  25  *    In this case, the pool allocator is just providing statistics and instrumentation
  26  *    on top of the heap, without modifying the heap allocation implementation.
  27  *
  28  * The memory pool component consists of two major abstractions:
  29  *     Manager: the factory for memory pools
  30  *     Pool: an individual pool that can allocate objects
  31  *
  32  * The memory pool manager maintains an array of individual pools so that instrumentation
  33  * can examine and manage all of them globally.
  34  *
  35  * Copyright (C) 2012, Broadcom Corporation
  36  * All Rights Reserved.
  37  *
  38  * This is UNPUBLISHED PROPRIETARY SOURCE CODE of Broadcom Corporation;
  39  * the contents of this file may not be disclosed to third parties, copied
  40  * or duplicated in any form, in whole or in part, without the prior
  41  * written permission of Broadcom Corporation.
  42  *
  43  * $Id$
  44  */
  45
  46 /*
  47  *
  48  *  List Manager
  49  *  +------------+
  50  *  | free_pools |------------------------------------+
  51  *  +------------+                                    |
  52  *  | pool_objs  |>+                                  |
  53  *  +------------+ |                                  |
  54  *  | npools     | |                                  |
  55  *  +------------+ |                                  |
  56  *  | max_pools  | |                                  |
  57  *  +------------+ |                                  |
  58  *  | osh        | |                                  |
  59  *  +------------+ |                                  |
  60  *                 |                                  |
  61  *                 |                                  |
  62  *                 |                                  |
  63  *                 |                                  |
  64  *                 v                                  v
  65  *              +--------------++--------------++--------------++--------------+
  66  *              | name         || name         || name         || name         |
  67  *       Meta   +--------------++--------------++--------------++--------------+
  68  *       Data   | objsz        || objsz        || objsz        || objsz        |
  69  *              +--------------++--------------++--------------++--------------+
  70  *              | num_alloc    || num_alloc    || num_alloc    || num_alloc    |
  71  *              +--------------++--------------++--------------++--------------+
  72  *              | high_water   || high_water   || high_water   || high_water   |
  73  *              +--------------++--------------++--------------++--------------+
  74  *              | failed_alloc || failed_alloc || failed_alloc || failed_alloc |
  75  *              +--------------++--------------++--------------++--------------+
  76  *              | flags (used) || flags (used) || flags (free) || flags (used) |
  77  *              +--------------++--------------++--------------++--------------+
  78  *              | nobj         || nobj         || nobj         || nobj         |
  79  *              +--------------++--------------++--------------++--------------+
  80  *              | memstart     || memstart     || memstart     || memstart     |
  81  *              +--------------++--------------++--------------++--------------+
  82  *              | freep        || freep        || freep        || freep        |
  83  *              +--------------++--------------++--------------++--------------+
  84  *                     |               |                                |
  85  *                     |               |                                |
  86  *                     v               v                                v
  87  *                 +-------+       +-------+                        +-------+
  88  *                 |       |       |       |                        |       |
  89  *                 | obj1  |       | obj1  |                        | obj1  |
  90  *                 |       |       |       |                        |       |
  91  *                 +-------+       +-------+                        +-------+
  92  *                     .               .                                .
  93  *                     .               .                                .
  94  *                     .               .                                .
  95  *                 +-------+       +-------+                        +-------+
  96  *                 |       |       |       |                        |       |
  97  *                 |       |       | objM  |                        |       |
  98  *                 |       |       |       |                        |       |
  99  *                 +-------+       +-------+                        +-------+
 100  *                 |       |                                        |       |
 101  *                 |       |                                        |       |
 102  *                 |       |                                        |       |
 103  *                 +-------+                                        +-------+
 104  *                 |       |                                        |       |
 105  *                 |       |                                        |       |
 106  *                 |       |                                        |       |
 107  *                 +-------+                                        +-------+
 108  *                 |       |                                        |       |
 109  *                 | objN  |                                        |       |
 110  *                 |       |                                        |       |
 111  *                 +-------+                                        +-------+
 112  *                                                                  |       |
 113  *                                                                  | objP  |
 114  *                                                                  |       |
 115  *                                                                  +-------+
 116  *
 117  */
 118
 119 #ifndef _BCM_MPOOL_PRI_H
 120 #define _BCM_MPOOL_PRI_H 1
 121
 122
 123 #include "osl.h"
 124 #include "typedefs.h"
 125 #include "bcm_mpool_pub.h"
 126
 127
 128 /*
 129  * Pool definitions.
 130  */
 131
 132
 133 /*
 134  * This structure is used to maintain a list of free objects.
 135  */
 136 typedef struct bcm_mp_free_list {
 137         struct bcm_mp_free_list *next;  /* Next pointer for the linked-list */
 138 } bcm_mp_free_list_t;
 139
 140
 141 /*
 142  * Type definition for an instance data specific to a prealloc pool.
 143  */
 144 typedef struct bcm_mp_prealloc_pool {
 145         /* Pre-alloc pool specific state. */
 146         uint16             nobj;             /* Total number of objects in this pool */
 147         unsigned int       padded_objsz;     /* Padded object size allocated in this pool */
 148         void               *malloc_memstart; /* Contiguous block of malloced memory objects. */
 149         bcm_mp_free_list_t *free_objp;       /* Free list of memory objects. */
 150 } bcm_mp_prealloc_pool_t;
 151
 152
 153 /*
 154  * Type definition for an instance data specific to a heap pool.
 155  */
 156 typedef struct bcm_mp_heap_pool {
 157         /* Heap pool specific state. */
 158         osl_t *osh;   /* OSH for malloc and free */
 159 } bcm_mp_heap_pool_t;
 160
 161
 162 /*
 163  * Type definition for an instance of a pool. This handle is used for allocating
 164  * and freeing memory through the pool, as well as management/instrumentation on this
 165  * specific pool.
 166  */
 167 typedef struct bcm_mp_pool {
 168         /* Common state. */
 169         char   name[BCM_MP_NAMELEN];      /* Name of this pool. */
 170         unsigned int objsz;               /* Object size allocated in this pool */
 171         uint16 num_alloc;                 /* Number of objects currently allocated */
 172         uint16 high_water;                /* Max number of allocated objects. */
 173         uint16 failed_alloc;              /* Failed allocations. */
 174         uint16 flags;                     /* Flags */
 175
 176         /* State specific to pool-type. */
 177         union {
 178                 bcm_mp_prealloc_pool_t p;  /* Prealloc pool. */
 179                 bcm_mp_heap_pool_t     h;  /* Heap pool. */
 180         } u;
 181 } bcm_mp_pool_t;
 182
 183
 184 /*
 185  * Flags definitions for 'flags' structure member of 'bcm_mp_pool'.
 186  */
 187
 188 /* Bits for pool-type. */
 189 #define BCM_MP_TYPE_MASK     0x0003 /* Mask for the bit position of pool type */
 190 #define BCM_MP_TYPE_HEAP     0      /* Bit equals zero means heap pool type */
 191 #define BCM_MP_TYPE_PREALLOC 1      /* Bit equals one means pre-alloc pool type */
 192
 193 /* Accessor functions for pool-type. */
 194 #define BCM_MP_GET_POOL_TYPE(pool) (((pool)->flags) & BCM_MP_TYPE_MASK)
 195 #define BCM_MP_SET_POOL_TYPE(pool, type) ((pool)->flags = ((pool)->flags & ~BCM_MP_TYPE_MASK) \
 196                                                            | (type))
 197
 198
 199 /* Bits in indicate if memory pool is in-use. */
 200 #define BCM_MP_POOL_IN_USE_MASK 0x0004
 201
 202 /* Bits in indicate if memory pool is in use. */
 203 #define BCM_MP_SET_IN_USE(pool) ((pool)->flags |= BCM_MP_POOL_IN_USE_MASK)
 204 #define BCM_MP_CLEAR_IN_USE(pool) ((pool)->flags &= ~BCM_MP_POOL_IN_USE_MASK)
 205 #define BCM_MP_IS_IN_USE(pool) (((pool)->flags & BCM_MP_POOL_IN_USE_MASK) == \
 206                                                  BCM_MP_POOL_IN_USE_MASK)
 207
 208
 209 /*
 210  * Manager definition. Used to create new pools and for global instrumentation.
 211  */
 212 typedef struct bcm_mpm_mgr {
 213         bcm_mp_pool_t      *pool_objs;   /* Array of malloced memory pool objects. */
 214         bcm_mp_free_list_t *free_pools;  /* Free list of memory pools. */
 215         uint16             npools;       /* Number of pools currently allocated */
 216         uint16             max_pools;    /* Max number of pools  */
 217         osl_t              *osh;         /* OSH for malloc and free */
 218 } bcm_mpm_mgr_t;
 219
 220
 221 #endif /* _BCM_MPOOL_PRI_H */