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 515243cf5e7e3e657978494d1bfdfa5d0fd87c28
Author: Alan Carvalho de Assis <[email protected]>
AuthorDate: Fri Nov 13 18:37:07 2026 -0300

    drivers/timers/ptp_clock: Add external time stamp (EXTTS) support.
    
    A PTP clock could only be read and adjusted; there was no way to time
    stamp an external signal, such as the PPS output of a GNSS receiver,
    with the clock.  read() on /dev/ptpX just returned 0.
    
    Add the Linux compatible external time stamp interface:
    
    * PTP_EXTTS_REQUEST(2), PTP_PEROUT_REQUEST(2) and PTP_ENABLE_PPS(2)
      ioctls, with the Linux request structures and flags.  The requests
      are passed to a new optional enable() lower half operation.
    * n_ext_ts, n_per_out and pps in struct ptp_clock_caps and in the
      lower half, reported by PTP_CLOCK_GETCAPS.
    * ptp_clock_event(), callable from an interrupt handler, to report a
      time stamp.  The upper half queues the events
      (CONFIG_PTP_CLOCK_EXTTS_QUEUE_SIZE, the oldest is dropped when the
      queue is full) and returns them as struct ptp_extts_event from
      read(), blocking or O_NONBLOCK, with poll() support
      (CONFIG_PTP_CLOCK_NPOLLWAITERS).
    
    The new members are added at the end of struct ptp_ops_s and struct
    ptp_lowerhalf_s, so the existing STM32 Ethernet PTP drivers are not
    changed: they report no channels, so the requests fail with -EINVAL
    as on Linux, and a lower half without enable() returns -EOPNOTSUPP.
    
    Assisted-by: Claude Code:claude-opus-5-5
    Signed-off-by: Alan Carvalho de Assis <[email protected]>
---
 Documentation/os/drivers/special/ptp.rst |  56 ++++++
 drivers/timers/Kconfig                   |  22 ++
 drivers/timers/ptp_clock.c               | 332 ++++++++++++++++++++++++++++++-
 include/nuttx/timers/ptp_clock.h         | 141 +++++++++++++
 4 files changed, 550 insertions(+), 1 deletion(-)

diff --git a/Documentation/os/drivers/special/ptp.rst 
b/Documentation/os/drivers/special/ptp.rst
index 5e592ef9196..4c5ad27a209 100644
--- a/Documentation/os/drivers/special/ptp.rst
+++ b/Documentation/os/drivers/special/ptp.rst
@@ -42,6 +42,9 @@ Hardware-specific drivers embed a ``struct ptp_lowerhalf_s`` 
and point its
    {
      FAR const struct ptp_ops_s *ops;  /* Lower half driver operations */
      FAR void *upper;                  /* The upper handle */
+     uint8_t n_ext_ts;                 /* Number of external time stamp inputs 
*/
+     uint8_t n_per_out;                /* Number of periodic outputs */
+     bool    pps;                      /* Whether PTP_ENABLE_PPS is supported 
*/
    };
 
    struct ptp_ops_s
@@ -60,6 +63,8 @@ Hardware-specific drivers embed a ``struct ptp_lowerhalf_s`` 
and point its
                         FAR struct timespec *res);
      CODE int (*control)(FAR struct ptp_lowerhalf_s *lower,
                          int cmd, unsigned long arg);
+     CODE int (*enable)(FAR struct ptp_lowerhalf_s *lower,
+                        FAR struct ptp_clock_request *rq, bool on);
    };
 
 The units are:
@@ -81,6 +86,21 @@ half from which operations exist and from ``max_adj``, so 
there is no
 operation to report them. Ioctl commands that the upper half does not know
 are passed to ``control``.
 
+``enable`` switches an ancillary feature on or off: an external time stamp
+input (``PTP_CLK_REQ_EXTTS``), a periodic output (``PTP_CLK_REQ_PEROUT``) or
+the PPS event (``PTP_CLK_REQ_PPS``). The number of inputs and outputs is
+declared in ``n_ext_ts`` and ``n_per_out`` and reported in the capabilities.
+A driver that time stamps an edge on an enabled input reports it with:
+
+.. code-block:: c
+
+   void ptp_clock_event(FAR struct ptp_lowerhalf_s *lower,
+                        FAR const struct ptp_clock_event *event);
+
+The upper half queues the event and the application reads it from the
+device. ``ptp_clock_event()`` can be called from a normal interrupt handler,
+but not from a zero latency (``CONFIG_ARCH_HIPRI_INTERRUPT``) handler.
+
 Configuration Options
 =====================
 
@@ -99,6 +119,13 @@ The PTP clock framework can be enabled with the following 
Kconfig options:
   Enable the ``clock_adjtime()`` system call, required for frequency and
   phase adjustments of PTP clocks.
 
+``CONFIG_PTP_CLOCK_EXTTS_QUEUE_SIZE``
+  Number of external time stamp events kept until the application reads them
+  (default 16). When the queue is full the oldest event is dropped.
+
+``CONFIG_PTP_CLOCK_NPOLLWAITERS``
+  Number of threads that can ``poll()`` one device at the same time.
+
 Device Interface
 ================
 
@@ -185,6 +212,35 @@ The following ioctl commands are supported:
   Read or set the drift statistics kept by the upper half
   (``struct ptp_statistics_s``).
 
+``PTP_EXTTS_REQUEST``
+  Enable or disable an external time stamp input. Every edge seen on an
+  enabled input is time stamped with the PTP clock and returned by
+  ``read()`` as a ``struct ptp_extts_event``. ``read()`` blocks until an
+  event is available (unless ``O_NONBLOCK`` is set) and ``poll()`` reports
+  ``POLLIN`` when events are queued. Enabling an input discards the events
+  that were queued before.
+
+  .. code-block:: c
+
+     struct ptp_extts_request req;
+     struct ptp_extts_event ev;
+
+     memset(&req, 0, sizeof(req));
+     req.index = 0;
+     req.flags = PTP_ENABLE_FEATURE | PTP_RISING_EDGE;
+     ioctl(fd, PTP_EXTTS_REQUEST, &req);
+
+     while (read(fd, &ev, sizeof(ev)) == sizeof(ev))
+       {
+         printf("edge on %u at %lld.%09u\n", ev.index,
+                (long long)ev.t.sec, ev.t.nsec);
+       }
+
+``PTP_PEROUT_REQUEST`` and ``PTP_ENABLE_PPS``
+  Configure a periodic output (``struct ptp_perout_request``, a zero period
+  disables it) or enable the PPS event. They are passed to the ``enable``
+  operation of the lower half.
+
 The ``PTP_CLOCK_GETCAPS``, ``PTP_SYS_OFFSET``, ``PTP_SYS_OFFSET_PRECISE`` and
 ``PTP_SYS_OFFSET_EXTENDED`` commands also exist with a ``2`` suffix
 (``PTP_CLOCK_GETCAPS2``, ``PTP_SYS_OFFSET2`` and so on), which the upper half
diff --git a/drivers/timers/Kconfig b/drivers/timers/Kconfig
index 9f9c5476a99..fae8a013df5 100644
--- a/drivers/timers/Kconfig
+++ b/drivers/timers/Kconfig
@@ -819,6 +819,28 @@ config PTP_CLOCK
                devices. If you want to use a PTP clock, then you should
                also enable at least one clock driver as well.
 
+if PTP_CLOCK
+
+config PTP_CLOCK_EXTTS_QUEUE_SIZE
+       int "External time stamp event queue size"
+       default 16
+       range 1 1024
+       ---help---
+               Number of external time stamp (EXTTS) events, for example
+               PPS pulses, that the PTP clock driver keeps until the
+               application reads them from /dev/ptpX.  When the queue is
+               full the oldest event is dropped.
+
+config PTP_CLOCK_NPOLLWAITERS
+       int "Number of poll waiters"
+       default 2
+       range 1 16
+       ---help---
+               Maximum number of threads that can poll() one /dev/ptpX
+               device at the same time.
+
+endif # PTP_CLOCK
+
 config PTP_CLOCK_DUMMY
        bool "the dummy test driver for ptp clock"
        default n
diff --git a/drivers/timers/ptp_clock.c b/drivers/timers/ptp_clock.c
index 39400586f3c..9e5ea28f0fa 100644
--- a/drivers/timers/ptp_clock.c
+++ b/drivers/timers/ptp_clock.c
@@ -24,6 +24,9 @@
 
 #include <sys/types.h>
 #include <stdio.h>
+#include <string.h>
+#include <fcntl.h>
+#include <poll.h>
 #include <assert.h>
 #include <errno.h>
 #include <nuttx/debug.h>
@@ -31,12 +34,25 @@
 #include <nuttx/fs/fs.h>
 #include <nuttx/kmalloc.h>
 #include <nuttx/mutex.h>
+#include <nuttx/poll.h>
+#include <nuttx/semaphore.h>
+#include <nuttx/spinlock.h>
 #include <nuttx/timers/ptp_clock.h>
 
 /****************************************************************************
  * Pre-processor Definitions
  ****************************************************************************/
 
+#ifndef CONFIG_PTP_CLOCK_EXTTS_QUEUE_SIZE
+#  define CONFIG_PTP_CLOCK_EXTTS_QUEUE_SIZE 16
+#endif
+
+#ifndef CONFIG_PTP_CLOCK_NPOLLWAITERS
+#  define CONFIG_PTP_CLOCK_NPOLLWAITERS 2
+#endif
+
+#define PTP_QUEUE_SIZE  CONFIG_PTP_CLOCK_EXTTS_QUEUE_SIZE
+
 /****************************************************************************
  * Private Types
  ****************************************************************************/
@@ -49,6 +65,22 @@ struct ptp_upperhalf_s
   mutex_t                     lock;     /* Manages exclusive access to file 
operations */
   long                        max_adj;  /* The maximum frequency adjustment */
   long                        adj_freq; /* remembers the frequency adjustment 
*/
+
+  /* External time stamp event queue.  Written by ptp_clock_event(), which
+   * may run in interrupt context, so it is protected by a spinlock.
+   */
+
+  spinlock_t                  qlock;    /* Protects the event queue */
+  sem_t                       qsem;     /* Wakes up blocked readers */
+  uint16_t                    qhead;    /* Index of the oldest event */
+  uint16_t                    qcount;   /* Number of queued events */
+  uint16_t                    nwaiters; /* Number of blocked readers */
+  uint32_t                    overrun;  /* Events lost due to full queue */
+  struct ptp_extts_event      queue[PTP_QUEUE_SIZE];
+
+  /* Poll waiters */
+
+  FAR struct pollfd_s         *fds[CONFIG_PTP_CLOCK_NPOLLWAITERS];
 };
 
 /****************************************************************************
@@ -59,6 +91,8 @@ static ssize_t ptp_clock_read(FAR struct file *filep, FAR 
char *buffer,
                               size_t buflen);
 static int     ptp_clock_ioctl(FAR struct file *filep, int cmd,
                                unsigned long arg);
+static int     ptp_clock_poll(FAR struct file *filep,
+                              FAR struct pollfd_s *fds, bool setup);
 
 /****************************************************************************
  * Private Data
@@ -72,16 +106,162 @@ static const struct file_operations g_ptp_clock_file_ops =
   NULL,            /* write */
   NULL,            /* seek */
   ptp_clock_ioctl, /* ioctl */
+  NULL,            /* mmap */
+  NULL,            /* truncate */
+  ptp_clock_poll,  /* poll */
 };
 
 /****************************************************************************
  * Private Functions
  ****************************************************************************/
 
+/****************************************************************************
+ * Name: ptp_clock_read
+ *
+ * Description:
+ *   Return queued external time stamp events as an array of
+ *   struct ptp_extts_event.  Blocks until at least one event is available
+ *   unless the file was opened with O_NONBLOCK.
+ *
+ ****************************************************************************/
+
 static ssize_t ptp_clock_read(FAR struct file *filep, FAR char *buffer,
                               size_t buflen)
 {
-  return 0;
+  FAR struct ptp_upperhalf_s *upper = filep->f_inode->i_private;
+  FAR struct ptp_extts_event *event = (FAR struct ptp_extts_event *)buffer;
+  size_t nevents = buflen / sizeof(struct ptp_extts_event);
+  irqstate_t flags;
+  size_t n = 0;
+  int ret;
+
+  if (nevents == 0)
+    {
+      return -EINVAL;
+    }
+
+  flags = spin_lock_irqsave(&upper->qlock);
+  while (upper->qcount == 0)
+    {
+      if (filep->f_oflags & O_NONBLOCK)
+        {
+          spin_unlock_irqrestore(&upper->qlock, flags);
+          return -EAGAIN;
+        }
+
+      upper->nwaiters++;
+      spin_unlock_irqrestore(&upper->qlock, flags);
+
+      ret = nxsem_wait(&upper->qsem);
+      if (ret < 0)
+        {
+          flags = spin_lock_irqsave(&upper->qlock);
+          if (upper->nwaiters > 0)
+            {
+              upper->nwaiters--;
+            }
+
+          spin_unlock_irqrestore(&upper->qlock, flags);
+          return ret;
+        }
+
+      flags = spin_lock_irqsave(&upper->qlock);
+    }
+
+  /* Copy the events.  The lock is held only for a few small copies */
+
+  while (n < nevents && upper->qcount > 0)
+    {
+      event[n++] = upper->queue[upper->qhead];
+      upper->qhead = (upper->qhead + 1) % PTP_QUEUE_SIZE;
+      upper->qcount--;
+    }
+
+  spin_unlock_irqrestore(&upper->qlock, flags);
+  return n * sizeof(struct ptp_extts_event);
+}
+
+/****************************************************************************
+ * Name: ptp_clock_poll
+ ****************************************************************************/
+
+static int ptp_clock_poll(FAR struct file *filep, FAR struct pollfd_s *fds,
+                          bool setup)
+{
+  FAR struct ptp_upperhalf_s *upper = filep->f_inode->i_private;
+  irqstate_t flags;
+  int ret = OK;
+  int i;
+
+  flags = spin_lock_irqsave(&upper->qlock);
+  if (setup)
+    {
+      for (i = 0; i < CONFIG_PTP_CLOCK_NPOLLWAITERS; i++)
+        {
+          if (upper->fds[i] == NULL)
+            {
+              upper->fds[i] = fds;
+              fds->priv     = &upper->fds[i];
+              break;
+            }
+        }
+
+      if (i >= CONFIG_PTP_CLOCK_NPOLLWAITERS)
+        {
+          fds->priv = NULL;
+          ret       = -EBUSY;
+        }
+      else if (upper->qcount > 0)
+        {
+          spin_unlock_irqrestore(&upper->qlock, flags);
+          poll_notify(&fds, 1, POLLIN);
+          return OK;
+        }
+    }
+  else if (fds->priv != NULL)
+    {
+      FAR struct pollfd_s **slot = (FAR struct pollfd_s **)fds->priv;
+
+      *slot     = NULL;
+      fds->priv = NULL;
+    }
+
+  spin_unlock_irqrestore(&upper->qlock, flags);
+  return ret;
+}
+
+/****************************************************************************
+ * Name: ptp_clock_flush
+ *
+ * Description:
+ *   Discard the queued external time stamp events, so that the application
+ *   does not read stale time stamps after (re)enabling a channel.
+ *
+ ****************************************************************************/
+
+static void ptp_clock_flush(FAR struct ptp_upperhalf_s *upper)
+{
+  irqstate_t flags;
+
+  flags = spin_lock_irqsave(&upper->qlock);
+  upper->qhead  = 0;
+  upper->qcount = 0;
+  spin_unlock_irqrestore(&upper->qlock, flags);
+}
+
+/****************************************************************************
+ * Name: ptp_clock_enable
+ ****************************************************************************/
+
+static int ptp_clock_enable(FAR struct ptp_lowerhalf_s *lower,
+                            FAR struct ptp_clock_request *rq, bool on)
+{
+  if (lower->ops->enable == NULL)
+    {
+      return -EOPNOTSUPP;
+    }
+
+  return lower->ops->enable(lower, rq, on);
 }
 
 static inline long ptp_clock_scaled_ppm_to_ppb(long ppm)
@@ -224,10 +404,95 @@ static int ptp_clock_ioctl(FAR struct file *filep, int 
cmd,
           caps->max_adj            = upper->max_adj;
           caps->cross_timestamping = lower->ops->getcrosststamp != NULL;
           caps->adjust_phase       = lower->ops->adjphase != NULL;
+          caps->n_ext_ts           = lower->n_ext_ts;
+          caps->n_per_out          = lower->n_per_out;
+          caps->pps                = lower->pps;
           ret = OK;
         }
         break;
 
+      case PTP_EXTTS_REQUEST:
+      case PTP_EXTTS_REQUEST2:
+        {
+          FAR struct ptp_extts_request *req =
+            (FAR struct ptp_extts_request *)(uintptr_t)arg;
+          struct ptp_clock_request rq;
+          bool on;
+
+          if (req == NULL || req->index >= lower->n_ext_ts)
+            {
+              ret = -EINVAL;
+              break;
+            }
+
+          if (cmd == PTP_EXTTS_REQUEST2 &&
+              (req->flags & ~(PTP_ENABLE_FEATURE | PTP_EXTTS_EDGES |
+                              PTP_STRICT_FLAGS)) != 0)
+            {
+              ret = -EINVAL;
+              break;
+            }
+
+          on = (req->flags & PTP_ENABLE_FEATURE) != 0;
+
+          memset(&rq, 0, sizeof(rq));
+          rq.type        = PTP_CLK_REQ_EXTTS;
+          rq.extts.index = req->index;
+          rq.extts.flags = req->flags;
+
+          if (on && (rq.extts.flags & PTP_EXTTS_EDGES) == 0)
+            {
+              rq.extts.flags |= PTP_RISING_EDGE;
+            }
+
+          if (on)
+            {
+              ptp_clock_flush(upper);
+            }
+
+          ret = ptp_clock_enable(lower, &rq, on);
+        }
+        break;
+
+      case PTP_PEROUT_REQUEST:
+      case PTP_PEROUT_REQUEST2:
+        {
+          FAR struct ptp_perout_request *req =
+            (FAR struct ptp_perout_request *)(uintptr_t)arg;
+          struct ptp_clock_request rq;
+
+          if (req == NULL || req->index >= lower->n_per_out)
+            {
+              ret = -EINVAL;
+              break;
+            }
+
+          memset(&rq, 0, sizeof(rq));
+          rq.type   = PTP_CLK_REQ_PEROUT;
+          rq.perout = *req;
+          ret = ptp_clock_enable(lower, &rq,
+                                 req->period.sec != 0 ||
+                                 req->period.nsec != 0);
+        }
+        break;
+
+      case PTP_ENABLE_PPS:
+      case PTP_ENABLE_PPS2:
+        {
+          struct ptp_clock_request rq;
+
+          if (!lower->pps)
+            {
+              ret = -EOPNOTSUPP;
+              break;
+            }
+
+          memset(&rq, 0, sizeof(rq));
+          rq.type = PTP_CLK_REQ_PPS;
+          ret = ptp_clock_enable(lower, &rq, arg != 0);
+        }
+        break;
+
       case PTP_SYS_OFFSET_PRECISE:
       case PTP_SYS_OFFSET_PRECISE2:
         {
@@ -440,13 +705,17 @@ int ptp_clock_register(FAR struct ptp_lowerhalf_s *lower, 
int32_t max_adj,
   upper->max_adj = max_adj;
   lower->upper   = upper;
   nxmutex_init(&upper->lock);
+  spin_lock_init(&upper->qlock);
+  nxsem_init(&upper->qsem, 0, 0);
 
   snprintf(path, sizeof(path), "/dev/ptp%d", devno);
   ptpinfo("Registering %s\n", path);
   ret = register_driver(path, &g_ptp_clock_file_ops, 0600, upper);
   if (ret < 0)
     {
+      nxsem_destroy(&upper->qsem);
       nxmutex_destroy(&upper->lock);
+      lower->upper = NULL;
       kmm_free(upper);
     }
 
@@ -477,7 +746,68 @@ void ptp_clock_unregister(FAR struct ptp_lowerhalf_s 
*lower, int devno)
 
       snprintf(path, sizeof(path), "/dev/ptp%d", devno);
       unregister_driver(path);
+      lower->upper = NULL;
+      nxsem_destroy(&upper->qsem);
       nxmutex_destroy(&upper->lock);
       kmm_free(upper);
     }
 }
+
+/****************************************************************************
+ * Name: ptp_clock_event
+ *
+ * Description:
+ *   Report an event (an external time stamp) to the upper half.  The event
+ *   is queued and can be read() from /dev/ptpX by the application.  When
+ *   the queue is full the oldest event is dropped.
+ *
+ *   This function may be called from a normal interrupt handler.  It must
+ *   NOT be called from a zero latency (CONFIG_ARCH_HIPRI_INTERRUPT)
+ *   handler, which is not allowed to use OS services.
+ *
+ * Input Parameters:
+ *   lower - A pointer to an instance of lower half ptp driver.
+ *   event - The event to report.
+ *
+ ****************************************************************************/
+
+void ptp_clock_event(FAR struct ptp_lowerhalf_s *lower,
+                     FAR const struct ptp_clock_event *event)
+{
+  FAR struct ptp_upperhalf_s *upper = lower->upper;
+  FAR struct ptp_extts_event *slot;
+  irqstate_t flags;
+
+  if (upper == NULL || event->type != PTP_CLK_REQ_EXTTS)
+    {
+      return;
+    }
+
+  flags = spin_lock_irqsave(&upper->qlock);
+
+  if (upper->qcount >= PTP_QUEUE_SIZE)
+    {
+      /* Drop the oldest event to make room for the newest one */
+
+      upper->qhead = (upper->qhead + 1) % PTP_QUEUE_SIZE;
+      upper->qcount--;
+      upper->overrun++;
+    }
+
+  slot = &upper->queue[(upper->qhead + upper->qcount) % PTP_QUEUE_SIZE];
+  memset(slot, 0, sizeof(*slot));
+  slot->t.sec  = event->ts.tv_sec;
+  slot->t.nsec = event->ts.tv_nsec;
+  slot->index  = event->index;
+  slot->flags  = event->flags;
+  upper->qcount++;
+
+  while (upper->nwaiters > 0)
+    {
+      upper->nwaiters--;
+      nxsem_post(&upper->qsem);
+    }
+
+  spin_unlock_irqrestore(&upper->qlock, flags);
+  poll_notify(upper->fds, CONFIG_PTP_CLOCK_NPOLLWAITERS, POLLIN);
+}
diff --git a/include/nuttx/timers/ptp_clock.h b/include/nuttx/timers/ptp_clock.h
index 106eebd232c..a47790b94d6 100644
--- a/include/nuttx/timers/ptp_clock.h
+++ b/include/nuttx/timers/ptp_clock.h
@@ -27,6 +27,8 @@
 
 #include <sys/types.h>
 #include <sys/timex.h>
+#include <stdbool.h>
+#include <stdint.h>
 
 #include <nuttx/clock.h>
 #include <nuttx/fs/ioctl.h>
@@ -53,6 +55,40 @@
 #define PTP_CLOCK_SETSTATS       _PTPIOC(0xd)
 #define PTP_CLOCK_GETSTATS       _PTPIOC(0xe)
 
+/* External timestamp (EXTTS), periodic output (PEROUT) and PPS requests.
+ * These follow the Linux PTP hardware clock API: once an external
+ * timestamp channel is enabled with PTP_EXTTS_REQUEST, every edge seen on
+ * that input is time stamped with the PTP clock and can be read() from
+ * the /dev/ptpX device as a struct ptp_extts_event.
+ */
+
+#define PTP_EXTTS_REQUEST        _PTPIOC(0xf)
+#define PTP_PEROUT_REQUEST       _PTPIOC(0x10)
+#define PTP_ENABLE_PPS           _PTPIOC(0x11)
+#define PTP_EXTTS_REQUEST2       _PTPIOC(0x12)
+#define PTP_PEROUT_REQUEST2      _PTPIOC(0x13)
+#define PTP_ENABLE_PPS2          _PTPIOC(0x14)
+
+/* Bits of the ptp_extts_request.flags field */
+
+#define PTP_ENABLE_FEATURE       (1 << 0)
+#define PTP_RISING_EDGE          (1 << 1)
+#define PTP_FALLING_EDGE         (1 << 2)
+#define PTP_STRICT_FLAGS         (1 << 3)
+#define PTP_EXTTS_EDGES          (PTP_RISING_EDGE | PTP_FALLING_EDGE)
+
+/* Bits of the ptp_perout_request.flags field */
+
+#define PTP_PEROUT_ONE_SHOT      (1 << 0)
+#define PTP_PEROUT_DUTY_CYCLE    (1 << 1)
+#define PTP_PEROUT_PHASE         (1 << 2)
+
+/* Request types passed to the lower half enable() method */
+
+#define PTP_CLK_REQ_EXTTS        0
+#define PTP_CLK_REQ_PEROUT       1
+#define PTP_CLK_REQ_PPS          2
+
 /* Maximum allowed offset measurement samples. */
 
 #define PTP_MAX_SAMPLES          25
@@ -117,6 +153,55 @@ struct ptp_clock_caps
   int max_adj;            /* Maximum frequency adjustment in parts per 
billion. */
   int cross_timestamping; /* Whether the clock supports precise system-device 
cross timestamps */
   int adjust_phase;       /* Whether the clock supports phase adjustment */
+  int n_ext_ts;           /* Number of external time stamp channels */
+  int n_per_out;          /* Number of programmable periodic signals */
+  int pps;                /* Whether the clock supports a PPS callback */
+};
+
+/* struct ptp_extts_request - enable or disable an external timestamp
+ * channel (PTP_EXTTS_REQUEST).
+ */
+
+struct ptp_extts_request
+{
+  unsigned int index;     /* Which channel to configure */
+  unsigned int flags;     /* Bit field of PTP_ENABLE_FEATURE and edges */
+  unsigned int rsv[2];    /* Reserved for future use */
+};
+
+/* struct ptp_extts_event - an external timestamp, returned by read() */
+
+struct ptp_extts_event
+{
+  struct ptp_clock_time t; /* Time when the event occurred */
+  unsigned int index;      /* Which channel produced the event */
+  unsigned int flags;      /* Edge that produced the event, if known */
+  unsigned int rsv[2];     /* Reserved for future use */
+};
+
+/* struct ptp_perout_request - configure a periodic output
+ * (PTP_PEROUT_REQUEST).
+ */
+
+struct ptp_perout_request
+{
+  struct ptp_clock_time start;   /* Absolute start time, or phase offset
+                                  * with PTP_PEROUT_PHASE */
+  struct ptp_clock_time period;  /* Desired period, zero means disable */
+  unsigned int index;            /* Which channel to configure */
+  unsigned int flags;            /* PTP_PEROUT_xxx flags */
+  struct ptp_clock_time on;      /* "On" time (PTP_PEROUT_DUTY_CYCLE) */
+};
+
+/* struct ptp_clock_request - request passed to the lower half enable()
+ * method.
+ */
+
+struct ptp_clock_request
+{
+  int type;                         /* PTP_CLK_REQ_xxx */
+  struct ptp_extts_request extts;   /* Valid for PTP_CLK_REQ_EXTTS */
+  struct ptp_perout_request perout; /* Valid for PTP_CLK_REQ_PEROUT */
 };
 
 struct ptp_sys_offset
@@ -317,6 +402,29 @@ struct ptp_ops_s
 
   CODE int (*control)(FAR struct ptp_lowerhalf_s *lower,
                       int cmd, unsigned long arg);
+
+  /**************************************************************************
+   * Name: enable
+   *
+   * Description:
+   *   Enables or disables an ancillary feature of the clock: an external
+   *   timestamp channel (EXTTS), a periodic output (PEROUT) or the PPS
+   *   event.  Time stamps of an enabled EXTTS channel are reported to the
+   *   upper half with ptp_clock_event().
+   *
+   * Input Parameters:
+   *   lower - The instance of lower half ptp driver.
+   *   rq    - The feature to change and its parameters.
+   *   on    - true to enable the feature, false to disable it.
+   *
+   * Returned Value:
+   *   Zero (OK) or positive on success; a negated errno value on failure.
+   *   -EOPNOTSUPP - The feature is not supported.
+   *
+   **************************************************************************/
+
+  CODE int (*enable)(FAR struct ptp_lowerhalf_s *lower,
+                     FAR struct ptp_clock_request *rq, bool on);
 };
 
 /* The ptp lower half driver interface, describes a PTP hardware
@@ -327,6 +435,19 @@ struct ptp_lowerhalf_s
 {
   FAR const struct ptp_ops_s *ops; /* Lower half driver operations. */
   FAR void *upper;                 /* The upper handle */
+  uint8_t n_ext_ts;                /* Number of external time stamp inputs */
+  uint8_t n_per_out;               /* Number of periodic outputs */
+  bool    pps;                     /* Whether PTP_ENABLE_PPS is supported */
+};
+
+/* struct ptp_clock_event - an event reported by the lower half */
+
+struct ptp_clock_event
+{
+  int type;                        /* PTP_CLK_REQ_EXTTS only for now */
+  unsigned int index;              /* Channel that produced the event */
+  unsigned int flags;              /* Edge, PTP_RISING/FALLING_EDGE or 0 */
+  struct timespec ts;              /* Time stamp in the PTP time scale */
 };
 
 /****************************************************************************
@@ -388,6 +509,26 @@ int ptp_clock_register(FAR struct ptp_lowerhalf_s *lower, 
int32_t max_adj,
 
 void ptp_clock_unregister(FAR struct ptp_lowerhalf_s *dev, int devno);
 
+/****************************************************************************
+ * Name: ptp_clock_event
+ *
+ * Description:
+ *   Report an event (an external time stamp) to the upper half.  The event
+ *   is queued and can be read() from /dev/ptpX by the application.
+ *
+ *   This function may be called from a normal interrupt handler.  It must
+ *   NOT be called from a zero latency (CONFIG_ARCH_HIPRI_INTERRUPT)
+ *   handler, which is not allowed to use OS services.
+ *
+ * Input Parameters:
+ *   lower - A pointer to an instance of lower half ptp driver.
+ *   event - The event to report.
+ *
+ ****************************************************************************/
+
+void ptp_clock_event(FAR struct ptp_lowerhalf_s *lower,
+                     FAR const struct ptp_clock_event *event);
+
 #if defined(__cplusplus)
 }
 #endif

Reply via email to