spi.h File Reference

Single-executor polling SPI endpoints and complete CS transactions. More...

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

Go to the source code of this file.

Data Structures
struct	nx_spi_request_t
	Caller-owned finite SPI request with one whole-CS interval. More...
struct	nx_spi_ops_t
	Shared read-only methods using one provider state. More...
struct	nx_spi_port
	Immutable interface pointing to caller-owned state. More...
struct	nx_spi_endpoint_ops_t
	Shared read-only methods using one provider state. More...
struct	nx_spi_endpoint
	Immutable interface pointing to caller-owned state. More...

Macros
#define	NX_SPI_MEMORY_TX_FIXED   1U
	Explicit single-cell DMA addresses, both borrowed until SETTLED.
#define	NX_SPI_MEMORY_RX_FIXED   2U

Typedefs
typedef struct nx_spi_port	nx_spi_port_t
typedef struct nx_spi_endpoint	nx_spi_endpoint_t

Functions
nx_result_t	nx_spi_endpoint_transfer (const nx_spi_endpoint_t *endpoint, const uint8_t *tx, uint8_t *rx, size_t length, nx_time_us_t deadline, size_t *transferred)
	Execute one bounded full-duplex 8-bit polling transaction.
nx_result_t	nx_spi_port_recover (const nx_spi_port_t *port)
	Recover an idle SPI controller after its retained fault.
nx_result_t	nx_spi_request_prepare (nx_spi_request_t *request, const uint8_t *tx, uint8_t *rx, size_t length, nx_time_us_t deadline)
	Prepare an unborrowed finite request without copying buffers.
nx_result_t	nx_spi_endpoint_submit (const nx_spi_endpoint_t *endpoint, nx_spi_request_t *request)
	Submit one finite asynchronous whole-CS transaction.
nx_result_t	nx_spi_endpoint_submit_memory (const nx_spi_endpoint_t *endpoint, nx_spi_request_t *request, uint8_t memory_flags)
	Submit explicit incrementing or single-cell DMA memory.
nx_result_t	nx_spi_endpoint_start_admitted (const nx_spi_endpoint_t *endpoint, nx_spi_request_t *request)
	Start an adapter-admitted QUEUED request without readmission.
bool	nx_spi_endpoint_on_port (const nx_spi_endpoint_t *endpoint, const nx_spi_port_t *port)
	Verify an endpoint belongs to the serviced bus.
nx_result_t	nx_spi_port_cancel (const nx_spi_port_t *port, nx_spi_request_t *request)
	Request cancellation without revoking DMA/CS buffer loans.
void	nx_spi_port_service (const nx_spi_port_t *port)
	Advance one asynchronous bus under its single task executor.
nx_result_t	nx_spi_port_stop (const nx_spi_port_t *port)
	Close admission and retain active sources until full drain.
nx_result_t	nx_spi_port_attach_wake (const nx_spi_port_t *port, const nx_irq_wake_t *wake, uint8_t syscall_ceiling)
	Attach an optional hint sink to asynchronous bus IRQ publishers.

Detailed Description

Single-executor polling SPI endpoints and complete CS transactions.

Author

Nexus Team

Definition in file spi.h.

Macro Definition Documentation

NX_SPI_MEMORY_RX_FIXED

#define NX_SPI_MEMORY_RX_FIXED   2U

Definition at line 22 of file spi.h.

NX_SPI_MEMORY_TX_FIXED

#define NX_SPI_MEMORY_TX_FIXED   1U

Explicit single-cell DMA addresses, both borrowed until SETTLED.

Definition at line 21 of file spi.h.

Typedef Documentation

nx_spi_endpoint_t

typedef struct nx_spi_endpoint nx_spi_endpoint_t

Definition at line 18 of file spi.h.

nx_spi_port_t

typedef struct nx_spi_port nx_spi_port_t

Definition at line 17 of file spi.h.

Function Documentation

nx_spi_endpoint_on_port()

bool nx_spi_endpoint_on_port	(	const nx_spi_endpoint_t *	endpoint,
		const nx_spi_port_t *	port )

Verify an endpoint belongs to the serviced bus.

Parameters

[in]	endpoint	Immutable endpoint identity kept alive by its caller.
[in]	port	Exact execution bus bound to an adapter.

Returns

True only when the provider proves matching controller state and compatible bus methods; false for invalid/missing methods.

Note

Task/IRQ bounded cold identity check, no lookup or ownership effects. An adapter checks this before hardware execution; asynchronous admission also checks before borrowing.

nx_spi_endpoint_start_admitted()

nx_result_t nx_spi_endpoint_start_admitted	(	const nx_spi_endpoint_t *	endpoint,
		nx_spi_request_t *	request )

Start an adapter-admitted QUEUED request without readmission.

Parameters

[in]	endpoint	Initialized exact CS binding and bus executor.
[in,out]	request	Live QUEUED storage already borrowed by its adapter.

Returns

Success hands execution to the bus; BUSY retains QUEUED. Other errors must be settled by the adapter executor.

nx_spi_endpoint_submit()

nx_result_t nx_spi_endpoint_submit	(	const nx_spi_endpoint_t *	endpoint,
		nx_spi_request_t *	request )

Submit one finite asynchronous whole-CS transaction.

Parameters

[in]	endpoint	Initialized endpoint on a single-executor bus.
[in,out]	request	READY storage; retained only after NX_SUCCESS.

Returns

Success means ACCEPTED; all rejection errors create zero retained references and zero residual hardware effects.

Note

Task-only bounded admission. Selected modes declare DMA domain/length/buffer requirements. DMA TC alone never proves peripheral idle; the bus executor continues service to SETTLED.

nx_spi_endpoint_submit_memory()

nx_result_t nx_spi_endpoint_submit_memory	(	const nx_spi_endpoint_t *	endpoint,
		nx_spi_request_t *	request,
		uint8_t	memory_flags )

Submit explicit incrementing or single-cell DMA memory.

Parameters

[in]	endpoint	Initialized single-executor DMA endpoint
[in,out]	request	READY request with two non-NULL caller addresses
[in]	memory_flags	TX_FIXED repeats one immutable dummy byte; RX_FIXED repeatedly writes one caller-owned discard byte; zero uses complete incrementing TX/RX buffers

Returns

ACCEPTED on SUCCESS; other results retain no references

Note

Fixed directions require one byte, other directions length bytes, within reviewed DMA domains. The actual spans must not overlap. All addresses remain borrowed through drain until acquire-observed SETTLED. No hidden scratch is used. Both fixed flags permit explicit clock-only transfers. Request preparation does not retain these flags; only this successful admission selects them. Ordinary submit and the existing owner continue their ordinary buffer contract.

nx_spi_endpoint_transfer()

nx_result_t nx_spi_endpoint_transfer	(	const nx_spi_endpoint_t *	endpoint,
		const uint8_t *	tx,
		uint8_t *	rx,
		size_t	length,
		nx_time_us_t	deadline,
		size_t *	transferred )

Execute one bounded full-duplex 8-bit polling transaction.

Parameters

[in]	endpoint	Fixed CS/mode/rate binding on one controller.
[in]	tx	Transmit bytes, or NULL to send 0xff.
[out]	rx	Receive bytes, or NULL to discard.
[in]	length	Positive transfer length; at least one buffer exists.
[in]	deadline	Absolute deadline; includes adapter queue residence.
[out]	transferred	Complete bytes; reset to zero before execution.

Returns

Success, BUSY/INVALID/TIMEOUT/IO. Return releases all buffers and CS after drain; polling is CPU-active, not IRQ/DMA async.

Note

Task-only single executor, no allocation/OS lock. One CS interval covers the entire transfer. Deadline cannot preempt an in-flight hardware byte; peripheral drain may exceed it.

nx_spi_port_attach_wake()

nx_result_t nx_spi_port_attach_wake	(	const nx_spi_port_t *	port,
		const nx_irq_wake_t *	wake,
		uint8_t	syscall_ceiling )

Attach an optional hint sink to asynchronous bus IRQ publishers.

Parameters

[in]	port	One initialized bus controlled by a task executor.
[in]	wake	Immutable borrowed target or NULL to detach.
[in]	syscall_ceiling	Optional additional unshifted kernel-safe priority floor; cannot weaken generated policy. PRIMASK kernel targets require zero. Ignored without kernel calls.

Returns

Success, PERMISSION for unsafe actual priority, CONTEXT/STATE for illegal control or UNSUPPORTED for a polling-only bus.

Note

Join old publishers and waiters before freeing wake storage.

nx_spi_port_cancel()

nx_result_t nx_spi_port_cancel	(	const nx_spi_port_t *	port,
		nx_spi_request_t *	request )

Request cancellation without revoking DMA/CS buffer loans.

Parameters

[in]	port	Same single execution owner as submit and service.
[in,out]	request	Exact live active request, never a stale raw pointer.

Returns

Success starts drain or observes prior settlement; STATE for another request, UNSUPPORTED for a polling-only provider.

Note

Cross-task controls use stable adapter slots and epochs.

nx_spi_port_recover()

nx_result_t nx_spi_port_recover

(

const nx_spi_port_t *

port

)

Recover an idle SPI controller after its retained fault.

Parameters

[in]

port

Single executor with no live transaction or CS borrow.

Returns

Success only after reset/idle proof; BUSY/STATE/UNSUPPORTED preserves recovery responsibility and never replays work.

nx_spi_port_service()

void nx_spi_port_service

(

const nx_spi_port_t *

port

)

Advance one asynchronous bus under its single task executor.

Parameters

[in]

port

Live provider; call while stopping and throughout drain.

Note

Bounded no-wait service. Final publication follows DMA/IRQ detach and peripheral-idle proof; failed drain quarantines.

nx_spi_port_stop()

nx_result_t nx_spi_port_stop

(

const nx_spi_port_t *

port

)

Close admission and retain active sources until full drain.

Parameters

[in]

port

Live bus; all external producers already quiesced.

Returns

Success proves source release, BUSY requires service, or UNSUPPORTED when the provider has no asynchronous lifecycle.

nx_spi_request_prepare()

nx_result_t nx_spi_request_prepare	(	nx_spi_request_t *	request,
		const uint8_t *	tx,
		uint8_t *	rx,
		size_t	length,
		nx_time_us_t	deadline )

Prepare an unborrowed finite request without copying buffers.

Parameters

[in,out]	request	Fresh initialized or consumed SETTLED descriptor.
[in]	tx	Nonempty TX bytes or NULL when the selected mode supports dummy transmission; immutable through final settlement.
[out]	rx	RX buffer or NULL when the selected mode supports discard.
[in]	length	Positive byte count with at least one supplied buffer.
[in]	deadline	Absolute monotonic deadline including queue time.

Returns

Success or INVALID/STATE; failure creates no buffer loan.