This is an automated email from the ASF dual-hosted git repository. xiaoxiang781216 pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/nuttx.git
commit df579e2e48c60d9550dec48d998258e35deac0b9 Author: Alan Carvalho de Assis <[email protected]> AuthorDate: Sun Nov 15 09:48:11 2026 -0300 drivers/timers/fake_capture: Time stamp the edges with a simulated counter. The fake capture driver only toggles a flag from a watchdog, so it cannot be used to test drivers built on the edge time stamp operations, such as the PPS disciplined PTP clock. * The edges now happen at fixed times of perf_gettime(), used as the "true" time, instead of when the watchdog runs. * getcount() and getcapture() are implemented with a simulated free running counter of CONFIG_FAKE_CAPTURE_COUNTER_FREQ Hz with a frequency error (CONFIG_FAKE_CAPTURE_ERROR_PPB). The counter is latched at the time of the edge, plus a jitter (CONFIG_FAKE_CAPTURE_JITTER_NS), so the latency of the watchdog does not affect the time stamps. * fake_capture_create() creates an instance with another frequency and duty cycle, without registering it, for kernel drivers. * getedges() returns the number of edges instead of the signal level. * FAKE_CAPTURE depends on CAPTURE_NOTIFY, whose bind() and unbind() it uses, instead of the CAPTURE_NSIGNALS symbol, which does not exist. /dev/fake_capture0 and /dev/fake_capture1 still report 10 Hz with a 50% duty cycle. Signed-off-by: Alan C. Assis <[email protected]> Assisted-by: Claude Code:claude-opus-5-5 --- .../os/drivers/character/timers/capture.rst | 20 +- drivers/timers/Kconfig | 37 ++- drivers/timers/fake_capture.c | 327 ++++++++++++++++++--- include/nuttx/timers/capture.h | 21 +- 4 files changed, 351 insertions(+), 54 deletions(-) diff --git a/Documentation/os/drivers/character/timers/capture.rst b/Documentation/os/drivers/character/timers/capture.rst index 2e7e5cbadd6..f9f5ef10fce 100644 --- a/Documentation/os/drivers/character/timers/capture.rst +++ b/Documentation/os/drivers/character/timers/capture.rst @@ -162,7 +162,7 @@ depends on ``CONFIG_CAPTURE``. The ``CONFIG_FAKE_CAPTURE`` option enables a software-based fake capture driver that simulates a 10Hz square wave with 50% duty cycle. This is useful for development and testing without requiring actual hardware. -It depends on ``CONFIG_CAPTURE`` and ``CONFIG_CAPTURE_NSIGNALS > 0``. +It depends on ``CONFIG_CAPTURE_NOTIFY``. Without it, capture is still possible manually by including the appropriate header (e.g., ``arch/arm/src/stm32h7/stm32_capture.h``) and performing a @@ -371,8 +371,8 @@ operations: They are used by kernel drivers built on a capture lower half, such as the PPS disciplined PTP clock (``CONFIG_PTP_PPS``, see :doc:`/os/drivers/special/ptp`). The STM32 timer capture -(``arch/arm/src/common/stm32/stm32_capture_m3m4_v1_lowerhalf.c``) implements -them. +(``arch/arm/src/common/stm32/stm32_capture_m3m4_v1_lowerhalf.c``) and the fake +capture driver implement them. Fake Capture Driver ~~~~~~~~~~~~~~~~~~~ @@ -380,10 +380,19 @@ Fake Capture Driver The fake capture driver (``CONFIG_FAKE_CAPTURE``) provides: * Software simulation of capture events using watchdog timers -* Fixed 10Hz frequency with 50% duty cycle +* 10Hz frequency with 50% duty cycle * Edge toggles every 50ms (rising and falling) * Supports all standard capture operations including notifications +* Edge time stamps (``getcount()`` and ``getcapture()``) from a simulated + free running counter of ``CONFIG_FAKE_CAPTURE_COUNTER_FREQ`` Hz, with a + frequency error (``CONFIG_FAKE_CAPTURE_ERROR_PPB``) and a jitter + (``CONFIG_FAKE_CAPTURE_JITTER_NS``). The edges happen at fixed times of + ``perf_gettime()`` and the counter is latched at the edge, so the latency + of the watchdog does not affect the time stamps. * Available at ``/dev/fake_capture0``, ``/dev/fake_capture1``, etc. +* ``fake_capture_create()`` creates an instance with another frequency and + duty cycle without registering it, for a kernel driver such as the PPS + disciplined PTP clock (``CONFIG_PTP_PPS_FAKE``) * Useful for development, testing, and CI/CD without hardware * Platform-independent implementation * Automatically initialized at boot (2 channels by default) @@ -391,5 +400,6 @@ The fake capture driver (``CONFIG_FAKE_CAPTURE``) provides: Limitations: * Fixed timing parameters (not configurable at runtime) -* Software timing accuracy (not hardware-precise) +* Software timing accuracy (not hardware-precise); the time stamps are as good + as ``perf_gettime()`` * Suitable for functional testing, not timing precision validation diff --git a/drivers/timers/Kconfig b/drivers/timers/Kconfig index fae8a013df5..0e64828700d 100644 --- a/drivers/timers/Kconfig +++ b/drivers/timers/Kconfig @@ -129,9 +129,42 @@ config CAPTURE_NOTIFY config FAKE_CAPTURE bool "Fake Capture Driver" default n - depends on CAPTURE_NSIGNALS > 0 + depends on CAPTURE_NOTIFY + ---help--- + Enables a fake capture driver for testing purposes. It + simulates a 10 Hz square wave with a 50% duty cycle on + /dev/fake_capture0 and /dev/fake_capture1. Its edges are time + stamped by a simulated free running counter (getcount and + getcapture), derived from perf_gettime(), which is used as the + "true" time. perf_gettime() must have a good resolution for + the time stamps to be meaningful (it is in nanoseconds on the + simulator). + +if FAKE_CAPTURE + +config FAKE_CAPTURE_COUNTER_FREQ + int "Simulated counter frequency (Hz)" + default 100000000 + range 1000000 1000000000 + +config FAKE_CAPTURE_ERROR_PPB + int "Simulated counter frequency error (ppb)" + default 0 + range -400000 400000 ---help--- - Enables a fake capture driver for testing purposes. + Frequency error of the oscillator of the simulated counter, in + parts per billion, as a real crystal would have. + +config FAKE_CAPTURE_JITTER_NS + int "Simulated edge jitter (ns, peak)" + default 0 + range 0 1000000 + ---help--- + Uniformly distributed jitter added to the time stamp of every + simulated edge. Typical GNSS receivers have a PPS jitter of a + few nanoseconds to some tens of nanoseconds. + +endif # FAKE_CAPTURE endif # CAPTURE diff --git a/drivers/timers/fake_capture.c b/drivers/timers/fake_capture.c index 2a59108e794..f2eaaa89401 100644 --- a/drivers/timers/fake_capture.c +++ b/drivers/timers/fake_capture.c @@ -18,22 +18,32 @@ * ****************************************************************************/ +/* The simulated signal is a square wave whose edges happen at fixed times + * of perf_gettime(), used as the "true" time. Its edges are time stamped + * with a simulated free running counter that runs + * CONFIG_FAKE_CAPTURE_ERROR_PPB faster than its nominal frequency, like a + * real crystal would. As with a hardware input capture, the counter value + * is latched exactly at the edge (plus a configurable jitter) and reported + * later from a watchdog, so the latency of the watchdog does not affect + * the time stamps. + */ + /**************************************************************************** * Included Files ****************************************************************************/ #include <nuttx/config.h> +#include <stdio.h> +#include <errno.h> + +#include <nuttx/clock.h> +#include <nuttx/debug.h> #include <nuttx/kmalloc.h> #include <nuttx/spinlock.h> #include <nuttx/wdog.h> #include <nuttx/timers/capture.h> -#include <errno.h> -#include <stdlib.h> -#include <string.h> -#include <nuttx/debug.h> - /**************************************************************************** * Pre-processor Definitions ****************************************************************************/ @@ -41,6 +51,18 @@ #define CAPTURE_DUTY_DEFAULT 50 #define CAPTURE_FREQ_DEFAULT 10 +/* Actual frequency of the simulated counter, in mHz, integer Hz and mHz + * remainder. + */ + +#define CAPTURE_COUNT_MHZ \ + ((int64_t)CONFIG_FAKE_CAPTURE_COUNTER_FREQ * 1000 + \ + (int64_t)CONFIG_FAKE_CAPTURE_COUNTER_FREQ * \ + CONFIG_FAKE_CAPTURE_ERROR_PPB / 1000000) + +#define CAPTURE_COUNT_HZ (CAPTURE_COUNT_MHZ / 1000) +#define CAPTURE_COUNT_MILLI (CAPTURE_COUNT_MHZ % 1000) + /**************************************************************************** * Private Types ****************************************************************************/ @@ -50,10 +72,17 @@ struct fake_capture_s struct cap_lowerhalf_s lower; /* Lower half capture driver */ spinlock_t lock; /* For mutually exclusive access */ struct wdog_s wdog; /* For timing capture events */ - bool high; /* Current edge state */ capture_notify_t cb; /* Capture event callback function pointer */ FAR void *priv; /* Pointer to private data */ enum cap_type_e type; /* Edge type for the capture channel */ + uint32_t freq; /* Frequency of the signal (Hz) */ + uint8_t duty; /* Duty cycle of the signal (%) */ + int64_t period; /* Period of the signal (ns) */ + int64_t width; /* High time of the signal (ns) */ + int64_t edge; /* Number of the last edge */ + uint32_t edges; /* Number of edges since start */ + uint32_t capture; /* Counter latched by the last edge */ + uint32_t rand; /* Jitter pseudo random state */ }; /**************************************************************************** @@ -72,6 +101,10 @@ static int fake_capture_bind(FAR struct cap_lowerhalf_s *lower, enum cap_type_e type, capture_notify_t cb, FAR void *priv); static int fake_capture_unbind(FAR struct cap_lowerhalf_s *lower); +static int fake_capture_getcount(FAR struct cap_lowerhalf_s *lower, + FAR uint32_t *count); +static int fake_capture_getcapture(FAR struct cap_lowerhalf_s *lower, + FAR uint32_t *count); /**************************************************************************** * Private Data @@ -79,42 +112,161 @@ static int fake_capture_unbind(FAR struct cap_lowerhalf_s *lower); static const struct cap_ops_s g_fake_cap_ops = { - .start = fake_capture_start, - .stop = fake_capture_stop, - .getduty = fake_capture_getduty, - .getfreq = fake_capture_getfreq, - .getedges = fake_capture_getedges, - .bind = fake_capture_bind, - .unbind = fake_capture_unbind, + .start = fake_capture_start, + .stop = fake_capture_stop, + .getduty = fake_capture_getduty, + .getfreq = fake_capture_getfreq, + .getedges = fake_capture_getedges, + .bind = fake_capture_bind, + .unbind = fake_capture_unbind, + .getcount = fake_capture_getcount, + .getcapture = fake_capture_getcapture, }; /**************************************************************************** * Private Functions ****************************************************************************/ +/**************************************************************************** + * Name: fake_capture_now + * + * Description: + * The "true" time, in nanoseconds. + * + ****************************************************************************/ + +static inline int64_t fake_capture_now(void) +{ + struct timespec ts; + + perf_convert(perf_gettime(), &ts); + return (int64_t)ts.tv_sec * NSEC_PER_SEC + ts.tv_nsec; +} + +/**************************************************************************** + * Name: fake_capture_count + * + * Description: + * The value of the simulated counter at a given true time. + * + ****************************************************************************/ + +static inline int64_t fake_capture_count(int64_t ns) +{ + int64_t sec = ns / NSEC_PER_SEC; + int64_t nsec = ns % NSEC_PER_SEC; + + return sec * CAPTURE_COUNT_HZ + sec * CAPTURE_COUNT_MILLI / 1000 + + nsec * CAPTURE_COUNT_HZ / NSEC_PER_SEC; +} + +/**************************************************************************** + * Name: fake_capture_jitter + * + * Description: + * Uniform jitter in [-JITTER, +JITTER] ns, converted to counts. + * + ****************************************************************************/ + +static int64_t fake_capture_jitter(FAR struct fake_capture_s *capture) +{ +#if CONFIG_FAKE_CAPTURE_JITTER_NS > 0 + int64_t ns; + + capture->rand = capture->rand * 1664525u + 1013904223u; + ns = (capture->rand >> 8) % (2 * CONFIG_FAKE_CAPTURE_JITTER_NS + 1); + ns -= CONFIG_FAKE_CAPTURE_JITTER_NS; + return ns * CAPTURE_COUNT_HZ / NSEC_PER_SEC; +#else + UNUSED(capture); + return 0; +#endif +} + +/**************************************************************************** + * Name: fake_capture_edge + * + * Description: + * The number of the last edge at or before a true time. The even edges + * are rising and the odd edges are falling. + * + ****************************************************************************/ + +static inline int64_t fake_capture_edge(FAR struct fake_capture_s *capture, + int64_t ns) +{ + int64_t period = ns / capture->period; + + return 2 * period + (ns - period * capture->period >= capture->width); +} + +/**************************************************************************** + * Name: fake_capture_time + * + * Description: + * The true time of an edge, in nanoseconds. + * + ****************************************************************************/ + +static inline int64_t fake_capture_time(FAR struct fake_capture_s *capture, + int64_t edge) +{ + return edge / 2 * capture->period + (edge & 1 ? capture->width : 0); +} + +/**************************************************************************** + * Name: fake_capture_schedule + * + * Description: + * Start the watchdog for the edge that follows the last one. One more + * tick makes sure that the watchdog does not expire before the edge. + * + ****************************************************************************/ + +static void fake_capture_isr(wdparm_t arg); + +static void fake_capture_schedule(FAR struct fake_capture_s *capture, + int64_t now) +{ + int64_t delay = fake_capture_time(capture, capture->edge + 1) - now; + + wd_start(&capture->wdog, NSEC2TICK(delay) + 1, fake_capture_isr, + (wdparm_t)capture); +} + static void fake_capture_isr(wdparm_t arg) { FAR struct fake_capture_s *capture = (FAR struct fake_capture_s *)arg; + int64_t now = fake_capture_now(); + int64_t edge = fake_capture_edge(capture, now); irqstate_t flags; - bool last; + bool rising; flags = spin_lock_irqsave(&capture->lock); - last = capture->high; - capture->high = !capture->high; - - if (capture->cb != NULL && - (capture->type == CAP_TYPE_BOTH || - (capture->type == CAP_TYPE_RISING && !last) || - (capture->type == CAP_TYPE_FALLING && last))) + if (edge != capture->edge) { - capture->cb(&capture->lower, capture->priv); + /* Latch the counter at the time of the edge, as the hardware does */ + + capture->edges += edge - capture->edge; + capture->edge = edge; + capture->capture = fake_capture_count(fake_capture_time(capture, + edge)) + + fake_capture_jitter(capture); + + rising = (edge & 1) == 0; + if (capture->cb != NULL && + (capture->type == CAP_TYPE_BOTH || + (capture->type == CAP_TYPE_RISING && rising) || + (capture->type == CAP_TYPE_FALLING && !rising))) + { + capture->cb(&capture->lower, capture->priv); + } } spin_unlock_irqrestore(&capture->lock, flags); - wd_start_next(&capture->wdog, MSEC2TICK(1000 / CAPTURE_FREQ_DEFAULT), - fake_capture_isr, (wdparm_t)capture); + fake_capture_schedule(capture, now); } /**************************************************************************** @@ -137,9 +289,17 @@ static void fake_capture_isr(wdparm_t arg) static int fake_capture_start(FAR struct cap_lowerhalf_s *lower) { FAR struct fake_capture_s *capture = (FAR struct fake_capture_s *)lower; + int64_t now = fake_capture_now(); + irqstate_t flags; + + flags = spin_lock_irqsave(&capture->lock); - wd_start(&capture->wdog, MSEC2TICK(1000 / CAPTURE_FREQ_DEFAULT), - fake_capture_isr, (wdparm_t)capture); + capture->edge = fake_capture_edge(capture, now); + capture->edges = 0; + + spin_unlock_irqrestore(&capture->lock, flags); + + fake_capture_schedule(capture, now); return OK; } @@ -185,8 +345,9 @@ static int fake_capture_stop(FAR struct cap_lowerhalf_s *lower) static int fake_capture_getduty(FAR struct cap_lowerhalf_s *lower, FAR uint8_t *duty) { - *duty = CAPTURE_DUTY_DEFAULT; + FAR struct fake_capture_s *capture = (FAR struct fake_capture_s *)lower; + *duty = capture->duty; return OK; } @@ -199,7 +360,7 @@ static int fake_capture_getduty(FAR struct cap_lowerhalf_s *lower, * * Input Parameters: * lower - Pointer to the capture channel lower-half data structure. - * duty - uint8_t pointer where the frequency value is written. + * freq - uint32_t pointer where the frequency value is written. * * Returned Value: * Returns OK on success. @@ -209,8 +370,9 @@ static int fake_capture_getduty(FAR struct cap_lowerhalf_s *lower, static int fake_capture_getfreq(FAR struct cap_lowerhalf_s *lower, FAR uint32_t *freq) { - *freq = CAPTURE_FREQ_DEFAULT; + FAR struct fake_capture_s *capture = (FAR struct fake_capture_s *)lower; + *freq = capture->freq; return OK; } @@ -219,11 +381,11 @@ static int fake_capture_getfreq(FAR struct cap_lowerhalf_s *lower, * * Description: * This function is a requirement of the upper-half driver. Returns - * the current edge type configured for the capture channel. + * the number of edges since the capture was started. * * Input Parameters: * lower - Pointer to the capture channel lower-half data structure. - * type - Pointer to the edge type variable to be updated. + * edges - uint32_t pointer where the number of edges is written. * * Returned Value: * Returns OK on success. @@ -234,11 +396,8 @@ static int fake_capture_getedges(FAR struct cap_lowerhalf_s *lower, FAR uint32_t *edges) { FAR struct fake_capture_s *capture = (FAR struct fake_capture_s *)lower; - irqstate_t flags = spin_lock_irqsave(&capture->lock); - *edges = capture->high; - - spin_unlock_irqrestore(&capture->lock, flags); + *edges = capture->edges; return OK; } @@ -251,9 +410,9 @@ static int fake_capture_getedges(FAR struct cap_lowerhalf_s *lower, * * Input Parameters: * lower - Pointer to the capture channel lower-half data structure. + * type - The edge type that will trigger the callback. * cb - The callback function pointer. * priv - The private argument to be passed to the callback function. - * edge - The edge type that will trigger the callback. * * Returned Value: * Returns OK on success. @@ -272,7 +431,7 @@ static int fake_capture_bind(FAR struct cap_lowerhalf_s *lower, capture->type = type; spin_unlock_irqrestore(&capture->lock, flags); - return 0; + return OK; } /**************************************************************************** @@ -299,13 +458,87 @@ static int fake_capture_unbind(FAR struct cap_lowerhalf_s *lower) capture->priv = NULL; spin_unlock_irqrestore(&capture->lock, flags); - return 0; + return OK; +} + +/**************************************************************************** + * Name: fake_capture_getcount + * + * Description: + * Return the current value of the simulated counter. + * + ****************************************************************************/ + +static int fake_capture_getcount(FAR struct cap_lowerhalf_s *lower, + FAR uint32_t *count) +{ + *count = fake_capture_count(fake_capture_now()); + return OK; +} + +/**************************************************************************** + * Name: fake_capture_getcapture + * + * Description: + * Return the value of the simulated counter latched by the last edge. + * It is called from the notification callback, with the lock held. + * + ****************************************************************************/ + +static int fake_capture_getcapture(FAR struct cap_lowerhalf_s *lower, + FAR uint32_t *count) +{ + FAR struct fake_capture_s *capture = (FAR struct fake_capture_s *)lower; + + *count = capture->capture; + return OK; } /**************************************************************************** * Public Functions ****************************************************************************/ +/**************************************************************************** + * Name: fake_capture_create + * + * Description: + * Create a fake capture lower half, without registering it. + * + * Input Parameters: + * freq - The frequency of the simulated signal, in Hz. + * duty - The duty cycle of the simulated signal, in percent. + * + * Returned Value: + * The new lower half on success; NULL on failure. + * + ****************************************************************************/ + +FAR struct cap_lowerhalf_s *fake_capture_create(uint32_t freq, uint8_t duty) +{ + FAR struct fake_capture_s *capture; + + if (freq == 0 || freq > NSEC_PER_SEC / 2 || duty == 0 || duty >= 100) + { + return NULL; + } + + capture = kmm_zalloc(sizeof(*capture)); + if (capture == NULL) + { + return NULL; + } + + spin_lock_init(&capture->lock); + capture->lower.ops = &g_fake_cap_ops; + capture->freq = freq; + capture->duty = duty; + capture->period = NSEC_PER_SEC / freq; + capture->width = capture->period * duty / 100; + capture->rand = 0x2545f491; + + return &capture->lower; +} + /**************************************************************************** * Name: fake_capture_initialize * @@ -314,7 +547,7 @@ static int fake_capture_unbind(FAR struct cap_lowerhalf_s *lower) * fake capture. * * Input Parameters: - * channel - The capture channel number to initialize. + * channels - The number of capture channels to initialize. * * Returned Value: * Zero (OK) on success; a negated errno value on failure. The following @@ -331,19 +564,21 @@ int fake_capture_initialize(int channels) for (i = 0; i < channels; i++) { - FAR struct fake_capture_s *priv; + FAR struct cap_lowerhalf_s *lower; - priv = kmm_zalloc(sizeof(*priv)); - DEBUGASSERT(priv); + lower = fake_capture_create(CAPTURE_FREQ_DEFAULT, + CAPTURE_DUTY_DEFAULT); + if (lower == NULL) + { + return -ENOMEM; + } - spin_lock_init(&priv->lock); - priv->lower.ops = &g_fake_cap_ops; snprintf(path, sizeof(path), "/dev/fake_capture%d", i); - ret = cap_register(path, &priv->lower); + ret = cap_register(path, lower); if (ret < 0) { cperr("Failed to register capture:%d\n", ret); - kmm_free(priv); + kmm_free(lower); break; } } diff --git a/include/nuttx/timers/capture.h b/include/nuttx/timers/capture.h index b9d620ebaa2..1f5549e7763 100644 --- a/include/nuttx/timers/capture.h +++ b/include/nuttx/timers/capture.h @@ -349,6 +349,26 @@ int cap_register(FAR const char *devpath, int cap_register_multiple(FAR const char *devpath, FAR struct cap_lowerhalf_s **lower, int n); +#ifdef CONFIG_FAKE_CAPTURE +/**************************************************************************** + * Name: fake_capture_create + * + * Description: + * Create a fake capture lower half, without registering it. It + * simulates a square wave whose edges are time stamped by a simulated + * free running counter of CONFIG_FAKE_CAPTURE_COUNTER_FREQ Hz. + * + * Input Parameters: + * freq - The frequency of the simulated signal, in Hz. + * duty - The duty cycle of the simulated signal, in percent (1-99). + * + * Returned Value: + * The new lower half on success; NULL on failure. + * + ****************************************************************************/ + +FAR struct cap_lowerhalf_s *fake_capture_create(uint32_t freq, uint8_t duty); + /**************************************************************************** * Name: fake_capture_initialize * @@ -366,7 +386,6 @@ int cap_register_multiple(FAR const char *devpath, * ****************************************************************************/ -#ifdef CONFIG_FAKE_CAPTURE int fake_capture_initialize(int channels); #endif
