begriffs open source - freertos/blob - include/atomic.h

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