Typed I/O: devices and execution contracts

These declarations come from public header files. Selection, lifecycle, supported execution modes and physical authorization remain bounded by the corresponding design and support records.

The Native model controls in model.h, spi_dma_model.h and rtc_lptim_model.h support host tests. They do not establish MCU hardware support or device discovery. Optional interfaces describe selected contracts; their presence does not imply support on every provider.

adc.h

Reviewed ADC single-shot and low-rate polling scans.

Author

Nexus Team

Functions

nx_result_t nx_adc_port_info(const nx_adc_port_t *port, nx_adc_info_t *info)

Query the fixed reviewed ADC sequence and raw-count format.

Parameters:

  • port – [in] Single-shot/low-rate scan provider.

  • info – [out] Resolution, declared reference and sequence length.

Returns:

Success or INVALID.

nx_result_t nx_adc_port_sequence_info(const nx_adc_port_t *port, nx_adc_sequence_info_t *info)

Read fixed channel order and complete-scan timing facts.

Parameters:

  • port – [in] Initialized timing-capable provider.

  • info – [out] Cold read-only facts; no acquisition starts.

Returns:

Success or INVALID/STATE/UNSUPPORTED.

nx_result_t nx_adc_port_attach_observer(const nx_adc_port_t *port, nx_adc_observer_t *observer)

Attach optional observer storage before acquisition starts.

Note

Stop and join before detach/reclaim. No hidden allocation; polling and finite modes need no observation storage.

Parameters:

  • port – [in] Initialized continuous provider, one task owner.

  • observer – [inout] Initialized stable caller storage, or NULL to detach. Provider validates exact stream count at start.

Returns:

Success or BUSY/CONTEXT/UNSUPPORTED.

nx_result_t nx_adc_port_block_observation(const nx_adc_port_t *port, const nx_stream_block_t *block, nx_adc_observation_t *observation)

Query one live consumer loan’s software completion record.

Parameters:

  • port – [in] Same stable observer-capable provider.

  • block – [in] Same stream’s currently acquired immutable block.

  • observation – [out] Copied epoch, ordinal, observed time and gap flag. This is never a hardware sample aperture timestamp.

Returns:

Success or INVALID/STATE/UNSUPPORTED, output unchanged on rejection.

nx_result_t nx_adc_port_sample(const nx_adc_port_t *port, uint16_t *samples, size_t capacity, nx_time_us_t deadline, size_t *count)

Sample the fixed single/scan sequence by bounded polling.

Note

CPU-active task-only acquisition. Reference voltage, sampling error and maximum rate need physical qualification.

Parameters:

  • port – [inout] Single execution owner; fixed channel/sample-time setup.

  • samples – [out] Raw counts in configured channel order.

  • capacity – [in] Sample capacity at least channel_count.

  • deadline – [in] Absolute clock-domain deadline.

  • count – [out] Complete valid samples; remaining output is untouched.

Returns:

Success or INVALID/BUSY/TIMEOUT/IO; abort/drain completes before return. No retained buffer, DMA/trigger/stream promise.

nx_result_t nx_adc_port_stream_start(const nx_adc_port_t *port, nx_stream_t *stream, uint32_t trigger_hz)

Start selected trigger/block acquisition with caller storage.

Note

Blocks contain native uint16_t raw counts in channel order. Capacities and lengths are multiples of a complete scan; DMA domains/alignment and physical rate require separate evidence.

Parameters:

  • port – [in] Trigger/block-capable provider, one task executor.

  • stream – [inout] Initialized immutable-consumer block mechanism.

  • trigger_hz – [in] Positive requested complete-scan rate; provider rejects rates outside its declared timer/ADC capability.

Returns:

Success or INVALID/BUSY/UNSUPPORTED before buffer admission.

nx_result_t nx_adc_port_stream_stop(const nx_adc_port_t *port)

Stop trigger and memory sources without revoking consumer loans.

Note

Consumer READY/BORROWED blocks must still be drained/released.

Parameters:

  • port – [in] Same acquisition executor; retain storage on BUSY.

Returns:

Success proves source detach, BUSY retains producer storage, UNSUPPORTED for a polling-only provider.

nx_result_t nx_adc_port_stream_service(const nx_adc_port_t *port)

Explicitly resume discrete block acquisition after consumer drain.

Note

No task, retry or hidden rearm is created. Block modes state their trigger gaps; continuous zero-gap capture requires a separately declared hardware capability and qualification.

Parameters:

  • port – [in] Same single task executor as start and stop.

Returns:

Success when an engine is armed, BUSY during source drain or free-block backpressure, STATE after acquisition stops.

nx_result_t nx_adc_port_attach_wake(const nx_adc_port_t *port, const nx_irq_wake_t *wake, uint8_t syscall_ceiling)

Attach an optional hint sink after checking publisher IRQ priority.

Note

Block/error predicates latch before notifications. Stop and join publishers and waiters before reclaiming old sink storage.

Parameters:

  • port – [in] Initialized block-capable provider, one task executor.

  • wake – [in] Immutable borrowed target or NULL to detach.

  • syscall_ceiling – [in] Optional additional unshifted kernel-safe priority floor; cannot weaken generated policy. PRIMASK kernel targets require zero. Ignored without kernel calls.

Returns:

Success or CONTEXT/STATE/PERMISSION/UNSUPPORTED.

struct nx_adc_info_t
#include <adc.h>

Raw count facts; nominal Vref is not a calibrated physical measurement.

Public Members

uint8_t resolution_bits
uint32_t reference_mv
size_t channel_count
struct nx_adc_sequence_info_t
#include <adc.h>

Immutable complete-scan timing facts for the selected mode.

Note

sample_times are codes into sample_cycles, in channel order. scan_cycles includes each channel’s sample and conversion. Clock declarations and cycle counts describe scheduling; they do not establish electrical accuracy or sample aperture timestamps. Arrays remain valid through provider lifetime.

Public Members

const uint8_t *channels
const uint8_t *sample_times
const uint16_t *sample_cycles
size_t channel_count
size_t sample_code_count
uint32_t adc_clock_hz
uint32_t timer_clock_hz
uint32_t scan_cycles
uint16_t conversion_cycles
struct nx_adc_ops_t
#include <adc.h>

Shared read-only methods using one provider state.

Note

Methods follow each public operation’s ownership contract. Missing optional methods report UNSUPPORTED.

Public Members

nx_result_t (*info)(const void *context, nx_adc_info_t *info)
nx_result_t (*sample)(void *context, uint16_t *samples, size_t capacity, nx_time_us_t deadline, size_t *count)
nx_result_t (*stream_start)(void *context, nx_stream_t *stream, uint32_t trigger_hz)
nx_result_t (*stream_stop)(void *context)
nx_result_t (*stream_service)(void *context)
nx_result_t (*attach_wake)(void *context, const nx_irq_wake_t *wake, uint8_t syscall_ceiling)
nx_result_t (*sequence_info)(const void *context, nx_adc_sequence_info_t *info)
nx_result_t (*attach_observer)(void *context, nx_adc_observer_t *observer)
nx_result_t (*block_observation)(const void *context, const nx_stream_block_t *block, nx_adc_observation_t *observation)
struct nx_adc_port
#include <adc.h>

Immutable interface pointing to caller-owned state.

Note

Face and state outlive callers, IRQs and retained borrows. Factory lookup neither initializes nor acquires hardware.

Public Members

const nx_adc_ops_t *ops
void *context

adc_format.h

Explicit integer sample representation and scan layout.

Author

Nexus Team

Enums

enum nx_adc_encoding_t

Integer encoding; no implicit voltage or floating-point conversion.

Values:

enumerator NX_ADC_ENCODING_UNKNOWN
enumerator NX_ADC_UNSIGNED
enumerator NX_ADC_TWOS_COMPLEMENT
enum nx_adc_byte_order_t

Byte order is explicit, independently of the executing CPU.

Values:

enumerator NX_ADC_BYTE_ORDER_UNKNOWN
enumerator NX_ADC_LITTLE_ENDIAN
enumerator NX_ADC_BIG_ENDIAN
enum nx_adc_group_t

Hardware conversion group; descriptive facts do not enable it.

Values:

enumerator NX_ADC_GROUP_UNKNOWN
enumerator NX_ADC_REGULAR
enumerator NX_ADC_INJECTED
enum nx_adc_trigger_t

Trigger identity is not a sample aperture timestamp.

Values:

enumerator NX_ADC_TRIGGER_UNKNOWN
enumerator NX_ADC_TRIGGER_SOFTWARE
enumerator NX_ADC_TRIGGER_TIMER
enumerator NX_ADC_TRIGGER_EVENT

Functions

nx_result_t nx_adc_format_validate(const nx_adc_format_t *format)

Validate a complete immutable layout without reading sample storage.

Parameters:

  • format – [in] Readable naturally aligned layout, retained by caller.

Returns:

SUCCESS or INVALID; no allocation, hardware access or retained loan.

nx_result_t nx_adc_format_decode(const nx_adc_format_t *format, const void *samples, size_t bytes, size_t scan, size_t channel, int64_t *value)

Decode one integer from a caller-owned or consumer-acquired scan.

Note

No pointer is retained. Input/output/format overlap and wrapping spans reject before access. Sample loads have bounded1..4 byte work. This operation performs neither calibrated engineering-unit conversion nor synchronization with an active producer. The consumer owns that join.

Parameters:

  • format – [in] Valid immutable uniform-channel scan description.

  • samples – [in] Readable storage; any producer/DMA access must be joined.

  • bytes – [in] Positive exact multiple of scan_stride, including padding.

  • scan – [in] Zero-based complete scan index.

  • channel – [in] Zero-based channel position in provider order.

  • value – [out] Separate aligned output, unchanged on rejection.

Returns:

SUCCESS or INVALID; all32-bit unsigned/signed raw values fit int64_t.

struct nx_adc_format_t
#include <adc_format.h>

Immutable uniform-channel integer layout, independent of ADC faces.

Note

storage_bytes is1..4; significant_bits is1..32 within that storage. lsb_bits names discarded low bits, not an arithmetic scaling factor. sample_stride and scan_stride include explicit padding in bytes. channel_count retains the provider’s separately declared channel order. Software triggers use identity0; hardware trigger identities are nonzero assembly-local IDs, never addresses or a promise of physical timing. Group/trigger declarations describe an already supported provider mode; validating a layout does not add support to a device or configure it.

Public Members

size_t sample_stride
size_t scan_stride
uint32_t trigger_identity
uint16_t channel_count
uint8_t storage_bytes
uint8_t significant_bits
uint8_t lsb_bits
nx_adc_encoding_t encoding
nx_adc_byte_order_t byte_order
nx_adc_group_t group
nx_adc_trigger_t trigger

adc_group.h

Optional finite whole-sequence integer ADC acquisition.

Author

Nexus Team

Functions

nx_result_t nx_adc_group_prepare(nx_adc_group_request_t *request, void *frames, size_t bytes, size_t frame_count, nx_time_us_t deadline)

Prepare caller storage without hardware access or retained borrow.

Note

Request and frames are distinct. Preparation reads no sample bytes and does not prove a DMA domain or chip mode. All previous observers must be joined before reuse. NX_DEADLINE_NEVER is rejected.

Parameters:

  • request – [inout] Initialized READY or fully consumed SETTLED storage.

  • frames – [out] Aligned nonempty raw output including explicit padding.

  • bytes – [in] Positive nonwrapping span; provider validates exact layout.

  • frame_count – [in] Positive whole-frame count, not a raw rank count.

  • deadline – [in] Finite absolute deadline in platform monotonic domain.

Returns:

SUCCESS or INVALID/STATE, rejected request remains unchanged.

nx_result_t nx_adc_group_submit(const nx_adc_group_port_t *port, nx_adc_group_request_t *request)

Accept and start one selected finite acquisition under a sole owner.

Note

Accepted descriptor is caller-immutable; caller cannot access frames until acquire-observed SETTLED. Priming may write this entire span but never publishes prime data as valid. Post-admission arm failure keeps the borrow until actual drain. Without trusted completion timestamps, completion first observed at/after deadline is TIMEOUT. One-frame injected profiles deliberately prevent a second trigger/JDR overwrite.

Parameters:

  • port – [in] Initialized selected face with immutable retained facts.

  • request – [inout] Exact READY descriptor and exclusive writable span.

Returns:

SUCCESS means ACCEPTED, including immediate SETTLED failure. Other results reject without pointer retention or residual new effects.

nx_result_t nx_adc_group_cancel(const nx_adc_group_port_t *port, nx_adc_group_request_t *request)

Start cancellation without revoking the accepted storage borrow.

Note

The first terminal fault/cancel/timeout remains authoritative.

Parameters:

  • port – [in] Same stable selected face and serialized privileged task.

  • request – [inout] Exact current accepted request, still live.

Returns:

SUCCESS starts/observes cancellation; it does not imply SETTLED.

nx_result_t nx_adc_group_service(const nx_adc_group_port_t *port)

Make bounded prime/acquisition/drain progress without hidden waits.

Note

No request or output is reclaimed while sources, ADC, DMA or IRQs may still reference it. QUARANTINED requests remain owned and retryable.

Parameters:

  • port – [in] Same stable selected face and serialized privileged task.

Returns:

SUCCESS after progress/settlement, BUSY during outstanding drain, or an error with retained recovery responsibility.

nx_result_t nx_adc_group_stop(const nx_adc_group_port_t *port)

Close admission and prove request source drain before reporting idle.

Note

Stop is not cold close: pads, common clock, internal-source enables and provider storage remain retained until platform joined close.

Parameters:

  • port – [in] Same stable selected face and serialized privileged task.

Returns:

SUCCESS only after final request detach; BUSY/IO keeps all leases.

nx_result_t nx_adc_group_info(const nx_adc_group_port_t *port, nx_adc_group_info_t *info)

Copy actual selected facts and current retained owner state.

Note

Observing idle/fault does not release a request or any cold lease.

Parameters:

  • port – [in] Same initialized selected face, unique task executor.

  • info – [out] Separate aligned output, unchanged on rejection.

Returns:

SUCCESS or INVALID/STATE/CONTEXT/UNSUPPORTED.

struct nx_adc_group_request_t
#include <adc_group.h>

Complete raw frame span with an explicit finite request lifetime.

Note

base.transferred counts complete frames, never bytes or individual ranks. SUCCESS means exactly frame_count; errors guarantee zero valid frames. Partial DMA/JEOC progress does not publish a valid prefix.

Public Members

nx_request_t base
void *frames

Exclusive producer storage, including padding.

size_t bytes

Exact frame_count * info.format.scan_stride.

size_t frame_count

Positive complete frames, within selected bound.

struct nx_adc_group_info_t
#include <adc_group.h>

Cold selected rank order, actual integer layout and scheduling facts.

Note

Arrays belong to immutable selected facts and outlive this port. A physical rank can be discarded padding required by silicon errata; format describes only valid logical results. No implicit data packing, engineering units, aperture timestamp or trigger counter is promised.

Public Members

nx_adc_format_t format
const uint8_t *channels

Logical rank order, including repeats.

const uint8_t *sample_times

Actual per-channel sampling codes.

const uint16_t *sample_halfcycles

Sampling-code lookup, immutable.

size_t sample_code_count
uint32_t adc_clock_hz
uint32_t physical_scan_halfcycles

Includes all discarded ranks.

uint32_t timer_period_us

Zero for software; not an aperture.

size_t max_frames
uint16_t physical_ranks
bool active
bool fault
bool quarantined
struct nx_adc_group_ops_t
#include <adc_group.h>

Shared read-only selected methods; ordinary ADC tables do not grow.

Note

A privileged task serializes every call. IRQs only record bounded facts in the same unique physical owner. No allocation, pool, implicit task, automatic rearm or runtime discovery is provided.

Public Members

nx_result_t (*submit)(void *context, nx_adc_group_request_t *request)
nx_result_t (*cancel)(void *context, nx_adc_group_request_t *request)
nx_result_t (*service)(void *context)
nx_result_t (*stop)(void *context)
nx_result_t (*info)(const void *context, nx_adc_group_info_t *info)
struct nx_adc_group_port
#include <adc_group.h>

Immutable selected face, sharing one const table across instances.

Note

Face/context/configuration outlive every request, vector and retained close. Existing ordinary ADC or PWM/ADC faces cannot expose the same leased ADC. A factory only returns this existing object.

Public Members

const nx_adc_group_ops_t *ops
void *context

adc_observer.h

Optional caller-owned ADC publication observations.

Author

Nexus Team

Defines

NX_ADC_OBSERVATION_DISCONTINUITY

Functions

nx_result_t nx_adc_observer_initialize(nx_adc_observer_t *observer, nx_adc_observation_t *records, size_t count)

Initialize fresh unborrowed optional observation storage.

Parameters:

  • observer – [out] Aligned fresh control, not published to readers.

  • records – [out] Distinct aligned exact record array.

  • count – [in] Positive count; must equal the selected stream count.

Returns:

Success or INVALID/CONTEXT; rejected outputs stay untouched.

nx_result_t nx_adc_observer_bind(nx_adc_observer_t *observer, nx_stream_t *stream, const void *owner, size_t owner_size)

Provider-only cold bind validates every metadata/payload span before the first DMA loan.

Parameters:

  • observer – [inout] Initialized exclusive observation control.

  • stream – [in] Exact initialized stream, no outstanding loans.

  • owner – [in] Provider’s stable complete private state span.

  • owner_size – [in] Positive exact state byte count.

Returns:

Success or INVALID/BUSY, without a partial retained bind.

nx_result_t nx_adc_observer_record(nx_adc_observer_t *observer, const nx_stream_fill_t *fill, nx_time_us_t observed_at)

Provider-only record before matching release-publication.

Parameters:

  • observer – [inout] Bound exact producer-owned control.

  • fill – [in] Still FILLING, with a proved detached memory target.

  • observed_at – [in] Software observation in the same clock domain.

Returns:

Success or STATE/EXHAUSTED without wrapping identities.

nx_result_t nx_adc_observer_read(const nx_adc_observer_t *observer, const nx_stream_block_t *block, nx_adc_observation_t *observation)

Read only a currently acquired block’s exact epoch record.

Parameters:

  • observer – [in] Stable bound observation control.

  • block – [in] Same stream’s live immutable consumer loan.

  • observation – [out] Complete copy; untouched on rejection.

Returns:

Success or INVALID/STATE for a missing/stale/released loan.

nx_result_t nx_adc_observer_unbind(nx_adc_observer_t *observer)

Provider-only unbind after all producer/consumer loans join.

Parameters:

  • observer – [inout] Stable initialized control; NULL is allowed.

Returns:

Success or BUSY retaining the bound stream.

struct nx_adc_observation_t
#include <adc_observer.h>

One loan’s software observation, never a sample aperture.

Note

observed_at uses the platform monotonic clock after target detach readback. IRQ delivery and publication latency are included. sequence counts observed valid block records, not timer triggers, samples or guessed missed scans.

Public Members

uint64_t epoch
nx_time_us_t observed_at
uint64_t sequence
uint32_t flags
struct nx_adc_observer_t
#include <adc_observer.h>

Optional caller-owned observer control and exact records.

Note

Initialize before attaching; internal fields belong to one producer. Records and control remain live through successful provider stop and all consumer releases. No default stream, slot or finite provider storage is enlarged.

Public Members

nx_stream_t *stream
nx_adc_observation_t *records
size_t count
uint64_t sequence
bool discontinuity

advanced_pwm.h

Optional fixed complementary PWM with latched break.

Author

Nexus Team

Functions

nx_result_t nx_advanced_pwm_set_duty(const nx_advanced_pwm_t *port, uint32_t duty_ticks)

Stage duty against the fixed declared PSC/ARR and complementary pair.

Note

Shadow duty becomes effective at the next update. Hardware deadtime encoding must exactly represent the cold-configured tDTS count; PSC does not scale deadtime. This API does not certify pin timing.

Parameters:

  • port – [in] One serialized privileged task owner.

  • duty_ticks – [in] Zero through the maintained period, inclusive.

Returns:

SUCCESS or INVALID/STATE/CONTEXT; no base-clock reconfiguration.

nx_result_t nx_advanced_pwm_start(const nx_advanced_pwm_t *port)

Enable outputs only with inactive break and no latched fault.

Note

Automatic output reenabling and irreversible hardware LOCK are prohibited. A break never silently starts outputs again.

Parameters:

  • port – [in] Privileged task owner of reviewed pin/clock/vector leases.

Returns:

SUCCESS or BUSY/STATE/IO/CONTEXT; failure retains ownership.

nx_result_t nx_advanced_pwm_stop(const nx_advanced_pwm_t *port)

Disable/read back master output and both channel sources.

Note

Cold assembly keeps the reviewed inactive-pin and shared-vector leases until success and IRQ quiescence. A latched break survives stop.

Parameters:

  • port – [in] Privileged task owner, no concurrent duty/lifecycle calls.

Returns:

SUCCESS proves output source detachment; BUSY retains responsibility.

nx_result_t nx_advanced_pwm_state(const nx_advanced_pwm_t *port, nx_advanced_pwm_state_t *state)

Query staged duty, actual enable state and latched break facts.

Parameters:

  • port – [in] Privileged task owner.

  • state – [out] Separate writable snapshot, never provider storage.

Returns:

SUCCESS or INVALID/STATE/CONTEXT.

nx_result_t nx_advanced_pwm_clear_fault(const nx_advanced_pwm_t *port)

Clear a software fault only while disabled and BKIN is inactive.

Note

Physical input and pending hardware break are rechecked. Application recovery policy and external power safety remain outside Nexus.

Parameters:

  • port – [in] Privileged task recovery owner.

Returns:

SUCCESS or BUSY/STATE/IO/CONTEXT; does not enable outputs.

struct nx_advanced_pwm_state_t
#include <advanced_pwm.h>

Counts use the fixed post-prescaler clock; deadtime uses tDTS.

Public Members

uint32_t period_ticks
uint32_t duty_ticks
uint32_t tick_hz
uint32_t deadtime_ticks
uint32_t deadtime_hz
bool running
bool fault
struct nx_advanced_pwm_ops_t
#include <advanced_pwm.h>

Shared immutable controls; configuration is a cold assembly fact.

Public Members

nx_result_t (*set_duty)(void *context, uint32_t duty_ticks)
nx_result_t (*start)(void *context)
nx_result_t (*stop)(void *context)
nx_result_t (*state)(const void *context, nx_advanced_pwm_state_t *state)
nx_result_t (*clear_fault)(void *context)
struct nx_advanced_pwm
#include <advanced_pwm.h>

Immutable identity; controller state and configuration outlive IRQs.

Public Members

const nx_advanced_pwm_ops_t *ops
void *context

can.h

Classic CAN value frames and caller-owned mailbox requests.

Author

Nexus Team

Defines

NX_CAN_LOSS_SOFTWARE
NX_CAN_LOSS_HARDWARE_LOWER_BOUND
NX_CAN_LOSS_SATURATED
NX_CAN_DLC_NORMALIZED

Enums

enum nx_can_format_t

Values:

enumerator NX_CAN_STANDARD
enumerator NX_CAN_EXTENDED
enum nx_can_frame_kind_t

Values:

enumerator NX_CAN_DATA
enumerator NX_CAN_REMOTE
enum nx_can_event_kind_t

Values:

enumerator NX_CAN_EVENT_FRAME
enumerator NX_CAN_EVENT_LOSS

Functions

nx_result_t nx_can_tx_prepare(nx_can_tx_request_t *request, const nx_can_frame_t *frame, nx_time_us_t deadline)

Validate and copy a classic frame into unborrowed request storage.

Note

Task owner only; failure retains no reference and changes no frame.

Parameters:

  • request – [inout] Initialized READY or consumed SETTLED storage.

  • frame – [in] Value copied here; remote data bytes are ignored.

  • deadline – [in] Absolute provider-clock deadline, including admission.

Returns:

Success, INVALID for nonclassic frame, STATE while borrowed.

nx_result_t nx_can_port_submit(const nx_can_port_t *port, nx_can_tx_request_t *request)

Admit one frame into one of three hardware mailboxes.

Note

Serialized privileged task owner, incoming IRQ masks clear. REJECTED retains nothing. TXOK plus completed/empty hardware proves success.

Parameters:

  • port – [in] Stable immutable face and private storage.

  • request – [inout] READY value request, kept alive until SETTLED.

Returns:

Success means ACCEPTED, not on-wire completion; other results reject.

nx_result_t nx_can_port_cancel(const nx_can_port_t *port, nx_can_tx_request_t *request)

Request abort without revoking a borrowed request.

Note

Abort may race real transmission; observed TXOK remains SUCCESS. Failed abort remains QUARANTINED and must keep storage alive.

Parameters:

  • port – [in] Stable face owned by the serialized task executor.

  • request – [inout] Live request previously accepted by this instance.

Returns:

Success requests drain; STATE for an unrelated request.

nx_result_t nx_can_port_service(const nx_can_port_t *port)

Process latched completions and absolute timeout/drain deadlines.

Note

Bounded three-mailbox/six-frame work, no worker, blocking or replay.

Parameters:

  • port – [in] Serialized task-owner face with incoming masks clear.

Returns:

Success, STATE before start, CONTEXT for an illegal caller.

nx_result_t nx_can_port_read_events(const nx_can_port_t *port, nx_can_event_t *events, size_t capacity, size_t *count)

Consume value events without overwriting earlier unconsumed facts.

Note

Each bounded record copy has a short metadata exclusion; pending loss is ordered after older records and before future frames.

Parameters:

  • port – [in] Stable instance; one task consumer owns this operation.

  • events – [out] Caller capacity; no retained output reference.

  • capacity – [in] Nonzero number of event records.

  • count – [out] Number copied; EMPTY means zero available.

Returns:

Success, EMPTY, INVALID or CONTEXT.

nx_result_t nx_can_port_state(const nx_can_port_t *port, nx_can_state_t *state)

Copy authoritative error/admission state, even when RX is full.

Note

Task-only, bounded; bus-off is latched until explicit recovery.

Parameters:

  • port – [in] Live instance and storage.

  • state – [out] Unretained value output.

Returns:

Success, INVALID or CONTEXT.

nx_result_t nx_can_port_stop(const nx_can_port_t *port)

Close admission, abort TX and detach IRQ/RX publishers.

Note

Never resets the shared primary controller to release a peer’s loan. Retry after progress. Success ends provider access to RX/wake storage.

Parameters:

  • port – [in] Serialized owner; external observers must also join.

Returns:

Success after hardware drain; BUSY retains requests/ring/wake loans.

nx_result_t nx_can_port_recover(const nx_can_port_t *port)

Explicitly reenter initialization after bus-off and complete drain.

Note

No automatic recovery or retransmission; domain/filter identity stays.

Parameters:

  • port – [in] Started owner with no active/quarantined TX slots.

Returns:

Success after bounded hardware acknowledgement, BUSY while borrowed.

nx_result_t nx_can_port_attach_wake(const nx_can_port_t *port, const nx_irq_wake_t *wake, uint8_t syscall_ceiling)

Borrow an optional wake target after checking all four actual IRQs.

Note

No implicit OS policy; NULL detaches. Wake is only a hint. The sink must support both task service/cancel and configurable IRQ contexts.

Parameters:

  • port – [in] Serialized task owner, started and masks clear.

  • wake – [in] Immutable target kept alive until successful stop/detach.

  • syscall_ceiling – [in] Additional numerical BASEPRI ceiling.

Returns:

Success, BUSY while an earlier publisher is live, PERMISSION, INVALID or CONTEXT, with no new borrow on failure.

struct nx_can_frame_t
#include <can.h>

Classic 2.0A/B value frame; DLC is always 0..8, never CAN FD.

Public Members

uint32_t id
nx_can_format_t format
nx_can_frame_kind_t kind
uint8_t dlc
uint8_t data[8]
struct nx_can_tx_request_t
#include <can.h>

Caller-owned frame copied at prepare; base must first be initialized.

Public Members

nx_request_t base
nx_can_frame_t frame
struct nx_can_event_t
#include <can.h>

Value receive fact or ordered loss boundary.

Note

Timestamp is IRQ acquisition/report time, not hardware SOF. Hardware overrun proves only a lower bound. Raw DLC 9..15 is normalized to 8.

Public Members

nx_can_frame_t frame
nx_time_us_t timestamp_us
uint64_t lost
uint32_t flags
nx_can_event_kind_t kind
uint8_t fifo
uint8_t filter
uint8_t raw_dlc
struct nx_can_state_t
#include <can.h>

Latched controller state, independent of receive-ring fullness.

Public Members

bool started
bool closing
bool bus_off
uint8_t pending
uint8_t transmit_errors
uint8_t receive_errors
uint8_t last_error
struct nx_can_ops_t
#include <can.h>

Shared immutable operations; execution owner serializes task methods.

Public Members

nx_result_t (*submit)(void*, nx_can_tx_request_t*)
nx_result_t (*cancel)(void*, nx_can_tx_request_t*)
nx_result_t (*service)(void*)
nx_result_t (*read_events)(void*, nx_can_event_t*, size_t, size_t*)
nx_result_t (*state)(void*, nx_can_state_t*)
nx_result_t (*stop)(void*)
nx_result_t (*recover)(void*)
nx_result_t (*attach_wake)(void*, const nx_irq_wake_t*, uint8_t)
struct nx_can_port
#include <can.h>

Immutable face; lookup does not allocate, start or acquire hardware.

Public Members

const nx_can_ops_t *ops
void *context

can_fd.h

Optional CAN FD value ports and retained hardware requests.

Author

Nexus Team

Defines

NX_CAN_FD_TIMESTAMP_UNAVAILABLE

Enums

enum nx_can_wire_format_t

Exact wire format; the classic interface remains independent.

Values:

enumerator NX_CAN_WIRE_CLASSIC
enumerator NX_CAN_WIRE_FD

Functions

nx_result_t nx_can_fd_tx_prepare(nx_can_fd_tx_request_t *request, const nx_can_fd_frame_t *frame, nx_time_us_t deadline)

Validate and copy an exact frame into unborrowed request storage.

Note

Serialized task owner. Failure changes no frame and creates no loan.

Parameters:

  • request – [inout] Initialized READY or consumed SETTLED storage.

  • frame – [in] Whole value copied without retaining this address.

  • deadline – [in] Absolute provider-clock deadline, including admission.

Returns:

Success, INVALID for a malformed frame, STATE while borrowed.

nx_result_t nx_can_fd_port_submit(const nx_can_fd_port_t *port, nx_can_fd_tx_request_t *request)

Admit one exact value into a physical hardware transmit element.

Note

Serialized privileged task, incoming masks clear. No software FIFO ordering is implied by admission; a hardware queue arbitrates by ID.

Parameters:

  • port – [in] Stable immutable selected controller face.

  • request – [inout] READY request retained until acquire SETTLED.

Returns:

SUCCESS means ACCEPTED; every failure rejects without effects.

nx_result_t nx_can_fd_port_cancel(const nx_can_fd_port_t *port, nx_can_fd_tx_request_t *request)

Request cancellation while preserving the accepted storage loan.

Note

Physical transmission may win cancellation and remain SUCCESS. Timeout/cancel do not release storage. Failed drain is QUARANTINED.

Parameters:

  • port – [in] Selected face owned by the sole task executor.

  • request – [inout] Exact request previously accepted by this instance.

Returns:

Success requests drain, STATE rejects an unrelated request.

nx_result_t nx_can_fd_port_service(const nx_can_fd_port_t *port)

Process bounded hardware facts and absolute deadline progress.

Note

No hidden worker, retry or blocking wait. Wake remains only a hint.

Parameters:

  • port – [in] Serialized privileged task face, incoming masks clear.

Returns:

Success, STATE while unavailable, CONTEXT for an illegal caller.

nx_result_t nx_can_fd_port_read_events(const nx_can_fd_port_t *port, nx_can_fd_event_t *events, size_t capacity, size_t *count)

Copy ordered value events into unretained caller output storage.

Note

Earlier retained records precede a pending loss boundary. Neither full receive storage nor a failed hint may erase protocol state.

Parameters:

  • port – [in] Stable instance with one task consumer.

  • events – [out] Writable output, disjoint from all borrowed storage.

  • capacity – [in] Positive number of complete output event records.

  • count – [out] Unretained number copied, disjoint from events.

Returns:

Success, EMPTY with zero copied, INVALID, STATE or CONTEXT.

nx_result_t nx_can_fd_port_state(const nx_can_fd_port_t *port, nx_can_fd_state_t *state)

Copy authoritative latched protocol and ownership state.

Note

Task-only; a full event ring does not hide bus-off or error state.

Parameters:

  • port – [in] Stable selected instance, including after successful stop.

  • state – [out] Writable value, disjoint from all borrowed controls.

Returns:

Success, INVALID or CONTEXT. Output is never retained.

nx_result_t nx_can_fd_port_stop(const nx_can_fd_port_t *port)

Close admission, drain transmit loans and withdraw IRQ publishers.

Note

Never reset a shared peripheral domain to revoke another owner. Retry after physical progress. Stop success is not observer join.

Parameters:

  • port – [in] Sole task owner; separate observers must also join.

Returns:

Success releases provider loans; failure retains incomplete leases.

nx_result_t nx_can_fd_port_recover(const nx_can_fd_port_t *port)

Recover the same hardware identity after complete transmit drain.

Note

Explicit recovery never replays a frame or reassigns shared RAM.

Parameters:

  • port – [in] Started task owner with no pending or quarantined request.

Returns:

Success after bounded acknowledgement, BUSY while borrowed.

nx_result_t nx_can_fd_port_attach_wake(const nx_can_fd_port_t *port, const nx_irq_wake_t *wake, uint8_t syscall_ceiling)

Borrow a wake sink after validating the actual enabled IRQ source.

Note

NULL detaches. Rejection preserves the earlier sink. Notification must be bounded and legal in both task and configurable IRQ contexts.

Parameters:

  • port – [in] Sole task owner, started and incoming masks clear.

  • wake – [in] Immutable sink retained through successful detach/stop.

  • syscall_ceiling – [in] Additional numerical BASEPRI ceiling.

Returns:

Success, BUSY while publishing, PERMISSION, INVALID or CONTEXT.

struct nx_can_fd_frame_t
#include <can_fd.h>

Value frame with an exact byte length, never raw or shifted DLC.

Note

FD admits0..8/12/16/20/24/32/48/64 bytes; no rounding or padding on wire. FD remote frames and classic BRS are invalid. A provider may reject a valid value when its selected hardware mode lacks that form.

Public Members

uint32_t id
nx_can_format_t format
nx_can_frame_kind_t kind
nx_can_wire_format_t wire
uint8_t payload_bytes
bool brs
uint8_t data[64]
struct nx_can_fd_tx_request_t
#include <can_fd.h>

Prepare copies a complete value; accepted request stays borrowed.

Public Members

nx_request_t base
nx_can_fd_frame_t frame
struct nx_can_fd_event_t
#include <can_fd.h>

Acquired value event, including observed transmitter ESI.

Note

acquired_us is provider acquisition time, never SOF. A disabled hardware counter reports raw0 plus TIMESTAMP_UNAVAILABLE. filter is the hardware index within the frame format’s filter list. Hardware loss proves a lower bound; classic DLC9..15 normalizes to8 with a flag.

Public Members

nx_can_fd_frame_t frame
nx_time_us_t acquired_us
uint64_t lost
uint32_t flags
nx_can_event_kind_t kind
uint16_t hardware_timestamp
uint8_t fifo
uint8_t filter
uint8_t raw_dlc
bool error_passive
bool nonmatching
struct nx_can_fd_filter_t
#include <can_fd.h>

Immutable mask filter; no product register or protocol policy.

Public Members

uint32_t id
uint32_t mask
nx_can_format_t format
uint8_t fifo
struct nx_can_fd_state_t
#include <can_fd.h>

Latched protocol state; payload length never describes a frame count.

Public Members

nx_can_state_t controller
uint8_t data_last_error
bool error_warning
bool error_passive
struct nx_can_fd_ops_t
#include <can_fd.h>

Public Members

nx_result_t (*submit)(void*, nx_can_fd_tx_request_t*)
nx_result_t (*cancel)(void*, nx_can_fd_tx_request_t*)
nx_result_t (*service)(void*)
nx_result_t (*read_events)(void*, nx_can_fd_event_t*, size_t, size_t*)
nx_result_t (*state)(void*, nx_can_fd_state_t*)
nx_result_t (*stop)(void*)
nx_result_t (*recover)(void*)
nx_result_t (*attach_wake)(void*, const nx_irq_wake_t*, uint8_t)
struct nx_can_fd_port
#include <can_fd.h>

Public Members

const nx_can_fd_ops_t *ops
void *context

cycle_probe.h

Opt-in raw cycle observations without elapsed-time claims.

Author

Nexus Team

Defines

NX_IO_CYCLE_PROBES
NX_IO_IRQ_PROBE_DECLARE(id)
NX_IO_IRQ_PROBE_BEGIN(id)
NX_IO_IRQ_PROBE_END(id)

Functions

nx_result_t nx_io_cycle_probe_begin(nx_io_cycle_probe_t *probe, nx_io_cycle_token_t *token)

Start one raw observation without enabling or resetting DWT.

Note

Configurable IRQ or unique task executor. Probe failure must never prevent real I/O dispatch, cancellation, service or retained drain.

Parameters:

  • probe – [inout] Live, exclusive zero/previously completed sidecar.

  • token – [inout] Zero/inactive token distinct from the complete probe.

Returns:

SUCCESS even if the counter is unavailable; INVALID/STATE/BUSY rejects before counter access. Same-probe reentry is counted.

nx_result_t nx_io_cycle_probe_end(nx_io_cycle_probe_t *probe, nx_io_cycle_token_t *token)

Finish the exact token, publish raw facts and remove its reference.

Note

No elapsed or budget validity is inferred from two counter values.

Parameters:

  • probe – [inout] Same stable sidecar supplied to begin.

  • token – [inout] Exact still-active token; not concurrently modified.

Returns:

SUCCESS, INVALID or STATE with another/inactive token.

nx_result_t nx_io_cycle_probe_snapshot(const nx_io_cycle_probe_t *probe, nx_io_cycle_observation_t *out)

Copy bounded IRQ statistics under saved local interrupt exclusion.

Note

Privileged task only. Incoming masks are restored. For a task service producer, use its same executor or join it before sampling; IRQ masks do not join a different preempted task. This is not SMP exclusion. No provider, payload, request or counter is accessed under the mask.

Parameters:

  • probe – [in] Stable same-CPU sidecar and live producer binding.

  • out – [out] Distinct aligned copied result, unchanged on rejection.

Returns:

SUCCESS, INVALID or CONTEXT for ISR/unprivileged callers.

nx_result_t nx_uart_word_port_service_observed(const nx_uart_word_port_t *port, nx_io_cycle_probe_t *probe)

Dispatch exactly one word service step with optional raw observation.

Note

No additional ops table, worker, request or payload reference. Invalid observation never prevents dispatch. Caller proves complete private state, borrowed descriptors and buffers disjoint from observation storage; this API knows only face/method spans and context identity.

Parameters:

  • port – [in] Original stable face, methods and unique task executor.

  • probe – [inout] Optional live sidecar, or NULL to omit observation.

Returns:

SUCCESS proves dispatch only; INVALID/UNSUPPORTED describes the face.

nx_result_t nx_spi_dma_transaction_service_observed(const nx_spi_dma_transaction_port_t *port, nx_io_cycle_probe_t *probe)

Dispatch exactly one whole-CS DMA service step with raw observation.

Note

Same disjointness/executor rules as the word wrapper. No diagnostic failure releases a QUARANTINED loan or changes settlement authority.

Parameters:

  • port – [in] Original enhanced controller and its unique task executor.

  • probe – [inout] Optional stable disjoint sidecar, or NULL.

Returns:

SUCCESS after dispatch, INVALID or UNSUPPORTED for an invalid face.

struct nx_io_cycle_observation_t
#include <cycle_probe.h>

Copied raw counter facts; readable does not mean elapsed is known.

Note

A pair is a modulo-2^32 residue, including preemption and probe cost. Neither wrap count, reset, rate nor epoch continuity is established. elapsed_known is always false. No field establishes a passed budget, IRQ arrival latency, exclusive CPU time or a physical WCET bound. attempts includes a currently active attempt; other totals describe completed attempts. Totals saturate rather than wrap.

Public Members

uint32_t attempts
uint32_t raw_pairs
uint32_t unavailable_pairs
uint32_t reentries
uint32_t last_begin
uint32_t last_end
uint32_t last_modulo_cycles
uint32_t maximum_modulo_cycles
bool last_available
bool elapsed_known
bool active
struct nx_io_cycle_probe_t
#include <cycle_probe.h>

Optional zero-initialized sidecar; no default provider state grows.

Note

One physical vector or one unique task executor writes each sidecar. Different nested vectors require distinct sidecars. NMI, HardFault, other cores and other security states must not access this storage. Reset/reclaim only after all producers, tokens and readers have joined.

Public Members

nx_io_cycle_observation_t observation
struct nx_io_cycle_token_t
#include <cycle_probe.h>

Zero-initialized stack token; do not copy or rebind while active.

Public Members

nx_io_cycle_probe_t *owner
uint32_t before
bool available

diagnostic.h

A valid request snapshot has a nonzero epoch and finite observed_at; its deadline may be NX_DEADLINE_NEVER to mean no deadline. SERVICE facts require finite last_service_at and observed_at in the same monotonic domain, and a finite positive maximum_service_gap_us. Unknown groups stay unknown.

Explicit copied facts explain pending I/O without recovery.

Author

Nexus Team

Defines

NX_IO_FACT_REQUEST
NX_IO_FACT_STREAM
NX_IO_FACT_LIFECYCLE
NX_IO_FACT_OWNER
NX_IO_FACT_SERVICE
NX_IO_FACT_OBSERVERS
NX_IO_FACT_ALL
NX_IO_DIAG_QUEUED
NX_IO_DIAG_ACTIVE
NX_IO_DIAG_DRAINING
NX_IO_DIAG_QUARANTINED
NX_IO_DIAG_SETTLED
NX_IO_DIAG_DEADLINE_REACHED
NX_IO_DIAG_NOT_STARTED
NX_IO_DIAG_STOPPING
NX_IO_DIAG_OWNER_CLOSED
NX_IO_DIAG_NO_FREE_SLOT
NX_IO_DIAG_OWNER_PENDING
NX_IO_DIAG_SERVICE_OVERDUE
NX_IO_DIAG_OBSERVERS_PENDING
NX_IO_DIAG_STREAM_OUTSTANDING
NX_IO_DIAG_STREAM_CURSOR_BUSY
NX_IO_DIAG_STREAM_LOSS

Functions

nx_result_t nx_io_diagnose(const nx_io_diagnostic_facts_t *facts, nx_io_diagnostic_t *out)

Classify supplied observations without touching live I/O.

Note

Task/IRQ bounded fixed work, no MMIO, locks, allocation, service or recovery. Deadline and quarantine never revoke an accepted borrow. Callers must still drain controls and join observers before storage reuse.

Parameters:

  • facts – [in] Stable aligned copies; no pointer is retained.

  • out – [out] Aligned output distinct from every input span.

Returns:

SUCCESS, INVALID for malformed facts/alias, STATE for reversed service time. Rejection leaves output unchanged.

const char *nx_io_diagnostic_name(uint32_t finding)

Optional stable reason key for exactly one finding bit.

Note

Task/IRQ constant work, no formatting or allocation.

Parameters:

  • finding – [in] One NX_IO_DIAG flag, never a combined mask.

Returns:

Immutable static text, or NULL for zero/unknown/many bits.

struct nx_io_diagnostic_facts_t
#include <diagnostic.h>

Stable caller copies, with independently known fact groups.

Note

request/stream may be NULL; their presence establishes the corresponding group. known accepts only LIFECYCLE, OWNER, SERVICE and OBSERVERS. Zero-initialized unknown values never establish readiness, health or a missed service. OWNER fields may come from an owner observer only when its diagnostic_result succeeded. They describe admission and pending work, not the cause of a BUSY service result. SERVICE timestamps use the same monotonic domain; both are finite and maximum_service_gap_us is a finite positive declared budget. This helper reads no clock itself. Copies remain stable throughout this call. Observations need not be simultaneous across devices.

Public Members

const nx_request_observation_t *request
const nx_stream_observation_t *stream
uint32_t known
nx_time_us_t last_service_at
nx_time_us_t observed_at
nx_time_us_t maximum_service_gap_us
bool started
bool stopping
bool owner_accepting
bool owner_queued
bool owner_slot_available
bool observers_pending
struct nx_io_diagnostic_t
#include <diagnostic.h>

Independent findings and unavailable fact groups.

Note

Zero findings is not a health certificate. SETTLED does not establish successful I/O or joined observers. Outstanding stream blocks include producer, ready and consumer loans; cursor busy describes only the ordinary stream cursor. Loss is pending stream metadata in this snapshot, not a cumulative total; publication moves it into a later block.

Public Members

uint32_t findings
uint32_t unknown_facts

dma.h

Explicit DMA memory domains, physical streams and drain facts.

Author

Nexus Team

Defines

NX_DMA_MEMORY_READ
NX_DMA_MEMORY_WRITE

Enums

enum nx_dma_direction_t

Transfer direction determines device access to caller memory.

Values:

enumerator NX_DMA_TO_DEVICE
enumerator NX_DMA_FROM_DEVICE

Functions

nx_result_t nx_dma_buffer_validate(const nx_dma_memory_region_t *regions, size_t count, const void *data, size_t length, size_t alignment, nx_dma_direction_t direction)

Validate an entire buffer within one explicit memory domain.

Note

Bounded task/IRQ check, no MMIO, allocation or side effects.

Parameters:

  • regions – [in] Immutable SoC domains kept alive for this call.

  • count – [in] Positive number of domains.

  • data – [in] Nonempty caller buffer; never borrowed by this helper.

  • length – [in] Positive byte length, including all DMA accesses.

  • alignment – [in] Nonzero power-of-two transfer alignment.

  • direction – [in] Device reads or writes the supplied memory.

Returns:

Success, INVALID for malformed ranges/alignment or PERMISSION for a range outside the required DMA domain.

nx_result_t nx_dma_storage_validate(const nx_dma_memory_region_t *regions, size_t count, const void *storage, size_t capacity, size_t transfer_bytes, size_t alignment, size_t cache_line_bytes, nx_dma_direction_t direction)

Check an explicit owned reservation and its DMA payload.

Note

Bounded task/IRQ validation, no allocation/cache operation. Callers exclusively own all lines and padding until drain and acquire-observed SETTLED. This validates geometry only; it cannot prove ownership or replace provider admission, actual cache geometry, mode-specific length checks or cache maintenance. Cancellation never releases that obligation.

Parameters:

  • regions – [in] Immutable reviewed SoC DMA domains, not retained.

  • count – [in] Positive domain count.

  • storage – [in] Caller-owned reservation, distinct from live loans.

  • capacity – [in] Whole reservation bytes, including owned padding.

  • transfer_bytes – [in] Positive payload size, at most capacity.

  • alignment – [in] Nonzero power-of-two transfer alignment.

  • cache_line_bytes – [in] Zero for no cache constraint, otherwise a reviewed power-of-two line size; address and capacity must be exact multiples. The helper never rounds ranges.

  • direction – [in] Device access permission for the whole storage.

Returns:

SUCCESS, INVALID or PERMISSION; no memory access or borrow.

nx_result_t nx_dma_resources_validate(const nx_dma_resource_t *resources, size_t count)

Reject duplicate physical streams in an assembled resource set.

Note

Cold conflict check; the selected SoC must validate all identities against its actual topology before using them. This helper does not infer silicon support or allocate.

Parameters:

  • resources – [in] Immutable resource list, not retained.

  • count – [in] Resource count; zero allows a NULL list.

Returns:

Success, INVALID for a NULL nonempty list or reserved zero controller, BUSY for a duplicate physical engine.

nx_result_t nx_dma_drain_check(const nx_dma_drain_facts_t *facts)

Require engine, IRQ and peripheral drain independently.

Note

The provider must observe actual registers and ordering before setting these facts. This helper does not stop hardware.

Parameters:

  • facts – [in] Provider observations; not retained.

Returns:

Success only when all sources are detached and idle, BUSY while any source remains, INVALID for impossible counters.

struct nx_dma_memory_region_t
#include <dma.h>

Reviewed DMA-visible memory interval, never CPU accessibility.

Note

begin plus size must not wrap. Cache maintenance remains a provider responsibility on cached architectures.

Public Members

uintptr_t begin
size_t size
uint32_t permissions
struct nx_dma_resource_t
#include <dma.h>

Opaque physical engine and request selector identities.

Note

Controller zero is reserved as invalid. Other values have provider-defined meanings; the SoC validates its topology. Two selectors on the same controller/stream conflict.

Public Members

uint8_t controller
uint8_t stream
uint8_t channel
struct nx_dma_drain_facts_t
#include <dma.h>

Independent facts required before memory borrow release.

Note

remaining describes DMA memory transfers, not wire bytes. A zero counter never establishes peripheral_idle.

Public Members

size_t length
size_t remaining
bool engine_disabled
bool irq_detached
bool peripheral_idle

encoder.h

Optional raw modulo quadrature encoder observations.

Author

Nexus Team

Enums

enum nx_encoder_mode_t

Exact edge counting personality, never a freely combinable mask.

Values:

enumerator NX_ENCODER_MODE_UNKNOWN
enumerator NX_ENCODER_MODE_X2_TI1
enumerator NX_ENCODER_MODE_X2_TI2
enumerator NX_ENCODER_MODE_X4_TI12

Functions

nx_result_t nx_encoder_start(const nx_encoder_t *port)

Enable only the two cold-selected encoder inputs and counter.

Note

The provider never changes pins, rate, filtering or mode at runtime. Clock, pin and vector leases belong to cold assembly through close.

Parameters:

  • port – [in] One serialized privileged Thread-mode owner.

Returns:

SUCCESS or error; a failed write keeps recovery responsibility.

nx_result_t nx_encoder_stop(const nx_encoder_t *port)

Observe counter and input-source withdrawal before returning.

Note

Stop preserves the raw position. It does not release cold resources.

Parameters:

  • port – [in] The same serialized privileged Thread-mode owner.

Returns:

SUCCESS proves source withdrawal; failure retains the session.

nx_result_t nx_encoder_read(const nx_encoder_t *port, nx_encoder_sample_t *sample)

Read one modulo position without inferring travel across wraps.

Note

observed_at is software observation time, not a sensor edge aperture. Direction, speed, mechanical zero and unbounded signed position need external sampling bounds and product policy. A read cannot reconstruct missed full wraps. No separately read DIR bit is an atomic edge history.

Parameters:

  • port – [in] Serialized privileged Thread-mode owner.

  • sample – [out] Aligned separate output, unchanged on rejection.

Returns:

SUCCESS or INVALID/STATE/CONTEXT/UNSUPPORTED.

nx_result_t nx_encoder_state(const nx_encoder_t *port, nx_encoder_state_t *state)

Report exact counter width and selected silicon filter codes.

Note

Filter codes and their kernel clock do not qualify noise rejection, physical edge rate or electrical sensor/Board behavior.

Parameters:

  • port – [in] Serialized privileged Thread-mode owner.

  • state – [out] Aligned separate output, unchanged on rejection.

Returns:

SUCCESS or INVALID/STATE/CONTEXT/UNSUPPORTED.

struct nx_encoder_sample_t
#include <encoder.h>

One raw modulo counter and separate software observation time.

Public Members

nx_time_us_t observed_at
uint32_t count
struct nx_encoder_state_t
#include <encoder.h>

Immutable input/filter facts and actual counter enable state.

Public Members

uint32_t filter_clock_hz
nx_encoder_mode_t mode
uint8_t counter_bits
uint8_t filter_a
uint8_t filter_b
bool running
struct nx_encoder_ops_t
#include <encoder.h>

Shared methods; no ring, request, allocation, callback or worker.

Public Members

nx_result_t (*start)(void *context)
nx_result_t (*stop)(void *context)
nx_result_t (*read)(void *context, nx_encoder_sample_t *sample)
nx_result_t (*state)(const void *context, nx_encoder_state_t *state)
struct nx_encoder
#include <encoder.h>

Immutable identity; exact private state owns the whole controller.

Public Members

const nx_encoder_ops_t *ops
void *context

entropy.h

The entropy face supplies bounded, health-admitted source words. nx_entropy_fill uses a finite absolute deadline and erases the complete admitted output on a read failure. It does not allocate, create a worker or establish entropy quality; it is not a DRBG. A source’s existence does not authorize full entropy credit for a cryptographic library. See the explicit F407 constructor for its clock and shutdown prerequisites. GD32 entropy is not implemented.

Explicit entropy source and finite all-or-erased filling.

Author

Nexus Team

Typedefs

typedef struct nx_entropy_port nx_entropy_port_t

Static two-pointer source face with private mutable state.

Note

Caller serializes use and lifecycle; face/table/state outlive each call. No buffer or request is retained after return. Source enable, clock dependencies, recovery and stop belong to its explicit lifecycle owner, not to TLS or this face.

Functions

nx_result_t nx_entropy_port_try_read(const nx_entropy_port_t *port, uint32_t *word)

Try to copy one complete source word without waiting.

Note

Invalid public spans reject before provider access. This wrapper cannot infer the extent of an opaque context; the caller proves its complete disjointness. Provider rejection never substitutes fixed values or timestamps for entropy.

Parameters:

  • port – [in] Live immutable face on its serialized task executor

  • word – [out] Naturally aligned writable word, disjoint from face, table and the complete private provider state

Returns:

SUCCESS, BUSY, IO, STATE, INVALID or UNSUPPORTED

nx_result_t nx_entropy_fill(const nx_entropy_port_t *port, void *output, size_t bytes, const nx_clock_t *clock, nx_time_us_t deadline)

Fill exactly the requested bytes before a finite deadline.

Note

Task-only synchronous polling; no heap, worker or OS wait. BUSY causes another clock-bounded poll. The supplied clock must continue advancing throughout the call; changing its domain or stopping its timer violates the contract. NX_DEADLINE_NEVER is rejected. Complete words are emitted least-significant byte first; unused final-word bytes are discarded. A zero-byte request validates face and clock but performs no clock/source access and accepts NULL output. Preflight rejection leaves output unchanged. Once admitted, any error erases the complete output using volatile writes; no partial entropy may be consumed. Output is disjoint from face/table/clock and all their opaque live contexts. This function detects known-span aliases, not opaque extents. Crypto libraries own conditioning, DRBGs and trust policy.

Parameters:

  • port – [in] Live serialized source; no concurrent lifecycle change

  • output – [out] Writable byte span; NULL only for zero bytes

  • bytes – [in] Exact required output size, not an entropy estimate

  • clock – [in] Live monotonic microsecond clock in one stable domain

  • deadline – [in] Finite absolute deadline in that clock domain

Returns:

SUCCESS only for a complete fill; TIMEOUT, IO, STATE or source error; INVALID/UNSUPPORTED for preflight rejection

struct nx_entropy_ops_t
#include <entropy.h>

Shared immutable entropy-source methods.

Note

try_read is task-only and bounded, never waits for hardware. SUCCESS copies one complete health-admitted 32-bit word; BUSY means no word yet, IO means a source/health failure, STATE means unavailable/closed. Failure leaves output unchanged. The provider owns hardware health and initial sample handling. No deterministic fallback, conditioning, DRBG or cryptographic certification is implied.

Public Members

nx_result_t (*try_read)(void *context, uint32_t *word)
struct nx_entropy_port
#include <entropy.h>

Static two-pointer source face with private mutable state.

Note

Caller serializes use and lifecycle; face/table/state outlive each call. No buffer or request is retained after return. Source enable, clock dependencies, recovery and stop belong to its explicit lifecycle owner, not to TLS or this face.

Public Members

const nx_entropy_ops_t *ops
void *context

ethernet.h

Caller-owned untagged Ethernet II frames and receive loans.

Author

Nexus Team

Defines

NX_ETH_FRAME_MIN
NX_ETH_FRAME_MAX
NX_ETH_RX_STORAGE_MIN
NX_ETH_RX_CRC
NX_ETH_RX_LENGTH
NX_ETH_RX_FRAGMENT
NX_ETH_RX_UNSUPPORTED
NX_ETH_RX_DMA_ERROR
NX_ETH_RX_BACKPRESSURE

Functions

nx_result_t nx_eth_tx_prepare(nx_eth_tx_request_t *request, const void *data, size_t length, nx_time_us_t deadline)

Prepare an initialized, unborrowed request and its immutable frame.

Note

Task owner. Ethernet II only, 14..1514 bytes excluding FCS; no VLAN or length-coded 802.3. Failure changes no request or payload.

Parameters:

  • request – [inout] Initialized READY or consumed SETTLED storage.

  • data – [in] Immutable contiguous Ethernet II frame.

  • length – [in] Bytes excluding FCS, from 14 through 1514.

  • deadline – [in] Absolute provider-clock deadline or NEVER.

Returns:

Success, INVALID for frame/overlap, STATE while borrowed.

nx_result_t nx_eth_port_submit(const nx_eth_port_t *port, nx_eth_tx_request_t *request)

Admit one frame into caller-owned hardware descriptors.

Note

Privileged serialized task, masks clear. SUCCESS is ACCEPTED. Borrow includes request and frame until acquire-observed SETTLED. Completion reports MAC wire status, never delivery to another application.

Parameters:

  • port – [in] Stable face and live private assembly.

  • request – [inout] Prepared storage borrowed on acceptance.

Returns:

Success means ACCEPTED; BUSY/STATE/IO/invalid inputs reject.

nx_result_t nx_eth_port_cancel(const nx_eth_port_t *port, nx_eth_tx_request_t *request)

Close TX admission and drain the shared TX engine without replay.

Note

Task owner. Cancel is controller-wide: other pending TX requests also become CANCELLED. It never revokes a borrow. Stuck sources quarantine. Apply a confirmed link again after successful drain to reopen TX.

Parameters:

  • port – [in] Serialized task-owner face.

  • request – [inout] Live request accepted by this instance.

Returns:

Success requests drain; STATE for a foreign request.

nx_result_t nx_eth_port_service(const nx_eth_port_t *port)

Task-owner bounded progress; no worker, lock, pool or wait.

Parameters:

  • port – [in] Serialized task-owner face and live storage.

Returns:

Success, STATE before startup, or invalid context/input.

nx_result_t nx_eth_port_acquire(const nx_eth_port_t *port, nx_eth_rx_frame_t *frame)

Task-consumer complete-frame loan; EMPTY creates no borrow.

Parameters:

  • port – [in] Stable started instance and one consumer.

  • frame – [out] Exact immutable frame loan, not output storage borrow.

Returns:

Success, EMPTY without a loan, or invalid state/context.

nx_result_t nx_eth_port_release(const nx_eth_port_t *port, const nx_eth_rx_frame_t *frame)

Final consumer access; stale, foreign and double releases reject.

Note

A held descriptor is never rearmed, even at ring wrap or stop.

Parameters:

  • port – [in] The same provider identity as acquisition.

  • frame – [in] Exact acquired token after final consumer access.

Returns:

Success, STATE for an altered token, or invalid input/context.

nx_result_t nx_eth_port_state(const nx_eth_port_t *port, nx_eth_state_t *state)

Copy latched instance/link/error facts; output is not retained.

Parameters:

  • port – [in] Stable private instance.

  • state – [out] Unretained output, separate from all provider storage.

Returns:

Success, INVALID for output alias, or CONTEXT.

Apply external PHY observations, not auto-negotiate or invent link.

Note

Task owner; changing speed/duplex first requires explicit link-down and observed idle TX/RX engines and FIFOs. BUSY keeps the old mode. Reapplying an unchanged up fact is idempotent. Link-down closes admission and drains pending TX with IO; later up requires real quiescence. This is not a PHY power/reset/electrical proof.

Parameters:

  • port – [in] Serialized task-owner face.

  • link – [in] Observed up/speed/duplex fact, never a guess.

Returns:

Success, BUSY until real drain, or STATE/IO/context error.

nx_result_t nx_eth_port_stop(const nx_eth_port_t *port)

Close admission and withdraw MAC/DMA/IRQ sources with readback.

Note

Task owner. Closing rejects new RX loans; existing loans still release. BUSY retains hardware/storage/wake ownership; timeout quarantines pending TX. Held RX loans remain valid and must be released before SUCCESS. Caller joins IRQ/consumers before reclaiming storage.

Parameters:

  • port – [in] Live face and all storage, including held loans.

Returns:

Success releases sources; BUSY/IO retain remaining ownership.

nx_result_t nx_eth_port_attach_wake(const nx_eth_port_t *port, const nx_irq_wake_t *wake, uint8_t syscall_ceiling)

Bind an optional borrowed hint after actual IRQ-policy validation.

Note

Task owner with no pending TX; notify is bounded and legal in IRQ. Service does not invoke the IRQ hint from a task. Detach after stop.

Parameters:

  • port – [in] Started serialized task-owner face.

  • wake – [in] Borrowed IRQ hint; NULL requests detach.

  • syscall_ceiling – [in] Exact configured unshifted syscall ceiling.

Returns:

Success, BUSY while publishers live, or policy/context error.

struct nx_eth_tx_request_t
#include <ethernet.h>

Caller-owned immutable contiguous frame, excluding its hardware FCS.

Public Members

nx_request_t base
const uint8_t *data
size_t length
#include <ethernet.h>

Observed PHY fact, supplied explicitly by the external link owner.

Public Members

struct nx_eth_rx_frame_t
#include <ethernet.h>

Complete immutable frame; release requires this exact incarnation.

Note

data excludes FCS; storage stays live until matching release. Copying a token does not create a second loan. Timestamp is acquisition, not SOF.

Public Members

const uint8_t *data
size_t length
size_t slot
const void *identity
uint64_t epoch
nx_time_us_t timestamp_us
struct nx_eth_state_t
#include <ethernet.h>

Latched facts survive receive backpressure and failed wake hints.

Public Members

uint64_t received
uint64_t discarded
uint64_t unavailable_events
uint32_t receive_flags
size_t pending_tx
size_t held_rx
bool started
bool closing
bool fatal_bus_error
bool transmit_underflow
struct nx_eth_ops_t
#include <ethernet.h>

Public Members

nx_result_t (*submit)(void*, nx_eth_tx_request_t*)
nx_result_t (*cancel)(void*, nx_eth_tx_request_t*)
nx_result_t (*service)(void*)
nx_result_t (*acquire)(void*, nx_eth_rx_frame_t*)
nx_result_t (*release)(void*, const nx_eth_rx_frame_t*)
nx_result_t (*state)(void*, nx_eth_state_t*)
nx_result_t (*stop)(void*)
nx_result_t (*attach_wake)(void*, const nx_irq_wake_t*, uint8_t)
struct nx_eth_port
#include <ethernet.h>

Public Members

const nx_eth_ops_t *ops
void *context

ethernet_frames.h

Optional scatter-gather frame and MAC-clock loans.

Author

Nexus Team

Note

Physical qualification is separate from software validation.

Defines

NX_ETH_FRAMES_CAPTURE_CORRUPT

Capture diagnostics; UNKNOWN stamp remains unusable measurement.

Functions

nx_result_t nx_eth_frames_tx_prepare(nx_eth_frames_tx_request_t *request, const nx_eth_fragment_t *fragments, size_t fragment_count, bool timestamp, nx_time_us_t deadline)

Prepare unborrowed request storage without hardware effects.

Note

Serialized task owner. Validate nonempty fragments, overflow and the complete Ethernet II header across fragments; permit one in-band C-tag. Untagged length is 14..1514, tagged 18..1518, excluding FCS. Hardware inserts padding/FCS. Length-coded 802.3, QinQ and 0x88A8 reject. Failure preserves request and retains no references. Deadline is an absolute monotonic provider time, distinct from the PTP clock domain.

nx_result_t nx_eth_frames_port_submit(const nx_eth_frames_port_t *port, nx_eth_frames_tx_request_t *request)

ACCEPT one complete frame after all storage and slots are validated.

Note

Task owner, privileged/unmasked; no pool, heap, worker or OS lock. REJECTED retains no references or OWN effects. ACCEPTED borrows request, fragment array and every payload until acquire-observed SETTLED. One returned descriptor does not prove wire completion. transferred is whole frame bytes on proven MAC success, otherwise zero.

nx_result_t nx_eth_frames_port_cancel(const nx_eth_frames_port_t *port, nx_eth_frames_tx_request_t *request)

Request controller-wide TX withdrawal without replay.

Note

Other pending TX are cancelled too; observed completed wire success can win. No cancellation revokes a borrow. Missing drain proof keeps QUARANTINED loans. This does not reset the shared MAC/PTP/RX owner.

nx_result_t nx_eth_frames_port_service(const nx_eth_frames_port_t *port)

Bounded task progress; IRQ handles at most one descriptor per side.

nx_result_t nx_eth_frames_port_acquire(const nx_eth_frames_port_t *port, nx_eth_frames_rx_loan_t *loan, nx_eth_fragment_t *fragments, size_t capacity)

Acquire one complete frame with whole-frame capacity admission.

Note

One task consumer. EMPTY creates no loan; OVERFLOW for too few views leaves the complete frame queued and all outputs unchanged. Stop closes new acquisitions. Held descriptors are never rearmed at wrap or stop.

nx_result_t nx_eth_frames_port_release(const nx_eth_frames_port_t *port, const nx_eth_frames_rx_loan_t *loan)

Final consumer access; stale/altered/foreign/double release rejects.

nx_result_t nx_eth_frames_port_state(const nx_eth_frames_port_t *port, nx_eth_frames_state_t *state)

Copy latched facts to unretained output disjoint from every loan.

nx_result_t nx_eth_frames_port_clock(const nx_eth_frames_port_t *port, nx_io_timestamp_t *stamp)

Read a coherent current hardware counter in its own domain.

Note

No clock synchronization, UTC mapping, acquired-time fallback or PHY compensation. source is SERVICE_OBSERVATION, not an SFD event. The owner extends seconds wrap and rejects regression, overflow and ambiguous gaps; ticks are nanoseconds with rate1e9 and unknown uncertainty.

Apply explicit external PHY observation after real TX/RX quiet.

nx_result_t nx_eth_frames_port_stop(const nx_eth_frames_port_t *port)

Close admission and prove DMA/MAC/IRQ withdrawal before release.

Note

Held RX and captured publishers retain ownership. Any failure keeps unfinished leases. Do not flush a nonempty TX FIFO to fake quiet. Caller joins all external producers/consumers/observers separately.

nx_result_t nx_eth_frames_port_recover(const nx_eth_frames_port_t *port, nx_time_us_t deadline)

Explicit recovery by the exclusive MAC owner after failed drain.

Note

Task owner; finite absolute deadline. Held RX or captured publishers return BUSY without reset. Reset acknowledgement is mandatory before detached pending TX can settle with their locked terminal cause; never report wire success without its actual status. No auto replay. Reset invalidates the old hardware clock epoch and records an RX gap. Source failure/timeout retains QUARANTINED loans and recovery responsibility.

nx_result_t nx_eth_frames_port_attach_wake(const nx_eth_frames_port_t *port, const nx_irq_wake_t *wake, uint8_t syscall_ceiling)

Optional borrowed IRQ hint; validate actual priority, detach/join.

struct nx_eth_fragment_t
#include <ethernet_frames.h>

Immutable TX fragment; its bytes remain borrowed until SETTLED.

Public Members

const uint8_t *data
size_t length
struct nx_eth_vlan_t
#include <ethernet_frames.h>

Single in-band 0x8100 C-tag; TCI is host-order, with PCP/DEI/VID.

Public Members

uint16_t tci
bool present
struct nx_eth_frames_tx_request_t
#include <ethernet_frames.h>

One whole L2 frame, excluding preamble, hardware pad and hardware FCS.

Note

The fragment array and every fragment remain borrowed after ACCEPTED. Requested TX capture is optional: wire success may have an unavailable or corrupt stamp. Read stamp only after acquire-observed SETTLED.

Public Members

nx_request_t base
const nx_eth_fragment_t *fragments
size_t fragment_count
bool timestamp_requested
nx_io_timestamp_t stamp
uint32_t capture_flags
struct nx_eth_frames_rx_loan_t
#include <ethernet_frames.h>

One complete receive loan over all descriptors of one frame.

Note

Output fragment views exclude FCS, even when FCS spans two buffers. The views array is an unretained output. Its underlying bytes stay immutable until exact release. Copying this token creates no loan.

Public Members

const void *identity
uint64_t epoch
size_t first_slot
size_t descriptor_count
size_t fragment_count
size_t length
nx_time_us_t acquired_us
nx_io_timestamp_source_t acquired_source
nx_eth_vlan_t vlan
nx_io_timestamp_t stamp
uint32_t capture_flags
struct nx_eth_frames_state_t
#include <ethernet_frames.h>

Latched engine facts and selected clock epoch, not protocol state.

Public Members

nx_eth_state_t mac
uint32_t clock_epoch
uint64_t receive_gaps
uint32_t timestamp_resolution_ns
bool quarantined
struct nx_eth_frames_ops_t
#include <ethernet_frames.h>

Public Members

nx_result_t (*submit)(void*, nx_eth_frames_tx_request_t*)
nx_result_t (*cancel)(void*, nx_eth_frames_tx_request_t*)
nx_result_t (*service)(void*)
nx_result_t (*acquire)(void*, nx_eth_frames_rx_loan_t*, nx_eth_fragment_t*, size_t)
nx_result_t (*release)(void*, const nx_eth_frames_rx_loan_t*)
nx_result_t (*state)(void*, nx_eth_frames_state_t*)
nx_result_t (*clock)(void*, nx_io_timestamp_t*)
nx_result_t (*stop)(void*)
nx_result_t (*recover)(void*, nx_time_us_t)
nx_result_t (*attach_wake)(void*, const nx_irq_wake_t*, uint8_t)
struct nx_eth_frames_port
#include <ethernet_frames.h>

Public Members

const nx_eth_frames_ops_t *ops
void *context

exti.h

Static EXTI line bindings, bounded event storage and drain.

Author

Nexus Team

Defines

NX_EXTI_EVENT_LOSS
NX_EXTI_EVENT_COALESCED

Enums

enum nx_exti_edge_t

Values:

enumerator NX_EXTI_RISING
enumerator NX_EXTI_FALLING
enumerator NX_EXTI_BOTH

Functions

nx_result_t nx_exti_port_read(const nx_exti_port_t *port, nx_exti_event_t *events, size_t capacity, size_t *count)

Read queued EXTI events from an exact static line binding.

Parameters:

  • port – [inout] One consumer; bounded configured IRQ-producer storage.

  • events – [out] Caller destination, never retained.

  • capacity – [in] Destination event count.

  • count – [out] Copied events; loss is observable via event flags.

Returns:

Success, EMPTY or INVALID. No debounce policy or callbacks.

nx_result_t nx_exti_port_stop(const nx_exti_port_t *port)

Disable the line source, clear pending and drain its handler.

Note

Failed withdrawal may already have disabled part of the source. Retry and observe success before reclaiming event or wake storage. Face and state remain live while a shared dispatch domain still refers to them.

Parameters:

  • port – [inout] Execution owner; consumer/writers must quiesce first.

Returns:

Success proves no remaining accesses to event storage; BUSY or IO retains storage, wake targets and cleanup responsibility. Shared vectors preserve other lines.

nx_result_t nx_exti_port_attach_wake(const nx_exti_port_t *port, const nx_irq_wake_t *wake, uint8_t syscall_ceiling)

Attach or detach an explicit event/loss IRQ wake target.

Note

Actual shared-vector priority must satisfy the target. Stop and join publishers before freeing old target storage. Wake callbacks observe already-latched event or loss facts.

Parameters:

  • port – [in] Initialized line, controlled by one task executor.

  • wake – [in] Immutable live target, or NULL to detach.

  • syscall_ceiling – [in] Optional additional unshifted kernel-safe priority floor; cannot weaken generated policy. PRIMASK kernel targets require zero. Ignored without kernel calls.

Returns:

Success or CONTEXT/STATE/PERMISSION/UNSUPPORTED.

struct nx_exti_event_t
#include <exti.h>

Edge facts; timestamp precision and coalescing are provider-specific.

Note

LOSS is an independent boundary after older buffered facts and before later facts. Its edge is invalid; its timestamp is detection/report time, never a reconstructed missing edge. For COALESCED facts, edge may derive from sampled pin level after an IRQ and does not represent complete edge history.

Public Members

nx_time_us_t timestamp_us
uint32_t flags
uint8_t line
nx_exti_edge_t edge
struct nx_exti_ops_t
#include <exti.h>

Shared read-only methods using one provider state.

Note

Methods follow each public operation’s ownership contract. Missing optional methods report UNSUPPORTED.

Public Members

nx_result_t (*read)(void *context, nx_exti_event_t *events, size_t capacity, size_t *count)
nx_result_t (*stop)(void *context)
nx_result_t (*attach_wake)(void *context, const nx_irq_wake_t *wake, uint8_t syscall_ceiling)
struct nx_exti_port
#include <exti.h>

Immutable interface pointing to caller-owned state.

Note

Face and state outlive callers, IRQs and retained borrows. Factory lookup neither initializes nor acquires hardware.

Public Members

const nx_exti_ops_t *ops
void *context

flash.h

Full physical Flash geometry and explicit bounded regions.

Author

Nexus Team

Enums

enum nx_flash_program_flags

Physical programming requirements beyond unit alignment.

Values:

enumerator NX_FLASH_PROGRAM_REQUIRES_FRESH_ERASE

Functions

const nx_flash_geometry_t *nx_flash_port_geometry(const nx_flash_port_t *port)

Query exact physical Flash geometry without side effects.

Parameters:

  • port – [in] Selected exact-density physical Flash provider.

Returns:

Immutable geometry, or NULL for invalid port.

nx_result_t nx_flash_port_read(const nx_flash_port_t *port, uint32_t offset, void *data, size_t length)

Read bounded physical Flash without retaining destination.

Parameters:

  • port – [in] Fixed provider; no concurrent erase/program.

  • offset – [in] Physical relative offset.

  • data – [out] Destination not retained beyond return.

  • length – [in] Byte count; zero permitted with NULL data.

Returns:

Success or INVALID; no access on rejected range/overflow.

nx_result_t nx_flash_port_program(const nx_flash_port_t *port, uint32_t offset, const void *data, size_t length, nx_time_us_t deadline)

Program aligned physical Flash and settle all hardware pulses.

Note

Task-only CPU-active operation. Product owns execution-from- Flash stall, watchdog and power-loss policy. No RAM fake on MCU.

Note

With NX_FLASH_PROGRAM_REQUIRES_FRESH_ERASE, each programmed unit needs a successful erase and no later program pulse. Reading all 0xff cannot prove this on ECC Flash. A failed or interrupted pulse consumes its unit until the next successful sector erase. The caller owns this provenance; providers keep no implicit erase-history bitmap.

Note

All-0xff input units must not issue a program pulse. A provider may reject a visibly non-erased destination.

Parameters:

  • port – [inout] Single execution owner with valid voltage/clock policy.

  • offset – [in] Program-unit aligned physical offset.

  • data – [in] Aligned-length input retained only until return.

  • length – [in] Positive program-unit multiple.

  • deadline – [in] Absolute deadline checked between hardware pulses.

Returns:

Success or INVALID/TIMEOUT/IO. Return proves no remaining buffer/hardware access; an active pulse cannot be preempted.

nx_result_t nx_flash_port_erase(const nx_flash_port_t *port, uint32_t offset, size_t length, nx_time_us_t deadline)

Erase a whole physical sector range with pulse settlement.

Parameters:

  • port – [inout] Single execution owner.

  • offset – [in] Exact sector-start physical offset.

  • length – [in] Positive sum of whole sectors.

  • deadline – [in] Absolute deadline checked between erase pulses.

Returns:

Success or INVALID/TIMEOUT/IO; partial erase is possible on timeout/error. Return waits for current pulse to become idle.

nx_result_t nx_flash_region_validate(const nx_flash_region_t *region)

Validate region bounds against physical geometry.

Parameters:

  • region – [in] Explicit caller-owned region description.

Returns:

Success or INVALID; erase geometry is checked per operation.

nx_result_t nx_flash_region_read(const nx_flash_region_t *region, uint32_t offset, void *data, size_t length)

Read within an explicit physical region.

Parameters:

  • region – [in] Valid region.

  • offset – [in] Region-relative byte offset.

  • data – [out] Destination buffer.

  • length – [in] Byte count.

Returns:

Success or INVALID without access outside the region.

nx_result_t nx_flash_region_program(const nx_flash_region_t *region, uint32_t offset, const void *data, size_t length, nx_time_us_t deadline)

Program within an explicitly writable physical region.

Parameters:

  • region – [in] Valid writable region.

  • offset – [in] Region-relative aligned offset.

  • data – [in] Input buffer; borrowed until return only.

  • length – [in] Aligned positive length.

  • deadline – [in] Absolute pulse deadline.

Returns:

Success, INVALID/PERMISSION or underlying pulse result.

nx_result_t nx_flash_region_erase(const nx_flash_region_t *region, uint32_t offset, size_t length, nx_time_us_t deadline)

Erase whole physical sectors within a writable region.

Parameters:

  • region – [in] Explicit valid writable region.

  • offset – [in] Region-relative sector boundary.

  • length – [in] Sum of whole sector lengths.

  • deadline – [in] Absolute pulse deadline.

Returns:

Success, INVALID/PERMISSION or underlying pulse result.

struct nx_flash_sector_t
#include <flash.h>

Erase sector geometry, with offset relative to full physical Flash.

Public Members

uint32_t offset
uint32_t size
struct nx_flash_geometry_t
#include <flash.h>

Read-only physical geometry; platform reserves no product storage.

Note

program_flags states additional unit requirements. Zero does not waive the selected provider’s programming rules.

Public Members

uint32_t base_address
uint32_t size
uint32_t program_unit
const nx_flash_sector_t *sectors
size_t sector_count
uint32_t program_flags
struct nx_flash_region_t
#include <flash.h>

Explicit consumer-selected bounds; no implicit product partition.

Public Members

const nx_flash_port_t *port
uint32_t offset
uint32_t size
bool writable
struct nx_flash_ops_t
#include <flash.h>

Shared read-only methods using one provider state.

Note

Methods follow each public operation’s ownership contract. Missing optional methods report UNSUPPORTED.

Public Members

const nx_flash_geometry_t *(*geometry)(const void *context)
nx_result_t (*read)(const void *context, uint32_t offset, void *data, size_t length)
nx_result_t (*program)(void *context, uint32_t offset, const void *data, size_t length, nx_time_us_t deadline)
nx_result_t (*erase)(void *context, uint32_t offset, size_t length, nx_time_us_t deadline)
struct nx_flash_port
#include <flash.h>

Immutable interface pointing to caller-owned state.

Note

Face and state outlive callers, IRQs and retained borrows. Factory lookup neither initializes nor acquires hardware.

Public Members

const nx_flash_ops_t *ops
void *context

fwd.h

Lightweight identities for typed I/O faces.

Author

Nexus Team

Note

Include the matching public header before accessing its layout, operations, requests or value types. Forward identities neither construct nor acquire any device.

Typedefs

typedef struct nx_adc_group_port nx_adc_group_port_t

Opaque identity; complete contracts live in its public header.

typedef struct nx_adc_port nx_adc_port_t
typedef struct nx_advanced_pwm nx_advanced_pwm_t
typedef struct nx_can_fd_port nx_can_fd_port_t
typedef struct nx_can_port nx_can_port_t
typedef struct nx_encoder nx_encoder_t
typedef struct nx_eth_frames_port nx_eth_frames_port_t
typedef struct nx_eth_port nx_eth_port_t
typedef struct nx_exti_port nx_exti_port_t
typedef struct nx_flash_port nx_flash_port_t
typedef struct nx_gpio_port nx_gpio_port_t
typedef struct nx_i2c_endpoint nx_i2c_endpoint_t
typedef struct nx_i2c_long_endpoint nx_i2c_long_endpoint_t
typedef struct nx_i2c_port nx_i2c_port_t
typedef struct nx_lptim_port nx_lptim_port_t
typedef struct nx_mdio_port nx_mdio_port_t
typedef struct nx_pin_state_port nx_pin_state_port_t
typedef struct nx_pwm_adc nx_pwm_adc_t
typedef struct nx_pwm_group nx_pwm_group_t
typedef struct nx_pwm_port nx_pwm_port_t
typedef struct nx_rtc_port nx_rtc_port_t
typedef struct nx_spi_dma_transaction_endpoint nx_spi_dma_transaction_endpoint_t
typedef struct nx_spi_dma_transaction_port nx_spi_dma_transaction_port_t
typedef struct nx_spi_endpoint nx_spi_endpoint_t
typedef struct nx_spi_port nx_spi_port_t
typedef struct nx_spi_transaction_endpoint nx_spi_transaction_endpoint_t
typedef struct nx_timer_capture nx_timer_capture_t
typedef struct nx_uart_port nx_uart_port_t
typedef struct nx_uart_word_port nx_uart_word_port_t
typedef struct nx_usb_activation_port nx_usb_activation_port_t
typedef struct nx_usb_device_port nx_usb_device_port_t
typedef struct nx_usb_endpoint_port nx_usb_endpoint_port_t
typedef struct nx_watchdog_port nx_watchdog_port_t

gpio.h

Fixed GPIO authorization masks and bounded port operations.

Author

Nexus Team

Functions

nx_result_t nx_gpio_port_write(const nx_gpio_port_t *port, uint32_t set_mask, uint32_t reset_mask)

Atomically set/reset one port’s authorized output mask.

Note

Task/IRQ bounded, no wait. One serialized writer owns the binding. Stop/mode changes require writers and IRQ quiescence.

Parameters:

  • port – [in] Fixed initialized binding, no registry or OS lock.

  • set_mask – [in] Authorized bits to set.

  • reset_mask – [in] Authorized bits to reset; disjoint from set_mask.

Returns:

NX_SUCCESS or INVALID/PERMISSION before any register write.

nx_result_t nx_gpio_port_read(const nx_gpio_port_t *port, uint32_t *value)

Read one input snapshot restricted to the binding mask.

Parameters:

  • port – [in] Fixed initialized binding.

  • value – [out] Masked input snapshot; unchanged on error.

Returns:

NX_SUCCESS or NX_ERROR_INVALID. No cross-port simultaneity.

nx_result_t nx_gpio_port_toggle(const nx_gpio_port_t *port, uint32_t mask)

Toggle authorized outputs under the single-writer contract.

Note

Read-modify-write is not atomic against unrelated writes.

Parameters:

  • port – [in] Fixed output binding with a serialized writer.

  • mask – [in] Authorized subset to toggle.

Returns:

NX_SUCCESS or INVALID/PERMISSION before register writes.

struct nx_gpio_ops_t
#include <gpio.h>

Shared read-only methods using one provider state.

Note

Methods follow each public operation’s ownership contract. Missing optional methods report UNSUPPORTED.

Public Members

nx_result_t (*write)(void *context, uint32_t set_mask, uint32_t reset_mask)
nx_result_t (*read)(const void *context, uint32_t *value)
nx_result_t (*toggle)(void *context, uint32_t mask)
struct nx_gpio_port
#include <gpio.h>

Immutable interface pointing to caller-owned state.

Note

Face and state outlive callers, IRQs and retained borrows. Factory lookup neither initializes nor acquires hardware.

Public Members

const nx_gpio_ops_t *ops
void *context

i2c.h

Address endpoints, repeated START and explicit STOP settlement.

Author

Nexus Team

Defines

NX_I2C_MAX_MESSAGES

Maintained finite-message admission bounds, checked before hardware access.

NX_I2C_MAX_MESSAGE_BYTES

Functions

nx_result_t nx_i2c_endpoint_transaction(const nx_i2c_endpoint_t *endpoint, nx_i2c_message_t *messages, size_t count, nx_time_us_t deadline, size_t *transferred)

Execute a polling 7-bit-address message transaction.

Note

Task-only, one executor. No hidden scan or GPIO recovery. Failed bus recovery is never reported as transfer success.

Parameters:

  • endpoint – [in] Fixed address/controller binding.

  • messages – [inout] Message buffers; write data are not modified.

  • count – [in] One through NX_I2C_MAX_MESSAGES.

  • deadline – [in] Finite absolute provider-clock deadline.

  • transferred – [out] Provider byte progress across messages, including error returns. TX may count bytes handed to the data register before their wire/ACK outcome is known.

Returns:

Success or INVALID/UNSUPPORTED/CONTEXT/STATE/BUSY/TIMEOUT/ NACK/ARBITRATION/IO. Each message has 1..NX_I2C_MAX_MESSAGE_BYTES bytes; any message may read or write. Return releases buffers after STOP/abort drain. Controller settlement does not establish bus recovery.

nx_result_t nx_i2c_port_recover(const nx_i2c_port_t *port)

Recover an idle controller after a bus fault.

Parameters:

  • port – [inout] Single executor, no live transaction/buffer borrow.

Returns:

Success only when hardware bus idle is observed; otherwise BUSY/IO/UNSUPPORTED. Does not replay a failed transaction.

nx_result_t nx_i2c_request_prepare(nx_i2c_request_t *request, nx_i2c_message_t *messages, size_t count, nx_time_us_t deadline)

Prepare an unborrowed request without copying payload.

Note

Payloads cannot overlap control storage, nor a read span overlap an immutable write span. Limits match polling.

Parameters:

  • request – [inout] Initialized READY or consumed SETTLED storage

  • messages – [inout] One through eight complete descriptors

  • count – [in] Exact descriptor count

  • deadline – [in] Absolute provider-clock deadline

Returns:

SUCCESS, INVALID, UNSUPPORTED or STATE; no new loan

nx_result_t nx_i2c_request_validate(const nx_i2c_request_t *request)

Validate finite descriptors and payload/control separation.

Note

Bounded cold check. Provider separately validates state, context and DMA domains before acquiring any loan.

Parameters:

  • request – [in] Complete caller-owned request, not retained

Returns:

SUCCESS, INVALID or UNSUPPORTED without mutation

nx_result_t nx_i2c_endpoint_submit(const nx_i2c_endpoint_t *endpoint, nx_i2c_request_t *request)

Admit one finite asynchronous repeated-START transaction.

Note

Selected modes declare DMA domains. DMA completion alone never establishes wire/STOP drain or borrow release. Any admitted abort requires explicit local recover before reuse; recovery never replays or pulses Board GPIO lines.

Parameters:

  • endpoint – [in] Initialized fixed address and single executor

  • request – [inout] READY descriptor and all referenced storage

Returns:

SUCCESS means ACCEPTED; rejection retains no references

nx_result_t nx_i2c_endpoint_start_admitted(const nx_i2c_endpoint_t *endpoint, nx_i2c_request_t *request)

Start an already borrowed QUEUED request without readmission.

Note

Other errors require adapter settlement; no polling fallback.

Parameters:

  • endpoint – [in] Fixed address on the adapter’s exact controller

  • request – [inout] Adapter-admitted QUEUED storage

Returns:

SUCCESS hands execution to provider; BUSY retains QUEUED

bool nx_i2c_endpoint_on_port(const nx_i2c_endpoint_t *endpoint, const nx_i2c_port_t *port)

Prove controller identity without hardware effects.

Parameters:

  • endpoint – [in] Immutable addressed child

  • port – [in] Exact execution controller

Returns:

True only for matching provider state and compatible methods

nx_result_t nx_i2c_port_cancel(const nx_i2c_port_t *port, nx_i2c_request_t *request)

Request cancellation without reclaiming any storage.

Parameters:

  • port – [in] Same single executor as submit/service

  • request – [inout] Exact active descriptor, never a stale raw pointer

Returns:

SUCCESS begins drain; STATE for another request

void nx_i2c_port_service(const nx_i2c_port_t *port)

Advance deadline and STOP/DMA drain in bounded task context.

Note

Final publication follows source detach and local wire idle. Drain failure quarantines all storage. This invokes no payload completion callback and never automatically replays.

Parameters:

  • port – [in] Live single executor, serviced throughout stop

nx_result_t nx_i2c_port_stop(const nx_i2c_port_t *port)

Close admission and stop only after every borrower drains.

Parameters:

  • port – [in] Controller with external producers quiesced

Returns:

SUCCESS releases sources; BUSY requires continued service

nx_result_t nx_i2c_port_attach_wake(const nx_i2c_port_t *port, const nx_irq_wake_t *wake, uint8_t syscall_ceiling)

Attach one optional hint sink after actual IRQ policy checks.

Note

Task-only. Sink remains alive until successful stop/detach.

Parameters:

  • port – [in] Initialized asynchronous controller

  • wake – [in] Borrowed sink or NULL to detach after publisher exit

  • syscall_ceiling – [in] Cannot weaken selected kernel policy

Returns:

SUCCESS or rejection before replacing any live binding

struct nx_i2c_message_t
#include <i2c.h>

One message; a new message starts with repeated START, final with STOP.

Public Members

uint8_t *data
size_t length
bool read
struct nx_i2c_request_t
#include <i2c.h>

Caller-owned finite message sequence.

Note

Descriptors and payloads remain borrowed until SETTLED. Writes stay immutable; reads receive into caller storage. Cancellation, deadlines and quarantine never revoke loans.

Public Members

nx_request_t base
nx_i2c_message_t *messages
size_t count
struct nx_i2c_ops_t
#include <i2c.h>

Shared read-only methods using one provider state.

Note

Methods follow each public operation’s ownership contract. Missing optional methods report UNSUPPORTED.

Public Members

nx_result_t (*recover)(void *context)
nx_result_t (*cancel)(void *context, nx_i2c_request_t *request)
void (*service)(void *context)
nx_result_t (*stop)(void *context)
nx_result_t (*attach_wake)(void *context, const nx_irq_wake_t *wake, uint8_t syscall_ceiling)
struct nx_i2c_port
#include <i2c.h>

Immutable interface pointing to caller-owned state.

Note

Face and state outlive callers, IRQs and retained borrows. Factory lookup neither initializes nor acquires hardware.

Public Members

const nx_i2c_ops_t *ops
void *context
struct nx_i2c_endpoint_ops_t
#include <i2c.h>

Shared read-only methods using one provider state.

Note

Methods follow each public operation’s ownership contract. Missing optional methods report UNSUPPORTED.

Public Members

nx_result_t (*transaction)(void *context, nx_i2c_message_t *messages, size_t count, nx_time_us_t deadline, size_t *transferred)
nx_result_t (*submit)(void *context, nx_i2c_request_t *request)
nx_result_t (*start_admitted)(void *context, nx_i2c_request_t *request)
bool (*on_port)(const void *context, const nx_i2c_port_t *port)
struct nx_i2c_endpoint
#include <i2c.h>

Immutable interface pointing to caller-owned state.

Note

Face and state outlive callers, IRQs and retained borrows. Factory lookup neither initializes nor acquires hardware.

Public Members

const nx_i2c_endpoint_ops_t *ops
void *context

i2c_bus_clear.h

Explicit open-drain I2C bus clear with retained leases.

Author

Nexus Team

Defines

NX_I2C_BUS_CLEAR_MAX_PULSES

Maximum completed recovery low/high periods per attempt.

Functions

nx_result_t nx_i2c_bus_clear_init(nx_i2c_bus_clear_t *clear, nx_i2c_bus_clear_port_t port, nx_clock_t clock, nx_i2c_bus_clear_timing_t timing)

Bind explicit electrical operations without touching pins.

Parameters:

  • clear – [inout] Fresh zeroed session or a session with no lease.

  • port – [in] All five methods required; caller verifies electrical authorization rather than relying on generic GPIO APIs.

  • clock – [in] Required bounded monotonic read in one boot domain.

  • timing – [in] Reviewed nonzero low/high/STOP/poll durations.

Returns:

SUCCESS, INVALID or BUSY for a retained lease. Rejection leaves the session and external resources unchanged.

nx_result_t nx_i2c_bus_clear_run(nx_i2c_bus_clear_t *clear, nx_time_us_t deadline, nx_time_us_t cleanup_deadline, nx_i2c_bus_clear_result_t *result)

Clear one idle, authorized bus with at most nine pulses.

Note

Task-only, all other bus users quiescent. Timing evidence and actual open-drain behavior require physical HIL.

Parameters:

  • clear – [inout] Initialized session with no retained lease.

  • deadline – [in] Finite absolute primary-operation deadline.

  • cleanup_deadline – [in] Finite absolute STOP/lease deadline in the same clock domain, at or after deadline.

  • result – [out] Independent primary/cleanup and retained effects.

Returns:

Primary failure, otherwise cleanup result. Invalid inputs and an existing lease reject without callbacks or changing result. An expired primary deadline has no pin effects. Each released SCL must be physically HIGH before timing its high period. A frozen/reversed clock reports IO and exits rather than spinning. Every acquired attempt performs explicit STOP cleanup under its independent budget; failed STOP or release method retains the lease. If release succeeds after its deadline, cleanup reports TIMEOUT with lease_held false to preserve actual returned ownership. It never replays the failed I2C transaction or retries recovery pulses.

nx_result_t nx_i2c_bus_clear_finish(nx_i2c_bus_clear_t *clear, nx_time_us_t deadline, nx_i2c_bus_clear_result_t *result)

Retry only retained STOP cleanup and ownership return.

Parameters:

  • clear – [inout] Initialized session with a retained lease.

  • deadline – [in] New finite absolute cleanup deadline.

  • result – [out] Preserved primary/pulse count and latest cleanup.

Returns:

Latest cleanup result; INVALID/STATE rejects without effects. A proved STOP is not repeated after release fails. Failure retains the lease and must not trigger a new clear or transaction. Success does not change a failed primary operation into success.

struct nx_i2c_bus_clear_ops_t
#include <i2c_bus_clear.h>

Read-only methods for an authorized two-pin GPIO handoff.

Note

Task-only, one executor. acquire is a bounded, nonblocking handoff: success proves the controller, DMA, IRQs, other masters and pin users quiescent, both physical pins exclusively leased in reviewed open-drain GPIO mode, with both lines released. Failure retains no lease or effects. drive only sinks LOW or releases a pin; false never means drive HIGH. When scl_low is true, drive establishes SCL LOW before changing SDA, including a retry from unknown previous pin state. sample reads physical levels, not output latches. Methods are bounded and preserve the lease on errors. release restores the saved peripheral/pin ownership only on success; failure retains all lease/storage responsibility. wait_until uses the injected clock’s finite absolute domain and reaches target or reports an error within a caller- proved finite bound, even if the clock stops. Late waits cannot qualify an expired operation. No callback may recursively operate on this session or run a transaction. The adapter must verify reviewed open-drain, pull-up, voltage and two-pin authorization facts before acquire.

Public Members

nx_result_t (*acquire)(void *context)
nx_result_t (*drive)(void *context, bool scl_low, bool sda_low)
nx_result_t (*sample)(void *context, bool *scl_high, bool *sda_high)
nx_result_t (*wait_until)(void *context, nx_time_us_t target)
nx_result_t (*release)(void *context)
struct nx_i2c_bus_clear_port_t
#include <i2c_bus_clear.h>

Explicit immutable GPIO methods and caller-owned adapter state.

Public Members

const nx_i2c_bus_clear_ops_t *ops
void *context
struct nx_i2c_bus_clear_timing_t
#include <i2c_bus_clear.h>

Caller-selected electrical timings in microseconds.

Note

All fields are nonzero. low/high bound each clear pulse; stop_setup bounds the observed SCL-high to SDA-release interval. stretch_poll bounds the interval between actual SCL samples. Values need board/device electrical review; the mechanism supplies no universal safe defaults.

Public Members

uint32_t low_us
uint32_t high_us
uint32_t stop_setup_us
uint32_t stretch_poll_us
struct nx_i2c_bus_clear_result_t
#include <i2c_bus_clear.h>

Independent recovery and STOP/ownership-return results.

Note

pulses counts completed recovery low/high periods, not the STOP preparation edge. stop_observed proves the requested STOP sequence ended with both sampled lines HIGH. lease_held means the adapter, session and context must remain alive and no controller transaction may start. A cleanup failure never replaces the primary failure.

Public Members

nx_result_t primary
nx_result_t cleanup
uint8_t pulses
bool stop_observed
bool lease_held
struct nx_i2c_bus_clear_t
#include <i2c_bus_clear.h>

Caller-owned, zero-initialized single-executor session.

Note

Public fields are mechanism storage, not caller controls. Methods, context and clock outlive every retained lease. No allocation, worker, lock, transaction buffer or hidden retry exists. Abandoning a retained lease requires explicit product quarantine/reset responsibility.

Public Members

nx_i2c_bus_clear_port_t port
nx_clock_t clock
nx_i2c_bus_clear_timing_t timing
nx_i2c_bus_clear_result_t result
nx_time_us_t last_time
bool clock_observed
bool initialized

i2c_long.h

Optional bounded long I2C messages without extra START.

Author

Nexus Team

Defines

NX_I2C_LONG_MAX_MESSAGE_BYTES

Functions

nx_result_t nx_i2c_long_messages_validate(const nx_i2c_message_t *messages, size_t count)

Validate complete messages before acquiring any hardware.

Note

Each message has 1..65535 bytes. A mutable read cannot overlap a write span or descriptor storage. Write data and descriptors stay immutable throughout a transaction.

Parameters:

  • messages – [in] Caller-owned finite descriptors and data

  • count – [in] One through NX_I2C_MAX_MESSAGES

Returns:

SUCCESS, INVALID or UNSUPPORTED; no references retained

nx_result_t nx_i2c_long_endpoint_transaction(const nx_i2c_long_endpoint_t *endpoint, nx_i2c_message_t *messages, size_t count, nx_time_us_t deadline, size_t *transferred)

Execute finite messages without splitting address phases.

Note

Task-only, one executor shared with base I2C. Each message issues one START; only a following message issues repeated START. Hardware reload does not split messages. Final STOP and bus-idle observation precede successful return. Failure never replays a prefix. Failed abort drain cannot return and release borrowed storage. No implicit bus recovery occurs.

Parameters:

  • endpoint – [in] Selected optional long-message provider

  • messages – [inout] Descriptors and buffers borrowed until return

  • count – [in] One through NX_I2C_MAX_MESSAGES

  • deadline – [in] Finite absolute provider-clock deadline

  • transferred – [out] Register byte progress, including failure; TX count does not prove those bytes were ACKed on wire

Returns:

SUCCESS or INVALID/UNSUPPORTED/CONTEXT/STATE/BUSY/TIMEOUT/ NACK/ARBITRATION/IO after local controller drain

struct nx_i2c_long_ops_t
#include <i2c_long.h>

Shared read-only optional long-message implementation.

Public Members

nx_result_t (*transaction)(void *context, nx_i2c_message_t *messages, size_t count, nx_time_us_t deadline, size_t *transferred)
struct nx_i2c_long_endpoint
#include <i2c_long.h>

Optional immutable face; controller state is shared with base I2C.

Note

Face and private context outlive callers. No queue or heap is owned.

Public Members

const nx_i2c_long_ops_t *ops
void *context

lptim.h

Finite 16-bit counter shots in a distinct tick domain.

Author

Nexus Team

Functions

nx_result_t nx_lptim_request_prepare(nx_lptim_request_t *request, const nx_lptim_domain_t *domain, uint32_t ticks, nx_time_us_t deadline)

Prepare initialized unborrowed storage with copied shot metadata.

Note

Complete spans must be aligned, nonwrapping and disjoint. No loan, clock access, unit conversion or physical rate qualification occurs.

Parameters:

  • request – [inout] READY or consumed SETTLED with all observers joined.

  • domain – [in] Separate nonzero owner/generation value copied here.

  • ticks – [in] Exact positive count, 1..65536, in this domain’s ticks.

  • deadline – [in] Absolute Core monotonic deadline or NX_DEADLINE_NEVER.

Returns:

SUCCESS or INVALID/STATE; failure leaves every request byte unchanged.

nx_result_t nx_lptim_port_sample(const nx_lptim_port_t *port, nx_lptim_sample_t *sample)

Copy the live counter domain and declared units on one task owner.

Note

Open idle reports counter zero and not running. This finite interface does not reconstruct unobserved wraps or provide an absolute clock.

Parameters:

  • port – [in] Serialized immutable face; no concurrent model/lifecycle.

  • sample – [out] Separate aligned writable snapshot.

Returns:

SUCCESS, STATE if closed, or INVALID/UNSUPPORTED; rejected output is unchanged.

nx_result_t nx_lptim_port_submit(const nx_lptim_port_t *port, nx_lptim_request_t *request)

Borrow one READY shot after all idle/domain/range checks.

Note

Expired finite deadline rejects TIMEOUT before source effects. Reserve a final nonwrapping domain increment before acceptance: EXHAUSTED never abandons a previously accepted loan. Clock context lifetime, complete extent/disjointness and non-reentry are assembly responsibilities.

Parameters:

  • port – [in] Same serialized owner with a copied external Core clock.

  • request – [inout] Caller request; no queue or hidden worker.

Returns:

SUCCESS means ACCEPTED; INVALID/STATE/BUSY/TIMEOUT/EXHAUSTED/UNSUPPORTED rejects without retained references or effects.

nx_result_t nx_lptim_port_cancel(const nx_lptim_port_t *port, nx_lptim_request_t *request)

Accept cancellation, retaining the loan until proved withdrawal.

Note

Cancel/stop may win before unobserved event/expiry. First cause stays fixed; transferred counts final source progress at actual withdrawal.

Parameters:

  • port – [in] Same serialized executor; no implicit cross-task locking.

  • request – [inout] Exact active identity; foreign identity is not read.

Returns:

SUCCESS may still mean QUARANTINED; rejection is STATE/INVALID/UNSUPPORTED.

nx_result_t nx_lptim_port_service(const nx_lptim_port_t *port)

Observe deadline/event and continue bounded real withdrawal.

Note

First observed expiry wins over pending completion. Clear all source, pending and owner references before final release SETTLED publication.

Parameters:

  • port – [in] Same serialized task owner; no implicit source advance.

Returns:

SUCCESS when idle/settled, BUSY while active or withdrawal is held; INVALID/STATE/UNSUPPORTED may reject dispatch.

nx_result_t nx_lptim_port_stop(const nx_lptim_port_t *port)

Close admission; cancelled/expired is never a loan-release proof.

Note

Repeated clean stop is safe; it does not reset generation or lifetime. Tick rate/source and backup/Stop/VBAT continuity need separate hardware contracts; this interface establishes none of those qualifications.

Parameters:

  • port – [in] Serialized owner, with all external publishers quiescent.

Returns:

SUCCESS after detachment, BUSY retains quarantined storage; INVALID/STATE/UNSUPPORTED may reject dispatch.

struct nx_lptim_domain_t
#include <lptim.h>

Owner and nonwrapping shot incarnation, never an RTC/Core token.

Note

Identity is compared without dereference. Tokens/observers must be retired before the owner storage lifetime ends or its address is reused.

Public Members

const void *identity
uint64_t generation
struct nx_lptim_sample_t
#include <lptim.h>

Declared units and modulo counter, not an absolute time estimate.

Note

A complete 65536-tick shot wraps counter to zero. Counter zero alone cannot establish completion, idle, missed wraps or low-power continuity. tick_hz is a fixed declared rate, not physical oscillator accuracy.

Public Members

nx_lptim_domain_t domain
uint32_t tick_hz
uint16_t counter
bool running
struct nx_lptim_request_t
#include <lptim.h>

One caller-owned finite shot; transferred is final observed ticks.

Note

Initialize base first. After ACCEPTED keep the entire request live and caller immutable until acquire-observed SETTLED and external joins. A latched CANCELLED/TIMEOUT fixes the cause, not the final progress: held withdrawal may allow further source ticks before detachment.

Public Members

nx_request_t base
nx_lptim_domain_t domain
uint32_t ticks
struct nx_lptim_ops_t
#include <lptim.h>

Shared readonly methods implement the corresponding public contract.

Public Members

nx_result_t (*sample)(const void *context, nx_lptim_sample_t *sample)
nx_result_t (*submit)(void *context, nx_lptim_request_t *request)
nx_result_t (*cancel)(void *context, nx_lptim_request_t *request)
nx_result_t (*service)(void *context)
nx_result_t (*stop)(void *context)
struct nx_lptim_port
#include <lptim.h>

Immutable two-pointer face; provider storage remains private.

Public Members

const nx_lptim_ops_t *ops
void *context

mdio.h

Narrow Clause22 station management with absolute deadlines.

Author

Nexus Team

Functions

nx_result_t nx_mdio_read(const nx_mdio_port_t *port, uint8_t address, uint8_t reg, uint16_t *value, nx_time_us_t deadline)

Read one Clause22 PHY register without retaining output storage.

Note

Serialized privileged task, incoming masks clear; finite absolute deadline in the provider clock. Address and register are 0..31. BUSY rejects before new MMIO effects; timeout does not pretend busy cleared.

Parameters:

  • port – [in] Stable face and caller-owned execution context.

  • address – [in] Clause22 PHY address, from 0 through 31.

  • reg – [in] Clause22 register address, from 0 through 31.

  • value – [out] Written only after timely observed completion.

  • deadline – [in] Finite absolute provider-clock deadline.

Returns:

Success, BUSY without a new command, or timeout/input/context error.

nx_result_t nx_mdio_write(const nx_mdio_port_t *port, uint8_t address, uint8_t reg, uint16_t value, nx_time_us_t deadline)

Write one Clause22 PHY register, not a PHY-specific policy sequence.

Note

Same task/deadline rules as read. No IRQ-masked busy wait or fallback.

Parameters:

  • port – [in] Stable face and caller-owned execution context.

  • address – [in] Clause22 PHY address, from 0 through 31.

  • reg – [in] Clause22 register address, from 0 through 31.

  • value – [in] Exact 16-bit register value.

  • deadline – [in] Finite absolute provider-clock deadline.

Returns:

Success, BUSY without a new command, or timeout/input/context error.

struct nx_mdio_ops_t
#include <mdio.h>

Public Members

nx_result_t (*read)(void*, uint8_t, uint8_t, uint16_t*, nx_time_us_t)
nx_result_t (*write)(void*, uint8_t, uint8_t, uint16_t, nx_time_us_t)
struct nx_mdio_port
#include <mdio.h>

Public Members

const nx_mdio_ops_t *ops
void *context

model.h

Explicit host-model fixtures; no physical MCU qualification.

Author

Nexus Team

Functions

nx_result_t nx_native_clock_configure(bool enabled, nx_time_us_t now)

Switch host model to a deterministic clock domain.

Parameters:

  • enabled – [in] True selects manual clock, false real monotonic.

  • now – [in] Initial manual microsecond value, below UINT64_MAX.

Returns:

Success or INVALID. Caller must first settle every request; switching creates a new domain and invalidates old deadlines.

nx_result_t nx_native_clock_advance(uint64_t duration_us)

Advance deterministic time without an implicit hardware IRQ.

Parameters:

  • duration_us – [in] Positive or zero microsecond increment.

Returns:

Success, STATE outside manual mode or EXHAUSTED on overflow.

nx_result_t nx_native_gpio_configure(uint32_t mask, uint32_t initial)

Configure the fixed GPIO model after writer quiescence.

Parameters:

  • mask – [in] Authorized input/output bit mask.

  • initial – [in] Initial output snapshot within mask.

Returns:

Success or INVALID; no fake Board/electrical qualification.

void nx_native_gpio_input(uint32_t value)

Inject one GPIO input snapshot in the deterministic model.

Parameters:

  • value – [in] Physical-port snapshot; read masks unauthorized bits.

uint32_t nx_native_gpio_output(void)

Observe output state for a host behavioral assertion.

Returns:

Model output snapshot; no measured waveform semantics.

nx_result_t nx_native_uart_configure(const nx_native_uart_config_t *config)

Configure exact RX/TX fixture capacities on the fixed UART.

Parameters:

  • config – [in] Caller-owned selected-profile storage description.

Returns:

Success, INVALID or BUSY if an active request remains.

nx_result_t nx_native_uart_tx_validate(void *context, const nx_uart_tx_request_t *request)

Validate exact Native TX context for selected RS485 binding.

Note

Task-only; no model IRQ, admission, GPIO or state mutation.

Parameters:

  • context – [in] Configured Native UART face’s exact context.

  • request – [in] Live READY/QUEUED descriptor, never retained.

Returns:

Same pure rejectable checks as Native submit/start.

nx_result_t nx_native_uart_model_irq_configure(const nx_uart_port_t *binding, const nx_irq_policy_t *policy, const nx_irq_source_t *source)

Copy explicit IRQ facts into a quiescent host UART model.

Note

Task-only cold configuration; caller has stopped publishers. No active request, stream or attached wake may remain. Default preparation explicitly models BASEPRI/four-bit IRQs; this entry can model Baseline without inventing a SoC/Board.

Parameters:

  • binding – [in] Configured Native UART face with no IRQ users.

  • policy – [in] Immutable CPU/kernel facts copied during this call.

  • source – [in] Actual modeled publisher facts copied during call.

Returns:

Success, INVALID, CONTEXT, STATE or BUSY before side effects.

void nx_native_uart_irq_step(void)

Execute one deterministic TX IRQ byte/TC event.

Note

No actual hardware IRQ, latency or wire timing is simulated.

nx_result_t nx_native_uart_receive(uint8_t byte, uint32_t flags)

Inject one RX IRQ fact into bounded selected-profile storage.

Parameters:

  • byte – [in] Received byte; ignored for NO_BYTE status facts.

  • flags – [in] NX_UART_EVENT_* error facts; zero for normal reception.

Returns:

Success, OVERFLOW or STATE if disabled.

void nx_native_uart_fault(bool start_failure, bool hold_drain)

Configure start failure or inability to prove hardware drain.

Parameters:

  • start_failure – [in] Fail after direct admission, not as rejection.

  • hold_drain – [in] Retain QUARANTINED request until explicitly released.

size_t nx_native_uart_transmitted(void)

Observe captured TX bytes.

Returns:

Number captured in caller-owned tx_log.

nx_result_t nx_native_spi_configure(uint8_t *registers, size_t length)

Configure a fixed SPI echo or register-file model.

Parameters:

  • registers – [inout] Optional caller-owned register bytes; NULL is echo.

  • length – [in] Register capacity; zero only for echo mode.

Returns:

Success or INVALID; fixture has one serialized executor.

void nx_native_spi_fault(size_t fail_after, bool busy)

Inject bounded SPI partial failure or controller occupancy.

Parameters:

  • fail_after – [in] Byte index to fail at, SIZE_MAX disables fault.

  • busy – [in] True rejects transactions without CS/buffer access.

bool nx_native_spi_cs_active(void)

Check the modeled CS level after a transaction.

Returns:

True while model transaction owns active CS.

nx_result_t nx_native_i2c_configure(uint8_t *memory, size_t length, uint8_t address)

Configure one 7-bit-address register-file I2C model.

Parameters:

  • memory – [inout] Caller-owned register bytes retained by fixture.

  • length – [in] Positive register capacity, at most 256.

  • address – [in] Valid nonreserved 7-bit address.

Returns:

Success or INVALID.

void nx_native_i2c_fault(nx_result_t result, bool stuck)

Inject NACK, arbitration loss or a stuck bus.

Parameters:

  • result – [in] Success disables fault; NACK/ARBITRATION/IO supported.

  • stuck – [in] True makes explicit recovery fail until released.

nx_result_t nx_native_flash_configure(uint8_t *memory, const nx_flash_geometry_t *geometry)

Configure physical-geometry RAM model, clearly nonpersistent.

Parameters:

  • memory – [inout] Caller-owned geometry-sized bytes; erased to 0xff.

  • geometry – [in] Caller-owned immutable contiguous sector geometry with program_flags = 0. This NOR model does not implement hidden ECC erase-history requirements.

Returns:

Success, INVALID geometry or UNSUPPORTED program flags; no heap, product reserve or persistence.

void nx_native_flash_fault(size_t pulse_count)

Inject program/erase failure after complete modeled pulses.

Parameters:

  • pulse_count – [in] Complete pulses allowed; SIZE_MAX disables fault.

void nx_native_watchdog_boot(uint32_t causes)

Reset the watchdog fixture as a simulated new boot.

Note

Test-only; production IWDG cannot be disabled by this action.

Parameters:

  • causes – [in] Latched reset cause mask.

bool nx_native_watchdog_expired(void)

Observe expiration of the enabled deterministic IWDG.

Returns:

True once its nominal model deadline expires; latches IWDG.

nx_result_t nx_native_exti_configure(uint8_t line, nx_exti_edge_t edge, nx_exti_event_t *events, size_t capacity)

Configure exact storage for one static EXTI line.

Parameters:

  • line – [in] Zero through fifteen.

  • edge – [in] RISING/FALLING/BOTH selection.

  • events – [inout] Fixture-owned queue storage.

  • capacity – [in] Positive event capacity.

Returns:

Success or INVALID; quiesce producer/consumer before reset.

nx_result_t nx_native_exti_emit(uint8_t line, nx_exti_edge_t edge)

Inject a timestamped selected edge fact.

Parameters:

  • line – [in] Configured static line.

  • edge – [in] RISING or FALLING occurrence.

Returns:

Success, INVALID/STATE/OVERFLOW; loss remains observable.

nx_result_t nx_native_pwm_configure(uint32_t tick_hz, uint32_t period_ticks)

Configure fixed PWM model timer facts after writer quiescence.

Parameters:

  • tick_hz – [in] Positive post-prescaler frequency.

  • period_ticks – [in] Fixed shared-base positive period.

Returns:

Success or INVALID.

nx_result_t nx_native_adc_configure(const uint16_t *samples, size_t count, uint8_t resolution_bits, uint32_t reference_mv)

Configure fixed ADC raw-count sequence and format.

Parameters:

  • samples – [in] Fixture-owned nominal sample sequence.

  • count – [in] Positive channel count.

  • resolution_bits – [in] One through sixteen.

  • reference_mv – [in] Positive nominal reference voltage.

Returns:

Success or INVALID.

void nx_native_adc_fault(size_t sample_count)

Inject ADC failure after a prefix of complete samples.

Parameters:

  • sample_count – [in] Complete samples allowed; SIZE_MAX disables.

void nx_native_gpio_model_input(const nx_gpio_port_t *binding, uint32_t value)

Operate on the selected Native model face only.

Note

Null or foreign-provider faces return INVALID for status operations, zero/false for observations, and have no effect for injections. Referenced fixture storage remains owned by the caller; reconfiguration requires writer and IRQ quiescence and never revokes a live UART borrow.

uint32_t nx_native_gpio_model_output(const nx_gpio_port_t *binding)

Operate on the selected Native model face only.

Note

Null or foreign-provider faces return INVALID for status operations, zero/false for observations, and have no effect for injections. Referenced fixture storage remains owned by the caller; reconfiguration requires writer and IRQ quiescence and never revokes a live UART borrow.

nx_result_t nx_native_uart_model_configure(const nx_uart_port_t *binding, const nx_native_uart_config_t *config)

Operate on the selected Native model face only.

Note

Null or foreign-provider faces return INVALID for status operations, zero/false for observations, and have no effect for injections. Referenced fixture storage remains owned by the caller; reconfiguration requires writer and IRQ quiescence and never revokes a live UART borrow.

void nx_native_uart_model_irq_step(const nx_uart_port_t *binding)

Operate on the selected Native model face only.

Note

Null or foreign-provider faces return INVALID for status operations, zero/false for observations, and have no effect for injections. Referenced fixture storage remains owned by the caller; reconfiguration requires writer and IRQ quiescence and never revokes a live UART borrow.

nx_result_t nx_native_uart_model_receive(const nx_uart_port_t *binding, uint8_t byte, uint32_t flags)

Operate on the selected Native model face only.

Note

Null or foreign-provider faces return INVALID for status operations, zero/false for observations, and have no effect for injections. Referenced fixture storage remains owned by the caller; reconfiguration requires writer and IRQ quiescence and never revokes a live UART borrow.

void nx_native_uart_model_fault(const nx_uart_port_t *binding, bool start_failure, bool hold_drain)

Operate on the selected Native model face only.

Note

Null or foreign-provider faces return INVALID for status operations, zero/false for observations, and have no effect for injections. Referenced fixture storage remains owned by the caller; reconfiguration requires writer and IRQ quiescence and never revokes a live UART borrow.

size_t nx_native_uart_model_transmitted(const nx_uart_port_t *binding)

Operate on the selected Native model face only.

Note

Null or foreign-provider faces return INVALID for status operations, zero/false for observations, and have no effect for injections. Referenced fixture storage remains owned by the caller; reconfiguration requires writer and IRQ quiescence and never revokes a live UART borrow.

nx_result_t nx_native_spi_model_configure(const nx_spi_endpoint_t *binding, uint8_t *registers, size_t length)

Operate on the selected Native model face only.

Note

Null or foreign-provider faces return INVALID for status operations, zero/false for observations, and have no effect for injections. Referenced fixture storage remains owned by the caller; reconfiguration requires writer and IRQ quiescence and never revokes a live UART borrow.

void nx_native_spi_model_fault(const nx_spi_port_t *binding, size_t fail_after, bool busy)

Operate on the selected Native model face only.

Note

Null or foreign-provider faces return INVALID for status operations, zero/false for observations, and have no effect for injections. Referenced fixture storage remains owned by the caller; reconfiguration requires writer and IRQ quiescence and never revokes a live UART borrow.

bool nx_native_spi_model_cs_active(const nx_spi_endpoint_t *binding)

Operate on the selected Native model face only.

Note

Null or foreign-provider faces return INVALID for status operations, zero/false for observations, and have no effect for injections. Referenced fixture storage remains owned by the caller; reconfiguration requires writer and IRQ quiescence and never revokes a live UART borrow.

nx_result_t nx_native_i2c_model_configure(const nx_i2c_endpoint_t *binding, uint8_t *memory, size_t length, uint8_t address)

Operate on the selected Native model face only.

Note

Null or foreign-provider faces return INVALID for status operations, zero/false for observations, and have no effect for injections. Referenced fixture storage remains owned by the caller; reconfiguration requires writer and IRQ quiescence and never revokes a live UART borrow.

void nx_native_i2c_model_fault(const nx_i2c_port_t *binding, nx_result_t result, bool stuck)

Operate on the selected Native model face only.

Note

Null or foreign-provider faces return INVALID for status operations, zero/false for observations, and have no effect for injections. Referenced fixture storage remains owned by the caller; reconfiguration requires writer and IRQ quiescence and never revokes a live UART borrow.

nx_result_t nx_native_flash_model_configure(const nx_flash_port_t *binding, uint8_t *memory, const nx_flash_geometry_t *geometry)

Operate on the selected Native model face only.

Note

Null or foreign-provider faces return INVALID for status operations, zero/false for observations, and have no effect for injections. Referenced fixture storage remains owned by the caller; reconfiguration requires writer and IRQ quiescence and never revokes a live UART borrow.

void nx_native_flash_model_fault(const nx_flash_port_t *binding, size_t pulse_count)

Operate on the selected Native model face only.

Note

Null or foreign-provider faces return INVALID for status operations, zero/false for observations, and have no effect for injections. Referenced fixture storage remains owned by the caller; reconfiguration requires writer and IRQ quiescence and never revokes a live UART borrow.

void nx_native_watchdog_model_boot(const nx_watchdog_port_t *binding, uint32_t causes)

Operate on the selected Native model face only.

Note

Null or foreign-provider faces return INVALID for status operations, zero/false for observations, and have no effect for injections. Referenced fixture storage remains owned by the caller; reconfiguration requires writer and IRQ quiescence and never revokes a live UART borrow.

bool nx_native_watchdog_model_expired(const nx_watchdog_port_t *binding)

Operate on the selected Native model face only.

Note

Null or foreign-provider faces return INVALID for status operations, zero/false for observations, and have no effect for injections. Referenced fixture storage remains owned by the caller; reconfiguration requires writer and IRQ quiescence and never revokes a live UART borrow.

nx_result_t nx_native_exti_model_configure(const nx_exti_port_t *binding, uint8_t line, nx_exti_edge_t edge, nx_exti_event_t *events, size_t capacity)

Operate on the selected Native model face only.

Note

Null or foreign-provider faces return INVALID for status operations, zero/false for observations, and have no effect for injections. Referenced fixture storage remains owned by the caller; reconfiguration requires writer and IRQ quiescence and never revokes a live UART borrow.

nx_result_t nx_native_exti_model_emit(const nx_exti_port_t *binding, uint8_t line, nx_exti_edge_t edge)

Operate on the selected Native model face only.

Note

Null or foreign-provider faces return INVALID for status operations, zero/false for observations, and have no effect for injections. Referenced fixture storage remains owned by the caller; reconfiguration requires writer and IRQ quiescence and never revokes a live UART borrow.

nx_result_t nx_native_pwm_model_configure(const nx_pwm_port_t *binding, uint32_t tick_hz, uint32_t period_ticks)

Operate on the selected Native model face only.

Note

Null or foreign-provider faces return INVALID for status operations, zero/false for observations, and have no effect for injections. Referenced fixture storage remains owned by the caller; reconfiguration requires writer and IRQ quiescence and never revokes a live UART borrow.

nx_result_t nx_native_adc_model_configure(const nx_adc_port_t *binding, const uint16_t *samples, size_t count, uint8_t resolution_bits, uint32_t reference_mv)

Operate on the selected Native model face only.

Note

Null or foreign-provider faces return INVALID for status operations, zero/false for observations, and have no effect for injections. Referenced fixture storage remains owned by the caller; reconfiguration requires writer and IRQ quiescence and never revokes a live UART borrow.

void nx_native_adc_model_fault(const nx_adc_port_t *binding, size_t sample_count)

Operate on the selected Native model face only.

Note

Null or foreign-provider faces return INVALID for status operations, zero/false for observations, and have no effect for injections. Referenced fixture storage remains owned by the caller; reconfiguration requires writer and IRQ quiescence and never revokes a live UART borrow.

void nx_native_spi_model_async_configure(const nx_spi_port_t *binding, bool automatic_irq)

Choose explicit or automatic modeled SPI IRQ stepping.

Note

Quiesce the controller first. Automatic service advances at most one byte or a separate final idle fact per call; this does not model physical DMA or wire timing.

void nx_native_spi_model_irq_step(const nx_spi_port_t *binding)

Inject one bounded SPI byte/idle event on the exact Native bus.

void nx_native_spi_model_drain_hold(const nx_spi_port_t *binding, bool hold)

Inject inability to prove SPI hardware drain.

Note

Retained requests become QUARANTINED until hold is released and the executor services the bus again. No loan is revoked.

nx_result_t nx_native_uart_model_idle(const nx_uart_port_t *binding)

Inject UART IDLE and publish its current valid byte prefix.

Returns:

Success, EMPTY without a prefix, STATE outside a running block stream, BUSY while its modeled writer is active, or INVALID for a foreign provider. No producer loan is revoked.

nx_result_t nx_native_adc_model_trigger(const nx_adc_port_t *binding)

Inject one ADC timer-trigger scan into a free selected block.

Note

Each success publishes one interleaved raw-count scan; partial failed scans are detached and never published.

Returns:

Success, OVERFLOW while a required block remains held, IO for a failed scan, STATE after stop, or INVALID for a foreign provider. No hardware cadence or analog accuracy is claimed.

Variables

const nx_gpio_port_t *const nx_native_gpio

Fixed model bindings; no allocation, lookup, probe or construction.

const nx_uart_port_t *const nx_native_uart
const nx_spi_endpoint_t *const nx_native_spi
const nx_spi_port_t *const nx_native_spi_port
const nx_i2c_port_t *const nx_native_i2c_port
const nx_i2c_endpoint_t *const nx_native_i2c
const nx_flash_port_t *const nx_native_flash
const nx_watchdog_port_t *const nx_native_watchdog
const nx_exti_port_t *const nx_native_exti
const nx_pwm_port_t *const nx_native_pwm
const nx_adc_port_t *const nx_native_adc
struct nx_native_uart_config_t
#include <model.h>

UART storage belongs to the fixture until port stop and IRQ quiescence.

Public Members

nx_uart_rx_profile_t profile
void *rx_storage
size_t rx_capacity
uint8_t *tx_log
size_t tx_capacity
bool automatic_irq

observation.h

Explicit timestamp provenance and checked service dispatch.

Author

Nexus Team

Enums

enum nx_io_timestamp_source_t

Observation location; software time never implies hardware SOF.

Values:

enumerator NX_IO_TIMESTAMP_UNKNOWN
enumerator NX_IO_TIMESTAMP_HARDWARE_EVENT
enumerator NX_IO_TIMESTAMP_IRQ_OBSERVATION
enumerator NX_IO_TIMESTAMP_SERVICE_OBSERVATION
enumerator NX_IO_TIMESTAMP_ACQUIRE_OBSERVATION
enum nx_io_timestamp_budget_verdict_t

A timing bound can straddle a budget without proving either side.

Values:

enumerator NX_IO_TIMESTAMP_BUDGET_UNKNOWN
enumerator NX_IO_TIMESTAMP_BUDGET_WITHIN
enumerator NX_IO_TIMESTAMP_BUDGET_EXCEEDED

Functions

nx_result_t nx_io_timestamp_elapsed(const nx_io_timestamp_t *first, const nx_io_timestamp_t *last, nx_io_timestamp_delta_t *out)

Compare two explicitly related observed events.

Note

Task/IRQ pure constant work; no clock, hardware, allocation, lock or reference retention. Inputs may coincide. The caller proves event pairing and timestamp provenance. Different explicit source kinds may be compared to observe delivery latency, without relabeling either observation.

Parameters:

  • first – [in] Stable aligned first fact, not concurrently modified.

  • last – [in] Stable last fact in the same domain, epoch and rate.

  • out – [out] Distinct aligned result, unchanged on rejection.

Returns:

SUCCESS, INVALID for malformed/overlapping storage, UNSUPPORTED for UNKNOWN source, STATE for incompatible domains or reversed ticks, EXHAUSTED for bound overflow.

nx_result_t nx_io_timestamp_budget(const nx_io_timestamp_t *first, const nx_io_timestamp_t *last, uint64_t maximum_ticks, nx_io_timestamp_budget_result_t *out)

Compare a complete timing-error interval with a budget.

Note

Pure O(1) Task/IRQ work with no clock access or retention. WITHIN requires upper <= maximum; EXCEEDED requires lower > maximum. An overlapping or unknown error interval gives UNKNOWN. SUCCESS alone does not mean within budget. The existing timestamp-owner/provenance contract applies: this does not extend raw DWT, validate epoch continuity, synchronize sampling, establish IRQ arrival or prove WCET.

Parameters:

  • first – [in] Stable aligned extended timestamp, causally paired.

  • last – [in] Stable aligned fact in the same domain/epoch/rate.

  • maximum_ticks – [in] Inclusive maximum, in the stated tick units.

  • out – [out] Distinct aligned result, unchanged on rejection.

Returns:

SUCCESS, INVALID/UNSUPPORTED/STATE as elapsed, or EXHAUSTED when the uncertainty sum or upper bound cannot fit.

nx_result_t nx_uart_port_service_checked(const nx_uart_port_t *port)

Dispatch the selected UART service or explain its absence.

Note

Same context, serialization and lifetime rules as ordinary service. SUCCESS proves dispatch only, not progress, health, settlement or permission to reclaim storage. This reads no request and adds no state, lock or hidden worker.

Parameters:

  • port – [in] Live immutable face and initialized provider state.

Returns:

SUCCESS after one dispatch, INVALID for malformed face, UNSUPPORTED when no service method exists.

nx_result_t nx_spi_port_service_checked(const nx_spi_port_t *port)

Dispatch the selected SPI service or explain its absence.

Note

Same context and owner rules as nx_spi_port_service; SUCCESS establishes dispatch only, never settlement.

Parameters:

  • port – [in] Live immutable face and initialized provider state.

Returns:

SUCCESS after dispatch, INVALID or UNSUPPORTED.

nx_result_t nx_i2c_port_service_checked(const nx_i2c_port_t *port)

Dispatch the selected I2C service or explain its absence.

Note

Same context and owner rules as nx_i2c_port_service; SUCCESS establishes dispatch only, never settlement.

Parameters:

  • port – [in] Live immutable face and initialized provider state.

Returns:

SUCCESS after dispatch, INVALID or UNSUPPORTED.

struct nx_io_timestamp_t
#include <observation.h>

Explicit, caller-supplied time fact without clock access.

Note

ticks is extended, monotonically increasing within one nonzero domain/epoch. Its owner extends counter wrap and changes epoch on reset, discontinuity or rate change. Domain and epoch are assembly-local identities, not clocks synchronized across cores, security domains or devices. UNKNOWN carries no usable measurement. Frequency is exact stated ticks/second, not measured accuracy. A known zero uncertainty states zero error; unknown uncertainty has a separate flag. These facts do not establish physical precision, causal pairing or event identity by themselves.

Public Members

uint64_t ticks
uint64_t ticks_per_second
uint32_t domain
uint32_t epoch
uint64_t uncertainty_ticks
nx_io_timestamp_source_t source
bool uncertainty_known
struct nx_io_timestamp_delta_t
#include <observation.h>

Delta in one common clock domain, with stated error bound.

Note

When uncertainty_known is false, uncertainty_ticks is zero and describes no error bound. No conversion, rounding or synchronization across clocks is implicit.

Public Members

uint64_t ticks
uint64_t ticks_per_second
uint64_t uncertainty_ticks
bool uncertainty_known
struct nx_io_timestamp_budget_result_t
#include <observation.h>

Inclusive interval and budget comparison in the stated tick domain.

Note

lower/upper are usable only when delta.uncertainty_known is true. Otherwise both are zero and verdict is UNKNOWN, never an exact zero.

Public Members

nx_io_timestamp_delta_t delta
uint64_t lower_ticks
uint64_t upper_ticks
nx_io_timestamp_budget_verdict_t verdict

pin_state.h

Explicit static default and sleep pad states.

Author

Nexus Team

Enums

enum nx_pin_state_selection_t

Only explicitly authored GPIO states; no implicit power policy.

Values:

enumerator NX_PIN_STATE_DEFAULT
enumerator NX_PIN_STATE_SLEEP
enumerator NX_PIN_STATE_INVALID

Functions

nx_result_t nx_pin_state_select(const nx_pin_state_port_t *port, nx_pin_state_selection_t state)

Select one explicitly supported GPIO state without waiting.

Note

Serialized same-CPU privileged Thread with incoming masks clear. No ISR/NMI, competing pad/RCC owner, AF switching, clock transition, wake or retention policy. Partial failure retains the lease; retry an explicit supported target or let the owner perform checked cleanup. This does not prove physical transients, external bias or PCB safety.

Parameters:

  • port – [in] Exclusive static pad/gate lease, with all writers quiescent.

  • state – [in] Default or sleep; neither name implies electrical safety.

Returns:

SUCCESS after actual target readback, or INVALID/UNSUPPORTED/ CONTEXT/STATE/BUSY/IO while preserving provider ownership.

struct nx_pin_state_ops_t
#include <pin_state.h>

One statically owned provider; no discovery or per-register dispatch.

Public Members

nx_result_t (*select)(void *context, nx_pin_state_selection_t state)
struct nx_pin_state_port
#include <pin_state.h>

Immutable face; provider storage and plans outlive every use.

Public Members

const nx_pin_state_ops_t *ops
void *context

pwm_adc.h

Optional finite coherent PWM / triggered ADC window.

Author

Nexus Team

Functions

nx_result_t nx_pwm_adc_prepare(nx_pwm_adc_request_t *request, uint16_t *samples, size_t sample_count, const nx_pwm_group_frame_t *frame, nx_time_us_t deadline)

Prepare distinct unborrowed request, frame and sample storage.

Note

Request, sample span, source frame descriptor and duty span must be naturally aligned, nonwrapping and disjoint. The caller has consumed prior results and joined every adapter observer before preparing again. NX_DEADLINE_NEVER is rejected; an expired finite deadline can be prepared but cannot admit new physical effects. Preparation does not access sample contents, borrow hardware or establish rate/region support. Failure leaves the initialized request unchanged.

Parameters:

  • request – [inout] Initialized READY or fully consumed SETTLED storage.

  • samples – [out] Naturally aligned writable caller sample array.

  • sample_count – [in] Positive exact sample count; provider checks DMA.

  • frame – [in] Readable descriptor copied by value during this call only; its complete duty array remains live through SETTLED.

  • deadline – [in] Finite absolute monotonic deadline for the whole window.

Returns:

SUCCESS or INVALID/STATE; no hardware access or provider borrow.

nx_result_t nx_pwm_adc_submit(const nx_pwm_adc_t *port, nx_pwm_adc_request_t *request)

Admit and arm one complete finite window on the unique task owner.

Note

Post-admission arm/prime failures drain under the accepted request. Normal completion stops the PWM sources before SETTLED and never rearms. DMA TC alone is insufficient for completion or safe output. An error/cancellation reports zero guaranteed valid samples; an aborted DMA remaining count cannot establish a valid prefix. A successful window reports exactly sample_count. After successful ordinary completion, another explicitly prepared submission may begin; an explicit stop or latched fault requires cold close/reinitialization. Provider checks context, fixed frame, region and overlap with all cold descriptors/MMIO before admission. The complete duty frame is constant for the window; sample count does not promise an exact PWM pulse count. Without a trusted completion timestamp, completion first observed at or after the request deadline reports TIMEOUT, even if DMA is already complete. This conservative observation rule promises no physical execution-time bound and never relaxes the required source drain.

Parameters:

  • port – [in] Initialized stable selected coupled face and cold leases.

  • request – [inout] Exact READY window prepared by the caller.

Returns:

SUCCESS means ACCEPTED, including a possibly already SETTLED error. Rejection means no retained pointer, payload access or new effect.

nx_result_t nx_pwm_adc_cancel(const nx_pwm_adc_t *port, nx_pwm_adc_request_t *request)

Latch cancellation while retaining the exact live window loan.

Note

Cancellation is task-local and does not provide a cross-task stable identity. Use the established adapter slot/epoch mechanism externally. A prior terminal fault is retained; cancellation never clears it.

Parameters:

  • port – [in] Same live coupled face and serialized privileged task.

  • request – [inout] Exact admitted request, still live until SETTLED.

Returns:

SUCCESS starts/observes cancellation, never implies SETTLED.

nx_result_t nx_pwm_adc_service(const nx_pwm_adc_t *port)

Advance bounded completion or source drain on the same task owner.

Note

No hidden worker/wait/allocation. Only observed source/vector withdrawal permits final pointer detach and release publication.

Parameters:

  • port – [in] Same live coupled face and serialized privileged task.

Returns:

SUCCESS after progress/settlement, BUSY while drain remains, or a fault requiring continued recovery service and explicit stop.

nx_result_t nx_pwm_adc_stop(const nx_pwm_adc_t *port)

Close admission and attempt final drain without revoking a loan.

Note

Continue the unique service/stop until quiet. Cold close additionally joins vectors and restores saved leases. Fault recovery does not automatically restart PWM or resume acquisition. SUCCESS does not release pads, clocks or private storage. Those cold leases remain held until the platform’s final joined close succeeds.

Parameters:

  • port – [in] Same live coupled face and serialized privileged task.

Returns:

SUCCESS proves stopped sources; BUSY/IO retains recovery storage.

nx_result_t nx_pwm_adc_state(const nx_pwm_adc_t *port, nx_pwm_adc_state_t *state)

Copy exact fixed facts and observed active/fault/quarantine state.

Note

State is an observation, not a source-drain or release operation.

Parameters:

  • port – [in] Same live coupled face and serialized privileged task.

  • state – [out] Distinct aligned output, unchanged on rejection.

Returns:

SUCCESS, INVALID/STATE/CONTEXT or UNSUPPORTED for a missing method.

struct nx_pwm_adc_request_t
#include <pwm_adc.h>

One finite window; transferred counts are raw samples, never bytes.

Note

Initialize base before first preparation. After successful admission, the request and duty array remain live and caller-immutable through acquire-observed SETTLED. The writable sample span belongs exclusively to the provider; the caller neither reads nor writes it while borrowed. Frame metadata is copied at preparation. No later shadow commit, automatic rearm, control algorithm or engineering-unit conversion is part of this finite-window interface. Hardware-specific sample storage and integer encoding are reported by state.format.

Public Members

nx_request_t base

Borrow and release publication state.

uint16_t *samples

Exclusive writable raw sample storage.

size_t sample_count

Positive number of requested samples.

nx_pwm_group_frame_t frame

Copied metadata; duty array is borrowed.

struct nx_pwm_adc_state_t
#include <pwm_adc.h>

Exact selected facts and observed source/recovery state.

Note

Format describes actual supported hardware. It does not establish aperture timestamps, analog accuracy, PWM duty epochs, IRQ latency, the number of output pulses or an inspected physical circuit.

Public Members

nx_adc_format_t format

Actual integer storage and provenance.

uint32_t tick_hz

PWM counter ticks per second.

uint32_t period_ticks

Fixed period in counter ticks.

uint32_t trigger_ticks

Fixed phase in counter ticks.

uint32_t deadtime_ticks

Deadtime in separate deadtime_hz units.

uint32_t deadtime_hz

Deadtime clock; never inferred from PSC.

size_t pwm_channels

Complete fixed-order frame width.

size_t max_samples

Provider/DMA finite-window count bound.

bool running

Observed source/counter activity.

bool fault

Latched fault requiring cold recovery.

bool quarantined

Incomplete withdrawal retains ownership.

struct nx_pwm_adc_ops_t
#include <pwm_adc.h>

Selected-only operations; no growth to ordinary PWM/ADC tables.

Note

Each callback implements its corresponding public function contract. One privileged task serializes submit/cancel/service/stop/state; IRQs only latch bounded physical facts into the same private owner. Missing callbacks return UNSUPPORTED. There is no allocating or hidden worker.

Public Members

nx_result_t (*submit)(void *context, nx_pwm_adc_request_t *request)
nx_result_t (*cancel)(void *context, nx_pwm_adc_request_t *request)
nx_result_t (*service)(void *context)
nx_result_t (*stop)(void *context)
nx_result_t (*state)(const void *context, nx_pwm_adc_state_t *state)
struct nx_pwm_adc
#include <pwm_adc.h>

Immutable cold-selected identity, never an allocating factory.

Note

Face, operations, context and cold configuration outlive every request and IRQ publisher. One coupled face owns all selected hardware; no independently startable PWM-group or ADC face exposes that hardware.

Public Members

const nx_pwm_adc_ops_t *ops
void *context

pwm_group.h

Fixed-base atomic multi-channel PWM shadow commits.

Author

Nexus Team

Functions

nx_result_t nx_pwm_group_commit(const nx_pwm_group_t *port, const nx_pwm_group_frame_t *frame)

Stage a complete channel group and its internal trigger comparison.

Note

Provider declares exact channel count, trigger range and ISR budget. Duties include zero and period. All channels share one fixed base. A failed partial hardware write must disable output and retain fault responsibility rather than release a mixed group to the next update. Stop is explicit; automatic output recovery after break is prohibited.

Parameters:

  • port – [in] One serialized privileged task/configurable-IRQ owner.

  • frame – [in] Complete readable batch; no pointer is retained on return.

Returns:

SUCCESS means one coherent group is staged for a hardware update, not that this update already happened. Invalid input has no effects.

nx_result_t nx_pwm_group_start(const nx_pwm_group_t *port)

Start only from disabled outputs and an inactive, cleared break.

Parameters:

  • port – [in] Serialized privileged task owner of all cold leases.

Returns:

SUCCESS or an error retaining cleanup and any fault responsibility.

nx_result_t nx_pwm_group_stop(const nx_pwm_group_t *port)

Withdraw master output, channels, counter and owned IRQ sources.

Note

This source-level promise does not certify the external circuit’s electrical safety. Board idle and publisher join belong to assembly.

Parameters:

  • port – [in] Same privileged task owner; cold pin/vector leases persist.

Returns:

SUCCESS proves source withdrawal; failure retains responsibility.

nx_result_t nx_pwm_group_clear_fault(const nx_pwm_group_t *port)

Explicitly clear fault while disabled after checking actual break.

Parameters:

  • port – [in] Serialized privileged task recovery owner.

Returns:

SUCCESS only after coherent shadows and break acknowledgment; never enables outputs. Product power-stage recovery policy stays external.

nx_result_t nx_pwm_group_state(const nx_pwm_group_t *port, nx_pwm_group_state_t *state)

Read fixed units and observed enable/fault facts without starting.

Parameters:

  • port – [in] Serialized privileged task owner.

  • state – [out] Separate writable output, unchanged on rejection.

Returns:

SUCCESS or INVALID/STATE/CONTEXT/UNSUPPORTED.

struct nx_pwm_group_frame_t
#include <pwm_group.h>

One synchronous shadow batch; channel order is fixed by assembly.

Public Members

const uint32_t *duty_ticks
size_t channel_count
uint32_t trigger_ticks
struct nx_pwm_group_state_t
#include <pwm_group.h>

Fixed units, software fault latch and actual hardware enable state.

Public Members

uint32_t period_ticks
uint32_t tick_hz
uint32_t deadtime_ticks
uint32_t deadtime_hz
size_t channel_count
bool running
bool fault
bool quarantined
struct nx_pwm_group_ops_t
#include <pwm_group.h>

Shared operations; commit must prevent partial shadow publication.

Public Members

nx_result_t (*commit)(void *context, const nx_pwm_group_frame_t *frame)
nx_result_t (*start)(void *context)
nx_result_t (*stop)(void *context)
nx_result_t (*clear_fault)(void *context)
nx_result_t (*state)(const void *context, nx_pwm_group_state_t *state)
struct nx_pwm_group
#include <pwm_group.h>

Immutable identity with no default-device state or allocation.

Public Members

const nx_pwm_group_ops_t *ops
void *context

rtc.h

Raw calendar and one finite alarm in its own time domain.

Author

Nexus Team

Functions

nx_result_t nx_rtc_calendar_validate(const nx_rtc_calendar_t *calendar)

Validate raw calendar fields without changing any storage.

Parameters:

  • calendar – [in] Readable naturally aligned value.

Returns:

SUCCESS or INVALID; no clock or provider access.

nx_result_t nx_rtc_alarm_validate(const nx_rtc_alarm_t *alarm)

Validate the finite alarm pattern’s day and time ranges.

Parameters:

  • alarm – [in] Readable naturally aligned value.

Returns:

SUCCESS or INVALID; not a promise that a provider can arm it.

nx_result_t nx_rtc_request_prepare(nx_rtc_request_t *request, const nx_rtc_domain_t *domain, const nx_rtc_alarm_t *alarm, nx_time_us_t deadline)

Copy a domain/pattern into initialized unborrowed caller storage.

Note

Inputs must be complete, aligned, nonwrapping spans disjoint from request. This cold operation takes no loan and cannot know the complete extent of an opaque provider or clock context. Admission checks the known provider spans; assembly owns opaque-context disjointness.

Parameters:

  • request – [inout] READY or consumed SETTLED storage, all joins complete.

  • domain – [in] Nonzero owner/generation copied during this call.

  • alarm – [in] Valid pattern copied during this call.

  • deadline – [in] Absolute Core monotonic deadline or NX_DEADLINE_NEVER.

Returns:

SUCCESS or INVALID/STATE; every failure leaves request unchanged.

nx_result_t nx_rtc_port_read(const nx_rtc_port_t *port, nx_rtc_snapshot_t *snapshot)

Copy a set calendar/domain on the single serialized task executor.

Parameters:

  • port – [in] Valid immutable live face; no concurrent lifecycle writer.

  • snapshot – [out] Separate aligned writable output.

Returns:

SUCCESS or STATE for closed/unset, INVALID or UNSUPPORTED; failure leaves output unchanged.

nx_result_t nx_rtc_port_set(const nx_rtc_port_t *port, const nx_rtc_calendar_t *calendar)

Set an idle calendar and advance its nonwrapping setting domain.

Note

Rejection changes no state. No implicit backup reset, synchronization, Core-time adjustment or authorization to overwrite retained hardware.

Parameters:

  • port – [in] Same single serialized privileged task owner.

  • calendar – [in] Separate raw value, copied on successful validation.

Returns:

SUCCESS, BUSY for a loan, STATE if closed, INVALID, EXHAUSTED or UNSUPPORTED.

nx_result_t nx_rtc_port_submit(const nx_rtc_port_t *port, nx_rtc_request_t *request)

Borrow and arm one future alarm; no queue, allocation or worker.

Note

Closed/stale/already-matching pattern returns STATE; active is BUSY. An observed expired finite deadline returns TIMEOUT before admission. Calendar, counter and Core deadline are separate domains. Assembly keeps the copied clock face’s borrowed context live, disjoint and non-reentrant for the entire owner lifetime and all external joins.

Parameters:

  • port – [in] Initialized serialized owner with a valid copied Core clock.

  • request – [inout] Exact READY request for the current setting domain.

Returns:

SUCCESS means ACCEPTED; INVALID/STATE/BUSY/TIMEOUT/UNSUPPORTED rejects without retained references or effects.

nx_result_t nx_rtc_port_cancel(const nx_rtc_port_t *port, nx_rtc_request_t *request)

Latch cancellation of the exact borrowed request, without revocation.

Note

Cancel/stop executed before service may win over unobserved expiry or event. The first terminal cause never changes while withdrawal waits.

Parameters:

  • port – [in] Same serialized executor; cross-task controls need an adapter.

  • request – [inout] Exact active identity; foreign identity is not read.

Returns:

SUCCESS accepts cancellation; it may still be QUARANTINED/borrowed. Rejection is STATE/INVALID/UNSUPPORTED.

nx_result_t nx_rtc_port_service(const nx_rtc_port_t *port)

Observe deadline/event or continue actual source withdrawal.

Note

At first observation expiry wins over pending event. Source/pending references detach before release SETTLED, the final provider access.

Parameters:

  • port – [in] Same serialized task executor; bounded, no hidden wait.

Returns:

SUCCESS when idle/settled, BUSY while active or withdrawal is held; INVALID/STATE/UNSUPPORTED may reject dispatch.

nx_result_t nx_rtc_port_stop(const nx_rtc_port_t *port)

Close admission and prove withdrawal before returning any loan.

Note

Clean repeated stop is idempotent. Stop does not reset identity or revoke pointers. Source/provider lifetime still covers external joins.

Parameters:

  • port – [in] Same serialized owner with external publishers quiescent.

Returns:

SUCCESS when closed/joined; BUSY retains the quarantined request. INVALID/STATE/UNSUPPORTED may reject dispatch.

struct nx_rtc_calendar_t
#include <rtc.h>

Raw YY calendar; no UTC, century, timezone or oscillator policy.

Note

YY is 00..99 and leap years satisfy YY modulo 4 == 0. Weekday is an independent 1..7 value, not inferred from the date. Other fields use month/day 1-based and 24-hour hour/minute/second values, without leap seconds. Natural year99->00 wrap does not reset the setting domain.

Public Members

uint8_t year
uint8_t month
uint8_t day
uint8_t weekday
uint8_t hour
uint8_t minute
uint8_t second
struct nx_rtc_domain_t
#include <rtc.h>

Opaque owner identity and non-repeating setting incarnation.

Note

Compare identity without dereference. Valid only in that owner storage lifetime; retire all tokens/observers before ending or reusing it. This is neither authorization nor a cross-boot/backup-reset identity.

Public Members

const void *identity
uint64_t generation
struct nx_rtc_snapshot_t
#include <rtc.h>

Calendar and setting domain copied in one serialized operation.

Public Members

nx_rtc_domain_t domain
nx_rtc_calendar_t calendar
struct nx_rtc_alarm_t
#include <rtc.h>

Exact future day/time match; no month/year or wildcard masks.

Public Members

uint8_t day
uint8_t hour
uint8_t minute
uint8_t second
struct nx_rtc_request_t
#include <rtc.h>

Caller-owned alarm, borrowed until acquire-observed SETTLED.

Note

Initialize base before first preparation. Domain and pattern are copied by value. After ACCEPTED the complete request remains live and caller immutable through SETTLED and any separate control/observer joins. transferred counts occurrences: SUCCESS is 1, every other result is 0.

Public Members

nx_request_t base
nx_rtc_domain_t domain
nx_rtc_alarm_t alarm
struct nx_rtc_ops_t
#include <rtc.h>

Shared immutable methods with the corresponding public contracts.

Public Members

nx_result_t (*read)(const void *context, nx_rtc_snapshot_t *snapshot)
nx_result_t (*set)(void *context, const nx_rtc_calendar_t *calendar)
nx_result_t (*submit)(void *context, nx_rtc_request_t *request)
nx_result_t (*cancel)(void *context, nx_rtc_request_t *request)
nx_result_t (*service)(void *context)
nx_result_t (*stop)(void *context)
struct nx_rtc_port
#include <rtc.h>

Two-pointer identity; face, ops and context outlive loans/observers.

Public Members

const nx_rtc_ops_t *ops
void *context

rtc_lptim_model.h

Explicit host source progression and withdrawal faults.

Author

Nexus Team

Functions

nx_result_t nx_native_rtc_model_advance(const nx_rtc_port_t *port, uint32_t seconds)

Advance a set raw calendar by bounded explicit source seconds.

Note

Constant bounded work, at most one date carry. A closed set calendar may advance; this does not reopen admission or prove backup retention. Does not read/advance Core clock, publish, settle or change terminal cause. Source changes are not an IRQ, worker or hardware qualification.

Parameters:

  • port – [in] Exact Native RTC face, serialized with every public call.

  • seconds – [in] 0..86400; zero never creates an event.

Returns:

SUCCESS, STATE if unset/unconstructed, INVALID or UNSUPPORTED.

nx_result_t nx_native_rtc_model_hold_withdraw(const nx_rtc_port_t *port, bool hold)

Inject/remove the external inability to withdraw an armed source.

Parameters:

  • port – [in] Exact Native RTC face on the same serialized owner.

  • hold – [in] True prevents withdrawal; false only removes the fault.

Returns:

SUCCESS or INVALID/STATE/UNSUPPORTED; never settles a request.

nx_result_t nx_native_lptim_model_advance(const nx_lptim_port_t *port, uint32_t ticks)

Advance a finite source, saturating at its exact shot limit.

Note

At full65536 the sampled 16-bit counter is zero; pending completion is independent. Held withdrawal permits final progress beyond cancel/time observation. Does not touch the request, terminal cause or Core clock.

Parameters:

  • port – [in] Exact Native LPTIM face, serialized with all public calls.

  • ticks – [in] 0..65536 source ticks; idle/unarmed does not accumulate.

Returns:

SUCCESS or INVALID/STATE/UNSUPPORTED.

nx_result_t nx_native_lptim_model_hold_withdraw(const nx_lptim_port_t *port, bool hold)

Inject/remove withdrawal hold; real public service still drains.

Parameters:

  • port – [in] Exact Native LPTIM face on the serialized executor.

  • hold – [in] False does not clear provider references or publish results.

Returns:

SUCCESS or INVALID/STATE/UNSUPPORTED.

spi.h

Single-executor polling SPI endpoints and complete CS transactions.

Author

Nexus Team

Defines

NX_SPI_MEMORY_TX_FIXED

Explicit single-cell DMA addresses, both borrowed until SETTLED.

NX_SPI_MEMORY_RX_FIXED

Functions

nx_result_t nx_spi_endpoint_transfer(const nx_spi_endpoint_t *endpoint, const uint8_t *tx, uint8_t *rx, size_t length, nx_time_us_t deadline, size_t *transferred)

Execute one bounded full-duplex 8-bit polling transaction.

Note

Task-only single executor, no allocation/OS lock. One CS interval covers the entire transfer. Deadline cannot preempt an in-flight hardware byte; peripheral drain may exceed it.

Parameters:

  • endpoint – [in] Fixed CS/mode/rate binding on one controller.

  • tx – [in] Transmit bytes, or NULL to send 0xff.

  • rx – [out] Receive bytes, or NULL to discard.

  • length – [in] Positive transfer length; at least one buffer exists.

  • deadline – [in] Absolute deadline; includes adapter queue residence.

  • transferred – [out] Complete bytes; reset to zero before execution.

Returns:

Success, BUSY/INVALID/TIMEOUT/IO. Return releases all buffers and CS after drain; polling is CPU-active, not IRQ/DMA async.

nx_result_t nx_spi_port_recover(const nx_spi_port_t *port)

Recover an idle SPI controller after its retained fault.

Parameters:

  • port – [in] Single executor with no live transaction or CS borrow.

Returns:

Success only after reset/idle proof; BUSY/STATE/UNSUPPORTED preserves recovery responsibility and never replays work.

nx_result_t nx_spi_request_prepare(nx_spi_request_t *request, const uint8_t *tx, uint8_t *rx, size_t length, nx_time_us_t deadline)

Prepare an unborrowed finite request without copying buffers.

Parameters:

  • request – [inout] Fresh initialized or consumed SETTLED descriptor.

  • tx – [in] Nonempty TX bytes or NULL when the selected mode supports dummy transmission; immutable through final settlement.

  • rx – [out] RX buffer or NULL when the selected mode supports discard.

  • length – [in] Positive byte count with at least one supplied buffer.

  • deadline – [in] Absolute monotonic deadline including queue time.

Returns:

Success or INVALID/STATE; failure creates no buffer loan.

nx_result_t nx_spi_endpoint_submit(const nx_spi_endpoint_t *endpoint, nx_spi_request_t *request)

Submit one finite asynchronous whole-CS transaction.

Note

Task-only bounded admission. Selected modes declare DMA domain/length/buffer requirements. DMA TC alone never proves peripheral idle; the bus executor continues service to SETTLED.

Parameters:

  • endpoint – [in] Initialized endpoint on a single-executor bus.

  • request – [inout] READY storage; retained only after NX_SUCCESS.

Returns:

Success means ACCEPTED; all rejection errors create zero retained references and zero residual hardware effects.

nx_result_t nx_spi_endpoint_submit_memory(const nx_spi_endpoint_t *endpoint, nx_spi_request_t *request, uint8_t memory_flags)

Submit explicit incrementing or single-cell DMA memory.

Note

Fixed directions require one byte, other directions length bytes, within reviewed DMA domains. The actual spans must not overlap. All addresses remain borrowed through drain until acquire-observed SETTLED. No hidden scratch is used. Both fixed flags permit explicit clock-only transfers. Request preparation does not retain these flags; only this successful admission selects them. Ordinary submit and the existing owner continue their ordinary buffer contract.

Parameters:

  • endpoint – [in] Initialized single-executor DMA endpoint

  • request – [inout] READY request with two non-NULL caller addresses

  • memory_flags – [in] TX_FIXED repeats one immutable dummy byte; RX_FIXED repeatedly writes one caller-owned discard byte; zero uses complete incrementing TX/RX buffers

Returns:

ACCEPTED on SUCCESS; other results retain no references

nx_result_t nx_spi_endpoint_start_admitted(const nx_spi_endpoint_t *endpoint, nx_spi_request_t *request)

Start an adapter-admitted QUEUED request without readmission.

Parameters:

  • endpoint – [in] Initialized exact CS binding and bus executor.

  • request – [inout] Live QUEUED storage already borrowed by its adapter.

Returns:

Success hands execution to the bus; BUSY retains QUEUED. Other errors must be settled by the adapter executor.

bool nx_spi_endpoint_on_port(const nx_spi_endpoint_t *endpoint, const nx_spi_port_t *port)

Verify an endpoint belongs to the serviced bus.

Note

Task/IRQ bounded cold identity check, no lookup or ownership effects. An adapter checks this before hardware execution; asynchronous admission also checks before borrowing.

Parameters:

  • endpoint – [in] Immutable endpoint identity kept alive by its caller.

  • port – [in] Exact execution bus bound to an adapter.

Returns:

True only when the provider proves matching controller state and compatible bus methods; false for invalid/missing methods.

nx_result_t nx_spi_port_cancel(const nx_spi_port_t *port, nx_spi_request_t *request)

Request cancellation without revoking DMA/CS buffer loans.

Note

Cross-task controls use stable adapter slots and epochs.

Parameters:

  • port – [in] Same single execution owner as submit and service.

  • request – [inout] Exact live active request, never a stale raw pointer.

Returns:

Success starts drain or observes prior settlement; STATE for another request, UNSUPPORTED for a polling-only provider.

void nx_spi_port_service(const nx_spi_port_t *port)

Advance one asynchronous bus under its single task executor.

Note

Bounded no-wait service. Final publication follows DMA/IRQ detach and peripheral-idle proof; failed drain quarantines.

Parameters:

  • port – [in] Live provider; call while stopping and throughout drain.

nx_result_t nx_spi_port_stop(const nx_spi_port_t *port)

Close admission and retain active sources until full drain.

Parameters:

  • port – [in] Live bus; all external producers already quiesced.

Returns:

Success proves source release, BUSY requires service, or UNSUPPORTED when the provider has no asynchronous lifecycle.

nx_result_t nx_spi_port_attach_wake(const nx_spi_port_t *port, const nx_irq_wake_t *wake, uint8_t syscall_ceiling)

Attach an optional hint sink to asynchronous bus IRQ publishers.

Note

Join old publishers and waiters before freeing wake storage.

Parameters:

  • port – [in] One initialized bus controlled by a task executor.

  • wake – [in] Immutable borrowed target or NULL to detach.

  • syscall_ceiling – [in] Optional additional unshifted kernel-safe priority floor; cannot weaken generated policy. PRIMASK kernel targets require zero. Ignored without kernel calls.

Returns:

Success, PERMISSION for unsafe actual priority, CONTEXT/STATE for illegal control or UNSUPPORTED for a polling-only bus.

struct nx_spi_request_t
#include <spi.h>

Caller-owned finite SPI request with one whole-CS interval.

Note

Initialize base before prepare. Accepted requests borrow both non-NULL buffers until acquire-observed SETTLED, including cancellation and timeout drain. QUARANTINED retains the loan.

Public Members

nx_request_t base
const uint8_t *tx
uint8_t *rx
size_t length
struct nx_spi_ops_t
#include <spi.h>

Shared read-only methods using one provider state.

Note

Methods follow each public operation’s ownership contract. Missing optional methods report UNSUPPORTED.

Public Members

nx_result_t (*recover)(void *context)
nx_result_t (*cancel)(void *context, nx_spi_request_t *request)
void (*service)(void *context)
nx_result_t (*stop)(void *context)
nx_result_t (*attach_wake)(void *context, const nx_irq_wake_t *wake, uint8_t syscall_ceiling)
struct nx_spi_port
#include <spi.h>

Immutable interface pointing to caller-owned state.

Note

Face and state outlive callers, IRQs and retained borrows. Factory lookup neither initializes nor acquires hardware.

Public Members

const nx_spi_ops_t *ops
void *context
struct nx_spi_endpoint_ops_t
#include <spi.h>

Shared read-only methods using one provider state.

Note

Methods follow each public operation’s ownership contract. Missing optional methods report UNSUPPORTED.

Public Members

nx_result_t (*transfer)(void *context, const uint8_t *tx, uint8_t *rx, size_t length, nx_time_us_t deadline, size_t *transferred)
nx_result_t (*submit)(void *context, nx_spi_request_t *request)
nx_result_t (*start_admitted)(void *context, nx_spi_request_t *request)
bool (*on_port)(const void *context, const nx_spi_port_t *port)
nx_result_t (*submit_memory)(void *context, nx_spi_request_t *request, uint8_t memory_flags)
struct nx_spi_endpoint
#include <spi.h>

Immutable interface pointing to caller-owned state.

Note

Face and state outlive callers, IRQs and retained borrows. Factory lookup neither initializes nor acquires hardware.

Public Members

const nx_spi_endpoint_ops_t *ops
void *context

spi_dma_model.h

Explicit Native segmented wire and drain fault controls.

Author

Nexus Team

Functions

void nx_native_spi_dma_model_step(const nx_spi_dma_transaction_port_t *port)

Move one modeled wire word or observe its final idle event.

Note

Caller-scheduled task/model IRQ; no hidden worker. Facts latch before a bounded hint. Never invoke after publisher join. A stopped owner cannot drive a successor’s model.

Parameters:

  • port – [in] Exact live Native enhanced controller.

nx_result_t nx_native_spi_dma_model_automatic(const nx_spi_dma_transaction_port_t *port, bool automatic)

Select optional single-step progress during task service.

Note

Task-only. Explicit stepping remains available. This model does not establish physical IRQ/DMA timing or HIL.

Parameters:

  • port – [in] Exact live Native enhanced controller, quiescent.

  • automatic – [in] True for one modeled step per service.

Returns:

SUCCESS, INVALID, STATE, CONTEXT or BUSY while borrowed.

nx_result_t nx_native_spi_dma_model_hold(const nx_spi_dma_transaction_port_t *port, bool hold)

Inject or remove inability to prove physical model drain.

Note

Task-only, allowed while borrowed. Removing the fault does not settle; continue model stepping and unique service.

Parameters:

  • port – [in] Exact live Native enhanced controller.

  • hold – [in] Keep all request/CS loans while true.

Returns:

SUCCESS, INVALID, STATE or CONTEXT.

nx_result_t nx_native_spi_dma_model_fault(const nx_spi_dma_transaction_port_t *port, size_t fail_after)

Fail a phase before the selected zero-based wire word.

Note

Task-only model input; no replay or early loan release.

Parameters:

  • port – [in] Exact live Native enhanced controller.

  • fail_after – [in] SIZE_MAX disables the injected fault.

Returns:

SUCCESS, INVALID, STATE or CONTEXT.

spi_dma_owner_binding.h

Optional immutable segmented SPI ownership and IRQ binding.

Author

Nexus Team

Functions

bool nx_spi_dma_owner_contains(const nx_spi_dma_owner_binding_t *binding, const nx_spi_dma_transaction_endpoint_t *endpoint)

Check exact endpoint membership without hardware effects.

Note

No acquisition, initialization, allocation or service.

Parameters:

  • binding – [in] Stable provider-owned immutable capability.

  • endpoint – [in] Stable enhanced endpoint on the selected bus.

Returns:

False for malformed or foreign identities.

nx_result_t nx_spi_dma_owner_attach_wake(const nx_spi_dma_owner_binding_t *binding, const nx_irq_wake_t *wake, uint8_t syscall_ceiling)

Attach a borrowed hint to actual validated IRQ publishers.

Note

Task-only. Rejection leaves the previous binding intact. A hint is never completion. Detach alone does not join a publisher that has already captured the sink. Stop and join publishers and waiters before destroying notification data.

Parameters:

  • binding – [in] Stable selected controller capability.

  • wake – [in] Immutable sink kept live through publisher join, NULL to detach under the provider’s lifecycle contract.

  • syscall_ceiling – [in] Actual unshifted kernel threshold.

Returns:

SUCCESS, INVALID, CONTEXT, UNSUPPORTED or provider failure.

struct nx_spi_dma_owner_binding_t
#include <spi_dma_owner_binding.h>

Selected-only provider capability without changing IO faces.

Note

Stable immutable storage outlives executor and publishers. contains proves actual controller identity; a display name or a caller-assembled pair of pointers is not such proof. attach_wake validates actual IRQ sources before borrowing the sink. A missing hook permits explicit periodic service.

Public Members

const nx_spi_dma_transaction_port_t *port
bool (*contains)(const nx_spi_dma_transaction_endpoint_t*, const nx_spi_dma_transaction_port_t*)
nx_result_t (*attach_wake)(const nx_spi_dma_transaction_port_t*, const nx_irq_wake_t*, uint8_t)

spi_dma_transaction.h

Optional finite whole-CS segmented SPI DMA request contract.

Author

Nexus Team

Functions

nx_result_t nx_spi_dma_transaction_prepare(nx_spi_dma_transaction_request_t *request, const nx_spi_dma_segment_t *segments, size_t count, uint8_t word_bits, nx_time_us_t deadline)

Prepare unborrowed storage after validating every span.

Note

Descriptors and payload never overlap request storage. RX cannot overwrite any TX or descriptor. Repeated RX alias is allowed only for the exact same explicit FIXED discard cell. Provider-specific domains are checked at admission.

Parameters:

  • request – [inout] Initialized READY or consumed SETTLED storage.

  • segments – [in] Immutable caller-owned array, at most MAX_SEGMENTS.

  • count – [in] Positive segment count; every words count is positive.

  • word_bits – [in] Common hardware width of 8 or 16 bits.

  • deadline – [in] Absolute monotonic deadline for the complete chain.

Returns:

SUCCESS, INVALID/UNSUPPORTED/STATE; no borrow on failure.

nx_result_t nx_spi_dma_transaction_validate(const nx_spi_dma_transaction_request_t *request)

Validate immutable fields without admission or memory modification.

nx_result_t nx_spi_dma_transaction_submit(const nx_spi_dma_transaction_endpoint_t *endpoint, nx_spi_dma_transaction_request_t *request)

Admit one finite chain on a task-only single executor.

Note

All domains and segments are validated before admission. One CS interval spans the chain; SCK gaps between segments are permitted. DMA TC alone never establishes wire idle.

Parameters:

  • endpoint – [in] Stable enhanced DMA endpoint and provider state.

  • request – [inout] READY descriptor, retained only on SUCCESS.

Returns:

SUCCESS means ACCEPTED, possibly already SETTLED. Rejection retains no references and creates no hardware effects.

nx_result_t nx_spi_dma_transaction_cancel(const nx_spi_dma_transaction_port_t *port, nx_spi_dma_transaction_request_t *request)

Cancel an exact live request while retaining all its loans.

Parameters:

  • port – [in] Same single executor used by submit and service.

  • request – [inout] Exact current request or acquire-observed SETTLED.

Returns:

SUCCESS starts/observes cancellation; INVALID/STATE/CONTEXT rejects without revoking any existing loan.

void nx_spi_dma_transaction_service(const nx_spi_dma_transaction_port_t *port)

Advance a bounded phase boundary, completion or drain.

Note

No wait, allocation, payload copy, hidden task or OS lock. Failed drain/release retains QUARANTINED storage. SETTLED follows final hardware detach and CS release and is the provider’s final access to caller request and descriptors.

Parameters:

  • port – [in] Task-only enhanced controller; continue during stop.

nx_result_t nx_spi_dma_transaction_stop(const nx_spi_dma_transaction_port_t *port)

Close admission and stop after complete source withdrawal.

Note

Repeated successful stop never touches hardware again; another owner may already have acquired the controller.

Parameters:

  • port – [in] Stable single-executor state, producers quiesced.

Returns:

SUCCESS proves stop; BUSY needs further service and retains all outstanding storage, including quarantined requests.

struct nx_spi_dma_segment_t
#include <spi_dma_transaction.h>

Explicit DMA words with caller-owned dummy/discard cells.

Note

Both addresses are mandatory. A FIXED direction borrows one word; an incrementing direction borrows words elements. Width is common to all segments. DMA never uses the polling segment’s implicit NULL/dummy representation or scratch.

Public Members

const void *tx
void *rx
size_t words
uint8_t memory_flags
struct nx_spi_dma_transaction_request_t
#include <spi_dma_transaction.h>

Caller-owned request retaining every segment through drain.

Note

Initialize base before prepare. ACCEPTED borrows this object, its descriptor array, all TX/RX spans and fixed cells until acquire-observed SETTLED. Intermediate segment completion, cancellation and timeout never release any of these loans. Completion counts words of successfully settled segments; partial effects in a failed segment remain unquantified.

Public Members

nx_request_t base
const nx_spi_dma_segment_t *segments
size_t count
uint8_t word_bits
struct nx_spi_dma_transaction_endpoint_ops_t
#include <spi_dma_transaction.h>

Public Members

nx_result_t (*submit)(void *context, nx_spi_dma_transaction_request_t *request)
struct nx_spi_dma_transaction_endpoint
#include <spi_dma_transaction.h>

Public Members

const nx_spi_dma_transaction_endpoint_ops_t *ops
void *context
struct nx_spi_dma_transaction_port_ops_t
#include <spi_dma_transaction.h>

Public Members

nx_result_t (*cancel)(void *context, nx_spi_dma_transaction_request_t *request)
void (*service)(void *context)
nx_result_t (*stop)(void *context)
struct nx_spi_dma_transaction_port
#include <spi_dma_transaction.h>

Public Members

const nx_spi_dma_transaction_port_ops_t *ops
void *context

spi_transaction.h

Optional multi-segment whole-CS 8/16-bit polling SPI.

Author

Nexus Team

Defines

NX_SPI_MAX_SEGMENTS

Bounded descriptor count; no hidden concatenation buffer exists.

Functions

nx_result_t nx_spi_transaction_validate(const nx_spi_segment_t *segments, size_t count, uint8_t word_bits)

Validate every descriptor and span without hardware effects.

Note

No memory is borrowed, copied, allocated or modified. NULL data pointers are legal dummy/discard operations. This does not validate provider-specific controller, rate or limits.

Parameters:

  • segments – [in] Aligned immutable array, retained by the caller.

  • count – [in] Positive descriptor count, at most MAX_SEGMENTS.

  • word_bits – [in] Exactly 8 or 16; fixed for the whole CS interval.

Returns:

SUCCESS, INVALID for malformed/overlapping/overflowing spans, or UNSUPPORTED for excess descriptor count or word width.

nx_result_t nx_spi_transaction_transfer(const nx_spi_transaction_endpoint_t *endpoint, const nx_spi_segment_t *segments, size_t count, uint8_t word_bits, nx_time_us_t deadline, size_t *transferred)

Execute all segments under exactly one asserted CS interval.

Note

Task-only single executor; polling is CPU-active. Return releases descriptor/payload borrows after wire drain or provider reset and CS release. Deadline cannot preempt an in-flight word. Errors never replay prior segments. No allocation, OS lock, hidden scratch, width changes or CS toggles occur between phases. This is synchronous: existing finite DMA request and cancellation contracts are unchanged.

Parameters:

  • endpoint – [in] Optional enhanced face with stable private state.

  • segments – [in] Caller-owned descriptors and their data spans.

  • count – [in] Number of phases, all validated before hardware use.

  • word_bits – [in] Common hardware frame width, 8 or 16 bits.

  • deadline – [in] Absolute monotonic deadline for all phases.

  • transferred – [out] Complete received words, never bytes; separate writable size_t storage, reset before provider execution.

Returns:

SUCCESS or INVALID/UNSUPPORTED/CONTEXT/STATE/BUSY/TIMEOUT/IO.

struct nx_spi_segment_t
#include <spi_transaction.h>

One phase within a single CS interval.

Note

Words have the transaction’s common width of 8 or 16 bits. NULL TX repeats dummy; NULL RX discards. Both may be NULL for clock-only words. Non-NULL spans contain words elements; 16-bit spans are uint16_t-aligned. Descriptor and TX storage stay immutable until return. RX never overlaps descriptors, TX storage, other RX spans or the completion output. Ordinary byte-span SPI remains a separate unchanged interface.

Public Members

const void *tx
void *rx
size_t words
uint16_t dummy
struct nx_spi_transaction_ops_t
#include <spi_transaction.h>

Shared immutable methods; absent transfer reports UNSUPPORTED.

Public Members

nx_result_t (*transfer)(void *context, const nx_spi_segment_t *segments, size_t count, uint8_t word_bits, nx_time_us_t deadline, size_t *transferred)
struct nx_spi_transaction_endpoint
#include <spi_transaction.h>

Optional face sharing the selected provider’s existing bus state.

Public Members

const nx_spi_transaction_ops_t *ops
void *context

stream.h

Bounded caller-owned blocks with explicit producer/consumer loans.

Author

Nexus Team

Defines

NX_STREAM_BOUNDARY_IDLE
NX_STREAM_BOUNDARY_TRIGGER
NX_STREAM_BOUNDARY_LOSS
NX_STREAM_BOUNDARY_ERROR

Enums

enum nx_stream_slot_state_t

Values:

enumerator NX_STREAM_SLOT_FREE
enumerator NX_STREAM_SLOT_FILLING
enumerator NX_STREAM_SLOT_READY
enumerator NX_STREAM_SLOT_BORROWED

Functions

nx_result_t nx_stream_initialize(nx_stream_t *stream, nx_stream_slot_t *slots, size_t count)

Initialize an unborrowed stream and exact supplied block array.

Note

Task-only cold assembly. This helper does not validate DMA domains; the hardware provider must validate every block.

Parameters:

  • stream – [out] Fresh storage, not visible to any producer/consumer.

  • slots – [inout] Buffers distinct from all control and slot metadata.

  • count – [in] Positive exact block count, not a maximum pool size.

Returns:

Success or INVALID; never allocates or retains bad inputs.

nx_result_t nx_stream_reserve(nx_stream_t *stream, nx_stream_fill_t *fill)

Reserve the next free block for one serialized producer.

Note

Bounded task/IRQ metadata operation; payload writes occur outside the short interrupt mask, within the returned loan.

Parameters:

  • stream – [inout] Live initialized stream with one producer.

  • fill – [out] Producer loan valid until publish or proved abort.

Returns:

Success, OVERFLOW without overwrite, STATE while stopping or EXHAUSTED when the monotonic loan identity cannot advance.

bool nx_stream_can_reserve(const nx_stream_t *stream)

Query the next physical slot without creating a loan or loss.

Note

Task/IRQ bounded hint. A producer still calls reserve before accessing payload; another context must not race admission.

Parameters:

  • stream – [in] Live initialized stream with one serialized producer.

Returns:

True only when admission is open and the next slot is free.

void nx_stream_note_loss(nx_stream_t *stream, uint32_t count)

Latch explicitly observed dropped producer boundaries.

Note

Task/IRQ bounded. Saturates at UINT32_MAX; the next published block carries LOSS independently of its useful payload length.

Parameters:

  • stream – [inout] Live stream controlled by the serialized producer.

  • count – [in] Positive lost block/boundary count, never guessed bytes.

nx_result_t nx_stream_publish(nx_stream_t *stream, const nx_stream_fill_t *fill, size_t length, uint32_t flags)

Publish a complete block after all hardware writes detached.

Note

Task/IRQ bounded. A DMA half/full flag is insufficient if the engine can still write the published block. Consumer-visible block bytes stay immutable until the consumer releases them.

Parameters:

  • stream – [inout] Same serialized producer as reserve.

  • fill – [in] Current producer loan, not retained after publication.

  • length – [in] Positive produced bytes within the reserved capacity.

  • flags – [in] IDLE/TRIGGER boundaries observed by the provider.

Returns:

Success, INVALID or STATE; failure retains producer ownership.

nx_result_t nx_stream_acquire(nx_stream_t *stream, nx_stream_block_t *block)

Acquire the next ready block for one serialized consumer.

Note

Task/IRQ bounded metadata; consumer processing happens outside the mask. Release may occur out of order without overwrite.

Parameters:

  • stream – [inout] Live stream; consumer may drain during stop.

  • block – [out] Immutable consumer loan with exact incarnation token.

Returns:

Success, EMPTY or INVALID; empty creates no loan.

nx_result_t nx_stream_release(nx_stream_t *stream, const nx_stream_block_t *block)

Release only the matching consumer incarnation after final use.

Note

Task/IRQ bounded; release is the consumer’s final block access.

Parameters:

  • stream – [inout] Same consumer owner; no remaining observers of block.

  • block – [in] Exact acquired token, never a reconstructed pointer.

Returns:

Success, STATE for stale/double release or INVALID.

nx_result_t nx_stream_abort(nx_stream_t *stream, const nx_stream_fill_t *fill, bool memory_quiesced)

Abort a producer loan only after memory write sources detach.

Note

Cancellation/deadline alone never establishes quiescence.

Parameters:

  • stream – [inout] Same producer owner as reserve.

  • fill – [in] Current exact loan.

  • memory_quiesced – [in] True only after provider proves DMA/IRQ stopped.

Returns:

Success, BUSY without proven drain, STATE for a stale token.

nx_result_t nx_stream_stop(nx_stream_t *stream)

Close producer admission while retaining every outstanding loan.

Note

Task/IRQ constant metadata work independent of block count. This operation does not stop hardware or revoke loans.

Parameters:

  • stream – [inout] Live control kept alive until final successful stop.

Returns:

Success only when all blocks are free, BUSY until producers detach and consumers drain/release, INVALID for bad control.

nx_result_t nx_stream_post_initialize(nx_stream_producer_t *producer, nx_stream_t *stream)

Bind a posted producer to a quiescent initialized stream.

Note

Task-only cold binding. Caller owns exclusive producer rights and retains control until all pending fills and IRQs drain.

Parameters:

  • producer – [out] Separate caller control, not aliased with buffers

  • stream – [inout] Admission open, no outstanding producer/consumer loans

Returns:

SUCCESS, INVALID, BUSY or STATE; rejected output is untouched

bool nx_stream_post_can_reserve(const nx_stream_producer_t *producer)

Query the next preposted slot without a loan or guessed loss.

Note

Bounded task/IRQ hint; still reserve before writing payload.

Parameters:

  • producer – [in] Same exclusive serialized producer

Returns:

True when the next reservation can succeed

nx_result_t nx_stream_post_reserve(nx_stream_producer_t *producer, nx_stream_fill_t *fill)

Reserve a future fill without making earlier blocks ready.

Note

O(1) task/IRQ. Failure leaves output and loss counters intact; only explicitly observed boundaries justify note_loss.

Parameters:

  • producer – [inout] Live posted producer

  • fill – [out] Exact pending loan until FIFO publish or LIFO abort

Returns:

SUCCESS, OVERFLOW, STATE, EXHAUSTED or INVALID

nx_result_t nx_stream_post_publish(nx_stream_producer_t *producer, const nx_stream_fill_t *fill, size_t length, uint32_t flags)

Publish only the oldest pending detached producer loan.

Note

O(1) task/IRQ. Consumer acquire/release use the original stream.

Parameters:

  • producer – [inout] Same exclusive producer as reserve

  • fill – [in] Exact oldest token, absent from every hardware target

  • length – [in] Positive valid bytes at most the block capacity

  • flags – [in] Observed IDLE/TRIGGER/ERROR boundary facts

Returns:

SUCCESS, INVALID or STATE; rejection retains the loan

nx_result_t nx_stream_post_abort(nx_stream_producer_t *producer, const nx_stream_fill_t *fill, bool memory_quiesced)

Cancel the newest pending fill after proof of memory drain.

Note

O(1) task/IRQ. Does not advance consumer or published cursor; no FREE hole appears ahead of future publication. Stopping closes admission but still permits proved tail rollback.

Parameters:

  • producer – [inout] Same producer; rollback is strictly LIFO

  • fill – [in] Exact newest pending token

  • memory_quiesced – [in] Source detached, no remaining writes

Returns:

SUCCESS, BUSY, STATE or INVALID; failure retains the loan

struct nx_stream_slot_t
#include <stream.h>

Caller-owned block metadata; initialize data and capacity only.

Note

Storage remains live through producer and consumer quiescence.

Public Members

uint8_t *data
size_t capacity
size_t length
uint64_t epoch
uint32_t flags
uint32_t lost_blocks
nx_stream_slot_state_t state
struct nx_stream_t
#include <stream.h>

Caller-owned stream control, initialized before publication.

Note

outstanding counts nonfree blocks, including filling, ready and borrowed states. Only stream operations mutate it.

Public Members

nx_stream_slot_t *slots
size_t count
size_t producer
size_t consumer
size_t outstanding
uint64_t epoch
uint32_t losses
bool stopping
struct nx_stream_fill_t
#include <stream.h>

Mutable producer loan; hardware must stop before abort or publish.

Public Members

uint8_t *data
size_t capacity
size_t slot
uint64_t epoch
struct nx_stream_producer_t
#include <stream.h>

Optional caller-owned preposted producer; no default cost.

Note

One serialized producer owns this control and the stream. Do not mix ordinary reserve/publish/abort with a live posted producer. Two hardware targets remain FILLING until detached. Publication is FIFO; rollback is LIFO to avoid consumer holes.

Public Members

nx_stream_t *stream
size_t cursor
size_t pending
struct nx_stream_block_t
#include <stream.h>

Immutable consumer loan, valid until matching release succeeds.

Public Members

const uint8_t *data
size_t length
size_t slot
uint64_t epoch
uint32_t flags
uint32_t lost_blocks

stream_budget.h

Optional constant-work snapshot and checked cold sizing.

Author

Nexus Team

Functions

nx_result_t nx_stream_observe(const nx_stream_t *stream, nx_stream_observation_t *out)

Snapshot maintained metadata under one short IRQ guard.

Note

Task/IRQ fixed work, no slot scan or payload access. Caller keeps all storage alive; no observer reference is retained. next_free is the ordinary stream cursor, not the private preposted cursor. Output is distinct from every payload.

Parameters:

  • stream – [in] Live initialized storage, no concurrent destruction.

  • out – [out] Distinct output, unchanged on rejected metadata/alias.

Returns:

SUCCESS, INVALID or STATE for inconsistent control facts.

nx_result_t nx_stream_budget_calculate(const nx_stream_budget_t *budget, nx_stream_budget_result_t *out)

Checked cold calculation, no stream mutation or allocation.

Note

required = targets + spares + ceil(rate*release_delay / (block_units*1000000)); payload is required*block*unit_bytes. Finite math is conservative under the declared FIFO frontier release bound; out-of-order release may still block the next cursor. Latency requires target_delay_us < floor(units_per_block*1000000/units_per_second). This creates no backpressure or hardware qualification.

Parameters:

  • budget – [in] Explicit rate, longest release delay and pipeline.

  • out – [out] Distinct output, unchanged on error or overflow.

Returns:

SUCCESS, INVALID or EXHAUSTED for arithmetic overflow.

struct nx_stream_observation_t
#include <stream_budget.h>

O(1) aggregate facts; free total does not imply cursor is free.

Public Members

size_t capacity
size_t outstanding
size_t free_blocks
uint64_t epoch
uint32_t losses
bool next_free
bool stopping
struct nx_stream_budget_t
#include <stream_budget.h>

Explicit engineering assumptions, no inferred hardware rate.

Note

release_delay includes queue/consumer delay until release of each published FIFO frontier. units convert to bytes using unit_bytes. targets/spares are actual selected hardware loans. All quantities are positive except delay/targets/spares.

Public Members

uint64_t units_per_second
size_t units_per_block
size_t unit_bytes
nx_time_us_t release_delay_us
nx_time_us_t target_delay_us
size_t hardware_targets
size_t spare_blocks
size_t configured_blocks
struct nx_stream_budget_result_t
#include <stream_budget.h>

Conservative declared-assumption budget; never physical evidence.

Public Members

size_t retained_blocks
size_t required_blocks
size_t required_payload_bytes
nx_time_us_t block_fill_us
bool capacity_sufficient
bool target_latency_sufficient

stream_profile.h

Optional readonly continuous-stream cold admission profiles.

Author

Nexus Team

Functions

nx_result_t nx_uart_stream_profile_start(const nx_uart_stream_profile_t *profile, nx_stream_t *stream)

Validate an actual pool before the bound UART may borrow it.

Note

Caller joins all pool users before this cold pool check. Failure before provider dispatch creates no borrow, epoch change or hardware effect. Rate, FIFO-frontier hold and IRQ latency remain declared assumptions, never measurements. This creates no external UART flow control or losslessness. Underlying unprofiled APIs retain their explicit contracts.

Parameters:

  • profile – [in] Stable readonly reviewed binding and assumptions.

  • stream – [inout] Initialized unborrowed pool with exact declared count and equal declared byte capacities, kept live through the original provider’s stop and all consumer releases.

Returns:

INVALID for mismatched geometry/alias, STATE for stopping metadata, BUSY for existing loans, CONTEXT outside an unmasked task, EXHAUSTED for overflow/insufficient budget, UNSUPPORTED for target latency; otherwise provider result.

nx_result_t nx_adc_stream_profile_start(const nx_adc_stream_profile_t *profile, nx_stream_t *stream, uint32_t trigger_hz)

Validate pool and whole-scan rate before ADC admission.

Note

ADC stopping its trigger creates a sampling gap. No budget makes that pause preserve wall-clock samples or prove the future consumer/IRQ bounds. No observer/queue is created.

Parameters:

  • profile – [in] Stable readonly binding to the selected ADC face.

  • stream – [inout] Initialized unborrowed exact pool, as for UART.

  • trigger_hz – [in] Positive nominal complete scans per second, no greater than the declared production-rate upper bound.

Returns:

Cold-check errors as for UART, or the original info/start result. Provider scan, timer, DMA/cache and alias checks still apply; no rejected operation retains new references.

struct nx_uart_stream_profile_t
#include <stream_profile.h>

Selected UART face and immutable byte-stream assumptions.

Note

Reviewed assembly binds the actual continuous provider. Two hardware targets and one replacement are required. A profile never allocates or owns the caller’s pool. The normal byte face and provider state retain their layouts. Cold admission rechecks payload disjointness in O(n^2); no additional check enters the IRQ or steady I/O path.

Public Members

const nx_uart_port_t *port
nx_stream_budget_t budget
struct nx_adc_stream_profile_t
#include <stream_profile.h>

Selected ADC face and complete-scan stream assumptions.

Note

One unit is a complete selected scan, stored as one uint16_t per channel. Resolution bits never replace storage width. Geometry and rates are reviewed assembly inputs; they establish neither sample accuracy nor an aperture time.

Public Members

const nx_adc_port_t *port
nx_stream_budget_t budget

timer.h

Fixed timer/channel PWM with one shared base configuration.

Author

Nexus Team

Functions

nx_result_t nx_pwm_port_set(const nx_pwm_port_t *port, uint32_t period_ticks, uint32_t duty_ticks)

Atomically stage a reviewed fixed-base PWM duty.

Note

Shadow update becomes effective at next update event; do not infer immediate electrical change from successful staging.

Parameters:

  • port – [inout] Fixed timer/channel with one serialized writer.

  • period_ticks – [in] Positive maintained shared-base period.

  • duty_ticks – [in] Zero through period_ticks, inclusive.

Returns:

Success or INVALID/STATE/BUSY. Zero/100 percent are explicit constant levels. Shared channels must use one PSC/ARR/base; changing another channel’s base is rejected by configuration.

nx_result_t nx_pwm_port_start(const nx_pwm_port_t *port)

Enable a previously configured fixed PWM output.

Parameters:

  • port – [inout] Execution owner after Board inactive level setup.

Returns:

Success or INVALID/STATE.

nx_result_t nx_pwm_port_stop(const nx_pwm_port_t *port)

Stop PWM at its declared Board inactive electrical level.

Parameters:

  • port – [inout] Quiesced execution owner; no concurrent set/start.

Returns:

Success or INVALID; no advanced break/capture promise.

nx_result_t nx_pwm_port_state(const nx_pwm_port_t *port, nx_pwm_state_t *state)

Query staged PWM counts and selected timer clock.

Parameters:

  • port – [in] Fixed initialized channel.

  • state – [out] Staged counts, clock and running state.

Returns:

Success or INVALID.

struct nx_pwm_state_t
#include <timer.h>

PWM counts refer to the fixed declared post-prescaler timer clock.

Public Members

uint32_t period_ticks
uint32_t duty_ticks
uint32_t tick_hz
bool running
struct nx_pwm_ops_t
#include <timer.h>

Shared read-only methods using one provider state.

Note

Methods follow each public operation’s ownership contract. Missing optional methods report UNSUPPORTED.

Public Members

nx_result_t (*set)(void *context, uint32_t period_ticks, uint32_t duty_ticks)
nx_result_t (*start)(void *context)
nx_result_t (*stop)(void *context)
nx_result_t (*state)(const void *context, nx_pwm_state_t *state)
struct nx_pwm_port
#include <timer.h>

Immutable interface pointing to caller-owned state.

Note

Face and state outlive callers, IRQs and retained borrows. Factory lookup neither initializes nor acquires hardware.

Public Members

const nx_pwm_ops_t *ops
void *context

timer_capture.h

Optional raw timer edge capture with caller-owned events.

Author

Nexus Team

Enums

enum nx_timer_capture_flags

Observable loss incidents, not an exact count of physical edges.

Values:

enumerator NX_TIMER_CAPTURE_OVERCAPTURE
enumerator NX_TIMER_CAPTURE_RING_LOSS

Functions

nx_result_t nx_timer_capture_start(const nx_timer_capture_t *port, nx_timer_capture_event_t *events, size_t capacity)

Borrow an exact event ring and enable the fixed capture channel.

Note

Ring remains borrowed until successful stop. ISR access is confined to this ring. Caller must not modify it or its provider while borrowed. Counter wrap is modulo the reported width; observation time is not an absolute edge timestamp or a clock accuracy qualification.

Parameters:

  • port – [in] One privileged task owner, serialized with stop/read.

  • events – [inout] Aligned writable ring, capacity positive.

  • capacity – [in] Number of events; no hidden buffer or worker.

Returns:

SUCCESS transfers the ring borrow; rejection retains nothing.

nx_result_t nx_timer_capture_stop(const nx_timer_capture_t *port)

Disable and read back channel/IRQ sources before returning storage.

Note

Read drains events after capture stops. Failed detach never frees storage. Board pins, timer clock and shared vector leases are released by cold assembly only after successful stop and publisher quiescence.

Parameters:

  • port – [in] Privileged task owner, with generated IRQ owner retained.

Returns:

SUCCESS is the final access to the ring; BUSY retains the borrow while queued events or failed hardware detachment remain.

nx_result_t nx_timer_capture_read(const nx_timer_capture_t *port, nx_timer_capture_event_t *event)

Copy the oldest event in a short saved-mask metadata section.

Parameters:

  • port – [in] Single privileged task consumer.

  • event – [out] Separate writable output, unchanged on EMPTY/rejection.

Returns:

SUCCESS, EMPTY, STATE or INVALID; no block release is required.

nx_result_t nx_timer_capture_state(const nx_timer_capture_t *port, nx_timer_capture_state_t *state)

Query counter units and observable queue/loss facts.

Note

Hardware overcapture and ring saturation can coalesce edges. A loss incident does not estimate edges, edge frequency or actual IRQ WCET.

Parameters:

  • port – [in] Privileged task owner; no concurrent lifecycle writer.

  • state – [out] Separate writable snapshot.

Returns:

SUCCESS or INVALID/STATE/CONTEXT.

struct nx_timer_capture_event_t
#include <timer_capture.h>

Hardware modulo counter and the separate IRQ observation time.

Public Members

nx_time_us_t observed_at
uint32_t captured_ticks
uint32_t flags
struct nx_timer_capture_state_t
#include <timer_capture.h>

Fixed counter units and current software retention state.

Public Members

uint32_t tick_hz
uint32_t loss_incidents
size_t pending
uint8_t counter_bits
bool running
bool draining
struct nx_timer_capture_ops_t
#include <timer_capture.h>

Shared immutable methods; no per-call acquisition or allocation.

Public Members

nx_result_t (*start)(void *context, nx_timer_capture_event_t *events, size_t capacity)
nx_result_t (*stop)(void *context)
nx_result_t (*read)(void *context, nx_timer_capture_event_t *event)
nx_result_t (*state)(const void *context, nx_timer_capture_state_t *state)
struct nx_timer_capture
#include <timer_capture.h>

Immutable identity; state and methods outlive calls and IRQs.

Public Members

const nx_timer_capture_ops_t *ops
void *context

uart.h

IRQ TX requests and independently budgeted byte/event reception.

Author

Nexus Team

Defines

NX_UART_EVENT_PARITY
NX_UART_EVENT_FRAMING
NX_UART_EVENT_OVERRUN
NX_UART_EVENT_NOISE
NX_UART_EVENT_LOSS
NX_UART_EVENT_NO_BYTE

Enums

enum nx_uart_rx_profile_t

Values:

enumerator NX_UART_RX_BYTES
enumerator NX_UART_RX_EVENTS
enumerator 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.

Parameters:

  • request – [inout] Fresh initialized or consumed SETTLED request.

  • data – [in] Nonempty payload retained unchanged through SETTLED.

  • length – [in] Positive byte count.

  • deadline – [in] Absolute deadline in nx_time_now_us clock domain.

Returns:

NX_SUCCESS or INVALID/STATE; failure retains no buffer.

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.

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.

Parameters:

  • port – [inout] Initialized idle port owned by this execution context.

  • request – [inout] 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.

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:

  • port – [inout] Single-executor initialized port.

  • request – [inout] 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_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:

  • port – [inout] Same single execution owner as submit/service.

  • request – [inout] 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.

void nx_uart_port_service(const nx_uart_port_t *port)

Observe time/hardware completion and drain one active request.

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.

Parameters:

  • port – [inout] Single task/loop execution owner.

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:

  • port – [inout] Initialized event-profile port; one consumer.

  • events – [out] Caller-owned destination; not retained.

  • capacity – [in] Destination event count.

  • count – [out] 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_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:

  • port – [inout] Initialized byte-profile port; one consumer.

  • bytes – [out] Caller-owned destination; not retained.

  • capacity – [in] Destination capacity in bytes.

  • count – [out] Bytes copied; valid on OVERFLOW and on a provider IO failure after copying bytes and attempting RX rearm.

Returns:

NX_SUCCESS, EMPTY, OVERFLOW or INVALID/UNSUPPORTED. Byte profile reports aggregate loss without invented timestamps. A provider can return IO if RX source rearm fails after copying; count and copied bytes remain valid. Admission closes and retained hardware requires verified stop.

nx_result_t nx_uart_port_stop(const nx_uart_port_t *port)

Close admission and drain TX before releasing hardware.

Note

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

Parameters:

  • port – [inout] Owner; producers must already have quiesced.

Returns:

NX_SUCCESS when stopped; BUSY while service must continue.

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.

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.

Parameters:

  • port – [in] Initialized provider, controlled by one task executor.

  • wake – [in] Immutable live target or NULL to detach.

  • syscall_ceiling – [in] 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.

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.

Note

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

Parameters:

  • port – [in] Block-capable provider, one task execution owner.

  • stream – [inout] 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.

nx_result_t nx_uart_port_rx_stop(const nx_uart_port_t *port)

Stop RX block production without revoking consumer loans.

Note

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

Parameters:

  • port – [in] 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.

struct nx_uart_rx_event_t
#include <uart.h>

Timestamp belongs to provider clock; precision is hardware-specific.

Note

NO_BYTE marks status-only IRQ facts: byte is invalid. LOSS is an independent NO_BYTE boundary marker, ordered after older buffered facts and before later reception. Its timestamp is provider detection/report time, never a reconstructed timestamp for missing bytes. Byte-profile reads report aggregate loss and omit status-only facts.

Public Members

nx_time_us_t timestamp_us
uint32_t flags
uint8_t byte
struct nx_uart_tx_request_t
#include <uart.h>

Caller-owned TX descriptor; initialize base before first prepare.

Public Members

nx_request_t base
const uint8_t *data
size_t length
struct nx_uart_ops_t
#include <uart.h>

Shared read-only methods using one provider state.

Note

Methods follow each public operation’s ownership contract. Missing optional methods report UNSUPPORTED.

Public Members

nx_result_t (*submit)(void *context, nx_uart_tx_request_t *request)
nx_result_t (*start_admitted)(void *context, nx_uart_tx_request_t *request)
nx_result_t (*cancel)(void *context, nx_uart_tx_request_t *request)
void (*service)(void *context)
nx_result_t (*read_events)(void *context, nx_uart_rx_event_t *events, size_t capacity, size_t *count)
nx_result_t (*read_bytes)(void *context, uint8_t *bytes, size_t capacity, size_t *count)
nx_result_t (*stop)(void *context)
nx_result_t (*attach_wake)(void *context, const nx_irq_wake_t *wake, uint8_t syscall_ceiling)
nx_result_t (*rx_start)(void *context, nx_stream_t *stream)
nx_result_t (*rx_stop)(void *context)
struct nx_uart_port
#include <uart.h>

Immutable interface pointing to caller-owned state.

Note

Face and state outlive callers, IRQs and retained borrows. Factory lookup neither initializes nor acquires hardware.

Public Members

const nx_uart_ops_t *ops
void *context

uart_format.h

Explicit payload, parity, stop and hardware-flow format.

Author

Nexus Team

Enums

enum nx_uart_parity_t

Values:

enumerator NX_UART_PARITY_NONE
enumerator NX_UART_PARITY_EVEN
enumerator NX_UART_PARITY_ODD
enum nx_uart_stop_t

Values:

enumerator NX_UART_STOP_1
enumerator NX_UART_STOP_2
enum nx_uart_flow_t

Values:

enumerator NX_UART_FLOW_NONE
enumerator NX_UART_FLOW_RTS
enumerator NX_UART_FLOW_CTS
enumerator NX_UART_FLOW_RTS_CTS

Functions

nx_result_t nx_uart_format_validate(nx_uart_format_t format)

Validate the common USART-v1 subset without hardware access.

Note

Pure, bounded, task/IRQ safe; Board admission remains separate.

Parameters:

  • format – [in] Explicit payload width, parity, stop and flow selection.

Returns:

Success for 7E/O, 8N/E/O or 9N with one/two stop bits; INVALID for unknown values, UNSUPPORTED for a known incompatible combination.

struct nx_uart_format_t
#include <uart_format.h>

Immutable wire format; data_bits excludes the parity bit.

Note

RTS/CTS needs independently reviewed Board routing and peer wiring.

Public Members

uint8_t data_bits
nx_uart_parity_t parity
nx_uart_stop_t stop
nx_uart_flow_t flow

uart_rs485.h

Optional single-owner RS485 direction and wire-tail adapter.

Author

Nexus Team

Typedefs

typedef nx_result_t (*nx_uart_tx_validate_fn)(void *context, const nx_uart_tx_request_t *request)

Exact transport’s side-effect-free TX admission validator.

Note

Reads clock/hardware facts but never writes GPIO/MMIO, admits, starts or retains a reference. One executor owns adapter and transport; no external direct TX is permitted.

Param context:

[in] The immutable transport face’s exact context.

Param request:

[in] Live READY or QUEUED descriptor, never retained.

Return:

Same rejectable checks used by the transport submit/start.

Functions

nx_result_t nx_uart_rs485_initialize(nx_uart_rs485_state_t *state, const nx_uart_rs485_config_t *config)

Bind exclusive transport and establish inactive DE.

Note

Task-only, no wait. No physical transceiver is inferred. Setup starts after successful DE assertion; hold starts after acquire-observed true transport settlement. Transfer deadline includes setup and wire completion; mandatory drain/hold may extend the borrow beyond that deadline. Rejected TX leaves DE and transport unchanged. Failed drain or DE withdrawal keeps QUARANTINED outer storage and DE ownership until service retry.

Parameters:

  • state – [inout] Fresh zero-initialized caller control.

  • config – [in] Immutable lifetime binding; one authorized DE bit, real board polarity, setup/hold in nx_time_now_us domain.

Returns:

Success or INVALID/CONTEXT/STATE/GPIO failure, no TX loan.

Variables

const nx_uart_ops_t nx_uart_rs485_ops
struct nx_uart_rs485_config_t
#include <uart_rs485.h>

Immutable selected electrical/timing facts, no task or heap.

Note

Configuration, faces, ops and context identities cannot change while bound. They are disjoint from mutable adapter, request and payload storage; exact pin ownership is external.

Public Members

const nx_uart_port_t *transport
const nx_gpio_port_t *direction
nx_uart_tx_validate_fn validate
uint32_t mask
nx_time_us_t setup_us
nx_time_us_t hold_us
bool active_high
struct nx_uart_rs485_state_t
#include <uart_rs485.h>

Caller-owned opt-in adapter, zero-initialize before init.

Note

Control is private after initialization. Immutable config, both faces, pin ownership and all storage outlive successful stop plus external observers. Default UART state is unchanged.

Public Members

const nx_uart_rs485_config_t *config
nx_uart_tx_request_t inner
nx_uart_tx_request_t *active
nx_time_us_t boundary
nx_result_t terminal
size_t transferred
uint8_t phase
bool initialized
bool closing

uart_word.h

Independent nine-bit face and caller-owned word requests.

Author

Nexus Team

Functions

nx_result_t nx_uart_word_tx_prepare(nx_uart_word_tx_request_t *request, const uint16_t *data, size_t words, nx_time_us_t deadline)

Prepare an unborrowed nine-bit payload, without admitting it.

Note

Task owner; payload values are checked before provider admission.

Parameters:

  • request – [inout] Initialized READY or consumed SETTLED descriptor.

  • data – [in] Aligned immutable words, disjoint from the descriptor.

  • words – [in] Positive word count, representable as a byte extent.

  • deadline – [in] Absolute nx_time_now_us monotonic transfer deadline.

Returns:

Success, INVALID or STATE; rejection retains no references/effects.

nx_result_t nx_uart_word_port_submit(const nx_uart_word_port_t *port, nx_uart_word_tx_request_t *request)

Admit one READY request to the single unmasked task executor.

Note

Counts use words; completion requires actual wire TC.

Parameters:

  • port – [in] Live initialized face, private state and IRQ binding.

  • request – [inout] Caller-owned descriptor, borrowed on success.

Returns:

Success means ACCEPTED; rejection has no borrow/hardware effects.

nx_result_t nx_uart_word_port_start_admitted(const nx_uart_word_port_t *port, nx_uart_word_tx_request_t *request)

Transfer an adapter’s QUEUED borrow without readmission.

Parameters:

  • port – [in] Live single-owner face.

  • request – [inout] Existing adapter borrow.

Returns:

Success transfers execution; BUSY leaves QUEUED and its borrow.

nx_result_t nx_uart_word_port_cancel(const nx_uart_word_port_t *port, nx_uart_word_tx_request_t *request)

Request cancellation without revoking request/payload ownership.

Note

Continue service through drain; failed drain stays QUARANTINED.

Parameters:

  • port – [in] Same unmasked task executor as submit/service.

  • request – [inout] Live request; cross-task control uses a stable slot.

Returns:

Success for this request, STATE for a different live request.

void nx_uart_word_port_service(const nx_uart_word_port_t *port)

Perform bounded owner-driven deadline, drain and settlement work.

Note

IRQ only publishes facts; SETTLED is final provider access. No wait, hidden worker or callback; obey the declared maximum service gap.

Parameters:

  • port – [in] Single unmasked task owner, kept alive through stop.

nx_result_t nx_uart_word_port_read(const nx_uart_word_port_t *port, uint16_t *words, size_t capacity, size_t *count)

Copy words without retaining destination storage.

Note

Loss does not invent a hardware timestamp or missing word count.

Parameters:

  • port – [in] Initialized face, one consumer under the task executor.

  • words – [out] Aligned destination, disjoint from provider/RX storage.

  • capacity – [in] Positive destination capacity in words.

  • count – [out] Number copied, including on OVERFLOW.

Returns:

Success, EMPTY, OVERFLOW, INVALID, CONTEXT or STATE.

nx_result_t nx_uart_word_port_stop(const nx_uart_word_port_t *port)

Close admission and stop after active TX and IRQ sources drain.

Note

Caller joins any in-flight IRQ before reclaiming provider storage.

Parameters:

  • port – [in] One task owner; external producers/observers quiesced.

Returns:

Success after hardware detach; BUSY while service must continue.

struct nx_uart_word_tx_request_t
#include <uart_word.h>

Each uint16_t contains 0..511; count excludes bytes and parity.

Note

Request and unchanged payload are borrowed until acquire SETTLED.

Public Members

nx_request_t base
const uint16_t *data
size_t words
struct nx_uart_word_ops_t
#include <uart_word.h>

Public Members

nx_result_t (*submit)(void *context, nx_uart_word_tx_request_t *request)
nx_result_t (*start_admitted)(void *context, nx_uart_word_tx_request_t *request)
nx_result_t (*cancel)(void *context, nx_uart_word_tx_request_t *request)
void (*service)(void *context)
nx_result_t (*read)(void *context, uint16_t *words, size_t capacity, size_t *count)
nx_result_t (*stop)(void *context)
struct nx_uart_word_port
#include <uart_word.h>

Independent immutable face; default byte face/state do not grow.

Note

Static identity; lookup does not allocate, discover or initialize.

Public Members

const nx_uart_word_ops_t *ops
void *context

usb_activation.h

Optional explicit nonzero USB endpoint activation.

Author

Nexus Team

Functions

nx_result_t nx_usb_activation_set(const nx_usb_activation_port_t *port, uint64_t epoch, uint8_t endpoint_address, bool active)

Explicitly activate or deactivate one selected nonzero direction.

Note

No request or buffer is borrowed. Existing loans must be explicitly cancelled and drained before target changes; failure never revokes other loans. Configuration/class policy remains external.

Parameters:

  • port – [in] Started serialized privileged Task owner, IRQ masks clear.

  • epoch – [in] Current software USB epoch; cold epoch zero is valid.

  • endpoint_address – [in] USB address byte; EP0 is not admitted.

  • active – [in] Requested active state, never packet submission.

Returns:

Success after proof; UNSUPPORTED when the operation is absent. INVALID/CONTEXT/STATE/BUSY reject before writes. IO may have partial effects and closes controller admission until explicit recovery.

struct nx_usb_activation_ops_t
#include <usb_activation.h>

Optional controller operation; absence means UNSUPPORTED.

Public Members

nx_result_t (*set)(void *context, uint64_t epoch, uint8_t endpoint_address, bool active)
struct nx_usb_activation_port
#include <usb_activation.h>

Immutable borrowed face, using the existing controller context.

Public Members

const nx_usb_activation_ops_t *ops
void *context

usb_device.h

Full-speed device packets and caller-owned endpoint loans.

Author

Nexus Team

Enums

enum nx_usb_stage_t

Values:

enumerator NX_USB_DATA
enumerator NX_USB_STATUS
enum nx_usb_event_kind_t

Values:

enumerator NX_USB_EVENT_SETUP
enumerator NX_USB_EVENT_RESET
enumerator NX_USB_EVENT_SUSPEND
enumerator NX_USB_EVENT_RESUME
enumerator NX_USB_EVENT_LOSS

Functions

nx_result_t nx_usb_in_prepare(nx_usb_request_t *request, const uint8_t *bytes, size_t length, nx_usb_stage_t stage, uint64_t epoch, nx_time_us_t deadline)

Prepare one IN packet without reading or borrowing its bytes.

Parameters:

  • request – [inout] Initialized unborrowed request.

  • bytes – [in] Immutable packet bytes, NULL only for zero length.

  • length – [in] Packet length, no automatic terminating ZLP.

  • stage – [in] DATA or control STATUS; STATUS must be zero length.

  • epoch – [in] Current SETUP epoch for EP0, zero for nonzero endpoints.

  • deadline – [in] Absolute independent monotonic clock deadline.

Returns:

Success, INVALID or STATE; rejection retains no references.

nx_result_t nx_usb_out_prepare(nx_usb_request_t *request, uint8_t *bytes, size_t capacity, nx_usb_stage_t stage, uint64_t epoch, nx_time_us_t deadline)

Prepare an OUT packet capacity without modifying its storage.

Parameters:

  • request – [inout] Initialized unborrowed request.

  • bytes – [out] Borrowed until SETTLED only after accepted submission.

  • capacity – [in] At most endpoint MPS; short packets complete normally.

  • stage – [in] DATA or zero-capacity control STATUS.

  • epoch – [in] Current SETUP epoch for EP0, zero for nonzero endpoints.

  • deadline – [in] Absolute independent monotonic clock deadline.

Returns:

Success, INVALID or STATE; rejection creates no borrow.

nx_result_t nx_usb_endpoint_submit(const nx_usb_endpoint_port_t *port, nx_usb_request_t *request)

Admit one packet, never a hidden queue or complete USB transaction.

Note

One privileged task executor, IRQ masks clear. IN FIFO writes do not prove host ACK. OUT overrun drains all packet words without overflow.

Parameters:

  • port – [in] Stable endpoint face and private state.

  • request – [inout] READY packet, buffers alive until acquire SETTLED.

Returns:

Success means ACCEPTED; fourth-party buffers are not copied early.

nx_result_t nx_usb_endpoint_cancel(const nx_usb_endpoint_port_t *port, nx_usb_request_t *request)

Request endpoint disable/drain without revoking a buffer loan.

Note

Control OUT0 has no hardware disable command: cancellation may require full device stop to settle. Missing proof becomes QUARANTINED. Reset/SETUP invalidates epochs but releases only after actual source drain.

Parameters:

  • port – [in] Same serialized privileged task owner.

  • request – [inout] Live request accepted by this exact endpoint.

Returns:

Success requests drain; failures retain all prior accepted loans.

nx_result_t nx_usb_endpoint_stall(const nx_usb_endpoint_port_t *port, bool stalled)

Set/clear STALL only after the endpoint has no live transfer.

Parameters:

  • port – [in] Serialized owner, started and IRQ masks clear.

  • stalled – [in] Desired STALL; clearing bulk/interrupt resets DATA0.

Returns:

Success after readback, BUSY retains a pending request.

nx_result_t nx_usb_device_service(const nx_usb_device_port_t *port)

Task-only bounded progress; deadline never depends on USB SOF.

Parameters:

  • port – [in] Serialized privileged owner with incoming IRQ masks clear.

Returns:

Success requests progress; no clock/endpoint loan is released early.

nx_result_t nx_usb_device_read_events(const nx_usb_device_port_t *port, nx_usb_event_t *events, size_t capacity, size_t *count)

Consume bounded value events; output is never retained.

Note

Invalid/STATE rejection leaves both outputs unchanged.

Parameters:

  • port – [in] Single task consumer and stable controller.

  • events – [out] Caller records disjoint from provider and live loans.

  • capacity – [in] Positive output count.

  • count – [out] Disjoint count output; EMPTY means zero.

Returns:

Success, EMPTY or rejection; authoritative latest SETUP is in state.

nx_result_t nx_usb_device_state(const nx_usb_device_port_t *port, nx_usb_device_state_t *state)

Task-only authoritative snapshot, independent of event-ring space.

Parameters:

  • port – [in] Serialized privileged owner with IRQ masks clear.

  • state – [out] Disjoint caller snapshot, never retained.

Returns:

Success copies state; alias/context rejection leaves output unchanged.

nx_result_t nx_usb_device_address(const nx_usb_device_port_t *port, uint64_t epoch, uint8_t address)

Stage SET_ADDRESS for the matching zero-data standard SETUP.

Parameters:

  • port – [in] Serialized privileged controller owner.

  • epoch – [in] Current SETUP identity.

  • address – [in] 0..127, matching SETUP wValue.

Returns:

Success stages only; address applies after real status-IN XFRC.

nx_result_t nx_usb_device_attach_wake(const nx_usb_device_port_t *port, const nx_irq_wake_t *wake, uint8_t syscall_ceiling)

Attach/detach a borrowed task/IRQ-compatible wake hint.

Parameters:

  • port – [in] Started serialized owner with IRQ masks clear.

  • wake – [in] Immutable target, or NULL to detach.

  • syscall_ceiling – [in] Additional numerical IRQ priority floor.

Returns:

Success after actual priority policy checks, BUSY while publisher remains live; rejection retains no new sink.

nx_result_t nx_usb_device_stop(const nx_usb_device_port_t *port)

Disconnect, disable, drain, detach IRQs, then release clock consumer.

Note

PIO OUT0 may remain enabled: successful global stop proves disconnect, OUT NAK, no DMA, empty RX FIFO, IRQ withdrawal and publisher join before final SETTLED. No forced reset revokes an unproved accepted borrow.

Parameters:

  • port – [in] Serialized owner; external observers must also join.

Returns:

Success ends provider access to endpoint/ring/wake storage; BUSY retains all storage and 48MHz ownership until actual progress.

struct nx_usb_request_t
#include <usb_device.h>

Public Members

nx_request_t base
const uint8_t *in
uint8_t *out
size_t length
uint64_t control_epoch
nx_usb_stage_t stage
struct nx_usb_setup_t
#include <usb_device.h>

Public Members

uint8_t request_type
uint8_t request
uint16_t value
uint16_t index
uint16_t length
uint64_t epoch
struct nx_usb_event_t
#include <usb_device.h>

Public Members

nx_usb_setup_t setup
nx_time_us_t timestamp_us
uint64_t lost
nx_usb_event_kind_t kind
struct nx_usb_device_state_t
#include <usb_device.h>

Public Members

nx_usb_setup_t setup
uint64_t epoch
uint64_t lost_events
bool started
bool closing
bool suspended
bool control_pending
uint8_t address
struct nx_usb_endpoint_ops_t
#include <usb_device.h>

Shared readonly packet methods; context is a selected endpoint.

Public Members

nx_result_t (*submit)(void*, nx_usb_request_t*)
nx_result_t (*cancel)(void*, nx_usb_request_t*)
nx_result_t (*stall)(void*, bool)
struct nx_usb_endpoint_port
#include <usb_device.h>

Public Members

const nx_usb_endpoint_ops_t *ops
void *context
struct nx_usb_device_ops_t
#include <usb_device.h>

Controller identity remains separate from endpoint identities.

Public Members

nx_result_t (*service)(void*)
nx_result_t (*read_events)(void*, nx_usb_event_t*, size_t, size_t*)
nx_result_t (*state)(void*, nx_usb_device_state_t*)
nx_result_t (*address)(void*, uint64_t, uint8_t)
nx_result_t (*attach_wake)(void*, const nx_irq_wake_t*, uint8_t)
nx_result_t (*stop)(void*)
struct nx_usb_device_port
#include <usb_device.h>

Public Members

const nx_usb_device_ops_t *ops
void *context

usb_profile.h

Selected-only immutable USB facts.

Author

Nexus Team

Note

Selection facts are not observed physical qualification.

Enums

enum nx_usb_fs_limit

Values:

enumerator NX_USB_FS_PHY_CLOCK_HZ
enumerator NX_USB_FS_FIFO_WORDS
enumerator NX_USB_FS_ENDPOINT_NUMBERS
enumerator NX_USB_FS_MAX_PACKET
enum nx_usb_profile_role_t

Values:

enumerator NX_USB_PROFILE_DEVICE
enum nx_usb_profile_speed_t

Values:

enumerator NX_USB_PROFILE_FULL_SPEED
enum nx_usb_profile_phy_t

Values:

enumerator NX_USB_PROFILE_INTERNAL_FS
enum nx_usb_profile_engine_t

Values:

enumerator NX_USB_PROFILE_PIO
enum nx_usb_profile_transfer_t

Values:

enumerator NX_USB_PROFILE_CONTROL
enumerator NX_USB_PROFILE_BULK
enumerator NX_USB_PROFILE_INTERRUPT

Functions

nx_result_t nx_usb_profile_validate(const nx_usb_device_profile_t *profile)

Validate exact selected FS facts without observing the controller.

Note

Task/ISR bounded and read-only. Facts identify selected software support; they never imply PCB routing, VBUS wiring or physical qualification. Public metadata, endpoint arrays, faces and operations tables require their natural C alignment and nonwrapping extents. Numeric rejection is not a probe of arbitrary addresses or opaque private contexts. EP0 selects control/64; nonzero bulk selects 8/16/32/64-byte MPS. Interrupt selects nonzero IN with 1..64-byte MPS. Host polling interval belongs to the external descriptor, not this profile.

Parameters:

  • profile – [in] Stable readable immutable facts, faces and endpoint array.

Returns:

Success or INVALID, including misaligned public metadata; no allocation, MMIO, discovery or lifecycle effect.

const nx_usb_endpoint_profile_t *nx_usb_profile_endpoint(const nx_usb_device_profile_t *profile, uint8_t number, bool in)

Find a direction in a previously validated immutable profile.

Note

Task/ISR read-only bounded lookup; all input lifetimes remain external.

Parameters:

  • profile – [in] Stable validated selected facts and endpoint array.

  • number – [in] Endpoint number, independent of direction.

  • in – [in] IN direction when true; OUT when false.

Returns:

Selected stable member or NULL, including misaligned profile/array metadata. No new endpoint can be discovered.

nx_result_t nx_usb_setup_reject(const nx_usb_setup_decision_port_t *port, uint64_t epoch)

Reject one published SETUP epoch by a checked EP0 IN STALL.

Note

Same privileged unmasked single task executor. The provider checks its published epoch and performs STALL in one local IRQ critical section, preserving the incoming mask. This excludes an already software-published replacement SETUP; it does not promise atomicity with physical bus packets not yet collected by the IRQ. No cancellation, global stop, allocation, class policy or address commit is implicit.

Parameters:

  • port – [in] Stable selected decision face, same controller owner.

  • epoch – [in] Nonzero software-published SETUP identity to reject.

Returns:

Success after guarded STALL readback; STATE for a superseded epoch/closing source, BUSY while either EP0 packet is live, INVALID for malformed metadata, CONTEXT for an invalid executor, IO for failed STALL readback, or UNSUPPORTED without the optional operation. Rejection retains no loan.

struct nx_usb_endpoint_profile_t
#include <usb_profile.h>

Public Members

const nx_usb_endpoint_port_t *port
uint16_t max_packet
uint8_t number
bool in
nx_usb_profile_transfer_t transfer
struct nx_usb_setup_decision_ops_t
#include <usb_profile.h>

Optional epoch-bound EP0 rejection, separate from generic ops.

Public Members

nx_result_t (*reject)(void*, uint64_t)
struct nx_usb_setup_decision_port_t
#include <usb_profile.h>

Public Members

const nx_usb_setup_decision_ops_t *ops
void *context
struct nx_usb_device_profile_t
#include <usb_profile.h>

Public Members

const nx_usb_device_port_t *port
const nx_usb_endpoint_profile_t *endpoints
size_t endpoint_count
uint32_t phy_clock_hz
uint16_t fifo_words
uint16_t rx_fifo_words
uint8_t endpoint_numbers
nx_usb_profile_role_t role
nx_usb_profile_speed_t speed
nx_usb_profile_phy_t phy
nx_usb_profile_engine_t engine
nx_usb_setup_decision_port_t setup_decision

wake.h

Explicit borrowed IRQ wake target and syscall-ceiling check.

Author

Nexus Team

Enums

enum nx_irq_kernel_policy_t

Explicit kernel interrupt-mask policy, independent of any RTOS.

Values:

enumerator NX_IRQ_KERNEL_NONE
enumerator NX_IRQ_KERNEL_PRIMASK
enumerator NX_IRQ_KERNEL_BASEPRI

Functions

nx_result_t nx_irq_wake_validate(const nx_irq_wake_t *wake, const nx_irq_policy_t *policy, const nx_irq_source_t *source)

Validate actual IRQ facts against an explicit kernel policy.

Note

Cold check without attachment or callback effects. No kernel target is accepted by NONE. PRIMASK permits every valid configurable IRQ with its fixed zero priority group. Kernel-calling BASEPRI targets require the maintained preemption grouping and a numerical priority at least the ceiling. Nonkernel hints do not impose kernel grouping. Binding does not authorize future CPU-context violations.

Parameters:

  • wake – [in] Optional immutable target; NULL disables notification.

  • policy – [in] Immutable validated CPU and kernel configuration.

  • source – [in] External IRQ number, unshifted priority and group.

Returns:

Success, INVALID for malformed facts/target, PERMISSION for a kernel-calling target in an unsafe interrupt domain.

nx_result_t nx_irq_wake_signal(const nx_irq_wake_t *wake)

Deliver one bounded hint after authoritative state is latched.

Note

Task/IRQ as allowed by the target, no hidden task or retry. A failed wake does not revoke state or request ownership.

Parameters:

  • wake – [in] Previously validated live target or NULL.

Returns:

Callback result, success for NULL, INVALID for a bad target.

struct nx_irq_wake_t
#include <wake.h>

Optional immutable wake target borrowed by an IRQ provider.

Note

notify runs in publisher context and must be bounded and legal in that IRQ. Storage and context outlive all publishers. Stop and join publishers before destroying the sink. A wake is only a hint; latched RX/request predicates stay authoritative.

Public Members

void *context
nx_result_t (*notify)(void *context)
bool calls_kernel
struct nx_irq_policy_t
#include <wake.h>

Immutable CPU and kernel facts for cold wake binding.

Note

NONE and PRIMASK require a zero syscall ceiling. BASEPRI requires a nonzero unshifted ceiling. Configuration owns these facts; a wake target cannot weaken them.

Public Members

nx_irq_kernel_policy_t kernel
uint16_t external_irq_count
uint8_t priority_bits
uint8_t syscall_ceiling
struct nx_irq_source_t
#include <wake.h>

Actual publisher facts read before attaching any borrowed sink.

Public Members

int16_t irq_number
uint8_t priority
uint8_t priority_group

watchdog.h

Irreversible IWDG effects and neutral hardware reset causes.

Author

Nexus Team

Defines

NX_RESET_POWER_ON
NX_RESET_PIN
NX_RESET_SOFTWARE
NX_RESET_IWDG
NX_RESET_WWDG
NX_RESET_LOW_POWER
NX_RESET_BROWNOUT

Functions

nx_result_t nx_watchdog_port_enable(const nx_watchdog_port_t *port, uint32_t timeout_us, bool debug_freeze, nx_watchdog_state_t *state)

Enable IWDG and report its effect and known timing bounds; activation is irreversible.

Note

Success establishes nominal hardware programming, not a guaranteed deadline. Both timeout bounds remain zero when oscillator limits are unknown. A product requiring bounded timing must admit the oscillator profile before activation. Enable runs in a privileged task and is serialized with feed, state and platform stop. Install IRQ feeding only after this call returns; activation does not support a concurrent reload during shadow-register programming.

Parameters:

  • port – [inout] Fixed provider; product owns feed/recovery policy.

  • timeout_us – [in] Requested nominal timeout in maintained range.

  • debug_freeze – [in] Requested CPU-managed debug-freeze setting; external debugger configuration is outside this request.

  • state – [out] Actual timeout bounds and remaining effect, including enabled=true when later setup reports failure after enabling.

Returns:

Success or INVALID/STATE/UNSUPPORTED/IO; never claims enabled hardware was disabled during rollback. Existing enable is identified. A provider without CPU debug-control access rejects true with UNSUPPORTED before activation; it neither queries nor changes external debugger control.

nx_result_t nx_watchdog_port_feed(const nx_watchdog_port_t *port)

Feed an enabled IWDG without changing product health policy.

Parameters:

  • port – [inout] Fixed enabled provider with one serialized feed owner.

Returns:

Success or INVALID/STATE; bounded task/IRQ, no allocation.

nx_result_t nx_watchdog_port_state(const nx_watchdog_port_t *port, nx_watchdog_state_t *state)

Query current watchdog effect and timeout uncertainty.

Parameters:

  • port – [in] Fixed provider.

  • state – [out] Current hardware/remembered initialization state.

Returns:

Success or INVALID; UNSUPPORTED retains observed hardware effects with both timeout bounds zero when those bounds cannot be established. Never infer a disabled watchdog from a failed query or unknown timeout.

uint32_t nx_reset_cause(void)

Read latched boot reset causes captured before clearing flags.

Note

No implicit acknowledgement, reboot or product classification.

Returns:

Bitmask of NX_RESET_*; multiple causes may be reported.

struct nx_watchdog_state_t
#include <watchdog.h>

Hardware-selected timeout bounds, including declared LSI uncertainty.

Note

A zero minimum and maximum mean the timeout bounds are unknown, for example while hardware shadow updates remain pending or no oscillator limits have been reviewed. The enabled and irreversible facts remain valid. debug_freeze reports the provider-supported firmware configuration. Providers with CPU-readable debug control observe its setting. A provider without CPU debug-control access supports false only; that value does not observe or describe an external debugger’s setting.

Public Members

uint32_t minimum_timeout_us
uint32_t maximum_timeout_us
bool enabled
bool irreversible
bool debug_freeze
struct nx_watchdog_ops_t
#include <watchdog.h>

Shared read-only methods using one provider state.

Note

Methods follow each public operation’s ownership contract. Missing optional methods report UNSUPPORTED.

Public Members

nx_result_t (*enable)(void *context, uint32_t timeout_us, bool debug_freeze, nx_watchdog_state_t *state)
nx_result_t (*feed)(void *context)
nx_result_t (*state)(const void *context, nx_watchdog_state_t *state)
struct nx_watchdog_port
#include <watchdog.h>

Immutable interface pointing to caller-owned state.

Note

Face and state outlive callers, IRQs and retained borrows. Factory lookup neither initializes nor acquires hardware.

Public Members

const nx_watchdog_ops_t *ops
void *context