        -:    0:Source:../../../os/common/oslib/include/chfifo.h
        -:    0:Programs:16
        -:    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    chfifo.h
        -:   22: * @brief   Objects FIFO structures and macros.
        -:   23: * @details This module implements a generic FIFO queue of objects by
        -:   24: *          coupling a Guarded Memory Pool (for objects storage) and
        -:   25: *          a MailBox.<br>
        -:   26: *          On the sender side free objects are taken from the pool, filled
        -:   27: *          and then sent to the receiver, on the receiver side objects are
        -:   28: *          fetched, used and then returned to the pool.
        -:   29: *          Operations defined for object FIFOs:
        -:   30: *          - <b>Take</b>: An object is taken from the pool of the free
        -:   31: *            objects, can be blocking.
        -:   32: *          - <b>Return</b>: An object is returned to the pool of the
        -:   33: *            free objects, it is guaranteed to be non-blocking.
        -:   34: *          - <b>Send</b>: An object is sent through the mailbox, it is
        -:   35: *            guaranteed to be non-blocking
        -:   36: *          - <b>Receive</b>: An object is received from the mailbox,
        -:   37: *            can be blocking.
        -:   38: *          .
        -:   39: *
        -:   40: * @addtogroup objects_fifo
        -:   41: * @{
        -:   42: */
        -:   43:
        -:   44:#ifndef CHFIFO_H
        -:   45:#define CHFIFO_H
        -:   46:
        -:   47:#if !defined(CH_CFG_USE_OBJ_FIFOS)
        -:   48:#define CH_CFG_USE_OBJ_FIFOS                TRUE
        -:   49:#endif
        -:   50:
        -:   51:#if (CH_CFG_USE_OBJ_FIFOS == TRUE) || defined(__DOXYGEN__)
        -:   52:
        -:   53:/*===========================================================================*/
        -:   54:/* Module constants.                                                         */
        -:   55:/*===========================================================================*/
        -:   56:
        -:   57:/*===========================================================================*/
        -:   58:/* Module pre-compile time settings.                                         */
        -:   59:/*===========================================================================*/
        -:   60:
        -:   61:/*===========================================================================*/
        -:   62:/* Derived constants and error checks.                                       */
        -:   63:/*===========================================================================*/
        -:   64:
        -:   65:#if CH_CFG_USE_MEMPOOLS == FALSE
        -:   66:#error "CH_CFG_USE_OBJ_FIFOS requires CH_CFG_USE_MEMPOOLS"
        -:   67:#endif
        -:   68:
        -:   69:#if CH_CFG_USE_SEMAPHORES == FALSE
        -:   70:#error "CH_CFG_USE_OBJ_FIFOS requires CH_CFG_USE_SEMAPHORES"
        -:   71:#endif
        -:   72:
        -:   73:#if CH_CFG_USE_MAILBOXES == FALSE
        -:   74:#error "CH_CFG_USE_OBJ_FIFOS requires CH_CFG_USE_MAILBOXES"
        -:   75:#endif
        -:   76:
        -:   77:/*===========================================================================*/
        -:   78:/* Module data structures and types.                                         */
        -:   79:/*===========================================================================*/
        -:   80:
        -:   81:/**
        -:   82: * @brief   Type of an objects FIFO.
        -:   83: */
        -:   84:typedef struct ch_objects_fifo {
        -:   85:  /**
        -:   86:   * @brief   Pool of the free objects.
        -:   87:   */
        -:   88:  guarded_memory_pool_t     free;
        -:   89:  /**
        -:   90:   * @brief   Mailbox of the sent objects.
        -:   91:   */
        -:   92:  mailbox_t                 mbx;
        -:   93:} objects_fifo_t;
        -:   94:
        -:   95:/*===========================================================================*/
        -:   96:/* Module macros.                                                            */
        -:   97:/*===========================================================================*/
        -:   98:
        -:   99:/*===========================================================================*/
        -:  100:/* External declarations.                                                    */
        -:  101:/*===========================================================================*/
        -:  102:
        -:  103:#ifdef __cplusplus
        -:  104:extern "C" {
        -:  105:#endif
        -:  106:
        -:  107:#ifdef __cplusplus
        -:  108:}
        -:  109:#endif
        -:  110:
        -:  111:/*===========================================================================*/
        -:  112:/* Module inline functions.                                                  */
        -:  113:/*===========================================================================*/
        -:  114:
        -:  115:/**
        -:  116: * @brief   Initializes a FIFO object.
        -:  117: * @pre     The messages size must be a multiple of the alignment
        -:  118: *          requirement.
        -:  119: *
        -:  120: * @param[out] ofp      pointer to a @p objects_fifo_t structure
        -:  121: * @param[in] objsize   size of objects
        -:  122: * @param[in] objn      number of objects available
        -:  123: * @param[in] objalign  required objects alignment
        -:  124: * @param[in] objbuf    pointer to the buffer of objects, it must be able
        -:  125: *                      to hold @p objn objects of @p objsize size with
        -:  126: *                      @p objealign alignment
        -:  127: * @param[in] msgbuf    pointer to the buffer of messages, it must be able
        -:  128: *                      to hold @p objn messages
        -:  129: *
        -:  130: * @init
        -:  131: */
function chFifoObjectInit called 1 returned 100% blocks executed 100%
        1:  132:static inline void chFifoObjectInit(objects_fifo_t *ofp, size_t objsize,
        -:  133:                                    size_t objn, unsigned objalign,
        -:  134:                                    void *objbuf, msg_t *msgbuf) {
        -:  135:
        1:  136:  chGuardedPoolObjectInitAligned(&ofp->free, objsize, objalign);
call    0 returned 100%
        1:  137:  chGuardedPoolLoadArray(&ofp->free, objbuf, objn);
call    0 returned 100%
        1:  138:  chMBObjectInit(&ofp->mbx, msgbuf, objn);
call    0 returned 100%
        1:  139:}
        -:  140:
        -:  141:/**
        -:  142: * @brief   Allocates a free object.
        -:  143: *
        -:  144: * @param[in] ofp       pointer to a @p objects_fifo_t structure
        -:  145: * @return              The pointer to the allocated object.
        -:  146: * @retval NULL         if an object is not immediately available.
        -:  147: *
        -:  148: * @iclass
        -:  149: */
        -:  150:static inline void *chFifoTakeObjectI(objects_fifo_t *ofp) {
        -:  151:
        -:  152:  return chGuardedPoolAllocI(&ofp->free);
        -:  153:}
        -:  154:
        -:  155:/**
        -:  156: * @brief   Allocates a free object.
        -:  157: *
        -:  158: * @param[in] ofp       pointer to a @p objects_fifo_t structure
        -:  159: * @param[in] timeout   the number of ticks before the operation timeouts,
        -:  160: *                      the following special values are allowed:
        -:  161: *                      - @a TIME_IMMEDIATE immediate timeout.
        -:  162: *                      - @a TIME_INFINITE no timeout.
        -:  163: *                      .
        -:  164: * @return              The pointer to the allocated object.
        -:  165: * @retval NULL         if an object is not available within the specified
        -:  166: *                      timeout.
        -:  167: *
        -:  168: * @sclass
        -:  169: */
        -:  170:static inline void *chFifoTakeObjectTimeoutS(objects_fifo_t *ofp,
        -:  171:                                             sysinterval_t timeout) {
        -:  172:
        -:  173:  return chGuardedPoolAllocTimeoutS(&ofp->free, timeout);
        -:  174:}
        -:  175:
        -:  176:/**
        -:  177: * @brief   Allocates a free object.
        -:  178: *
        -:  179: * @param[in] ofp       pointer to a @p objects_fifo_t structure
        -:  180: * @param[in] timeout   the number of ticks before the operation timeouts,
        -:  181: *                      the following special values are allowed:
        -:  182: *                      - @a TIME_IMMEDIATE immediate timeout.
        -:  183: *                      - @a TIME_INFINITE no timeout.
        -:  184: *                      .
        -:  185: * @return              The pointer to the allocated object.
        -:  186: * @retval NULL         if an object is not available within the specified
        -:  187: *                      timeout.
        -:  188: *
        -:  189: * @api
        -:  190: */
        -:  191:static inline void *chFifoTakeObjectTimeout(objects_fifo_t *ofp,
        -:  192:                                            sysinterval_t timeout) {
        -:  193:
        -:  194:  return chGuardedPoolAllocTimeout(&ofp->free, timeout);
        -:  195:}
        -:  196:
        -:  197:/**
        -:  198: * @brief   Releases a fetched object.
        -:  199: *
        -:  200: * @param[in] ofp       pointer to a @p objects_fifo_t structure
        -:  201: * @param[in] objp      pointer to the object to be released
        -:  202: *
        -:  203: * @iclass
        -:  204: */
        -:  205:static inline void chFifoReturnObjectI(objects_fifo_t *ofp,
        -:  206:                                       void *objp) {
        -:  207:
        -:  208:  chGuardedPoolFreeI(&ofp->free, objp);
        -:  209:}
        -:  210:
        -:  211:/**
        -:  212: * @brief   Releases a fetched object.
        -:  213: *
        -:  214: * @param[in] ofp       pointer to a @p objects_fifo_t structure
        -:  215: * @param[in] objp      pointer to the object to be released
        -:  216: *
        -:  217: * @api
        -:  218: */
        -:  219:static inline void chFifoReturnObject(objects_fifo_t *ofp,
        -:  220:                                      void *objp) {
        -:  221:
        -:  222:  chGuardedPoolFree(&ofp->free, objp);
        -:  223:}
        -:  224:
        -:  225:/**
        -:  226: * @brief   Posts an object.
        -:  227: * @note    By design the object can be always immediately posted.
        -:  228: *
        -:  229: * @param[in] ofp       pointer to a @p objects_fifo_t structure
        -:  230: * @param[in] objp      pointer to the object to be posted
        -:  231: *
        -:  232: * @iclass
        -:  233: */
        -:  234:static inline void chFifoSendObjectI(objects_fifo_t *ofp,
        -:  235:                                     void *objp) {
        -:  236:  msg_t msg;
        -:  237:
        -:  238:  msg = chMBPostI(&ofp->mbx, (msg_t)objp);
        -:  239:  chDbgAssert(msg == MSG_OK, "post failed");
        -:  240:}
        -:  241:
        -:  242:/**
        -:  243: * @brief   Posts an object.
        -:  244: * @note    By design the object can be always immediately posted.
        -:  245: *
        -:  246: * @param[in] ofp       pointer to a @p objects_fifo_t structure
        -:  247: * @param[in] objp      pointer to the object to be posted
        -:  248: *
        -:  249: * @sclass
        -:  250: */
        -:  251:static inline void chFifoSendObjectS(objects_fifo_t *ofp,
        -:  252:                                     void *objp) {
        -:  253:  msg_t msg;
        -:  254:
        -:  255:  msg = chMBPostTimeoutS(&ofp->mbx, (msg_t)objp, TIME_IMMEDIATE);
        -:  256:  chDbgAssert(msg == MSG_OK, "post failed");
        -:  257:}
        -:  258:
        -:  259:/**
        -:  260: * @brief   Posts an object.
        -:  261: * @note    By design the object can be always immediately posted.
        -:  262: *
        -:  263: * @param[in] ofp       pointer to a @p objects_fifo_t structure
        -:  264: * @param[in] objp      pointer to the object to be released
        -:  265: *
        -:  266: * @api
        -:  267: */
        -:  268:static inline void chFifoSendObject(objects_fifo_t *ofp, void *objp) {
        -:  269:
        -:  270:  msg_t msg;
        -:  271:
        -:  272:  msg = chMBPostTimeout(&ofp->mbx, (msg_t)objp, TIME_IMMEDIATE);
        -:  273:  chDbgAssert(msg == MSG_OK, "post failed");
        -:  274:}
        -:  275:
        -:  276:/**
        -:  277: * @brief   Fetches an object.
        -:  278: *
        -:  279: * @param[in] ofp       pointer to a @p objects_fifo_t structure
        -:  280: * @param[in] objpp     pointer to the fetched object reference
        -:  281: * @return              The operation status.
        -:  282: * @retval MSG_OK       if an object has been correctly fetched.
        -:  283: * @retval MSG_TIMEOUT  if the FIFO is empty and a message cannot be fetched.
        -:  284: *
        -:  285: * @iclass
        -:  286: */
        -:  287:static inline msg_t chFifoReceiveObjectI(objects_fifo_t *ofp,
        -:  288:                                         void **objpp) {
        -:  289:
        -:  290:  return chMBFetchI(&ofp->mbx, (msg_t *)objpp);
        -:  291:}
        -:  292:
        -:  293:/**
        -:  294: * @brief   Fetches an object.
        -:  295: *
        -:  296: * @param[in] ofp       pointer to a @p objects_fifo_t structure
        -:  297: * @param[in] objpp     pointer to the fetched object reference
        -:  298: * @param[in] timeout   the number of ticks before the operation timeouts,
        -:  299: *                      the following special values are allowed:
        -:  300: *                      - @a TIME_IMMEDIATE immediate timeout.
        -:  301: *                      - @a TIME_INFINITE no timeout.
        -:  302: *                      .
        -:  303: * @return              The operation status.
        -:  304: * @retval MSG_OK       if an object has been correctly fetched.
        -:  305: * @retval MSG_TIMEOUT  if the operation has timed out.
        -:  306: *
        -:  307: * @sclass
        -:  308: */
        -:  309:static inline msg_t chFifoReceiveObjectTimeoutS(objects_fifo_t *ofp,
        -:  310:                                                void **objpp,
        -:  311:                                                sysinterval_t timeout) {
        -:  312:
        -:  313:  return chMBFetchTimeoutS(&ofp->mbx, (msg_t *)objpp, timeout);
        -:  314:}
        -:  315:
        -:  316:/**
        -:  317: * @brief   Fetches an object.
        -:  318: *
        -:  319: * @param[in] ofp       pointer to a @p objects_fifo_t structure
        -:  320: * @param[in] objpp     pointer to the fetched object reference
        -:  321: * @param[in] timeout   the number of ticks before the operation timeouts,
        -:  322: *                      the following special values are allowed:
        -:  323: *                      - @a TIME_IMMEDIATE immediate timeout.
        -:  324: *                      - @a TIME_INFINITE no timeout.
        -:  325: *                      .
        -:  326: * @return              The operation status.
        -:  327: * @retval MSG_OK       if an object has been correctly fetched.
        -:  328: * @retval MSG_TIMEOUT  if the operation has timed out.
        -:  329: *
        -:  330: * @api
        -:  331: */
        -:  332:static inline msg_t chFifoReceiveObjectTimeout(objects_fifo_t *ofp,
        -:  333:                                               void **objpp,
        -:  334:                                               sysinterval_t timeout) {
        -:  335:
        -:  336:  return chMBFetchTimeout(&ofp->mbx, (msg_t *)objpp, timeout);
        -:  337:}
        -:  338:#endif /* CH_CFG_USE_OBJ_FIFOS == TRUE */
        -:  339:
        -:  340:#endif /* CHFIFO_H */
        -:  341:
        -:  342:/** @} */
