User mode semaphore APIs

Macros
#define	SYS_SEM_DEFINE(_name, _initial_count, _count_limit)
	Statically define and initialize a sys_sem.
#define	SYS_SEM_LOCK_BREAK   continue
	Leaves a code block guarded with SYS_SEM_LOCK after releasing the lock.
#define	SYS_SEM_LOCK(sem)
	Guards a code block with the given sys_sem, automatically acquiring the semaphore before executing the code block.

Functions
int	sys_sem_init (struct sys_sem *sem, unsigned int initial_count, unsigned int limit)
	Initialize a semaphore.
int	sys_sem_give (struct sys_sem *sem)
	Give a semaphore.
int	sys_sem_take (struct sys_sem *sem, k_timeout_t timeout)
	Take a sys_sem.
unsigned int	sys_sem_count_get (struct sys_sem *sem)
	Get sys_sem's value.

Detailed Description

Macro Definition Documentation

SYS_SEM_DEFINE

#define SYS_SEM_DEFINE	(		_name,
			_initial_count,
			_count_limit )

#include <zephyr/sys/sem.h>

Value:

        struct sys_sem _name = { \
                .futex = { _initial_count }, \
                .limit = _count_limit \
        }; \
        BUILD_ASSERT(((_count_limit) != 0) && \
                     ((_initial_count) <= (_count_limit)))

Statically define and initialize a sys_sem.

The semaphore can be accessed outside the module where it is defined using:

extern struct sys_sem <name>; 

Route this to memory domains using K_APP_DMEM().

Parameters

_name	Name of the semaphore.
_initial_count	Initial semaphore count.
_count_limit	Maximum permitted semaphore count.

SYS_SEM_LOCK

#define SYS_SEM_LOCK

(

sem

)

#include <zephyr/sys/sem.h>

Value:

        for (int __rc SYS_SEM_LOCK_ONEXIT = sys_sem_take((sem), K_FOREVER); ({                     \
                     __ASSERT(__rc >= 0, "Failed to take sem: %d", __rc);                          \
                     __rc == 0;                                                                    \
             });                                                                                   \
             ({                                                                                    \
                     __rc = sys_sem_give((sem));                                                   \
                     __ASSERT(__rc == 0, "Failed to give sem: %d", __rc);                          \
             }),                                                                                   \
                      __rc = 1)

Guards a code block with the given sys_sem, automatically acquiring the semaphore before executing the code block.

The semaphore will be released either when reaching the end of the code block or when leaving the block with SYS_SEM_LOCK_BREAK.

Example usage:

SYS_SEM_LOCK(&sem) {
 
  ...execute statements with the semaphore held...
 
  if (some_condition) {
    ...release the lock and leave the guarded section prematurely:
    SYS_SEM_LOCK_BREAK;
  }
 
  ...execute statements with the lock held...
 
}

Behind the scenes this pattern expands to a for-loop whose body is executed exactly once:

for (sys_sem_take(&sem, K_FOREVER); ...; sys_sem_give(&sem)) {
    ...
}

Warning

The code block must execute to its end or be left by calling SYS_SEM_LOCK_BREAK. Otherwise, e.g. if exiting the block with a break, goto or return statement, the semaphore will not be released on exit.

Parameters

sem	Semaphore (sys_sem) used to guard the enclosed code block.

SYS_SEM_LOCK_BREAK

#define SYS_SEM_LOCK_BREAK   continue

#include <zephyr/sys/sem.h>

Leaves a code block guarded with SYS_SEM_LOCK after releasing the lock.

See SYS_SEM_LOCK for details.

Function Documentation

sys_sem_count_get()

unsigned int sys_sem_count_get

(

struct sys_sem *

sem

)

#include <zephyr/sys/sem.h>

Get sys_sem's value.

This routine returns the current value of sem.

Parameters

sem	Address of the sys_sem.

Returns

Current value of sys_sem.

sys_sem_give()

int sys_sem_give

(

struct sys_sem *

sem

)

#include <zephyr/sys/sem.h>

Give a semaphore.

This routine gives sem, unless the semaphore is already at its maximum permitted count.

Parameters

sem	Address of the semaphore.

Return values

0	Semaphore given.
-EINVAL	Parameter address not recognized.
-EACCES	Caller does not have enough access.
-EAGAIN	Count reached Maximum permitted count and try again.

sys_sem_init()

int sys_sem_init	(	struct sys_sem *	sem,
		unsigned int	initial_count,
		unsigned int	limit )

#include <zephyr/sys/sem.h>

Initialize a semaphore.

This routine initializes a semaphore instance, prior to its first use.

Parameters

sem	Address of the semaphore.
initial_count	Initial semaphore count.
limit	Maximum permitted semaphore count.

Return values

0	Initial success.
-EINVAL	Bad parameters, the value of limit should be located in (0, INT_MAX] and initial_count shouldn't be greater than limit.

sys_sem_take()

int sys_sem_take	(	struct sys_sem *	sem,
		k_timeout_t	timeout )

#include <zephyr/sys/sem.h>

Take a sys_sem.

This routine takes sem.

Parameters

sem	Address of the sys_sem.
timeout	Waiting period to take the sys_sem, or one of the special values K_NO_WAIT and K_FOREVER.

Return values

0	sys_sem taken.
-EINVAL	Parameter address not recognized.
-ETIMEDOUT	Waiting period timed out.
-EACCES	Caller does not have enough access.