Document source: e47887d3a11f; code reference: e47887d3a11f. 中文. Source language: en; requested: en; actual: en; translation: reviewed.

Source documentation does not establish software or physical hardware qualification. See the support and qualification records for their exact scope.

Extension and lifecycle APIs

These public headers describe framed data, explicit owners, retained clocks and trusted mediation. Their declarations do not establish a board connection, execution mode, kernel gateway or physical qualification. Construction, memory ownership and final-access requirements remain part of each contract.

Explicit F407 entropy construction

For an F407 assembly, explicitly call nexus_add_stm32f407_entropy(target) and link that target at the product’s composition site. It owns the unique static RNG source and refuses a second constructor. The getter nx_stm32f407_entropy_instance() returns an existing readonly face; it performs no startup, register access or factory registration.

After successful Platform startup, call nx_stm32f407_entropy_instance_start() with exact validated Board/profile hse_hz and hclk_hz facts. The implementation checks the live PLL48/HCLK relationship and acquires only its RNG clock gate; it neither configures the shared PLL nor starts Platform. The reviewed source choices are 8 MHz HSE or 16 MHz HSI. The product must preserve those clock dependencies through stop.

Run start/stop from one privileged, unmasked, serialized task context. Join every entropy consumer before nx_stm32f407_entropy_instance_stop(), and require that stop to succeed before withdrawing Platform clocks. Failed withdrawal retains the same owner and cleanup responsibility; retry stop without resetting or rebinding its state. A stopped face remains valid and rejects data calls with STATE. This explicit constructor is separate from TOML typed-factory selection; neither it nor software RNG health checks qualify physical min-entropy or HIL.

stm32f407_entropy.h

Explicit optional construction of the unique F407 RNG source.

Author

Nexus Team

Functions

const nx_entropy_port_t *nx_stm32f407_entropy_instance(void)

Return the existing static source face without starting it.

Note

No allocation, register access, clock acquisition, locking or registration. The face’s private state belongs to the unique explicit constructor target. Data calls use its shared provider table directly; a cold face reports STATE.

Returns:

Stable readonly face, including while the source is stopped

nx_result_t nx_stm32f407_entropy_instance_start(const nx_stm32f407_entropy_config_t *config)

Start the explicit source after successful Platform startup.

Note

Privileged unmasked serialized task. One unique hardware RNG owner; a repeated live start returns BUSY. No scheduler, Platform startup or clock-profile change is implicit. A post-write IO may retain owned effects; stop must succeed before releasing Platform clock resources or recovery state.

Parameters:

• config – [in] Exact validated Board/profile facts, copied during this call; source/PLL48 dependency stays live until stop

Returns:

SUCCESS, CONTEXT, INVALID, BUSY, STATE, UNSUPPORTED or IO

nx_result_t nx_stm32f407_entropy_instance_stop(void)

Stop the source before withdrawing Platform clock resources.

Note

Privileged unmasked serialized task after source consumers have joined. Retry the same stop on failed withdrawal; do not reset or rebind private state. The existing static face remains valid and reports STATE while admission is closed.

Returns:

SUCCESS when stopped; IO retains failed cleanup ownership

struct nx_stm32f407_entropy_config_t

#include <stm32f407_entropy.h>

Exact Board/profile facts admitted against the live RCC.

Note

First scope uses an 8 MHz reviewed HSE Board or the fixed 16 MHz HSI. These values come from validated assembly facts, not guessed hardware. Start checks exact PLL48 and HCLK; caller maintains the source/PLLQ/HCLK dependency until stop.

Public Members

uint32_t hse_hz

uint32_t hclk_hz

frame_stream.h

Complete framed blocks and strided DMA consumer loans.

Author

Nexus Team

Defines

NX_FRAME_MAX_PLANES

Typedefs

typedef struct nx_frame_dma_loan nx_frame_dma_loan_t

Immutable consumer block retained through final DMA access.

Note

Zero-initialize before first acquisition. Keep this exact control live and exclusively owned until release; copied tokens never authorize earlier reuse or another instance.

Enums

enum nx_frame_sample_t

Memory representations; these values never configure a wire.

Values:

enumerator NX_FRAME_PCM_SIGNED

enumerator NX_FRAME_PCM_UNSIGNED

enumerator NX_FRAME_PDM_BITS

enum nx_frame_audio_kind_t

Serial framing whose complete units determine block geometry.

Values:

enumerator NX_FRAME_AUDIO_I2S

enumerator NX_FRAME_AUDIO_SAI

enumerator NX_FRAME_AUDIO_PDM

enum nx_frame_alignment_t

Position of useful sample bits in each stored slot container.

Values:

enumerator NX_FRAME_SAMPLE_LSB

enumerator NX_FRAME_SAMPLE_MSB

Functions

nx_result_t nx_frame_layout_audio(const nx_frame_audio_format_t *format, nx_frame_layout_t *layout)

Compute complete audio storage without touching payload.

Note

Task/IRQ bounded pure calculation. No format conversion, serializer configuration or codec negotiation is performed.

Parameters:

• format – [in] Explicit framing, sample and stored slot geometry.

• layout – [out] Separate fresh output, unchanged on rejection.

Returns:

SUCCESS, INVALID for incompatible framing or EXHAUSTED on arithmetic overflow; never retains an input or allocates.

nx_result_t nx_frame_layout_planar(const nx_frame_plane_t *planes, size_t count, nx_frame_layout_t *layout)

Check and copy planar/strided frame geometry.

Note

Bounded pure calculation. Pixel/color meanings remain with the selected camera/display/DMA adapter.

Parameters:

• planes – [in] 1..NX_FRAME_MAX_PLANES immutable plane descriptions.

• count – [in] Exact plane count, not a runtime pool maximum.

• layout – [out] Fresh output, unchanged on every rejection.

Returns:

SUCCESS, INVALID for empty/overlapping/short-stride planes, or EXHAUSTED on byte arithmetic overflow.

nx_result_t nx_frame_stream_initialize(nx_frame_stream_t *framed, nx_stream_t *stream, const nx_frame_layout_t *layout)

Cold-bind a complete-frame layout to an existing queue.

Note

Task-only cold assembly, O(n squared) storage checks. No hardware or DMA-domain admission is inferred. Keep all queue/control/payload storage live through final stop.

Parameters:

• framed – [out] Fresh control disjoint from queue and payloads.

• stream – [inout] Initialized unborrowed queue with all slots free.

• layout – [in] Checked complete-frame geometry, copied on success.

Returns:

SUCCESS, INVALID for aliases/short buffers/bad layout, BUSY for outstanding blocks or STATE while stopping.

nx_result_t nx_frame_stream_publish(nx_frame_stream_t *framed, const nx_stream_fill_t *fill, uint32_t flags)

Publish one complete frame after final producer access.

Note

Bounded task/IRQ metadata. Reserve/prepost/abort still use the existing stream; publication always has exact frame size.

Parameters:

• framed – [inout] Exclusive serialized producer binding.

• fill – [in] Existing stream producer loan, detached from all DMA.

• flags – [in] Existing observed stream boundary flags.

Returns:

Existing stream result; rejection retains the fill loan.

nx_result_t nx_frame_stream_post_publish(nx_frame_stream_t *framed, nx_stream_producer_t *producer, const nx_stream_fill_t *fill, uint32_t flags)

Publish one complete frame from the existing posted FIFO.

Note

Bounded task/IRQ metadata; preserves pending and FIFO counts.

Parameters:

• framed – [inout] Same producer binding and complete-frame layout.

• producer – [inout] Existing posted producer bound to this stream.

• fill – [in] Oldest pending loan, absent from all hardware targets.

• flags – [in] Observed existing stream boundary flags.

Returns:

Existing posted-publication result, INVALID for foreign pool.

nx_result_t nx_frame_stream_acquire(nx_frame_stream_t *framed, nx_frame_dma_loan_t *loan)

Acquire the next complete immutable DMA consumer loan.

Note

Task/IRQ; output disjointness scans the fixed pool in O(n) before the O(1) guarded queue operation. Output cannot alias queue controls or any full-capacity pool payload. EMPTY creates no loan and never repeats a previous frame. Caller owns silence/blanking/stop policy. Do not use retries as additional observed boundaries.

Parameters:

• framed – [inout] Same serialized consumer, one call per observed output boundary when using underrun accounting.

• loan – [inout] Zero or previously released control, unchanged on error.

Returns:

SUCCESS, EMPTY with saturating underrun count, BUSY for a live loan, INVALID for output alias or STATE for an incomplete queued block.

nx_result_t nx_frame_dma_view(const nx_frame_dma_loan_t *loan, size_t plane, size_t x, size_t y, size_t width, size_t height, nx_frame_dma_view_t *view)

Derive a strided byte rectangle from a live frame loan.

Note

Task/IRQ; an O(n) immutable-pool output check precedes the O(1) guarded view calculation. Output cannot alias the loan, queue controls or any full-capacity pool payload. The adapter checks pixel alignment, resource and DMA domain.

Parameters:

• loan – [in] Exact live immutable DMA consumer loan.

• plane – [in] Plane index in the bound layout.

• x – [in] Byte column within a row, not a pixel count.

• y – [in] First complete row.

• width – [in] Positive bytes per selected row.

• height – [in] Positive selected row count.

• view – [out] Fresh output unchanged on failure.

Returns:

SUCCESS, INVALID for out-of-plane rectangles or STATE for stale/foreign loans; no DMA access begins here.

nx_result_t nx_frame_dma_release(nx_frame_stream_t *framed, nx_frame_dma_loan_t *loan, const nx_dma_drain_facts_t *drain)

Release only after the adapter proves final DMA access.

Note

Bounded task/IRQ metadata. Timeout/cancel is not quiescence; failed drain retains the queue borrow, including during stop. This helper checks proof facts and does not stop hardware.

Parameters:

• framed – [inout] Original owner; another instance cannot release.

• loan – [inout] Exact acquired control, cleared only on success.

• drain – [in] Actual provider observations of engine, IRQ and peripheral quiescence; counter completion alone is not proof.

Returns:

SUCCESS, BUSY while any source remains, STATE for stale or foreign tokens, or INVALID for impossible drain counters.

struct nx_frame_audio_format_t

#include <frame_stream.h>

Immutable audio memory format, independent of codec policy.

Note

PCM frames store every slot, including inactive slots, in ascending slot order; slot_bits is the container width. I2S has two 16/32-bit slots; SAI has 1..32 8/16/32-bit slots. PDM has 1..8 byte-interleaved lanes; each byte holds eight successive bits of one lane, so frames must divide by eight. active_slots selects valid lanes/slots without compacting storage. Sample byte order is explicitly declared.

Public Members

nx_frame_audio_kind_t kind

nx_frame_sample_t sample

nx_frame_alignment_t alignment

size_t frames

uint32_t active_slots

uint8_t slots

uint8_t sample_bits

uint8_t slot_bits

bool big_endian

struct nx_frame_plane_t

#include <frame_stream.h>

One plane; the last row needs no trailing stride padding.

Note

row_bytes/stride are bytes, rows is a complete line count. A plane occupies (rows - 1) * stride + row_bytes bytes.

Public Members

size_t offset

size_t row_bytes

size_t stride

size_t rows

struct nx_frame_layout_t

#include <frame_stream.h>

Immutable frame geometry copied into a bound stream.

Note

Plane intervals, including inter-row padding, cannot overlap. bytes is the exact maximum plane end, not summed row bytes. Audio formats are separate immutable caller metadata; this layout represents their checked complete-unit storage.

Public Members

nx_frame_plane_t planes[NX_FRAME_MAX_PLANES]

size_t plane_count

size_t bytes

struct nx_frame_stream_t

#include <frame_stream.h>

Caller-owned binding; the existing stream owns every queue.

Note

Initialize before publication. One serialized producer and consumer use framed publish/acquire exclusively until stop. Hardware, queue capacity and synchronization remain explicit.

Public Members

nx_stream_t *stream

nx_frame_layout_t layout

uint32_t underruns

struct nx_frame_dma_loan

#include <frame_stream.h>

Immutable consumer block retained through final DMA access.

Note

Zero-initialize before first acquisition. Keep this exact control live and exclusively owned until release; copied tokens never authorize earlier reuse or another instance.

Public Members

nx_frame_stream_t *owner

nx_stream_block_t block

const struct nx_frame_dma_loan *identity

struct nx_frame_dma_view_t

#include <frame_stream.h>

Checked 2D byte rectangle for an explicit DMA adapter.

Public Members

const uint8_t *data

size_t row_bytes

size_t stride

size_t rows

size_t span_bytes

spi_dma_owner.h

Optional typed whole-CS SPI executor for bounded BusOwner.

Author

Nexus Team

Functions

nx_owner_executor_port_t nx_spi_dma_owner_executor_port(nx_spi_dma_owner_executor_t *executor, const nx_spi_dma_owner_binding_t *binding)

Bind a fresh executor without opening hardware or admission.

Note

Task-only, all lifecycle users joined before replacement. Uses original FIFO/slots/epochs; final provider terminal result survives late cancellation. Continue unique executor service during stop and quarantine. Hardware stop, publisher join and observer join remain explicit external steps.

Parameters:

• executor – [inout] Zero fresh storage, distinct from capability/face.

• binding – [in] Initialized bus exclusively serviced by this owner.

Returns:

Executor for nx_bus_owner_init, zero port on invalid input.

nx_result_t nx_spi_dma_owner_submit(nx_bus_owner_t *owner, nx_request_t *request, nx_spi_dma_owner_operation_t *operation, const nx_wait_port_t *completion, nx_owner_ticket_t *ticket)

Check typed storage, then use bounded owner admission.

Note

The request has an absolute deadline including queue time. Task multi-producer checks run outside the metadata guard. There is no capacity scan, allocation, OS lock or worker. One operation has one CS interval with allowed SCK gaps. Schedule bounded service even when hints fail. Waiters never service the shared controller. Queued provider failures settle later without converting admission into rejection.

Parameters:

• owner – [inout] Owner with this exact typed executor.

• request – [inout] Prepared READY outer request.

• operation – [in] Immutable chain through outer SETTLED.

• completion – [in] Optional static caller hint, or NULL.

• ticket – [out] Stable slot/epoch identity on SUCCESS.

Returns:

SUCCESS means ACCEPTED; failure retains nothing.

struct nx_spi_dma_owner_operation_t

#include <spi_dma_owner.h>

Caller-owned queued and active SPI chain.

Note

The outer deadline includes queue residence. The chain, descriptors and all TX/RX or fixed cells stay borrowed until acquire-observed outer SETTLED. Counts and results use words.

Public Members

const nx_spi_dma_transaction_endpoint_t *endpoint

const nx_spi_dma_segment_t *segments

size_t count

uint8_t word_bits

struct nx_spi_dma_owner_executor_t

#include <spi_dma_owner.h>

Selected-only exact metadata; no queue, payload copy or worker.

Public Members

const nx_spi_dma_owner_binding_t *binding

nx_spi_dma_transaction_request_t inner

bool pending

mapped_storage.h

Bounded read mappings and exclusive storage requests.

Author

Nexus Team

Enums

enum nx_mapped_storage_reader_t

Read-only consumers; capability does not prove physical routing.

Values:

enumerator NX_MAPPED_STORAGE_CPU_READ

enumerator NX_MAPPED_STORAGE_XIP

enumerator NX_MAPPED_STORAGE_DMA_READ

enum nx_mapped_storage_operation_t

Physical mutation, separate from read-map ownership.

Values:

enumerator NX_MAPPED_STORAGE_PROGRAM

enumerator NX_MAPPED_STORAGE_ERASE

Functions

nx_result_t nx_mapped_storage_prepare(nx_mapped_storage_request_t *request, nx_mapped_storage_operation_t operation, size_t offset, const void *data, size_t length, nx_time_us_t deadline)

Prepare unborrowed caller storage without accessing payload.

Returns:

SUCCESS or INVALID/STATE; no retained references on failure.

const nx_mapped_storage_geometry_t *nx_mapped_storage_geometry(const nx_mapped_storage_port_t *port)

Query immutable geometry without starting hardware.

nx_result_t nx_mapped_storage_acquire(const nx_mapped_storage_port_t *port, nx_mapped_storage_reader_t reader, size_t offset, size_t length, nx_mapped_storage_loan_t *loan)

Acquire one bounded, positive read-only span on a serialized executor.

Returns:

SUCCESS or INVALID/UNSUPPORTED/BUSY/EXHAUSTED/STATE. Rejection retains no loan. Live read maps exclude all command/program/erase/cache/DMA writers. CPU/XIP/DMA consumers may run concurrently after successful acquisition.

nx_result_t nx_mapped_storage_release(const nx_mapped_storage_port_t *port, const nx_mapped_storage_loan_t *loan)

Release an exact live loan after its consumers have joined.

Returns:

SUCCESS, INVALID/STATE, or backend unmap error retaining the loan. Task-only, same serialized executor; no forced revocation or timeout release.

nx_result_t nx_mapped_storage_submit(const nx_mapped_storage_port_t *port, nx_mapped_storage_request_t *request, nx_mapped_storage_ticket_t *ticket)

Admit one exclusive PROGRAM/ERASE request with an absolute deadline.

Returns:

SUCCESS is ACCEPTED, possibly settled. Rejection retains no request or payload and produces no hardware effects. No map loan may remain live. Task-only serialized owner; no workers, allocation, locks or queue exist.

nx_result_t nx_mapped_storage_cancel(const nx_mapped_storage_port_t *port, nx_mapped_storage_ticket_t ticket)

Request cancellation by instance and nonrepeating writer epoch.

Returns:

SUCCESS starts/observes drain; STATE rejects stale/foreign identity. Cancellation never releases storage. Continue service through drain.

void nx_mapped_storage_service(const nx_mapped_storage_port_t *port)

Advance one bounded backend step or drain attempt without waiting.

Note

Backend/IRQ/data references detach before release-publication of SETTLED, which is the final request access. Failed drain is QUARANTINED; storage remains borrowed and later service may retry source withdrawal.

nx_result_t nx_mapped_storage_stop(const nx_mapped_storage_port_t *port)

Close admission and request writer cancellation.

Returns:

SUCCESS only after all map loans and writer sources are gone; BUSY retains storage and needs release/service. Repeated successful stop performs no backend operation. The owner cannot restart or revoke loans.

struct nx_mapped_storage_geometry_t

#include <mapped_storage.h>

Exact byte geometry; units divide size and one another.

Public Members

const uint8_t *mapped_base

size_t size

size_t program_unit

size_t erase_unit

uint32_t readers

struct nx_mapped_storage_request_t

#include <mapped_storage.h>

Caller-owned request and input, borrowed through SETTLED.

Note

Initialize base before prepare. PROGRAM borrows length input bytes; ERASE requires NULL input. Geometry alignment is checked at admission. Partial effects survive cancellation, timeout and I/O failure. No replay.

Public Members

nx_request_t base

nx_mapped_storage_operation_t operation

size_t offset

const void *data

size_t length

struct nx_mapped_storage_loan_t

#include <mapped_storage.h>

Stable instance-bound identity of one read mapping.

Note

Fields are immutable until release. Data stays read-only. Join every CPU, XIP instruction fetch and DMA reader before release; a copied token grants no additional loan. A failed release keeps the complete loan live.

Public Members

const void *instance

const void *data

size_t length

size_t slot

uint64_t epoch

struct nx_mapped_storage_ticket_t

#include <mapped_storage.h>

Stable writer identity; drain controls before reuse or destruction.

Public Members

const void *instance

uint64_t epoch

struct nx_mapped_storage_ops_t

#include <mapped_storage.h>

Shared immutable operations; every callback receives instance state.

Public Members

const nx_mapped_storage_geometry_t *(*geometry)(const void *context)

nx_result_t (*acquire)(void *context, nx_mapped_storage_reader_t reader, size_t offset, size_t length, nx_mapped_storage_loan_t *loan)

nx_result_t (*release)(void *context, const nx_mapped_storage_loan_t *loan)

nx_result_t (*submit)(void *context, nx_mapped_storage_request_t *request, nx_mapped_storage_ticket_t *ticket)

nx_result_t (*cancel)(void *context, nx_mapped_storage_ticket_t ticket)

void (*service)(void *context)

nx_result_t (*stop)(void *context)

struct nx_mapped_storage_port_t

#include <mapped_storage.h>

Immutable face; context and all retained storage outlive users.

Public Members

const nx_mapped_storage_ops_t *ops

void *context

mapped_storage_owner.h

Explicit portable mapped-storage constructor and storage.

Author

Nexus Team

Functions

nx_result_t nx_mapped_storage_owner_init(nx_mapped_storage_owner_t *owner, nx_mapped_storage_slot_t *slots, size_t capacity, nx_mapped_storage_backend_t backend, nx_clock_t clock)

Bind unused explicit storage without hardware or payload access.

Returns:

SUCCESS or INVALID; zero capacity, overlapping metadata/aperture, overflowing spans, inconsistent units and missing callbacks reject. Caller constructs a const face with owner_ops and this owner context.

Variables

const nx_mapped_storage_ops_t nx_mapped_storage_owner_ops

One read-only method table shared by every portable owner instance.

struct nx_mapped_storage_backend_t

#include <mapped_storage_owner.h>

Private provider boundary; immutable callbacks and independent context.

Note

Context is one explicitly sized private state span. Geometry and mapped address stay fixed. map SUCCESS establishes the readable aperture; map failure leaves no effects. unmap SUCCESS proves all aperture/cache references withdrawn; failure retains the last map loan. start is called only after request admission and mapping exclusion. start errors may have effects and always proceed through drain. poll advances bounded work, returns BUSY or a terminal result, and supplies monotonically increasing completed bytes. cancel initiates withdrawal but proves no drain. drain SUCCESS detaches every hardware/IRQ/cache/DMA/descriptor/data source; BUSY retains ownership, other errors quarantine it. No callback retains the request itself. Command/cache/DMA writers outside these callbacks are forbidden while the owner exists. Physical adapters own cache-line domains, XIP execution exclusion and hardware-specific drain proof.

Public Members

void *context

size_t context_size

nx_mapped_storage_geometry_t geometry

nx_result_t (*map)(void *context)

nx_result_t (*unmap)(void *context)

nx_result_t (*start)(void *context, nx_mapped_storage_operation_t operation, size_t offset, const void *data, size_t length)

nx_result_t (*poll)(void *context, size_t *completed)

nx_result_t (*cancel)(void *context)

nx_result_t (*drain)(void *context)

struct nx_mapped_storage_slot_t

#include <mapped_storage_owner.h>

Exact caller-owned map capacity; fields belong to the owner.

Public Members

uint64_t epoch

size_t next

const void *data

size_t length

bool live

struct nx_mapped_storage_owner_t

#include <mapped_storage_owner.h>

Caller-owned state, published only after successful initialization.

Note

All methods and controls use one serialized task executor. Consumers may use their maps elsewhere, then join before release. No implicit IRQ guard or cross-task synchronization is supplied. Keep state, slots, backend context, clock and face alive through stop and control/consumer join.

Public Members

nx_mapped_storage_backend_t backend

nx_clock_t clock

nx_mapped_storage_slot_t *slots

size_t capacity

size_t free_head

size_t loans

nx_mapped_storage_request_t *active

uint64_t writer_epoch

size_t completed

nx_result_t terminal

bool draining

bool accepting

native_mapped_storage.h

Caller-owned coherent Native NOR model with bounded steps.

Author

Nexus Team

Functions

nx_result_t nx_native_mapped_storage_init(nx_native_mapped_storage_t *model, uint8_t *bytes, size_t size, size_t program_unit, size_t erase_unit, size_t quantum, nx_mapped_storage_backend_t *backend)

Construct an unused Native backend without modifying backing bytes.

Returns:

SUCCESS or INVALID. Only CPU_READ is supported; XIP and DMA tags reject. Native coherent memory needs no cache maintenance. The portable owner still excludes mappings from every modeled mutation and drain.

struct nx_native_mapped_storage_t

#include <native_mapped_storage.h>

Independent Native backend state; never a physical Flash substitute.

Note

The model preserves supplied bytes, programs only 1-to-0, and erases to 0xff. One service changes at most quantum bytes. No implicit file, heap, thread, DMA, executable aperture or durability claim exists. fault_after bounds mutated bytes; SIZE_MAX disables the fault. hold_drain models live retained sources and drain_error models failure to prove source withdrawal.

Public Members

uint8_t *bytes

size_t size

size_t quantum

const uint8_t *input

size_t offset

size_t length

size_t completed

size_t fault_after

nx_mapped_storage_operation_t operation

bool active

bool cancelled

bool mapped

bool hold_drain

bool drain_error

amp_ipc.h

Bounded epoch-safe unidirectional shared-memory loans.

Author

Nexus Team

Version

1.0.0

Date

2026-10-20

Copyright

Copyright (c) 2026 Nexus Team

Defines

NX_AMP_IPC_UNIT

Explicit port-isolation unit; supported cache granules divide 64.

Typedefs

typedef struct nx_amp_ipc nx_amp_ipc_t

Enums

enum nx_amp_role_t

Values:

enumerator NX_AMP_SENDER

enumerator NX_AMP_RECEIVER

Functions

nx_result_t nx_amp_ipc_send(nx_amp_ipc_t *ipc, uint32_t offset, uint32_t bytes, nx_amp_ticket_t *ticket)

Publish one complete-cache-line payload span without copying.

Note

Serialized owner Thread only, same rule for every API below. No waits, allocation, scheduler, ISR or implicit worker. Outputs must not overlap any live instance/lane storage. Producer must finish DMA/other writers before this call.

Returns:

SUCCESS transfers a read-only borrow until exact ACK poll or successful reset_join. Rejection retains nothing and does not publish. EXHAUSTED means no reusable slot identity.

nx_result_t nx_amp_ipc_poll(nx_amp_ticket_t ticket)

Acquire-observe an exact ACK; BUSY/IO/STATE retain the sender borrow.

nx_result_t nx_amp_ipc_receive(nx_amp_ipc_t *ipc, nx_amp_view_t *view)

Acquire one offer after descriptor/payload invalidation succeeds.

nx_result_t nx_amp_ipc_finish(nx_amp_ticket_t ticket)

Join the caller view, then publish its exact ACK.

Note

Valid ticket invocation permanently joins local readers. IO or STATE retains endpoint/slot storage; retry finish or use reset_join after closing. Stale tickets change nothing.

nx_result_t nx_amp_ipc_close(nx_amp_ipc_t *ipc, nx_amp_close_t *control)

Close admission; outstanding send/receive loans remain retained.

nx_result_t nx_amp_ipc_join(nx_amp_close_t control)

Join a closed endpoint after all exact ACKs/local returns.

Note

BUSY, IO or STATE retain the unique owner. Success performs its final access and unclaims the role. Storage cannot be reconstructed: boot/sequence identities never reset here.

nx_result_t nx_amp_ipc_reset_join(nx_amp_close_t control)

Join after an explicit old-peer stop proof.

Note

Closed endpoint required; receiver views must have been consumed by finish first. Failed proof retains ALL sender loans and ownership. Success retires this endpoint; any replacement uses a strictly newer nonzero boot epoch from the external boot owner, never rollover/reuse.

struct nx_amp_word_t

#include <amp_ipc.h>

One writer’s isolated publication word; accesses use the port only.

Public Members

uint32_t value

uint32_t reserved[15]

struct nx_amp_record_t

#include <amp_ipc.h>

Shared descriptor; offsets refer to the configured payload window.

Public Members

uint32_t sender_epoch

uint32_t receiver_epoch

uint32_t sequence

uint32_t offset

uint32_t length

uint32_t reserved[11]

struct nx_amp_wire_slot_t

#include <amp_ipc.h>

Caller-owned shared slot with disjoint writer cache lines.

Note

Sender alone writes offer/published; receiver alone writes receipt/acknowledged. All four units must be reachable by both CPUs. Cold initialization precedes either endpoint.

Public Members

nx_amp_record_t offer

nx_amp_word_t published

nx_amp_record_t receipt

nx_amp_word_t acknowledged

struct nx_amp_port_ops_t

#include <amp_ipc.h>

Hardware/ownership boundary supplied by the integration.

Note

Every callback is synchronous, bounded and non-reentrant. claim grants the unique role owner of this exact lane and atomically rejects a reused/non-increasing local boot epoch, even after ordinary join. Its authoritative hardware boot owner preserves this history across CPU resets; exhaustion fails closed. Rejection has no effects. unclaim follows final join only and never erases boot identity history. clean/invalidate cover exact complete isolated cache lines, finish their architectural barriers, and may fail. A failed clean MUST NOT publish a control word. acquire/release are infallible atomic 32-bit coherent control operations: the port owns any control-cache maintenance. They must order descriptor/payload access across both CPUs and bus fabric. stopped proves the named old peer CPU, DMA, IRQ and all observers can never access the lane or payload again. The context binds the exact physical lane and peer execution epoch covered by stopped. An epoch observation, cancel, deadline or elapsed timeout never supplies this proof. No existing single-core SoC supplies it.

Public Members

nx_result_t (*claim)(void *context, const void *owner, const nx_amp_wire_slot_t *lane, nx_amp_role_t role, uint32_t local_epoch)

void (*unclaim)(void *context, const void *owner)

nx_result_t (*clean)(void *context, const void *address, size_t bytes)

nx_result_t (*invalidate)(void *context, const void *address, size_t bytes)

uint32_t (*acquire)(void *context, const uint32_t *word)

void (*release)(void *context, uint32_t *word, uint32_t value)

nx_result_t (*stopped)(void *context, uint32_t old_peer_epoch)

struct nx_amp_ticket_t

#include <amp_ipc.h>

Instance/boot/slot identity; endpoint outlives every ticket copy.

Public Members

nx_amp_ipc_t *owner

uint32_t local_epoch

uint32_t peer_epoch

uint32_t slot

uint32_t sequence

struct nx_amp_view_t

#include <amp_ipc.h>

Receiver’s borrowed read-only shared span.

Note

Caller must join every local reader before finish. A valid finish invocation consumes the caller view even when link acknowledgement fails; endpoint storage remains retained.

Public Members

nx_amp_ticket_t ticket

const void *data

size_t bytes

struct nx_amp_close_t

#include <amp_ipc.h>

Stable close identity; endpoint lives longer than all control copies.

Public Members

nx_amp_ipc_t *owner

uint32_t local_epoch

uint32_t peer_epoch

amp_ipc_storage.h

Caller-owned endpoint configuration and retained loan state.

Author

Nexus Team

Version

1.0.0

Date

2026-10-20

Copyright

Copyright (c) 2026 Nexus Team

Functions

nx_result_t nx_amp_ipc_construct(nx_amp_ipc_t *ipc, const nx_amp_config_t *config)

Claim and bind unused zero-initialized endpoint storage.

Note

Serialized privileged owner Thread, before publication. Validates disjoint spans and exact boot epochs before claim. Rejected construction has no references or shared effects. The port must independently enforce unique hardware/role ownership; this component contains no global registry.

struct nx_amp_local_slot_t

#include <amp_ipc_storage.h>

Zero-initialized local state; no sharing with another endpoint.

Public Members

uint32_t sequence

uint32_t offset

uint32_t length

bool active

bool returned

struct nx_amp_config_t

#include <amp_ipc_storage.h>

One unidirectional lane and exact caller-owned storage.

Note

Both boot words are externally published, monotonic nonzero epochs. Never republish an old boot identity, including after a whole-device reset. The boot owner must fail closed on exhaustion. Initial shared records/words are zeroed or retained from older epochs, never edited while live. Wire and boot words occupy separate complete 64-byte units. All shared spans align to granule (power of two, 1..64). Payload size is a positive multiple of granule. Configuration, callbacks and all supplied storage outlive final join.

Public Members

const nx_amp_port_ops_t *ops

void *context

nx_amp_wire_slot_t *wire

nx_amp_local_slot_t *slots

uint32_t capacity

void *payload

uint32_t payload_bytes

nx_amp_word_t *local_boot

nx_amp_word_t *peer_boot

uint32_t local_epoch

uint32_t peer_epoch

uint32_t granule

nx_amp_role_t role

struct nx_amp_ipc

#include <amp_ipc_storage.h>

Public Members

nx_amp_config_t config

bool initialized

bool closed

bool faulted

bool joined

stm32f407_handoff.h

Exact F407 Flash-image transfer after explicit owner drain.

Author

Nexus Team

Functions

nx_result_t nx_stm32f407_handoff_initialize(size_t consumer_capacity)

Construct the single static F407 handoff admission domain.

Note

Serialized privileged Thread, once before any consumer. No heap, hardware writes, discovery or implicit startup. The caller enrolls every platform/product execution, IRQ, DMA, observer and memory owner that can outlive entry. Release a lease only after its actual join/drain.

Parameters:

• consumer_capacity – [in] Positive bound on enrolled live tokens.

Returns:

SUCCESS, INVALID, CONTEXT or STATE; never resets an epoch.

nx_clock_domain_t *nx_stm32f407_handoff_domain(void)

Return the existing single static admission domain.

Note

Pure lookup; does not initialize, acquire or touch hardware.

Returns:

Stable object identity, including before initialization.

nx_result_t nx_stm32f407_handoff(nx_clock_barrier_t owners, uint32_t vector_address)

Validate stopped F407 state and tail-transfer to Flash.

Note

Selected STM32F407VET6/ZGT6 baremetal images only. Caller is privileged Thread on MSP, PRIMASK=1, other masks clear. No scheduler may have started. Stop the actual Platform, join all users and keep admission closed. An unrelated empty domain cannot authorize transfer. Rejects active FP/lazy preservation, partial CP10/11 permissions, MPU, ART, SysTick, enabled/pending/active IRQs, non-HSI16/reset buses, peripheral/DMA gates, busy Flash and retained System effects. Ordinary inactive CP10/11 permissions from SystemInit are supported. Main SRAM is preserved; MSP is 8-aligned in (0x20000000,0x20020000]. All 98 vectors fit exact observed and generated Flash geometry. Reset PC is Thumb with its first halfword in Flash. Success sets VTOR, disables CP10/11, sets CONTROL=0, PSP=0 and MSP, then branches to PC with PRIMASK=1. This is a masked handoff entry. No RAM copy/clear, image authentication/selection, device drain, clock change or physical qualification occurs. Target owns RAM startup and resets controllers before enabling gates. No old deadline survives transfer. Exclude NMI/HardFault, debugger, DMA and other bus masters. Enrollment is caller policy; Platform and product owners are never enrolled automatically. Rejection preserves masks and performs no writable MMIO. Reading SysTick CTRL consumes COUNTFLAG even if rejected.

Parameters:

• owners – [in] Closed, drained barrier from this exact domain.

• vector_address – [in] 512-aligned physical Flash vector address.

Returns:

Error before transfer; success never returns.

frame_dma2d.h

Explicit optional H743 RGB565 copy and fixed PFC owner.

Author

Nexus Team

Defines

NX_H743_FRAME_DMA2D_STORAGE_BYTES

Exact opaque storage reservation for one optional owner.

Note

Zero-initialize once; do not copy or mutate. This is one object’s ABI storage, not a pool or allocator. Keep it, face and all accepted requests live until successful stop.

Typedefs

typedef enum nx_frame_blit_format nx_frame_blit_format_t

Exact source-to-RGB565 operations; unknown values are unsupported.

Enums

enum nx_frame_blit_format

Exact source-to-RGB565 operations; unknown values are unsupported.

Values:

enumerator NX_FRAME_BLIT_RGB565

RGB565 source and output; zero preserves the copy operation.

enumerator NX_FRAME_BLIT_ARGB8888_TO_RGB565

ARGB8888 to RGB565; input bytes B,G,R,A on this little-endian MCU.

Note

Alpha is discarded; no blending, channel/byte swap or CLUT load.

enum nx_h743_frame_resource_t

Explicit exclusive physical resource; no runtime resource registry.

Values:

enumerator NX_H743_FRAME_DMA2D_CONTROLLER

Functions

nx_result_t nx_h743_frame_dma2d_initialize(nx_h743_frame_dma2d_storage_t *storage, const nx_frame_blitter_t *face, const nx_h743_frame_dma2d_config_t *config)

Acquire cold DMA2D and its dedicated RCC gate/reset bit.

Note

Privileged unmasked task, one serialized executor. Caller explicitly excludes every other DMA2D owner, including HAL, IRQ handlers and resource selections outside this component. Never change Cache/RCC/reset/MPU or clock domain before stop. All payloads must be wholly in AXI SRAM [0x24000000, 0x24080000); source/destination overlap is rejected. Only RGB565 M2M or fixed ARGB8888-to-RGB565 PFC is supported. Offsets count each side’s pixels (LOM=0), not bytes. CLUT/blending/other formats/IRQ are unsupported. No pins, Board route, scheduler, queue or worker is created. Initialization IO errors retain cleanup ownership; call stop. A successful stop detaches every source then withdraws only its RCC gate. Repeated stop performs no hardware accesses.

Parameters:

• storage – [inout] Fresh zero storage exclusively owned by caller.

• face – [in] Stable readonly {&nx_h743_frame_dma2d_ops, storage}.

• config – [in] Exact resource plus positive abort observation bound.

Returns:

SUCCESS, INVALID, BUSY for foreign gate/reset/IRQ ownership, UNSUPPORTED for non-V/cache-on, CONTEXT or IO.

Variables

const nx_frame_blitter_ops_t nx_h743_frame_dma2d_ops

struct nx_frame_blit_request_t

#include <frame_dma2d.h>

One caller-owned request; rectangle coordinates are bytes.

Note

Initialize/prepare base using the ordinary request helpers. ACCEPTED borrows this object, the exact source loan control and destination span until acquire-observed SETTLED. Source loan ownership transfers to this owner on acceptance; it is released only after final DMA access. Rejection leaves the original loan with its caller. Do not separately release, mutate or reuse accepted controls, source or destination. x/width_bytes are source bytes, not output bytes or pixels. Source address/x/width/stride align to 2 for RGB565 or 4 for ARGB8888. Destination is RGB565, aligned to 2 bytes. Destination row bytes are width_bytes/source_pixel_bytes*2; destination_stride/capacity are bytes. LOM=0 pixel gaps are at most 0x3fff on each side; width at most 0x3fff pixels, height at most 0xffff rows. Success reports output bytes, excluding stride padding, through nx_request_result. Destination cannot overlap a full-capacity source-pool slot. Every control is disjoint from every slot’s full capacity. The selected source slot is immutable through final access. Task-only admission checks known pool extents in O(n).

Public Members

nx_request_t base

nx_frame_dma_loan_t *source

size_t plane

size_t x

size_t y

size_t width_bytes

size_t rows

uint8_t *destination

size_t destination_stride

size_t destination_capacity

nx_frame_blit_format_t format

struct nx_frame_blitter_ops_t

#include <frame_dma2d.h>

One-executor task-only operations; each service call is bounded.

Note

Submit SUCCESS means ACCEPTED, including a later setup/readback error. Accepted failures retain every borrow until service proves final drain. The first observed failure is retained across cancel/guard restoration.

Public Members

nx_result_t (*submit)(void *context, nx_frame_blit_request_t *request, nx_time_us_t now)

nx_result_t (*service)(void *context, nx_time_us_t now)

nx_result_t (*cancel)(void *context, nx_frame_blit_request_t *request)

nx_result_t (*stop)(void *context)

struct nx_frame_blitter_t

#include <frame_dma2d.h>

Immutable face; state is separate caller-owned private storage.

Public Members

const nx_frame_blitter_ops_t *ops

void *context

struct nx_h743_frame_dma2d_config_t

#include <frame_dma2d.h>

Cold configuration for exact H743 V with D-Cache disabled.

Note

abort_observations bounds failed service observations before quarantine. It is a software progress budget, not a measured bus/DMA timing bound. The same executor continues service after recoverable quarantine; actual drain can settle it. Observed active RCC gate loss or reset assertion instead permanently retains all borrows. Restoring registers cannot prove that lost transfer history; no API reclaims it. An unobserved reset pulse is undetectable, so exclusive RCC ownership remains mandatory. System recovery is external.

Public Members

nx_h743_frame_resource_t resource

uint32_t abort_observations

union nx_h743_frame_dma2d_storage_t

#include <frame_dma2d.h>

Public Members

uint64_t alignment

uintptr_t pointer_alignment

unsigned char private_bytes[NX_H743_FRAME_DMA2D_STORAGE_BYTES]

stm32u575_retained_time.h

Independent monotonic domain from a retained U575 calendar.

Author

Nexus Team

Defines

NX_U575_RETAINED_TIME_STORAGE_BYTES

Enums

enum nx_u575_retained_time_resource_t

Exclusive exact RTC source; no second owner may configure it.

Values:

enumerator NX_U575_RETAINED_TIME_RTC

Functions

nx_result_t nx_stm32u575_retained_time_initialize(nx_stm32u575_retained_time_storage_t *storage, const nx_stm32u575_retained_time_config_t *config, nx_clock_t *clock)

Open a separate elapsed clock without reading or changing Core TIM2.

Note

Exact U575 TZEN0, privileged unmasked Thread, baremetal integration. External boot owns a valid raw calendar/LSE32768/RTCEN/RTCAPBEN, crystal mode LSEBYP=0 and conservative drive 10/11. ES0499 Rev12 2.2.3/16 affect revision X; this profile does not qualify revision. External boot/Board owners exclude PC13 transitions on the LQFP reference per 2.2.1; reads cannot prove electrical silence.

Note

The selected MSIS4/equal-bus profile is checked before every tuple pair, with no concurrent clock-profile writer. This conservative profile is not a general RTC-write frequency rule. Require PRER127/255, BCD24h BYPSHAD, no shift/calibration/alarms.

Note

Both standalone and delegated construction require quiet RTC IRQ, WUTE/WUTIE clear and no RTC flags. The explicit wake_owner may operate only its WUT/IRQ fields after successful construction. Calendar provenance, including intentional YY00, cannot be inferred from INITS. DBP/WPR need not be unlocked; no hardware writes occur.

Note

This face has a distinct domain from nx_time_now_us(). Old Core deadlines are never translated. Stop/reopen invalidates old faces’ numerical deadlines after all consumers and observers have joined.

Parameters:

• storage – [inout] Fresh zero or fully stopped, externally joined owner.

• config – [in] Separate immutable configuration, copied during this call.

• clock – [out] Separate writable face, copied only on success.

Returns:

SUCCESS, INVALID, STATE, BUSY, CONTEXT, UNSUPPORTED or EXHAUSTED; rejection leaves owner and output unchanged, with no hardware writes.

nx_result_t nx_stm32u575_retained_time_initialize_alarm_a_copy(nx_stm32u575_retained_time_storage_t *storage, const nx_stm32u575_retained_time_config_t *config, nx_clock_t *clock)

Open the fixed AlarmA-copy delegate for the same concrete Stop2 owner.

Note

All ordinary initialization preconditions remain required. Unlike the WUT-only initializer, this explicitly delegates fixed AlarmA compare registers, ALRAE and ALRAF/CALRAF to the same serialized wake owner. ALRAIE and automatic flag clearing stay forbidden. The fixed profile masks all calendar fields and compares no subseconds, producing its first event on a seconds increment. Both alarm registers start zero. The delegate preserves the calendar/source and owns complete producer withdrawal before any compound copy settlement. No AlarmA factory, arbitrary alarm scheduler or second RTC writer is admitted.

Parameters:

• storage – [inout] Same fresh or fully stopped and joined storage.

• config – [in] Same immutable configuration with non-NULL wake_owner.

• clock – [out] Separate writable face, unchanged on every rejection.

Returns:

Same initialization results; no hardware writes occur.

nx_result_t nx_stm32u575_retained_time_sample(nx_stm32u575_retained_time_storage_t *storage, nx_stm32u575_retained_time_snapshot_t *snapshot)

Observe a bounded coherent tuple and extend the independent domain.

Note

Thread may hold PRIMASK; BASEPRI/FAULTMASK and Handler mode are excluded. BUSY means no coherent tuple after eight bounded retries, and changes neither owner nor output. A source/configuration change, backward/out-of-window calendar or time exhaustion permanently taints this live epoch. Later samples return STATE; no stale value is valid.

Parameters:

• storage – [inout] Same serialized privileged Thread owner.

• snapshot – [out] Separate aligned writable output, unchanged on failure.

Returns:

SUCCESS, INVALID, STATE, BUSY, CONTEXT or EXHAUSTED.

nx_result_t nx_stm32u575_retained_time_validate_wake(nx_stm32u575_retained_time_storage_t *storage, const void *wake_owner, uint64_t generation)

Check one explicit WUT identity against this live clock generation.

Note

Same serialized privileged Thread, PRIMASK0/1 allowed. The WUT owner obtains generation through sample and checks it before and after each transition. Reopen invalidates old bindings; no second owner is inferred.

Returns:

SUCCESS, INVALID, STATE or CONTEXT; no output or hardware effects.

nx_result_t nx_stm32u575_retained_time_validate_alarm_a_copy(nx_stm32u575_retained_time_storage_t *storage, const void *wake_owner, uint64_t generation)

Validate the exact opt-in AlarmA-copy owner and live clock generation.

Note

Same Thread/PRIMASK boundary as validate_wake. An ordinary WUT-only clock cannot authorize AlarmA. Wrong identity/generation/mode rejects without taint; observed source or fixed-profile drift taints the epoch.

Parameters:

• storage – [inout] Same live serialized clock owner.

• wake_owner – [in] Exact stable identity from opt-in initialization.

• generation – [in] Nonzero generation obtained from a successful sample.

Returns:

SUCCESS, INVALID, STATE or CONTEXT; no hardware writes occur.

nx_time_us_t nx_stm32u575_retained_time_now(void *context)

Clock-face read; failure cannot return a stale or invalid timestamp.

Note

On any failed sample, taint the epoch, retain the interrupt mask, call nx_fault_observe(NX_FAULT_PLATFORM, reason, …) and park if the observer returns. Products may supply separately reviewed nonreturning recovery. No loan or observer is released by fault observation.

Parameters:

• context – [inout] Exact live storage from successful initialization.

Returns:

A new valid sample in the same independent monotonic domain.

nx_result_t nx_stm32u575_retained_time_stop(nx_stm32u575_retained_time_storage_t *storage)

Close clock admission after every external face/deadline user joins.

Note

Does not reset generations or alter the source. An explicit reopen starts a new zero-based elapsed domain, including after a tainted one. No scheduler, wake IRQ, WFI, Core restoration, Stop2 or VBAT retention guarantee is established by this read-only source component.

Returns:

SUCCESS, INVALID, CONTEXT or STATE; clean repeated stop is idempotent.

union nx_stm32u575_retained_time_storage_t

#include <stm32u575_retained_time.h>

One zero-initialized caller owner, not a pool or allocation service.

Note

Do not copy or mutate. Keep this storage alive through every copied clock face, deadline consumer and observer. Memory retention for any future power mode is an assembly obligation, never implied by a RAM address. This read-only clock does not require SRAM4 or enter Stop2.

Public Members

uint64_t alignment

uintptr_t pointer_alignment

unsigned char private_bytes[NX_U575_RETAINED_TIME_STORAGE_BYTES]

struct nx_stm32u575_retained_time_config_t

#include <stm32u575_retained_time.h>

Bounded observation gap, declared by the serialized lifecycle owner.

Note

Observe at least once per max_gap_seconds, in 1..86400 seconds. Missed complete 100-year periods and small external clock settings cannot be detected from calendar snapshots. Exclude every calendar writer and other RTC configuration owner, including the polling AlarmA factory selection. The sole explicit WUT delegate is described below. The complete elapsed interval, including wake latency or recovery, must fit this gap; the nominal WUT duration alone is not a bound.

Public Members

nx_u575_retained_time_resource_t resource

uint32_t max_gap_seconds

const void *wake_owner

NULL for RTC-only; otherwise stable identity of one WUT owner.

Note

Delegates only WUCKSEL/WUTE/WUTIE, WUTR, WUTF/SCR.CWUTF and RTC IRQ ownership; ICSR.WUTWF may change with that bounded operation. That same serialized owner preserves every calendar/source field. Identity is compared without dereference; it is not authorization.

struct nx_stm32u575_retained_time_snapshot_t

#include <stm32u575_retained_time.h>

A successful sample copied together in this owner’s boot lifetime.

Note

Microseconds are floor(ticks*1000000/256); resolution is 3906.25us, with exact carried fractional quarters. Generation changes only on explicit successful initialize/reopen, never natural 99->00 rollover.

Public Members

const void *identity

uint64_t generation

nx_time_us_t now

uint64_t ticks

stm32u575_lpdma_copy.h

Exact U575 SRAM4 finite autonomous copy receiver.

Author

Nexus Team

Defines

NX_U575_LPDMA_COPY_STORAGE_BYTES

Functions

nx_result_t nx_stm32u575_lpdma_copy_initialize(nx_stm32u575_lpdma_copy_storage_t *storage, const nx_stm32u575_lpdma_copy_config_t *config, nx_stm32u575_lpdma_copy_t *copy)

Construct one serialized privileged Thread owner without MMIO writes.

Note

Exact STM32U575ZIT6Q TZEN0/MSIS4/MSIK4/equal buses/Range4 and selected SRAM4 only. LPDMA1EN/SRAM4EN and power/retention belong to selected startup; every channel and vector must initially be quiet. The run-gate owner keeps both gates and exclusive hardware configuration stable through stop and joins; no other LPDMA channel may start. This component owns only fixed sleep/autonomous bits and preserves unrelated RTC bits. SRAM4EN and power/retention preconditions belong to startup and the combined sleep owner. This component never repairs lost RAM by changing SRAM4PD/PDS and never disables the caller’s SRAM4EN.

Parameters:

• storage – [inout] Fresh zero or clean stopped and externally joined.

• config – [in] Separate immutable clock/owner binding.

• copy – [out] Separate writable immutable face, unchanged on failure.

nx_result_t nx_stm32u575_lpdma_copy_request_prepare(nx_stm32u575_lpdma_copy_request_t *request, const nx_stm32u575_retained_time_snapshot_t *domain, const void *source, void *destination, size_t length, nx_stm32u575_lpdma_copy_workspace_t *workspace, nx_time_us_t deadline)

Prepare copied metadata in an unborrowed request, without MMIO.

Note

Rejecting a span, alias, wrap or state leaves every request byte unchanged. Preparation does not borrow or write any buffer/workspace. Old Core TIM2 deadlines are never translated into this domain.

Parameters:

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

• domain – [in] Separate successful retained clock sample.

• source – [in] Borrowed immutable bytes wholly inside nonsecure SRAM4.

• destination – [out] Separate borrowed writable SRAM4 span.

• length – [in] At least two bytes; both full extents must fit SRAM4.

• workspace – [inout] Separate aligned 24-byte SRAM4 LLI workspace.

• deadline – [in] Absolute microseconds in that domain, or NEVER.

nx_result_t nx_stm32u575_lpdma_copy_cancel(const nx_stm32u575_lpdma_copy_t *copy, nx_stm32u575_lpdma_copy_request_t *request)

Latch cancellation of the exact active identity without release.

Note

Late cancellation after observed channel completion rejects STATE. Cancellation before unobserved completion fixes the first failure. DMA drain alone cannot release an AlarmA/WUT/clock restoration loan.

Parameters:

• copy – [in] Immutable face of the initialized physical receiver.

• request – [inout] Exact active request, retained through SETTLED.

nx_result_t nx_stm32u575_lpdma_copy_service(const nx_stm32u575_lpdma_copy_t *copy, uint32_t poll_limit)

Observe and perform bounded DMA withdrawal; never publish SETTLED.

Note

Positive finite per-phase observation budget, not a time estimate. BUSY retains request, both buffers and workspace, even after DMA idle. Only the concrete Stop2 owner can release after the entire RTC/IRQ/ DMA/clock/gate chain is restored. Unknown profile performs no DMA MMIO. An externally asserted LPDMA reset observed while borrowed leaves an uncertain loan permanently quarantined; reset-default IDLE cannot prove earlier master accesses joined. No software force release exists. Preserve incoming masks; while borrowed the concrete Stop2 boundary requires PRIMASK1, BASEPRI/FAULTMASK0 until complete recovery.

Parameters:

• copy – [in] Immutable face of the initialized physical receiver.

• poll_limit – [in] Positive observation budget for each drain phase.

nx_result_t nx_stm32u575_lpdma_copy_stop(const nx_stm32u575_lpdma_copy_t *copy, uint32_t poll_limit)

Close admission, retaining all live loans until compound recovery.

Note

Keep every related object alive and RUN admission closed on BUSY. Repeated clean stop is safe after external publishers have joined. No Stop2 residency, LPBAM peripheral, physical copy or HIL result is implied by the public type or successful software execution.

Parameters:

• copy – [in] Immutable face of the initialized physical receiver.

• poll_limit – [in] Positive observation budget for each drain phase.

Variables

const nx_stm32u575_lpdma_copy_ops_t nx_stm32u575_lpdma_copy_ops

Exact physical implementation identity, not arbitrary callbacks.

union nx_stm32u575_lpdma_copy_storage_t

#include <stm32u575_lpdma_copy.h>

Zero-initialized caller owner; never copy, reset or reconstruct live.

Note

Keep this storage, every copied face and bound clock alive until stop succeeds and all external observers have joined. One exact ch0 owner exists; there is no allocation, queue, worker or factory lookup. One privileged Thread serializes every lifecycle/control operation. No ISR, concurrent producer or unjoined delayed cancellation command may use request pointers across prepare/reuse.

Public Members

uint64_t alignment

uintptr_t pointer_alignment

unsigned char private_bytes[NX_U575_LPDMA_COPY_STORAGE_BYTES]

struct nx_stm32u575_lpdma_copy_workspace_t

#include <stm32u575_lpdma_copy.h>

One generated full next LLI; raw caller instructions are not used.

Note

Entire 24-byte extent must be four-byte aligned in selected SRAM4. Provider overwrites all words only after admission. Keep it immutable and disjoint from both buffers and all request/control storage while borrowed. A NOINIT section never establishes descriptor construction.

Public Members

uint32_t private_words[6]

struct nx_stm32u575_lpdma_copy_config_t

#include <stm32u575_lpdma_copy.h>

Explicit same-owner clock binding; copied only on initialization.

Note

clock is the live opt-in AlarmA-copy retained clock. wake_owner is the stable concrete Stop2 owner identity. Identity equality is trusted assembly binding, never hardware authentication. No RTC writer exists in this component.

Public Members

nx_stm32u575_retained_time_storage_t *clock

const void *wake_owner

struct nx_stm32u575_lpdma_copy_request_t

#include <stm32u575_lpdma_copy.h>

One finite two-block copy in the independent retained time domain.

Note

Initialize base before prepare. Prepared metadata is caller immutable from ACCEPTED until acquire-observed SETTLED and external joins. source/destination/whole workspace must be disjoint exact nonsecure SRAM4 spans, not CPU-visible SRAM1 or secure aliases. length is at least two bytes; byte-width incremented transfers preserve exact byte count.

Public Members

nx_request_t base

const void *identity

const void *source

void *destination

size_t length

nx_stm32u575_lpdma_copy_workspace_t *workspace

const void *clock_identity

uint64_t clock_generation

struct nx_stm32u575_lpdma_copy_ops_t

#include <stm32u575_lpdma_copy.h>

Shared readonly methods; public service never releases the chain.

Public Members

nx_result_t (*cancel)(void *context, nx_stm32u575_lpdma_copy_request_t *request)

nx_result_t (*service)(void *context, uint32_t poll_limit)

nx_result_t (*stop)(void *context, uint32_t poll_limit)

struct nx_stm32u575_lpdma_copy_t

#include <stm32u575_lpdma_copy.h>

Immutable typed face; copied faces still name the exact live owner.

Public Members

const nx_stm32u575_lpdma_copy_ops_t *ops

void *context

stm32u575_lpdma_lptim1.h

Exact U575 finite LPTIM1 autonomous register update.

Author

Nexus Team

Version

1.0.0

Date

2026-10-20

Copyright

Copyright (c) 2026 Nexus Team

Defines

NX_U575_LPDMA_LPTIM1_STORAGE_BYTES

Functions

nx_result_t nx_stm32u575_lpdma_lptim1_initialize(nx_stm32u575_lpdma_lptim1_storage_t *storage, const nx_stm32u575_lpdma_lptim1_config_t *config, nx_stm32u575_lpdma_lptim1_t *receiver)

Bind one pure owner; no MMIO writes, allocation or worker.

Note

Exact STM32U575ZIT6Q TZEN0, MSIS4/MSIK4/equal buses/Range4, caches off. Selected SRAM4/LPDMA1 startup and retained LSE RTC access remain live. LPDMA0 and the entire LPTIM1 controller are exclusive; no other channel, timer writer, IRQ user or external reset exists. Config/face/control storage must be separate. Rejection retains no new reference.

nx_result_t nx_stm32u575_lpdma_lptim1_start(const nx_stm32u575_lpdma_lptim1_t *receiver, uint32_t poll_limit)

Explicitly prepare cold LPTIM1 access gates and LSE kernel.

Note

Unmasked privileged Thread, positive per-phase poll budget. Owns only LPTIM1EN, LPTIM1SEL and added LSESYSEN, preserving RTC/LSE provenance. LPTIM1 must be reset/cold and initially unclocked with reset mux. A failed preparation can retain effects; keep owner live and call stop until it succeeds. It never starts the timer or borrows a request.

nx_result_t nx_stm32u575_lpdma_lptim1_request_prepare(nx_stm32u575_lpdma_lptim1_request_t *request, const nx_stm32u575_retained_time_snapshot_t *domain, const nx_stm32u575_lptim1_tuple_t *tuple, nx_stm32u575_lpdma_lptim1_workspace_t *workspace, nx_time_us_t deadline)

Prepare one SRAM4 tuple without borrowing or writing data/LLIs.

Note

Tuple contents remain unchanged from prepare through settlement. Invalid/aliased/wrapping spans leave every request byte unchanged. Deadline is absolute retained microseconds or NEVER; no TIM2 conversion.

nx_result_t nx_stm32u575_lpdma_lptim1_cancel(const nx_stm32u575_lpdma_lptim1_t *receiver, nx_stm32u575_lpdma_lptim1_request_t *request)

Request withdrawal without revoking any borrowed storage.

Note

Masked privileged MSP Thread through compound recovery. Late cancel after observed DMA completion rejects STATE. First failure persists.

nx_result_t nx_stm32u575_lpdma_lptim1_service(const nx_stm32u575_lpdma_lptim1_t *receiver, uint32_t poll_limit)

Bounded producer/master isolation, never independent settlement.

Note

Producer UEDE withdrawal precedes DMA suspend/reset/idle. All final peripheral/IRQ references and Stop2 restoration precede final release. Unknown clock/access profile permits no peripheral MMIO; external DMA or LPTIM reset during a loan permanently quarantines that loan.

nx_result_t nx_stm32u575_lpdma_lptim1_stop(const nx_stm32u575_lpdma_lptim1_t *receiver, uint32_t poll_limit)

Close admission and restore owned start effects after compound join.

Note

Positive per-phase observation budget is not elapsed time. BUSY keeps all effects/storage alive; recover through the concrete Stop2 owner. A fresh final write-OK proof means synchronized register writes, never physical Stop2 residency, output playback, board routing or HIL.

Variables

const nx_stm32u575_lpdma_lptim1_ops_t nx_stm32u575_lpdma_lptim1_ops

struct nx_stm32u575_lptim1_tuple_t

#include <stm32u575_lpdma_lptim1.h>

One caller-owned immutable register tuple, in exact SRAM4.

Note

CCR1 < ARR, RCR=0 and 1023<=ARR<=65535. There is exactly one tuple; repeated updates need a separate write-OK proof and are not admitted. No GPIO route or physical waveform playback is established.

Public Members

uint32_t ccr1

uint32_t rcr

uint32_t arr

struct nx_stm32u575_lpdma_lptim1_workspace_t

#include <stm32u575_lpdma_lptim1.h>

Exactly two generated continuation LLIs; never caller instructions.

Note

Entire aligned 48-byte extent is separate nonsecure SRAM4. The owner writes all words only after ACCEPTED; keep immutable until SETTLED.

Public Members

uint32_t private_words[12]

union nx_stm32u575_lpdma_lptim1_storage_t

#include <stm32u575_lpdma_lptim1.h>

Zero caller storage, never copy/reset/reconstruct a live owner.

Note

One privileged Thread serializes all calls; no ISR/concurrent writer. Keep owner, clock and every face alive through stop and observer joins.

Public Members

uint64_t alignment

uintptr_t pointer_alignment

unsigned char private_bytes[NX_U575_LPDMA_LPTIM1_STORAGE_BYTES]

struct nx_stm32u575_lpdma_lptim1_config_t

#include <stm32u575_lpdma_lptim1.h>

Explicit live retained-clock and same concrete Stop2 binding.

Note

Use the ordinary retained-clock initializer with wake_owner equal to nx_stm32u575_stop2_identity(). No AlarmA-copy opt-in is required.

Public Members

nx_stm32u575_retained_time_storage_t *clock

const void *wake_owner

struct nx_stm32u575_lpdma_lptim1_request_t

#include <stm32u575_lpdma_lptim1.h>

Prepared metadata; all fields are provider-controlled after prepare.

Note

Initialize base first. ACCEPTED borrows request, tuple and workspace until acquire-observed SETTLED and external joins. Cancel/deadline do not revoke a borrow. CPU control storage must be separate from SRAM4 data/LLIs. Never mutate or reprepare while borrowed.

Public Members

nx_request_t base

const void *identity

const nx_stm32u575_lptim1_tuple_t *tuple

void *private_destination

size_t private_length

nx_stm32u575_lpdma_lptim1_workspace_t *workspace

const void *clock_identity

uint64_t clock_generation

struct nx_stm32u575_lpdma_lptim1_ops_t

#include <stm32u575_lpdma_lptim1.h>

Shared immutable methods; service never publishes SETTLED.

Public Members

nx_result_t (*cancel)(void*, nx_stm32u575_lpdma_lptim1_request_t*)

nx_result_t (*service)(void*, uint32_t)

nx_result_t (*stop)(void*, uint32_t)

nx_result_t (*start)(void*, uint32_t)

struct nx_stm32u575_lpdma_lptim1_t

#include <stm32u575_lpdma_lptim1.h>

Copied immutable faces retain the exact physical owner identity.

Public Members

const nx_stm32u575_lpdma_lptim1_ops_t *ops

void *context

stm32u575_stop2.h

Exact U575 TZEN0 retained-RTC Stop2 boundary.

Author

Nexus Team

Functions

const void *nx_stm32u575_stop2_identity(void)

Stable trusted assembly identity for retained-time wake_owner.

nx_result_t nx_stm32u575_stop2_initialize(size_t capacity, nx_stm32u575_retained_time_storage_t *clock)

Bind the static owner and construct its RUN domain.

Note

Serialized privileged unmasked Thread, once. Retain clock storage throughout this owner’s lifetime. No hardware writes or heap allocation occur.

Parameters:

• capacity – [in] Positive bound on external consumer leases.

• clock – [inout] Live retained-time owner bound to this identity.

Returns:

SUCCESS, INVALID, CONTEXT, STATE or clock failure.

nx_clock_domain_t *nx_stm32u575_stop2_domain(void)

Pure lookup; all platform/product RUN owners enroll explicitly.

nx_stm32u575_stop2_result_t nx_stm32u575_stop2_enter(nx_clock_barrier_t owners, uint32_t wake_ticks, uint32_t poll_limit)

Arm WUT, cross Stop2, restore and drain with PRIMASK=1.

Note

Exact STM32U575ZIT6Q TZEN0 baremetal only. Privileged MSP Thread, CONTROL=0, PRIMASK=1, BASEPRI=FAULTMASK=0. No scheduler may have started. Close RUN admission, stop Platform/System and join every producer, IRQ, DMA, observer and deadline user. Release leases only after real drain; pass the closed barrier when no consumers remain. Enrollment is never automatic. End Core TIM2 deadlines; TIM2 is not read or restarted. The independent RTC clock stays outside this RUN domain. Requires MSIS4/MSIK4/equal buses, quiet gates, all SRAM retained, caches/debug/MPU/SysTick/other IRQ and EXTI sources off. Reading SysTick CTRL consumes COUNTFLAG on rejection too. Exclusive RTC: bound calendar reader and this WUT writer. Boot supplies valid retained LSE calendar and DBP=1. Only WUT is written; WPR is unlocked then relocked each phase. Exclude NMI/HardFault, debugger, watchdogs, other masters and asynchronous configuration writers externally. Zero gates cannot prove those obligations. Binding is trusted assembly identity, never hardware authentication. WUTR=wake_ticks-1. First WUTF is between WUTR and WUTR+2 ticks. RTC samples resolve 3906.25us; short wakes may show zero elapsed. Retained max_gap_seconds must cover sleep, arm/drain execution and externally bounded wake latency. WFI has no CPU duration bound if hardware wake fails. A missed sample gap taints the independent clock epoch. wait_executed proves WFI ran, never physical residency. All returns preserve masks. Success requires observed WUT, IRQ and added gate withdrawal plus MSIS4/MSIK4/Range4 restore. Failed drain retains ownership. Keep admission closed and related objects alive; call recover before any restart. No failure revokes a loan. Restarting Platform creates a new TIM2 epoch; no old deadline survives that lifecycle. RTOS Tick compensation and LPBAM remain unsupported.

Parameters:

• owners – [in] Closed, drained barrier from this exact domain.

• wake_ticks – [in] 2..65536 RTC/16 ticks, nominal 488.28125us.

• poll_limit – [in] Positive finite per-phase observation budget.

Returns:

Primary/cleanup results, retained effects and RTC samples.

nx_stm32u575_stop2_result_t nx_stm32u575_stop2_recover(nx_clock_barrier_t owners, uint32_t poll_limit)

Retry retained WUT/IRQ/clock drain without another WFI.

Note

Same masked boundary and exact closed barrier. Recovery cannot repair a tainted RTC epoch or authorize old deadlines. Hardware drain can finish with invalid RTC sampling. Join all retained-clock users before its explicit stop/reopen.

struct nx_stm32u575_stop2_result_t

#include <stm32u575_stop2.h>

Bounded transition result; snapshots belong only to the RTC domain.

Public Members

nx_result_t primary

nx_result_t cleanup

uint32_t remaining_effects

bool wait_executed

bool wake_flag

nx_stm32u575_retained_time_snapshot_t before

nx_stm32u575_retained_time_snapshot_t after

stm32u575_stop2_copy.h

Exact same-owner U575 Stop2 finite SRAM4 copy boundary.

Author

Nexus Team

Version

1.0.0

Date

2026-10-20

Copyright

Copyright (c) 2026 Nexus Team

Functions

nx_stm32u575_stop2_copy_result_t nx_stm32u575_stop2_copy_enter(nx_clock_barrier_t owners, const nx_stm32u575_lpdma_copy_t *copy, nx_stm32u575_lpdma_copy_request_t *request, uint32_t escape_ticks, uint32_t poll_limit)

Cross Stop2 with one finite AlarmA-triggered SRAM4 copy.

Note

All masked-MSP-Thread and stopped/joined RUN preconditions of enter remain required. The clock uses the explicit AlarmA-copy initializer and this owner’s wake identity. Selected startup provides nonsecure SRAM4 and prepared LPDMA1 access; unrelated channels and masters are quiet. The receiver validates the actual binding and registers. No caller callback or gate mask authorizes exceptions.

Note

All calendar mask bits are set; ALRMASSR=0, ALRAIE=0 and ALRAFCLR=0. The receiver is ready before ALRAE enables the next whole-second event on trigger14. ALRAF and DMA pending remain intact while the producer is enabled. WUT is an independent escape. The receiver owns its generated second LLI and LPDMA1 channel0 IRQ114 wake vector. wait_executed proves WFI, never physical residency.

Note

Rejection leaves the new request unborrowed. Once accepted, setup failure retains every copy reference until RTC/WUT producer, DMA master/reset, IRQ, gate and clock restoration are independently quiet. Keep both owners, clock, buffers, workspace and RUN barrier live and closed. Preserve PRIMASK=1 through retained recovery. recover retries the same compound chain without WFI. An observed external LPDMA reset permanently quarantines the chain: quiet reset values and deassertion cannot prove the prior master’s final access. Only an externally established system reset ends that responsibility. A tainted clock may settle an error after hardware drain, never a successful fresh elapsed time. No old TIM2 deadline, RTOS compensation, peripheral LPBAM plan or physical copy result is established.

Note

Link only Nexus::U575Stop2Copy for this mode. It owns the same static RUN domain and WUT/recover symbols as Nexus::U575Stop2; linking both alternatives is rejected. WUT-only enter remains available, but rejects every retained copy loan. Keep PRIMASK=1 until complete recovery.

Parameters:

• owners – [in] Exact closed, drained RUN-domain barrier.

• copy – [in] Immutable initialized LPDMA1/channel0 face.

• request – [inout] Prepared READY copy in the bound retained domain.

• escape_ticks – [in] 4096..65536 RTC/16 ticks, nominal 2..32 s.

• poll_limit – [in] Positive observation budget for each phase.

Returns:

Admission, transition, cleanup and retained effects.

struct nx_stm32u575_stop2_copy_result_t

#include <stm32u575_stop2_copy.h>

Separate copy admission and exact Stop2 transition observations.

Note

accepted means the request, buffers and workspace became borrowed, including when later RTC/power setup fails. Read the final copy result and count only through acquire-observed request SETTLED. transition describes the boundary; dma_wake records observed ch0 NVIC pending.

Public Members

bool accepted

bool dma_wake

nx_stm32u575_stop2_result_t transition

stm32u575_stop2_lptim1.h

Same concrete Stop2 owner and finite LPTIM1 LPBAM boundary.

Author

Nexus Team

Version

1.0.0

Date

2026-10-20

Copyright

Copyright (c) 2026 Nexus Team

Functions

nx_stm32u575_stop2_lptim1_result_t nx_stm32u575_stop2_lptim1_enter(nx_clock_barrier_t owners, const nx_stm32u575_lpdma_lptim1_t *receiver, nx_stm32u575_lpdma_lptim1_request_t *request, uint32_t escape_ticks, uint32_t poll_limit)

One finite hardware-requested LPTIM1 tuple across Stop2.

Note

Link only Nexus::U575Stop2Lptim1; WUT/copy alternatives are exclusive. Same static owner, RUN ClockDomain and recovery. Ordinary retained time uses this wake identity; explicitly start the dedicated receiver first. Closed/drained exact RUN barrier, stopped Platform, privileged MSP Thread CONTROL0/PRIMASK1/BASEPRI0/FAULTMASK0 remain required. Keep masks and RUN admission closed through all retained recovery.

Note

LPTIM1 LSE/preload/CC1E, initial ARR1023/RCR0; request13/BREQ1 gates CCR1, two generated software-requested LLIs write RCR and ARR last. No AlarmA trigger. WUT escapes at 4096..65536 RTC/16 ticks. Positive poll_limit bounds observations, not WFI duration or physical response.

Note

UEDE withdrawal/DIEROK precede DMA suspend/reset/idle and reference detach. Fresh write-OK gates success. Owned RCC reset disables LPTIM1 per ES0499. All peripheral/IRQ/gate/clock restoration precedes SETTLED; start access gates stay until joined public stop. Cancel/deadline never revoke storage. Unknown profile permits no peripheral MMIO. External peripheral reset permanently quarantines an active loan until system reset. Recovery never runs WFI. No GPIO/Board route, output playback, physical residency, timing/power or HIL result is implied.

struct nx_stm32u575_stop2_lptim1_result_t

#include <stm32u575_stop2_lptim1.h>

Admission and software sleep observations, not the final result.

Note

accepted borrows request/tuple/workspace even when setup later fails. dma_wake is pending IRQ114; wait_executed proves WFI execution only.

Public Members

bool accepted

bool dma_wake

nx_stm32u575_stop2_result_t transition

user_io_async.h

Bounded copied UART user mediation.

Author

Nexus Team

Version

1.0.0

Date

2026-10-20

Copyright

Copyright (c) 2026 Nexus Team

Typedefs

typedef struct nx_user_io_async nx_user_io_async_t

Enums

enum nx_user_io_async_constants

Values:

enumerator NX_USER_IO_ASYNC_ABI

enumerator NX_USER_IO_ASYNC_SUBMIT

enumerator NX_USER_IO_ASYNC_POLL

enumerator NX_USER_IO_ASYNC_CANCEL

enumerator NX_USER_IO_ASYNC_CONSUME

Functions

nx_result_t nx_user_io_async_dispatch(nx_user_io_async_t *mediation, const nx_user_io_async_message_t *message, const uint8_t *payload, nx_user_io_async_reply_t *reply)

Authenticate and copy one bounded user gateway transaction.

Note

Privileged unmasked Thread, one serialized gateway executor. Authenticate the current principal on every call. The trusted copy port supplies fault containment and mapping stability; range checks alone prove neither. The caller separately drives the existing BusOwner/UARTOwner; this call never services it. CANCEL only requests its drain. CONSUME requires acquire SETTLED and the existing owner’s idle/join barrier, copies the reply first, then wipes bytes/releases the exact cell. Failed reply copy, cancellation or quarantine never releases an accepted cell. No SVC/CMSE entry or NS RTOS is provided.

Parameters:

• mediation – [inout] Trusted privileged binding and exact copied slots.

• message – [in] Transient full readable user header, copied once.

• payload – [in] Transient readable SUBMIT bytes; NULL otherwise.

• reply – [out] Transient disjoint full writable user reply.

Returns:

SUCCESS after reply copy; identity/span/protocol/copy/control errors otherwise. No user address survives any return. A reply-copy error can follow acceptance: POLL the proposed slot/epoch; duplicate SUBMIT cannot replay or replace it.

nx_result_t nx_user_io_async_close(nx_user_io_async_t *mediation)

Close copied admission and cancel this binding’s live work.

Note

Trusted privileged management, not a user gateway action. Same serialized lifecycle executor as dispatch/join, except synchronous identity/copy callbacks may request close. This is not a general concurrent cross-task control API. Close is permanent; it does not close the underlying owner. No worker or provider service runs here. Keep driving the owner and authenticate POLL/CONSUME through normal dispatch. Identity/copy callbacks may request close, never recursively dispatch or reconstruct. All bound storage stays live.

nx_result_t nx_user_io_async_reap(nx_user_io_async_t *mediation)

Privileged retirement after permanently lost user mappings.

Note

Same trusted serialized management as close/join; never an untrusted wire action. The kernel decides when cleanup is authorized. First close/cancel and separately drive the real owner. Every retained exact cell must acquire SETTLED and the owner must be idle. The trusted drained proof then fences future gateway entries and joins all outer observers while retaining the role. Only then are all copied payloads wiped and cells retired without user copyout. Pending, quarantined or unjoined work retains every cell unchanged. Success is idempotent and permanently rejects dispatch. It does not release the role: successful join is still required before reclaiming any bound storage. No forced borrow revocation, process-liveness policy or provider service is supplied.

nx_result_t nx_user_io_async_join(nx_user_io_async_t *mediation)

Join closed/consumed cells, owner and trusted gateway role.

Note

Trusted serialized management. No reinitialization/reopen, hidden provider stop or identity registry is created. A successful join permits a fresh object with a larger claimed session; never reset or reconstruct this live object.

Returns:

SUCCESS only after no gateway/copy, copied cell or owner publisher remains and the trusted role release proves outer gateway observers joined; BUSY/error retains role and storage.

struct nx_user_io_async_message_t

#include <user_io_async.h>

Twelve scalar local C gateway words; no principal, address or callback.

Note

SUBMIT proposes the exact next nonzero 64-bit epoch for an explicit slot within the exact claimed nonzero session and supplies positive length plus an absolute deadline in the existing owner’s clock domain. Other actions use the accepted exact epoch and zero length/deadline words. device must match the immutable trusted binding; reserved=0. Word pairs encode low then high halves, independently of the compiler enum, pointer and uint64_t alignment ABI. These are local C gateway records; an integrating kernel owns byte order and any transport serialization.

Public Members

uint32_t abi

uint32_t action

uint32_t device

uint32_t slot

uint32_t session_low

uint32_t session_high

uint32_t epoch_low

uint32_t epoch_high

uint32_t length

uint32_t deadline_low

uint32_t deadline_high

uint32_t reserved

struct nx_user_io_async_reply_t

#include <user_io_async.h>

Ten initialized scalar words; no privileged pointer.

Note

state is a Core nx_request_state_t value encoded as uint32_t. Only SETTLED has a final result/count; other results are BUSY with count zero. accepted=1 denotes the retained copied cell, including a terminal error when the existing owner rejects admission. No hardware effect follows from acceptance alone.

Public Members

uint32_t abi

uint32_t slot

uint32_t session_low

uint32_t session_high

uint32_t epoch_low

uint32_t epoch_high

uint32_t state

uint32_t result

uint32_t transferred

uint32_t accepted

user_io_async_storage.h

Trusted kernel assembly for exact copied UART user cells.

Author

Nexus Team

Version

1.0.0

Date

2026-10-20

Copyright

Copyright (c) 2026 Nexus Team

Enums

enum nx_user_io_copy_access

Nominal copy permissions; actual access still requires trusted copy.

Values:

enumerator NX_USER_IO_COPY_READ

enumerator NX_USER_IO_COPY_WRITE

Functions

nx_result_t nx_user_io_async_construct(nx_user_io_async_t *mediation, nx_user_io_async_slot_t *slots, size_t count, const nx_user_io_async_config_t *config)

Cold construct one exact copied mediation over a real owner.

Note

Privileged unmasked Thread with owner idle and no concurrent users. Cold O(n squared) alias checks reject all known mutable cell/payload/control overlaps and user-RAM aliases. Admission checks fixed region extents and copies at most the selected exact payload budget; no queue or worker is added. Keep policy, cells, owner, provider and all contexts stable through permanent close, consumption and successful join. Pure cold checks precede a constructing reservation and the trusted role claim; no fallible step follows successful claim. Fresh objects require a larger externally claimed session; this object cannot be reconstructed to reset its epochs.

Parameters:

• mediation – [out] Fresh zero privileged storage, initialized once.

• slots – [inout] Exact caller-owned cells/payloads, no maximum pool.

• count – [in] Positive cell count representable in a scalar slot ID.

• config – [in] Immutable trusted principal/grant/copy/owner binding.

Returns:

SUCCESS or INVALID/STATE/CONTEXT/BUSY/EXHAUSTED, or trusted claim error without new retained users or hardware effects; every rejected output remains unchanged.

struct nx_user_io_copy_region_t

#include <user_io_async_storage.h>

Nominal actual user RAM; trusted copy still enforces real access.

Public Members

uintptr_t begin

size_t bytes

uint32_t access

struct nx_user_io_copy_ops_t

#include <user_io_async_storage.h>

Bounded trusted kernel identity and fault-contained copies.

Note

identity authenticates the current entry, never user input. Copy operations guarantee complete checked CPU access and mapping/process lifetime for the callback duration. Neither success nor error retains a user address, kernel scratch pointer, mapping or observer after return. Errors may have partially copied bytes; the copied payload cell is wiped on rejection, and reply failure is recoverable through exact slot/epoch. No callback blocks, dispatches recursively, or substitutes a permission observation for fault-safe copying. Identity/copy callbacks may close this mediation. A new kernel/CMSE wrapper must actually establish these preconditions; this component does not.

             claim is a trusted exclusive role authority for the actual
             owner/controller binding. It rejects a second live role even
             with a larger session, and rejects reused/non-increasing
             nonzero sessions from persistent, nonwrapping history across
             fresh storage, process/device reset and reconstruction.
             Failed claim retains no reference/effect. Successful claim
             permanently consumes that session and retains the exact role
             until release. release SUCCESS proves outer

gateway/transport observers joined and detaches all authority references; failure retains the original role unchanged. drained SUCCESS permanently fences future outer gateway entry and joins all gateway/transport observers, while the exact role remains claimed. Failed drained preserves the role and every cell unchanged. It must not modify bound configuration, cell identities or requests. Claim, release and drained are bounded and cannot recursively construct, dispatch, close, reap or join. Context/history must remain live; no source code implements this kernel authority, physical isolation, storage partition or recovery policy. Alternate wrappers of one controller are not distinct roles.

Public Members

nx_result_t (*claim)(void *context, uint32_t principal, uint32_t device, uint64_t session, nx_bus_owner_t *owner, const nx_user_io_async_t *role)

nx_result_t (*release)(void *context, const nx_user_io_async_t *role, uint64_t session)

nx_result_t (*drained)(void *context, const nx_user_io_async_t *role, uint64_t session)

nx_result_t (*identity)(void *context, uint32_t *principal)

nx_result_t (*copy_in)(void *context, uint32_t principal, void *destination, const void *user_source, size_t bytes)

nx_result_t (*copy_out)(void *context, uint32_t principal, void *user_destination, const void *source, size_t bytes)

struct nx_user_io_copy_port_t

#include <user_io_async_storage.h>

Public Members

const nx_user_io_copy_ops_t *ops

void *context

size_t context_bytes

struct nx_user_io_async_config_t

#include <user_io_async_storage.h>

Immutable trusted one-principal/one-device/one-owner grant.

Note

This is kernel configuration, never copied from users. owner/executor/port must be the already constructed exact BusOwner + UARTOwner bridge, with no other direct producers or external request/payload observers. Completion callbacks are not installed. All callback contexts remain privileged; explicit extents cover their complete live controls. Guard, clock and wake contexts may be the same trusted object. The caller owns actual UART startup, hardware attribution, executor scheduling, clock/deadline domain and final stop.

Public Members

uint32_t principal

uint32_t device

uint64_t session

nx_bus_owner_t *owner

nx_uart_owner_executor_t *executor

const nx_uart_port_t *port

size_t port_context_bytes

size_t guard_context_bytes

size_t clock_context_bytes

size_t wake_context_bytes

nx_user_io_copy_port_t copy

const nx_user_io_copy_region_t *regions

size_t region_count

struct nx_user_io_async_slot_t

#include <user_io_async_storage.h>

Exact privileged cell; initialize only data and capacity.

Note

All other fields start zero and are mechanism-private after construction. data is independent writable privileged RAM, capacity is its exact positive byte budget, at most UINT32_MAX. No user pointer is ever assigned here. Core identity epochs never wrap and survive consume/close; never copy or reset a live cell. UARTOwner borrows operation/payload until real provider final access, then user-result retention lasts until successful reply copy plus joined CONSUME, or trusted joined reap. Epoch history survives both paths.

Public Members

uint8_t *data

size_t capacity

nx_request_slot_t identity

nx_request_t request

nx_uart_owner_operation_t operation

nx_owner_ticket_t owner_ticket

struct nx_user_io_async

#include <user_io_async_storage.h>

Caller-owned trusted control; initialize once, never reset epochs.

Public Members

const nx_user_io_async_config_t *config

nx_user_io_async_slot_t *slots

size_t count

bool initialized

bool constructing

bool closing

bool closing_call

bool working

bool releasing

bool joined

bool reaping

bool reaped

i3c_controller.h

Explicit bounded I3C discovery, transfers and event ownership.

Author

Nexus Team

Version

1.0.0

Date

2026-10-20

Copyright

Copyright (c) 2026 Nexus Team

Typedefs

typedef struct nx_i3c_controller nx_i3c_controller_t

Enums

enum nx_i3c_kind_t

Values:

enumerator NX_I3C_DISCOVER

enumerator NX_I3C_PRIVATE

enumerator NX_I3C_CCC

enum nx_i3c_event_kind_t

Values:

enumerator NX_I3C_EVENT_IBI

enumerator NX_I3C_EVENT_HOT_JOIN

Functions

nx_result_t nx_i3c_request_prepare(nx_i3c_request_t *request, nx_i3c_kind_t kind, nx_i3c_endpoint_t endpoint, uint8_t ccc, uint8_t *data, size_t bytes, bool read, bool broadcast, nx_time_us_t deadline)

Prepare unused metadata without retaining its payload.

Note

Serialized owner Thread. DISCOVER has no payload or target. PRIVATE permits 1..65535 bytes. CCC permits only ENEC/DISEC broadcast/direct writes and direct GETMWL/GETMRL/GETPID/ GETBCR/GETDCR/GETSTATUS reads, with exact defined lengths. GETMRL uses two bytes, or three when confirmed BCR bit2 advertises an IBI payload. Address-changing, HDR and controller-handoff CCCs reject. All APIs require one serialized executor. Port and clock callbacks must not reenter the core, invoke application code or mutate retained state. No ISR, allocation, OS lock or worker. Absolute deadlines use the injected clock.

nx_result_t nx_i3c_submit(nx_i3c_controller_t *controller, nx_i3c_request_t *request, nx_i3c_ticket_t *ticket)

Admit a finite operation after cold validation and readiness.

Note

SUCCESS transfers the borrow. Rejection has no effects or retained references. Outputs cannot alias retained controller, port table, target/event storage, policy, request or payload. Port and clock context spans remain the caller’s responsibility.

nx_result_t nx_i3c_service(nx_i3c_controller_t *controller)

Perform one bounded FIFO/event phase or one drain proof.

Note

Partial DAA, malformed observations and errors fault admission while retaining every known/tentative assigned address. Cancel/timeout/failed drain never release a loan. Failed quiescence stays QUARANTINED; continued service may recover. An event overflow returns OVERFLOW and latches its counter, without discarding an already retained queued event.

nx_result_t nx_i3c_cancel(nx_i3c_ticket_t ticket)

Request withdrawal using stable epoch before request dereference.

nx_result_t nx_i3c_endpoint(nx_i3c_controller_t *controller, size_t index, nx_i3c_endpoint_t *endpoint)

Obtain only a confirmed target; tentative/retired records reject.

nx_result_t nx_i3c_event_take(nx_i3c_controller_t *controller, nx_i3c_event_t *event)

Copy one retained event; EMPTY leaves output unchanged.

nx_result_t nx_i3c_event_status(nx_i3c_controller_t *controller, nx_i3c_event_status_t *status)

Copy saturating loss counters without clearing them.

nx_result_t nx_i3c_close(nx_i3c_controller_t *controller)

Close admission without changing loans, target identities or events.

nx_result_t nx_i3c_reset(nx_i3c_controller_t *controller)

Prove a whole-bus reset before invalidating dynamic addresses.

Note

Requires closed admission. Hardware proof covers real wire, FIFO and IRQ quiescence AND every target’s dynamic address invalidated. Peripheral reset or FIFO flush alone is never this proof. Failure preserves all loans and address records. Success settles outstanding work and invalidates endpoints; retained events preserve their old epochs for the caller.

nx_result_t nx_i3c_reopen(nx_i3c_controller_t *controller)

Reopen an idle unfaulted pause; faults require explicit bus reset.

nx_result_t nx_i3c_stop(nx_i3c_controller_t *controller)

Close, withdraw and finally relinquish the unique controller.

Note

Active work or queued events return BUSY. Caller continues service, consumes events and retries. Assigned/tentative addresses or a fault return STATE until whole-bus reset proof invalidates them. Successful final wire/ FIFO/IRQ quiescence releases ownership, never reconstructing this object. Storage outlives copied endpoints and tickets.

struct nx_i3c_endpoint_t

#include <i3c_controller.h>

Controller-bound confirmed target incarnation, never a factory ID.

Public Members

nx_i3c_controller_t *controller

size_t index

uint64_t epoch

struct nx_i3c_ticket_t

#include <i3c_controller.h>

Stable operation identity; controller outlives all copied controls.

Public Members

nx_i3c_controller_t *controller

uint64_t epoch

struct nx_i3c_request_t

#include <i3c_controller.h>

Caller-owned finite operation; no implicit bus discovery.

Note

Initialize base once with nx_request_initialize. Accepted metadata and payload stay borrowed until acquire SETTLED. TX stays immutable; transferred counts bytes handed to the FIFO, not acknowledged target effects. No replay after errors. Public fields are immutable throughout an accepted borrow.

Public Members

nx_request_t base

nx_i3c_endpoint_t endpoint

uint8_t *data

size_t bytes

nx_i3c_kind_t kind

uint8_t ccc

bool read

bool broadcast

struct nx_i3c_event_t

#include <i3c_controller.h>

Copied event; no callback, target creation or hidden work.

Note

IBI endpoint retains its exact confirmed target epoch. Confirmed BCR bit1 must advertise IBI. Bit2 requires 1..4 payload bytes including MDB; otherwise zero data bytes. HOT_JOIN carries no endpoint and only requests explicit caller-controlled discovery. Payload is at most four bytes, as in the selected H563 reference; no timestamp claim.

Public Members

nx_i3c_event_kind_t kind

nx_i3c_endpoint_t endpoint

uint8_t payload[4]

uint8_t bytes

struct nx_i3c_event_status_t

#include <i3c_controller.h>

Explicit loss accounting; counters saturate rather than wrap.

Public Members

uint32_t overflow

uint32_t rejected_ibi

i3c_controller_storage.h

Caller storage and aggregate I3C hardware boundary.

Author

Nexus Team

Version

1.0.0

Date

2026-10-20

Copyright

Copyright (c) 2026 Nexus Team

Functions

nx_result_t nx_i3c_controller_construct(nx_i3c_controller_t *controller, const nx_i3c_controller_config_t *config)

Bind unused zero storage and claim one controller.

Note

Reject overlapping/unaligned/overflowing storage, duplicate PIDs/addresses, reserved I3C addresses and nonzero targets. The config value is copied and need not remain alive; its referenced storage and contexts remain live and separate from every request/payload/output. 48-bit PIDs are caller- authored, never selected by a factory. Positive event capacity and 1..8-byte service batches match this bounded SDR/IBI reference. No legacy I2C, DMA, HDR, target role, implicit discovery or hidden event worker.

struct nx_i3c_target_definition_t

#include <i3c_controller_storage.h>

Authored immutable target policy, not runtime factory discovery.

Public Members

uint64_t pid

uint8_t address

struct nx_i3c_target_state_t

#include <i3c_controller_storage.h>

Caller-owned target record, zero-initialized once.

Note

Core retains tentative and confirmed addresses on DAA error. Epoch never resets or wraps, including after bus reset.

Public Members

uint64_t epoch

uint8_t address

uint8_t bcr

uint8_t dcr

bool assigned

bool tentative

struct nx_i3c_command_t

#include <i3c_controller_storage.h>

Value command; begin copies it synchronously and retains no pointer.

Public Members

nx_i3c_kind_t kind

uint32_t bytes

uint8_t address

uint8_t ccc

bool read

bool broadcast

struct nx_i3c_observation_t

#include <i3c_controller_storage.h>

One bounded hardware observation and aggregate FIFO progress.

Note

No callback retains spans. tx/rx counts may not exceed the supplied capacities. DAA acknowledged confirms the preceding assignment BEFORE any next identity in this observation. A complete DAA with a tentative unacknowledged address is an error, never implicit success. Event data are fully copied.

Public Members

size_t transmitted

size_t received

nx_result_t error

uint64_t pid

uint8_t bcr

uint8_t dcr

uint8_t ibi_address

uint8_t ibi_payload[4]

uint8_t ibi_bytes

bool identity

bool assigned

bool complete

bool ibi

bool hot_join

struct nx_i3c_port_ops_t

#include <i3c_controller_storage.h>

Synchronous bounded hardware leaves; no request forwarding.

begin and assign are infallible commands. pump reports later hardware failures and services at most the supplied batch capacities plus one IBI and one hot-join latch. No command or span is retained. No application code is called. withdraw requests abort. quiescent SUCCESS proves actual wire/FIFO/IRQ quiescence and all port observers detached.

reset additionally proves EVERY target dynamic address invalidated. FIFO flush or controller reset alone cannot report SUCCESS. BUSY/IO/UNSUPPORTED proof retains loans and ownership. release follows successful final quiescence. The port context and supplied storage outlive observers.

Note

All port/clock callbacks are non-reentrant: no core calls, application calls or mutation of retained core state. claim atomically acquires an exclusive controller and its IRQ/clock/pins. SUCCESS requires independently established proof that EVERY target dynamic address is invalidated, including targets still powered across MCU reset. The caller establishes this baseline before construction; claim never attempts an unproven reset. Rejection has no effects. ready is a read-only admission check.

Public Members

nx_result_t (*claim)(void *context, const void *owner)

void (*release)(void *context, const void *owner)

nx_result_t (*ready)(void *context)

void (*begin)(void *context, const nx_i3c_command_t *command)

void (*pump)(void *context, const uint8_t *tx, size_t tx_capacity, uint8_t *rx, size_t rx_capacity, nx_i3c_observation_t *observation)

void (*assign)(void *context, uint8_t address)

void (*withdraw)(void *context)

nx_result_t (*quiescent)(void *context)

nx_result_t (*reset)(void *context)

struct nx_i3c_controller_config_t

#include <i3c_controller_storage.h>

Exact caller capacities; separate static controller and target data.

Public Members

const nx_i3c_port_ops_t *ops

void *context

nx_clock_t clock

const nx_i3c_target_definition_t *definitions

nx_i3c_target_state_t *targets

size_t target_count

nx_i3c_event_t *events

size_t event_capacity

size_t batch_bytes

struct nx_i3c_controller

#include <i3c_controller_storage.h>

Public Members

nx_i3c_controller_config_t config

nx_request_slot_t slot

nx_i3c_request_t *active

size_t progress

size_t pending_target

size_t event_head

size_t event_count

nx_i3c_event_status_t event_status

nx_result_t result

bool initialized

bool closed

bool faulted

bool draining

bool joined

f407_i2s2_slave_tx.h

Exact F407 finite stereo16 I2S2 slave transmitter.

Author

Nexus Team

Version

1.0.0

Date

2026-10-20

Copyright

Copyright (c) 2026 Nexus Team

Defines

NX_F407_I2S2_SLAVE_TX_STORAGE_BYTES

Enums

enum nx_f407_i2s2_resource_t

Fixed chip resource selected by the same validated hardware IR.

Values:

enumerator NX_F407_I2S2_SLAVE_TX

Functions

nx_result_t nx_f407_i2s2_slave_tx_initialize(nx_f407_i2s2_slave_tx_storage_t *storage, const nx_f407_i2s2_slave_tx_t *face, const nx_f407_i2s2_slave_tx_config_t *config)

Acquire the selected F407 SPI2 personality and fixed pads.

The caller owns the external master and holds CK idle LOW and WS HIGH continuously from before initialization/submission until acquire-observed ACTIVE. Pin reads sample instants; they cannot prove electrical silence. The master transmits exactly the declared complete frames and stops before a missing next word. Restart begins at the left channel. A prefilling cancellation with CK idle cannot empty DR; preserve QUARANTINED storage until coordinated drain clocks allow TXE then fresh BSY observations. This error drain can underrun and does not promise valid stereo audio or a complete transmitted frame; errors report zero transferred bytes. Timeout, TC or NDTR0 never proves wire completion or final access. The caller also supplies valid operating voltage, I/O levels, load, CK/WS/SD timing and DMA refill margin under DS8626. ACTIVE and pin samples do not measure or qualify those electrical/rate conditions.

One privileged unmasked task serializes every method and external owner lifecycle. Preserve incoming masks on all rejection paths. NMI/HardFault, other DMA/IRQ/pin owners, reset/reclock/debugger writers and concurrent Platform stop are excluded. Observed reset or clock-profile history loss while borrowed permanently retains the request; restoring reset-looking registers cannot establish prior final access. Main SRAM is DMA-visible; CCM is not. Chip pin capability establishes neither a PCB route nor codec/electrical HIL. The assembly and fixture supply the actual F407/package identity: shared device-group and density reads alone do not distinguish an F405 or authenticate the physical package.

Note

Exact F407VE/ZG, baremetal, HSE8/PLL168 and live TIM2 only. The normal hardware role exclusively claims SPI2/I2S2, PB12 WS/PB13 CK/PB15 SD AF5, DMA1 Stream4 channel0 and both vectors. No PLLI2S, continuous DBM or IRQ service is enabled. Peripheral/pad/SPI2 gate ownership lasts until stop SUCCESS, independently of each request’s shorter frame loan. The selected cold-reset Platform separately holds the shared GPIOB/DMA1 gates. Initialization requires both already on; this provider never enables or withdraws them. Every shared domain user, including external HAL users, must join before Platform stop. Clock-gating is not proof of a reset engine; unknown running-state attachment is unsupported.

Parameters:

• storage – [inout] Fresh zero storage, disjoint from all controls.

• face – [in] Stable readonly {&nx_f407_i2s2_slave_tx_ops, storage}.

• config – [in] Fixed resource and observation budget.

Returns:

SUCCESS, INVALID, CONTEXT, BUSY, STATE, UNSUPPORTED or IO. Initialization IO retains cleanup responsibility; call stop before reuse.

Variables

const nx_f407_i2s2_slave_tx_ops_t nx_f407_i2s2_slave_tx_ops

Shared immutable methods; callbacks receive the storage context.

struct nx_f407_i2s2_tx_request_t

#include <f407_i2s2_slave_tx.h>

One complete contiguous interleaved stereo16 frame block.

Note

Initialize and prepare base with the ordinary helpers. The source has one plane of contiguous nonempty rows, no offset or padding, and 4..131068 bytes in a multiple of four. Each frame stores left then right 16-bit little-endian samples. The fixed Philips I2S wire emits each sample MSB first in 16-bit slots. Sample values, rate, codec and external clocks are caller policy. Acceptance transfers the exact immutable source loan and borrows this request until acquire-observed SETTLED. Never separately release, mutate or reuse accepted storage. SUCCESS reports the whole block only after memory and wire completion. Every error or cancellation reports zero; the DMA count does not establish serialized audio bytes.

Public Members

nx_request_t base

nx_frame_dma_loan_t *source

struct nx_f407_i2s2_slave_tx_ops_t

#include <f407_i2s2_slave_tx.h>

One privileged serialized task executor; no ISR callback.

Note

submit SUCCESS means ACCEPTED, including subsequent setup failure. QUEUED is not armed. Acquire-observed ACTIVE alone authorizes the external master to begin CK, after one DR halfword and a live TIM2 interval have been observed. Error, cancellation or timeout retains the full loan until actual engine, serializer, vector and address withdrawal. service returns SUCCESS when idle or settled, otherwise BUSY or an observed failure with the borrow retained. stop closes further admission and requests cancellation; repeat it after service proves the remaining cleanup. The first SR observation occurs only after acceptance because reading SR clears UDR/FRE. Its fault remains latched through cleanup; a later clean status read cannot erase the operation’s cause. No method allocates, starts a task or replays a block. Admission checks controls against every full-capacity pool slot in O(slot count); service/cancel do not scan the pool.

Public Members

nx_result_t (*submit)(void *context, nx_f407_i2s2_tx_request_t *request)

nx_result_t (*service)(void *context)

nx_result_t (*cancel)(void *context, nx_f407_i2s2_tx_request_t *request)

nx_result_t (*stop)(void *context)

struct nx_f407_i2s2_slave_tx_t

#include <f407_i2s2_slave_tx.h>

Immutable caller-owned face; private state is separate.

Public Members

const nx_f407_i2s2_slave_tx_ops_t *ops

void *context

struct nx_f407_i2s2_slave_tx_config_t

#include <f407_i2s2_slave_tx.h>

Exact resource and positive bounded observation budget.

Note

poll_limit bounds each arm/drain observation loop, not time or external-clock progress. Arming observes at least three actual 1 MHz TIM2 ticks after I2SE readback. Deadlines are absolute in the current live Platform TIM2 epoch. The caller stops and joins this owner before Platform stop/restart; the deadline includes wire and observer withdrawal. No automatic ClockDomain enrollment is implied.

Public Members

nx_f407_i2s2_resource_t resource

uint32_t poll_limit

union nx_f407_i2s2_slave_tx_storage_t

#include <f407_i2s2_slave_tx.h>

Exact storage for one owner, zeroed once before publication.

Note

Do not copy or alter. Keep storage and face live through successful stop. Accepted request/source loans last until acquire-observed SETTLED; a failed stop never revokes an unfinished borrow.

Public Members

uint64_t alignment

uintptr_t pointer_alignment

unsigned char private_bytes[NX_F407_I2S2_SLAVE_TX_STORAGE_BYTES]

MCUboot control and explicit Flash composition

Nexus::MCUBootControl exposes the stateless public control API below. It uses only Nexus types. Nexus::MCUBootPort is the separate, concrete Flash composition boundary; Nexus::MCUBootBootStorage belongs to a separately linked boot image. These targets are outside the default platform assembly.

Use the canonical MCUboot contract for helper selection, the boot/application ownership diagram, finite operation and Flash-region lifetime, partial persistent writes and product recovery duties. The selected overwrite-only profile supports permanent requests; the control API does not authenticate a candidate, reset hardware or provide rollback. Software models and linked-image budgets do not establish physical Flash, power-cut or HIL qualification.

mcuboot_control.h

Stateless control of a fixed MCUboot overwrite-only image.

The selected single-image profile supports permanent requests only. This API neither downloads nor verifies an image, resets hardware, confirms a trial image, or provides rollback. Applications own authorization, valid candidate bytes, maintenance scheduling, platform lifetime and reset policy.

Author

Nexus Team

Enums

enum nx_mcuboot_request_t

Requested upgrade behavior; TEST is explicitly unsupported.

Values:

enumerator NX_MCUBOOT_REQUEST_TEST

enumerator NX_MCUBOOT_REQUEST_PERMANENT

enum nx_mcuboot_action_t

Upstream observed action, not a physical or image-health verdict.

Note

TEST and REVERT can be observed in foreign trailer metadata; their presence does not add support for those modes to overwrite-only firmware.

Values:

enumerator NX_MCUBOOT_ACTION_NONE

enumerator NX_MCUBOOT_ACTION_TEST

enumerator NX_MCUBOOT_ACTION_PERMANENT

enumerator NX_MCUBOOT_ACTION_REVERT

enumerator NX_MCUBOOT_ACTION_FAILED

Functions

nx_result_t nx_mcuboot_query(nx_mcuboot_action_t *action)

Query upstream’s planned action for image zero.

Note

Task/boot context only. Caller serializes access and supplies the immutable Flash operation hook and its finite deadline for the whole call. All referenced areas, regions, clock and provider remain alive through return. The pinned upstream API treats an unreadable secondary trailer as empty; NONE therefore does not establish secondary availability or image validity.

Parameters:

• action – Receives a value on success only; never retained.

Returns:

NX_SUCCESS for a known action, NX_ERROR_INVALID for NULL, or NX_ERROR_IO for upstream PANIC, an unknown value or a reported read error.

nx_result_t nx_mcuboot_request(nx_mcuboot_request_t request)

Request a permanent upgrade using the upstream public trailer API.

Note

Same serialized finite operation/lifetime contract as query. Return settles current Flash access; a timeout is not a physical pulse abort. This does not prove candidate authenticity, promise old-image recovery, renew the deadline, stop infrastructure or reset the MCU.

Parameters:

• request – PERMANENT requests an update; TEST rejects without access.

Returns:

NX_SUCCESS after upstream completes and reports PERMANENT on readback, NX_ERROR_UNSUPPORTED for TEST, NX_ERROR_INVALID for an unknown request, NX_ERROR_STATE for another known readback action, or NX_ERROR_IO for an upstream error. An error can follow partial persistent trailer modification, including a pending TEST that cannot be silently promoted.