Zephyr API Documentation  3.7.0-rc3
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
Atomic Services APIs

Macros

#define ATOMIC_INIT(i)   (i)
 Initialize an atomic variable.
 
#define ATOMIC_PTR_INIT(p)   (p)
 Initialize an atomic pointer variable.
 
#define ATOMIC_BITMAP_SIZE(num_bits)   (ROUND_UP(num_bits, ATOMIC_BITS) / ATOMIC_BITS)
 This macro computes the number of atomic variables necessary to represent a bitmap with num_bits.
 
#define ATOMIC_DEFINE(name, num_bits)    atomic_t name[ATOMIC_BITMAP_SIZE(num_bits)]
 Define an array of atomic variables.
 

Functions

static bool atomic_test_bit (const atomic_t *target, int bit)
 Atomically test a bit.
 
static bool atomic_test_and_clear_bit (atomic_t *target, int bit)
 Atomically test and clear a bit.
 
static bool atomic_test_and_set_bit (atomic_t *target, int bit)
 Atomically set a bit.
 
static void atomic_clear_bit (atomic_t *target, int bit)
 Atomically clear a bit.
 
static void atomic_set_bit (atomic_t *target, int bit)
 Atomically set a bit.
 
static void atomic_set_bit_to (atomic_t *target, int bit, bool val)
 Atomically set a bit to a given value.
 
bool atomic_cas (atomic_t *target, atomic_val_t old_value, atomic_val_t new_value)
 Atomic compare-and-set.
 
bool atomic_ptr_cas (atomic_ptr_t *target, atomic_ptr_val_t old_value, atomic_ptr_val_t new_value)
 Atomic compare-and-set with pointer values.
 
atomic_val_t atomic_add (atomic_t *target, atomic_val_t value)
 Atomic addition.
 
atomic_val_t atomic_sub (atomic_t *target, atomic_val_t value)
 Atomic subtraction.
 
atomic_val_t atomic_inc (atomic_t *target)
 Atomic increment.
 
atomic_val_t atomic_dec (atomic_t *target)
 Atomic decrement.
 
atomic_val_t atomic_get (const atomic_t *target)
 Atomic get.
 
atomic_ptr_val_t atomic_ptr_get (const atomic_ptr_t *target)
 Atomic get a pointer value.
 
atomic_val_t atomic_set (atomic_t *target, atomic_val_t value)
 Atomic get-and-set.
 
atomic_ptr_val_t atomic_ptr_set (atomic_ptr_t *target, atomic_ptr_val_t value)
 Atomic get-and-set for pointer values.
 
atomic_val_t atomic_clear (atomic_t *target)
 Atomic clear.
 
atomic_ptr_val_t atomic_ptr_clear (atomic_ptr_t *target)
 Atomic clear of a pointer value.
 
atomic_val_t atomic_or (atomic_t *target, atomic_val_t value)
 Atomic bitwise inclusive OR.
 
atomic_val_t atomic_xor (atomic_t *target, atomic_val_t value)
 Atomic bitwise exclusive OR (XOR).
 
atomic_val_t atomic_and (atomic_t *target, atomic_val_t value)
 Atomic bitwise AND.
 
atomic_val_t atomic_nand (atomic_t *target, atomic_val_t value)
 Atomic bitwise NAND.
 

Detailed Description

Macro Definition Documentation

◆ ATOMIC_BITMAP_SIZE

#define ATOMIC_BITMAP_SIZE (   num_bits)    (ROUND_UP(num_bits, ATOMIC_BITS) / ATOMIC_BITS)

#include <zephyr/sys/atomic.h>

This macro computes the number of atomic variables necessary to represent a bitmap with num_bits.

Parameters
num_bitsNumber of bits.

◆ ATOMIC_DEFINE

#define ATOMIC_DEFINE (   name,
  num_bits 
)     atomic_t name[ATOMIC_BITMAP_SIZE(num_bits)]

#include <zephyr/sys/atomic.h>

Define an array of atomic variables.

This macro defines an array of atomic variables containing at least num_bits bits.

Note
If used from file scope, the bits of the array are initialized to zero; if used from within a function, the bits are left uninitialized.
Parameters
nameName of array of atomic variables.
num_bitsNumber of bits needed.

◆ ATOMIC_INIT

#define ATOMIC_INIT (   i)    (i)

#include <zephyr/sys/atomic.h>

Initialize an atomic variable.

This macro can be used to initialize an atomic variable. For example,

atomic_t my_var = ATOMIC_INIT(75);
long atomic_t
Definition: atomic_types.h:15
#define ATOMIC_INIT(i)
Initialize an atomic variable.
Definition: atomic.h:59
Parameters
iValue to assign to atomic variable.

◆ ATOMIC_PTR_INIT

#define ATOMIC_PTR_INIT (   p)    (p)

#include <zephyr/sys/atomic.h>

Initialize an atomic pointer variable.

This macro can be used to initialize an atomic pointer variable. For example,

atomic_ptr_t my_ptr = ATOMIC_PTR_INIT(&data);
void * atomic_ptr_t
Definition: atomic_types.h:17
#define ATOMIC_PTR_INIT(p)
Initialize an atomic pointer variable.
Definition: atomic.h:70
Parameters
pPointer value to assign to atomic pointer variable.

Function Documentation

◆ atomic_add()

atomic_val_t atomic_add ( atomic_t target,
atomic_val_t  value 
)

#include <zephyr/sys/atomic.h>

Atomic addition.

This routine performs an atomic addition on target.

Note
As for all atomic APIs, includes a full/sequentially-consistent memory barrier (where applicable).
Parameters
targetAddress of atomic variable.
valueValue to add.
Returns
Previous value of target.

◆ atomic_and()

atomic_val_t atomic_and ( atomic_t target,
atomic_val_t  value 
)

#include <zephyr/sys/atomic.h>

Atomic bitwise AND.

This routine atomically sets target to the bitwise AND of target and value.

Note
As for all atomic APIs, includes a full/sequentially-consistent memory barrier (where applicable).
Parameters
targetAddress of atomic variable.
valueValue to AND.
Returns
Previous value of target.

◆ atomic_cas()

bool atomic_cas ( atomic_t target,
atomic_val_t  old_value,
atomic_val_t  new_value 
)

#include <zephyr/sys/atomic.h>

Atomic compare-and-set.

This routine performs an atomic compare-and-set on target. If the current value of target equals old_value, target is set to new_value. If the current value of target does not equal old_value, target is left unchanged.

Note
As for all atomic APIs, includes a full/sequentially-consistent memory barrier (where applicable).
Parameters
targetAddress of atomic variable.
old_valueOriginal value to compare against.
new_valueNew value to store.
Returns
true if new_value is written, false otherwise.

◆ atomic_clear()

atomic_val_t atomic_clear ( atomic_t target)

#include <zephyr/sys/atomic.h>

Atomic clear.

This routine atomically sets target to zero and returns its previous value. (Hence, it is equivalent to atomic_set(target, 0).)

Note
As for all atomic APIs, includes a full/sequentially-consistent memory barrier (where applicable).
Parameters
targetAddress of atomic variable.
Returns
Previous value of target.

◆ atomic_clear_bit()

static void atomic_clear_bit ( atomic_t target,
int  bit 
)
inlinestatic

#include <zephyr/sys/atomic.h>

Atomically clear a bit.

Atomically clear bit number bit of target. The target may be a single atomic variable or an array of them.

Note
As for all atomic APIs, includes a full/sequentially-consistent memory barrier (where applicable).
Parameters
targetAddress of atomic variable or array.
bitBit number (starting from 0).

◆ atomic_dec()

atomic_val_t atomic_dec ( atomic_t target)

#include <zephyr/sys/atomic.h>

Atomic decrement.

This routine performs an atomic decrement by 1 on target.

Note
As for all atomic APIs, includes a full/sequentially-consistent memory barrier (where applicable).
Parameters
targetAddress of atomic variable.
Returns
Previous value of target.

◆ atomic_get()

atomic_val_t atomic_get ( const atomic_t target)

#include <zephyr/sys/atomic.h>

Atomic get.

This routine performs an atomic read on target.

Note
As for all atomic APIs, includes a full/sequentially-consistent memory barrier (where applicable).
Parameters
targetAddress of atomic variable.
Returns
Value of target.

◆ atomic_inc()

atomic_val_t atomic_inc ( atomic_t target)

#include <zephyr/sys/atomic.h>

Atomic increment.

This routine performs an atomic increment by 1 on target.

Note
As for all atomic APIs, includes a full/sequentially-consistent memory barrier (where applicable).
Parameters
targetAddress of atomic variable.
Returns
Previous value of target.

◆ atomic_nand()

atomic_val_t atomic_nand ( atomic_t target,
atomic_val_t  value 
)

#include <zephyr/sys/atomic.h>

Atomic bitwise NAND.

This routine atomically sets target to the bitwise NAND of target and value. (This operation is equivalent to target = ~(target & value).)

Note
As for all atomic APIs, includes a full/sequentially-consistent memory barrier (where applicable).
Parameters
targetAddress of atomic variable.
valueValue to NAND.
Returns
Previous value of target.

◆ atomic_or()

atomic_val_t atomic_or ( atomic_t target,
atomic_val_t  value 
)

#include <zephyr/sys/atomic.h>

Atomic bitwise inclusive OR.

This routine atomically sets target to the bitwise inclusive OR of target and value.

Note
As for all atomic APIs, includes a full/sequentially-consistent memory barrier (where applicable).
Parameters
targetAddress of atomic variable.
valueValue to OR.
Returns
Previous value of target.

◆ atomic_ptr_cas()

bool atomic_ptr_cas ( atomic_ptr_t target,
atomic_ptr_val_t  old_value,
atomic_ptr_val_t  new_value 
)

#include <zephyr/sys/atomic.h>

Atomic compare-and-set with pointer values.

This routine performs an atomic compare-and-set on target. If the current value of target equals old_value, target is set to new_value. If the current value of target does not equal old_value, target is left unchanged.

Note
As for all atomic APIs, includes a full/sequentially-consistent memory barrier (where applicable).
Parameters
targetAddress of atomic variable.
old_valueOriginal value to compare against.
new_valueNew value to store.
Returns
true if new_value is written, false otherwise.

◆ atomic_ptr_clear()

atomic_ptr_val_t atomic_ptr_clear ( atomic_ptr_t target)

#include <zephyr/sys/atomic.h>

Atomic clear of a pointer value.

This routine atomically sets target to zero and returns its previous value. (Hence, it is equivalent to atomic_set(target, 0).)

Note
As for all atomic APIs, includes a full/sequentially-consistent memory barrier (where applicable).
Parameters
targetAddress of atomic variable.
Returns
Previous value of target.

◆ atomic_ptr_get()

atomic_ptr_val_t atomic_ptr_get ( const atomic_ptr_t target)

#include <zephyr/sys/atomic.h>

Atomic get a pointer value.

This routine performs an atomic read on target.

Note
As for all atomic APIs, includes a full/sequentially-consistent memory barrier (where applicable).
Parameters
targetAddress of pointer variable.
Returns
Value of target.

◆ atomic_ptr_set()

atomic_ptr_val_t atomic_ptr_set ( atomic_ptr_t target,
atomic_ptr_val_t  value 
)

#include <zephyr/sys/atomic.h>

Atomic get-and-set for pointer values.

This routine atomically sets target to value and returns the previous value of target.

Note
As for all atomic APIs, includes a full/sequentially-consistent memory barrier (where applicable).
Parameters
targetAddress of atomic variable.
valueValue to write to target.
Returns
Previous value of target.

◆ atomic_set()

atomic_val_t atomic_set ( atomic_t target,
atomic_val_t  value 
)

#include <zephyr/sys/atomic.h>

Atomic get-and-set.

This routine atomically sets target to value and returns the previous value of target.

Note
As for all atomic APIs, includes a full/sequentially-consistent memory barrier (where applicable).
Parameters
targetAddress of atomic variable.
valueValue to write to target.
Returns
Previous value of target.

◆ atomic_set_bit()

static void atomic_set_bit ( atomic_t target,
int  bit 
)
inlinestatic

#include <zephyr/sys/atomic.h>

Atomically set a bit.

Atomically set bit number bit of target. The target may be a single atomic variable or an array of them.

Note
As for all atomic APIs, includes a full/sequentially-consistent memory barrier (where applicable).
Parameters
targetAddress of atomic variable or array.
bitBit number (starting from 0).

◆ atomic_set_bit_to()

static void atomic_set_bit_to ( atomic_t target,
int  bit,
bool  val 
)
inlinestatic

#include <zephyr/sys/atomic.h>

Atomically set a bit to a given value.

Atomically set bit number bit of target to value val. The target may be a single atomic variable or an array of them.

Note
As for all atomic APIs, includes a full/sequentially-consistent memory barrier (where applicable).
Parameters
targetAddress of atomic variable or array.
bitBit number (starting from 0).
valtrue for 1, false for 0.

◆ atomic_sub()

atomic_val_t atomic_sub ( atomic_t target,
atomic_val_t  value 
)

#include <zephyr/sys/atomic.h>

Atomic subtraction.

This routine performs an atomic subtraction on target.

Note
As for all atomic APIs, includes a full/sequentially-consistent memory barrier (where applicable).
Parameters
targetAddress of atomic variable.
valueValue to subtract.
Returns
Previous value of target.

◆ atomic_test_and_clear_bit()

static bool atomic_test_and_clear_bit ( atomic_t target,
int  bit 
)
inlinestatic

#include <zephyr/sys/atomic.h>

Atomically test and clear a bit.

Atomically clear bit number bit of target and return its old value. The target may be a single atomic variable or an array of them.

Note
As for all atomic APIs, includes a full/sequentially-consistent memory barrier (where applicable).
Parameters
targetAddress of atomic variable or array.
bitBit number (starting from 0).
Returns
false if the bit was already cleared, true if it wasn't.

◆ atomic_test_and_set_bit()

static bool atomic_test_and_set_bit ( atomic_t target,
int  bit 
)
inlinestatic

#include <zephyr/sys/atomic.h>

Atomically set a bit.

Atomically set bit number bit of target and return its old value. The target may be a single atomic variable or an array of them.

Note
As for all atomic APIs, includes a full/sequentially-consistent memory barrier (where applicable).
Parameters
targetAddress of atomic variable or array.
bitBit number (starting from 0).
Returns
true if the bit was already set, false if it wasn't.

◆ atomic_test_bit()

static bool atomic_test_bit ( const atomic_t target,
int  bit 
)
inlinestatic

#include <zephyr/sys/atomic.h>

Atomically test a bit.

This routine tests whether bit number bit of target is set or not. The target may be a single atomic variable or an array of them.

Note
As for all atomic APIs, includes a full/sequentially-consistent memory barrier (where applicable).
Parameters
targetAddress of atomic variable or array.
bitBit number (starting from 0).
Returns
true if the bit was set, false if it wasn't.

◆ atomic_xor()

atomic_val_t atomic_xor ( atomic_t target,
atomic_val_t  value 
)

#include <zephyr/sys/atomic.h>

Atomic bitwise exclusive OR (XOR).

Note
As for all atomic APIs, includes a full/sequentially-consistent memory barrier (where applicable).

This routine atomically sets target to the bitwise exclusive OR (XOR) of target and value.

Parameters
targetAddress of atomic variable.
valueValue to XOR
Returns
Previous value of target.