spinlock.h

Go to the documentation of this file.

/*
 * Copyright (c) 2018 Intel Corporation.
 *
 * SPDX-License-Identifier: Apache-2.0
 */
 
#ifndef ZEPHYR_INCLUDE_SPINLOCK_H_
#define ZEPHYR_INCLUDE_SPINLOCK_H_
 
#include <errno.h>
#include <stdbool.h>
 
#include <zephyr/arch/cpu.h>
#include <zephyr/sys/atomic.h>
#include <zephyr/sys/__assert.h>
#include <zephyr/sys/time_units.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
struct z_spinlock_key {
        int key;
};
 
struct k_spinlock {
#ifdef CONFIG_SMP
        atomic_t locked;
#endif
 
#ifdef CONFIG_SPIN_VALIDATE
        /* Stores the thread that holds the lock with the locking CPU
         * ID in the bottom two bits.
         */
        uintptr_t thread_cpu;
#ifdef CONFIG_SPIN_LOCK_TIME_LIMIT
        /* Stores the time (in cycles) when a lock was taken
         */
        uint32_t lock_time;
#endif /* CONFIG_SPIN_LOCK_TIME_LIMIT */
#endif /* CONFIG_SPIN_VALIDATE */
 
#if defined(CONFIG_CPP) && !defined(CONFIG_SMP) && \
        !defined(CONFIG_SPIN_VALIDATE)
        /* If CONFIG_SMP and CONFIG_SPIN_VALIDATE are both not defined
         * the k_spinlock struct will have no members. The result
         * is that in C sizeof(k_spinlock) is 0 and in C++ it is 1.
         *
         * This size difference causes problems when the k_spinlock
         * is embedded into another struct like k_msgq, because C and
         * C++ will have different ideas on the offsets of the members
         * that come after the k_spinlock member.
         *
         * To prevent this we add a 1 byte dummy member to k_spinlock
         * when the user selects C++ support and k_spinlock would
         * otherwise be empty.
         */
        char dummy;
#endif
};
 
/* There's a spinlock validation framework available when asserts are
 * enabled.  It adds a relatively hefty overhead (about 3k or so) to
 * kernel code size, don't use on platforms known to be small.
 */
#ifdef CONFIG_SPIN_VALIDATE
bool z_spin_lock_valid(struct k_spinlock *l);
bool z_spin_unlock_valid(struct k_spinlock *l);
void z_spin_lock_set_owner(struct k_spinlock *l);
BUILD_ASSERT(CONFIG_MP_MAX_NUM_CPUS <= 4, "Too many CPUs for mask");
 
# ifdef CONFIG_KERNEL_COHERENCE
bool z_spin_lock_mem_coherent(struct k_spinlock *l);
# endif /* CONFIG_KERNEL_COHERENCE */
 
#endif /* CONFIG_SPIN_VALIDATE */
 
typedef struct z_spinlock_key k_spinlock_key_t;
 
static ALWAYS_INLINE void z_spinlock_validate_pre(struct k_spinlock *l)
{
        ARG_UNUSED(l);
#ifdef CONFIG_SPIN_VALIDATE
        __ASSERT(z_spin_lock_valid(l), "Invalid spinlock %p", l);
#ifdef CONFIG_KERNEL_COHERENCE
        __ASSERT_NO_MSG(z_spin_lock_mem_coherent(l));
#endif
#endif
}
 
static ALWAYS_INLINE void z_spinlock_validate_post(struct k_spinlock *l)
{
        ARG_UNUSED(l);
#ifdef CONFIG_SPIN_VALIDATE
        z_spin_lock_set_owner(l);
#if defined(CONFIG_SPIN_LOCK_TIME_LIMIT) && (CONFIG_SPIN_LOCK_TIME_LIMIT != 0)
        l->lock_time = sys_clock_cycle_get_32();
#endif /* CONFIG_SPIN_LOCK_TIME_LIMIT */
#endif /* CONFIG_SPIN_VALIDATE */
}
 
static ALWAYS_INLINE k_spinlock_key_t k_spin_lock(struct k_spinlock *l)
{
        ARG_UNUSED(l);
        k_spinlock_key_t k;
 
        /* Note that we need to use the underlying arch-specific lock
         * implementation.  The "irq_lock()" API in SMP context is
         * actually a wrapper for a global spinlock!
         */
        k.key = arch_irq_lock();
 
        z_spinlock_validate_pre(l);
#ifdef CONFIG_SMP
        while (!atomic_cas(&l->locked, 0, 1)) {
                arch_spin_relax();
        }
#endif
        z_spinlock_validate_post(l);
 
        return k;
}
 
static ALWAYS_INLINE int k_spin_trylock(struct k_spinlock *l, k_spinlock_key_t *k)
{
        int key = arch_irq_lock();
 
        z_spinlock_validate_pre(l);
#ifdef CONFIG_SMP
        if (!atomic_cas(&l->locked, 0, 1)) {
                arch_irq_unlock(key);
                return -EBUSY;
        }
#endif
        z_spinlock_validate_post(l);
 
        k->key = key;
 
        return 0;
}
 
static ALWAYS_INLINE void k_spin_unlock(struct k_spinlock *l,
                                        k_spinlock_key_t key)
{
        ARG_UNUSED(l);
#ifdef CONFIG_SPIN_VALIDATE
        __ASSERT(z_spin_unlock_valid(l), "Not my spinlock %p", l);
 
#if defined(CONFIG_SPIN_LOCK_TIME_LIMIT) && (CONFIG_SPIN_LOCK_TIME_LIMIT != 0)
        uint32_t delta = sys_clock_cycle_get_32() - l->lock_time;
 
        __ASSERT(delta < CONFIG_SPIN_LOCK_TIME_LIMIT,
                 "Spin lock %p held %u cycles, longer than limit of %u cycles",
                 l, delta, CONFIG_SPIN_LOCK_TIME_LIMIT);
#endif /* CONFIG_SPIN_LOCK_TIME_LIMIT */
#endif /* CONFIG_SPIN_VALIDATE */
 
#ifdef CONFIG_SMP
        /* Strictly we don't need atomic_clear() here (which is an
         * exchange operation that returns the old value).  We are always
         * setting a zero and (because we hold the lock) know the existing
         * state won't change due to a race.  But some architectures need
         * a memory barrier when used like this, and we don't have a
         * Zephyr framework for that.
         */
        atomic_clear(&l->locked);
#endif
        arch_irq_unlock(key.key);
}
 
#if defined(CONFIG_SMP) && defined(CONFIG_TEST)
/*
 * @brief Checks if spinlock is held by some CPU, including the local CPU.
 *              This API shouldn't be used outside the tests for spinlock
 *
 * @param l A pointer to the spinlock
 * @retval true - if spinlock is held by some CPU; false - otherwise
 */
static ALWAYS_INLINE bool z_spin_is_locked(struct k_spinlock *l)
{
        return l->locked;
}
#endif
 
/* Internal function: releases the lock, but leaves local interrupts disabled */
static ALWAYS_INLINE void k_spin_release(struct k_spinlock *l)
{
        ARG_UNUSED(l);
#ifdef CONFIG_SPIN_VALIDATE
        __ASSERT(z_spin_unlock_valid(l), "Not my spinlock %p", l);
#endif
#ifdef CONFIG_SMP
        atomic_clear(&l->locked);
#endif
}
 
#if defined(CONFIG_SPIN_VALIDATE) && defined(__GNUC__)
static ALWAYS_INLINE void z_spin_onexit(__maybe_unused k_spinlock_key_t *k)
{
        __ASSERT(k->key, "K_SPINLOCK exited with goto, break or return, "
                         "use K_SPINLOCK_BREAK instead.");
}
#define K_SPINLOCK_ONEXIT __attribute__((__cleanup__(z_spin_onexit)))
#else
#define K_SPINLOCK_ONEXIT
#endif
 
#define K_SPINLOCK_BREAK continue
 
#define K_SPINLOCK(lck)                                                                            \
        for (k_spinlock_key_t __i K_SPINLOCK_ONEXIT = {}, __key = k_spin_lock(lck); !__i.key;      \
             k_spin_unlock(lck, __key), __i.key = 1)
 
#ifdef __cplusplus
}
#endif
 
#endif /* ZEPHYR_INCLUDE_SPINLOCK_H_ */