Explicit open-drain I2C bus clear with retained leases. More...

#include "nexus/core/time.h"

Data Structures
struct	nx_i2c_bus_clear_ops_t
	Read-only methods for an authorized two-pin GPIO handoff. More...
struct	nx_i2c_bus_clear_port_t
	Explicit immutable GPIO methods and caller-owned adapter state. More...
struct	nx_i2c_bus_clear_timing_t
	Caller-selected electrical timings in microseconds. More...
struct	nx_i2c_bus_clear_result_t
	Independent recovery and STOP/ownership-return results. More...
struct	nx_i2c_bus_clear_t
	Caller-owned, zero-initialized single-executor session. More...

Macros
#define	NX_I2C_BUS_CLEAR_MAX_PULSES 9U
	Maximum completed recovery low/high periods per attempt.

Functions
nx_result_t	nx_i2c_bus_clear_init (nx_i2c_bus_clear_t *clear, nx_i2c_bus_clear_port_t port, nx_clock_t clock, nx_i2c_bus_clear_timing_t timing)
	Bind explicit electrical operations without touching pins.
nx_result_t	nx_i2c_bus_clear_run (nx_i2c_bus_clear_t clear, nx_time_us_t deadline, nx_time_us_t cleanup_deadline, nx_i2c_bus_clear_result_t result)
	Clear one idle, authorized bus with at most nine pulses.
nx_result_t	nx_i2c_bus_clear_finish (nx_i2c_bus_clear_t clear, nx_time_us_t deadline, nx_i2c_bus_clear_result_t result)
	Retry only retained STOP cleanup and ownership return.

Detailed Description

Explicit open-drain I2C bus clear with retained leases.

Definition in file i2c_bus_clear.h.

Macro Definition Documentation

#define NX_I2C_BUS_CLEAR_MAX_PULSES 9U

Maximum completed recovery low/high periods per attempt.

Definition at line 17 of file i2c_bus_clear.h.

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

Retry only retained STOP cleanup and ownership return.

Parameters

[in,out]	clear	Initialized session with a retained lease.
[in]	deadline	New finite absolute cleanup deadline.
[out]	result	Preserved primary/pulse count and latest cleanup.

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

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

Bind explicit electrical operations without touching pins.

Parameters

[in,out]	clear	Fresh zeroed session or a session with no lease.
[in]	port	All five methods required; caller verifies electrical authorization rather than relying on generic GPIO APIs.
[in]	clock	Required bounded monotonic read in one boot domain.
[in]	timing	Reviewed nonzero low/high/STOP/poll durations.

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

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

Parameters

[in,out]	clear	Initialized session with no retained lease.
[in]	deadline	Finite absolute primary-operation deadline.
[in]	cleanup_deadline	Finite absolute STOP/lease deadline in the same clock domain, at or after deadline.
[out]	result	Independent primary/cleanup and retained effects.

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

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