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)) || ((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 )

isr-ok

#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)

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 )

isr-ok

#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)

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.