timer_capture.h File Reference

Optional raw timer edge capture with caller-owned events. More...

#include "nexus/core/time.h"

Go to the source code of this file.

Data Structures
struct	nx_timer_capture_event_t
	Hardware modulo counter and the separate IRQ observation time. More...
struct	nx_timer_capture_state_t
	Fixed counter units and current software retention state. More...
struct	nx_timer_capture_ops_t
	Shared immutable methods; no per-call acquisition or allocation. More...
struct	nx_timer_capture_t
	Immutable identity; state and methods outlive calls and IRQs. More...

Enumerations
enum	nx_timer_capture_flags { NX_TIMER_CAPTURE_OVERCAPTURE = 1U , NX_TIMER_CAPTURE_RING_LOSS = 2U }
	Observable loss incidents, not an exact count of physical edges. More...

Functions
nx_result_t	nx_timer_capture_start (const nx_timer_capture_t *port, nx_timer_capture_event_t *events, size_t capacity)
	Borrow an exact event ring and enable the fixed capture channel.
nx_result_t	nx_timer_capture_stop (const nx_timer_capture_t *port)
	Disable and read back channel/IRQ sources before returning storage.
nx_result_t	nx_timer_capture_read (const nx_timer_capture_t *port, nx_timer_capture_event_t *event)
	Copy the oldest event in a short saved-mask metadata section.
nx_result_t	nx_timer_capture_state (const nx_timer_capture_t *port, nx_timer_capture_state_t *state)
	Query counter units and observable queue/loss facts.

Detailed Description

Optional raw timer edge capture with caller-owned events.

Author

Nexus Team

Definition in file timer_capture.h.

Enumeration Type Documentation

nx_timer_capture_flags

enum nx_timer_capture_flags

Observable loss incidents, not an exact count of physical edges.

Enumerator
NX_TIMER_CAPTURE_OVERCAPTURE
NX_TIMER_CAPTURE_RING_LOSS

Definition at line 13 of file timer_capture.h.

Function Documentation

nx_timer_capture_read()

nx_result_t nx_timer_capture_read	(	const nx_timer_capture_t *	port,
		nx_timer_capture_event_t *	event )

Copy the oldest event in a short saved-mask metadata section.

Parameters

[in]	port	Single privileged task consumer.
[out]	event	Separate writable output, unchanged on EMPTY/rejection.

Returns

SUCCESS, EMPTY, STATE or INVALID; no block release is required.

nx_timer_capture_start()

nx_result_t nx_timer_capture_start	(	const nx_timer_capture_t *	port,
		nx_timer_capture_event_t *	events,
		size_t	capacity )

Borrow an exact event ring and enable the fixed capture channel.

Parameters

[in]	port	One privileged task owner, serialized with stop/read.
[in,out]	events	Aligned writable ring, capacity positive.
[in]	capacity	Number of events; no hidden buffer or worker.

Returns

SUCCESS transfers the ring borrow; rejection retains nothing.

Note

Ring remains borrowed until successful stop. ISR access is confined to this ring. Caller must not modify it or its provider while borrowed. Counter wrap is modulo the reported width; observation time is not an absolute edge timestamp or a clock accuracy qualification.

nx_timer_capture_state()

nx_result_t nx_timer_capture_state	(	const nx_timer_capture_t *	port,
		nx_timer_capture_state_t *	state )

Query counter units and observable queue/loss facts.

Parameters

[in]	port	Privileged task owner; no concurrent lifecycle writer.
[out]	state	Separate writable snapshot.

Returns

SUCCESS or INVALID/STATE/CONTEXT.

Note

Hardware overcapture and ring saturation can coalesce edges. A loss incident does not estimate edges, edge frequency or actual IRQ WCET.

nx_timer_capture_stop()

nx_result_t nx_timer_capture_stop

(

const nx_timer_capture_t *

port

)

Disable and read back channel/IRQ sources before returning storage.

Parameters

[in]

port

Privileged task owner, with generated IRQ owner retained.

Returns

SUCCESS is the final access to the ring; BUSY retains the borrow while queued events or failed hardware detachment remain.

Note

Read drains events after capture stops. Failed detach never frees storage. Board pins, timer clock and shared vector leases are released by cold assembly only after successful stop and publisher quiescence.