adc.h File Reference

Reviewed ADC single-shot and low-rate polling scans. More...

#include "nexus/core/time.h"
#include "nexus/io/adc_observer.h"
#include "nexus/io/stream.h"
#include "nexus/io/wake.h"

Go to the source code of this file.

Data Structures
struct	nx_adc_info_t
	Raw count facts; nominal Vref is not a calibrated physical measurement. More...
struct	nx_adc_sequence_info_t
	Immutable complete-scan timing facts for the selected mode. More...
struct	nx_adc_ops_t
	Shared read-only methods using one provider state. More...
struct	nx_adc_port
	Immutable interface pointing to caller-owned state. More...

Typedefs
typedef struct nx_adc_port	nx_adc_port_t

Functions
nx_result_t	nx_adc_port_info (const nx_adc_port_t *port, nx_adc_info_t *info)
	Query the fixed reviewed ADC sequence and raw-count format.
nx_result_t	nx_adc_port_sequence_info (const nx_adc_port_t *port, nx_adc_sequence_info_t *info)
	Read fixed channel order and complete-scan timing facts.
nx_result_t	nx_adc_port_attach_observer (const nx_adc_port_t *port, nx_adc_observer_t *observer)
	Attach optional observer storage before acquisition starts.
nx_result_t	nx_adc_port_block_observation (const nx_adc_port_t *port, const nx_stream_block_t *block, nx_adc_observation_t *observation)
	Query one live consumer loan's software completion record.
nx_result_t	nx_adc_port_sample (const nx_adc_port_t *port, uint16_t *samples, size_t capacity, nx_time_us_t deadline, size_t *count)
	Sample the fixed single/scan sequence by bounded polling.
nx_result_t	nx_adc_port_stream_start (const nx_adc_port_t *port, nx_stream_t *stream, uint32_t trigger_hz)
	Start selected trigger/block acquisition with caller storage.
nx_result_t	nx_adc_port_stream_stop (const nx_adc_port_t *port)
	Stop trigger and memory sources without revoking consumer loans.
nx_result_t	nx_adc_port_stream_service (const nx_adc_port_t *port)
	Explicitly resume discrete block acquisition after consumer drain.
nx_result_t	nx_adc_port_attach_wake (const nx_adc_port_t *port, const nx_irq_wake_t *wake, uint8_t syscall_ceiling)
	Attach an optional hint sink after checking publisher IRQ priority.

Detailed Description

Reviewed ADC single-shot and low-rate polling scans.

Author

Nexus Team

Definition in file adc.h.

Typedef Documentation

nx_adc_port_t

typedef struct nx_adc_port nx_adc_port_t

Definition at line 18 of file adc.h.

Function Documentation

nx_adc_port_attach_observer()

nx_result_t nx_adc_port_attach_observer	(	const nx_adc_port_t *	port,
		nx_adc_observer_t *	observer )

Attach optional observer storage before acquisition starts.

Parameters

[in]	port	Initialized continuous provider, one task owner.
[in,out]	observer	Initialized stable caller storage, or NULL to detach. Provider validates exact stream count at start.

Returns

Success or BUSY/CONTEXT/UNSUPPORTED.

Note

Stop and join before detach/reclaim. No hidden allocation; polling and finite modes need no observation storage.

nx_adc_port_attach_wake()

nx_result_t nx_adc_port_attach_wake	(	const nx_adc_port_t *	port,
		const nx_irq_wake_t *	wake,
		uint8_t	syscall_ceiling )

Attach an optional hint sink after checking publisher IRQ priority.

Parameters

[in]	port	Initialized block-capable provider, one 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 or CONTEXT/STATE/PERMISSION/UNSUPPORTED.

Note

Block/error predicates latch before notifications. Stop and join publishers and waiters before reclaiming old sink storage.

nx_adc_port_block_observation()

nx_result_t nx_adc_port_block_observation	(	const nx_adc_port_t *	port,
		const nx_stream_block_t *	block,
		nx_adc_observation_t *	observation )

Query one live consumer loan's software completion record.

Parameters

[in]	port	Same stable observer-capable provider.
[in]	block	Same stream's currently acquired immutable block.
[out]	observation	Copied epoch, ordinal, observed time and gap flag. This is never a hardware sample aperture timestamp.

Returns

Success or INVALID/STATE/UNSUPPORTED, output unchanged on rejection.

nx_adc_port_info()

nx_result_t nx_adc_port_info	(	const nx_adc_port_t *	port,
		nx_adc_info_t *	info )

Query the fixed reviewed ADC sequence and raw-count format.

Parameters

[in]	port	Single-shot/low-rate scan provider.
[out]	info	Resolution, declared reference and sequence length.

Returns

Success or INVALID.

nx_adc_port_sample()

nx_result_t nx_adc_port_sample	(	const nx_adc_port_t *	port,
		uint16_t *	samples,
		size_t	capacity,
		nx_time_us_t	deadline,
		size_t *	count )

Sample the fixed single/scan sequence by bounded polling.

Parameters

[in,out]	port	Single execution owner; fixed channel/sample-time setup.
[out]	samples	Raw counts in configured channel order.
[in]	capacity	Sample capacity at least channel_count.
[in]	deadline	Absolute clock-domain deadline.
[out]	count	Complete valid samples; remaining output is untouched.

Returns

Success or INVALID/BUSY/TIMEOUT/IO; abort/drain completes before return. No retained buffer, DMA/trigger/stream promise.

Note

CPU-active task-only acquisition. Reference voltage, sampling error and maximum rate need physical qualification.

nx_adc_port_sequence_info()

nx_result_t nx_adc_port_sequence_info	(	const nx_adc_port_t *	port,
		nx_adc_sequence_info_t *	info )

Read fixed channel order and complete-scan timing facts.

Parameters

[in]	port	Initialized timing-capable provider.
[out]	info	Cold read-only facts; no acquisition starts.

Returns

Success or INVALID/STATE/UNSUPPORTED.

nx_adc_port_stream_service()

nx_result_t nx_adc_port_stream_service

(

const nx_adc_port_t *

port

)

Explicitly resume discrete block acquisition after consumer drain.

Parameters

[in]

port

Same single task executor as start and stop.

Returns

Success when an engine is armed, BUSY during source drain or free-block backpressure, STATE after acquisition stops.

Note

No task, retry or hidden rearm is created. Block modes state their trigger gaps; continuous zero-gap capture requires a separately declared hardware capability and qualification.

nx_adc_port_stream_start()

nx_result_t nx_adc_port_stream_start	(	const nx_adc_port_t *	port,
		nx_stream_t *	stream,
		uint32_t	trigger_hz )

Start selected trigger/block acquisition with caller storage.

Parameters

[in]	port	Trigger/block-capable provider, one task executor.
[in,out]	stream	Initialized immutable-consumer block mechanism.
[in]	trigger_hz	Positive requested complete-scan rate; provider rejects rates outside its declared timer/ADC capability.

Returns

Success or INVALID/BUSY/UNSUPPORTED before buffer admission.

Note

Blocks contain native uint16_t raw counts in channel order. Capacities and lengths are multiples of a complete scan; DMA domains/alignment and physical rate require separate evidence.

nx_adc_port_stream_stop()

nx_result_t nx_adc_port_stream_stop

(

const nx_adc_port_t *

port

)

Stop trigger and memory sources without revoking consumer loans.

Parameters

[in]

port

Same acquisition executor; retain storage on BUSY.

Returns

Success proves source detach, BUSY retains producer storage, UNSUPPORTED for a polling-only provider.

Note

Consumer READY/BORROWED blocks must still be drained/released.