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.
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.
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.
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);
An example is provided in examples/app_locks_example that demonstrates basic lock allocation, freeing, acquiring and releasing.
This type represents a hardware lock.
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).
the allocated lock if allocation is successful or the value HWLOCK_NOT_ALLOCATED if not.
Free a hardware lock.
This function frees a given hardware lock and returns it to the hardware pool to be reallocated elsewhere.
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.
Acquire a hardware lock.
This function acquires a lock for the current logical core. If another core holds the lock the function will pause until the lock is released.
lock – the hardware lock to acquire
Release a hardware lock.
This function releases a lock from the current logical core. The lock should have been previously claimed by hwlock_acquire().
lock – the hardware lock to release
Type that represents a software lock
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().
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.
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.
lock – the software lock to acquire.
a value that is equal to SWLOCK_NOT_ACQUIRED if the attempt fails. Any other value indicates that the acquisition has succeeded.
Acquire a software lock.
This function acquires a lock for the current logical core. If another core holds the lock then the function will wait until it becomes available.
lock – the software lock to acquire.
Release a software lock.
This function releases a previously acquired software lock for other cores to use.
lock – the software lock to release.