interface/vcos/vcos_queue.h

   1 /*
   2 Copyright (c) 2012, Broadcom Europe Ltd
   3 All rights reserved.
   4
   5 Redistribution and use in source and binary forms, with or without
   6 modification, are permitted provided that the following conditions are met:
   7     * Redistributions of source code must retain the above copyright
   8       notice, this list of conditions and the following disclaimer.
   9     * Redistributions in binary form must reproduce the above copyright
  10       notice, this list of conditions and the following disclaimer in the
  11       documentation and/or other materials provided with the distribution.
  12     * Neither the name of the copyright holder nor the
  13       names of its contributors may be used to endorse or promote products
  14       derived from this software without specific prior written permission.
  15
  16 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
  17 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  18 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  19 DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY
  20 DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  21 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  22 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  23 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  24 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  25 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  26 */
  27
  28 /*=============================================================================
  29 VideoCore OS Abstraction Layer - Queue public header file
  30 =============================================================================*/
  31
  32 #ifndef VCOS_QUEUE_H
  33 #define VCOS_QUEUE_H
  34
  35 #ifdef __cplusplus
  36 extern "C" {
  37 #endif
  38
  39 #include "interface/vcos/vcos_types.h"
  40 #include "vcos.h"
  41
  42 /** \file vcos_queue.h
  43   *
  44   * API for accessing a fixed length queue.
  45   *
  46   * Nucleus offers variable length items, but this feature is not used
  47   * in the current code base, so is withdrawn to simplify the API.
  48   */
  49
  50 /** Create a fixed length queue.
  51   *
  52   * @param queue        Pointer to queue control block
  53   * @param name         Name of queue
  54   * @param message_size Size of each queue message item in words (words are sizeof VCOS_UNSIGNED).
  55   * @param queue_start  Start address of queue area
  56   * @param queue_size   Size in words (words are sizeof VCOS_UNSIGNED) of queue
  57   *
  58   */
  59
  60 VCOS_INLINE_DECL
  61 VCOS_STATUS_T vcos_queue_create(VCOS_QUEUE_T *queue,
  62                                 const char *name,
  63                                 VCOS_UNSIGNED message_size,
  64                                 void *queue_start,
  65                                 VCOS_UNSIGNED queue_size);
  66
  67 /** Delete a queue.
  68   * @param queue The queue to delete
  69   */
  70 VCOS_INLINE_DECL
  71 void vcos_queue_delete(VCOS_QUEUE_T *queue);
  72
  73 /** Send an item to a queue. If there is no space, the call with
  74   * either block waiting for space, or return an error, depending
  75   * on the value of the wait parameter.
  76   *
  77   * @param queue The queue to send to
  78   * @param src   The data to send (length set when queue was created)
  79   * @param wait  Whether to wait for space (VCOS_SUSPEND) or fail if
  80   *              no space (VCOS_NO_SUSPEND).
  81   *
  82   * @return If space available, returns VCOS_SUCCESS. Otherwise returns
  83   * VCOS_EAGAIN if no space available before timeout expires.
  84   *
  85   */
  86 VCOS_INLINE_DECL
  87 VCOS_STATUS_T vcos_queue_send(VCOS_QUEUE_T *queue, const void *src, VCOS_UNSIGNED wait);
  88
  89 /** Receive an item from a queue.
  90   * @param queue The queue to receive from
  91   * @param dst   Where to write the data to
  92   * @param wait  Whether to wait (VCOS_SUSPEND) or fail if
  93   *              empty (VCOS_NO_SUSPEND).
  94   *
  95   * @return If an item is available, returns VCOS_SUCCESS. Otherwise returns
  96   * VCOS_EAGAIN if no item available before timeout expires.
  97   */
  98 VCOS_INLINE_DECL
  99 VCOS_STATUS_T vcos_queue_receive(VCOS_QUEUE_T *queue, void *dst, VCOS_UNSIGNED wait);
 100
 101 #ifdef __cplusplus
 102 }
 103 #endif
 104 #endif
 105