Clock Monitor

Clock Monitor Interface. More...

Topics
	CLOCK_MONITOR Driver Backend API

Files
file	clock_monitor.h
	Public Clock Monitor driver API.

Data Structures
struct	clock_monitor_window_cfg
	Configuration for CLOCK_MONITOR_MODE_WINDOW. More...
struct	clock_monitor_measure_cfg
	Configuration for CLOCK_MONITOR_MODE_MEASURE. More...
struct	clock_monitor_event_data
	Event payload delivered to the user callback. More...
struct	clock_monitor_config
	Top-level configuration handed to clock_monitor_configure. More...

Typedefs
typedef void(*	clock_monitor_callback_t) (const struct device *dev, const struct clock_monitor_event_data *evt, void *user_data)
	Callback invoked on clock monitor events.

Enumerations
enum	clock_monitor_mode { CLOCK_MONITOR_MODE_WINDOW = 1 , CLOCK_MONITOR_MODE_MEASURE }
	Operating mode of a clock monitor instance. More...
enum	{ CLOCK_MONITOR_EVT_FREQ_HIGH = BIT(0) , CLOCK_MONITOR_EVT_FREQ_LOW = BIT(1) , CLOCK_MONITOR_EVT_CLOCK_LOST = BIT(2) , CLOCK_MONITOR_EVT_MEASURE_DONE = BIT(3) }
	Clock monitor event flags, OR-combined into uint32_t masks. More...

Functions
int	clock_monitor_configure (const struct device *dev, const struct clock_monitor_config *cfg)
	Apply a monitor configuration.
int	clock_monitor_start (const struct device *dev)
	Start operation of the configured mode.
int	clock_monitor_stop (const struct device *dev)
	Stop the monitor.
int	clock_monitor_get_rate (const struct device *dev, uint32_t *rate_hz)
	Poll the most recent completed measurement.
int	clock_monitor_set_source (const struct device *dev, uint32_t reference, uint32_t target)
	Switch the reference / target clock inputs at runtime.

Detailed Description

Clock Monitor Interface.

Since

4.5

Version

0.1.0

Typedef Documentation

clock_monitor_callback_t

typedef void(* clock_monitor_callback_t) (const struct device *dev, const struct clock_monitor_event_data *evt, void *user_data)

#include <zephyr/drivers/clock_monitor.h>

Callback invoked on clock monitor events.

May be called in ISR context. Keep the callback short; defer heavy work to a thread / work queue.

Parameters

dev	Clock monitor device.
evt	Event payload. Lifetime ends when the callback returns.
user_data	Opaque pointer copied from clock_monitor_config.

Enumeration Type Documentation

anonymous enum

anonymous enum

#include <zephyr/drivers/clock_monitor.h>

Clock monitor event flags, OR-combined into uint32_t masks.

Enumerator
CLOCK_MONITOR_EVT_FREQ_HIGH	Monitored frequency exceeded the upper threshold.
CLOCK_MONITOR_EVT_FREQ_LOW	Monitored frequency fell below the lower threshold.
CLOCK_MONITOR_EVT_CLOCK_LOST	Monitored clock stopped or stuck.
CLOCK_MONITOR_EVT_MEASURE_DONE	Frequency measurement completed.

clock_monitor_mode

enum clock_monitor_mode

#include <zephyr/drivers/clock_monitor.h>

Operating mode of a clock monitor instance.

Value 0 is intentionally unnamed: a zero-initialized configuration is rejected by clock_monitor_configure with -ENOTSUP.

Enumerator
CLOCK_MONITOR_MODE_WINDOW	Continuous high/low threshold window check: the frequency of the monitored clock is continuously compared against programmable upper and lower bounds and events are raised when it leaves the window.
CLOCK_MONITOR_MODE_MEASURE	One frequency measurement per clock_monitor_start, reported in Hz through the configure-time callback. The device automatically returns to the configured (stopped) state before the completion callback runs; no clock_monitor_stop is needed on the happy path. To repeat the measurement, call clock_monitor_start again from the callback.

Function Documentation

clock_monitor_configure()

int clock_monitor_configure	(	const struct device *	dev,
		const struct clock_monitor_config *	cfg )

#include <zephyr/drivers/clock_monitor.h>

Apply a monitor configuration.

Must be called when the monitor is stopped. Installs cfg->callback (may be NULL) atomically with the rest of the configuration. Reconfiguration is done by calling this function again with a new mode/parameter set; there is no separate teardown operation.

Parameters

dev	Clock monitor device.
cfg	Configuration to apply.

Return values

0	success
-EINVAL	malformed configuration
-ENOTSUP	back-end does not support the requested mode
-EBUSY	monitor is running, or another configure() is in progress
-EIO	reference clock query failed or hardware init failed

clock_monitor_get_rate()

int clock_monitor_get_rate	(	const struct device *	dev,
		uint32_t *	rate_hz )

#include <zephyr/drivers/clock_monitor.h>

Poll the most recent completed measurement.

Returns the result of the most recent measurement completed since the last clock_monitor_configure. The value is retained: it is NOT cleared by reads, and reading has no hardware side effects. This is the polling alternative to the configure-time callback and works from user mode, where callbacks may not be installed.

Parameters

	dev	Device, configured in MEASURE mode.
[out]	rate_hz	Measured frequency in Hz. Written only on success.

Return values

0	*rate_hz holds the most recent measured value
-EAGAIN	measurement in flight, or none completed yet
-EIO	monitored clock lost (stuck) since configure()
-ENOSYS	back-end has no measurement hardware

clock_monitor_set_source()

int clock_monitor_set_source	(	const struct device *	dev,
		uint32_t	reference,
		uint32_t	target )

#include <zephyr/drivers/clock_monitor.h>

Switch the reference / target clock inputs at runtime.

The reference and target arguments are opaque back-end cookies. Each back-end exposes its accepted encodings through a dt-bindings header (e.g. <zephyr/dt-bindings/clock_monitor/<vendor>-<ip>.h>) so that devicetree properties and runtime calls share a single set of constants.

Parameters

dev	Clock monitor device.
reference	Reference clock cookie, or sentinel.
target	Target clock cookie, or sentinel.

Return values

0	success
-ENOTSUP	back-end's hardware cannot switch sources at runtime
-EINVAL	one or both cookies are unknown to this back-end
-EBUSY	monitor running or measurement in progress
-ENOSYS	back-end does not implement set_source()

clock_monitor_start()

int clock_monitor_start

(

const struct device *

dev

)

#include <zephyr/drivers/clock_monitor.h>

Start operation of the configured mode.

The device must already have been configured via clock_monitor_configure. The behavior follows the installed mode:

• CLOCK_MONITOR_MODE_WINDOW begins continuous threshold checking. Threshold crossings are delivered through the configure-time callback until clock_monitor_stop.
• CLOCK_MONITOR_MODE_MEASURE begins one measurement. The completion invokes the configure-time callback with CLOCK_MONITOR_EVT_MEASURE_DONE and the measured value in evt->measured_hz (or CLOCK_MONITOR_EVT_CLOCK_LOST with 0 if the monitored clock is stuck). The device automatically returns to the configured (stopped) state before the callback runs.

This function is ISR-safe and may be called from the event callback: repeating sampling is achieved by calling it again from the callback (the same idiom as re-arming a counter alarm from its callback).

The API provides no blocking wait or timeout for measurements: wait for the callback (e.g. on a semaphore it gives) with an application-chosen timeout, and call clock_monitor_stop to abort an in-flight measurement on the timeout path. Alternatively poll clock_monitor_get_rate.

Parameters

dev	Clock monitor device.

Return values

0	success
-EINVAL	device not configured
-EBUSY	already running

clock_monitor_stop()

int clock_monitor_stop

(

const struct device *

dev

)

#include <zephyr/drivers/clock_monitor.h>

Stop the monitor.

Returns the device to the configured (stopped) state and aborts any in-flight measurement. Idempotent: stopping an already-stopped device returns 0.

This function is ISR-safe and may be called from the event callback (a benign no-op there in MEASURE mode, where the auto-disarm has already stopped the device).

Parameters

dev	Clock monitor device.

Return values

0

success