git.sur5r.net Git - freertos/blob - Source/include/semphr.h

   1 /*\r
   2         FreeRTOS.org V4.4.0 - Copyright (C) 2003-2007 Richard Barry.\r
   3 \r
   4         This file is part of the FreeRTOS.org distribution.\r
   5 \r
   6         FreeRTOS.org is free software; you can redistribute it and/or modify\r
   7         it under the terms of the GNU General Public License as published by\r
   8         the Free Software Foundation; either version 2 of the License, or\r
   9         (at your option) any later version.\r
  10 \r
  11         FreeRTOS.org is distributed in the hope that it will be useful,\r
  12         but WITHOUT ANY WARRANTY; without even the implied warranty of\r
  13         MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\r
  14         GNU General Public License for more details.\r
  15 \r
  16         You should have received a copy of the GNU General Public License\r
  17         along with FreeRTOS.org; if not, write to the Free Software\r
  18         Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA\r
  19 \r
  20         A special exception to the GPL can be applied should you wish to distribute\r
  21         a combined work that includes FreeRTOS.org, without being obliged to provide\r
  22         the source code for any proprietary components.  See the licensing section \r
  23         of http://www.FreeRTOS.org for full details of how and when the exception\r
  24         can be applied.\r
  25 \r
  26         ***************************************************************************\r
  27         See http://www.FreeRTOS.org for documentation, latest information, license \r
  28         and contact details.  Please ensure to read the configuration and relevant \r
  29         port sections of the online documentation.\r
  30 \r
  31         Also see http://www.SafeRTOS.com for an IEC 61508 compliant version along\r
  32         with commercial development and support options.\r
  33         ***************************************************************************\r
  34 */\r
  35 \r
  36 #include "queue.h"\r
  37 \r
  38 #ifndef SEMAPHORE_H\r
  39 #define SEMAPHORE_H\r
  40 \r
  41 typedef xQueueHandle xSemaphoreHandle;\r
  42 \r
  43 #define semBINARY_SEMAPHORE_QUEUE_LENGTH        ( ( unsigned portCHAR ) 1 )\r
  44 #define semSEMAPHORE_QUEUE_ITEM_LENGTH          ( ( unsigned portCHAR ) 0 )\r
  45 #define semGIVE_BLOCK_TIME                                      ( ( portTickType ) 0 )\r
  46 \r
  47 \r
  48 /**\r
  49  * semphr. h\r
  50  * <pre>vSemaphoreCreateBinary( xSemaphoreHandle xSemaphore )</pre>\r
  51  *\r
  52  * <i>Macro</i> that implements a semaphore by using the existing queue mechanism.\r
  53  * The queue length is 1 as this is a binary semaphore.  The data size is 0\r
  54  * as we don't want to actually store any data - we just want to know if the\r
  55  * queue is empty or full.\r
  56  *\r
  57  * This type of semaphore can be used for pure synchronisation between tasks or\r
  58  * between an interrupt and a task.  The semaphore need not be given back once\r
  59  * obtained, so one task/interrupt can continuously 'give' the semaphore while\r
  60  * another continuously 'takes' the semaphore.  For this reason this type of\r
  61  * semaphore does not use a priority inheritance mechanism.  For an alternative\r
  62  * that does use priority inheritance see xSemaphoreCreateMutex().\r
  63  *\r
  64  * @param xSemaphore Handle to the created semaphore.  Should be of type xSemaphoreHandle.\r
  65  *\r
  66  * Example usage:\r
  67  <pre>\r
  68  xSemaphoreHandle xSemaphore;\r
  69 \r
  70  void vATask( void * pvParameters )\r
  71  {\r
  72     // Semaphore cannot be used before a call to vSemaphoreCreateBinary ().\r
  73     // This is a macro so pass the variable in directly.\r
  74     vSemaphoreCreateBinary( xSemaphore );\r
  75 \r
  76     if( xSemaphore != NULL )\r
  77     {\r
  78         // The semaphore was created successfully.\r
  79         // The semaphore can now be used.  \r
  80     }\r
  81  }\r
  82  </pre>\r
  83  * \defgroup vSemaphoreCreateBinary vSemaphoreCreateBinary\r
  84  * \ingroup Semaphores\r
  85  */\r
  86 #define vSemaphoreCreateBinary( xSemaphore )            {                                                                                                                                                                                       \\r
  87                                                                                                                 xSemaphore = xQueueCreate( ( unsigned portCHAR ) 1, semSEMAPHORE_QUEUE_ITEM_LENGTH );   \\r
  88                                                                                                                 if( xSemaphore != NULL )                                                                                                                                \\r
  89                                                                                                                 {                                                                                                                                                                               \\r
  90                                                                                                                         xSemaphoreGive( xSemaphore );                                                                                                           \\r
  91                                                                                                                 }                                                                                                                                                                               \\r
  92                                                                                                         }\r
  93 \r
  94 /**\r
  95  * semphr. h\r
  96  * xSemaphoreTake( \r
  97  *                   xSemaphoreHandle xSemaphore, \r
  98  *                   portTickType xBlockTime \r
  99  *               )</pre>\r
 100  *\r
 101  * <i>Macro</i> to obtain a semaphore.  The semaphore must of been created using \r
 102  * vSemaphoreCreateBinary ().\r
 103  *\r
 104  * @param xSemaphore A handle to the semaphore being obtained.  This is the\r
 105  * handle returned by vSemaphoreCreateBinary ();\r
 106  *\r
 107  * @param xBlockTime The time in ticks to wait for the semaphore to become\r
 108  * available.  The macro portTICK_RATE_MS can be used to convert this to a\r
 109  * real time.  A block time of zero can be used to poll the semaphore.\r
 110  *\r
 111  * @return pdTRUE if the semaphore was obtained.  pdFALSE if xBlockTime\r
 112  * expired without the semaphore becoming available.\r
 113  *\r
 114  * Example usage:\r
 115  <pre>\r
 116  xSemaphoreHandle xSemaphore = NULL;\r
 117 \r
 118  // A task that creates a semaphore.\r
 119  void vATask( void * pvParameters )\r
 120  {\r
 121     // Create the semaphore to guard a shared resource.\r
 122     vSemaphoreCreateBinary( xSemaphore );\r
 123  }\r
 124 \r
 125  // A task that uses the semaphore.\r
 126  void vAnotherTask( void * pvParameters )\r
 127  {\r
 128     // ... Do other things.\r
 129 \r
 130     if( xSemaphore != NULL )\r
 131     {\r
 132         // See if we can obtain the semaphore.  If the semaphore is not available\r
 133         // wait 10 ticks to see if it becomes free.     \r
 134         if( xSemaphoreTake( xSemaphore, ( portTickType ) 10 ) == pdTRUE )\r
 135         {\r
 136             // We were able to obtain the semaphore and can now access the\r
 137             // shared resource.\r
 138 \r
 139             // ...\r
 140 \r
 141             // We have finished accessing the shared resource.  Release the \r
 142             // semaphore.\r
 143             xSemaphoreGive( xSemaphore );\r
 144         }\r
 145         else\r
 146         {\r
 147             // We could not obtain the semaphore and can therefore not access\r
 148             // the shared resource safely.\r
 149         }\r
 150     }\r
 151  }\r
 152  </pre>\r
 153  * \defgroup xSemaphoreTake xSemaphoreTake\r
 154  * \ingroup Semaphores\r
 155  */\r
 156 #define xSemaphoreTake( xSemaphore, xBlockTime )        xQueueReceive( ( xQueueHandle ) xSemaphore, NULL, xBlockTime )\r
 157 \r
 158 /**\r
 159  * semphr. h\r
 160  * <pre>xSemaphoreGive( xSemaphoreHandle xSemaphore )</pre>\r
 161  *\r
 162  * <i>Macro</i> to release a semaphore.  The semaphore must of been created using \r
 163  * vSemaphoreCreateBinary (), and obtained using sSemaphoreTake ().\r
 164  *\r
 165  * This must not be used from an ISR.  See xSemaphoreGiveFromISR () for\r
 166  * an alternative which can be used from an ISR.\r
 167  *\r
 168  * @param xSemaphore A handle to the semaphore being released.  This is the\r
 169  * handle returned by vSemaphoreCreateBinary ();\r
 170  *\r
 171  * @return pdTRUE if the semaphore was released.  pdFALSE if an error occurred.\r
 172  * Semaphores are implemented using queues.  An error can occur if there is\r
 173  * no space on the queue to post a message - indicating that the \r
 174  * semaphore was not first obtained correctly.\r
 175  *\r
 176  * Example usage:\r
 177  <pre>\r
 178  xSemaphoreHandle xSemaphore = NULL;\r
 179 \r
 180  void vATask( void * pvParameters )\r
 181  {\r
 182     // Create the semaphore to guard a shared resource.\r
 183     vSemaphoreCreateBinary( xSemaphore );\r
 184 \r
 185     if( xSemaphore != NULL )\r
 186     {\r
 187         if( xSemaphoreGive( xSemaphore ) != pdTRUE )\r
 188         {\r
 189             // We would expect this call to fail because we cannot give\r
 190             // a semaphore without first "taking" it!\r
 191         }\r
 192 \r
 193         // Obtain the semaphore - don't block if the semaphore is not\r
 194         // immediately available.\r
 195         if( xSemaphoreTake( xSemaphore, ( portTickType ) 0 ) )\r
 196         {\r
 197             // We now have the semaphore and can access the shared resource.\r
 198 \r
 199             // ...\r
 200 \r
 201             // We have finished accessing the shared resource so can free the\r
 202             // semaphore.\r
 203             if( xSemaphoreGive( xSemaphore ) != pdTRUE )\r
 204             {\r
 205                 // We would not expect this call to fail because we must have\r
 206                 // obtained the semaphore to get here.\r
 207             }\r
 208         }\r
 209     }\r
 210  }\r
 211  </pre>\r
 212  * \defgroup xSemaphoreGive xSemaphoreGive\r
 213  * \ingroup Semaphores\r
 214  */\r
 215 #define xSemaphoreGive( xSemaphore )                            xQueueGenericSend( ( xQueueHandle ) xSemaphore, NULL, semGIVE_BLOCK_TIME, queueSEND_TO_BACK )\r
 216 \r
 217 /**\r
 218  * semphr. h\r
 219  * <pre>\r
 220  xSemaphoreGiveFromISR( \r
 221                           xSemaphoreHandle xSemaphore, \r
 222                           portSHORT sTaskPreviouslyWoken \r
 223                       )</pre>\r
 224  *\r
 225  * <i>Macro</i> to  release a semaphore.  The semaphore must of been created using \r
 226  * vSemaphoreCreateBinary (), and obtained using xSemaphoreTake ().\r
 227  *\r
 228  * Mutex type semaphores (those created using a call to xSemaphoreCreateMutex())\r
 229  * must not be used with this macro.\r
 230  *\r
 231  * This macro can be used from an ISR.\r
 232  *\r
 233  * @param xSemaphore A handle to the semaphore being released.  This is the\r
 234  * handle returned by vSemaphoreCreateBinary ();\r
 235  *\r
 236  * @param sTaskPreviouslyWoken This is included so an ISR can make multiple calls\r
 237  * to xSemaphoreGiveFromISR () from a single interrupt.  The first call\r
 238  * should always pass in pdFALSE.  Subsequent calls should pass in\r
 239  * the value returned from the previous call.  See the file serial .c in the\r
 240  * PC port for a good example of using xSemaphoreGiveFromISR ().\r
 241  *\r
 242  * @return pdTRUE if a task was woken by releasing the semaphore.  This is \r
 243  * used by the ISR to determine if a context switch may be required following\r
 244  * the ISR.\r
 245  *\r
 246  * Example usage:\r
 247  <pre>\r
 248  #define LONG_TIME 0xffff\r
 249  #define TICKS_TO_WAIT  10\r
 250  xSemaphoreHandle xSemaphore = NULL;\r
 251 \r
 252  // Repetitive task.\r
 253  void vATask( void * pvParameters )\r
 254  {\r
 255     for( ;; )\r
 256     {\r
 257         // We want this task to run every 10 ticks or a timer.  The semaphore \r
 258         // was created before this task was started\r
 259 \r
 260         // Block waiting for the semaphore to become available.\r
 261         if( xSemaphoreTake( xSemaphore, LONG_TIME ) == pdTRUE )\r
 262         {\r
 263             // It is time to execute.\r
 264 \r
 265             // ...\r
 266 \r
 267             // We have finished our task.  Return to the top of the loop where\r
 268             // we will block on the semaphore until it is time to execute \r
 269             // again.\r
 270         }\r
 271     }\r
 272  }\r
 273 \r
 274  // Timer ISR\r
 275  void vTimerISR( void * pvParameters )\r
 276  {\r
 277  static unsigned portCHAR ucLocalTickCount = 0;\r
 278 \r
 279     // A timer tick has occurred.\r
 280 \r
 281     // ... Do other time functions.\r
 282 \r
 283     // Is it time for vATask () to run?\r
 284     ucLocalTickCount++;\r
 285     if( ucLocalTickCount >= TICKS_TO_WAIT )\r
 286     {\r
 287         // Unblock the task by releasing the semaphore.\r
 288         xSemaphoreGive( xSemaphore );\r
 289 \r
 290         // Reset the count so we release the semaphore again in 10 ticks time.\r
 291         ucLocalTickCount = 0;\r
 292     }\r
 293  }\r
 294  </pre>\r
 295  * \defgroup xSemaphoreGiveFromISR xSemaphoreGiveFromISR\r
 296  * \ingroup Semaphores\r
 297  */\r
 298 #define xSemaphoreGiveFromISR( xSemaphore, xTaskPreviouslyWoken )                       xQueueGenericSendFromISR( ( xQueueHandle ) xSemaphore, NULL, xTaskPreviouslyWoken, queueSEND_TO_BACK )\r
 299 \r
 300 /**\r
 301  * semphr. h\r
 302  * <pre>xSemaphoreCreateMutex( xSemaphoreHandle xSemaphore )</pre>\r
 303  *\r
 304  * <i>Macro</i> that implements a mutex semaphore by using the existing queue \r
 305  * mechanism.\r
 306  *\r
 307  * This type of semaphore uses a priority inheritance mechanism so a task \r
 308  * 'taking' a semaphore MUST ALWAYS 'give' the semaphore back once the \r
 309  * semaphore it is no longer required.  \r
 310  *\r
 311  * Mutex type semaphores cannot be used from within interrupt service routines.  \r
 312  *\r
 313  * See xSemaphoreCreateBinary() for an alternative implemnetation that can be \r
 314  * used for pure synchronisation (where one task or interrupt always 'gives' the \r
 315  * semaphore and another always 'takes' the semaphore) and from within interrupt \r
 316  * service routines.\r
 317  *\r
 318  * @param xSemaphore Handle to the created mutex semaphore.  Should be of type \r
 319  *              xSemaphoreHandle.\r
 320  *\r
 321  * Example usage:\r
 322  <pre>\r
 323  xSemaphoreHandle xSemaphore;\r
 324 \r
 325  void vATask( void * pvParameters )\r
 326  {\r
 327     // Semaphore cannot be used before a call to vSemaphoreCreateBinary ().\r
 328     // This is a macro so pass the variable in directly.\r
 329     vSemaphoreCreateMutex( xSemaphore );\r
 330 \r
 331     if( xSemaphore != NULL )\r
 332     {\r
 333         // The semaphore was created successfully.\r
 334         // The semaphore can now be used.  \r
 335     }\r
 336  }\r
 337  </pre>\r
 338  * \defgroup vSemaphoreCreateMutex vSemaphoreCreateMutex\r
 339  * \ingroup Semaphores\r
 340  */\r
 341 #define xSemaphoreCreateMutex() xQueueCreateMutex()\r
 342 \r
 343 \r
 344 #endif /* SEMAPHORE_H */\r
 345 \r
 346 \r