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

   1 /*\r
   2  * FreeRTOS Kernel V10.2.1\r
   3  * Copyright (C) 2019 Amazon.com, Inc. or its affiliates.  All Rights Reserved.\r
   4  *\r
   5  * Permission is hereby granted, free of charge, to any person obtaining a copy of\r
   6  * this software and associated documentation files (the "Software"), to deal in\r
   7  * the Software without restriction, including without limitation the rights to\r
   8  * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of\r
   9  * the Software, and to permit persons to whom the Software is furnished to do so,\r
  10  * subject to the following conditions:\r
  11  *\r
  12  * The above copyright notice and this permission notice shall be included in all\r
  13  * copies or substantial portions of the Software.\r
  14  *\r
  15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\r
  16  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS\r
  17  * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR\r
  18  * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER\r
  19  * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\r
  20  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\r
  21  *\r
  22  * http://www.FreeRTOS.org\r
  23  * http://aws.amazon.com/freertos\r
  24  *\r
  25  * 1 tab == 4 spaces!\r
  26  */\r
  27 \r
  28 /**\r
  29  * @file atomic.h\r
  30  * @brief FreeRTOS atomic operation support.\r
  31  *\r
  32  * This file implements atomic by disabling interrupts globally. \r
  33  * Implementation with architecture specific atomic instructions  \r
  34  * are to be provided under each compiler directory. \r
  35  */\r
  36 \r
  37 #ifndef ATOMIC_H\r
  38 #define ATOMIC_H\r
  39 \r
  40 #ifndef INC_FREERTOS_H\r
  41     #error "include FreeRTOS.h must appear in source files before include atomic.h"\r
  42 #endif\r
  43 \r
  44 /* Standard includes. */\r
  45 #include <stdint.h>\r
  46 \r
  47 #ifdef __cplusplus\r
  48 extern "C" {\r
  49 #endif\r
  50 \r
  51 /* Port specific definitions -- entering/exiting critical section.\r
  52  * Refer template -- ./lib/FreeRTOS/portable/Compiler/Arch/portmacro.h\r
  53  *\r
  54  * Every call to ATOMIC_EXIT_CRITICAL() must be closely paired with\r
  55  * ATOMIC_ENTER_CRITICAL().\r
  56  *  */\r
  57 #if defined( portSET_INTERRUPT_MASK_FROM_ISR )\r
  58 \r
  59     /* Nested interrupt scheme is supported in this port. */\r
  60     #define ATOMIC_ENTER_CRITICAL()     \\r
  61         UBaseType_t uxCriticalSectionType = portSET_INTERRUPT_MASK_FROM_ISR()\r
  62 \r
  63     #define ATOMIC_EXIT_CRITICAL()      \\r
  64         portCLEAR_INTERRUPT_MASK_FROM_ISR( uxCriticalSectionType )\r
  65 \r
  66 #else\r
  67 \r
  68     /* Nested interrupt scheme is NOT supported in this port. */\r
  69     #define ATOMIC_ENTER_CRITICAL()     portENTER_CRITICAL()\r
  70     #define ATOMIC_EXIT_CRITICAL()      portEXIT_CRITICAL()\r
  71 \r
  72 #endif /* portSET_INTERRUPT_MASK_FROM_ISR() */\r
  73 \r
  74 /* Port specific definition -- "always inline". \r
  75  * Inline is compiler specific, and may not always get inlined depending on your optimization level. \r
  76  * Also, inline is considerred as performance optimization for atomic. \r
  77  * Thus, if portFORCE_INLINE is not provided by portmacro.h, instead of resulting error,\r
  78  * simply define it. \r
  79  */\r
  80 #ifndef portFORCE_INLINE\r
  81     #define portFORCE_INLINE \r
  82 #endif\r
  83 \r
  84 #define ATOMIC_COMPARE_AND_SWAP_SUCCESS     0x1U        /**< Compare and swap succeeded, swapped. */\r
  85 #define ATOMIC_COMPARE_AND_SWAP_FAILURE     0x0U        /**< Compare and swap failed, did not swap. */\r
  86 \r
  87 /*----------------------------- Swap && CAS ------------------------------*/\r
  88 \r
  89 /**\r
  90  * Atomic compare-and-swap\r
  91  *\r
  92  * @brief Performs an atomic compare-and-swap operation on the specified values.\r
  93  *\r
  94  * @param[in, out] pDestination  Pointer to memory location from where value is\r
  95  *                               to be loaded and checked.\r
  96  * @param[in] ulExchange         If condition meets, write this value to memory.\r
  97  * @param[in] ulComparand        Swap condition.\r
  98  *\r
  99  * @return Unsigned integer of value 1 or 0. 1 for swapped, 0 for not swapped.\r
 100  *\r
 101  * @note This function only swaps *pDestination with ulExchange, if previous\r
 102  *       *pDestination value equals ulComparand.\r
 103  */\r
 104 static portFORCE_INLINE uint32_t Atomic_CompareAndSwap_u32(\r
 105         uint32_t volatile * pDestination,\r
 106         uint32_t ulExchange,\r
 107         uint32_t ulComparand )\r
 108 {\r
 109 \r
 110     uint32_t ulReturnValue = ATOMIC_COMPARE_AND_SWAP_FAILURE;\r
 111 \r
 112     ATOMIC_ENTER_CRITICAL();\r
 113 \r
 114     if ( *pDestination == ulComparand )\r
 115     {\r
 116         *pDestination = ulExchange;\r
 117         ulReturnValue = ATOMIC_COMPARE_AND_SWAP_SUCCESS;\r
 118     }\r
 119 \r
 120     ATOMIC_EXIT_CRITICAL();\r
 121 \r
 122     return ulReturnValue;\r
 123 \r
 124 }\r
 125 \r
 126 /**\r
 127  * Atomic swap (pointers)\r
 128  *\r
 129  * @brief Atomically sets the address pointed to by *ppDestination to the value\r
 130  *        of *pExchange.\r
 131  *\r
 132  * @param[in, out] ppDestination  Pointer to memory location from where a pointer\r
 133  *                                value is to be loaded and written back to.\r
 134  * @param[in] pExchange           Pointer value to be written to *ppDestination.\r
 135  *\r
 136  * @return The initial value of *ppDestination.\r
 137  */\r
 138 static portFORCE_INLINE void * Atomic_SwapPointers_p32(\r
 139         void * volatile * ppDestination,\r
 140         void * pExchange )\r
 141 {\r
 142     void * pReturnValue;\r
 143 \r
 144     ATOMIC_ENTER_CRITICAL();\r
 145 \r
 146     pReturnValue = *ppDestination;\r
 147 \r
 148     *ppDestination = pExchange;\r
 149 \r
 150     ATOMIC_EXIT_CRITICAL();\r
 151 \r
 152     return pReturnValue;\r
 153 }\r
 154 \r
 155 /**\r
 156  * Atomic compare-and-swap (pointers)\r
 157  *\r
 158  * @brief Performs an atomic compare-and-swap operation on the specified pointer\r
 159  *        values.\r
 160  *\r
 161  * @param[in, out] ppDestination  Pointer to memory location from where a pointer\r
 162  *                                value is to be loaded and checked.\r
 163  * @param[in] pExchange           If condition meets, write this value to memory.\r
 164  * @param[in] pComparand          Swap condition.\r
 165  *\r
 166  * @return Unsigned integer of value 1 or 0. 1 for swapped, 0 for not swapped.\r
 167  *\r
 168  * @note This function only swaps *ppDestination with pExchange, if previous\r
 169  *       *ppDestination value equals pComparand.\r
 170  */\r
 171 static portFORCE_INLINE uint32_t Atomic_CompareAndSwapPointers_p32(\r
 172         void * volatile * ppDestination,\r
 173         void * pExchange, void * pComparand )\r
 174 {\r
 175     uint32_t ulReturnValue = ATOMIC_COMPARE_AND_SWAP_FAILURE;\r
 176 \r
 177     ATOMIC_ENTER_CRITICAL();\r
 178 \r
 179     if ( *ppDestination == pComparand )\r
 180     {\r
 181         *ppDestination = pExchange;\r
 182         ulReturnValue = ATOMIC_COMPARE_AND_SWAP_SUCCESS;\r
 183     }\r
 184 \r
 185     ATOMIC_EXIT_CRITICAL();\r
 186 \r
 187     return ulReturnValue;\r
 188 }\r
 189 \r
 190 \r
 191 /*----------------------------- Arithmetic ------------------------------*/\r
 192 \r
 193 /**\r
 194  * Atomic add\r
 195  *\r
 196  * @brief Atomically adds count to the value of the specified pointer points to.\r
 197  *\r
 198  * @param[in,out] pAddend  Pointer to memory location from where value is to be\r
 199  *                         loaded and written back to.\r
 200  * @param[in] ulCount      Value to be added to *pAddend.\r
 201  *\r
 202  * @return previous *pAddend value.\r
 203  */\r
 204 static portFORCE_INLINE uint32_t Atomic_Add_u32(\r
 205         uint32_t volatile * pAddend,\r
 206         uint32_t ulCount )\r
 207 {\r
 208     uint32_t ulCurrent;\r
 209 \r
 210     ATOMIC_ENTER_CRITICAL();\r
 211 \r
 212     ulCurrent = *pAddend;\r
 213 \r
 214     *pAddend += ulCount;\r
 215 \r
 216     ATOMIC_EXIT_CRITICAL();\r
 217 \r
 218     return ulCurrent;\r
 219 }\r
 220 \r
 221 /**\r
 222  * Atomic subtract\r
 223  *\r
 224  * @brief Atomically subtracts count from the value of the specified pointer\r
 225  *        pointers to.\r
 226  *\r
 227  * @param[in,out] pAddend  Pointer to memory location from where value is to be\r
 228  *                         loaded and written back to.\r
 229  * @param[in] ulCount      Value to be subtract from *pAddend.\r
 230  *\r
 231  * @return previous *pAddend value.\r
 232  */\r
 233 static portFORCE_INLINE uint32_t Atomic_Subtract_u32(\r
 234         uint32_t volatile * pAddend,\r
 235         uint32_t ulCount )\r
 236 {\r
 237     uint32_t ulCurrent;\r
 238 \r
 239     ATOMIC_ENTER_CRITICAL();\r
 240 \r
 241     ulCurrent = *pAddend;\r
 242 \r
 243     *pAddend -= ulCount;\r
 244 \r
 245     ATOMIC_EXIT_CRITICAL();\r
 246 \r
 247     return ulCurrent;\r
 248 }\r
 249 \r
 250 /**\r
 251  * Atomic increment\r
 252  *\r
 253  * @brief Atomically increments the value of the specified pointer points to.\r
 254  *\r
 255  * @param[in,out] pAddend  Pointer to memory location from where value is to be\r
 256  *                         loaded and written back to.\r
 257  *\r
 258  * @return *pAddend value before increment.\r
 259  */\r
 260 static portFORCE_INLINE uint32_t Atomic_Increment_u32( uint32_t volatile * pAddend )\r
 261 {\r
 262     uint32_t ulCurrent;\r
 263 \r
 264     ATOMIC_ENTER_CRITICAL();\r
 265 \r
 266     ulCurrent = *pAddend;\r
 267 \r
 268     *pAddend += 1;\r
 269 \r
 270     ATOMIC_EXIT_CRITICAL();\r
 271 \r
 272     return ulCurrent;\r
 273 }\r
 274 \r
 275 /**\r
 276  * Atomic decrement\r
 277  *\r
 278  * @brief Atomically decrements the value of the specified pointer points to\r
 279  *\r
 280  * @param[in,out] pAddend  Pointer to memory location from where value is to be\r
 281  *                         loaded and written back to.\r
 282  *\r
 283  * @return *pAddend value before decrement.\r
 284  */\r
 285 static portFORCE_INLINE uint32_t Atomic_Decrement_u32( uint32_t volatile * pAddend )\r
 286 {\r
 287     uint32_t ulCurrent;\r
 288 \r
 289     ATOMIC_ENTER_CRITICAL();\r
 290 \r
 291     ulCurrent = *pAddend;\r
 292 \r
 293     *pAddend -= 1;\r
 294 \r
 295     ATOMIC_EXIT_CRITICAL();\r
 296 \r
 297     return ulCurrent;\r
 298 }\r
 299 \r
 300 /*----------------------------- Bitwise Logical ------------------------------*/\r
 301 \r
 302 /**\r
 303  * Atomic OR\r
 304  *\r
 305  * @brief Performs an atomic OR operation on the specified values.\r
 306  *\r
 307  * @param [in, out] pDestination  Pointer to memory location from where value is\r
 308  *                                to be loaded and written back to.\r
 309  * @param [in] ulValue            Value to be ORed with *pDestination.\r
 310  *\r
 311  * @return The original value of *pDestination.\r
 312  */\r
 313 static portFORCE_INLINE uint32_t Atomic_OR_u32(\r
 314         uint32_t volatile * pDestination,\r
 315         uint32_t ulValue )\r
 316 {\r
 317     uint32_t ulCurrent;\r
 318 \r
 319     ATOMIC_ENTER_CRITICAL();\r
 320 \r
 321     ulCurrent = *pDestination;\r
 322 \r
 323     *pDestination |= ulValue;\r
 324 \r
 325     ATOMIC_EXIT_CRITICAL();\r
 326 \r
 327     return ulCurrent;\r
 328 }\r
 329 \r
 330 /**\r
 331  * Atomic AND\r
 332  *\r
 333  * @brief Performs an atomic AND operation on the specified values.\r
 334  *\r
 335  * @param [in, out] pDestination  Pointer to memory location from where value is\r
 336  *                                to be loaded and written back to.\r
 337  * @param [in] ulValue            Value to be ANDed with *pDestination.\r
 338  *\r
 339  * @return The original value of *pDestination.\r
 340  */\r
 341 static portFORCE_INLINE uint32_t Atomic_AND_u32(\r
 342         uint32_t volatile * pDestination,\r
 343         uint32_t ulValue )\r
 344 {\r
 345     uint32_t ulCurrent;\r
 346 \r
 347     ATOMIC_ENTER_CRITICAL();\r
 348 \r
 349     ulCurrent = *pDestination;\r
 350 \r
 351     *pDestination &= ulValue;\r
 352 \r
 353     ATOMIC_EXIT_CRITICAL();\r
 354 \r
 355     return ulCurrent;\r
 356 }\r
 357 \r
 358 /**\r
 359  * Atomic NAND\r
 360  *\r
 361  * @brief Performs an atomic NAND operation on the specified values.\r
 362  *\r
 363  * @param [in, out] pDestination  Pointer to memory location from where value is\r
 364  *                                to be loaded and written back to.\r
 365  * @param [in] ulValue            Value to be NANDed with *pDestination.\r
 366  *\r
 367  * @return The original value of *pDestination.\r
 368  */\r
 369 static portFORCE_INLINE uint32_t Atomic_NAND_u32(\r
 370         uint32_t volatile * pDestination,\r
 371         uint32_t ulValue )\r
 372 {\r
 373     uint32_t ulCurrent;\r
 374 \r
 375     ATOMIC_ENTER_CRITICAL();\r
 376 \r
 377     ulCurrent = *pDestination;\r
 378 \r
 379     *pDestination = ~(ulCurrent & ulValue);\r
 380 \r
 381     ATOMIC_EXIT_CRITICAL();\r
 382 \r
 383     return ulCurrent;\r
 384 }\r
 385 \r
 386 /**\r
 387  * Atomic XOR\r
 388  *\r
 389  * @brief Performs an atomic XOR operation on the specified values.\r
 390  *\r
 391  * @param [in, out] pDestination  Pointer to memory location from where value is\r
 392  *                                to be loaded and written back to.\r
 393  * @param [in] ulValue            Value to be XORed with *pDestination.\r
 394  *\r
 395  * @return The original value of *pDestination.\r
 396  */\r
 397 static portFORCE_INLINE uint32_t Atomic_XOR_u32(\r
 398         uint32_t volatile * pDestination,\r
 399         uint32_t ulValue )\r
 400 {\r
 401     uint32_t ulCurrent;\r
 402 \r
 403     ATOMIC_ENTER_CRITICAL();\r
 404 \r
 405     ulCurrent = *pDestination;\r
 406 \r
 407     *pDestination ^= ulValue;\r
 408 \r
 409     ATOMIC_EXIT_CRITICAL();\r
 410 \r
 411     return ulCurrent;\r
 412 }\r
 413 \r
 414 #ifdef __cplusplus\r
 415 }\r
 416 #endif\r
 417 \r
 418 #endif /* ATOMIC_H */\r