Optional common components

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

bmp280.h

BMP280 calibration and explicit forced-conversion driver.

Author

Nexus Team

Functions

nx_result_t nx_bmp280_parse_calibration(const uint8_t *bytes, size_t length, nx_bmp280_calibration_t *calibration)

Parse the exact 24-byte little-endian calibration block.

Parameters:

  • bytes – [in] Register block beginning at 0x88

  • length – [in] Must be exactly 24

  • calibration – [out] Written only on success

Returns:

SUCCESS or INVALID for length/zero pressure divisor

nx_result_t nx_bmp280_compensate(const nx_bmp280_calibration_t *calibration, uint32_t raw_temperature, uint32_t raw_pressure, nx_bmp280_sample_t *sample)

Compensate one raw sample using checked integer arithmetic.

Parameters:

  • calibration – [in] Parsed calibration

  • raw_temperature – [in] Unsigned 20-bit ADC value

  • raw_pressure – [in] Unsigned 20-bit ADC value

  • sample – [out] Written only on success

Returns:

SUCCESS, INVALID for malformed/overflow calibration or IO for disabled ADC sentinel/out-of-datasheet-range physical output

nx_result_t nx_bmp280_init(nx_bmp280_t *device, nx_bmp280_transport_port_t transport, nx_time_us_t deadline)

Validate chip ID and load calibration, without scanning.

Note

Task context; failure leaves initialized false and no borrow. Does not soft-reset the part or create a wait loop/task. Retry BUSY explicitly.

Parameters:

  • device – [out] Zero-initialized unused instance

  • transport – [in] Synchronous settled port and live monotonic clock

  • deadline – [in] Absolute deadline for all initialization accesses

Returns:

SUCCESS, BUSY for NVM update, or transport/identity error

nx_result_t nx_bmp280_begin(nx_bmp280_t *device, nx_time_us_t deadline)

Start one forced temperature/pressure conversion.

Note

Task-only serialized driver owner; oversampling x1/x1.

Parameters:

  • device – [inout] Initialized non-measuring instance

  • deadline – [in] Absolute deadline covering conversion and reads

Returns:

SUCCESS, BUSY, TIMEOUT or transport error

nx_result_t nx_bmp280_poll(nx_bmp280_t *device, nx_bmp280_sample_t *sample)

Poll conversion without an implicit worker or blocking delay.

Note

Task-only. Every port call releases temporary buffers before return. BUSY retains device conversion state, never stack or caller buffers. After terminal failure, begin may retry; the external owner chooses policy.

Parameters:

  • device – [inout] Instance with a previously started conversion

  • sample – [out] Written only on SUCCESS

Returns:

SUCCESS, BUSY while converting, TIMEOUT or transport error

void nx_bmp280_stop(nx_bmp280_t *device)

Stop software use after all synchronous calls have exited.

Note

Does not power off or reset a physical part. Sensor-internal conversion can finish without accessing MCU storage. No MCU borrow remains.

Parameters:

  • device – [inout] Quiesced driver instance

struct nx_bmp280_transport_port_t
#include <bmp280.h>

Synchronous settled SPI transaction port.

Note

exchange always releases every TX/RX buffer before returning, including TIMEOUT/error. One CS interval covers all bytes; mode 0 or 3, 8-bit words, <=10 MHz. Caller serializes this device and its bus owner. Driver stack transactions never cross asynchronous borrowing boundaries.

Public Members

void *context
nx_result_t (*exchange)(void*, const uint8_t*, uint8_t*, size_t, nx_time_us_t deadline)
nx_clock_t clock
struct nx_bmp280_calibration_t
#include <bmp280.h>

Register calibration, owned by one device instance.

Public Members

uint16_t t1
int16_t t2
int16_t t3
uint16_t p1
int16_t p2
int16_t p3
int16_t p4
int16_t p5
int16_t p6
int16_t p7
int16_t p8
int16_t p9
struct nx_bmp280_sample_t
#include <bmp280.h>

Output is valid only on successful conversion/compensation.

Public Members

int32_t centi_celsius
uint32_t pressure_pa
struct nx_bmp280_t
#include <bmp280.h>

Explicit device context, no Board pins or automatic sampling task.

Public Members

nx_bmp280_transport_port_t transport
nx_bmp280_calibration_t calibration
nx_time_us_t deadline
nx_time_us_t earliest_ready
bool initialized
bool measuring

bmp280_spi.h

Optional BMP280 adapter over a fixed SPI endpoint.

Author

Nexus Team

Functions

nx_bmp280_transport_port_t nx_bmp280_spi_transport(const nx_spi_endpoint_t *endpoint, nx_clock_t clock)

Bind a real polling SPI endpoint as settled transport.

Parameters:

  • endpoint – [in] Fixed endpoint kept alive throughout device use

  • clock – [in] Same monotonic domain as IO transfer deadlines

Returns:

Narrow transport; no global discovery or CS selection

bus_owner.h

Explicit bounded multi-producer, single-executor adapter.

Author

Nexus Team

Functions

nx_result_t nx_bus_owner_init(nx_bus_owner_t *owner, nx_owner_slot_t *slots, size_t capacity, nx_owner_guard_port_t guard, nx_owner_executor_port_t executor, nx_clock_t clock, const nx_wait_port_t *wake)

Initialize unused owner/slot storage.

Note

Startup context; no task, worker, timer or heap is created.

Parameters:

  • owner – [out] Unused caller-owned adapter storage

  • slots – [in] Exact queue capacity, no maximum pool

  • capacity – [in] Number of slots, greater than zero

  • guard – [in] Live short exclusion port

  • executor – [in] Single real execution port

  • clock – [in] Same monotonic domain as request deadlines

  • wake – [in] Optional static executor notification, or NULL

Returns:

SUCCESS or INVALID

nx_result_t nx_bus_owner_submit(nx_bus_owner_t *owner, nx_request_t *request, void *operation, const nx_wait_port_t *completion, nx_owner_ticket_t *ticket)

Establish the chain’s unique admission.

Note

Task multi-producer context. Free-slot admission and FIFO insertion use constant metadata work under the guard. An exhausted epoch permanently retires its slot. Deadline includes queue residence. Caller must not modify request, operation or buffers after admission. A notification error after admission cannot change SUCCESS to rejection; executor must recheck/pump periodically.

Parameters:

  • owner – [inout] Live accepting adapter

  • request – [inout] Prepared READY storage, retained until SETTLED

  • operation – [in] Executor-specific descriptor and payload storage

  • completion – [in] Optional static caller wake port, or NULL

  • ticket – [out] Stable cancellation identity, valid on SUCCESS

Returns:

SUCCESS means ACCEPTED; rejection retains zero references

nx_result_t nx_bus_owner_cancel(nx_bus_owner_t *owner, nx_owner_ticket_t ticket)

Submit cancellation through stable adapter storage.

Note

Task multi-producer context. No request pointer is accepted. Queued cancellation settles without starting. Active cancellation drains cooperatively; an irreversible operation may already have transferred data.

Parameters:

  • owner – [inout] Live adapter

  • ticket – [in] Previously accepted slot/epoch

Returns:

SUCCESS when marked, STATE for stale/released identity

nx_result_t nx_bus_owner_service(nx_bus_owner_t *owner)

Advance at most one bounded execution step.

Note

Task/explicit loop only. Consumers never service through wait. Keep calling during stop until idle; no callback creates a worker.

Parameters:

  • owner – [inout] Live adapter, called by its unique executor

Returns:

SUCCESS for progress/idle, BUSY for provider wait/contention, or provider error while retaining ownership for continued recovery

void nx_bus_owner_stop(nx_bus_owner_t *owner)

Close admission and request every accepted operation to stop.

Note

Task context. Executor must keep servicing/draining while producers wait/join. Stop is not settlement or storage reclamation.

Parameters:

  • owner – [inout] Live adapter

bool nx_bus_owner_idle(nx_bus_owner_t *owner)

Test whether execution and completion publication have exited.

Note

Join producers and any wake publishers before reclaiming owner, slots, guard or notifications. No future submit/cancel is permitted.

Parameters:

  • owner – [inout] Live adapter

Returns:

True if no queue/active/service publisher remains

struct nx_owner_guard_port_t
#include <bus_owner.h>

Explicit bounded metadata exclusion port.

Note

Task producer calls only. enter/leave must serialize all producers and the executor. Never hold this guard over start/service/cancel, waiting, payload copies or notification callbacks. State restores incoming interrupt mask when an architecture guard is used. Port storage stays live.

Public Members

void *context
uintptr_t (*enter)(void*)
void (*leave)(void*, uintptr_t)
struct nx_owner_executor_port_t
#include <bus_owner.h>

One real execution owner, injected without OS dependency.

start SUCCESS borrows operation until service SUCCESS. BUSY or any start error retains zero operation references/hardware effects; an error after partial start must instead accept and report through service. service SUCCESS proves all hardware/IRQ/deferred accesses stopped, writes final result/count, and releases the operation. BUSY still borrows. Other service errors retain ownership and require continued recovery/service. cancel requests drain; it never by itself releases operation. Callbacks run only in the externally scheduled executor, outside adapter metadata guard.

Note

terminal_authority selects providers that observe deadlines and latch their first terminal hardware fact themselves. Their final result survives late cancellation/publication. Other executors use adapter deadline/cancellation results. Queued deadlines always belong to the adapter.

Public Members

void *context
nx_result_t (*start)(void*, void *operation, nx_time_us_t deadline)
nx_result_t (*service)(void*, nx_result_t *result, size_t *transferred)
nx_result_t (*cancel)(void*)
bool terminal_authority
struct nx_owner_ticket_t
#include <bus_owner.h>

Stable control identity; never dereference a stale request pointer.

Public Members

size_t slot
uint64_t epoch
struct nx_owner_slot_t
#include <bus_owner.h>

Exact caller-owned slot, linked in either the free or FIFO chain; initialize only with owner init.

Public Members

nx_request_slot_t identity
void *operation
nx_wait_port_t completion
size_t next
bool cancel_requested
bool cancel_sent
struct nx_bus_owner_t
#include <bus_owner.h>

Explicit adapter state; external application supplies all storage.

Public Members

nx_owner_slot_t *slots
size_t capacity
size_t head
size_t tail
size_t active
size_t free_head
nx_owner_guard_port_t guard
nx_owner_executor_port_t executor
nx_clock_t clock
nx_wait_port_t wake
nx_result_t cancellation_result
bool accepting
bool servicing

clock_domain.h

Explicit clock consumers and epoch-bound drain control.

Author

Nexus Team

Version

1.0.0

Date

2026-10-11

Copyright

Copyright (c) 2026 Nexus Team

Typedefs

typedef struct nx_clock_domain nx_clock_domain_t

Opaque provider, statically supplied by its privileged owner.

typedef struct nx_clock_lease nx_clock_lease_t

One stable caller-owned consumer token.

Note

Zero-initialize before first acquisition. On SUCCESS the provider borrows this exact object; do not copy, mutate or reclaim it until release succeeds. Internal fields are not application controls. A release is the provider’s final access, not proof that a peripheral has stopped. Release only after that consumer’s IRQ, DMA and observer drain.

Enums

enum nx_clock_power_mode_t

Only shallow sleep preserves the established clock/time domain.

Values:

enumerator NX_CLOCK_SHALLOW_SLEEP
enumerator NX_CLOCK_DEEP_STOP
enumerator NX_CLOCK_DYNAMIC_RUN

Functions

nx_result_t nx_clock_domain_acquire(nx_clock_domain_t *domain, nx_clock_lease_t *lease)

Acquire one admitted clock consumer without waiting.

Note

Privileged Thread or configurable IRQ only; same CPU, saved-mask metadata guard. NMI/HardFault/SMP excluded. Capacity bounds token/alias scans. Token remains borrowed until successful release, even while admission is closed.

Returns:

SUCCESS, BUSY for closed admission, EXHAUSTED for budget, or INVALID/STATE/CONTEXT with no retained token or effects

nx_result_t nx_clock_domain_release(nx_clock_domain_t *domain, nx_clock_lease_t *lease)

Remove the exact retained token after consumer drain.

Note

Same contexts as acquire. Copied tokens cannot release the original. There is no callback or last access after SUCCESS.

Returns:

SUCCESS or INVALID/STATE/CONTEXT without removing a borrow

nx_result_t nx_clock_domain_close(nx_clock_domain_t *domain, nx_clock_barrier_t *control)

Close admission and return the current epoch control.

Note

Serialized privileged Thread only. No waiting, cancellation, clock writes or implicit consumer shutdown. Idempotent in the same closed epoch; output must not alias live storage.

nx_result_t nx_clock_domain_quiescent(nx_clock_barrier_t control)

Validate closed admission and zero retained consumers.

Note

Same CPU privileged Thread. This certifies only explicitly enrolled consumers. It does not authorize PLL reprogramming, suspend kernel Tick or change the Core deadline domain.

Returns:

SUCCESS, BUSY while consumers remain, STATE for stale/open control, INVALID or CONTEXT; no state changes

nx_result_t nx_clock_domain_reopen(nx_clock_barrier_t control)

Reopen a drained domain under a new admission epoch.

Note

Serialized privileged Thread. Does not restart the clock or reinterpret existing deadlines. Actual cold clock changes additionally require all Tick/time providers stopped and a new explicit deadline domain; this API performs neither.

Returns:

SUCCESS, BUSY, STATE, EXHAUSTED or CONTEXT without changes

struct nx_clock_lease
#include <clock_domain.h>

One stable caller-owned consumer token.

Note

Zero-initialize before first acquisition. On SUCCESS the provider borrows this exact object; do not copy, mutate or reclaim it until release succeeds. Internal fields are not application controls. A release is the provider’s final access, not proof that a peripheral has stopped. Release only after that consumer’s IRQ, DMA and observer drain.

Public Members

nx_clock_domain_t *owner
struct nx_clock_lease *next
uint64_t epoch
struct nx_clock_barrier_t
#include <clock_domain.h>

Epoch-bound close control and quiescence evidence.

Note

A value copy is allowed. This is not an authorization token or proof about unregistered consumers. Domain storage lives longer than every copy. A successful reopen invalidates all prior controls without resetting the epoch.

Public Members

nx_clock_domain_t *domain
uint64_t epoch

dp83848.h

Explicit DP83848 identity, reset and observed link mechanism.

Author

Nexus Team

Defines

NX_DP83848_TI_ID
NX_DP83848_NS_ID
NX_DP83848_10_HALF
NX_DP83848_10_FULL
NX_DP83848_100_HALF
NX_DP83848_100_FULL

Functions

nx_result_t nx_dp83848_probe(nx_dp83848_t *phy, nx_time_us_t deadline)

Read exact supported identity; mismatch never becomes a default PHY.

Parameters:

  • phy – [inout] Explicit MDIO face, address and expected supported model.

  • deadline – [in] Finite absolute MDIO clock deadline.

Returns:

Success, UNSUPPORTED for identity mismatch, or MDIO error.

nx_result_t nx_dp83848_reset(nx_dp83848_t *phy, nx_time_us_t deadline)

Bounded BMCR soft reset and observed self-clearing acknowledgement.

Note

Task-only finite absolute deadline; reset restraps the device and clears configured truth. This is not a GPIO, power or strap proof.

Parameters:

  • phy – [inout] Proved identity and caller-owned component state.

  • deadline – [in] Finite absolute MDIO clock deadline.

Returns:

Success after real reset acknowledgement, or state/MDIO error.

nx_result_t nx_dp83848_configure(nx_dp83848_t *phy, const nx_dp83848_mode_t *mode, nx_time_us_t deadline)

Start explicit negotiation or fixed mode, never wait for fake link.

Note

Task-only; identity must be proved. SUCCESS means registers configured, not autonegotiation complete. Failures retain configured=false.

Parameters:

  • phy – [inout] Proved identity, kept live through operations.

  • mode – [in] Explicit fixed mode or negotiation advertisement.

  • deadline – [in] Finite absolute MDIO clock deadline.

Returns:

Success means configured registers; otherwise no configured truth.

Observe latch-low BMSR twice and DP83848 PHYSTS speed/duplex truth.

Note

Task-only; output changes only on SUCCESS. up requires actual link and complete autonegotiation when selected. Protocol or remote fault does not invent speed/link. MAC application remains an external action.

Parameters:

  • phy – [inout] Probed and configured caller-owned component.

  • link – [out] Observed value, separate from component storage.

  • deadline – [in] Finite absolute MDIO clock deadline.

Returns:

Success copies observed link; other results preserve output.

struct nx_dp83848_mode_t
#include <dp83848.h>

External policy explicitly selects autonegotiation or fixed mode.

Public Members

uint8_t advertisement
bool autonegotiation
bool full_duplex
uint16_t speed_mbps
struct nx_dp83848_t
#include <dp83848.h>

Caller-owned PHY state; no board address, reset GPIO or worker default.

Note

expected_id selects TI or NS model, ignoring revision nibble only. One task owner serializes this component and the shared MDIO port.

Public Members

const nx_mdio_port_t *mdio
uint32_t expected_id
uint8_t address
bool probed
bool configured
nx_dp83848_mode_t mode

file_flash.h

Native persistent file Flash model with fault injection.

Author

Nexus Team

Version

1.0.0

Date

2026-10-09

Copyright

Copyright (c) 2026 Nexus Team

Functions

nx_storage_status_t nx_file_flash_open(nx_file_flash_t *flash, const char *path, size_t size, size_t erase_size, size_t program_size)

Open an exclusively locked persistent host Flash model.

Note

Task-only POSIX model. Does not qualify MCU Flash or actual power loss; existing file size mismatch is rejected without truncation.

Parameters:

  • flash – [out] Unused caller-owned storage

  • path – [in] Regular-file path; symlink traversal rejected

  • size – [in] Exact persistent byte size

  • erase_size – [in] Uniform erase block bytes

  • program_size – [in] Aligned program bytes, 1..256

Returns:

OK or INVALID/IO; failed open retains no file descriptor

void nx_file_flash_close(nx_file_flash_t *flash)

Close the host file after all store users have quiesced.

Note

No future port calls are permitted until explicit reopen.

Parameters:

  • flash – [inout] Open serialized model

void nx_file_flash_fail_after(nx_file_flash_t *flash, int64_t events)

Set an explicit model interruption boundary.

Note

Zero simulates power-off until explicitly cleared.

Parameters:

  • flash – [inout] Serialized open model

  • events – [in] Programmed/erased bytes and sync attempts permitted; negative disables

struct nx_file_flash_t
#include <file_flash.h>

Public Members

int fd
nx_storage_port_t port
int64_t fail_after
uint64_t mutation_events

flash_storage.h

Explicit physical Flash-region adapter without global registry.

Author

Nexus Team

Functions

nx_result_t nx_flash_storage_bind(nx_flash_storage_adapter_t *adapter, nx_flash_region_t region, nx_time_us_t deadline, nx_storage_port_t *port)

Bind an explicit writable uniform-erase physical region.

Note

Task-only, serialized caller. No region is reserved by the platform. Mixed sector geometries require another explicit storage adapter; this one rejects them. IO pulse settlement guarantees sync durability; no caller buffer survives a port call. Physical power-loss remains unqualified.

Parameters:

  • adapter – [out] Unused caller storage kept through all store calls

  • region – [in] Externally selected writable physical region

  • deadline – [in] Absolute whole-transaction deadline for mutations

  • port – [out] Narrow synchronous persistent port, valid on SUCCESS

Returns:

SUCCESS or INVALID/PERMISSION/UNSUPPORTED geometry error

void nx_flash_storage_set_deadline(nx_flash_storage_adapter_t *adapter, nx_time_us_t deadline)

Set the next transaction’s one absolute mutation deadline.

Note

Caller serializes and sets this before open/save/recovery. Per-pulse timeouts cannot preempt hardware pulses; IO settles before return.

Parameters:

  • adapter – [inout] Bound adapter with no active store operation

  • deadline – [in] Absolute deadline in nx_time_now_us domain

struct nx_flash_storage_adapter_t
#include <flash_storage.h>

Caller-owned adapter, no dynamic binding or global token lookup.

Public Members

nx_flash_region_t region
nx_time_us_t deadline

log.h

Instance-local synchronous bounded log sink.

Author

Nexus Team

Enums

enum nx_log_level_t

Structured severity, with filtering before touching a sink.

Values:

enumerator NX_LOG_DEBUG
enumerator NX_LOG_INFO
enumerator NX_LOG_WARNING
enumerator NX_LOG_ERROR

Functions

nx_result_t nx_log_init(nx_log_t *logger, nx_log_sink_port_t sink, nx_log_level_t minimum)

Initialize an unused logger before exposing it to tasks.

Parameters:

  • logger – [out] Unused caller storage

  • sink – [in] Required bounded synchronous sink

  • minimum – [in] Minimum accepted severity

Returns:

SUCCESS or INVALID

nx_result_t nx_log_write(nx_log_t *logger, nx_log_level_t level, const void *bytes, size_t length, nx_time_us_t deadline)

Write caller bytes, with no implicit allocation/formatting.

Note

Task multi-producer entry with nonblocking serialization. M0/M0+ use CPU-local saved-PRIMASK metadata exclusion and require privileged callers on one CPU. Sink calls run after restoring the incoming mask. This does not make NMI/HardFault or cross-security-domain writers valid. IRQ use is prohibited. Drop/retry policy remains with the external caller.

Parameters:

  • logger – [inout] Live instance

  • level – [in] Message severity

  • bytes – [in] Message bytes, borrowed only during this call

  • length – [in] Byte count; zero permits NULL

  • deadline – [in] Absolute deadline understood by sink

Returns:

SUCCESS for filtered/sent bytes, BUSY for concurrent/recursive writes, STATE after stop, otherwise sink error

nx_result_t nx_log_flush(nx_log_t *logger, nx_time_us_t deadline)

Flush an explicit sink without creating a background worker.

Note

Same task/privilege/CPU domain as write.

Parameters:

  • logger – [inout] Live instance

  • deadline – [in] Absolute sink deadline

Returns:

SUCCESS, BUSY, STATE, UNSUPPORTED or sink error

nx_result_t nx_log_stop(nx_log_t *logger)

Reject new writes and test whether the sink has exited.

Note

Task context. A stop caller may retry; no active sink call is forcibly cancelled. Join publishers before reclaiming logger/sink storage.

Parameters:

  • logger – [inout] Live instance; external users must eventually join

Returns:

SUCCESS when no sink call is active, BUSY while draining

struct nx_log_sink_port_t
#include <log.h>

Synchronous caller-injected sink.

Note

write/flush release every byte buffer before returning even on timeout/error; asynchronous/DMA sinks require their own settled adapter. Calls are bounded by absolute monotonic deadlines, in task context. No sink discovery, allocation, formatting, worker or global error handler exists.

Public Members

void *context
nx_result_t (*write)(void*, nx_log_level_t, const void*, size_t, nx_time_us_t deadline)
nx_result_t (*flush)(void*, nx_time_us_t deadline)
struct nx_log_t
#include <log.h>

Logger storage belongs to its caller; shared immutable port is copied.

Public Members

nx_log_sink_port_t sink
nx_log_level_t minimum
uint32_t busy
uint32_t stopped

modbus_rtu.h

Bounded Modbus RTU core and explicit RS485 ports.

Author

Nexus Team

Defines

NX_MODBUS_ADU_MAX
NX_MODBUS_REGISTER_MAX

Enums

enum nx_modbus_register_result_t

Values:

enumerator NX_MODBUS_OK
enumerator NX_MODBUS_ILLEGAL_ADDRESS
enumerator NX_MODBUS_ILLEGAL_VALUE
enumerator NX_MODBUS_DEVICE_FAILURE
enumerator NX_MODBUS_DEVICE_BUSY

Values:

Functions

uint16_t nx_modbus_crc16(const uint8_t *bytes, size_t length)

Compute standard Modbus CRC16 over caller bytes.

Parameters:

  • bytes – [in] Input, NULL only when length is zero

  • length – [in] Byte count

Returns:

CRC16; zero for invalid NULL input with nonzero length

bool nx_modbus_rtu_init(nx_modbus_rtu_t *server, const nx_modbus_config_t *config)

Initialize an unused or fully quiesced protocol instance.

Note

Task-only; configuration is copied, contexts stay live. First direction(false) failure is reported; no worker or UART is created. Reinitializing a faulted TX borrow is prohibited; stop/recover it first.

Parameters:

  • server – [out] Caller-owned storage, no existing transport borrow

  • config – [in] Explicit register/RS485 ports and finite budgets

Returns:

True when initialized into RX silence acquisition

bool nx_modbus_rtu_feed(nx_modbus_rtu_t *server, uint8_t byte, uint64_t arrival_us)

Feed an externally timestamped UART byte.

Note

Task-only. IRQ queues are external, bounded and explicit; queue overflow must call rx_error. No live UART discovery or ISR callback.

Parameters:

  • server – [inout] Initialized instance, serialized by caller

  • byte – [in] Wire byte

  • arrival_us – [in] Capture timestamp in port monotonic domain

Returns:

True if byte joined the frame, false for discard/error

bool nx_modbus_rtu_poll(nx_modbus_rtu_t *server, uint64_t now_us)

Service RTU silence and bounded synchronous RS485 response.

Note

Task-only, explicit external scheduling. RS485 drain must observe the final stop bit. Failed abort retains TX bytes and asserted DE in LINK_FAULTED; keep instance/port alive until successful recover or stop.

Parameters:

  • server – [inout] Initialized instance, single execution owner

  • now_us – [in] Snapshot in the same monotonic domain

Returns:

True for successful progress, false for clock/transport error

void nx_modbus_rtu_rx_error(nx_modbus_rtu_t *server, uint64_t now_us)

Discard an errored or overrun receive frame.

Note

Task-only. Does not discard a retained faulted TX borrow.

Parameters:

  • server – [inout] Initialized serialized instance

  • now_us – [in] Error timestamp in port’s monotonic domain

bool nx_modbus_rtu_recover(nx_modbus_rtu_t *server)

Settle retained TX then restore receive silence acquisition.

Note

Explicit task maintenance action, no fabricated recovery.

Parameters:

  • server – [inout] Initialized serialized instance with live ports

Returns:

True only after actual port abort/drain and receive direction

bool nx_modbus_rtu_stop(nx_modbus_rtu_t *server)

Settle the port before reclaiming protocol storage.

Note

Stop future feed/poll users first. No future use except explicit initialization is allowed after successful stop.

Parameters:

  • server – [inout] Initialized, exclusively owned instance

Returns:

True when no transport borrow remains and instance is stopped; false preserves fault state, TX bytes and all port lifetime obligations

struct nx_modbus_registers_t
#include <modbus_rtu.h>

Public Members

void *context
nx_modbus_register_result_t (*read)(void*, uint16_t, uint16_t, uint16_t*)
nx_modbus_register_result_t (*authorize_write)(void*, uint16_t, uint16_t, const uint16_t*)
nx_modbus_register_result_t (*write_atomic)(void*, uint16_t, uint16_t, const uint16_t*)
struct nx_modbus_rs485_port_t
#include <modbus_rtu.h>

Public Members

void *context
uint64_t (*now_us)(void*)
bool (*direction)(void*, bool transmit)
bool (*write)(void*, const uint8_t*, size_t, uint64_t deadline_us)
bool (*drain)(void*, uint64_t deadline_us)
bool (*abort_and_settle)(void*, uint64_t deadline_us)
struct nx_modbus_counters_t
#include <modbus_rtu.h>

Public Members

uint64_t frames
uint64_t accepted
uint64_t crc_errors
uint64_t timing_errors
uint64_t overflows
uint64_t exceptions
uint64_t broadcasts
uint64_t tx_errors
uint64_t clock_errors
struct nx_modbus_config_t
#include <modbus_rtu.h>

Public Members

uint8_t address
uint32_t baudrate
uint8_t bits_per_character
uint32_t tx_timeout_us
uint32_t abort_timeout_us
nx_modbus_registers_t registers
nx_modbus_rs485_port_t port
struct nx_modbus_rtu_t
#include <modbus_rtu.h>

Public Members

nx_modbus_config_t config
nx_modbus_counters_t counters
nx_modbus_link_state_t state
uint32_t t1_5_us
uint32_t t3_5_us
uint64_t last_byte_us
uint64_t last_event_us
uint16_t rx_length
uint16_t tx_length
uint8_t rx[NX_MODBUS_ADU_MAX]
uint8_t tx[NX_MODBUS_ADU_MAX]
uint16_t values[NX_MODBUS_REGISTER_MAX]
bool initialized
bool clock_started

owner_observer.h

Explicit owner progress diagnostics without default state.

Author

Nexus Team

Functions

nx_result_t nx_owner_observer_bind(nx_owner_observer_t *observer, nx_bus_owner_t *owner)

Bind an initialized exact owner without creating work.

Parameters:

  • observer – [inout] Fresh zero/detached sidecar, distinct from owner.

  • owner – [inout] Initialized stable owner, no concurrent lifecycle.

Returns:

SUCCESS or INVALID/STATE, no service or borrow on rejection.

nx_result_t nx_owner_observer_service(nx_owner_observer_t *observer, nx_time_us_t now, nx_owner_observation_t *out)

Execute exactly one real service step and copy diagnostics.

Note

Clock reversal never blocks drain or rewrites its result. Snapshot uses the existing guard outside hardware service. No callback, slot scan or worker occurs under that guard. Quarantine and elapsed deadlines never release a loan. Output also excludes accepted descriptors and payloads. Only the owner/slot control spans are checked here.

Parameters:

  • observer – [inout] Bound sidecar on the unique executor.

  • now – [in] Monotonic timestamp, independent of service result.

  • out – [out] Distinct stable output, no retained references.

Returns:

Actual service result; invalid bindings reject beforehand.

void nx_owner_observer_detach(nx_owner_observer_t *observer)

Drop only the observation binding, no owner/loan teardown.

Parameters:

  • observer – [inout] Caller-serialized sidecar, no remaining readers.

struct nx_owner_observation_t
#include <owner_observer.h>

Copied service facts without request, payload or slot references.

Public Members

nx_result_t service_result
nx_result_t diagnostic_result
nx_time_us_t observed_at
nx_time_us_t max_gap
uint32_t calls
uint32_t busy
uint32_t errors
uint32_t quarantines
uint32_t clock_errors
nx_owner_ticket_t active
nx_request_state_t active_state
bool has_active
bool idle
struct nx_owner_observer_t
#include <owner_observer.h>

Opt-in caller sidecar; no pointer added to default owner.

Note

Exact owner, slots and guard remain live until detach and all observer calls exit. The same unique owner executor calls this wrapper; producer calls retain the owner guard. Never reinitialize/replace the bound owner underneath it.

Public Members

nx_bus_owner_t *owner
nx_time_us_t last_observed
nx_owner_observation_t observation
bool observed

spi_async_owner.h

Optional finite async SPI executor for one explicit bus.

Author

Nexus Team

Functions

nx_owner_executor_port_t nx_spi_async_owner_executor_port(nx_spi_async_owner_executor_t *executor, const nx_spi_port_t *port)

Bind one async-capable bus to an explicit owner executor.

Note

Startup/task context. Operations use nx_spi_owner_operation_t endpoints on this bus only; membership is checked before admission. No polling fallback is selected. Controller and executor remain live through drain, control acknowledgement and observer exit. QUARANTINED retains both buffer loans. Hardware stop and IRQ/notification destruction are explicit external steps after owner shutdown, not part of this bind.

Parameters:

  • executor – [out] Fresh storage with no previous outstanding loans.

  • port – [in] Initialized controller exclusively owned by this executor; direct clients and other owners must quiesce.

Returns:

Valid executor port, or a zero port for incomplete methods.

struct nx_spi_async_owner_executor_t
#include <spi_async_owner.h>

Exact async storage independent of the polling adapter.

Note

inner is a private publication object. Its borrow must end before the outer owner publishes SETTLED. No queue, payload copy, allocation or hidden worker is created.

Public Members

const nx_spi_port_t *port
nx_spi_request_t inner
bool pending

spi_owner.h

Explicit polling SPI executor for the bounded owner adapter.

Author

Nexus Team

Functions

nx_owner_executor_port_t nx_spi_owner_executor_port(nx_spi_owner_executor_t *executor, const nx_spi_port_t *port)

Bind an explicit synchronous SPI execution adapter.

Note

start executes a real CPU-active polling transaction and releases all IO buffers before returning. Owner service later publishes its caller-owned request. Polling cannot be preempted by another task’s cancel; once the polling call returns, its result is final despite later cancellation or publication delay. Do not claim IRQ/DMA mode or low-CPU asynchronous hardware execution. Endpoints must prove their controller identity before any wire effect; distinct chip selects on this controller remain valid. The controller and executor outlive owner shutdown and all observers.

Parameters:

  • executor – [out] Fresh storage with no outstanding operation

  • port – [in] Controller exclusively serviced by this owner

Returns:

Port for nx_bus_owner_init, or a zero port for invalid input

struct nx_spi_owner_operation_t
#include <spi_owner.h>

Caller-owned SPI transaction descriptor, borrowed until SETTLED.

Public Members

const nx_spi_endpoint_t *endpoint
const uint8_t *tx
uint8_t *rx
size_t length
struct nx_spi_owner_executor_t
#include <spi_owner.h>

Exact polling executor storage; no payload copy or queue.

Public Members

const nx_spi_port_t *port
nx_result_t result
size_t transferred
bool pending

storage.h

Two-bank durable blob storage over an explicit narrow port.

Author

Nexus Team

Defines

NX_STORAGE_HEADER_SIZE

Enums

enum nx_storage_status_t

Storage errors expose retry/reopen/recovery decisions.

Values:

enumerator NX_STORAGE_OK
enumerator NX_STORAGE_INVALID
enumerator NX_STORAGE_IO
enumerator NX_STORAGE_CORRUPT
enumerator NX_STORAGE_NO_SPACE
enumerator NX_STORAGE_NOT_FOUND
enumerator NX_STORAGE_UNSUPPORTED

Functions

nx_storage_status_t nx_storage_open(nx_storage_t *storage, const nx_storage_port_t *port, size_t offset, size_t bank_size, void *workspace, size_t workspace_bytes)

Open/recover two externally supplied uniform erase banks.

Note

Task-only bounded scan over both bank payloads. Workspace remains borrowed by the instance through every subsequent load/save call.

Parameters:

  • storage – [out] Unused or quiesced instance, no concurrent calls

  • port – [in] Persistent settled port, may be storage’s existing port

  • offset – [in] Erase-aligned start within port region

  • bank_size – [in] Each bank’s erase-aligned byte size

  • workspace – [in] Caller buffer, disjoint from instance/payload

  • workspace_bytes – [in] At least max(32, port.program_size)

Returns:

OK for recovered/empty store, CORRUPT for ambiguous or only invalid committed generations, IO/INVALID for port/geometry failures

nx_storage_status_t nx_storage_load(nx_storage_t *storage, void *output, size_t *size)

Load and validate the latest committed whole blob.

Note

Output bytes valid only on OK; failure may partially write output. No destination pointer is retained after returning.

Parameters:

  • storage – [inout] Open instance, exclusively owned for this call

  • output – [out] Destination; NULL requests only required size

  • size – [inout] Input capacity, output payload/required bytes

Returns:

OK, NOT_FOUND, NO_SPACE, CORRUPT or IO/INVALID

nx_storage_status_t nx_storage_save(nx_storage_t *storage, const void *data, size_t size)

Commit a complete blob to the inactive bank.

Note

Marker is programmed last after sync. Failed mutation keeps the previous bank and requires reopen; ambiguous marker failure can mean the new blob committed. Product owns migration/authentication/recovery policy.

Parameters:

  • storage – [inout] Open exclusively owned instance

  • data – [in] Payload disjoint from workspace, borrowed during call

  • size – [in] Payload bytes; zero permits NULL

Returns:

OK, NO_SPACE, INVALID or underlying port error

size_t nx_storage_capacity(const nx_storage_t *storage)

Query usable blob capacity without touching hardware.

Parameters:

  • storage – [in] Geometry-established instance, or NULL

Returns:

Payload bytes per bank, or zero for invalid geometry

struct nx_storage_port_t
#include <storage.h>

Synchronous settled persistent Flash port.

Note

Task-only; caller serializes every operation. Offsets are byte-relative to the supplied region. program changes only 1 to 0 in complete aligned program units; erase uses complete uniform erase units. sync makes earlier successful writes durable. Errors can change a subset of addressed units, but never retain caller buffers after returning. RAM is a model, not a persistent implementation. Product owns the region/layout and power policy.

Public Members

void *ctx
size_t size
size_t erase_size
size_t program_size
nx_storage_status_t (*read)(void*, size_t, void*, size_t)
nx_storage_status_t (*program)(void*, size_t, const void*, size_t)
nx_storage_status_t (*erase)(void*, size_t, size_t)
nx_storage_status_t (*sync)(void*)
struct nx_storage_t
#include <storage.h>

Instance metadata with caller-sized workspace.

Note

Two independently erasable banks commit whole blobs. No heap, global registry, maximum pool or default product reservation. Wire format v1 is explicit little-endian and CRC-protected, not authenticated. Keep instance, port context and workspace alive through close/quiescence. A mutating I/O error invalidates opened; reopen to establish which commit actually survived.

Public Members

nx_storage_port_t flash
size_t offset
size_t bank_size
size_t payload_offset
uint64_t generation
size_t payload_size
int active_bank
bool opened
uint8_t *workspace
size_t workspace_bytes

uart_owner.h

Explicit IRQ UART executor with private provider settlement.

Author

Nexus Team

Functions

nx_owner_executor_port_t nx_uart_owner_executor_port(nx_uart_owner_executor_t *executor, const nx_uart_port_t *uart)

Bind a UART controller to one explicit service executor.

Note

Startup/task context. Controller and executor remain alive through owner stop/drain and external observer quiescence. Direct UART users must not share this controller. Queued time belongs to the bus owner; after start the UART’s first terminal TC/error/cancel/deadline fact is authoritative. cancel observes provider completion/deadline before asking it to abort. Failed drain keeps both requests QUARANTINED; service must continue during recovery. Outer SETTLED never precedes inner acquire-observed SETTLED and pointer detach. The application separately stops hardware and RX consumers only after all owner operations and controls quiesce.

Parameters:

  • executor – [inout] Unused caller-owned storage, no concurrent calls

  • uart – [inout] Initialized UART exclusively owned by this executor

Returns:

Port for nx_bus_owner_init, or an invalid zero port for NULL

struct nx_uart_owner_operation_t
#include <uart_owner.h>

Caller-owned TX payload descriptor borrowed until outer SETTLED.

Public Members

const uint8_t *data
size_t length
struct nx_uart_owner_executor_t
#include <uart_owner.h>

One executor’s exact private provider request.

Note

inner is a separate publication object, not another outer queue or caller admission. Only this executor accesses it; producers retain their outer request and payload until the bus owner publishes outer SETTLED. No buffer copy, heap, worker or pool. Never pass inner to application observers.

Public Members

const nx_uart_port_t *port
nx_uart_tx_request_t inner
bool pending

user_io_broker.h

Narrow kernel-invoked user GPIO message contract.

Author

Nexus Team

Version

1.0.0

Date

2026-10-11

Copyright

Copyright (c) 2026 Nexus Team

Typedefs

typedef struct nx_user_io_broker nx_user_io_broker_t

Broker and persistent kernel call storage stay provider private.

typedef struct nx_user_io_call nx_user_io_call_t

Enums

enum nx_user_io_constants

Only scalar GPIO operations are admitted by this message ABI.

Values:

enumerator NX_USER_IO_ABI
enumerator NX_USER_GPIO_READ
enumerator NX_USER_GPIO_WRITE

Functions

nx_user_io_result_t nx_user_io_broker_gpio(nx_user_io_broker_t *broker, nx_user_io_call_t *call, const nx_user_io_message_t *message, nx_user_io_reply_t *reply)

Execute one scalar GPIO message through a trusted gateway.

Note

Kernel-invoked privileged Thread with incoming masks clear, one serialized broker executor. Principal comes from the configured trusted kernel identity port. Pin both validated memory ranges before any GPIO call; snapshot input once, copy an initialized reply. Kernel call storage is zero-initialized outside user RAM and must outlive retained pins. No OS SVC/MPU/TZ wiring or user privilege elevation is provided by this component.

Returns:

REJECTED has accepted=false, no pin/effect. ACCEPTED may already be detached or retain cleanup after a failure.

nx_user_io_result_t nx_user_io_broker_gpio_finish(nx_user_io_broker_t *broker, nx_user_io_call_t *call)

Retry retained cleanup without reading users or replaying IO.

Note

Same privileged serialized kernel owner, incoming masks clear. Successful unpin follows actual provider/observer drain; a failed unpin keeps memory, call slot and identity retained. Does not imply that a previously performed GPIO write can be reversed.

struct nx_user_io_message_t
#include <user_io_broker.h>

Untrusted copied message; identity never comes from users.

Note

No arbitrary port, MMIO, callback, slot or principal pointer. reserved words must be zero. WRITE has read_mask=0 and disjoint set/reset masks. READ has zero set/reset masks and a positive authorized read_mask. Caller keeps storage immutable until the gateway completes or retains its pin.

Public Members

uint32_t abi
uint32_t device
uint32_t operation
uint32_t set_mask
uint32_t reset_mask
uint32_t read_mask
uint32_t reserved[2]
struct nx_user_io_reply_t
#include <user_io_broker.h>

Fully initialized copied result; value is zero for errors/WRITE.

Public Members

uint32_t result
uint32_t value
struct nx_user_io_result_t
#include <user_io_broker.h>

Distinguish admission, cleanup retention and possible effect.

Note

accepted means at least one memory pin was acquired. On retained=true the exact kernel call slot and user address space remain borrowed. device_effect_possible is set before a WRITE provider call; an error cannot authorize replay. result describes admission/device execution; cleanup_result separately describes the most recent release attempt. This is software responsibility, not physical pin evidence.

Public Members

nx_result_t result
nx_result_t cleanup_result
bool accepted
bool retained
bool device_effect_possible