Hardware Spinlock

Interfaces for hardware spinlocks. More...

Files
file	hwspinlock.h
	Main header file for hardware spinlock driver API.

Data Structures
struct	hwspinlock_context
	HW spinlock controller runtime context. More...
struct	hwspinlock_dt_spec
	Complete hardware spinlock DT information. More...

Macros
#define	HWSPINLOCK_CTX_INITIALIZER
	Initializer for a hwspinlock_ctx_t.
#define	HWSPINLOCK_DT_SPEC_GET_BY_IDX(node_id, idx)
	Structure initializer for struct hwspinlock_dt_spec from devicetree by index.
#define	HWSPINLOCK_DT_SPEC_GET_BY_NAME(node_id, name)
	Structure initializer for struct hwspinlock_dt_spec from devicetree by name.
#define	HWSPINLOCK_DT_SPEC_GET(node_id)
	Structure initializer for struct hwspinlock_dt_spec from devicetree.
#define	HWSPINLOCK_DT_SPEC_INST_GET_BY_IDX(inst, idx)
	Instance version of HWSPINLOCK_DT_SPEC_GET_BY_IDX()
#define	HWSPINLOCK_DT_SPEC_INST_GET_BY_NAME(inst, name)
	Instance version of HWSPINLOCK_DT_SPEC_GET_BY_NAME()
#define	HWSPINLOCK_DT_SPEC_INST_GET(inst)
	Instance version of HWSPINLOCK_DT_SPEC_GET()

Typedefs
typedef struct hwspinlock_context	hwspinlock_ctx_t
	Opaque type to represent a hwspinlock runtime context.

Functions
static int	hw_spin_trylock (const struct device *dev, hwspinlock_ctx_t *ctx, uint32_t id, k_spinlock_key_t *key)
	Try to lock HW spinlock.
static k_spinlock_key_t	hw_spin_lock (const struct device *dev, hwspinlock_ctx_t *ctx, uint32_t id)
	Lock HW spinlock.
static void	hw_spin_unlock (const struct device *dev, hwspinlock_ctx_t *ctx, uint32_t id, k_spinlock_key_t key)
	Unlock HW spinlock.
static uint32_t	hw_spinlock_get_max_id (const struct device *dev)
	Get HW spinlock max ID.
static int	hw_spin_trylock_dt (struct hwspinlock_dt_spec *spec, k_spinlock_key_t *key)
	Try to lock HW spinlock from a struct hwspinlock_dt_spec.
static k_spinlock_key_t	hw_spin_lock_dt (struct hwspinlock_dt_spec *spec)
	Lock HW spinlock from a struct hwspinlock_dt_spec.
static void	hw_spin_unlock_dt (struct hwspinlock_dt_spec *spec, k_spinlock_key_t key)
	Unlock HW spinlock from a struct hwspinlock_dt_spec.
static uint32_t	hw_spinlock_get_max_id_dt (struct hwspinlock_dt_spec *spec)
	Get HW spinlock max ID from a struct hwspinlock_dt_spec.

Detailed Description

Interfaces for hardware spinlocks.

Macro Definition Documentation

HWSPINLOCK_CTX_INITIALIZER

#define HWSPINLOCK_CTX_INITIALIZER

#include <zephyr/drivers/hwspinlock.h>

Value:

        {                                                                                          \
                .lock = {0},                                                                       \
        }

Initializer for a hwspinlock_ctx_t.

Note

We must declare each field individually because a struct k_spinlock might have no field depending on Kconfig options, and gcc requires struct without any field to be initialized explicitly, instead of just being able to do {0}.

HWSPINLOCK_DT_SPEC_GET

#define HWSPINLOCK_DT_SPEC_GET

(

node_id

)

#include <zephyr/drivers/hwspinlock.h>

Value:

        HWSPINLOCK_DT_SPEC_GET_BY_IDX(node_id, 0)

Structure initializer for struct hwspinlock_dt_spec from devicetree.

This is equivalent to HWSPINLOCK_DT_SPEC_GET_BY_IDX(node_id, 0)

Parameters

node_id

Devicetree node identifier for the HWSPINLOCK device

See also

HWSPINLOCK_DT_SPEC_GET_BY_IDX()

HWSPINLOCK_DT_SPEC_GET_BY_IDX

#define HWSPINLOCK_DT_SPEC_GET_BY_IDX	(		node_id,
			idx )

#include <zephyr/drivers/hwspinlock.h>

Value:

        {                                                                                          \
                .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,                                                 \
        }

Structure initializer for struct hwspinlock_dt_spec from devicetree by index.

This helper macro expands to a static initializer for a struct hwspinlock_dt_spec by reading the relevant device controller and id number from the devicetree.

Example devicetree fragment:

n: node {
        hwlocks = <&hwlock 8>,
                  <&hwlock 9>;
};

Example usage:

const struct hwspinlock_dt_spec spec = HWSPINLOCK_DT_SPEC_GET_BY_IDX(DT_NODELABEL(n), 0);

Parameters

node_id	Devicetree node identifier for the HWSPINLOCK device
idx	Index of hwlocks element

Returns

static initializer for a struct hwspinlock_dt_spec

HWSPINLOCK_DT_SPEC_GET_BY_NAME

#define HWSPINLOCK_DT_SPEC_GET_BY_NAME	(		node_id,
			name )

#include <zephyr/drivers/hwspinlock.h>

Value:

        {                                                                                          \
                .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,                                                 \
        }

Structure initializer for struct hwspinlock_dt_spec from devicetree by name.

This helper macro expands to a static initializer for a struct hwspinlock_dt_spec by reading the relevant device controller and id number from the devicetree.

Example devicetree fragment:

n: node {
        hwlocks = <&hwlock 8>,
                  <&hwlock 9>;
        hwlock-names = "rd", "wr";
};

Example usage:

const struct hwspinlock_dt_spec spec = HWSPINLOCK_DT_SPEC_GET_BY_NAME(DT_NODELABEL(n), wr);

Parameters

node_id	Devicetree node identifier for the HWSPINLOCK device
name	lowercase-and-underscores name of the hwlocks element

Returns

static initializer for a struct hwspinlock_dt_spec

HWSPINLOCK_DT_SPEC_INST_GET

#define HWSPINLOCK_DT_SPEC_INST_GET

(

inst

)

#include <zephyr/drivers/hwspinlock.h>

Value:

        HWSPINLOCK_DT_SPEC_GET(DT_DRV_INST(inst))

Instance version of HWSPINLOCK_DT_SPEC_GET()

Parameters

inst	DT_DRV_COMPAT instance number

See also

HWSPINLOCK_DT_SPEC_GET()

HWSPINLOCK_DT_SPEC_INST_GET_BY_IDX

#define HWSPINLOCK_DT_SPEC_INST_GET_BY_IDX	(		inst,
			idx )

#include <zephyr/drivers/hwspinlock.h>

Value:

        HWSPINLOCK_DT_SPEC_GET_BY_IDX(DT_DRV_INST(inst), idx)

Instance version of HWSPINLOCK_DT_SPEC_GET_BY_IDX()

Parameters

inst	DT_DRV_COMPAT instance number
idx	Index of the hwlocks element

See also

HWSPINLOCK_DT_SPEC_GET_BY_IDX()

HWSPINLOCK_DT_SPEC_INST_GET_BY_NAME

#define HWSPINLOCK_DT_SPEC_INST_GET_BY_NAME	(		inst,
			name )

#include <zephyr/drivers/hwspinlock.h>

Value:

        HWSPINLOCK_DT_SPEC_GET_BY_NAME(DT_DRV_INST(inst), name)

Instance version of HWSPINLOCK_DT_SPEC_GET_BY_NAME()

Parameters

inst	DT_DRV_COMPAT instance number
name	lowercase-and-underscores name of the hwlocks element

See also

HWSPINLOCK_DT_SPEC_GET_BY_NAME()

Typedef Documentation

hwspinlock_ctx_t

typedef struct hwspinlock_context hwspinlock_ctx_t

#include <zephyr/drivers/hwspinlock.h>

Opaque type to represent a hwspinlock runtime context.

This type is not meant to be inspected by application code.

Function Documentation

hw_spin_lock()

k_spinlock_key_t hw_spin_lock ( const struct device * dev, hwspinlock_ctx_t * ctx, uint32_t id )

inlinestatic

#include <zephyr/drivers/hwspinlock.h>

Lock HW spinlock.

This function is used when locking an HW spinlock. If the spinlock is already locked by another party, waits for it to be released. This is useful when protecting a resource which is shared between multiple clusters.

Note

The goal is not to replace regular spinlocks, but to protect shared resources between clusters. However, because we don't want another thread to take the same HW spinlock twice, the locking mechanism acts as a regular spinlock as well.

Because this uses a regular zephyr spinlock in conjunction with a hwspinlock, the same rules applies. Separate hwspinlock may be nested. It is legal to lock another (unlocked) hwspinlock while holding a lock. However, an attempt to acquire a hwspinlock that the CPU already holds will deadlock.

See also

k_spin_lock

Parameters

dev	HW spinlock device instance.
ctx	HW spinlock runtime context.
id	Spinlock identifier.

Returns

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

hw_spin_lock_dt()

k_spinlock_key_t hw_spin_lock_dt ( struct hwspinlock_dt_spec * spec )

inlinestatic

#include <zephyr/drivers/hwspinlock.h>

Lock HW spinlock from a struct hwspinlock_dt_spec.

This is the dt_spec equivalent of hw_spin_lock()

See also

hw_spin_lock

Parameters

spec	HWSPINLOCK specification from devicetree

Returns

See return values from hw_spin_lock()

hw_spin_trylock()

int hw_spin_trylock ( const struct device * dev, hwspinlock_ctx_t * ctx, uint32_t id, k_spinlock_key_t * key )

inlinestatic

#include <zephyr/drivers/hwspinlock.h>

Try to lock HW spinlock.

This function is used when trying to lock an HW spinlock. If the spinlock is already locked by another cluster, exits with -EBUSY.

See also

hw_spin_lock

Parameters

	dev	HW spinlock device instance.
	ctx	HW spinlock runtime context.
	id	Spinlock identifier.
[out]	key	A pointer to the spinlock key.

Return values

0	On success.
-ENOSYS	If the operation is not implemented.
-EINVAL	If HW spinlock id is invalid.
-EBUSY	If HW spinlock is already locked by someone else.

hw_spin_trylock_dt()

int hw_spin_trylock_dt ( struct hwspinlock_dt_spec * spec, k_spinlock_key_t * key )

inlinestatic

#include <zephyr/drivers/hwspinlock.h>

Try to lock HW spinlock from a struct hwspinlock_dt_spec.

This is the dt_spec equivalent of hw_spin_trylock()

See also

hw_spin_trylock

Parameters

	spec	HWSPINLOCK specification from devicetree
[out]	key	A pointer to the spinlock key.

Returns

See return values from hw_spin_trylock()

hw_spin_unlock()

void hw_spin_unlock ( const struct device * dev, hwspinlock_ctx_t * ctx, uint32_t id, k_spinlock_key_t key )

inlinestatic

#include <zephyr/drivers/hwspinlock.h>

Unlock HW spinlock.

This function to unlock an HW spinlock

Parameters

dev	HW spinlock device instance.
ctx	HW spinlock runtime context.
id	Spinlock identifier.
key	The value returned from hw_spin_lock() when this lock was acquired

hw_spin_unlock_dt()

void hw_spin_unlock_dt ( struct hwspinlock_dt_spec * spec, k_spinlock_key_t key )

inlinestatic

#include <zephyr/drivers/hwspinlock.h>

Unlock HW spinlock from a struct hwspinlock_dt_spec.

This is the dt_spec equivalent of hw_spin_unlock()

See also

hw_spin_unlock

Parameters

spec	HWSPINLOCK specification from devicetree
key	The value returned from hw_spin_lock() when this lock was acquired

hw_spinlock_get_max_id()

uint32_t hw_spinlock_get_max_id ( const struct device * dev )

inlinestatic

#include <zephyr/drivers/hwspinlock.h>

Get HW spinlock max ID.

This function is used to get the HW spinlock maximum ID. It should be called before attempting to lock/unlock a specific HW spinlock.

Parameters

dev	HW spinlock device instance.

Return values

HW	spinlock max ID.

hw_spinlock_get_max_id_dt()

uint32_t hw_spinlock_get_max_id_dt ( struct hwspinlock_dt_spec * spec )

inlinestatic

#include <zephyr/drivers/hwspinlock.h>

Get HW spinlock max ID from a struct hwspinlock_dt_spec.

This is the dt_spec equivalent of hw_spinlock_get_max_id()

See also

hw_spinlock_get_max_id

Parameters

spec	HWSPINLOCK specification from devicetree

Returns

See return values from hw_spinlock_get_max_id()