查看“Hardware spinlock overview”的源代码

This article gives information about the Linux<sup>&reg;</sup> hardware spinlock framework.

It explains how to activate the hardware spinlock framework and, based on examples, how to use it.

==Framework purpose==

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.

==System overview==
[[File:HWSpinlock-overview.png|thumb|center|upright=4|alt=Alternate text|Hardware spinlock framework overview| |link=]]

===Component description===
* '''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_internal_peripheral| 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

===API description===
====Kernel space interface====
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/hwspinlock.txt<ref name="inkern">{{CodeSource | Linux kernel | Documentation/hwspinlock.txt}}, Hardware spinlock 'inkern' API</ref>.

====Driver interface====
Hardware spinlock driver interfaces (registration, operations) are described in the kernel documentation file API for implementors section: Documentation/hwspinlock.txt<ref name="inkern">{{CodeSource | Linux kernel | Documentation/hwspinlock.txt}}, Hardware spinlock 'inkern' API</ref>.

==Configuration==

===Kernel configuration===
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'''

===Device tree configuration===
''Hardware spinlock bindings''<ref name="Hardware Spinlock bindings">{{CodeSource | Linux kernel | Documentation/devicetree/bindings/hwlock/hwlock.txt}}, Linux Foundation, hardware spinlock generic DT bindings</ref> documentation deals with all required or optional hardware spinlock generic DT properties.

Detailed DT configuration for STM32 internal peripherals:
 {{highlight|hsem}}: hwspinlock@4c000000 {
        compatible = "st,stm32-hwspinlock";
        #hwlock-cells = <1>;
 };
 
 foo-client {
       hwlocks = <{{highlight|&hsem}} 0>; {{highlight|/*Client use lock 0*/}}
 };

==How to use the framework==
Typical usage of hardware spinlock by drivers is taken from the kernel documentation file API for a typical usage section: Documentation/hwspinlock.txt<ref name="inkern">{{CodeSource | Linux kernel | Documentation/hwspinlock.txt}}, Hardware spinlock 'inkern' API</ref>.:
<pre>
#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;
}
</pre>

==Source code location==
Source files are located inside kernel Linux.

*'''Hardware spinlock core part''': generic core<ref>{{CodeSource | Linux kernel | drivers/hwspinlock/hwspinlock_core.c | Hardware spinlock framework source - hwspinlock_core.c}} Sources of generic hardware spinlock framework</ref>

*'''STM32 hardware spinlock vendor part''': driver code <ref>{{CodeSource | Linux kernel | drivers/hwspinlock/stm32_hwspinlock.c | STM32 hardware spinlock driver}} Provides all vendor specifics functions</ref>

==References==
<references />

<noinclude>
[[Category:Hardware spinlock|0]]
{{PublicationRequestId | 10250 | 2019-01-11 | PhilipS}}
{{ArticleBasedOnModel | Framework overview article model}}
</noinclude>