ref: e5b73212f6addcfdb5e306df63d7135e543c4f8d
src/libs/mynewt-nimble/porting/nimble/include/os/os_mempool.h
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 |
/* * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file * distributed with this work for additional information * regarding copyright ownership. The ASF licenses this file * to you under the Apache License, Version 2.0 (the * "License"); you may not use this file except in compliance * with the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, * software distributed under the License is distributed on an * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY * KIND, either express or implied. See the License for the * specific language governing permissions and limitations * under the License. */ /** * @addtogroup OSKernel * @{ * @defgroup OSMempool Memory Pools * @{ */ #ifndef _OS_MEMPOOL_H_ #define _OS_MEMPOOL_H_ #include <stdbool.h> #include "os/os.h" #include "os/queue.h" #ifdef __cplusplus extern "C" { #endif /** * A memory block structure. This simply contains a pointer to the free list * chain and is only used when the block is on the free list. When the block * has been removed from the free list the entire memory block is usable by the * caller. */ struct os_memblock { SLIST_ENTRY(os_memblock) mb_next; }; /* XXX: Change this structure so that we keep the first address in the pool? */ /* XXX: add memory debug structure and associated code */ /* XXX: Change how I coded the SLIST_HEAD here. It should be named: SLIST_HEAD(,os_memblock) mp_head; */ /** * Memory pool */ struct os_mempool { /** Size of the memory blocks, in bytes. */ uint32_t mp_block_size; /** The number of memory blocks. */ uint16_t mp_num_blocks; /** The number of free blocks left */ uint16_t mp_num_free; /** The lowest number of free blocks seen */ uint16_t mp_min_free; /** Bitmap of OS_MEMPOOL_F_[...] values. */ uint8_t mp_flags; /** Address of memory buffer used by pool */ uintptr_t mp_membuf_addr; STAILQ_ENTRY(os_mempool) mp_list; SLIST_HEAD(,os_memblock); /** Name for memory block */ char *name; }; /** * Indicates an extended mempool. Address can be safely cast to * (struct os_mempool_ext *). */ #define OS_MEMPOOL_F_EXT 0x01 struct os_mempool_ext; /** * Block put callback function. If configured, this callback gets executed * whenever a block is freed to the corresponding extended mempool. Note: The * os_memblock_put() function calls this callback instead of freeing the block * itself. Therefore, it is the callback's responsibility to free the block * via a call to os_memblock_put_from_cb(). * * @param ome The extended mempool that a block is being * freed back to. * @param data The block being freed. * @param arg Optional argument configured along with the * callback. * * @return Indicates whether the block was successfully * freed. A non-zero value should only be * returned if the block was not successfully * released back to its pool. */ typedef os_error_t os_mempool_put_fn(struct os_mempool_ext *ome, void *data, void *arg); struct os_mempool_ext { struct os_mempool mpe_mp; /* Callback that is executed immediately when a block is freed. */ os_mempool_put_fn *mpe_put_cb; void *mpe_put_arg; }; #define OS_MEMPOOL_INFO_NAME_LEN (32) /** * Information describing a memory pool, used to return OS information * to the management layer. */ struct os_mempool_info { /** Size of the memory blocks in the pool */ int omi_block_size; /** Number of memory blocks in the pool */ int omi_num_blocks; /** Number of free memory blocks */ int omi_num_free; /** Minimum number of free memory blocks ever */ int omi_min_free; /** Name of the memory pool */ char omi_name[OS_MEMPOOL_INFO_NAME_LEN]; }; /** * Get information about the next system memory pool. * * @param mempool The current memory pool, or NULL if starting iteration. * @param info A pointer to the structure to return memory pool information * into. * * @return The next memory pool in the list to get information about, or NULL * when at the last memory pool. */ struct os_mempool *os_mempool_info_get_next(struct os_mempool *, struct os_mempool_info *); /* * To calculate size of the memory buffer needed for the pool. NOTE: This size * is NOT in bytes! The size is the number of os_membuf_t elements required for * the memory pool. */ #if (OS_CFG_ALIGNMENT == OS_CFG_ALIGN_4) #define OS_MEMPOOL_SIZE(n,blksize) ((((blksize) + 3) / 4) * (n)) typedef uint32_t os_membuf_t; #else #define OS_MEMPOOL_SIZE(n,blksize) ((((blksize) + 7) / 8) * (n)) typedef uint64_t os_membuf_t; #endif /** Calculates the number of bytes required to initialize a memory pool. */ #define OS_MEMPOOL_BYTES(n,blksize) \ (sizeof (os_membuf_t) * OS_MEMPOOL_SIZE((n), (blksize))) /** * Initialize a memory pool. * * @param mp Pointer to a pointer to a mempool * @param blocks The number of blocks in the pool * @param blocks_size The size of the block, in bytes. * @param membuf Pointer to memory to contain blocks. * @param name Name of the pool. * * @return os_error_t */ os_error_t os_mempool_init(struct os_mempool *mp, uint16_t blocks, uint32_t block_size, void *membuf, char *name); /** * Initializes an extended memory pool. Extended attributes (e.g., callbacks) * are not specified when this function is called; they are assigned manually * after initialization. * * @param mpe The extended memory pool to initialize. * @param blocks The number of blocks in the pool. * @param block_size The size of each block, in bytes. * @param membuf Pointer to memory to contain blocks. * @param name Name of the pool. * * @return os_error_t */ os_error_t os_mempool_ext_init(struct os_mempool_ext *mpe, uint16_t blocks, uint32_t block_size, void *membuf, char *name); /** * Clears a memory pool. * * @param mp The mempool to clear. * * @return os_error_t */ os_error_t os_mempool_clear(struct os_mempool *mp); /** * Performs an integrity check of the specified mempool. This function * attempts to detect memory corruption in the specified memory pool. * * @param mp The mempool to check. * * @return true if the memory pool passes the integrity * check; * false if the memory pool is corrupt. */ bool os_mempool_is_sane(const struct os_mempool *mp); /** * Checks if a memory block was allocated from the specified mempool. * * @param mp The mempool to check as parent. * @param block_addr The memory block to check as child. * * @return 0 if the block does not belong to the mempool; * 1 if the block does belong to the mempool. */ int os_memblock_from(const struct os_mempool *mp, const void *block_addr); /** * Get a memory block from a memory pool * * @param mp Pointer to the memory pool * * @return void* Pointer to block if available; NULL otherwise */ void *os_memblock_get(struct os_mempool *mp); /** * Puts the memory block back into the pool, ignoring the put callback, if any. * This function should only be called from a put callback to free a block * without causing infinite recursion. * * @param mp Pointer to memory pool * @param block_addr Pointer to memory block * * @return os_error_t */ os_error_t os_memblock_put_from_cb(struct os_mempool *mp, void *block_addr); /** * Puts the memory block back into the pool * * @param mp Pointer to memory pool * @param block_addr Pointer to memory block * * @return os_error_t */ os_error_t os_memblock_put(struct os_mempool *mp, void *block_addr); #ifdef __cplusplus } #endif #endif /* _OS_MEMPOOL_H_ */ /** * @} OSMempool * @} OSKernel */ |