Zephyr API Documentation: Spinlock APIs (2024)

#include <zephyr/spinlock.h>

Value:

Guards a code block with the given spinlock, automatically acquiring the lock before executing the code block.

The lock will be released either when reaching the end of the code block or when leaving the block with K_SPINLOCK_BREAK.

Example usage:

Behind the scenes this pattern expands to a for-loop whose body is executed exactly once:

Warning

The code block must execute to its end or be left by calling K_SPINLOCK_BREAK. Otherwise, e.g. if exiting the block with a break, goto or return statement, the spinlock will not be released on exit.

Note

In user mode the spinlock must be placed in memory accessible to the application, see K_APP_DMEM and K_APP_BMEM macros for details.

Parameters

lck	Spinlock used to guard the enclosed code block.

#define K_SPINLOCK_BREAKcontinue

#include <zephyr/spinlock.h>

Leaves a code block guarded with K_SPINLOCK after releasing the lock.

See K_SPINLOCK for details.

typedef struct z_spinlock_key k_spinlock_key_t

#include <zephyr/spinlock.h>

Spinlock key type.

This type defines a "key" value used by a spinlock implementation to store the system interrupt state at the time of a call to k_spin_lock(). It is expected to be passed to a matching k_spin_unlock().

This type is opaque and should not be inspected by application code.

#include <zephyr/spinlock.h>

Lock a spinlock.

This routine locks the specified spinlock, returning a key handle representing interrupt state needed at unlock time. Upon returning, the calling thread is guaranteed not to be suspended or interrupted on its current CPU until it calls k_spin_unlock(). The implementation guarantees mutual exclusion: exactly one thread on one CPU will return from k_spin_lock() at a time. Other CPUs trying to acquire a lock already held by another CPU will enter an implementation-defined busy loop ("spinning") until the lock is released.

Separate spin locks may be nested. It is legal to lock an (unlocked) spin lock while holding a different lock. Spin locks are not recursive, however: an attempt to acquire a spin lock that the CPU already holds will deadlock.

In circ*mstances where only one CPU exists, the behavior of k_spin_lock() remains as specified above, though obviously no spinning will take place. Implementations may be free to optimize in uniprocessor contexts such that the locking reduces to an interrupt mask operation.

Parameters

l	A pointer to the spinlock to lock

Returns

A key value that must be passed to k_spin_unlock() when the lock is released.

#include <zephyr/spinlock.h>

Attempt to lock a spinlock.

This routine makes one attempt to lock l. If it is successful, then it will store the key into k.

Parameters

[in]	l	A pointer to the spinlock to lock
[out]	k	A pointer to the spinlock key

Return values

0	on success
-EBUSY	if another thread holds the lock

See also

k_spin_lock

k_spin_unlock

#include <zephyr/spinlock.h>

Unlock a spin lock.

This releases a lock acquired by k_spin_lock(). After this function is called, any CPU will be able to acquire the lock. If other CPUs are currently spinning inside k_spin_lock() waiting for this lock, exactly one of them will return synchronously with the lock held.

Spin locks must be properly nested. A call to k_spin_unlock() must be made on the lock object most recently locked using k_spin_lock(), using the key value that it returned. Attempts to unlock mis-nested locks, or to unlock locks that are not held, or to passing a key parameter other than the one returned from k_spin_lock(), are illegal. When CONFIG_SPIN_VALIDATE is set, some of these errors can be detected by the framework.

Parameters

l	A pointer to the spinlock to release
key	The value returned from k_spin_lock() when this lock was acquired