        -:    0:Source:../../../os/common/oslib/include/chmempools.h
        -:    0:Programs:17
        -:    1:/*
        -:    2:    ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio.
        -:    3:
        -:    4:    This file is part of ChibiOS.
        -:    5:
        -:    6:    ChibiOS is free software; you can redistribute it and/or modify
        -:    7:    it under the terms of the GNU General Public License as published by
        -:    8:    the Free Software Foundation; either version 3 of the License, or
        -:    9:    (at your option) any later version.
        -:   10:
        -:   11:    ChibiOS is distributed in the hope that it will be useful,
        -:   12:    but WITHOUT ANY WARRANTY; without even the implied warranty of
        -:   13:    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
        -:   14:    GNU General Public License for more details.
        -:   15:
        -:   16:    You should have received a copy of the GNU General Public License
        -:   17:    along with this program.  If not, see <http://www.gnu.org/licenses/>.
        -:   18:*/
        -:   19:
        -:   20:/**
        -:   21: * @file    chmempools.h
        -:   22: * @brief   Memory Pools macros and structures.
        -:   23: *
        -:   24: * @addtogroup pools
        -:   25: * @{
        -:   26: */
        -:   27:
        -:   28:#ifndef CHMEMPOOLS_H
        -:   29:#define CHMEMPOOLS_H
        -:   30:
        -:   31:#if !defined(CH_CFG_USE_MEMPOOLS)
        -:   32:#define CH_CFG_USE_MEMPOOLS                 FALSE
        -:   33:#endif
        -:   34:
        -:   35:#if (CH_CFG_USE_MEMPOOLS == TRUE) || defined(__DOXYGEN__)
        -:   36:
        -:   37:/*===========================================================================*/
        -:   38:/* Module constants.                                                         */
        -:   39:/*===========================================================================*/
        -:   40:
        -:   41:/*===========================================================================*/
        -:   42:/* Module pre-compile time settings.                                         */
        -:   43:/*===========================================================================*/
        -:   44:
        -:   45:/*===========================================================================*/
        -:   46:/* Derived constants and error checks.                                       */
        -:   47:/*===========================================================================*/
        -:   48:
        -:   49:#if CH_CFG_USE_MEMCORE == FALSE
        -:   50:#error "CH_CFG_USE_MEMPOOLS requires CH_CFG_USE_MEMCORE"
        -:   51:#endif
        -:   52:
        -:   53:/*===========================================================================*/
        -:   54:/* Module data structures and types.                                         */
        -:   55:/*===========================================================================*/
        -:   56:
        -:   57:/**
        -:   58: * @brief   Memory pool free object header.
        -:   59: */
        -:   60:struct pool_header {
        -:   61:  struct pool_header    *next;          /**< @brief Pointer to the next pool
        -:   62:                                                    header in the list.     */
        -:   63:};
        -:   64:
        -:   65:/**
        -:   66: * @brief   Memory pool descriptor.
        -:   67: */
        -:   68:typedef struct {
        -:   69:  struct pool_header    *next;          /**< @brief Pointer to the header.  */
        -:   70:  size_t                object_size;    /**< @brief Memory pool objects
        -:   71:                                                    size.                   */
        -:   72:  unsigned              align;          /**< @brief Required alignment.     */
        -:   73:  memgetfunc_t          provider;       /**< @brief Memory blocks provider
        -:   74:                                                    for this pool.          */
        -:   75:} memory_pool_t;
        -:   76:
        -:   77:#if (CH_CFG_USE_SEMAPHORES == TRUE) || defined(__DOXYGEN__)
        -:   78:/**
        -:   79: * @brief   Guarded memory pool descriptor.
        -:   80: */
        -:   81:typedef struct {
        -:   82:  semaphore_t           sem;            /**< @brief Counter semaphore guarding
        -:   83:                                                    the memory pool.        */
        -:   84:  memory_pool_t         pool;           /**< @brief The memory pool itself. */
        -:   85:} guarded_memory_pool_t;
        -:   86:#endif /* CH_CFG_USE_SEMAPHORES == TRUE */
        -:   87:
        -:   88:/*===========================================================================*/
        -:   89:/* Module macros.                                                            */
        -:   90:/*===========================================================================*/
        -:   91:
        -:   92:/**
        -:   93: * @brief   Data part of a static memory pool initializer.
        -:   94: * @details This macro should be used when statically initializing a
        -:   95: *          memory pool that is part of a bigger structure.
        -:   96: *
        -:   97: * @param[in] name      the name of the memory pool variable
        -:   98: * @param[in] size      size of the memory pool contained objects
        -:   99: * @param[in] align     required memory alignment
        -:  100: * @param[in] provider  memory provider function for the memory pool
        -:  101: */
        -:  102:#define _MEMORYPOOL_DATA(name, size, align, provider)                       \
        -:  103:  {NULL, size, align, provider}
        -:  104:
        -:  105:/**
        -:  106: * @brief   Static memory pool initializer.
        -:  107: * @details Statically initialized memory pools require no explicit
        -:  108: *          initialization using @p chPoolInit().
        -:  109: *
        -:  110: * @param[in] name      the name of the memory pool variable
        -:  111: * @param[in] size      size of the memory pool contained objects
        -:  112: * @param[in] align     required memory alignment
        -:  113: * @param[in] provider  memory provider function for the memory pool or @p NULL
        -:  114: *                      if the pool is not allowed to grow automatically
        -:  115: */
        -:  116:#define MEMORYPOOL_DECL(name, size, align, provider)                        \
        -:  117:  memory_pool_t name = _MEMORYPOOL_DATA(name, size, align, provider)
        -:  118:
        -:  119:#if (CH_CFG_USE_SEMAPHORES == TRUE) || defined(__DOXYGEN__)
        -:  120:/**
        -:  121: * @brief   Data part of a static guarded memory pool initializer.
        -:  122: * @details This macro should be used when statically initializing a
        -:  123: *          memory pool that is part of a bigger structure.
        -:  124: *
        -:  125: * @param[in] name      the name of the memory pool variable
        -:  126: * @param[in] size      size of the memory pool contained objects
        -:  127: * @param[in] align     required memory alignment
        -:  128: */
        -:  129:#define _GUARDEDMEMORYPOOL_DATA(name, size, align) {                        \
        -:  130:  _SEMAPHORE_DATA(name.sem, (cnt_t)0),                                      \
        -:  131:  _MEMORYPOOL_DATA(NULL, size, align, NULL)                                 \
        -:  132:}
        -:  133:
        -:  134:/**
        -:  135: * @brief   Static guarded memory pool initializer.
        -:  136: * @details Statically initialized guarded memory pools require no explicit
        -:  137: *          initialization using @p chGuardedPoolInit().
        -:  138: *
        -:  139: * @param[in] name      the name of the guarded memory pool variable
        -:  140: * @param[in] size      size of the memory pool contained objects
        -:  141: * @param[in] align     required memory alignment
        -:  142: */
        -:  143:#define GUARDEDMEMORYPOOL_DECL(name, size, align)                           \
        -:  144:  guarded_memory_pool_t name = _GUARDEDMEMORYPOOL_DATA(name, size, align)
        -:  145:#endif /* CH_CFG_USE_SEMAPHORES == TRUE */
        -:  146:
        -:  147:/*===========================================================================*/
        -:  148:/* External declarations.                                                    */
        -:  149:/*===========================================================================*/
        -:  150:
        -:  151:#ifdef __cplusplus
        -:  152:extern "C" {
        -:  153:#endif
        -:  154:  void chPoolObjectInitAligned(memory_pool_t *mp, size_t size,
        -:  155:                               unsigned align, memgetfunc_t provider);
        -:  156:  void chPoolLoadArray(memory_pool_t *mp, void *p, size_t n);
        -:  157:  void *chPoolAllocI(memory_pool_t *mp);
        -:  158:  void *chPoolAlloc(memory_pool_t *mp);
        -:  159:  void chPoolFreeI(memory_pool_t *mp, void *objp);
        -:  160:  void chPoolFree(memory_pool_t *mp, void *objp);
        -:  161:#if CH_CFG_USE_SEMAPHORES == TRUE
        -:  162:  void chGuardedPoolObjectInitAligned(guarded_memory_pool_t *gmp,
        -:  163:                                      size_t size,
        -:  164:                                      unsigned align);
        -:  165:  void chGuardedPoolLoadArray(guarded_memory_pool_t *gmp, void *p, size_t n);
        -:  166:  void *chGuardedPoolAllocTimeoutS(guarded_memory_pool_t *gmp,
        -:  167:                                   sysinterval_t timeout);
        -:  168:  void *chGuardedPoolAllocTimeout(guarded_memory_pool_t *gmp,
        -:  169:                                  sysinterval_t timeout);
        -:  170:  void chGuardedPoolFreeI(guarded_memory_pool_t *gmp, void *objp);
        -:  171:  void chGuardedPoolFree(guarded_memory_pool_t *gmp, void *objp);
        -:  172:#endif
        -:  173:#ifdef __cplusplus
        -:  174:}
        -:  175:#endif
        -:  176:
        -:  177:/*===========================================================================*/
        -:  178:/* Module inline functions.                                                  */
        -:  179:/*===========================================================================*/
        -:  180:
        -:  181:/**
        -:  182: * @brief   Initializes an empty memory pool.
        -:  183: *
        -:  184: * @param[out] mp       pointer to a @p memory_pool_t structure
        -:  185: * @param[in] size      the size of the objects contained in this memory pool,
        -:  186: *                      the minimum accepted size is the size of a pointer to
        -:  187: *                      void.
        -:  188: * @param[in] provider  memory provider function for the memory pool or
        -:  189: *                      @p NULL if the pool is not allowed to grow
        -:  190: *                      automatically
        -:  191: *
        -:  192: * @init
        -:  193: */
function chPoolObjectInit called 2 returned 100% blocks executed 100%
        2:  194:static inline void chPoolObjectInit(memory_pool_t *mp,
        -:  195:                                    size_t size,
        -:  196:                                    memgetfunc_t provider) {
        -:  197:
        2:  198:  chPoolObjectInitAligned(mp, size, PORT_NATURAL_ALIGN, provider);
call    0 returned 100%
        2:  199:}
        -:  200:
        -:  201:/**
        -:  202: * @brief   Adds an object to a memory pool.
        -:  203: * @pre     The memory pool must be already been initialized.
        -:  204: * @pre     The added object must be of the right size for the specified
        -:  205: *          memory pool.
        -:  206: * @pre     The added object must be memory aligned to the size of
        -:  207: *          @p stkalign_t type.
        -:  208: * @note    This function is just an alias for @p chPoolFree() and has been
        -:  209: *          added for clarity.
        -:  210: *
        -:  211: * @param[in] mp        pointer to a @p memory_pool_t structure
        -:  212: * @param[in] objp      the pointer to the object to be added
        -:  213: *
        -:  214: * @api
        -:  215: */
function chPoolAdd called 4 returned 100% blocks executed 100%
        4:  216:static inline void chPoolAdd(memory_pool_t *mp, void *objp) {
        -:  217:
        4:  218:  chPoolFree(mp, objp);
call    0 returned 100%
        4:  219:}
        -:  220:
        -:  221:/**
        -:  222: * @brief   Adds an object to a memory pool.
        -:  223: * @pre     The memory pool must be already been initialized.
        -:  224: * @pre     The added object must be of the right size for the specified
        -:  225: *          memory pool.
        -:  226: * @pre     The added object must be memory aligned to the size of
        -:  227: *          @p stkalign_t type.
        -:  228: * @note    This function is just an alias for @p chPoolFreeI() and has been
        -:  229: *          added for clarity.
        -:  230: *
        -:  231: * @param[in] mp        pointer to a @p memory_pool_t structure
        -:  232: * @param[in] objp      the pointer to the object to be added
        -:  233: *
        -:  234: * @iclass
        -:  235: */
        -:  236:static inline void chPoolAddI(memory_pool_t *mp, void *objp) {
        -:  237:
        -:  238:  chPoolFreeI(mp, objp);
        -:  239:}
        -:  240:
        -:  241:#if (CH_CFG_USE_SEMAPHORES == TRUE) || defined(__DOXYGEN__)
        -:  242:/**
        -:  243: * @brief   Initializes an empty guarded memory pool.
        -:  244: *
        -:  245: * @param[out] gmp      pointer to a @p guarded_memory_pool_t structure
        -:  246: * @param[in] size      the size of the objects contained in this guarded
        -:  247: *                      memory pool, the minimum accepted size is the size
        -:  248: *                      of a pointer to void.
        -:  249: *
        -:  250: * @init
        -:  251: */
        -:  252:static inline void chGuardedPoolObjectInit(guarded_memory_pool_t *gmp,
        -:  253:                                           size_t size) {
        -:  254:
        -:  255:  chGuardedPoolObjectInitAligned(gmp, size, PORT_NATURAL_ALIGN);
        -:  256:}
        -:  257:
        -:  258:/**
        -:  259: * @brief   Adds an object to a guarded memory pool.
        -:  260: * @pre     The guarded memory pool must be already been initialized.
        -:  261: * @pre     The added object must be of the right size for the specified
        -:  262: *          guarded memory pool.
        -:  263: * @pre     The added object must be properly aligned.
        -:  264: * @note    This function is just an alias for @p chGuardedPoolFree() and
        -:  265: *          has been added for clarity.
        -:  266: *
        -:  267: * @param[in] gmp       pointer to a @p guarded_memory_pool_t structure
        -:  268: * @param[in] objp      the pointer to the object to be added
        -:  269: *
        -:  270: * @api
        -:  271: */
function chGuardedPoolAdd called 20 returned 100% blocks executed 100%
       20:  272:static inline void chGuardedPoolAdd(guarded_memory_pool_t *gmp, void *objp) {
        -:  273:
       20:  274:  chGuardedPoolFree(gmp, objp);
call    0 returned 100%
       20:  275:}
        -:  276:
        -:  277:/**
        -:  278: * @brief   Adds an object to a guarded memory pool.
        -:  279: * @pre     The guarded memory pool must be already been initialized.
        -:  280: * @pre     The added object must be of the right size for the specified
        -:  281: *          guarded memory pool.
        -:  282: * @pre     The added object must be properly aligned.
        -:  283: * @note    This function is just an alias for @p chGuardedPoolFreeI() and
        -:  284: *          has been added for clarity.
        -:  285: *
        -:  286: * @param[in] gmp       pointer to a @p guarded_memory_pool_t structure
        -:  287: * @param[in] objp      the pointer to the object to be added
        -:  288: *
        -:  289: * @iclass
        -:  290: */
        -:  291:static inline void chGuardedPoolAddI(guarded_memory_pool_t *gmp, void *objp) {
        -:  292:
        -:  293:  chGuardedPoolFreeI(gmp, objp);
        -:  294:}
        -:  295:
        -:  296:/**
        -:  297: * @brief   Allocates an object from a guarded memory pool.
        -:  298: * @pre     The guarded memory pool must be already been initialized.
        -:  299: *
        -:  300: * @param[in] gmp       pointer to a @p guarded_memory_pool_t structure
        -:  301: * @return              The pointer to the allocated object.
        -:  302: * @retval NULL         if the pool is empty.
        -:  303: *
        -:  304: * @iclass
        -:  305: */
        -:  306:static inline void *chGuardedPoolAllocI(guarded_memory_pool_t *gmp) {
        -:  307:  void *p;
        -:  308:
        -:  309:  p = chPoolAllocI(&gmp->pool);
        -:  310:  if (p != NULL) {
        -:  311:    chSemFastWaitI(&gmp->sem);
        -:  312:    chDbgAssert(chSemGetCounterI(&gmp->sem) >= (cnt_t)0,
        -:  313:                "semaphore out of sync");
        -:  314:  }
        -:  315:  return p;
        -:  316:}
        -:  317:#endif /* CH_CFG_USE_SEMAPHORES == TRUE */
        -:  318:
        -:  319:#endif /* CH_CFG_USE_MEMPOOLS == TRUE */
        -:  320:
        -:  321:#endif /* CHMEMPOOLS_H */
        -:  322:
        -:  323:/** @} */
