This article gives information about the Linux® hardware spinlock framework.
It explains how to activate the hardware spinlock framework and, based on examples, how to use it.
1. Framework purpose[edit source]
Hardware spinlock modules provide hardware assistance for synchronization and mutual exclusion between heterogeneous processors and those not operating under a single, shared operating system.
A generic hardware spinlock framework allows platform-independent drivers to use the hardware spinlock device in order to access data structures that are shared between processors, that otherwise have no alternative mechanism to accomplish synchronization and mutual exclusion operations.
2. System overview[edit source]
2.1. Component description[edit source]
- Hardware spinlock:. The role of this framework is to:
- provide an API to other drivers
- call specific vendor callbacks to perform lock and unlock operations
- stm32-hwspinlock microprocessor specific hardware spinlock driver. The role of this driver is to:
- register vendor-specific functions (callback) to the hardware spinlock framework
- access HSEM peripheral registers to perform lock and unlock operations
- Client driver
- Client driver could be any driver that needs to use hardware spinlock to protect a critical section of code
2.2. API description[edit source]
2.2.1. Kernel space interface[edit source]
Kernel drivers can be clients of the hardware spinlock framework and can request, lock, unlock and free a hardware spinlock.
Client functions are described in kernel documentation file user API section: Documentation/locking/hwspinlock.rst[1].
2.2.2. Driver interface[edit source]
Hardware spinlock driver interfaces (registration, operations) are described in the kernel documentation file API for implementors section: Documentation/locking/hwspinlock.rst[1].
3. Configuration[edit source]
3.1. Kernel configuration[edit source]
Hardware spinlock is activated by default in ST deliveries. Nevertheless, if a specific configuration is needed, this section indicates how hardware spinlock can be activated/deactivated in the kernel.
Activate hardware spinlock in the kernel configuration using the Linux Menuconfig tool: Menuconfig or how to configure kernel
Device Drivers --->
<*> Hardware Spinlock drivers--->
<*> STM32 Hardware Spinlock device
3.2. Device tree configuration[edit source]
Please refer to the HSEM device tree configuration.
4. How to use the framework[edit source]
Typical usage of hardware spinlock by drivers is taken from the kernel documentation file API for a typical usage section: Documentation/locking/hwspinlock.rst[1].:
#include <linux/hwspinlock.h>
#include <linux/err.h>
int hwspinlock_example1(void)
{
struct hwspinlock *hwlock;
int ret;
/* dynamically assign a hwspinlock without device tree usage*/
hwlock = hwspin_lock_request();
if (!hwlock)
...
id = hwspin_lock_get_id(hwlock);
/* probably need to communicate id to a remote processor now */
/* take the lock, spin for 1 sec if it's already taken */
ret = hwspin_lock_timeout(hwlock, 1000);
if (ret)
...
/*
* we took the lock, do our thing now, but do NOT sleep
*/
/* release the lock */
hwspin_unlock(hwlock);
/* free the lock */
ret = hwspin_lock_free(hwlock);
if (ret)
...
return ret;
}
5. How to trace and debug the framework[edit source]
5.1. How to monitor[edit source]
This framework does not provide with any way to monitor the hwspinlock usage.
5.2. How to trace[edit source]
This framework does not provide with any convenient way to get traces. To get traces, add some printk logs in the code and rebuild the kernel:
- to log how the users get a reference to a hwspinlock: add some printk in hwspin_lock_request_specific (file : hwspinlock_core.c).
- to log how the users lock / unlock a hwspinlock: add some printk in stm32_hwspinlock_trylock/unlock (file : stm32_hwspinlock.c). Be aware that PINCTRL locks an hwspinlock every time it configures an IO. Hence, when tracing lock / unlock, the log buffer is flooded with these trace logs.
5.3. How to debug[edit source]
There is no specific way to debug this framework. Nevertheless, below are some possible issues you may face:
- a user driver outputs the error log Failed to request hwspinlock or Failed to get hwspinlock : this means that the user failed in getting a reference to an hwspinlock. In that case, check the DeviceTree declaration, it may be wrong.
- a user driver outputs the error log Can't get hwspinlock : this means that a hwspinlock is kept locked by a remote processor, or that the hwspinlock driver is not clocked. In that case, check the remote processor firmware code and check the hwspinlock probe success.
6. Source code location[edit source]
Source files are located inside kernel Linux.
- Hardware spinlock core part: generic core[2]
- STM32 hardware spinlock vendor part: driver code [3]
7. References[edit source]
- ↑ 1.0 1.1 1.2 Documentation/locking/hwspinlock.rst , Hardware spinlock 'inkern' API
- ↑ Hardware spinlock framework source - hwspinlock_core.c Sources of generic hardware spinlock framework
- ↑ STM32 hardware spinlock driver Provides all vendor specifics functions