freertos.h File Reference

Per-object static FreeRTOS storage and optional thin services. More...

#include "FreeRTOS.h"
#include "nexus/core/time.h"
#include "nexus/os/wait.h"
#include "queue.h"
#include "semphr.h"
#include "task.h"

Go to the source code of this file.

Data Structures
struct	nx_freertos_notify_t
	Static binary latch; one waiter, independently quiesced publishers. More...
struct	nx_freertos_task_t
	Task has its own TCB; stack is supplied with its actual word count. More...
struct	nx_freertos_queue_t
	Queue control only; actual depth/item byte storage is external. More...
struct	nx_freertos_direct_notify_t
	Fixed receiver and exclusive kernel notification slot; no latch. More...
struct	nx_freertos_permanent_task_t
	Permanent task control without a join completion semaphore. More...
struct	nx_freertos_queue_waiter
	Caller-owned single-operation latch for a closable queue. More...
struct	nx_freertos_closable_queue_t
	Opt-in close broadcasts; raw queue storage remains unchanged. More...

Typedefs
typedef struct nx_freertos_queue_waiter	nx_freertos_queue_waiter_t
	Caller-owned single-operation latch for a closable queue.

Functions
bool	nx_freertos_isr_allowed (void)
	Test whether the current context may call kernel ISR APIs.
nx_result_t	nx_freertos_notify_init (nx_freertos_notify_t *notification)
	Initialize unused notification storage.
nx_wait_port_t	nx_freertos_notify_port (nx_freertos_notify_t *notification)
	Bind a latched single-waiter notification.
nx_result_t	nx_freertos_notify_destroy (nx_freertos_notify_t *notification)
	Destroy after publishers and waiter have stopped and joined.
nx_result_t	nx_freertos_task_start (nx_freertos_task_t *task, const char *name, StackType_t *stack, size_t stack_words, UBaseType_t priority, void(*entry)(void *), void *context)
	Create one task from its exact caller-owned stack and TCB.
nx_result_t	nx_freertos_task_discard_before_scheduler (nx_freertos_task_t *task)
	Discard one created task before its wrapper has executed.
nx_result_t	nx_freertos_task_join (nx_freertos_task_t *task, nx_time_us_t deadline)
	Join a cooperatively returned task and reclaim kernel state.
nx_result_t	nx_freertos_queue_init (nx_freertos_queue_t *queue, uint8_t *storage, size_t storage_bytes, size_t depth, size_t item_size)
	Create an exact-sized static byte-copy queue.
nx_result_t	nx_freertos_queue_send (nx_freertos_queue_t *queue, const void *item, TickType_t wait_ticks)
	Copy an item with a bounded relative kernel wait.
nx_result_t	nx_freertos_queue_receive (nx_freertos_queue_t *queue, void *item, TickType_t wait_ticks)
	Receive one byte-copy item.
nx_result_t	nx_freertos_queue_destroy (nx_freertos_queue_t *queue)
	Destroy after admission is stopped and all users joined.
nx_result_t	nx_freertos_queue_send_until (nx_freertos_queue_t *queue, const void *item, nx_time_us_t deadline)
	Send using one absolute monotonic deadline.
nx_result_t	nx_freertos_queue_receive_until (nx_freertos_queue_t *queue, void *item, nx_time_us_t deadline)
	Receive using one absolute monotonic deadline.
nx_result_t	nx_freertos_direct_notify_init (nx_freertos_direct_notify_t *notification, TaskHandle_t receiver, UBaseType_t index)
	Bind an exclusive slot of one live receiver task.
nx_wait_port_t	nx_freertos_direct_notify_port (nx_freertos_direct_notify_t *notification)
	Get a direct notification wait port.
nx_result_t	nx_freertos_direct_notify_destroy (nx_freertos_direct_notify_t *notification)
	Unbind after all publishers stop and join.
nx_result_t	nx_freertos_permanent_task_start (nx_freertos_permanent_task_t *task, const char *name, StackType_t *stack, size_t stack_words, UBaseType_t priority, void(*entry)(void *), void *context)
	Start a task whose entry must never return.
nx_result_t	nx_freertos_queue_waiter_init (nx_freertos_queue_waiter_t *waiter)
	Initialize one exact caller-owned queue waiter.
nx_result_t	nx_freertos_queue_waiter_destroy (nx_freertos_queue_waiter_t *waiter)
	Destroy only after all operations stop and join.
nx_result_t	nx_freertos_closable_queue_init (nx_freertos_closable_queue_t *queue, uint8_t *storage, size_t storage_bytes, size_t depth, size_t item_size, size_t maximum_waiters)
	Initialize an optional reliably closable byte-copy queue.
nx_result_t	nx_freertos_closable_queue_send_until (nx_freertos_closable_queue_t *queue, const void *item, nx_time_us_t deadline, nx_freertos_queue_waiter_t *waiter)
	Send with close-aware admission and absolute deadline.
nx_result_t	nx_freertos_closable_queue_receive_until (nx_freertos_closable_queue_t *queue, void *item, nx_time_us_t deadline, nx_freertos_queue_waiter_t *waiter)
	Receive existing items after close, then CANCELLED.
nx_result_t	nx_freertos_closable_queue_close (nx_freertos_closable_queue_t *queue)
	Stop sends and wake every currently registered waiter.
nx_result_t	nx_freertos_closable_queue_destroy (nx_freertos_closable_queue_t *queue)
	Destroy a closed, drained and quiesced queue.

Detailed Description

Per-object static FreeRTOS storage and optional thin services.

Author

Nexus Team

Note

Running task operations require privileged unmasked Thread mode; IRQ wake has its own contract. Before scheduler start, the selected Baseline port may retain PRIMASK=1 or the Mainline port its exact syscall BASEPRI; all other masks must be zero. Matching a value cannot prove mask provenance. Unsafe contexts return CONTEXT before mutating kernel APIs or object storage; a scheduler-state read may be needed. Startup permits init, task creation, wake and zero-wait queues. Wait, join and nonzero waits require a running scheduler. Port binding and sequence snapshots remain reads. MPU user-task gateways and cross-world secure task calls are outside these privileged, current-security-domain APIs.

Definition in file freertos.h.

Typedef Documentation

nx_freertos_queue_waiter_t

typedef struct nx_freertos_queue_waiter nx_freertos_queue_waiter_t

Caller-owned single-operation latch for a closable queue.

Function Documentation

nx_freertos_closable_queue_close()

nx_result_t nx_freertos_closable_queue_close

(

nx_freertos_closable_queue_t *

queue

)

Stop sends and wake every currently registered waiter.

Parameters

[in,out]

queue

Live queue

Returns

SUCCESS, including repeated close, or validation/context

Note

Task-only, no forced cancellation or task deletion. Close does not join users or authorize storage reclamation.

nx_freertos_closable_queue_destroy()

nx_result_t nx_freertos_closable_queue_destroy

(

nx_freertos_closable_queue_t *

queue

)

Destroy a closed, drained and quiesced queue.

Parameters

[in,out]

queue

Live queue without future entrants

Returns

SUCCESS, BUSY while open/users/items remain, or error

Note

Stop/join producers, drain with owner, join consumers and then destroy queue and every waiter independently.

nx_freertos_closable_queue_init()

nx_result_t nx_freertos_closable_queue_init	(	nx_freertos_closable_queue_t *	queue,
		uint8_t *	storage,
		size_t	storage_bytes,
		size_t	depth,
		size_t	item_size,
		size_t	maximum_waiters )

Initialize an optional reliably closable byte-copy queue.

Parameters

[out]	queue	Zeroed control kept until destroy
[in]	storage	Payload buffer kept until destroy
[in]	storage_bytes	Actual payload capacity
[in]	depth	Positive item count
[in]	item_size	Positive byte-copy size
[in]	maximum_waiters	Explicit positive simultaneous-call budget

Returns

SUCCESS or validation/context/start error

Note

No hidden worker or waiter pool. Each concurrent blocking operation supplies its own initialized waiter. Broadcasting pauses scheduling while visiting at most maximum_waiters latches. Kernel payload copies and each latch signal have their own short IRQ guards. Budget scheduling delay and IRQ latency separately. Large payloads should queue stable handles. The registry is single-core and task-only.

nx_freertos_closable_queue_receive_until()

nx_result_t nx_freertos_closable_queue_receive_until	(	nx_freertos_closable_queue_t *	queue,
		void *	item,
		nx_time_us_t	deadline,
		nx_freertos_queue_waiter_t *	waiter )

Receive existing items after close, then CANCELLED.

Parameters

[in,out]	queue	Live closable queue
[out]	item	Configured bytes valid only on SUCCESS
[in]	deadline	nx_time_now_us domain
[in,out]	waiter	Exclusive initialized caller waiter

Returns

SUCCESS, CANCELLED when closed/empty, TIMEOUT or error

nx_freertos_closable_queue_send_until()

nx_result_t nx_freertos_closable_queue_send_until	(	nx_freertos_closable_queue_t *	queue,
		const void *	item,
		nx_time_us_t	deadline,
		nx_freertos_queue_waiter_t *	waiter )

Send with close-aware admission and absolute deadline.

Parameters

[in,out]	queue	Live closable queue
[in]	item	Bytes borrowed until return, never after timeout
[in]	deadline	nx_time_now_us domain, NEVER supported
[in,out]	waiter	Exclusive initialized caller waiter

Returns

SUCCESS, CANCELLED after close, TIMEOUT, BUSY or error

Note

Readiness/admission and close serialize in a kernel task scheduling guard. A latched wake closes wake-before-sleep.

nx_freertos_direct_notify_destroy()

nx_result_t nx_freertos_direct_notify_destroy

(

nx_freertos_direct_notify_t *

notification

)

Unbind after all publishers stop and join.

Parameters

[in,out]

notification

Live storage with no future users

Returns

SUCCESS, BUSY if waiting, or validation/context error

Note

Does not delete receiver or clear its kernel slot. Receiver and storage must outlive every retained port and publisher.

nx_freertos_direct_notify_init()

nx_result_t nx_freertos_direct_notify_init	(	nx_freertos_direct_notify_t *	notification,
		TaskHandle_t	receiver,
		UBaseType_t	index )

Bind an exclusive slot of one live receiver task.

Parameters

[out]	notification	Zeroed caller storage
[in]	receiver	Task retained until all publishers quiesce
[in]	index	Exclusively owned kernel notification slot

Returns

SUCCESS, INVALID, CONTEXT or UNSUPPORTED by OS profile

Note

Caller ensures slot exclusivity. No global slot registry, allocation, slot discovery or cross-world synchronization.

nx_freertos_direct_notify_port()

nx_wait_port_t nx_freertos_direct_notify_port

(

nx_freertos_direct_notify_t *

notification

)

Get a direct notification wait port.

Parameters

[in]

notification

Live explicitly bound storage

Returns

Port using nx_time_now_us or an invalid zero port

Note

Only receiver may wait. Task/validated IRQ publishers use the exclusive slot; notification remains a predicate hint.

nx_freertos_isr_allowed()

bool nx_freertos_isr_allowed

(

void

)

Test whether the current context may call kernel ISR APIs.

Returns

True for a privileged unmasked external Cortex-M IRQ within the selected CPU/SoC bounds and kernel mask contract

Note

Native POSIX has no physical IRQ and returns false. NMI, faults and kernel-owned exceptions are rejected before entering FreeRTOS. Mainline priority/grouping must respect the syscall ceiling. Baseline PRIMASK ports accept every configurable IRQ and do not read Mainline priority grouping. Nonsecure permission does not exclude Secure-side accesses.

nx_freertos_notify_destroy()

nx_result_t nx_freertos_notify_destroy

(

nx_freertos_notify_t *

notification

)

Destroy after publishers and waiter have stopped and joined.

Parameters

[in,out]

notification

Live storage with no future users

Returns

SUCCESS, BUSY if a waiter is still registered, or error

Note

Task context. Quiescence is required beyond this busy check.

nx_freertos_notify_init()

nx_result_t nx_freertos_notify_init

(

nx_freertos_notify_t *

notification

)

Initialize unused notification storage.

Parameters

[out]

notification

Caller storage, zeroed before first use

Returns

SUCCESS or invalid/context/initialization error

Note

Task/startup context; no heap or timer daemon is needed.

nx_freertos_notify_port()

nx_wait_port_t nx_freertos_notify_port

(

nx_freertos_notify_t *

notification

)

Bind a latched single-waiter notification.

Parameters

[in]

notification

Initialized live storage

Returns

Notification port using nx_time_now_us clock domain

Note

Task wake uses xSemaphoreGive. IRQ wake validates priority then uses xSemaphoreGiveFromISR. Saturated latch is harmless; sequence and request predicates remain authoritative. No deferred daemon publishes wakes.

nx_freertos_permanent_task_start()

nx_result_t nx_freertos_permanent_task_start	(	nx_freertos_permanent_task_t *	task,
		const char *	name,
		StackType_t *	stack,
		size_t	stack_words,
		UBaseType_t	priority,
		void(*	entry )(void *),
		void *	context )

Start a task whose entry must never return.

Parameters

[out]	task	Zeroed permanent control, retained until reset
[in]	name	Copied kernel diagnostic name
[in]	stack	Aligned actual stack retained until reset
[in]	stack_words	Capacity includes reviewed startup minimum
[in]	priority	Below configMAX_PRIORITIES
[in]	entry	Permanent entry; return violates kernel contract
[in]	context	Retained until reset

Returns

SUCCESS or validation/context/start error

Note

No join latch, destroy or forced deletion. Choose joinable tasks for cooperative shutdown and reclaimable storage.

nx_freertos_queue_destroy()

nx_result_t nx_freertos_queue_destroy

(

nx_freertos_queue_t *

queue

)

Destroy after admission is stopped and all users joined.

Parameters

[in,out]

queue

Live drained queue, no future operations

Returns

SUCCESS, BUSY while users/items remain, or invalid/context

nx_freertos_queue_init()

nx_result_t nx_freertos_queue_init	(	nx_freertos_queue_t *	queue,
		uint8_t *	storage,
		size_t	storage_bytes,
		size_t	depth,
		size_t	item_size )

Create an exact-sized static byte-copy queue.

Parameters

[out]	queue	Zero-initialized caller queue control
[in]	storage	Byte buffer kept until destroy
[in]	storage_bytes	Actual byte capacity
[in]	depth	Number of items
[in]	item_size	Bytes copied per item

Returns

SUCCESS or invalid/context/start error

nx_freertos_queue_receive()

nx_result_t nx_freertos_queue_receive	(	nx_freertos_queue_t *	queue,
		void *	item,
		TickType_t	wait_ticks )

Receive one byte-copy item.

Parameters

[in,out]	queue	Live queue
[out]	item	Configured item byte capacity, valid only on success
[in]	wait_ticks	Explicit relative wait; portMAX_DELAY prohibited

Returns

SUCCESS, TIMEOUT, INVALID or CONTEXT

nx_freertos_queue_receive_until()

nx_result_t nx_freertos_queue_receive_until	(	nx_freertos_queue_t *	queue,
		void *	item,
		nx_time_us_t	deadline )

Receive using one absolute monotonic deadline.

Parameters

[in,out]	queue	Live raw queue
[out]	item	Configured bytes valid only on SUCCESS
[in]	deadline	nx_time_now_us domain

Returns

SUCCESS, TIMEOUT or validation/context error

nx_freertos_queue_send()

nx_result_t nx_freertos_queue_send	(	nx_freertos_queue_t *	queue,
		const void *	item,
		TickType_t	wait_ticks )

Copy an item with a bounded relative kernel wait.

Parameters

[in,out]	queue	Live queue
[in]	item	At least configured item bytes; not retained afterward
[in]	wait_ticks	Explicit relative wait; portMAX_DELAY prohibited

Returns

SUCCESS, TIMEOUT, INVALID or CONTEXT

Note

Task context. Admission/stop belongs to the application's explicit owner adapter, not this generic copy queue.

nx_freertos_queue_send_until()

nx_result_t nx_freertos_queue_send_until	(	nx_freertos_queue_t *	queue,
		const void *	item,
		nx_time_us_t	deadline )

Send using one absolute monotonic deadline.

Parameters

[in,out]	queue	Live raw queue
[in]	item	Configured bytes borrowed until return
[in]	deadline	nx_time_now_us domain, NEVER permits long waits

Returns

SUCCESS, TIMEOUT or validation/context error

Note

Immediate readiness wins over expiration. Stop admission and user quiescence remain external raw-queue obligations.

nx_freertos_queue_waiter_destroy()

nx_result_t nx_freertos_queue_waiter_destroy

(

nx_freertos_queue_waiter_t *

waiter

)

Destroy only after all operations stop and join.

Parameters

[in,out]

waiter

Live storage without future callers

Returns

SUCCESS, BUSY if active, or validation/context error

nx_freertos_queue_waiter_init()

nx_result_t nx_freertos_queue_waiter_init

(

nx_freertos_queue_waiter_t *

waiter

)

Initialize one exact caller-owned queue waiter.

Parameters

[out]

waiter

Zeroed storage, one simultaneous operation maximum

Returns

SUCCESS or validation/context/start error

nx_freertos_task_discard_before_scheduler()

nx_result_t nx_freertos_task_discard_before_scheduler

(

nx_freertos_task_t *

task

)

Discard one created task before its wrapper has executed.

Parameters

[in,out]

task

Live caller-owned static task, unused by other callers

Returns

SUCCESS after synchronous kernel deletion and latch cleanup; INVALID for absent, incomplete or already entered control; CONTEXT for ISR, unprivileged, noncanonical masks or a running/suspended scheduler, without mutation

Note

Single privileged startup lifecycle owner; scheduler state must be NOT_STARTED. The kernel candidate is first suspended to remove its retained TCB reference before deletion. No unmatched vTaskSuspendAll may remain during bootstrap: NOT_STARTED cannot reveal the kernel's private suspension nesting. This caller precondition applies before mutation. Success permits TCB, stack and context reuse after all external users are quiescent. This does not cancel or join an executed task.

nx_freertos_task_join()

nx_result_t nx_freertos_task_join	(	nx_freertos_task_t *	task,
		nx_time_us_t	deadline )

Join a cooperatively returned task and reclaim kernel state.

Parameters

[in,out]	task	Started task, distinct from current task
[in]	deadline	Absolute wait deadline in nx_time_now_us domain

Returns

SUCCESS only after external vTaskDelete removes the task; TIMEOUT retains handle, TCB, stack and context; CONTEXT rejects unsafe CPU context, self-join or stopped scheduler

Note

Single joiner, task context. The entry return parks its wrapper; no self-delete/idle cleanup race releases caller storage early. Stop producers, keep bus owner draining, join producers, then join owner.

nx_freertos_task_start()

nx_result_t nx_freertos_task_start	(	nx_freertos_task_t *	task,
		const char *	name,
		StackType_t *	stack,
		size_t	stack_words,
		UBaseType_t	priority,
		void(*	entry )(void *),
		void *	context )

Create one task from its exact caller-owned stack and TCB.

Parameters

[out]	task	Zero-initialized unused control storage
[in]	name	Kernel diagnostic name, copied by the kernel
[in]	stack	StackType_t array kept until successful join
[in]	stack_words	Actual capacity, at least the selected port startup minimum; runtime stack budget remains caller-owned
[in]	priority	Priority below configMAX_PRIORITIES
[in]	entry	Application entry, may return after cooperative stop
[in]	context	Entry context kept until join

Returns

SUCCESS or invalid/context/start error

Note

Task/startup context. No hidden worker or maximum pool. Entry must return in privileged Thread mode, with manual interrupt masks restored and the scheduler resumed after any temporary suspension.