hwspinlock.h

Go to the documentation of this file.

/*
 * Copyright (c) 2025 Sequans Communications
 *
 * SPDX-License-Identifier: Apache-2.0
 */

 
#ifndef ZEPHYR_INCLUDE_DRIVERS_HWSPINLOCK_H_
#define ZEPHYR_INCLUDE_DRIVERS_HWSPINLOCK_H_

 
#include <zephyr/types.h>
#include <zephyr/sys/util.h>
#include <zephyr/sys/__assert.h>
#include <zephyr/device.h>
#include <zephyr/spinlock.h>
#include <zephyr/devicetree.h>
 
#ifdef __cplusplus
extern "C" {
#endif

struct hwspinlock_context {
        /*
         * Per HW spinlock lock.
         *
         * HW spinlock protects resources across clusters, but we need to protect the
         * access to the HW spinlock inside of the same cluster, so a single thread may
         * claim the lock at a time.
         */
        struct k_spinlock lock;
};

typedef struct hwspinlock_context hwspinlock_ctx_t;

struct hwspinlock_dt_spec {
        const struct device *dev;
        uint32_t id;
        hwspinlock_ctx_t ctx;
};

#define HWSPINLOCK_CTX_INITIALIZER                                                                 \
        {                                                                                          \
                .lock = {},                                                                        \
        }

#define HWSPINLOCK_DT_SPEC_GET_BY_IDX(node_id, idx)                                                \
        {                                                                                          \
                .dev = DEVICE_DT_GET(DT_HWSPINLOCK_CTRL_BY_IDX(node_id, idx)),                     \
                .id = DT_HWSPINLOCK_ID_BY_IDX(node_id, idx),                                       \
                .ctx = HWSPINLOCK_CTX_INITIALIZER,                                                 \
        }

#define HWSPINLOCK_DT_SPEC_GET_BY_NAME(node_id, name)                                              \
        {                                                                                          \
                .dev = DEVICE_DT_GET(DT_HWSPINLOCK_CTRL_BY_NAME(node_id, name)),                   \
                .id = DT_HWSPINLOCK_ID_BY_NAME(node_id, name),                                     \
                .ctx = HWSPINLOCK_CTX_INITIALIZER,                                                 \
        }

#define HWSPINLOCK_DT_SPEC_GET(node_id) \
        HWSPINLOCK_DT_SPEC_GET_BY_IDX(node_id, 0)

#define HWSPINLOCK_DT_SPEC_INST_GET_BY_IDX(inst, idx)                                              \
        HWSPINLOCK_DT_SPEC_GET_BY_IDX(DT_DRV_INST(inst), idx)

#define HWSPINLOCK_DT_SPEC_INST_GET_BY_NAME(inst, name)                                            \
        HWSPINLOCK_DT_SPEC_GET_BY_NAME(DT_DRV_INST(inst), name)

#define HWSPINLOCK_DT_SPEC_INST_GET(inst) \
        HWSPINLOCK_DT_SPEC_GET(DT_DRV_INST(inst))


typedef int (*hwspinlock_api_trylock)(const struct device *dev, uint32_t id);

typedef void (*hwspinlock_api_lock)(const struct device *dev, uint32_t id);

typedef void (*hwspinlock_api_unlock)(const struct device *dev, uint32_t id);

typedef uint32_t (*hwspinlock_api_get_max_id)(const struct device *dev);

__subsystem struct hwspinlock_driver_api {
        hwspinlock_api_trylock trylock;
        hwspinlock_api_lock lock;
        hwspinlock_api_unlock unlock;
        hwspinlock_api_get_max_id get_max_id;
};


static inline int hw_spin_trylock(const struct device *dev, hwspinlock_ctx_t *ctx, uint32_t id,
                                  k_spinlock_key_t *key)
{
        const struct hwspinlock_driver_api *api = DEVICE_API_GET(hwspinlock, dev);
        int ret;
 
        if (api->trylock == NULL) {
                return -ENOSYS;
        }
 
        ret = k_spin_trylock(&ctx->lock, key);
        if (ret) {
                return ret;
        }
 
        ret = api->trylock(dev, id);
        if (ret) {
                /* HW trylock failed: release local lock before returning. */
                k_spin_unlock(&ctx->lock, *key);
                return ret;
        }
 
        return 0;
}

static inline k_spinlock_key_t hw_spin_lock(const struct device *dev, hwspinlock_ctx_t *ctx,
                                            uint32_t id)
{
        const struct hwspinlock_driver_api *api = DEVICE_API_GET(hwspinlock, dev);
        k_spinlock_key_t k;
 
        __ASSERT(api->lock != NULL, "hwspinlock lock callback must be implemented");
 
        k = k_spin_lock(&ctx->lock);
        api->lock(dev, id);
 
        return k;
}

static inline void hw_spin_unlock(const struct device *dev, hwspinlock_ctx_t *ctx, uint32_t id,
                                  k_spinlock_key_t key)
{
        const struct hwspinlock_driver_api *api = DEVICE_API_GET(hwspinlock, dev);
 
        __ASSERT(api->unlock != NULL, "hwspinlock unlock callback must be implemented");
 
        api->unlock(dev, id);
        k_spin_unlock(&ctx->lock, key);
}

static inline uint32_t hw_spinlock_get_max_id(const struct device *dev)
{
        const struct hwspinlock_driver_api *api = DEVICE_API_GET(hwspinlock, dev);
 
        __ASSERT(api->get_max_id != NULL, "hwspinlock get_max_id callback must be implemented");
 
        return api->get_max_id(dev);
}

static inline int hw_spin_trylock_dt(struct hwspinlock_dt_spec *spec, k_spinlock_key_t *key)
{
        return hw_spin_trylock(spec->dev, &spec->ctx, spec->id, key);
}

static inline k_spinlock_key_t hw_spin_lock_dt(struct hwspinlock_dt_spec *spec)
{
        return hw_spin_lock(spec->dev, &spec->ctx, spec->id);
}

static inline void hw_spin_unlock_dt(struct hwspinlock_dt_spec *spec, k_spinlock_key_t key)
{
        hw_spin_unlock(spec->dev, &spec->ctx, spec->id, key);
}

static inline uint32_t hw_spinlock_get_max_id_dt(struct hwspinlock_dt_spec *spec)
{
        return hw_spinlock_get_max_id(spec->dev);
}
 
#ifdef __cplusplus
}
#endif

 
#endif /* ZEPHYR_INCLUDE_DRIVERS_HWSPINLOCK_H_ */