lib_locks: Lock handling library#
Introduction#
This library provides access to hardware and software locks for use in concurrent C programs. In general it is not safe to use these to marshall within XC due to the assumptions XC makes about safe concurrent data access.
Two types of locks are provided. Hardware locks are fast and power efficient but there are a limited number per tile. Software locks are slower but you can use an unlimited number of them.
lib_locks is intended to be used with the XCommon CMake
, the XMOS application build and dependency management system.
Basic use#
Declaration & allocation#
Before using a lock it first must be declared.
Software based locks should be initialised to a specific value:
swlock_t swlock = SWLOCK_INITIAL_VALUE;
Hardware locks relate to a physical resource in the device and so need to be properly allocated:
hwlock_t hwlock;
hwlock = hwlock_alloc();
Locks are typically used to protect critical sections of code when multiple threads are involved, so they are often declared globally for shared access.
Acquisition and release#
Hardware and software based locks use a similar API for acquisition and release. For software based locks the following is used:
swlock_acquire(&swlock);
// Perform critical code section..
swlock_release(&swlock);
Similarly, for hardware based locks:
hwlock_acquire(&hwlock);
// Perform critical code section..
hwlock_release(&hwlock);
In all cases these are blocking calls.
Freeing#
Once an application no longer requires a hardware lock it should be freed to allow the underlying hardware resource to be reused:
hwlock_free(hwlock);
Example application#
An example is provided in examples/app_locks_example that demonstrates basic lock allocation, freeing, acquiring and releasing.
Hardware lock API#
-
typedef unsigned hwlock_t#
This type represents a hardware lock.
-
inline hwlock_t hwlock_alloc(void)#
Allocate a hardware lock.
This function will allocate a new hardware lock from the pool of hardware locks available on the xCORE. The hardware has a limited number of hardware locks (for example, current L and S series devices have 4 locks per tile).
- Returns:
the allocated lock if allocation is successful or the value
HWLOCK_NOT_ALLOCATEDif not.
-
inline void hwlock_free(hwlock_t lock)#
Free a hardware lock.
This function frees a given hardware lock and returns it to the hardware pool to be reallocated elsewhere.
- Parameters:
lock – the hardware lock to be freed. If this is an invalid lock id or not an currently allocated lock then the function will trap.
Software lock API#
-
typedef unsigned swlock_t#
Type that represents a software lock
-
SWLOCK_INITIAL_VALUE#
This define should be used to initialize a software lock e.g.
swlock_t my_lock = SWLOCK_INITIAL_VALUE;
If you intialize this way there is no need to call swlock_init().
-
void swlock_init(REFERENCE_PARAM(swlock_t, lock))#
Initialize a software lock.
This function will initialize a software lock for use. Note that unlike hardware locks, there is no need to allocate or free a software lock from a limited pool.
-
int swlock_try_acquire(REFERENCE_PARAM(swlock_t, lock))#
Try and acquire a software lock.
This function tries to acquire a lock for the current logical core. If another core holds the lock then the function will fail and return.
- Parameters:
lock – the software lock to acquire.
- Returns:
a value that is equal to
SWLOCK_NOT_ACQUIREDif the attempt fails. Any other value indicates that the acquisition has succeeded.