sem.h

Defines

EMB_SEM_COUNT_MAX
EMB_SEM_SATURATE

Typedefs

typedef union emb_sem_storage emb_sem_storage_t
typedef uint32_t emb_sem_count_t
typedef struct emb_sem_attr emb_sem_attr_t

Functions

void emb_sem_attr_default(emb_sem_attr_t *out_attr)

emb_sem_attr_default()

- Fill counting semaphore attributes with defaults.

Context: thread isr prekernel Blocking: no Timing: O(1) Ownership: none Configuration: CONFIG_EMB_SEM Requirements: API-020 KRN-SYNC-028 Since: 0.2 Stability: yes

Parameters:

  • out_attr – Receives name NULL, initial 0, max EMB_SEM_COUNT_MAX and flags 0; NULL is a no-op.

void emb_sem_attr_binary(emb_sem_attr_t *out_attr, bool initially_available)

emb_sem_attr_binary()

- Attributes of a binary semaphore: max 1, EMB_SEM_SATURATE.

Context: thread isr prekernel Blocking: no Timing: O(1) Ownership: none Configuration: CONFIG_EMB_SEM Requirements: API-020 KRN-SYNC-028 Since: 0.2 Stability: yes

Parameters:

  • out_attr – Receives max 1 and EMB_SEM_SATURATE; NULL is a no-op.

  • initially_available – True starts at 1, false at 0.

emb_status_t emb_sem_init(emb_sem_storage_t *storage, const emb_sem_attr_t *attr, emb_sem_t *out_sem)

emb_sem_init()

- Construct a semaphore in caller-provided storage.

Context: prekernel thread Blocking: no Timing: O(1) Ownership: borrows:storage Configuration: CONFIG_EMB_SEM Requirements: API-021 KRN-SYNC-028 KRN-OBJ-003 Since: 0.2 Stability: yes

Return: EMB_OK; EMB_EINVAL for bad storage/output, max == 0 or initial > max.

Parameters:

  • storage – Aligned caller-owned storage; retain it until successful destruction.

  • attr – Copied attributes; NULL selects defaults. Keep name storage alive.

  • out_sem – Required output handle; cleared before argument validation.

emb_status_t emb_sem_destroy(emb_sem_t sem)

emb_sem_destroy()

- End the semaphore (KRN-OBJ-001).

Context: thread Blocking: no Timing: O(waiters) with EMB_OBJ_ABORT_WAITERS Ownership: gives:storage Configuration: CONFIG_EMB_SEM Requirements: KRN-OBJ-001 Since: 0.2 Stability: yes

Return: EMB_OK; EMB_EBUSY with waiters and no ABORT_WAITERS (misuse).

Parameters:

  • sem – Initialized semaphore; no live waiters unless ABORT_WAITERS is set.

emb_status_t emb_sem_take(emb_sem_t sem, emb_timeout_t timeout)

emb_sem_take() - Take one unit, waiting up to timeout

.

Context: thread Blocking: timeout Timing: O(1) fast path; O(waiters + timeouts) finite wait enqueue Ownership: none Configuration: CONFIG_EMB_SEM Requirements: KRN-SYNC-028 KRN-WAIT-012 Since: 0.2 Stability: yes

Return: EMB_OK; EMB_ETIMEDOUT; EMB_ECANCELED; EMB_EDESTROYED; EMB_EINVAL; EMB_EPERM.

Parameters:

  • sem – Initialized semaphore to consume.

  • timeout – EMB_NO_WAIT, EMB_WAIT_FOREVER or EMB_TIMEOUT(duration); this is thread-only.

emb_status_t emb_sem_take_until(emb_sem_t sem, emb_instant_t deadline)

emb_sem_take_until()

- Take one unit with an absolute deadline.

Context: thread Blocking: timeout Timing: O(1) fast path; O(waiters + timeouts) finite wait enqueue Ownership: none Configuration: CONFIG_EMB_SEM Requirements: API-024 KRN-TIM-011 KRN-SYNC-028 Since: 0.2 Stability: yes

Return: the same statuses as emb_sem_take(). EMB_TICK_MAX is the current internal forever sentinel. Keep 32-bit deadlines within the signed half-range window (SPEC-003 §5.2).

Parameters:

  • sem – Initialized semaphore to consume.

  • deadline – Kernel-clock deadline; a past deadline attempts a take without waiting.

emb_status_t emb_sem_give(emb_sem_t sem)

emb_sem_give()

- Give one unit: hand it to the first waiter, else count it.

Context: thread isr Blocking: no Timing: O(1) count/selection, plus profile-specific timeout removal and scheduling Ownership: none Configuration: CONFIG_EMB_SEM Requirements: KRN-SYNC-005 KRN-SYNC-028 KRN-IRQ-033 Since: 0.2 Stability: yes

Return: EMB_OK; EMB_EOVERFLOW at max without EMB_SEM_SATURATE; EMB_EINVAL.

Parameters:

  • sem – Initialized semaphore to signal; a waiting thread receives the unit directly.

emb_sem_count_t emb_sem_count(emb_sem_t sem)

emb_sem_count()

- Snapshot of the count; 0 for a bad handle.

Context: thread isr Blocking: no Timing: O(1) Ownership: none Configuration: CONFIG_EMB_SEM Requirements: KRN-SYNC-028 Since: 0.2 Stability: yes

Parameters:

  • sem – Initialized semaphore to inspect; the returned count is a snapshot, not a reservation.

emb_status_t emb_sem_bind_notify(emb_sem_t sem, emb_thread_t thread, emb_notify_bits_t bit)

emb_sem_bind_notify() - Set bit in thread

when the count goes from 0 to 1 (ADR-027).

Context: prekernel thread Blocking: no Timing: O(1) Ownership: none Configuration: CONFIG_EMB_SEM CONFIG_EMB_NOTIFY Requirements: KRN-SYNC-035 KRN-NOTIF-005 KRN-NOTIF-009 Since: 0.2 Stability: yes

Return: EMB_OK; EMB_EEXIST when already bound; EMB_EINVAL for bad handles, a zero/multi-bit mask or a kernel bit. Binding does not signal an already-positive count: inspect/drain initial readiness before waiting. Keep the target thread alive until the semaphore is destroyed.

Parameters:

  • sem – Initialized semaphore with no existing binding.

  • thread – Initialized target retained for the entire binding lifetime; no unbind API exists yet.

  • bit – One application-bit mask, e.g. EMB_NOTIFY_BIT(0), not a bit index.

struct emb_sem_t
#include <sem.h>

Public Members

uintptr_t raw
struct emb_sem_attr
#include <sem.h>

Public Members

const char *name
emb_sem_count_t initial
emb_sem_count_t max
uint8_t flags
uint8_t reserved_[3]