Semaphore APIs

Macros
#define	K_SEM_MAX_LIMIT   UINT_MAX
	Maximum limit value allowed for a semaphore.
#define	K_SEM_DEFINE(name, initial_count, count_limit)
	Statically define and initialize a semaphore.

Functions
int	k_sem_init (struct k_sem *sem, unsigned int initial_count, unsigned int limit)
	Initialize a semaphore.
int	k_sem_take (struct k_sem *sem, k_timeout_t timeout)
	Take a semaphore.
void	k_sem_give (struct k_sem *sem)
	Give a semaphore.
void	k_sem_reset (struct k_sem *sem)
	Resets a semaphore's count to zero.
unsigned int	k_sem_count_get (struct k_sem *sem)
	Get a semaphore's count.

Detailed Description

Macro Definition Documentation

K_SEM_DEFINE

#define K_SEM_DEFINE	(		name,
			initial_count,
			count_limit
	)

#include <zephyr/kernel.h>

Value:

        STRUCT_SECTION_ITERABLE(k_sem, name) = \
                Z_SEM_INITIALIZER(name, initial_count, count_limit); \
        BUILD_ASSERT(((count_limit) != 0) && \
                     ((initial_count) <= (count_limit)) && \
                         ((count_limit) <= K_SEM_MAX_LIMIT));

Statically define and initialize a semaphore.

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

extern struct k_sem <name>; 

Parameters

name	Name of the semaphore.
initial_count	Initial semaphore count.
count_limit	Maximum permitted semaphore count.

K_SEM_MAX_LIMIT

#define K_SEM_MAX_LIMIT   UINT_MAX

#include <zephyr/kernel.h>

Maximum limit value allowed for a semaphore.

This is intended for use when a semaphore does not have an explicit maximum limit, and instead is just used for counting purposes.

Function Documentation

k_sem_count_get()

unsigned int k_sem_count_get

(

struct k_sem *

sem

)

#include <zephyr/kernel.h>

Get a semaphore's count.

This routine returns the current count of sem.

Parameters

sem	Address of the semaphore.

Returns

Current semaphore count.

k_sem_give()

void k_sem_give

(

struct k_sem *

sem

)

#include <zephyr/kernel.h>

Give a semaphore.

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

Function properties (list may not be complete)

isr-ok

Parameters

sem	Address of the semaphore.

k_sem_init()

int k_sem_init	(	struct k_sem *	sem,
		unsigned int	initial_count,
		unsigned int	limit
	)

#include <zephyr/kernel.h>

Initialize a semaphore.

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

Parameters

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

See also

K_SEM_MAX_LIMIT

Return values

0	Semaphore created successfully
-EINVAL	Invalid values

k_sem_reset()

void k_sem_reset

(

struct k_sem *

sem

)

#include <zephyr/kernel.h>

Resets a semaphore's count to zero.

This routine sets the count of sem to zero. Any outstanding semaphore takes will be aborted with -EAGAIN.

Parameters

sem	Address of the semaphore.

k_sem_take()

int k_sem_take	(	struct k_sem *	sem,
		k_timeout_t	timeout
	)

#include <zephyr/kernel.h>

Take a semaphore.

This routine takes sem.

Note

timeout must be set to K_NO_WAIT if called from ISR.

Function properties (list may not be complete)

isr-ok

Parameters

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

Return values

0	Semaphore taken.
-EBUSY	Returned without waiting.
-EAGAIN	Waiting period timed out, or the semaphore was reset during the waiting period.