Semaphores

Counting semaphores; a binary semaphore has limit 1. More...

Data Structures
struct	pbl_sem
	Counting semaphore. More...

Macros
#define	PBL_SEM_INITIALIZER(init, lim)    {.initial = (init), .limit = (lim), .backend = PBL_SEM_BACKEND_INITIALIZER(init)}
	Static initializer for a semaphore.
#define	PBL_SEM_DEFINE(name, initial, limit)    struct pbl_sem name = PBL_SEM_INITIALIZER(initial, limit)
	Define a semaphore, usable without pbl_sem_init().

Functions
void	pbl_sem_init (struct pbl_sem *s, uint32_t initial, uint32_t limit)
	Initialize a semaphore in dynamically allocated memory.
void	pbl_sem_deinit (struct pbl_sem *s)
	Release a semaphore before its memory is reused.
int	pbl_sem_take (struct pbl_sem *s, pbl_timeout_t timeout)
	Take a token.
void	pbl_sem_give (struct pbl_sem *s)
	Give a token.
void	pbl_sem_reset (struct pbl_sem *s)
	Set the count back to its initial value.
uint32_t	pbl_sem_count (const struct pbl_sem *s)
	Get the current count.

Detailed Description

Counting semaphores; a binary semaphore has limit 1.

A give hands the token directly to the highest priority waiter, so a woken taker never finds the count stolen. Both operations may be called from ISRs; an ISR never blocks and gets -EBUSY when no token is available.

Signalling a thread from an interrupt:

static PBL_SEM_DEFINE(s_done, 0, 1);
 
static void prv_dma_isr(void) {
  pbl_sem_give(&s_done);
}
 
int transfer(void) {
  prv_dma_start();
  if (pbl_sem_take(&s_done, PBL_MSEC(100)) != 0) {
    prv_dma_abort();
    return -ETIMEDOUT;
  }
  return 0;
}

---

Data Structure Documentation

pbl_sem

struct pbl_sem

Counting semaphore.

Usable from ISRs with PBL_NO_WAIT.

Data Fields
struct pbl_sem_backend	backend	Backend state, including the current count.
uint32_t	initial	Count restored by pbl_sem_reset().
uint32_t	limit	Maximum count; gives beyond it are dropped.

Macro Definition Documentation

PBL_SEM_DEFINE

#define PBL_SEM_DEFINE	(		name,
			initial,
			limit
	)		struct pbl_sem name = PBL_SEM_INITIALIZER(initial, limit)

Define a semaphore, usable without pbl_sem_init().

Parameters

name	Name of the semaphore variable.
initial	Initial count.
limit	Maximum count.

PBL_SEM_INITIALIZER

#define PBL_SEM_INITIALIZER	(		init,
			lim
	)		{.initial = (init), .limit = (lim), .backend = PBL_SEM_BACKEND_INITIALIZER(init)}

Static initializer for a semaphore.

Parameters

init	Initial count.
lim	Maximum count.

Function Documentation

pbl_sem_count()

uint32_t pbl_sem_count

(

const struct pbl_sem *

s

)

Get the current count.

Parameters

s	Semaphore.

Returns

Tokens available.

pbl_sem_deinit()

void pbl_sem_deinit

(

struct pbl_sem *

s

)

Release a semaphore before its memory is reused.

Required for dynamically allocated semaphores.

Parameters

s	Semaphore.

pbl_sem_give()

void pbl_sem_give

(

struct pbl_sem *

s

)

Give a token.

Wakes the highest priority waiter, or increments the count up to the limit. ISR-safe.

Parameters

s	Semaphore.

pbl_sem_init()

void pbl_sem_init	(	struct pbl_sem *	s,
		uint32_t	initial,
		uint32_t	limit
	)

Initialize a semaphore in dynamically allocated memory.

Parameters

[out]	s	Semaphore.
	initial	Initial count, at most limit.
	limit	Maximum count, at least 1.

pbl_sem_reset()

void pbl_sem_reset

(

struct pbl_sem *

s

)

Set the count back to its initial value.

Waiters are not woken.

Parameters

s	Semaphore.

pbl_sem_take()

int pbl_sem_take	(	struct pbl_sem *	s,
		pbl_timeout_t	timeout
	)

Take a token.

Parameters

s	Semaphore.
timeout	How long to wait for a token; ignored in an ISR, which never waits.

Return values

0	Token taken.
-EAGAIN	Timed out.
-EBUSY	No token and timeout is PBL_NO_WAIT, or called from an ISR.
-EINTR	The thread was suspended while waiting.