Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
Toggle table of contents sidebar

# lib_locks: Locks for concurrency

## 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_ALLOCATED` if 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.

inline 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

inline 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

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

void swlock_acquire(REFERENCE_PARAM(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(REFERENCE_PARAM(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.