granicus.if.org Git - esp-idf/blob - components/esp32/include/xtensa/xos_semaphore.h

   1 /** @file */
   2
   3 // xos_semaphore.h - XOS Semaphore API interface and data structures.
   4
   5 // Copyright (c) 2003-2015 Cadence Design Systems, Inc.
   6 //
   7 // Permission is hereby granted, free of charge, to any person obtaining
   8 // a copy of this software and associated documentation files (the
   9 // "Software"), to deal in the Software without restriction, including
  10 // without limitation the rights to use, copy, modify, merge, publish,
  11 // distribute, sublicense, and/or sell copies of the Software, and to
  12 // permit persons to whom the Software is furnished to do so, subject to
  13 // the following conditions:
  14 //
  15 // The above copyright notice and this permission notice shall be included
  16 // in all copies or substantial portions of the Software.
  17 //
  18 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  19 // EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  20 // MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
  21 // IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
  22 // CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
  23 // TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
  24 // SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  25
  26 // NOTE: Do not include this file directly in your application. Including
  27 // xos.h will automatically include this file.
  28
  29 #ifndef __XOS_SEMAPHORE_H__
  30 #define __XOS_SEMAPHORE_H__
  31
  32 #include "xos_types.h"
  33
  34 #ifdef __cplusplus
  35 extern "C" {
  36 #endif
  37
  38
  39 //-----------------------------------------------------------------------------
  40 // Semaphore flags.
  41 //-----------------------------------------------------------------------------
  42 #define XOS_SEM_WAIT_PRIORITY     0x0000  ///< Wake waiters in priority order (default)
  43 #define XOS_SEM_WAIT_FIFO         0x0001  ///< Wake waiters in FIFO order
  44 #define XOS_SEM_PRIORITY_INV      0x0004  // Protect against priority inversion
  45
  46
  47 //-----------------------------------------------------------------------------
  48 ///
  49 /// XosSem object.
  50 ///
  51 //-----------------------------------------------------------------------------
  52 typedef struct XosSem {
  53   uint32_t              count;          ///< Current count
  54   XosThreadQueue        waitq;          ///< Queue of waiters.
  55   uint32_t              flags;          ///< Properties.
  56 #if XOS_SEM_DEBUG
  57   uint32_t              sig;            // Valid signature indicates inited.
  58 #endif
  59 } XosSem;
  60
  61
  62 //-----------------------------------------------------------------------------
  63 ///
  64 ///  Initialize a semaphore object before first use.
  65 ///
  66 ///  \param     sem             Pointer to semaphore object.
  67 ///
  68 ///  \param     flags           Creation flags:
  69 ///                             - XOS_SEM_WAIT_FIFO -- queue waiting threads in
  70 ///                               fifo order.
  71 ///                             - XOS_SEM_WAIT_PRIORITY -- queue waiting threads
  72 ///                               by priority. This is the default.
  73 ///                             - XOS_SEM_PRIORITY_INV -- protect against priority
  74 ///                               inversion.
  75 ///
  76 ///  \param     initial_count   Initial count for semaphore on creation.
  77 ///
  78 ///  \return    Returns XOS_OK on success, else error code.
  79 ///
  80 ///  NOTE: XOS_SEM_PRIORITY_INV is NOT supported in the current release. It will
  81 ///  be supported in a future release.
  82 ///
  83 //-----------------------------------------------------------------------------
  84 int32_t
  85 xos_sem_create(XosSem * sem, uint32_t flags, uint32_t initial_count);
  86
  87
  88 //-----------------------------------------------------------------------------
  89 ///
  90 ///  Destroy a semaphore object. Must have been previously created by calling
  91 ///  xos_sem_create().
  92 ///
  93 ///  \param     sem             Pointer to semaphore object.
  94 ///
  95 ///  \return    Returns XOS_OK on success, else error code.
  96 ///
  97 //-----------------------------------------------------------------------------
  98 int32_t
  99 xos_sem_delete(XosSem * sem);
 100
 101
 102 //-----------------------------------------------------------------------------
 103 ///
 104 ///  Decrement the semaphore count: block until the decrement is possible.
 105 ///  The semaphore must have been initialized.
 106 ///
 107 ///  \param     sem             Pointer to semaphore object.
 108 ///
 109 ///  \return    Returns XOS_OK on success, else error code.
 110 ///
 111 //-----------------------------------------------------------------------------
 112 int32_t
 113 xos_sem_get(XosSem * sem);
 114
 115
 116 //-----------------------------------------------------------------------------
 117 ///
 118 ///  Decrement the semaphore count: block until the decrement is possible or
 119 ///  the timeout expires. The semaphore must have been initialized.
 120 ///
 121 ///  \param     sem             Pointer to semaphore object.
 122 ///
 123 ///  \param     to_cycles       Timeout in cycles. Convert from time to cycles
 124 ///                             using the helper functions provided in xos_timer.
 125 ///                             A value of zero indicates no timeout.
 126 ///
 127 ///  \return    Returns XOS_OK on success, XOS_ERR_TIMEOUT on timeout, else error code.
 128 ///
 129 ///  NOTE: If XOS_OPT_WAIT_TIMEOUT is not enabled, then the timeout value is
 130 ///  ignored, and no timeout will occur.
 131 ///
 132 //-----------------------------------------------------------------------------
 133 int32_t
 134 xos_sem_get_timeout(XosSem * sem, uint64_t to_cycles);
 135
 136
 137 //-----------------------------------------------------------------------------
 138 ///
 139 ///  Increment the semaphore count. The semaphore must have been initialized.
 140 ///  Remember that this action may wake up a waiting thread, and if that thread
 141 ///  is higher priority then there will be an immediate context switch.
 142 ///
 143 ///  \param     sem             Pointer to semaphore object.
 144 ///
 145 ///  \return    Returns XOS_OK on success, else error code.
 146 ///
 147 //-----------------------------------------------------------------------------
 148 int32_t
 149 xos_sem_put(XosSem * sem);
 150
 151
 152 //-----------------------------------------------------------------------------
 153 ///
 154 ///  Try to decrement the semaphore, but do not block if the semaphore count is
 155 ///  zero. Return immediately. The semaphore must have been initialized.
 156 ///
 157 ///  \param     sem             Pointer to semaphore object.
 158 ///
 159 ///  \return    Returns XOS_OK on success (semaphore decremented), else error code.
 160 ///
 161 //-----------------------------------------------------------------------------
 162 int32_t
 163 xos_sem_tryget(XosSem * sem);
 164
 165
 166 //-----------------------------------------------------------------------------
 167 ///
 168 ///  Return the count of the semaphore but do not attempt to decrement it.
 169 ///  The semaphore must have been initialized.
 170 ///
 171 ///  \param     sem             Pointer to semaphore object.
 172 ///
 173 ///  \return    Returns semaphore count, -1 on error.
 174 ///
 175 //-----------------------------------------------------------------------------
 176 static inline int32_t
 177 xos_sem_test(XosSem * sem)
 178 {
 179     XOS_ASSERT(sem);
 180
 181     return sem ? sem->count : -1;
 182 }
 183
 184
 185 #ifdef __cplusplus
 186 }
 187 #endif
 188
 189 #endif  //      __XOS_SEMAPHORE_H__
 190