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_dt_spec {
        const struct device *dev;
        uint32_t id;
};

#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),                                       \
        }

#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),                                     \
        }

#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))

 
#define __HWSPINLOCK_NUM_LOCKS_FROM_DT_NODE(node_id) \
        DT_PROP(node_id, num_locks)
 
#define __HWSPINLOCK_SPINLOCK_ARRAY_NAME_FROM_DT_NODE(node_id) \
        CONCAT(__hwspinlock_locks_, DT_DEP_ORD(node_id))


#define HWSPINLOCK_COMMON_CONFIG_FROM_DT_NODE(node_id)                                             \
        {                                                                                          \
                .num_locks = __HWSPINLOCK_NUM_LOCKS_FROM_DT_NODE(node_id),                         \
                .locks = __HWSPINLOCK_SPINLOCK_ARRAY_NAME_FROM_DT_NODE(node_id),                   \
        }

#define HWSPINLOCK_COMMON_CONFIG_FROM_DT_INST(inst) \
        HWSPINLOCK_COMMON_CONFIG_FROM_DT_NODE(DT_DRV_INST(inst))

#define HWSPINLOCK_SPINLOCK_ARRAY_DT_DEFINE(node_id)                                               \
        static struct k_spinlock __HWSPINLOCK_SPINLOCK_ARRAY_NAME_FROM_DT_NODE(                    \
                node_id)[__HWSPINLOCK_NUM_LOCKS_FROM_DT_NODE(node_id)]

#define HWSPINLOCK_SPINLOCK_ARRAY_DT_INST_DEFINE(inst) \
        HWSPINLOCK_SPINLOCK_ARRAY_DT_DEFINE(DT_DRV_INST(inst))

struct hwspinlock_driver_config {
        uint8_t num_locks;
        struct k_spinlock *locks;
};


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, uint32_t id, k_spinlock_key_t *key)
{
        const struct hwspinlock_driver_api *api = DEVICE_API_GET(hwspinlock, dev);
        const struct hwspinlock_driver_config *const cfg = dev->config;
        int ret;
 
        if (api->trylock == NULL) {
                return -ENOSYS;
        }
 
        ret = k_spin_trylock(&cfg->locks[id], key);
        if (ret) {
                return ret;
        }
 
        ret = api->trylock(dev, id);
        if (ret) {
                /* HW trylock failed: release local lock before returning. */
                k_spin_unlock(&cfg->locks[id], *key);
        }
 
        return ret;
}

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

static inline void hw_spin_unlock(const struct device *dev, uint32_t id, k_spinlock_key_t key)
{
        const struct hwspinlock_driver_api *api = DEVICE_API_GET(hwspinlock, dev);
        const struct hwspinlock_driver_config *const cfg = dev->config;
 
        __ASSERT(api->unlock != NULL, "hwspinlock unlock callback must be implemented");
 
        api->unlock(dev, id);
        k_spin_unlock(&cfg->locks[id], 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);
        __unused const struct hwspinlock_driver_config *const cfg = dev->config;
 
        if (!api->get_max_id) {
                /* Lock ids range from 0 to n-1 */
                return cfg->num_locks - 1;
        }
 
        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->id, key);
}

static inline k_spinlock_key_t hw_spin_lock_dt(struct hwspinlock_dt_spec *spec)
{
        return hw_spin_lock(spec->dev, 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->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_ */