clock_domain.h File Reference

Explicit clock consumers and epoch-bound drain control. More...

#include "nexus/core/status.h"

Go to the source code of this file.

Data Structures
struct	nx_clock_lease
	One stable caller-owned consumer token. More...
struct	nx_clock_barrier_t
	Epoch-bound close control and quiescence evidence. More...

Typedefs
typedef struct nx_clock_domain	nx_clock_domain_t
	Opaque provider, statically supplied by its privileged owner.
typedef struct nx_clock_lease	nx_clock_lease_t
	One stable caller-owned consumer token.

Enumerations
enum	nx_clock_power_mode_t { NX_CLOCK_SHALLOW_SLEEP = 0 , NX_CLOCK_DEEP_STOP , NX_CLOCK_DYNAMIC_RUN }
	Only shallow sleep preserves the established clock/time domain. More...

Functions
nx_result_t	nx_clock_domain_acquire (nx_clock_domain_t *domain, nx_clock_lease_t *lease)
	Acquire one admitted clock consumer without waiting.
nx_result_t	nx_clock_domain_release (nx_clock_domain_t *domain, nx_clock_lease_t *lease)
	Remove the exact retained token after consumer drain.
nx_result_t	nx_clock_domain_close (nx_clock_domain_t *domain, nx_clock_barrier_t *control)
	Close admission and return the current epoch control.
nx_result_t	nx_clock_domain_quiescent (nx_clock_barrier_t control)
	Validate closed admission and zero retained consumers.
nx_result_t	nx_clock_domain_reopen (nx_clock_barrier_t control)
	Reopen a drained domain under a new admission epoch.

Detailed Description

Explicit clock consumers and epoch-bound drain control.

Author

Nexus Team

Version

1.0.0

Date

2026-10-11

Copyright

Copyright (c) 2026 Nexus Team

Definition in file clock_domain.h.

Typedef Documentation

nx_clock_domain_t

typedef struct nx_clock_domain nx_clock_domain_t

Opaque provider, statically supplied by its privileged owner.

Definition at line 16 of file clock_domain.h.

nx_clock_lease_t

typedef struct nx_clock_lease nx_clock_lease_t

One stable caller-owned consumer token.

Note

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

Enumeration Type Documentation

nx_clock_power_mode_t

enum nx_clock_power_mode_t

Only shallow sleep preserves the established clock/time domain.

Enumerator
NX_CLOCK_SHALLOW_SLEEP
NX_CLOCK_DEEP_STOP
NX_CLOCK_DYNAMIC_RUN

Definition at line 43 of file clock_domain.h.

Function Documentation

nx_clock_domain_acquire()

nx_result_t nx_clock_domain_acquire	(	nx_clock_domain_t *	domain,
		nx_clock_lease_t *	lease )

Acquire one admitted clock consumer without waiting.

Returns

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

Note

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

nx_clock_domain_close()

nx_result_t nx_clock_domain_close	(	nx_clock_domain_t *	domain,
		nx_clock_barrier_t *	control )

Close admission and return the current epoch control.

Note

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

nx_clock_domain_quiescent()

nx_result_t nx_clock_domain_quiescent

(

nx_clock_barrier_t

control

)

Validate closed admission and zero retained consumers.

Returns

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

Note

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

nx_clock_domain_release()

nx_result_t nx_clock_domain_release	(	nx_clock_domain_t *	domain,
		nx_clock_lease_t *	lease )

Remove the exact retained token after consumer drain.

Returns

SUCCESS or INVALID/STATE/CONTEXT without removing a borrow

Note

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

nx_clock_domain_reopen()

nx_result_t nx_clock_domain_reopen

(

nx_clock_barrier_t

control

)

Reopen a drained domain under a new admission epoch.

Returns

SUCCESS, BUSY, STATE, EXHAUSTED or CONTEXT without changes

Note

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