Lock handling Module

This module provides access to hardware and software locks for use in concurrent C programs. In general it is not safe to use these to marshal 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 is a limited number of them per tile. Software locks are slower but you can use an unlimited number of them.

This module was originally obtained from XMOS public repositories and still today it is maintained by XMOS.

Note

This module is internally used by certain SOMANET Libraries. Its use is only recommended to advanced users. You will find a demo app for this module at XMOS public repositories.

Hardware lock API

hwlock_t

This type represents a hardware lock.

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 if not.
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.
void hwlock_acquire(hwlock_t lock)

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.

Parameters:
  • lock – the hardware lock to acquire
void hwlock_release(hwlock_t lock)

Release a hardware lock.

This function releases a lock from the current logical core. The lock should have been previously claimed by hwlock_acquire().

Parameters:
  • lock – the hardware lock to release

Software lock API

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(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(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 if the attempt fails. Any other value indicates that the acquisition has succeeded.

void swlock_acquire(swlock_t &lock)

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.

Parameters:
  • lock – the software lock to acquire.
void swlock_release(swlock_t &lock)

Release a software lock.

This function releases a previously acquired software lock for other cores to use.

Parameters:
  • lock – the software lock to release.