threadx.h File Reference

Caller-owned ThreadX task, wait and byte queue services. More...

#include "nexus/core/time.h"
#include "nexus/os/wait.h"
#include "tx_api.h"

Go to the source code of this file.

Data Structures
struct	nx_threadx_notify_t
	One binary latch; publishers quiesce before destruction. More...
struct	nx_threadx_task_t
	Returning task retains all storage until external successful join. More...
struct	nx_threadx_permanent_task_t
	Permanent task has no completion latch, join or destroy. More...
struct	nx_threadx_queue_t
	Exact arbitrary byte items; no native word-size narrowing. More...
struct	nx_threadx_queue_waiter
	One explicit caller latch per simultaneous close-aware operation. More...
struct	nx_threadx_closable_queue_t
	Optional bounded close broadcast; registry is task-only. More...

Typedefs
typedef struct nx_threadx_queue_waiter	nx_threadx_queue_waiter_t
	One explicit caller latch per simultaneous close-aware operation.

Functions
nx_result_t	nx_threadx_kernel_enter (void(*startup)(void *), void *context)
	Explicit irreversible kernel entry owned by the product.
void	nx_threadx_fail_stop (nx_result_t reason)
	Product failure hook; default parks forever.
nx_result_t	nx_threadx_external_tick_setup (uint32_t tick_hz)
	Mandatory product hook only for explicit external Tick.
bool	nx_threadx_isr_allowed (void)
	Read-only configurable-IRQ and selected mask-policy gate.
nx_result_t	nx_threadx_notify_init (nx_threadx_notify_t *notification)
	Initialize one binary latch in task or actual bootstrap.
nx_wait_port_t	nx_threadx_notify_port (nx_threadx_notify_t *notification)
	Bind a sequence hint and one concurrent blocking waiter.
nx_result_t	nx_threadx_notify_destroy (nx_threadx_notify_t *notification)
	Destroy only after all publishers and waiter quiesce.
nx_result_t	nx_threadx_task_start (nx_threadx_task_t *task, const char *name, void *stack, size_t stack_bytes, UINT priority, void(*entry)(void *), void *context)
	Create a cooperatively returning task using exact storage.
nx_result_t	nx_threadx_task_join (nx_threadx_task_t *task, nx_time_us_t deadline)
	Join a cooperatively returned task and prove detachment.
nx_result_t	nx_threadx_task_discard_before_scheduler (nx_threadx_task_t *task)
	Discard an unused task only inside actual bootstrap.
nx_result_t	nx_threadx_permanent_task_start (nx_threadx_permanent_task_t *task, const char *name, void *stack, size_t stack_bytes, UINT priority, void(*entry)(void *), void *context)
	Start a permanent task without a completion latch.
nx_result_t	nx_threadx_queue_init (nx_threadx_queue_t *queue, uint8_t *storage, size_t storage_bytes, size_t depth, size_t item_size)
	Initialize an exact arbitrary-byte bounded queue.
nx_result_t	nx_threadx_queue_send_until (nx_threadx_queue_t *queue, const void *item, nx_time_us_t deadline)
	Task-only send; immediate readiness wins over expiration.
nx_result_t	nx_threadx_queue_receive_until (nx_threadx_queue_t *queue, void *item, nx_time_us_t deadline)
	Task-only receive; output changes only on SUCCESS.
nx_result_t	nx_threadx_queue_destroy (nx_threadx_queue_t *queue)
	Destroy a drained queue after every caller quiesces.
nx_result_t	nx_threadx_queue_waiter_init (nx_threadx_queue_waiter_t *waiter)
	Initialize one explicit close-aware operation latch.
nx_result_t	nx_threadx_queue_waiter_destroy (nx_threadx_queue_waiter_t *waiter)
	Destroy inactive waiter after its operation has returned.
nx_result_t	nx_threadx_closable_queue_init (nx_threadx_closable_queue_t *queue, uint8_t *storage, size_t storage_bytes, size_t depth, size_t item_size, size_t maximum_waiters)
	Add explicit bounded close broadcast to a byte queue.
nx_result_t	nx_threadx_closable_queue_close (nx_threadx_closable_queue_t *queue)
	Reject sends, wake registered waiters, retain queued items.
nx_result_t	nx_threadx_closable_queue_send_until (nx_threadx_closable_queue_t *queue, const void *item, nx_time_us_t deadline, nx_threadx_queue_waiter_t *waiter)
	Send with immediate close wake and explicit admission.
nx_result_t	nx_threadx_closable_queue_receive_until (nx_threadx_closable_queue_t *queue, void *item, nx_time_us_t deadline, nx_threadx_queue_waiter_t *waiter)
	Receive and drain previously queued items after close.
nx_result_t	nx_threadx_closable_queue_destroy (nx_threadx_closable_queue_t *queue)
	Destroy only a closed, drained and quiesced queue.

Detailed Description

Caller-owned ThreadX task, wait and byte queue services.

Author

Nexus Team

Note

Privileged, single-core, current-security-domain APIs. All controls start zeroed and remain adapter-owned while live. One external lifecycle owner serializes init/destroy and joins; publishers, queue callers and IRQ sources must quiesce before reclaiming storage. Runtime task operations require unmasked Thread mode and a running kernel. Actual bootstrap permits object init, task create/discard and wake; it does not permit blocking waits or queue operations. A manual mask, ISR or unsupported context returns CONTEXT before mutation. The byte queue's task threshold guard rejects foreign priority-zero time-sliced callers. Caller controls, stack ranges, full borrowed name/context objects, queue payloads, item buffers and waiters must be disjoint. Cold admission rejects known control/stack/payload overlap and name/context starting inside control or stack; unknown opaque extents remain the caller's responsibility. Never operate a closable queue through its raw inner queue. All deadlines use nx_time_now_us; NX_DEADLINE_NEVER is an actual unbounded kernel wait. Timeout never revokes any accepted I/O borrow. MPU/TZ isolation, tickless sleep and additional Cortex-M ports are outside this backend scope.

Definition in file threadx.h.

Typedef Documentation

nx_threadx_queue_waiter_t

typedef struct nx_threadx_queue_waiter nx_threadx_queue_waiter_t

One explicit caller latch per simultaneous close-aware operation.

Function Documentation

nx_threadx_closable_queue_close()

nx_result_t nx_threadx_closable_queue_close

(

nx_threadx_closable_queue_t *

queue

)

Reject sends, wake registered waiters, retain queued items.

Parameters

[in,out]

queue

Live close-aware queue

Returns

SUCCESS, INVALID or CONTEXT; close is idempotent

nx_threadx_closable_queue_destroy()

nx_result_t nx_threadx_closable_queue_destroy

(

nx_threadx_closable_queue_t *

queue

)

Destroy only a closed, drained and quiesced queue.

Parameters

[in,out]

queue

Live control and its borrowed payload storage

Returns

SUCCESS, INVALID, CONTEXT or BUSY; failure retains storage

nx_threadx_closable_queue_init()

nx_result_t nx_threadx_closable_queue_init	(	nx_threadx_closable_queue_t *	queue,
		uint8_t *	storage,
		size_t	storage_bytes,
		size_t	depth,
		size_t	item_size,
		size_t	maximum_waiters )

Add explicit bounded close broadcast to a byte queue.

Parameters

[in,out]	queue	Zeroed caller control retained until destroy
[in]	storage	Caller payload storage retained until destroy
[in]	storage_bytes	Exact depth multiplied by item_size
[in]	depth	Positive capacity below TX_WAIT_FOREVER
[in]	item_size	Positive exact payload byte count
[in]	maximum_waiters	Positive maximum simultaneous operations

Returns

SUCCESS, INVALID, CONTEXT or IO

Note

Payload size and maximum_waiters bound task scheduling pause; the entire copy/broadcast does not mask interrupts.

nx_threadx_closable_queue_receive_until()

nx_result_t nx_threadx_closable_queue_receive_until	(	nx_threadx_closable_queue_t *	queue,
		void *	item,
		nx_time_us_t	deadline,
		nx_threadx_queue_waiter_t *	waiter )

Receive and drain previously queued items after close.

Parameters

[in,out]	queue	Live queue retained throughout the operation
[out]	item	Exactly item_size writable bytes borrowed until return
[in]	deadline	Absolute Core deadline or NX_DEADLINE_NEVER
[in,out]	waiter	Live exclusive latch for this simultaneous call

Returns

SUCCESS, CANCELLED, TIMEOUT, BUSY, INVALID, CONTEXT or IO

Note

Closed and empty returns CANCELLED; failure leaves output.

nx_threadx_closable_queue_send_until()

nx_result_t nx_threadx_closable_queue_send_until	(	nx_threadx_closable_queue_t *	queue,
		const void *	item,
		nx_time_us_t	deadline,
		nx_threadx_queue_waiter_t *	waiter )

Send with immediate close wake and explicit admission.

Parameters

[in,out]	queue	Live queue retained throughout the operation
[in]	item	Exactly item_size readable bytes borrowed until return
[in]	deadline	Absolute Core deadline or NX_DEADLINE_NEVER
[in,out]	waiter	Live exclusive latch for this simultaneous call

Returns

SUCCESS, CANCELLED, TIMEOUT, BUSY, INVALID, CONTEXT or IO

Note

A closed queue rejects sends without changing payload.

nx_threadx_external_tick_setup()

nx_result_t nx_threadx_external_tick_setup

(

uint32_t

tick_hz

)

Mandatory product hook only for explicit external Tick.

Parameters

[in]

tick_hz

Exact immutable resolved kernel frequency

Returns

SUCCESS after binding a real bounded periodic IRQ source

Note

Actual kernel bootstrap, privileged PRIMASK masked. Provider owns timer clock and IRQ ceiling; it must not change the platform's continuous monotonic clock. Missing hook fails linking. Failure enters retaining fail-stop.

nx_threadx_fail_stop()

void nx_threadx_fail_stop

(

nx_result_t

reason

)

Product failure hook; default parks forever.

Parameters

[in]

reason

Context, permanent-entry or kernel-return failure

Note

Actual fault context is not repaired or normalized; it may be masked, ISR or unprivileged. Do not assume a working kernel, clock, stack or permission to access a peripheral. The adapter observes the Core fault hook before this hook. Product owns separately reviewed safe output/reset actions. Returning does not authorize cleanup; the adapter parks.

nx_threadx_isr_allowed()

bool nx_threadx_isr_allowed

(

void

)

Read-only configurable-IRQ and selected mask-policy gate.

Returns

True only in a privileged unmasked reviewed external IRQ

Note

Native has no hardware IRQ source and returns false.

nx_threadx_kernel_enter()

nx_result_t nx_threadx_kernel_enter	(	void(*	startup )(void *),
		void *	context )

Explicit irreversible kernel entry owned by the product.

Parameters

[in]	startup	Product initialization inside tx_application_define
[in]	context	Borrowed through startup and kernel lifetime

Returns

CONTEXT or INVALID before entry; successful entry never returns

Note

Privileged cold Thread/MSP, no live FP context or masks. Startup may create and discard unused static objects. After startup returns, the bootstrap scope is sealed. Only the trusted kernel may call adapter tx_application_define; it validates canonical privileged Thread context before the product callback. This is not a security isolation API. An unexpected kernel return invokes fail-stop and retains all effects; it never reopens bootstrap reclamation.

nx_threadx_notify_destroy()

nx_result_t nx_threadx_notify_destroy

(

nx_threadx_notify_t *

notification

)

Destroy only after all publishers and waiter quiesce.

Parameters

[in,out]

notification

Live caller latch

Returns

SUCCESS, INVALID, CONTEXT, BUSY or IO; failure retains it

nx_threadx_notify_init()

nx_result_t nx_threadx_notify_init

(

nx_threadx_notify_t *

notification

)

Initialize one binary latch in task or actual bootstrap.

Parameters

[in,out]

notification

Zeroed caller control retained until destroy

Returns

SUCCESS, INVALID, CONTEXT or IO

nx_threadx_notify_port()

nx_wait_port_t nx_threadx_notify_port

(

nx_threadx_notify_t *

notification

)

Bind a sequence hint and one concurrent blocking waiter.

Parameters

[in,out]

notification

Live latch retained through every port user

Returns

Wait face; empty face for null or non-live control

Note

Binding/arm are reads. Wake supports task/bootstrap or an IRQ admitted by nx_threadx_isr_allowed. Wait is task-only; finite deadline expiration precedes a changed sequence.

nx_threadx_permanent_task_start()

nx_result_t nx_threadx_permanent_task_start	(	nx_threadx_permanent_task_t *	task,
		const char *	name,
		void *	stack,
		size_t	stack_bytes,
		UINT	priority,
		void(*	entry )(void *),
		void *	context )

Start a permanent task without a completion latch.

Parameters

[in,out]	task	Zeroed caller control, retained until reset
[in]	name	Borrowed immutable name, retained until reset
[in]	stack	Aligned caller buffer, retained until reset
[in]	stack_bytes	Actual capacity, at least TX_MINIMUM_STACK
[in]	priority	Smaller ThreadX priority values run first
[in]	entry	Never returns; return invokes retaining fail-stop
[in]	context	Borrowed until reset

Returns

SUCCESS, INVALID, CONTEXT or IO

Note

Eight-byte stack alignment; failure can retain live state.

nx_threadx_queue_destroy()

nx_result_t nx_threadx_queue_destroy

(

nx_threadx_queue_t *

queue

)

Destroy a drained queue after every caller quiesces.

Parameters

[in,out]

queue

Live caller control and storage

Returns

SUCCESS, INVALID, CONTEXT or BUSY; failure retains storage

nx_threadx_queue_init()

nx_result_t nx_threadx_queue_init	(	nx_threadx_queue_t *	queue,
		uint8_t *	storage,
		size_t	storage_bytes,
		size_t	depth,
		size_t	item_size )

Initialize an exact arbitrary-byte bounded queue.

Parameters

[in,out]	queue	Zeroed caller control retained until destroy
[in]	storage	Caller payload storage retained until destroy
[in]	storage_bytes	Exact depth multiplied by item_size
[in]	depth	Positive bounded capacity, below TX_WAIT_FOREVER
[in]	item_size	Positive byte count, without word-size narrowing

Returns

SUCCESS, INVALID, CONTEXT or IO

nx_threadx_queue_receive_until()

nx_result_t nx_threadx_queue_receive_until	(	nx_threadx_queue_t *	queue,
		void *	item,
		nx_time_us_t	deadline )

Task-only receive; output changes only on SUCCESS.

Parameters

[in,out]	queue	Live queue retained throughout the operation
[out]	item	Exactly item_size writable bytes borrowed until return
[in]	deadline	Absolute Core deadline or NX_DEADLINE_NEVER

Returns

SUCCESS, INVALID, CONTEXT, TIMEOUT, OVERFLOW or IO

nx_threadx_queue_send_until()

nx_result_t nx_threadx_queue_send_until	(	nx_threadx_queue_t *	queue,
		const void *	item,
		nx_time_us_t	deadline )

Task-only send; immediate readiness wins over expiration.

Parameters

[in,out]	queue	Live queue retained throughout the operation
[in]	item	Exactly item_size readable bytes borrowed until return
[in]	deadline	Absolute Core deadline or NX_DEADLINE_NEVER

Returns

SUCCESS, INVALID, CONTEXT, TIMEOUT, OVERFLOW or IO

nx_threadx_queue_waiter_destroy()

nx_result_t nx_threadx_queue_waiter_destroy

(

nx_threadx_queue_waiter_t *

waiter

)

Destroy inactive waiter after its operation has returned.

Parameters

[in,out]

waiter

Live caller latch with no concurrent users

Returns

SUCCESS, INVALID, CONTEXT, BUSY or IO

nx_threadx_queue_waiter_init()

nx_result_t nx_threadx_queue_waiter_init

(

nx_threadx_queue_waiter_t *

waiter

)

Initialize one explicit close-aware operation latch.

Parameters

[in,out]

waiter

Zeroed caller storage retained until waiter destroy

Returns

SUCCESS, INVALID, CONTEXT or IO

nx_threadx_task_discard_before_scheduler()

nx_result_t nx_threadx_task_discard_before_scheduler

(

nx_threadx_task_t *

task

)

Discard an unused task only inside actual bootstrap.

Parameters

[in,out]

task

Live task whose entry has never begun

Returns

SUCCESS, INVALID, CONTEXT or IO; failure retains storage

Note

This is prestart rollback, never runtime cancellation.

nx_threadx_task_join()

nx_result_t nx_threadx_task_join	(	nx_threadx_task_t *	task,
		nx_time_us_t	deadline )

Join a cooperatively returned task and prove detachment.

Parameters

[in,out]	task	Live caller task, one external joiner only
[in]	deadline	Absolute Core deadline or NX_DEADLINE_NEVER

Returns

SUCCESS, INVALID, CONTEXT, TIMEOUT or IO

Note

Self-join is rejected. Timeout retains task, borrowed name, stack and context. Completion hint alone never reclaims; successful real kernel deletion establishes detachment.

nx_threadx_task_start()

nx_result_t nx_threadx_task_start	(	nx_threadx_task_t *	task,
		const char *	name,
		void *	stack,
		size_t	stack_bytes,
		UINT	priority,
		void(*	entry )(void *),
		void *	context )

Create a cooperatively returning task using exact storage.

Parameters

[in,out]	task	Zeroed caller TCB/control, retained until join/discard
[in]	name	Borrowed immutable name, retained until reclamation
[in]	stack	Eight-byte aligned caller storage
[in]	stack_bytes	Actual capacity, at least TX_MINIMUM_STACK
[in]	priority	ThreadX priority; smaller values run first
[in]	entry	Returns only after application stop/drain
[in]	context	Borrowed until successful join/discard

Returns

SUCCESS, INVALID, CONTEXT or IO; partial failure retains live control if reclamation cannot be established

Note

No adapter heap or worker. Name is borrowed, not copied. Linux uses its own pthread stack; the caller buffer only validates kernel metadata and is not a host stack budget. Higher-priority entries may run before start returns.