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  * The atomic interface can be used in FreeRTOS tasks on all FreeRTOS ports. It
  38  * can also be used in Interrupt Service Routines (ISRs) on FreeRTOS ports that
  39  * support nested interrupts (i.e. portHAS_NESTED_INTERRUPTS is set to 1). The
  40  * atomic interface must not be used in ISRs on FreeRTOS ports that do not
  41  * support nested interrupts (i.e. portHAS_NESTED_INTERRUPTS is set to 0)
  42  * because ISRs on these ports cannot be interrupted and therefore, do not need
  43  * atomics in ISRs.
  44  */
  45
  46 #ifndef ATOMIC_H
  47 #define ATOMIC_H
  48
  49 #ifndef INC_FREERTOS_H
  50     #error "include FreeRTOS.h must appear in source files before include atomic.h"
  51 #endif
  52
  53 /* Standard includes. */
  54 #include <stdint.h>
  55
  56 /* *INDENT-OFF* */
  57 #ifdef __cplusplus
  58     extern "C" {
  59 #endif
  60 /* *INDENT-ON* */
  61
  62 /*
  63  * Port specific definitions -- entering/exiting critical section.
  64  * Refer template -- ./lib/FreeRTOS/portable/Compiler/Arch/portmacro.h
  65  *
  66  * Every call to ATOMIC_EXIT_CRITICAL() must be closely paired with
  67  * ATOMIC_ENTER_CRITICAL().
  68  *
  69  */
  70 #if ( portHAS_NESTED_INTERRUPTS == 1 )
  71
  72 /* Nested interrupt scheme is supported in this port. */
  73     #define ATOMIC_ENTER_CRITICAL() \
  74     UBaseType_t uxCriticalSectionType = portSET_INTERRUPT_MASK_FROM_ISR()
  75
  76     #define ATOMIC_EXIT_CRITICAL() \
  77     portCLEAR_INTERRUPT_MASK_FROM_ISR( uxCriticalSectionType )
  78
  79 #else
  80
  81 /* Nested interrupt scheme is NOT supported in this port. */
  82     #define ATOMIC_ENTER_CRITICAL()    portENTER_CRITICAL()
  83     #define ATOMIC_EXIT_CRITICAL()     portEXIT_CRITICAL()
  84
  85 #endif /* portSET_INTERRUPT_MASK_FROM_ISR() */
  86
  87 /*
  88  * Port specific definition -- "always inline".
  89  * Inline is compiler specific, and may not always get inlined depending on your
  90  * optimization level.  Also, inline is considered as performance optimization
  91  * for atomic.  Thus, if portFORCE_INLINE is not provided by portmacro.h,
  92  * instead of resulting error, simply define it away.
  93  */
  94 #ifndef portFORCE_INLINE
  95     #define portFORCE_INLINE
  96 #endif
  97
  98 #define ATOMIC_COMPARE_AND_SWAP_SUCCESS    0x1U     /**< Compare and swap succeeded, swapped. */
  99 #define ATOMIC_COMPARE_AND_SWAP_FAILURE    0x0U     /**< Compare and swap failed, did not swap. */
 100
 101 /*----------------------------- Swap && CAS ------------------------------*/
 102
 103 /**
 104  * Atomic compare-and-swap
 105  *
 106  * @brief Performs an atomic compare-and-swap operation on the specified values.
 107  *
 108  * @param[in, out] pulDestination  Pointer to memory location from where value is
 109  *                               to be loaded and checked.
 110  * @param[in] ulExchange         If condition meets, write this value to memory.
 111  * @param[in] ulComparand        Swap condition.
 112  *
 113  * @return Unsigned integer of value 1 or 0. 1 for swapped, 0 for not swapped.
 114  *
 115  * @note This function only swaps *pulDestination with ulExchange, if previous
 116  *       *pulDestination value equals ulComparand.
 117  */
 118 static portFORCE_INLINE uint32_t Atomic_CompareAndSwap_u32( uint32_t volatile * pulDestination,
 119                                                             uint32_t ulExchange,
 120                                                             uint32_t ulComparand )
 121 {
 122     uint32_t ulReturnValue;
 123
 124     ATOMIC_ENTER_CRITICAL();
 125     {
 126         if( *pulDestination == ulComparand )
 127         {
 128             *pulDestination = ulExchange;
 129             ulReturnValue = ATOMIC_COMPARE_AND_SWAP_SUCCESS;
 130         }
 131         else
 132         {
 133             ulReturnValue = ATOMIC_COMPARE_AND_SWAP_FAILURE;
 134         }
 135     }
 136     ATOMIC_EXIT_CRITICAL();
 137
 138     return ulReturnValue;
 139 }
 140 /*-----------------------------------------------------------*/
 141
 142 /**
 143  * Atomic swap (pointers)
 144  *
 145  * @brief Atomically sets the address pointed to by *ppvDestination to the value
 146  *        of *pvExchange.
 147  *
 148  * @param[in, out] ppvDestination  Pointer to memory location from where a pointer
 149  *                                 value is to be loaded and written back to.
 150  * @param[in] pvExchange           Pointer value to be written to *ppvDestination.
 151  *
 152  * @return The initial value of *ppvDestination.
 153  */
 154 static portFORCE_INLINE void * Atomic_SwapPointers_p32( void * volatile * ppvDestination,
 155                                                         void * pvExchange )
 156 {
 157     void * pReturnValue;
 158
 159     ATOMIC_ENTER_CRITICAL();
 160     {
 161         pReturnValue = *ppvDestination;
 162         *ppvDestination = pvExchange;
 163     }
 164     ATOMIC_EXIT_CRITICAL();
 165
 166     return pReturnValue;
 167 }
 168 /*-----------------------------------------------------------*/
 169
 170 /**
 171  * Atomic compare-and-swap (pointers)
 172  *
 173  * @brief Performs an atomic compare-and-swap operation on the specified pointer
 174  *        values.
 175  *
 176  * @param[in, out] ppvDestination  Pointer to memory location from where a pointer
 177  *                                 value is to be loaded and checked.
 178  * @param[in] pvExchange           If condition meets, write this value to memory.
 179  * @param[in] pvComparand          Swap condition.
 180  *
 181  * @return Unsigned integer of value 1 or 0. 1 for swapped, 0 for not swapped.
 182  *
 183  * @note This function only swaps *ppvDestination with pvExchange, if previous
 184  *       *ppvDestination value equals pvComparand.
 185  */
 186 static portFORCE_INLINE uint32_t Atomic_CompareAndSwapPointers_p32( void * volatile * ppvDestination,
 187                                                                     void * pvExchange,
 188                                                                     void * pvComparand )
 189 {
 190     uint32_t ulReturnValue = ATOMIC_COMPARE_AND_SWAP_FAILURE;
 191
 192     ATOMIC_ENTER_CRITICAL();
 193     {
 194         if( *ppvDestination == pvComparand )
 195         {
 196             *ppvDestination = pvExchange;
 197             ulReturnValue = ATOMIC_COMPARE_AND_SWAP_SUCCESS;
 198         }
 199     }
 200     ATOMIC_EXIT_CRITICAL();
 201
 202     return ulReturnValue;
 203 }
 204
 205
 206 /*----------------------------- Arithmetic ------------------------------*/
 207
 208 /**
 209  * Atomic add
 210  *
 211  * @brief Atomically adds count to the value of the specified pointer points to.
 212  *
 213  * @param[in,out] pulAddend  Pointer to memory location from where value is to be
 214  *                         loaded and written back to.
 215  * @param[in] ulCount      Value to be added to *pulAddend.
 216  *
 217  * @return previous *pulAddend value.
 218  */
 219 static portFORCE_INLINE uint32_t Atomic_Add_u32( uint32_t volatile * pulAddend,
 220                                                  uint32_t ulCount )
 221 {
 222     uint32_t ulCurrent;
 223
 224     ATOMIC_ENTER_CRITICAL();
 225     {
 226         ulCurrent = *pulAddend;
 227         *pulAddend += ulCount;
 228     }
 229     ATOMIC_EXIT_CRITICAL();
 230
 231     return ulCurrent;
 232 }
 233 /*-----------------------------------------------------------*/
 234
 235 /**
 236  * Atomic subtract
 237  *
 238  * @brief Atomically subtracts count from the value of the specified pointer
 239  *        pointers to.
 240  *
 241  * @param[in,out] pulAddend  Pointer to memory location from where value is to be
 242  *                         loaded and written back to.
 243  * @param[in] ulCount      Value to be subtract from *pulAddend.
 244  *
 245  * @return previous *pulAddend value.
 246  */
 247 static portFORCE_INLINE uint32_t Atomic_Subtract_u32( uint32_t volatile * pulAddend,
 248                                                       uint32_t ulCount )
 249 {
 250     uint32_t ulCurrent;
 251
 252     ATOMIC_ENTER_CRITICAL();
 253     {
 254         ulCurrent = *pulAddend;
 255         *pulAddend -= ulCount;
 256     }
 257     ATOMIC_EXIT_CRITICAL();
 258
 259     return ulCurrent;
 260 }
 261 /*-----------------------------------------------------------*/
 262
 263 /**
 264  * Atomic increment
 265  *
 266  * @brief Atomically increments the value of the specified pointer points to.
 267  *
 268  * @param[in,out] pulAddend  Pointer to memory location from where value is to be
 269  *                         loaded and written back to.
 270  *
 271  * @return *pulAddend value before increment.
 272  */
 273 static portFORCE_INLINE uint32_t Atomic_Increment_u32( uint32_t volatile * pulAddend )
 274 {
 275     uint32_t ulCurrent;
 276
 277     ATOMIC_ENTER_CRITICAL();
 278     {
 279         ulCurrent = *pulAddend;
 280         *pulAddend += 1;
 281     }
 282     ATOMIC_EXIT_CRITICAL();
 283
 284     return ulCurrent;
 285 }
 286 /*-----------------------------------------------------------*/
 287
 288 /**
 289  * Atomic decrement
 290  *
 291  * @brief Atomically decrements the value of the specified pointer points to
 292  *
 293  * @param[in,out] pulAddend  Pointer to memory location from where value is to be
 294  *                         loaded and written back to.
 295  *
 296  * @return *pulAddend value before decrement.
 297  */
 298 static portFORCE_INLINE uint32_t Atomic_Decrement_u32( uint32_t volatile * pulAddend )
 299 {
 300     uint32_t ulCurrent;
 301
 302     ATOMIC_ENTER_CRITICAL();
 303     {
 304         ulCurrent = *pulAddend;
 305         *pulAddend -= 1;
 306     }
 307     ATOMIC_EXIT_CRITICAL();
 308
 309     return ulCurrent;
 310 }
 311
 312 /*----------------------------- Bitwise Logical ------------------------------*/
 313
 314 /**
 315  * Atomic OR
 316  *
 317  * @brief Performs an atomic OR operation on the specified values.
 318  *
 319  * @param [in, out] pulDestination  Pointer to memory location from where value is
 320  *                                to be loaded and written back to.
 321  * @param [in] ulValue            Value to be ORed with *pulDestination.
 322  *
 323  * @return The original value of *pulDestination.
 324  */
 325 static portFORCE_INLINE uint32_t Atomic_OR_u32( uint32_t volatile * pulDestination,
 326                                                 uint32_t ulValue )
 327 {
 328     uint32_t ulCurrent;
 329
 330     ATOMIC_ENTER_CRITICAL();
 331     {
 332         ulCurrent = *pulDestination;
 333         *pulDestination |= ulValue;
 334     }
 335     ATOMIC_EXIT_CRITICAL();
 336
 337     return ulCurrent;
 338 }
 339 /*-----------------------------------------------------------*/
 340
 341 /**
 342  * Atomic AND
 343  *
 344  * @brief Performs an atomic AND operation on the specified values.
 345  *
 346  * @param [in, out] pulDestination  Pointer to memory location from where value is
 347  *                                to be loaded and written back to.
 348  * @param [in] ulValue            Value to be ANDed with *pulDestination.
 349  *
 350  * @return The original value of *pulDestination.
 351  */
 352 static portFORCE_INLINE uint32_t Atomic_AND_u32( uint32_t volatile * pulDestination,
 353                                                  uint32_t ulValue )
 354 {
 355     uint32_t ulCurrent;
 356
 357     ATOMIC_ENTER_CRITICAL();
 358     {
 359         ulCurrent = *pulDestination;
 360         *pulDestination &= ulValue;
 361     }
 362     ATOMIC_EXIT_CRITICAL();
 363
 364     return ulCurrent;
 365 }
 366 /*-----------------------------------------------------------*/
 367
 368 /**
 369  * Atomic NAND
 370  *
 371  * @brief Performs an atomic NAND operation on the specified values.
 372  *
 373  * @param [in, out] pulDestination  Pointer to memory location from where value is
 374  *                                to be loaded and written back to.
 375  * @param [in] ulValue            Value to be NANDed with *pulDestination.
 376  *
 377  * @return The original value of *pulDestination.
 378  */
 379 static portFORCE_INLINE uint32_t Atomic_NAND_u32( uint32_t volatile * pulDestination,
 380                                                   uint32_t ulValue )
 381 {
 382     uint32_t ulCurrent;
 383
 384     ATOMIC_ENTER_CRITICAL();
 385     {
 386         ulCurrent = *pulDestination;
 387         *pulDestination = ~( ulCurrent & ulValue );
 388     }
 389     ATOMIC_EXIT_CRITICAL();
 390
 391     return ulCurrent;
 392 }
 393 /*-----------------------------------------------------------*/
 394
 395 /**
 396  * Atomic XOR
 397  *
 398  * @brief Performs an atomic XOR operation on the specified values.
 399  *
 400  * @param [in, out] pulDestination  Pointer to memory location from where value is
 401  *                                to be loaded and written back to.
 402  * @param [in] ulValue            Value to be XORed with *pulDestination.
 403  *
 404  * @return The original value of *pulDestination.
 405  */
 406 static portFORCE_INLINE uint32_t Atomic_XOR_u32( uint32_t volatile * pulDestination,
 407                                                  uint32_t ulValue )
 408 {
 409     uint32_t ulCurrent;
 410
 411     ATOMIC_ENTER_CRITICAL();
 412     {
 413         ulCurrent = *pulDestination;
 414         *pulDestination ^= ulValue;
 415     }
 416     ATOMIC_EXIT_CRITICAL();
 417
 418     return ulCurrent;
 419 }
 420
 421 /* *INDENT-OFF* */
 422 #ifdef __cplusplus
 423     }
 424 #endif
 425 /* *INDENT-ON* */
 426
 427 #endif /* ATOMIC_H */