c1c1ffe7f7
The tables in the Kernel Primer are changed to lists. Making it easier to update them. Other minor changes were done to ensure consitency. The :c: and :cpp: markup has been fixed. When the documentation for a call exists, then it is linked. Change-Id: I8f389a0a0ca7c5fe904c0a1fa520e2e499f1001b Signed-off-by: Rodrigo Caballero <rodrigo.caballero.abraham@intel.com>
105 lines
2.8 KiB
ReStructuredText
105 lines
2.8 KiB
ReStructuredText
.. _atomic_services:
|
|
|
|
Atomic Services
|
|
###############
|
|
|
|
Concepts
|
|
********
|
|
|
|
The kernel supports an atomic 32-bit data type called :c:type:`atomic_t`.
|
|
A variable of this type can be read and modified by any task, fiber, or ISR
|
|
in an uninterruptible manner. This guarantees that the desired operation
|
|
will not be interfered with due to the scheduling of a higher priority context,
|
|
even if the higher priority context manipulates the same variable.
|
|
|
|
Purpose
|
|
*******
|
|
|
|
Use the atomic services to implement critical section processing that only
|
|
requires the manipulation of a single 32-bit data item.
|
|
|
|
.. note::
|
|
Using an atomic variable is typically far more efficient than using
|
|
other techniques to implement critical sections such as using
|
|
a microkernel mutex, offloading the processing to a fiber, or
|
|
locking interrupts.
|
|
|
|
Usage
|
|
*****
|
|
|
|
Example: Implementing an Uninterruptible Counter
|
|
================================================
|
|
This code shows how a function can keep track of the number of times
|
|
it has been invoked. Since the count is incremented atomically, there is
|
|
no risk that it will become corrupted in mid-increment if the routine is
|
|
interrupted by the scheduling of a higher priority context that also
|
|
calls the routine.
|
|
|
|
.. code-block:: c
|
|
|
|
atomic_t call_count;
|
|
|
|
int call_counting_routine(void)
|
|
{
|
|
/* increment invocation counter */
|
|
atomic_inc(&call_count);
|
|
|
|
/* do rest of routine's processing */
|
|
...
|
|
}
|
|
|
|
APIs
|
|
****
|
|
|
|
The following atomic operation APIs are provided by :file:`atomic.h`:
|
|
|
|
:c:func:`atomic_get()`
|
|
Reads an atomic variable.
|
|
|
|
:c:func:`atomic_set()`
|
|
Writes an atomic variable.
|
|
|
|
:c:func:`atomic_clear()`
|
|
Clears an atomic variable.
|
|
|
|
:c:func:`atomic_add()`
|
|
Performs an addition operation on an atomic variable.
|
|
|
|
:c:func:`atomic_sub()`
|
|
Performs a subtraction operation on an atomic variable.
|
|
|
|
:c:func:`atomic_inc()`
|
|
Performs an increment operation on an atomic variable.
|
|
|
|
:c:func:`atomic_dec()`
|
|
Performs a decrement operation on an atomic variable.
|
|
|
|
:c:func:`atomic_and()`
|
|
Perform an "and" operation on an atomic variable.
|
|
|
|
:c:func:`atomic_or()`
|
|
Perform an "or" operation on an atomic variable.
|
|
|
|
:c:func:`atomic_xor()`
|
|
Perform a "xor" operation on an atomic variable.
|
|
|
|
:c:func:`atomic_nand()`
|
|
Perform a "nand" operation on an atomic variable.
|
|
|
|
:c:func:`atomic_cas()`
|
|
Performs compare-and-set operation on an atomic variable.
|
|
|
|
:c:func:`atomic_set_bit()`
|
|
Sets specified bit of an atomic variable to 1.
|
|
|
|
:c:func:`atomic_clear_bit()`
|
|
Sets specified bit of an atomic variable to 0.
|
|
|
|
:c:func:`atomic_test_bit()`
|
|
Reads specified bit of an atomic variable.
|
|
|
|
:c:func:`atomic_test_and_set_bit()`
|
|
Reads specified bit of an atomic variable and sets it to 1.
|
|
|
|
:c:func:`atomic_test_and_clear_bit()`
|
|
Reads specified bit of an atomic variable and sets it to 0. |