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 fab58bc86049e9452dddcff525420ad0dfd2abfe Author: Alan Carvalho de Assis <[email protected]> AuthorDate: Sat Nov 14 18:34:21 2026 -0300 drivers/timers: Add PPS disciplined software PTP clock. Add CONFIG_PTP_PPS, a PTP clock (/dev/ptpX) built on a capture lower half (struct cap_lowerhalf_s) with a free running 32-bit counter. With the PPS output of a GNSS receiver on the capture input, the gnsspps application disciplines the clock so that boards share GNSS time. The time is base_ns + ((cnt - base_cnt) * mult + base_frac) >> shift, where cnt is read with getcount(): * shift keeps mult below 2^31, which gives a frequency resolution better than 1 ppb, and base_frac keeps the conversion exact. * adjfine() re-bases before it changes mult, so frequency changes are phase continuous. * A watchdog re-bases every 2^30 counts, so the conversion never overflows, even without PPS. The capture channel is the external time stamp input 0. Enabling it binds a notification callback for the requested edges; the callback reads the counter latched by the hardware with getcapture() and queues the EXTTS event, so the interrupt latency does not change the time stamp. The board calls ptp_pps_register() with the lower half and the counter frequency. CONFIG_PTP_PPS depends on CONFIG_CAPTURE_NOTIFY. CONFIG_PTP_PPS_FAKE registers the clock on a 1 Hz fake capture, whose simulated counter has a frequency error and whose simulated PPS has a jitter, to test the complete chain on the simulator. Assisted-by: Claude Code:claude-opus-5-5 Signed-off-by: Alan Carvalho de Assis <[email protected]> --- Documentation/os/drivers/special/ptp.rst | 63 ++++ drivers/drivers_initialize.c | 7 + drivers/timers/CMakeLists.txt | 4 + drivers/timers/Kconfig | 55 +++ drivers/timers/Make.defs | 6 + drivers/timers/ptp_pps.c | 615 +++++++++++++++++++++++++++++++ include/nuttx/timers/ptp_pps.h | 97 +++++ 7 files changed, 847 insertions(+) diff --git a/Documentation/os/drivers/special/ptp.rst b/Documentation/os/drivers/special/ptp.rst index 4c5ad27a209..d1c3658db6f 100644 --- a/Documentation/os/drivers/special/ptp.rst +++ b/Documentation/os/drivers/special/ptp.rst @@ -126,6 +126,10 @@ The PTP clock framework can be enabled with the following Kconfig options: ``CONFIG_PTP_CLOCK_NPOLLWAITERS`` Number of threads that can ``poll()`` one device at the same time. +``CONFIG_PTP_PPS`` + PPS disciplined software PTP clock, see + `PPS Disciplined Software Clock`_ below. + Device Interface ================ @@ -472,6 +476,65 @@ Time Offset Adjustment return 0; } +PPS Disciplined Software Clock +============================== + +``CONFIG_PTP_PPS`` (``drivers/timers/ptp_pps.c``) builds a PTP clock on top +of a capture lower half (``struct cap_lowerhalf_s``, see +:doc:`/os/drivers/character/timers/capture`) whose free running 32-bit +counter latches the edges of its input in hardware, typically a timer input +capture channel. Its main use is to synchronize boards to GNSS time: the PPS +output of a GNSS receiver goes to the capture input, the ``gnsspps`` +application reads the EXTTS events and disciplines the clock. See +:doc:`/applications/system/gnsspps/index`. + +The time is a linear function of the counter, +``t = base_ns + ((cnt - base_cnt) * mult + base_frac) >> shift``, where +``shift`` is chosen so that ``mult`` stays below 2\ :sup:`31`. This gives a +frequency resolution better than 1 ppb for any counter frequency, an exact +conversion (the remainder is kept in ``base_frac``) and phase continuous +frequency changes. A watchdog re-bases the clock every 2\ :sup:`30` counter +periods so the conversion never overflows, even without PPS. + +The board registers the clock on a capture lower half: + +.. code-block:: c + + int ptp_pps_register(FAR struct cap_lowerhalf_s *lower, uint32_t freq, + int devno); + +``freq`` is the frequency of the counter of the lower half. Besides +``start`` and ``stop``, the lower half must implement these operations of +``struct cap_ops_s`` (``bind`` and ``unbind`` need +``CONFIG_CAPTURE_NOTIFY``): + +``getcount`` + Read the free running counter. It must count up and wrap around from + ``0xffffffff`` to 0. ``clock_gettime()`` converts it to the time of the + clock. +``bind`` / ``unbind`` + The EXTTS input 0 of the clock is the capture channel. Enabling it with + ``PTP_EXTTS_REQUEST`` binds a notification callback for the requested + edges. +``getcapture`` + Called from the notification callback, it returns the counter value + latched by the hardware on the edge, which is converted to the time of the + clock and queued as a ``struct ptp_extts_event``. Because the counter is + latched by hardware, the interrupt latency does not affect the time stamp; + the callback only has to run within 2\ :sup:`31` counter periods. + +Existing lower halves: + +- The STM32 timer capture (``CONFIG_STM32_TIMx_CAP``, + ``arch/arm/src/common/stm32/stm32_capture_m3m4_v1_lowerhalf.c``) with a + 32-bit timer, TIM2 or TIM5, at the full timer clock + (``CONFIG_STM32_TIMx_CLOCK``). See ``stm32f4discovery:gnsspps``. +- The fake capture driver (``CONFIG_FAKE_CAPTURE``, + ``drivers/timers/fake_capture.c``), whose simulated counter has a + configurable frequency error and whose simulated PPS has a configurable + jitter. ``CONFIG_PTP_PPS_FAKE`` registers a clock on it, to test the + complete chain on the simulator. + Implementing a Lower-Half Driver ================================= diff --git a/drivers/drivers_initialize.c b/drivers/drivers_initialize.c index 5be91008817..d3d5bf639e9 100644 --- a/drivers/drivers_initialize.c +++ b/drivers/drivers_initialize.c @@ -56,6 +56,7 @@ #include <nuttx/syslog/syslog_console.h> #include <nuttx/thermal.h> #include <nuttx/timers/ptp_clock_dummy.h> +#include <nuttx/timers/ptp_pps.h> #include <nuttx/timers/capture.h> #include <nuttx/trace.h> #include <nuttx/usrsock/usrsock_rpmsg.h> @@ -341,6 +342,12 @@ void drivers_initialize(void) fake_capture_initialize(2); #endif +#ifdef CONFIG_PTP_PPS_FAKE + ptp_pps_register(fake_capture_create(1, 10), + CONFIG_FAKE_CAPTURE_COUNTER_FREQ, + CONFIG_PTP_PPS_FAKE_DEVNO); +#endif + #ifdef CONFIG_DMABUF_HEAPS dmabuf_system_heap_create(); #endif diff --git a/drivers/timers/CMakeLists.txt b/drivers/timers/CMakeLists.txt index c9096ca79d1..5ffb15f31b6 100644 --- a/drivers/timers/CMakeLists.txt +++ b/drivers/timers/CMakeLists.txt @@ -150,4 +150,8 @@ if(CONFIG_PTP_CLOCK_DUMMY) list(APPEND SRCS ptp_clock_dummy.c) endif() +if(CONFIG_PTP_PPS) + list(APPEND SRCS ptp_pps.c) +endif() + target_sources(drivers PRIVATE ${SRCS}) diff --git a/drivers/timers/Kconfig b/drivers/timers/Kconfig index 0e64828700d..7caa450c75a 100644 --- a/drivers/timers/Kconfig +++ b/drivers/timers/Kconfig @@ -881,4 +881,59 @@ config PTP_CLOCK_DUMMY ---help--- The dummy test driver. +config PTP_PPS + bool "PPS disciplined software PTP clock" + default n + depends on CAPTURE_NOTIFY + select PTP_CLOCK + ---help--- + A PTP hardware clock (/dev/ptpX) built on top of a capture + lower half (struct cap_lowerhalf_s) whose free running 32-bit + counter latches the edges of its input in hardware, for + example a timer input capture channel connected to the PPS + output of a GNSS receiver. + + The clock is read, stepped and frequency adjusted through the + standard clock_gettime(), clock_settime() and clock_adjtime() + interfaces, and the captured edges are delivered to the + application as struct ptp_extts_event records read from + /dev/ptpX. The gnsspps application in nuttx-apps uses them + to discipline the clock to GNSS time, so that boards that + each have a GNSS receiver share the same time scale. + + The capture lower half must implement the getcount, + getcapture, bind and unbind operations, and the board calls + ptp_pps_register() with it. + +if PTP_PPS + +config PTP_PPS_MAX_ADJ + int "Maximum frequency adjustment (ppb)" + default 500000 + range 1000 10000000 + ---help--- + Largest frequency correction, in parts per billion, that the + clock accepts through clock_adjtime(ADJ_FREQUENCY). It must + cover the tolerance of the oscillator that drives the + counter. The default of 500 ppm covers any crystal. + +config PTP_PPS_FAKE + bool "PPS disciplined clock on a fake capture" + default n + depends on FAKE_CAPTURE + ---help--- + Register a PPS disciplined clock on a fake capture lower half + (see FAKE_CAPTURE) that simulates a 1 Hz PPS. Set the + frequency error of its counter and the jitter of the PPS with + FAKE_CAPTURE_ERROR_PPB and FAKE_CAPTURE_JITTER_NS, so that the + complete chain (driver, EXTTS events and the gnsspps servo) can + be tested on the simulator without any hardware. + +config PTP_PPS_FAKE_DEVNO + int "Device number (/dev/ptpX)" + default 0 + depends on PTP_PPS_FAKE + +endif # PTP_PPS + endmenu # Timer Driver Support diff --git a/drivers/timers/Make.defs b/drivers/timers/Make.defs index 14d098bc4e6..4c3d3212ccc 100644 --- a/drivers/timers/Make.defs +++ b/drivers/timers/Make.defs @@ -207,6 +207,12 @@ ifeq ($(CONFIG_PTP_CLOCK_DUMMY),y) TMRVPATH = :timers endif +ifeq ($(CONFIG_PTP_PPS),y) + CSRCS += ptp_pps.c + TMRDEPPATH = --dep-path timers + TMRVPATH = :timers +endif + # Include timer build support (if any were selected) DEPPATH += $(TMRDEPPATH) diff --git a/drivers/timers/ptp_pps.c b/drivers/timers/ptp_pps.c new file mode 100644 index 00000000000..3dedfb8be61 --- /dev/null +++ b/drivers/timers/ptp_pps.c @@ -0,0 +1,615 @@ +/**************************************************************************** + * drivers/timers/ptp_pps.c + * + * SPDX-License-Identifier: Apache-2.0 + * + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. The + * ASF licenses this file to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance with the + * License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + * License for the specific language governing permissions and limitations + * under the License. + * + ****************************************************************************/ + +/* PPS disciplined software PTP clock. + * + * The clock is built on a capture lower half (struct cap_lowerhalf_s) + * whose free running 32-bit counter is read with getcount(). The time of + * the clock is a linear function of the counter: + * + * t(cnt) = base_ns + ((cnt - base_cnt) * mult + base_frac) >> shift + * + * mult is the length of one counter period in units of 2^-shift ns. shift + * is chosen so that mult is just below 2^31, which gives a frequency + * resolution of better than 1 ppb for any counter frequency and keeps the + * 32x32 bit product within 64 bits. The remainder of the conversion is + * kept in base_frac, so no time is lost when the clock is re-based. + * + * Frequency changes re-base the clock first, so they are phase + * continuous. A watchdog re-bases the clock periodically so that the + * counter difference never exceeds 2^30, whatever the counter frequency. + * + * The capture channel is the external time stamp (EXTTS) input 0: the + * capture notification callback reads the counter value latched by the + * hardware on the edge with getcapture(), converts it to the time of the + * clock and queues it as a struct ptp_extts_event. + */ + +/**************************************************************************** + * Included Files + ****************************************************************************/ + +#include <nuttx/config.h> + +#include <sys/types.h> +#include <inttypes.h> +#include <stdint.h> +#include <assert.h> +#include <errno.h> + +#include <nuttx/clock.h> +#include <nuttx/debug.h> +#include <nuttx/irq.h> +#include <nuttx/kmalloc.h> +#include <nuttx/lib/math32.h> +#include <nuttx/spinlock.h> +#include <nuttx/wdog.h> +#include <nuttx/timers/capture.h> +#include <nuttx/timers/ptp_clock.h> +#include <nuttx/timers/ptp_pps.h> + +/**************************************************************************** + * Pre-processor Definitions + ****************************************************************************/ + +/* The clock is re-based at least every 2^30 counter periods, a quarter of + * the wrap around period of the counter. + */ + +#define PTP_PPS_REBASE_COUNTS (UINT32_C(1) << 30) + +/* Largest mult, leaves room for any frequency adjustment up to 100% */ + +#define PTP_PPS_MULT_MAX UINT32_C(0x7fffffff) + +/* Counter differences at or above this value are before the time base */ + +#define PTP_PPS_DIFF_NEG (UINT32_C(1) << 31) + +/**************************************************************************** + * Private Types + ****************************************************************************/ + +struct ptp_pps_s +{ + struct ptp_lowerhalf_s ptp; /* Must be first */ + FAR struct cap_lowerhalf_s *lower; /* Counter and capture input */ + spinlock_t lock; /* Protects the time base */ + struct wdog_s wdog; /* Periodic re-base */ + clock_t period; /* Re-base period, in ticks */ + uint32_t freq; /* Nominal counter frequency (Hz) */ + unsigned int edges; /* Edge reported in EXTTS events */ + + /* Time base, see the description at the top of the file */ + + int64_t base_ns; + uint32_t base_cnt; + uint32_t base_frac; + uint32_t mult; + uint32_t mult_nom; + uint8_t shift; +}; + +/**************************************************************************** + * Private Function Prototypes + ****************************************************************************/ + +static int ptp_pps_adjfine(FAR struct ptp_lowerhalf_s *lower, long ppb); +static int ptp_pps_adjtime(FAR struct ptp_lowerhalf_s *lower, + int64_t delta); +static int ptp_pps_gettime(FAR struct ptp_lowerhalf_s *lower, + FAR struct timespec *ts, + FAR struct ptp_system_timestamp *sts); +static int ptp_pps_getcrosststamp(FAR struct ptp_lowerhalf_s *lower, + FAR struct system_device_crosststamp *cts); +static int ptp_pps_settime(FAR struct ptp_lowerhalf_s *lower, + FAR const struct timespec *ts); +static int ptp_pps_getres(FAR struct ptp_lowerhalf_s *lower, + FAR struct timespec *res); +static int ptp_pps_enable(FAR struct ptp_lowerhalf_s *lower, + FAR struct ptp_clock_request *rq, bool on); + +/**************************************************************************** + * Private Data + ****************************************************************************/ + +static const struct ptp_ops_s g_ptp_pps_ops = +{ + ptp_pps_adjfine, /* adjfine */ + NULL, /* adjphase */ + ptp_pps_adjtime, /* adjtime */ + ptp_pps_gettime, /* gettime */ + ptp_pps_getcrosststamp, /* getcrosststamp */ + ptp_pps_settime, /* settime */ + ptp_pps_getres, /* getres */ + NULL, /* control */ + ptp_pps_enable, /* enable */ +}; + +/**************************************************************************** + * Private Functions + ****************************************************************************/ + +/**************************************************************************** + * Name: ptp_pps_ns2ts + ****************************************************************************/ + +static inline void ptp_pps_ns2ts(int64_t ns, FAR struct timespec *ts) +{ + ts->tv_sec = ns / NSEC_PER_SEC; + ts->tv_nsec = ns % NSEC_PER_SEC; + + if (ts->tv_nsec < 0) + { + ts->tv_nsec += NSEC_PER_SEC; + ts->tv_sec--; + } +} + +/**************************************************************************** + * Name: ptp_pps_count + * + * Description: + * Read the free running counter of the lower half. + * + ****************************************************************************/ + +static inline uint32_t ptp_pps_count(FAR struct ptp_pps_s *dev) +{ + uint32_t cnt = 0; + + dev->lower->ops->getcount(dev->lower, &cnt); + return cnt; +} + +/**************************************************************************** + * Name: ptp_pps_cnt2ns + * + * Description: + * Convert a counter value to the time of the clock. The counter value + * may be slightly older than the time base (a capture that is reported + * after a re-base), so the difference is signed. + * + * Must be called with the lock held. + * + ****************************************************************************/ + +static int64_t ptp_pps_cnt2ns(FAR struct ptp_pps_s *dev, uint32_t cnt) +{ + uint32_t diff = cnt - dev->base_cnt; + uint64_t prod; + int64_t ns; + + if (diff < PTP_PPS_DIFF_NEG) + { + prod = diff; + prod = prod * dev->mult + dev->base_frac; + ns = prod >> dev->shift; + return dev->base_ns + ns; + } + + /* The counter value is before the time base, round toward -infinity */ + + diff = dev->base_cnt - cnt; + prod = diff; + prod = prod * dev->mult; + if (prod <= dev->base_frac) + { + return dev->base_ns; + } + + prod -= dev->base_frac; + ns = (prod + (UINT64_C(1) << dev->shift) - 1) >> dev->shift; + return dev->base_ns - ns; +} + +/**************************************************************************** + * Name: ptp_pps_rebase + * + * Description: + * Move the time base to the current counter value. Must be called with + * the lock held. + * + ****************************************************************************/ + +static void ptp_pps_rebase(FAR struct ptp_pps_s *dev) +{ + uint32_t cnt = ptp_pps_count(dev); + uint32_t diff = cnt - dev->base_cnt; + uint64_t prod; + int64_t ns; + + /* The counter only moves forward and the watchdog keeps the difference + * below 2^31, so the unsigned difference is the elapsed counter periods. + */ + + if (diff == 0) + { + return; + } + + prod = diff; + prod = prod * dev->mult + dev->base_frac; + ns = prod >> dev->shift; + dev->base_ns += ns; + dev->base_frac = prod & ((UINT64_C(1) << dev->shift) - 1); + dev->base_cnt = cnt; +} + +/**************************************************************************** + * Name: ptp_pps_wdog + * + * Description: + * Re-base the clock periodically so that the counter difference used in + * the conversion never overflows, even if no PPS is received. + * + ****************************************************************************/ + +static void ptp_pps_wdog(wdparm_t arg) +{ + FAR struct ptp_pps_s *dev = (FAR struct ptp_pps_s *)arg; + irqstate_t flags; + + flags = spin_lock_irqsave(&dev->lock); + ptp_pps_rebase(dev); + spin_unlock_irqrestore(&dev->lock, flags); + + wd_start(&dev->wdog, dev->period, ptp_pps_wdog, arg); +} + +/**************************************************************************** + * Name: ptp_pps_notify + * + * Description: + * Capture notification, called by the lower half on each captured edge, + * normally from its interrupt handler. The counter value latched by + * the hardware is converted to the time of the clock and queued as an + * EXTTS event. + * + ****************************************************************************/ + +static void ptp_pps_notify(FAR struct cap_lowerhalf_s *lower, + FAR void *priv) +{ + FAR struct ptp_pps_s *dev = priv; + struct ptp_clock_event event; + irqstate_t flags; + uint32_t cnt; + int64_t ns; + + if (lower->ops->getcapture(lower, &cnt) < 0) + { + return; + } + + flags = spin_lock_irqsave(&dev->lock); + ns = ptp_pps_cnt2ns(dev, cnt); + spin_unlock_irqrestore(&dev->lock, flags); + + event.type = PTP_CLK_REQ_EXTTS; + event.index = 0; + event.flags = dev->edges; + ptp_pps_ns2ts(ns, &event.ts); + + ptp_clock_event(&dev->ptp, &event); +} + +/**************************************************************************** + * Name: ptp_pps_adjfine + * + * Description: + * Set the frequency offset of the clock, in ppb, relative to the nominal + * counter frequency. Positive values make the clock run faster. + * + ****************************************************************************/ + +static int ptp_pps_adjfine(FAR struct ptp_lowerhalf_s *lower, long ppb) +{ + FAR struct ptp_pps_s *dev = (FAR struct ptp_pps_s *)lower; + irqstate_t flags; + int64_t mult; + + mult = dev->mult_nom; + mult += mult * ppb / NSEC_PER_SEC; + if (mult <= 0 || mult > UINT32_MAX) + { + return -ERANGE; + } + + flags = spin_lock_irqsave(&dev->lock); + ptp_pps_rebase(dev); + dev->mult = mult; + spin_unlock_irqrestore(&dev->lock, flags); + + ptpinfo("adjfine %ld ppb, mult %" PRId64 "\n", ppb, mult); + return OK; +} + +/**************************************************************************** + * Name: ptp_pps_adjtime + ****************************************************************************/ + +static int ptp_pps_adjtime(FAR struct ptp_lowerhalf_s *lower, int64_t delta) +{ + FAR struct ptp_pps_s *dev = (FAR struct ptp_pps_s *)lower; + irqstate_t flags; + + flags = spin_lock_irqsave(&dev->lock); + dev->base_ns += delta; + spin_unlock_irqrestore(&dev->lock, flags); + + ptpinfo("adjtime %" PRId64 " ns\n", delta); + return OK; +} + +/**************************************************************************** + * Name: ptp_pps_gettime + ****************************************************************************/ + +static int ptp_pps_gettime(FAR struct ptp_lowerhalf_s *lower, + FAR struct timespec *ts, + FAR struct ptp_system_timestamp *sts) +{ + FAR struct ptp_pps_s *dev = (FAR struct ptp_pps_s *)lower; + irqstate_t flags; + int64_t ns; + + flags = spin_lock_irqsave(&dev->lock); + + if (sts != NULL) + { + nxclock_gettime(CLOCK_REALTIME, &sts->pre_ts); + } + + ns = ptp_pps_cnt2ns(dev, ptp_pps_count(dev)); + + if (sts != NULL) + { + nxclock_gettime(CLOCK_REALTIME, &sts->post_ts); + } + + spin_unlock_irqrestore(&dev->lock, flags); + + ptp_pps_ns2ts(ns, ts); + return OK; +} + +/**************************************************************************** + * Name: ptp_pps_getcrosststamp + * + * Description: + * Read the clock and the system clocks with interrupts disabled, as + * close together as possible. + * + ****************************************************************************/ + +static int ptp_pps_getcrosststamp(FAR struct ptp_lowerhalf_s *lower, + FAR struct system_device_crosststamp *cts) +{ + FAR struct ptp_pps_s *dev = (FAR struct ptp_pps_s *)lower; + irqstate_t flags; + int64_t ns; + + flags = spin_lock_irqsave(&dev->lock); + ns = ptp_pps_cnt2ns(dev, ptp_pps_count(dev)); + nxclock_gettime(CLOCK_REALTIME, &cts->realtime); + nxclock_gettime(CLOCK_MONOTONIC, &cts->monoraw); + spin_unlock_irqrestore(&dev->lock, flags); + + ptp_pps_ns2ts(ns, &cts->device); + return OK; +} + +/**************************************************************************** + * Name: ptp_pps_settime + ****************************************************************************/ + +static int ptp_pps_settime(FAR struct ptp_lowerhalf_s *lower, + FAR const struct timespec *ts) +{ + FAR struct ptp_pps_s *dev = (FAR struct ptp_pps_s *)lower; + irqstate_t flags; + int64_t ns; + + if (ts->tv_nsec < 0 || ts->tv_nsec >= NSEC_PER_SEC) + { + return -EINVAL; + } + + /* tv_sec may be 32-bit, do the multiplication in 64-bit */ + + ns = ts->tv_sec; + ns = ns * NSEC_PER_SEC + ts->tv_nsec; + + flags = spin_lock_irqsave(&dev->lock); + ptp_pps_rebase(dev); + dev->base_ns = ns; + dev->base_frac = 0; + spin_unlock_irqrestore(&dev->lock, flags); + + return OK; +} + +/**************************************************************************** + * Name: ptp_pps_getres + ****************************************************************************/ + +static int ptp_pps_getres(FAR struct ptp_lowerhalf_s *lower, + FAR struct timespec *res) +{ + FAR struct ptp_pps_s *dev = (FAR struct ptp_pps_s *)lower; + + res->tv_sec = 0; + res->tv_nsec = div_round_up(NSEC_PER_SEC, dev->freq); + return OK; +} + +/**************************************************************************** + * Name: ptp_pps_enable + * + * Description: + * Enable or disable the external time stamp input 0, the capture channel + * of the lower half. + * + ****************************************************************************/ + +static int ptp_pps_enable(FAR struct ptp_lowerhalf_s *lower, + FAR struct ptp_clock_request *rq, bool on) +{ + FAR struct ptp_pps_s *dev = (FAR struct ptp_pps_s *)lower; + FAR struct cap_lowerhalf_s *cap = dev->lower; + enum cap_type_e type; + + if (rq->type != PTP_CLK_REQ_EXTTS) + { + return -EOPNOTSUPP; + } + + if (rq->extts.index != 0) + { + return -EINVAL; + } + + if (!on) + { + return cap->ops->unbind(cap); + } + + switch (rq->extts.flags & PTP_EXTTS_EDGES) + { + case PTP_EXTTS_EDGES: + type = CAP_TYPE_BOTH; + dev->edges = 0; + break; + + case PTP_FALLING_EDGE: + type = CAP_TYPE_FALLING; + dev->edges = PTP_FALLING_EDGE; + break; + + default: + type = CAP_TYPE_RISING; + dev->edges = PTP_RISING_EDGE; + break; + } + + return cap->ops->bind(cap, type, ptp_pps_notify, dev); +} + +/**************************************************************************** + * Public Functions + ****************************************************************************/ + +/**************************************************************************** + * Name: ptp_pps_register + * + * Description: + * Create a PPS disciplined PTP clock on top of a capture lower half and + * register it as /dev/ptp<devno>. See include/nuttx/timers/ptp_pps.h. + * + ****************************************************************************/ + +int ptp_pps_register(FAR struct cap_lowerhalf_s *lower, uint32_t freq, + int devno) +{ + FAR const struct cap_ops_s *ops; + FAR struct ptp_pps_s *dev; + uint64_t mult = 0; + uint64_t period; + int shift; + int ret; + + DEBUGASSERT(lower != NULL && lower->ops != NULL); + + ops = lower->ops; + if (freq == 0 || ops->start == NULL || ops->getcount == NULL || + ops->getcapture == NULL || ops->bind == NULL || ops->unbind == NULL) + { + return -EINVAL; + } + + /* Find the largest shift that keeps mult below 2^31 */ + + for (shift = 31; shift > 0; shift--) + { + mult = NSEC_PER_SEC; + mult = ((mult << shift) + freq / 2) / freq; + if (mult <= PTP_PPS_MULT_MAX) + { + break; + } + } + + if (mult == 0 || mult > PTP_PPS_MULT_MAX) + { + return -EINVAL; + } + + dev = kmm_zalloc(sizeof(struct ptp_pps_s)); + if (dev == NULL) + { + ptperr("ERROR: Allocation failed\n"); + return -ENOMEM; + } + + /* Re-base at least every 2^30 counter periods */ + + period = PTP_PPS_REBASE_COUNTS; + period = period * TICK_PER_SEC / freq; + + dev->lower = lower; + dev->freq = freq; + dev->shift = shift; + dev->mult_nom = mult; + dev->mult = mult; + dev->period = period > 0 ? period : 1; + dev->ptp.ops = &g_ptp_pps_ops; + dev->ptp.n_ext_ts = 1; + spin_lock_init(&dev->lock); + + /* Start the counter */ + + ret = ops->start(lower); + if (ret < 0) + { + ptperr("ERROR: Failed to start the capture: %d\n", ret); + kmm_free(dev); + return ret; + } + + dev->base_cnt = ptp_pps_count(dev); + + ptpinfo("freq %" PRIu32 " Hz, shift %d, mult %" PRIu32 "\n", + freq, shift, dev->mult); + + ret = ptp_clock_register(&dev->ptp, CONFIG_PTP_PPS_MAX_ADJ, devno); + if (ret < 0) + { + ptperr("ERROR: ptp_clock_register failed: %d\n", ret); + ops->stop(lower); + kmm_free(dev); + return ret; + } + + wd_start(&dev->wdog, dev->period, ptp_pps_wdog, (wdparm_t)dev); + return OK; +} diff --git a/include/nuttx/timers/ptp_pps.h b/include/nuttx/timers/ptp_pps.h new file mode 100644 index 00000000000..e541c801bfa --- /dev/null +++ b/include/nuttx/timers/ptp_pps.h @@ -0,0 +1,97 @@ +/**************************************************************************** + * include/nuttx/timers/ptp_pps.h + * + * SPDX-License-Identifier: Apache-2.0 + * + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. The + * ASF licenses this file to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance with the + * License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + * License for the specific language governing permissions and limitations + * under the License. + * + ****************************************************************************/ + +#ifndef __INCLUDE_NUTTX_TIMERS_PTP_PPS_H +#define __INCLUDE_NUTTX_TIMERS_PTP_PPS_H + +/**************************************************************************** + * Included Files + ****************************************************************************/ + +#include <nuttx/config.h> + +#include <stdint.h> + +#include <nuttx/timers/capture.h> + +#ifdef CONFIG_PTP_PPS + +/**************************************************************************** + * Public Function Prototypes + ****************************************************************************/ + +#ifdef __cplusplus +extern "C" +{ +#endif + +/**************************************************************************** + * Name: ptp_pps_register + * + * Description: + * Create a PPS disciplined PTP clock on top of a capture lower half and + * register it as /dev/ptp<devno>. + * + * The time of the clock is computed from the free running counter of the + * capture lower half (getcount) with a 64-bit fixed point conversion + * whose rate is changed by clock_adjtime(ADJ_FREQUENCY), so the clock + * can be disciplined with a resolution better than 1 ppb. The external + * time stamp (EXTTS) input 0 of the clock is the capture channel: on + * each edge the counter value latched by the hardware (getcapture) is + * converted to the time of the clock and queued as a struct + * ptp_extts_event for the readers of /dev/ptpX. Because the counter is + * latched by hardware, the time stamp does not depend on the interrupt + * latency. + * + * PPS pin --> [timer input capture] --getcapture()--> EXTTS event + * | ^ + * free running counter --getcount()--> clock_gettime() + * + * The lower half must implement start, getcount, getcapture, bind and + * unbind. Its counter must count up at 'freq' Hz and wrap around from + * 0xffffffff to 0, and the notification callback must be called less + * than 2^31 counter periods after the edge. The capture is started by + * this function and the lower half must not be used by another driver. + * + * The clock starts at zero; set it with clock_settime() or let the + * gnsspps application do it. + * + * Input Parameters: + * lower - The capture lower half. It must persist as long as the + * driver persists. + * freq - The frequency of the counter of the lower half, in Hz. + * devno - The device number, the device is registered as /dev/ptp<devno> + * + * Returned Value: + * Zero (OK) on success; a negated errno value on failure. + * + ****************************************************************************/ + +int ptp_pps_register(FAR struct cap_lowerhalf_s *lower, uint32_t freq, + int devno); + +#ifdef __cplusplus +} +#endif + +#endif /* CONFIG_PTP_PPS */ +#endif /* __INCLUDE_NUTTX_TIMERS_PTP_PPS_H */
