= The user_lock library =

[[PageOutline]]

The [source:soft/giet_vm/giet_libs/user_lock.c user_lock.c] and [source:soft/giet_vm/giet_libs/user_lock.h user_lock.h] 
files define two types of services:
 * user-level atomic access functions, to increment a shared counter.
 * user-level spin-locks, to obtain exclusive access to a shared resource in a parallel multi-tasks application.
The proposed spin-lock implement a waiting queue service, to enforce fairness and avoid live-lock situations.
Each lock (giet_lock_t object) occupies a complete 64 bytes cache line to avoid false sharing.

 == Lock placement ==

The lock being shared by several tasks, should be defined as a global variable of type '''user_lock_t''' in the application code.
It is possible to control precisely the placement of a specific lock by defining a specific vseg in the application mapping. 

 == Access functions ==

 === unsigned int '''atomic_increment'''( unsigned int* shared, unsigned int increment) ===
This function uses a LL/SC to atomically increment a shared variable.
 * '''shared''' : pointer on the shared variable
 * '''increment''' : increment value.

 === '''void lock_init'''( user_lock_t * lock ) ===
This function should be called by one single task.
 * '''lock''' : pointer on the user_lock_t structure.

 === '''void lock_acquire'''( giet_lock_t * lock ) ===
This blocking function returns only when the lock has been successfully taken.
 * '''lock''' : pointer on the user_lock_t structure.

 === '''void lock_release'''( giet_lock_t * lock ) ===
This function releases the lock. It must be called by a task after a successful lock_acquire().
 * '''lock''' : pointer on the user_lock_t structure.