Zephyr API Documentation 4.0.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
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)))
sys_sem structure
Definition sem.h:35

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
_nameName of the semaphore.
_initial_countInitial semaphore count.
_count_limitMaximum 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)
#define K_FOREVER
Generate infinite timeout delay.
Definition kernel.h:1446
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.

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:
}
...execute statements with the lock held...
}
#define SYS_SEM_LOCK_BREAK
Leaves a code block guarded with SYS_SEM_LOCK after releasing the lock.
Definition sem.h:167
#define SYS_SEM_LOCK(sem)
Guards a code block with the given sys_sem, automatically acquiring the semaphore before executing th...
Definition sem.h:207

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
semSemaphore (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
semAddress 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
semAddress of the semaphore.
Return values
0Semaphore given.
-EINVALParameter address not recognized.
-EACCESCaller does not have enough access.
-EAGAINCount 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
semAddress of the semaphore.
initial_countInitial semaphore count.
limitMaximum permitted semaphore count.
Return values
0Initial success.
-EINVALBad 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
semAddress of the sys_sem.
timeoutWaiting period to take the sys_sem, or one of the special values K_NO_WAIT and K_FOREVER.
Return values
0sys_sem taken.
-EINVALParameter address not recognized.
-ETIMEDOUTWaiting period timed out.
-EACCESCaller does not have enough access.