uart.h File Reference

IRQ TX requests and independently budgeted byte/event reception. More...

#include "nexus/core/request.h"
#include "nexus/io/stream.h"
#include "nexus/io/wake.h"

Go to the source code of this file.

Data Structures
struct	nx_uart_rx_event_t
	Timestamp belongs to provider clock; precision is hardware-specific. More...
struct	nx_uart_tx_request_t
	Caller-owned TX descriptor; initialize base before first prepare. More...
struct	nx_uart_ops_t
	Shared read-only methods using one provider state. More...
struct	nx_uart_port
	Immutable interface pointing to caller-owned state. More...

Macros
#define	NX_UART_EVENT_PARITY   1u
#define	NX_UART_EVENT_FRAMING   2u
#define	NX_UART_EVENT_OVERRUN   4u
#define	NX_UART_EVENT_NOISE   8u
#define	NX_UART_EVENT_LOSS   16u
#define	NX_UART_EVENT_NO_BYTE   32u

Typedefs
typedef struct nx_uart_port	nx_uart_port_t

Enumerations
enum	nx_uart_rx_profile_t { NX_UART_RX_BYTES , NX_UART_RX_EVENTS , NX_UART_RX_BLOCKS }

Functions
nx_result_t	nx_uart_tx_prepare (nx_uart_tx_request_t *request, const uint8_t *data, size_t length, nx_time_us_t deadline)
	Prepare an unborrowed IRQ TX descriptor without copying data.
nx_result_t	nx_uart_port_submit (const nx_uart_port_t *port, nx_uart_tx_request_t *request)
	Submit one direct request to a single-executor UART.
nx_result_t	nx_uart_port_start_admitted (const nx_uart_port_t *port, nx_uart_tx_request_t *request)
	Start an adapter-admitted QUEUED request without readmission.
nx_result_t	nx_uart_port_cancel (const nx_uart_port_t *port, nx_uart_tx_request_t *request)
	Request cancellation; acceptance does not mean settlement.
void	nx_uart_port_service (const nx_uart_port_t *port)
	Observe time/hardware completion and drain one active request.
nx_result_t	nx_uart_port_read_events (const nx_uart_port_t *port, nx_uart_rx_event_t *events, size_t capacity, size_t *count)
	Read buffered RX events from the selected event profile.
nx_result_t	nx_uart_port_read_bytes (const nx_uart_port_t *port, uint8_t *bytes, size_t capacity, size_t *count)
	Read buffered bytes from the selected byte profile.
nx_result_t	nx_uart_port_stop (const nx_uart_port_t *port)
	Close admission and drain TX before releasing hardware.
nx_result_t	nx_uart_port_attach_wake (const nx_uart_port_t *port, const nx_irq_wake_t *wake, uint8_t syscall_ceiling)
	Attach or detach one explicit IRQ wake target.
nx_result_t	nx_uart_port_rx_start (const nx_uart_port_t *port, nx_stream_t *stream)
	Start the selected RX block mode using exact caller storage.
nx_result_t	nx_uart_port_rx_stop (const nx_uart_port_t *port)
	Stop RX block production without revoking consumer loans.

Detailed Description

IRQ TX requests and independently budgeted byte/event reception.

Author

Nexus Team

Definition in file uart.h.

Macro Definition Documentation

NX_UART_EVENT_FRAMING

#define NX_UART_EVENT_FRAMING   2u

Definition at line 25 of file uart.h.

NX_UART_EVENT_LOSS

#define NX_UART_EVENT_LOSS   16u

Definition at line 28 of file uart.h.

NX_UART_EVENT_NO_BYTE

#define NX_UART_EVENT_NO_BYTE   32u

Definition at line 29 of file uart.h.

NX_UART_EVENT_NOISE

#define NX_UART_EVENT_NOISE   8u

Definition at line 27 of file uart.h.

NX_UART_EVENT_OVERRUN

#define NX_UART_EVENT_OVERRUN   4u

Definition at line 26 of file uart.h.

NX_UART_EVENT_PARITY

#define NX_UART_EVENT_PARITY   1u

Definition at line 24 of file uart.h.

Typedef Documentation

nx_uart_port_t

typedef struct nx_uart_port nx_uart_port_t

Definition at line 18 of file uart.h.

Enumeration Type Documentation

nx_uart_rx_profile_t

enum nx_uart_rx_profile_t

Enumerator
NX_UART_RX_BYTES
NX_UART_RX_EVENTS
NX_UART_RX_BLOCKS

Definition at line 19 of file uart.h.

Function Documentation

nx_uart_port_attach_wake()

nx_result_t nx_uart_port_attach_wake	(	const nx_uart_port_t *	port,
		const nx_irq_wake_t *	wake,
		uint8_t	syscall_ceiling )

Attach or detach one explicit IRQ wake target.

Parameters

[in]	port	Initialized provider, controlled by one task executor.
[in]	wake	Immutable live target or NULL to detach.
[in]	syscall_ceiling	Optional additional unshifted kernel-safe priority floor; cannot weaken generated policy. PRIMASK kernel targets require zero. Ignored without kernel calls.

Returns

Success, CONTEXT outside task control, PERMISSION for unsafe actual IRQ priority, or provider STATE/UNSUPPORTED.

Note

Quiesce every previous publisher before reclaiming an old target. IRQ events latch RX/completion facts before notifying. Detachment removes future publications; notification storage still requires joining external waiters and callbacks.

nx_uart_port_cancel()

nx_result_t nx_uart_port_cancel	(	const nx_uart_port_t *	port,
		nx_uart_tx_request_t *	request )

Request cancellation; acceptance does not mean settlement.

Parameters

[in,out]	port	Same single execution owner as submit/service.
[in,out]	request	Active live descriptor; cross-task callers use a stable adapter slot and expected epoch instead of this pointer.

Returns

NX_SUCCESS for pending/already settled cancellation; STATE for a different request. Borrow continues until SETTLED.

nx_uart_port_read_bytes()

nx_result_t nx_uart_port_read_bytes	(	const nx_uart_port_t *	port,
		uint8_t *	bytes,
		size_t	capacity,
		size_t *	count )

Read buffered bytes from the selected byte profile.

Parameters

[in,out]	port	Initialized byte-profile port; one consumer.
[out]	bytes	Caller-owned destination; not retained.
[in]	capacity	Destination capacity in bytes.
[out]	count	Bytes copied; valid even when OVERFLOW is returned.

Returns

NX_SUCCESS, EMPTY, OVERFLOW or INVALID/UNSUPPORTED. Byte profile reports aggregate loss without invented timestamps.

nx_uart_port_read_events()

nx_result_t nx_uart_port_read_events	(	const nx_uart_port_t *	port,
		nx_uart_rx_event_t *	events,
		size_t	capacity,
		size_t *	count )

Read buffered RX events from the selected event profile.

Parameters

[in,out]	port	Initialized event-profile port; one consumer.
[out]	events	Caller-owned destination; not retained.
[in]	capacity	Destination event count.
[out]	count	Events copied, including explicit loss/error flags.

Returns

NX_SUCCESS, EMPTY or INVALID/UNSUPPORTED. IRQ produces only into configured storage; overflow never silently overwrites.

nx_uart_port_rx_start()

nx_result_t nx_uart_port_rx_start	(	const nx_uart_port_t *	port,
		nx_stream_t *	stream )

Start the selected RX block mode using exact caller storage.

Parameters

[in]	port	Block-capable provider, one task execution owner.
[in,out]	stream	Initialized block stream retained until RX stops and all acquired consumer blocks are released.

Returns

Success or INVALID/BUSY/UNSUPPORTED with zero failed admission loan; selected hardware modes validate every DMA block domain.

Note

Provider boundaries and gaps are explicit capability facts. The provider must never overwrite a borrowed consumer block.

nx_uart_port_rx_stop()

nx_result_t nx_uart_port_rx_stop

(

const nx_uart_port_t *

port

)

Stop RX block production without revoking consumer loans.

Parameters

[in]

port

Same executor as RX start; storage stays live on BUSY.

Returns

Success proves memory sources detached; BUSY retains producer loan, UNSUPPORTED for a byte/event-only provider.

Note

Consumers separately drain READY blocks and release loans; successful RX stop does not destroy stream or wake storage.

nx_uart_port_service()

void nx_uart_port_service

(

const nx_uart_port_t *

port

)

Observe time/hardware completion and drain one active request.

Parameters

[in,out]

port

Single task/loop execution owner.

Note

Bounded, no wait/callback; call throughout stop/drain and at the declared maximum service interval. Publication is final request access. Hardware unable to drain retains QUARANTINED.

nx_uart_port_start_admitted()

nx_result_t nx_uart_port_start_admitted	(	const nx_uart_port_t *	port,
		nx_uart_tx_request_t *	request )

Start an adapter-admitted QUEUED request without readmission.

Parameters

[in,out]	port	Single-executor initialized port.
[in,out]	request	QUEUED descriptor already borrowed by adapter.

Returns

BUSY retains QUEUED; NX_SUCCESS transfers execution to port. Other start errors must be settled by the adapter executor.

nx_uart_port_stop()

nx_result_t nx_uart_port_stop

(

const nx_uart_port_t *

port

)

Close admission and drain TX before releasing hardware.

Parameters

[in,out]

port

Owner; producers must already have quiesced.

Returns

NX_SUCCESS when stopped; BUSY while service must continue.

Note

RX/IRQ and external consumers must quiesce before storage reclamation. No automatic task/notification destruction.

nx_uart_port_submit()

nx_result_t nx_uart_port_submit	(	const nx_uart_port_t *	port,
		nx_uart_tx_request_t *	request )

Submit one direct request to a single-executor UART.

Parameters

[in,out]	port	Initialized idle port owned by this execution context.
[in,out]	request	READY descriptor; borrowed only on NX_SUCCESS.

Returns

NX_SUCCESS means ACCEPTED, including a later start failure. BUSY/INVALID/CONTEXT/STATE/TIMEOUT means REJECTED with zero borrow; an already expired direct request is not admitted.

Note

Task-only, bounded admission. TX completion waits for true TC (wire idle). IRQ only moves bytes/publishes hardware facts; the owner calls service to observe deadlines and settle. The first observed terminal fact latches its result. Later service, deadline or cancellation does not overwrite an already observed TC. IRQ/service latency bounds remain provider and product qualification inputs.

nx_uart_tx_prepare()

nx_result_t nx_uart_tx_prepare	(	nx_uart_tx_request_t *	request,
		const uint8_t *	data,
		size_t	length,
		nx_time_us_t	deadline )

Prepare an unborrowed IRQ TX descriptor without copying data.

Parameters

[in,out]	request	Fresh initialized or consumed SETTLED request.
[in]	data	Nonempty payload retained unchanged through SETTLED.
[in]	length	Positive byte count.
[in]	deadline	Absolute deadline in nx_time_now_us clock domain.

Returns

NX_SUCCESS or INVALID/STATE; failure retains no buffer.