Address endpoints, repeated START and explicit STOP settlement. More...

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

Data Structures
struct	nx_i2c_message_t
	One message; a new message starts with repeated START, final with STOP. More...
struct	nx_i2c_request_t
	Caller-owned finite message sequence. More...
struct	nx_i2c_ops_t
	Shared read-only methods using one provider state. More...
struct	nx_i2c_port
	Immutable interface pointing to caller-owned state. More...
struct	nx_i2c_endpoint_ops_t
	Shared read-only methods using one provider state. More...
struct	nx_i2c_endpoint
	Immutable interface pointing to caller-owned state. More...

Macros
#define	NX_I2C_MAX_MESSAGES 8U
	Maintained finite-message admission bounds, checked before hardware access.
#define	NX_I2C_MAX_MESSAGE_BYTES 256U

Typedefs
typedef struct nx_i2c_port	nx_i2c_port_t
typedef struct nx_i2c_endpoint	nx_i2c_endpoint_t

Functions
nx_result_t	nx_i2c_endpoint_transaction (const nx_i2c_endpoint_t endpoint, nx_i2c_message_t messages, size_t count, nx_time_us_t deadline, size_t *transferred)
	Execute a polling 7-bit-address message transaction.
nx_result_t	nx_i2c_port_recover (const nx_i2c_port_t *port)
	Recover an idle controller after a bus fault.
nx_result_t	nx_i2c_request_prepare (nx_i2c_request_t request, nx_i2c_message_t messages, size_t count, nx_time_us_t deadline)
	Prepare an unborrowed request without copying payload.
nx_result_t	nx_i2c_request_validate (const nx_i2c_request_t *request)
	Validate finite descriptors and payload/control separation.
nx_result_t	nx_i2c_endpoint_submit (const nx_i2c_endpoint_t endpoint, nx_i2c_request_t request)
	Admit one finite asynchronous repeated-START transaction.
nx_result_t	nx_i2c_endpoint_start_admitted (const nx_i2c_endpoint_t endpoint, nx_i2c_request_t request)
	Start an already borrowed QUEUED request without readmission.
bool	nx_i2c_endpoint_on_port (const nx_i2c_endpoint_t endpoint, const nx_i2c_port_t port)
	Prove controller identity without hardware effects.
nx_result_t	nx_i2c_port_cancel (const nx_i2c_port_t port, nx_i2c_request_t request)
	Request cancellation without reclaiming any storage.
void	nx_i2c_port_service (const nx_i2c_port_t *port)
	Advance deadline and STOP/DMA drain in bounded task context.
nx_result_t	nx_i2c_port_stop (const nx_i2c_port_t *port)
	Close admission and stop only after every borrower drains.
nx_result_t	nx_i2c_port_attach_wake (const nx_i2c_port_t port, const nx_irq_wake_t wake, uint8_t syscall_ceiling)
	Attach one optional hint sink after actual IRQ policy checks.

Detailed Description

Address endpoints, repeated START and explicit STOP settlement.

Author: Nexus Team

Definition in file i2c.h.

Macro Definition Documentation

◆ NX_I2C_MAX_MESSAGE_BYTES

#define NX_I2C_MAX_MESSAGE_BYTES 256U

Definition at line 23 of file i2c.h.

◆ NX_I2C_MAX_MESSAGES

#define NX_I2C_MAX_MESSAGES 8U

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

Definition at line 22 of file i2c.h.

Typedef Documentation

◆ nx_i2c_endpoint_t

typedef struct nx_i2c_endpoint nx_i2c_endpoint_t

Definition at line 18 of file i2c.h.

◆ nx_i2c_port_t

typedef struct nx_i2c_port nx_i2c_port_t

Definition at line 17 of file i2c.h.

Function Documentation

◆ nx_i2c_endpoint_on_port()

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

Prove controller identity without hardware effects.

Parameters

[in]	endpoint	Immutable addressed child
[in]	port	Exact execution controller

Returns: True only for matching provider state and compatible methods

◆ nx_i2c_endpoint_start_admitted()

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

Start an already borrowed QUEUED request without readmission.

Parameters

[in]	endpoint	Fixed address on the adapter's exact controller
[in,out]	request	Adapter-admitted QUEUED storage

Returns: SUCCESS hands execution to provider; BUSY retains QUEUED

Note: Other errors require adapter settlement; no polling fallback.

◆ nx_i2c_endpoint_submit()

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

Admit one finite asynchronous repeated-START transaction.

Parameters

[in]	endpoint	Initialized fixed address and single executor
[in,out]	request	READY descriptor and all referenced storage

Returns: SUCCESS means ACCEPTED; rejection retains no references

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

◆ nx_i2c_endpoint_transaction()

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

Execute a polling 7-bit-address message transaction.

Parameters

[in]	endpoint	Fixed address/controller binding.
[in,out]	messages	Message buffers; write data are not modified.
[in]	count	One through NX_I2C_MAX_MESSAGES.
[in]	deadline	Finite absolute provider-clock deadline.
[out]	transferred	Completed byte prefix across messages, including error returns.

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

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

◆ nx_i2c_port_attach_wake()

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

Attach one optional hint sink after actual IRQ policy checks.

Parameters

[in]	port	Initialized asynchronous controller
[in]	wake	Borrowed sink or NULL to detach after publisher exit
[in]	syscall_ceiling	Cannot weaken selected kernel policy

Returns: SUCCESS or rejection before replacing any live binding

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

◆ nx_i2c_port_cancel()

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

Request cancellation without reclaiming any storage.

Parameters

[in]	port	Same single executor as submit/service
[in,out]	request	Exact active descriptor, never a stale raw pointer

Returns: SUCCESS begins drain; STATE for another request

◆ nx_i2c_port_recover()

nx_result_t nx_i2c_port_recover ( const nx_i2c_port_t * port )

Recover an idle controller after a bus fault.

Parameters

[in,out] port Single executor, no live transaction/buffer borrow.

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

◆ nx_i2c_port_service()

void nx_i2c_port_service ( const nx_i2c_port_t * port )

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

Parameters

[in] port Live single executor, serviced throughout stop

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

◆ nx_i2c_port_stop()

nx_result_t nx_i2c_port_stop ( const nx_i2c_port_t * port )

Close admission and stop only after every borrower drains.

Parameters

[in] port Controller with external producers quiesced

Returns: SUCCESS releases sources; BUSY requires continued service

◆ nx_i2c_request_prepare()

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

Prepare an unborrowed request without copying payload.

Parameters

[in,out]	request	Initialized READY or consumed SETTLED storage
[in,out]	messages	One through eight complete descriptors
[in]	count	Exact descriptor count
[in]	deadline	Absolute provider-clock deadline

Returns: SUCCESS, INVALID, UNSUPPORTED or STATE; no new loan

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

◆ nx_i2c_request_validate()

nx_result_t nx_i2c_request_validate ( const nx_i2c_request_t * request )

Validate finite descriptors and payload/control separation.

Parameters

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

Returns: SUCCESS, INVALID or UNSUPPORTED without mutation

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

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ NX_I2C_MAX_MESSAGE_BYTES

◆ NX_I2C_MAX_MESSAGES

Typedef Documentation

◆ nx_i2c_endpoint_t

◆ nx_i2c_port_t

Function Documentation

◆ nx_i2c_endpoint_on_port()

◆ nx_i2c_endpoint_start_admitted()

◆ nx_i2c_endpoint_submit()

◆ nx_i2c_endpoint_transaction()

◆ nx_i2c_port_attach_wake()

◆ nx_i2c_port_cancel()

◆ nx_i2c_port_recover()

◆ nx_i2c_port_service()

◆ nx_i2c_port_stop()

◆ nx_i2c_request_prepare()

◆ nx_i2c_request_validate()