[PATCH net-next v5 0/2] ptp: Alibaba CIPU PTP clock driver

[PATCH net-next v5 0/2] ptp: Alibaba CIPU PTP clock driver

[Wen Gu]

This adds a driver for Alibaba CIPU PTP clock.

The CIPU, an underlying infrastructure of Alibaba Cloud, synchronizes
time with atomic clocks via the network and provides microsecond or
sub-microsecond precision timestamps for VMs and bare metals on cloud.

User space processes, such as chrony, running in VMs or on bare metals
can get the high precision time through the ptp device exposed by this
driver.

In addition, this driver exposes sysfs files for obtaining device
attributes and event statistics, as described in the documentation.

---
v5->v4:
- add documentation describing sysfs files.

v4->v3:
https://lore.kernel.org/netdev/20250812115321.9179-1-guwen@linux.alibaba.com/
- use disable_* variant helpers as suggested by Paolo.
- minor nit: make PTP_CIPU_REG macro one line.

v3->v2:
https://lore.kernel.org/netdev/20250717075734.62296-1-guwen@linux.alibaba.com/
- follow the sysfs convention of one value per file;
- rename enum constants for brevity;
- improve macros for printing;
- add more comments;

v2->v1:
https://lore.kernel.org/netdev/20250627072921.52754-1-guwen@linux.alibaba.com/
- add Kconfig dependency on CONFIG_PCI to fix kernel test
  robot's complaint.

v1:
https://lore.kernel.org/netdev/20250625132549.93614-1-guwen@linux.alibaba.com/

Wen Gu (2):
  ptp: introduce Alibaba CIPU PHC driver
  ptp: add sysfs documentation for Alibaba CIPU PHC driver

 .../ABI/testing/sysfs-ptp-devices-cipu        | 227 +++++
 MAINTAINERS                                   |   8 +
 drivers/ptp/Kconfig                           |  12 +
 drivers/ptp/Makefile                          |   1 +
 drivers/ptp/ptp_cipu.c                        | 946 ++++++++++++++++++
 5 files changed, 1194 insertions(+)
 create mode 100644 Documentation/ABI/testing/sysfs-ptp-devices-cipu
 create mode 100644 drivers/ptp/ptp_cipu.c

-- 
2.43.5

[PATCH net-next v5 1/2] ptp: introduce Alibaba CIPU PHC driver

[Wen Gu]

This adds a driver for Alibaba CIPU PTP clock. The CIPU, an underlying
infrastructure of Alibaba Cloud, synchronizes time with atomic clocks
via the network and provides microsecond or sub-microsecond precision
timestamps for VMs and bare metals on cloud.

User space processes, such as chrony, running in VMs or on bare metals
can get the high precision time through the PTP device exposed by this
driver.

Signed-off-by: Wen Gu <guwen@linux.alibaba.com>
Reviewed-by: Xuan Zhuo <xuanzhuo@linux.alibaba.com>
---
 MAINTAINERS            |   7 +
 drivers/ptp/Kconfig    |  12 +
 drivers/ptp/Makefile   |   1 +
 drivers/ptp/ptp_cipu.c | 946 +++++++++++++++++++++++++++++++++++++++++
 4 files changed, 966 insertions(+)
 create mode 100644 drivers/ptp/ptp_cipu.c

diff --git a/MAINTAINERS b/MAINTAINERS
index d652f4f27756..b1543fcd12ea 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -795,6 +795,13 @@ S:	Maintained
 F:	Documentation/i2c/busses/i2c-ali1563.rst
 F:	drivers/i2c/busses/i2c-ali1563.c
 
+ALIBABA CIPU PTP DRIVER
+M:	Wen Gu <guwen@linux.alibaba.com>
+M:	Xuan Zhuo <xuanzhuo@linux.alibaba.com>
+L:	netdev@vger.kernel.org
+S:	Supported
+F:	drivers/ptp/ptp_cipu.c
+
 ALIBABA ELASTIC RDMA DRIVER
 M:	Cheng Xu <chengyou@linux.alibaba.com>
 M:	Kai Shen <kaishen@linux.alibaba.com>
diff --git a/drivers/ptp/Kconfig b/drivers/ptp/Kconfig
index 5f8ea34d11d6..42c23d33269a 100644
--- a/drivers/ptp/Kconfig
+++ b/drivers/ptp/Kconfig
@@ -263,4 +263,16 @@ config PTP_NETC_V4_TIMER
 	  synchronization. It also supports periodic output signal (e.g. PPS)
 	  and external trigger timestamping.
 
+config PTP_1588_CLOCK_CIPU
+	tristate "Alibaba CIPU PTP clock"
+	depends on PTP_1588_CLOCK
+	depends on 64BIT
+	depends on PCI
+	help
+	  This driver adds support for using the Alibaba CIPU PHC device
+	  as a PTP clock. This is only useful with the Alibaba Cloud CIPU
+	  infrastructure.
+
+	  To compile this driver as a module, choose M here: the module
+	  will be called ptp_cipu.
 endmenu
diff --git a/drivers/ptp/Makefile b/drivers/ptp/Makefile
index bdc47e284f14..a8396a5d5996 100644
--- a/drivers/ptp/Makefile
+++ b/drivers/ptp/Makefile
@@ -22,3 +22,4 @@ obj-$(CONFIG_PTP_1588_CLOCK_OCP)	+= ptp_ocp.o
 obj-$(CONFIG_PTP_DFL_TOD)		+= ptp_dfl_tod.o
 obj-$(CONFIG_PTP_S390)			+= ptp_s390.o
 obj-$(CONFIG_PTP_NETC_V4_TIMER)		+= ptp_netc.o
+obj-$(CONFIG_PTP_1588_CLOCK_CIPU)	+= ptp_cipu.o
diff --git a/drivers/ptp/ptp_cipu.c b/drivers/ptp/ptp_cipu.c
new file mode 100644
index 000000000000..c0e5ab4beb11
--- /dev/null
+++ b/drivers/ptp/ptp_cipu.c
@@ -0,0 +1,946 @@
+// SPDX-License-Identifier: GPL-2.0-or-later
+/*
+ * PTP clock for Alibaba CIPU
+ *
+ * Copyright (C) 2025 Alibaba Inc.
+ */
+
+#include <linux/kernel.h>
+#include <linux/module.h>
+#include <linux/pci.h>
+#include <linux/ptp_clock_kernel.h>
+#include <linux/types.h>
+#include <linux/version.h>
+#include <linux/utsname.h>
+
+#define DRV_VER_MAJOR		1
+#define DRV_VER_MINOR		3
+#define DRV_VER_SUBMINOR	0
+#ifndef DRV_TYPE
+#define DRV_TYPE		0
+#endif
+#define LINUX_UPSTREAM		0x1F
+
+enum {
+	PTP_CIPU_DEV_RESET,
+	PTP_CIPU_DEV_INIT,
+	PTP_CIPU_DEV_READY,
+}; /* device status */
+
+/* feature bits mask */
+#define PTP_CIPU_M_FT_TAI	BIT(0) /* 1: support TAI. 0: def UTC */
+#define PTP_CIPU_M_FT_EPOCH	BIT(1) /* 1: epoch base, 0: 1970-01-01. */
+#define PTP_CIPU_M_FT_IRQ_ABN	BIT(2) /* 1: abnormal event irq. */
+#define PTP_CIPU_M_FT_IRQ_REC	BIT(3) /* 1: recovery event irq. */
+
+/* timestamp bits mask */
+#define PTP_CIPU_M_TS_ABN	BIT_ULL(63) /* 1: normal, 0: abnormal */
+#define PTP_CIPU_M_TS_RESVD	BIT_ULL(62) /* reserved now */
+
+/* sync status bits mask */
+#define PTP_CIPU_M_ST_DEV_MT	BIT(0) /* maintenance */
+#define PTP_CIPU_M_ST_CLK_ABN	BIT(1) /* atomic clock abnormal */
+#define PTP_CIPU_M_ST_DEV_BUSY	BIT(4) /* cipu device busy */
+#define PTP_CIPU_M_ST_DEV_ERR	BIT(7) /* cipu device error */
+
+#define PTP_CIPU_M_ST_PHC_ISSUE	\
+	(PTP_CIPU_M_ST_DEV_MT | PTP_CIPU_M_ST_CLK_ABN | \
+	 PTP_CIPU_M_ST_DEV_BUSY | PTP_CIPU_M_ST_DEV_ERR)
+
+/* TAI is not supported now */
+#define PTP_CIPU_DRV_CAP (PTP_CIPU_M_FT_EPOCH | PTP_CIPU_M_FT_IRQ_ABN | \
+			  PTP_CIPU_M_FT_IRQ_REC)
+
+struct ptp_cipu_regs {
+	u32	dev_feat;	/* RO, device features */
+	u32	gst_feat;	/* RW, guest features */
+	u32	drv_ver;	/* RW, driver version */
+	u32	env_ver;	/* RW, environment version */
+	u8	dev_stat;	/* RW, device status */
+	u8	sync_stat;	/* RO, sync status */
+	u16	reserved;
+	u32	tm_prec_ns;	/* RO, time precision */
+	u32	epo_base_yr;	/* RO, epoch base */
+	u32	leap_sec;	/* RO, leap second */
+	u32	max_lat_ns;	/* RO, max latency */
+	u32	mt_tout_us;	/* RO, maintenance timeout */
+	u64	tstamp_ns;	/* RO, timestamp */
+	u32	thresh_us;	/* RO, threshold */
+};
+
+#define PTP_CIPU_BAR_0	0
+#define PTP_CIPU_REG(reg) offsetof(struct ptp_cipu_regs, reg)
+
+enum {
+	EVT_TYPE_PTP,
+	EVT_TYPE_DEV,
+	EVT_TYPE_DRV,
+}; /* event types */
+
+enum {
+	EVT_P_GT_OPS,
+	EVT_P_GT_INVAL,
+	EVT_P_GT_TOUT,
+	EVT_P_GT_ETHRESH,
+	EVT_P_MAX,
+}; /* events related to ptp operations */
+
+enum {
+	EVT_H_CLK_ABN,
+	EVT_H_CLK_ABN_REC,
+	EVT_H_DEV_MT,
+	EVT_H_DEV_MT_REC,
+	EVT_H_DEV_MT_TOUT,
+	EVT_H_DEV_BUSY,
+	EVT_H_DEV_BUSY_REC,
+	EVT_H_DEV_ERR,
+	EVT_H_DEV_ERR_REC,
+	EVT_H_MAX,
+}; /* events related to hardware device */
+
+enum {
+	EVT_D_GENERAL,
+	EVT_D_PROBE_FAIL,
+	EVT_D_MAX,
+}; /* events related to driver ifself */
+
+struct ptp_cipu_stats {
+	u64	ptp_evts[EVT_P_MAX];
+	u64	dev_evts[EVT_H_MAX];
+}; /* statistics */
+
+#define PTP_DEV_ERR(dev, type, event, fmt, ...) \
+	dev_err_ratelimited(dev, "[%02x:%02x]: " fmt, \
+			    type, event, ##__VA_ARGS__)
+#define PTP_DEV_WARN(dev, type, event, fmt, ...) \
+	dev_warn_ratelimited(dev, "[%02x:%02x]: " fmt, \
+			     type, event, ##__VA_ARGS__)
+#define PTP_DEV_INFO(dev, type, event, fmt, ...) \
+	dev_info_ratelimited(dev, "[%02x:%02x]: " fmt, \
+			     type, event, ##__VA_ARGS__)
+
+#define PTP_CIPU_TIMER_PERIOD	(30 * HZ)
+
+struct ptp_cipu_timer_ctx {
+	u64 over_thresh_cnt;
+	u32 thresh_us;
+};
+
+enum {
+	PTP_CIPU_IRQ_0,
+	PTP_CIPU_IRQ_1,
+	PTP_CIPU_IRQ_NUM,
+};
+
+struct ptp_cipu_irq_ctx {
+	irqreturn_t (*irq_func)(int irq, void *data);
+};
+
+struct ptp_cipu_ctx {
+	struct pci_dev *pdev;
+	struct ptp_clock *ptp_clock;
+	struct ptp_clock_info ptp_info;
+	spinlock_t lock; /* lock for getting time */
+	int reg_len;
+	void __iomem *reg_addr;
+	struct ptp_cipu_regs regs;
+	struct ptp_cipu_stats __percpu *stats;
+	time64_t epo_base_ns;
+	struct workqueue_struct	*wq;
+	struct mutex sync_lock;	/* lock for sync_status */
+	struct work_struct sync_work;
+	struct delayed_work gen_timer; /* general timer */
+	struct ptp_cipu_timer_ctx timer_ctx;
+	struct delayed_work mt_timer; /* maintenance check timer */
+	u8 has_issue;
+};
+
+static int cipu_iowrite8_and_check(void __iomem *addr,
+				   u8 value, u8 *res)
+{
+	iowrite8(value, addr);
+	/* If the value is not what the device expects
+	 * or the device is broken, the write will fail.
+	 */
+	if (value != ioread8(addr))
+		return -EIO;
+	*res = value;
+	return 0;
+}
+
+static int cipu_iowrite32_and_check(void __iomem *addr,
+				    u32 value, u32 *res)
+{
+	iowrite32(value, addr);
+	/* If the value is not what the device expects
+	 * or the device is broken, the write will fail.
+	 */
+	if (value != ioread32(addr))
+		return -EIO;
+	*res = value;
+	return 0;
+}
+
+static void ptp_cipu_print_dev_events(struct ptp_cipu_ctx *ptp_ctx,
+				      int event)
+{
+	struct device *dev = &ptp_ctx->pdev->dev;
+	int type = EVT_TYPE_DEV;
+
+	switch (event) {
+	case EVT_H_CLK_ABN:
+		PTP_DEV_ERR(dev, type, event,
+			    "Atomic Clock Error Detected\n");
+		break;
+	case EVT_H_CLK_ABN_REC:
+		PTP_DEV_INFO(dev, type, event,
+			     "Atomic Clock Error Recovered\n");
+		break;
+	case EVT_H_DEV_MT:
+		PTP_DEV_ERR(dev, type, event,
+			    "Maintenance Exception Detected\n");
+		break;
+	case EVT_H_DEV_MT_REC:
+		PTP_DEV_INFO(dev, type, event,
+			     "Maintenance Exception Recovered\n");
+		break;
+	case EVT_H_DEV_MT_TOUT:
+		PTP_DEV_INFO(dev, type, event,
+			     "Maintenance Exception Failed to Recover within %d us\n",
+			     ptp_ctx->regs.mt_tout_us);
+		break;
+	case EVT_H_DEV_BUSY:
+		PTP_DEV_ERR(dev, type, event, "PHC Busy Detected\n");
+		break;
+	case EVT_H_DEV_BUSY_REC:
+		PTP_DEV_INFO(dev, type, event, "PHC Busy Recovered\n");
+		break;
+	case EVT_H_DEV_ERR:
+		PTP_DEV_ERR(dev, type, event, "PHC Error Detected\n");
+		break;
+	case EVT_H_DEV_ERR_REC:
+		PTP_DEV_INFO(dev, type, event, "PHC Error Recovered\n");
+		break;
+	default:
+		break;
+	}
+}
+
+static void ptp_cipu_print_ptp_events(struct ptp_cipu_ctx *ptp_ctx,
+				      int event)
+{
+	struct device *dev = &ptp_ctx->pdev->dev;
+	int type = EVT_TYPE_PTP;
+
+	switch (event) {
+	case EVT_P_GT_OPS:
+		/* no action required */
+		break;
+	case EVT_P_GT_INVAL:
+		PTP_DEV_WARN(dev, type, event,
+			     "PHC Get Time Failed Due to Invalid Timestamp\n");
+		break;
+	case EVT_P_GT_TOUT:
+		PTP_DEV_WARN(dev, type, event,
+			     "PHC Get Time Failed Due to Register Read Timeout\n");
+		break;
+	case EVT_P_GT_ETHRESH:
+		/* aggregate output to timer */
+		break;
+	default:
+		break;
+	}
+}
+
+static int ptp_cipu_record_events(struct ptp_cipu_ctx *ptp_ctx,
+				  int type, int event)
+{
+	switch (type) {
+	case EVT_TYPE_PTP:
+		if (event >= EVT_P_MAX)
+			goto out;
+		this_cpu_inc(ptp_ctx->stats->ptp_evts[event]);
+		ptp_cipu_print_ptp_events(ptp_ctx, event);
+		break;
+	case EVT_TYPE_DEV:
+		if (event >= EVT_H_MAX)
+			goto out;
+		this_cpu_inc(ptp_ctx->stats->dev_evts[event]);
+		ptp_cipu_print_dev_events(ptp_ctx, event);
+		break;
+	case EVT_TYPE_DRV:
+		if (event >= EVT_D_MAX)
+			goto out;
+		break;
+	default:
+		type = 0xff;
+		goto out;
+	}
+	return 0;
+
+out:
+	PTP_DEV_WARN(&ptp_ctx->pdev->dev, type, event,
+		     "Invalid Events\n");
+	return -EINVAL;
+}
+
+/* process exception or recovery, must be protected by sync_lock */
+static int ptp_cipu_process_sync_status(struct ptp_cipu_ctx *ptp_ctx)
+{
+	struct ptp_cipu_regs *regs = &ptp_ctx->regs;
+	u32 last_status, status, diff_status;
+
+	last_status = regs->sync_stat;
+	regs->sync_stat = ioread32(ptp_ctx->reg_addr + PTP_CIPU_REG(sync_stat));
+	status = regs->sync_stat;
+
+	ptp_ctx->has_issue = status & PTP_CIPU_M_ST_PHC_ISSUE ? 1 : 0;
+
+	diff_status = last_status ^ status;
+
+	if (diff_status & PTP_CIPU_M_ST_CLK_ABN)
+		ptp_cipu_record_events(ptp_ctx, EVT_TYPE_DEV,
+				       (status & PTP_CIPU_M_ST_CLK_ABN) ?
+				       EVT_H_CLK_ABN :
+				       EVT_H_CLK_ABN_REC);
+
+	if (diff_status & PTP_CIPU_M_ST_DEV_BUSY)
+		ptp_cipu_record_events(ptp_ctx, EVT_TYPE_DEV,
+				       (status & PTP_CIPU_M_ST_DEV_BUSY) ?
+				       EVT_H_DEV_BUSY :
+				       EVT_H_DEV_BUSY_REC);
+
+	if (diff_status & PTP_CIPU_M_ST_DEV_ERR)
+		ptp_cipu_record_events(ptp_ctx, EVT_TYPE_DEV,
+				       (status & PTP_CIPU_M_ST_DEV_ERR) ?
+				       EVT_H_DEV_ERR :
+				       EVT_H_DEV_ERR_REC);
+
+	if (diff_status & PTP_CIPU_M_ST_DEV_MT) {
+		ptp_cipu_record_events(ptp_ctx, EVT_TYPE_DEV,
+				       (status & PTP_CIPU_M_ST_DEV_MT) ?
+				       EVT_H_DEV_MT :
+				       EVT_H_DEV_MT_REC);
+		if (status & PTP_CIPU_M_ST_DEV_MT)
+			/* Maintenance exception occurs, start a timer
+			 * to check whether the maintenance status can
+			 * be recovered within time mt_tout_us.
+			 */
+			queue_delayed_work(ptp_ctx->wq, &ptp_ctx->mt_timer,
+					   usecs_to_jiffies(regs->mt_tout_us));
+		else if (!(status & PTP_CIPU_M_ST_DEV_MT))
+			/* Maintenance exception recovered. */
+			cancel_delayed_work(&ptp_ctx->mt_timer);
+	}
+	return status;
+}
+
+static void ptp_cipu_gen_timer(struct work_struct *work)
+{
+	struct ptp_cipu_ctx *ptp_ctx = container_of(to_delayed_work(work),
+						    struct ptp_cipu_ctx,
+						    gen_timer);
+	int cpu, thresh, last, now = 0;
+	struct ptp_cipu_stats *stats;
+
+	for_each_possible_cpu(cpu) {
+		stats = per_cpu_ptr(ptp_ctx->stats, cpu);
+		now += stats->ptp_evts[EVT_P_GT_ETHRESH];
+	}
+	last = ptp_ctx->timer_ctx.over_thresh_cnt;
+	thresh = ptp_ctx->timer_ctx.thresh_us;
+
+	ptp_ctx->timer_ctx.over_thresh_cnt = now;
+	ptp_ctx->timer_ctx.thresh_us = ptp_ctx->regs.thresh_us;
+
+	if (now > last)
+		PTP_DEV_WARN(&ptp_ctx->pdev->dev,
+			     EVT_TYPE_PTP, EVT_P_GT_ETHRESH,
+			     "Offset of PHC and System Time Exceeds %d us %d time(s)\n",
+			     thresh, now - last);
+	mod_delayed_work(ptp_ctx->wq, &ptp_ctx->gen_timer,
+			 PTP_CIPU_TIMER_PERIOD);
+}
+
+static void ptp_cipu_mt_timer(struct work_struct *work)
+{
+	struct ptp_cipu_ctx *ptp_ctx = container_of(to_delayed_work(work),
+						    struct ptp_cipu_ctx,
+						    mt_timer);
+	u32 sync_stat;
+
+	mutex_lock(&ptp_ctx->sync_lock);
+	sync_stat = ptp_cipu_process_sync_status(ptp_ctx);
+	if (sync_stat & PTP_CIPU_M_ST_DEV_MT)
+		ptp_cipu_record_events(ptp_ctx, EVT_TYPE_DEV,
+				       EVT_H_DEV_MT_TOUT);
+	mutex_unlock(&ptp_ctx->sync_lock);
+}
+
+static void ptp_cipu_sync_status_work(struct work_struct *work)
+{
+	struct ptp_cipu_ctx *ptp_ctx =
+		container_of(work, struct ptp_cipu_ctx, sync_work);
+
+	mutex_lock(&ptp_ctx->sync_lock);
+	ptp_cipu_process_sync_status(ptp_ctx);
+	mutex_unlock(&ptp_ctx->sync_lock);
+}
+
+static irqreturn_t ptp_cipu_status_handler(int irq, void *data)
+{
+	struct ptp_cipu_ctx *ptp_ctx = (struct ptp_cipu_ctx *)data;
+
+	queue_work(ptp_ctx->wq, &ptp_ctx->sync_work);
+	return IRQ_HANDLED;
+}
+
+static irqreturn_t ptp_cipu_update_threshold(int irq, void *data)
+{
+	struct ptp_cipu_ctx *ptp_ctx = (struct ptp_cipu_ctx *)data;
+
+	ptp_ctx->regs.thresh_us =
+		ioread32(ptp_ctx->reg_addr + PTP_CIPU_REG(thresh_us));
+	mod_delayed_work(ptp_ctx->wq, &ptp_ctx->gen_timer, 0);
+	return IRQ_HANDLED;
+}
+
+static struct ptp_cipu_irq_ctx irq_ctx[PTP_CIPU_IRQ_NUM] = {
+	[PTP_CIPU_IRQ_0] = { .irq_func = ptp_cipu_update_threshold },
+	[PTP_CIPU_IRQ_1] = { .irq_func = ptp_cipu_status_handler }
+};
+
+static int __ptp_cipu_gettimex(struct ptp_cipu_ctx *ptp_ctx,
+			       struct timespec64 *ts,
+			       struct ptp_system_timestamp *sts)
+{
+	struct ptp_cipu_regs *regs = &ptp_ctx->regs;
+	ktime_t tstamp_ns, intvl_ns, sys_ns, phc_ns;
+	struct timespec64 intvl;
+	unsigned long flags;
+
+	ptp_cipu_record_events(ptp_ctx, EVT_TYPE_PTP, EVT_P_GT_OPS);
+
+	spin_lock_irqsave(&ptp_ctx->lock, flags);
+	ptp_read_system_prets(sts);
+	tstamp_ns = readq(ptp_ctx->reg_addr + PTP_CIPU_REG(tstamp_ns));
+	ptp_read_system_postts(sts);
+	spin_unlock_irqrestore(&ptp_ctx->lock, flags);
+
+	if (tstamp_ns & PTP_CIPU_M_TS_ABN) {
+		/* invalid timestamp */
+		ptp_cipu_record_events(ptp_ctx, EVT_TYPE_PTP, EVT_P_GT_INVAL);
+		queue_work(ptp_ctx->wq, &ptp_ctx->sync_work);
+		return -EIO;
+	}
+
+	/* PHC had issues before, but timestamp is currently valid,
+	 * which means that there is an update of the sync_status to process.
+	 */
+	if (ptp_ctx->has_issue)
+		queue_work(ptp_ctx->wq, &ptp_ctx->sync_work);
+
+	intvl = timespec64_sub(sts->post_ts, sts->pre_ts);
+	intvl_ns = timespec64_to_ns(&intvl);
+	if (abs(intvl_ns) > regs->max_lat_ns) {
+		/* register read timeout */
+		ptp_cipu_record_events(ptp_ctx, EVT_TYPE_PTP, EVT_P_GT_TOUT);
+		return -EIO;
+	}
+
+	sys_ns = timespec64_to_ns(&sts->pre_ts) + intvl_ns / 2;
+	phc_ns = ptp_ctx->epo_base_ns + (tstamp_ns &
+		~(PTP_CIPU_M_TS_ABN | PTP_CIPU_M_TS_RESVD));
+
+	if (abs(phc_ns - sys_ns) >
+	    ptp_ctx->timer_ctx.thresh_us * NSEC_PER_USEC)
+		/* time drifting exceeds the threshold, just record it */
+		ptp_cipu_record_events(ptp_ctx, EVT_TYPE_PTP, EVT_P_GT_ETHRESH);
+
+	*ts = ns_to_timespec64(phc_ns);
+	return 0;
+}
+
+static int ptp_cipu_gettimex(struct ptp_clock_info *ptp, struct timespec64 *ts,
+			     struct ptp_system_timestamp *sts_user)
+{
+	struct ptp_cipu_ctx *ptp_ctx =
+			container_of(ptp, struct ptp_cipu_ctx, ptp_info);
+	struct ptp_system_timestamp sts_stack, *sts;
+
+	sts = sts_user ? sts_user : &sts_stack;
+
+	return __ptp_cipu_gettimex(ptp_ctx, ts, sts);
+}
+
+static int ptp_cipu_gettime(struct ptp_clock_info *ptp, struct timespec64 *ts)
+{
+	struct ptp_cipu_ctx *ptp_ctx =
+			container_of(ptp, struct ptp_cipu_ctx, ptp_info);
+	struct ptp_system_timestamp sts;
+
+	return __ptp_cipu_gettimex(ptp_ctx, ts, &sts);
+}
+
+static int ptp_cipu_enable(struct ptp_clock_info *info,
+			   struct ptp_clock_request *request, int on)
+{
+	return -EOPNOTSUPP;
+}
+
+static int ptp_cipu_settime(struct ptp_clock_info *p,
+			    const struct timespec64 *ts)
+{
+	return -EOPNOTSUPP;
+}
+
+static int ptp_cipu_adjfine(struct ptp_clock_info *ptp, long scaled_ppm)
+{
+	return -EOPNOTSUPP;
+}
+
+static int ptp_cipu_adjtime(struct ptp_clock_info *ptp, s64 delta)
+{
+	return -EOPNOTSUPP;
+}
+
+static struct ptp_clock_info ptp_cipu_clock_info = {
+	.owner		= THIS_MODULE,
+	.name		= "ptp_cipu",
+	.adjtime	= ptp_cipu_adjtime,
+	.adjfine	= ptp_cipu_adjfine,
+	.gettimex64	= ptp_cipu_gettimex,
+	.gettime64	= ptp_cipu_gettime,
+	.settime64	= ptp_cipu_settime,
+	.enable		= ptp_cipu_enable,
+};
+
+static int ptp_cipu_set_guest_features(struct ptp_cipu_ctx *ptp_ctx)
+{
+	struct ptp_cipu_regs *regs = &ptp_ctx->regs;
+
+	regs->dev_feat = ioread32(ptp_ctx->reg_addr + PTP_CIPU_REG(dev_feat));
+
+	return cipu_iowrite32_and_check(ptp_ctx->reg_addr +
+					PTP_CIPU_REG(gst_feat),
+					PTP_CIPU_DRV_CAP & regs->dev_feat,
+					&regs->gst_feat);
+}
+
+static int ptp_cipu_set_dev_status(struct ptp_cipu_ctx *ptp_ctx,
+				   int status)
+{
+	return cipu_iowrite8_and_check(ptp_ctx->reg_addr +
+				       PTP_CIPU_REG(dev_stat), status,
+				       &ptp_ctx->regs.dev_stat);
+}
+
+static int ptp_cipu_set_drv_version(struct ptp_cipu_ctx *ptp_ctx)
+{
+	struct ptp_cipu_regs *regs = &ptp_ctx->regs;
+	int version, patchlevel, sublevel;
+	u32 env_ver, drv_ver;
+	int rc;
+
+	if (sscanf(utsname()->release, "%u.%u.%u",
+		   &version, &patchlevel, &sublevel) != 3)
+		return -EINVAL;
+	sublevel = sublevel < 0xFF ? sublevel : 0xFF;
+
+	env_ver = (LINUX_UPSTREAM << 27) | (version << 16) |
+		  (patchlevel << 8) | sublevel;
+
+	rc = cipu_iowrite32_and_check(ptp_ctx->reg_addr +
+				      PTP_CIPU_REG(env_ver),
+				      env_ver, &regs->env_ver);
+	if (rc)
+		return rc;
+
+	drv_ver = (DRV_TYPE << 24) | (DRV_VER_MAJOR << 16) |
+		  (DRV_VER_MINOR << 8) | DRV_VER_SUBMINOR;
+
+	return cipu_iowrite32_and_check(ptp_ctx->reg_addr +
+					PTP_CIPU_REG(drv_ver), drv_ver,
+					&regs->drv_ver);
+}
+
+static int ptp_cipu_init_context(struct ptp_cipu_ctx *ptp_ctx)
+{
+	struct ptp_cipu_regs *regs = &ptp_ctx->regs;
+	void __iomem *reg_addr = ptp_ctx->reg_addr;
+	int rc = -ENOMEM;
+
+	spin_lock_init(&ptp_ctx->lock);
+	mutex_init(&ptp_ctx->sync_lock);
+	ptp_ctx->has_issue = 0;
+	INIT_DELAYED_WORK(&ptp_ctx->gen_timer, ptp_cipu_gen_timer);
+	INIT_DELAYED_WORK(&ptp_ctx->mt_timer, ptp_cipu_mt_timer);
+	INIT_WORK(&ptp_ctx->sync_work, ptp_cipu_sync_status_work);
+
+	ptp_ctx->stats = alloc_percpu(struct ptp_cipu_stats);
+	if (!ptp_ctx->stats)
+		return rc;
+
+	ptp_ctx->wq = alloc_workqueue("ptp-cipu-wq", 0, 0);
+	if (!ptp_ctx->wq)
+		goto out_stats;
+
+	rc = ptp_cipu_set_guest_features(ptp_ctx);
+	if (rc)
+		goto out_wq;
+
+	rc = ptp_cipu_set_drv_version(ptp_ctx);
+	if (rc)
+		goto out_wq;
+
+	regs->tm_prec_ns = ioread32(reg_addr + PTP_CIPU_REG(tm_prec_ns));
+	regs->max_lat_ns = ioread32(reg_addr + PTP_CIPU_REG(max_lat_ns));
+	regs->mt_tout_us = ioread32(reg_addr + PTP_CIPU_REG(mt_tout_us));
+	regs->thresh_us = ioread32(reg_addr + PTP_CIPU_REG(thresh_us));
+
+	if (regs->gst_feat & PTP_CIPU_M_FT_EPOCH) {
+		regs->epo_base_yr = ioread32(reg_addr +
+					    PTP_CIPU_REG(epo_base_yr));
+		ptp_ctx->epo_base_ns = NSEC_PER_SEC *
+				mktime64(regs->epo_base_yr, 1, 1, 0, 0, 0);
+	}
+
+	/* currently we don't support TAI */
+	if (regs->gst_feat & PTP_CIPU_M_FT_TAI)
+		regs->leap_sec = ioread32(reg_addr + PTP_CIPU_REG(leap_sec));
+
+	ptp_ctx->timer_ctx.thresh_us = regs->thresh_us;
+	queue_delayed_work(ptp_ctx->wq, &ptp_ctx->gen_timer,
+			   PTP_CIPU_TIMER_PERIOD);
+	return 0;
+
+out_wq:
+	destroy_workqueue(ptp_ctx->wq);
+out_stats:
+	free_percpu(ptp_ctx->stats);
+	return rc;
+}
+
+static void ptp_cipu_clear_context(struct ptp_cipu_ctx *ptp_ctx)
+{
+	disable_work_sync(&ptp_ctx->sync_work);
+	disable_delayed_work_sync(&ptp_ctx->gen_timer);
+	disable_delayed_work_sync(&ptp_ctx->mt_timer);
+	destroy_workqueue(ptp_ctx->wq);
+	free_percpu(ptp_ctx->stats);
+}
+
+#define REG_ATTR_RO(name) \
+static ssize_t reg_##name##_show(struct device *dev, \
+				 struct device_attribute *attr, char *buf) \
+{ \
+	struct ptp_cipu_ctx *ctx = pci_get_drvdata(to_pci_dev(dev)); \
+	struct ptp_cipu_regs *regs = &ctx->regs; \
+	return sysfs_emit(buf, "0x%x\n", regs->name); \
+} \
+static DEVICE_ATTR_RO(reg_##name)
+
+REG_ATTR_RO(dev_feat);
+REG_ATTR_RO(gst_feat);
+REG_ATTR_RO(drv_ver);
+REG_ATTR_RO(env_ver);
+REG_ATTR_RO(dev_stat);
+REG_ATTR_RO(sync_stat);
+REG_ATTR_RO(tm_prec_ns);
+REG_ATTR_RO(epo_base_yr);
+REG_ATTR_RO(leap_sec);
+REG_ATTR_RO(max_lat_ns);
+REG_ATTR_RO(mt_tout_us);
+REG_ATTR_RO(thresh_us);
+
+#define STATS_ATTR_RO(name, events, index) \
+static ssize_t name##_show(struct device *dev, \
+			   struct device_attribute *attr, char *buf) \
+{ \
+	struct ptp_cipu_ctx *ctx = pci_get_drvdata(to_pci_dev(dev)); \
+	struct ptp_cipu_stats *stats; \
+	u64 sum = 0; \
+	int cpu; \
+	for_each_possible_cpu(cpu) { \
+		stats = per_cpu_ptr(ctx->stats, cpu); \
+		sum += stats->events[index]; \
+	} \
+	return sysfs_emit(buf, "0x%llx\n", sum); \
+} \
+static DEVICE_ATTR_RO(name)
+
+#define PTP_STATS_ATTR_RO(name, index) \
+	STATS_ATTR_RO(name, ptp_evts, index)
+
+#define DEV_STATS_ATTR_RO(name, index) \
+	STATS_ATTR_RO(name, dev_evts, index)
+
+/* PTP events statistics */
+PTP_STATS_ATTR_RO(ptp_gettm, EVT_P_GT_OPS);
+PTP_STATS_ATTR_RO(ptp_gettm_inval_err, EVT_P_GT_INVAL);
+PTP_STATS_ATTR_RO(ptp_gettm_tout_err, EVT_P_GT_TOUT);
+PTP_STATS_ATTR_RO(ptp_gettm_excd_thresh, EVT_P_GT_ETHRESH);
+
+/* device events statistics */
+DEV_STATS_ATTR_RO(dev_clk_abn, EVT_H_CLK_ABN);
+DEV_STATS_ATTR_RO(dev_clk_abn_rec, EVT_H_CLK_ABN_REC);
+DEV_STATS_ATTR_RO(dev_maint, EVT_H_DEV_MT);
+DEV_STATS_ATTR_RO(dev_maint_rec, EVT_H_DEV_MT_REC);
+DEV_STATS_ATTR_RO(dev_maint_tout, EVT_H_DEV_MT_TOUT);
+DEV_STATS_ATTR_RO(dev_busy, EVT_H_DEV_BUSY);
+DEV_STATS_ATTR_RO(dev_busy_rec, EVT_H_DEV_BUSY_REC);
+DEV_STATS_ATTR_RO(dev_err, EVT_H_DEV_ERR);
+DEV_STATS_ATTR_RO(dev_err_rec, EVT_H_DEV_ERR_REC);
+
+static ssize_t drv_cap_show(struct device *dev,
+			    struct device_attribute *attr, char *buf)
+{
+	u32 drv_cap = PTP_CIPU_DRV_CAP;
+
+	return sysfs_emit(buf, "0x%04x\n", drv_cap);
+}
+static DEVICE_ATTR_RO(drv_cap);
+
+static struct attribute *ptp_cipu_attrs[] = {
+	&dev_attr_reg_dev_feat.attr,
+	&dev_attr_reg_gst_feat.attr,
+	&dev_attr_reg_drv_ver.attr,
+	&dev_attr_reg_env_ver.attr,
+	&dev_attr_reg_dev_stat.attr,
+	&dev_attr_reg_sync_stat.attr,
+	&dev_attr_reg_tm_prec_ns.attr,
+	&dev_attr_reg_epo_base_yr.attr,
+	&dev_attr_reg_leap_sec.attr,
+	&dev_attr_reg_max_lat_ns.attr,
+	&dev_attr_reg_mt_tout_us.attr,
+	&dev_attr_reg_thresh_us.attr,
+
+	&dev_attr_ptp_gettm.attr,
+	&dev_attr_ptp_gettm_inval_err.attr,
+	&dev_attr_ptp_gettm_tout_err.attr,
+	&dev_attr_ptp_gettm_excd_thresh.attr,
+
+	&dev_attr_dev_clk_abn.attr,
+	&dev_attr_dev_clk_abn_rec.attr,
+	&dev_attr_dev_maint.attr,
+	&dev_attr_dev_maint_rec.attr,
+	&dev_attr_dev_maint_tout.attr,
+	&dev_attr_dev_busy.attr,
+	&dev_attr_dev_busy_rec.attr,
+	&dev_attr_dev_err.attr,
+	&dev_attr_dev_err_rec.attr,
+
+	&dev_attr_drv_cap.attr,
+	NULL,
+};
+
+static const struct attribute_group ptp_cipu_attr_group = {
+	.attrs = ptp_cipu_attrs,
+	.name = "cipu",
+};
+
+static int ptp_cipu_init_sysfs(struct pci_dev *pdev)
+{
+	return sysfs_create_group(&pdev->dev.kobj, &ptp_cipu_attr_group);
+}
+
+static void ptp_cipu_remove_sysfs(struct pci_dev *pdev)
+{
+	sysfs_remove_group(&pdev->dev.kobj, &ptp_cipu_attr_group);
+}
+
+static int ptp_cipu_init_irq(struct ptp_cipu_ctx *ptp_ctx)
+{
+	struct pci_dev *pdev = ptp_ctx->pdev;
+	int i, rc;
+
+	rc = pci_alloc_irq_vectors(pdev, PTP_CIPU_IRQ_NUM,
+				   PTP_CIPU_IRQ_NUM, PCI_IRQ_MSIX);
+	if (rc < 0)
+		goto out;
+
+	for (i = 0; i < PTP_CIPU_IRQ_NUM; i++) {
+		rc = pci_request_irq(pdev, i, irq_ctx[i].irq_func, NULL,
+				     ptp_ctx, "ptp-cipu");
+		if (rc)
+			goto out_vec;
+	}
+	return 0;
+
+out_vec:
+	for (i = i - 1; i >= 0; i--)
+		pci_free_irq(pdev, i, ptp_ctx);
+	pci_free_irq_vectors(pdev);
+out:
+	return rc;
+}
+
+static void ptp_cipu_clear_irq(struct ptp_cipu_ctx *ptp_ctx)
+{
+	struct pci_dev *pdev = ptp_ctx->pdev;
+	int i;
+
+	for (i = 0; i < PTP_CIPU_IRQ_NUM; i++)
+		pci_free_irq(pdev, i, ptp_ctx);
+	pci_free_irq_vectors(pdev);
+}
+
+static int ptp_cipu_probe(struct pci_dev *pdev,
+			  const struct pci_device_id *id)
+{
+	struct ptp_cipu_ctx *ptp_ctx;
+	int rc;
+
+	ptp_ctx = kzalloc(sizeof(*ptp_ctx), GFP_KERNEL);
+	if (!ptp_ctx) {
+		rc = -ENOMEM;
+		PTP_DEV_ERR(&pdev->dev, EVT_TYPE_DRV, EVT_D_PROBE_FAIL,
+			    "Context Allocated Error: %d\n", rc);
+		return rc;
+	}
+	ptp_ctx->pdev = pdev;
+	pci_set_drvdata(pdev, ptp_ctx);
+
+	rc = pci_enable_device(pdev);
+	if (rc) {
+		PTP_DEV_ERR(&pdev->dev, EVT_TYPE_DRV, EVT_D_PROBE_FAIL,
+			    "PCI Device Enabled Fail: %d\n", rc);
+		goto out_mem;
+	}
+
+	ptp_ctx->reg_len = sizeof(struct ptp_cipu_regs);
+	ptp_ctx->reg_addr = pci_iomap(pdev, PTP_CIPU_BAR_0, ptp_ctx->reg_len);
+	if (!ptp_ctx->reg_addr) {
+		rc = -ENOMEM;
+		PTP_DEV_ERR(&pdev->dev, EVT_TYPE_DRV, EVT_D_PROBE_FAIL,
+			    "PCI IO Map Error: %d\n", rc);
+		goto out_enable;
+	}
+
+	rc = ptp_cipu_set_dev_status(ptp_ctx, PTP_CIPU_DEV_RESET);
+	if (rc) {
+		PTP_DEV_ERR(&pdev->dev, EVT_TYPE_DRV, EVT_D_PROBE_FAIL,
+			    "Initialize Device Status to %d Error: %d\n",
+			    PTP_CIPU_DEV_RESET, rc);
+		goto out_map;
+	}
+
+	rc = ptp_cipu_init_context(ptp_ctx);
+	if (rc) {
+		PTP_DEV_ERR(&pdev->dev, EVT_TYPE_DRV, EVT_D_PROBE_FAIL,
+			    "Initialize Context Error: %d\n", rc);
+		goto out_map;
+	}
+
+	rc = ptp_cipu_set_dev_status(ptp_ctx, PTP_CIPU_DEV_INIT);
+	if (rc) {
+		PTP_DEV_ERR(&pdev->dev, EVT_TYPE_DRV, EVT_D_PROBE_FAIL,
+			    "Initialize Device Status to %d Error: %d\n",
+			    PTP_CIPU_DEV_INIT, rc);
+		goto out_context;
+	}
+
+	rc = ptp_cipu_init_irq(ptp_ctx);
+	if (rc) {
+		PTP_DEV_ERR(&pdev->dev, EVT_TYPE_DRV, EVT_D_PROBE_FAIL,
+			    "Initialize IRQ Error: %d\n", rc);
+		goto out_reset;
+	}
+
+	rc = ptp_cipu_init_sysfs(pdev);
+	if (rc) {
+		PTP_DEV_ERR(&pdev->dev, EVT_TYPE_DRV, EVT_D_PROBE_FAIL,
+			    "Initialize Sysfs Error: %d\n", rc);
+		goto out_irq;
+	}
+
+	ptp_ctx->ptp_info = ptp_cipu_clock_info;
+	ptp_ctx->ptp_clock = ptp_clock_register(&ptp_ctx->ptp_info,
+						&pdev->dev);
+	if (IS_ERR(ptp_ctx->ptp_clock)) {
+		rc = PTR_ERR(ptp_ctx->ptp_clock);
+		PTP_DEV_ERR(&pdev->dev, EVT_TYPE_DRV, EVT_D_PROBE_FAIL,
+			    "PTP Clock Register Error: %d\n", rc);
+		goto out_sysfs;
+	}
+
+	/* all set, enable irqs */
+	rc = ptp_cipu_set_dev_status(ptp_ctx, PTP_CIPU_DEV_READY);
+	if (rc) {
+		PTP_DEV_ERR(&pdev->dev, EVT_TYPE_DRV, EVT_D_PROBE_FAIL,
+			    "Initialize Device Status to %d Error: %d\n",
+			    PTP_CIPU_DEV_READY, rc);
+		goto out_clock;
+	}
+
+	PTP_DEV_INFO(&pdev->dev, EVT_TYPE_DRV, EVT_D_GENERAL,
+		     "Alibaba CIPU PHC Driver Loaded, Version v%d.%d.%d\n",
+		     DRV_VER_MAJOR, DRV_VER_MINOR, DRV_VER_SUBMINOR);
+	return rc;
+
+out_clock:
+	ptp_clock_unregister(ptp_ctx->ptp_clock);
+out_sysfs:
+	ptp_cipu_remove_sysfs(pdev);
+out_irq:
+	ptp_cipu_clear_irq(ptp_ctx);
+out_reset:
+	ptp_cipu_set_dev_status(ptp_ctx, PTP_CIPU_DEV_RESET);
+out_context:
+	ptp_cipu_clear_context(ptp_ctx);
+out_map:
+	pci_iounmap(pdev, ptp_ctx->reg_addr);
+out_enable:
+	pci_disable_device(pdev);
+out_mem:
+	kfree(ptp_ctx);
+	ptp_ctx = NULL;
+	return rc;
+}
+
+static void ptp_cipu_remove(struct pci_dev *pdev)
+{
+	struct ptp_cipu_ctx *ptp_ctx = pci_get_drvdata(pdev);
+
+	ptp_clock_unregister(ptp_ctx->ptp_clock);
+	ptp_cipu_remove_sysfs(pdev);
+	ptp_cipu_set_dev_status(ptp_ctx, PTP_CIPU_DEV_RESET); /* disable irqs */
+	ptp_cipu_clear_irq(ptp_ctx);
+	ptp_cipu_clear_context(ptp_ctx); /* wait for timer/worker to finish */
+	pci_iounmap(pdev, ptp_ctx->reg_addr);
+	pci_disable_device(pdev);
+	kfree(ptp_ctx);
+	PTP_DEV_INFO(&pdev->dev, EVT_TYPE_DRV, EVT_D_GENERAL,
+		     "Alibaba CIPU PHC Driver Unloaded\n");
+}
+
+static const struct pci_device_id ptp_cipu_pci_tbl[] = {
+	{ PCI_DEVICE_SUB(PCI_VENDOR_ID_ALIBABA, 0x500C,
+			 PCI_VENDOR_ID_ALIBABA, 0x1123) },
+	{ }
+};
+MODULE_DEVICE_TABLE(pci, ptp_cipu_pci_tbl);
+
+static struct pci_driver ptp_cipu_driver = {
+	.name		= KBUILD_MODNAME,
+	.id_table	= ptp_cipu_pci_tbl,
+	.probe		= ptp_cipu_probe,
+	.remove		= ptp_cipu_remove,
+};
+
+static int __init ptp_cipu_init(void)
+{
+	return pci_register_driver(&ptp_cipu_driver);
+}
+
+static void __exit ptp_cipu_exit(void)
+{
+	pci_unregister_driver(&ptp_cipu_driver);
+}
+
+module_init(ptp_cipu_init);
+module_exit(ptp_cipu_exit);
+
+MODULE_DESCRIPTION("PTP clock for Alibaba CIPU");
+MODULE_AUTHOR("Wen Gu <guwen@linux.alibaba.com>");
+MODULE_LICENSE("GPL");
-- 
2.43.5

Re: [PATCH net-next v5 1/2] ptp: introduce Alibaba CIPU PHC driver

[Jakub Kicinski]

On Thu, 30 Oct 2025 20:13:13 +0800 Wen Gu wrote:
> This adds a driver for Alibaba CIPU PTP clock. The CIPU, an underlying
> infrastructure of Alibaba Cloud, synchronizes time with atomic clocks
> via the network and provides microsecond or sub-microsecond precision
> timestamps for VMs and bare metals on cloud.
> 
> User space processes, such as chrony, running in VMs or on bare metals
> can get the high precision time through the PTP device exposed by this
> driver.

As mentioned on previous revisions this is a pure clock device which has
nothing to do with networking and PTP. There should be a separate class
for "hypervisor clocks", if not a common driver.
-- 
pw-bot: cr

Re: [PATCH net-next v5 1/2] ptp: introduce Alibaba CIPU PHC driver

[Wen Gu]

On 2025/11/1 07:58, Jakub Kicinski wrote:
> On Thu, 30 Oct 2025 20:13:13 +0800 Wen Gu wrote:
>> This adds a driver for Alibaba CIPU PTP clock. The CIPU, an underlying
>> infrastructure of Alibaba Cloud, synchronizes time with atomic clocks
>> via the network and provides microsecond or sub-microsecond precision
>> timestamps for VMs and bare metals on cloud.
>>
>> User space processes, such as chrony, running in VMs or on bare metals
>> can get the high precision time through the PTP device exposed by this
>> driver.
> 
> As mentioned on previous revisions this is a pure clock device which has
> nothing to do with networking and PTP.

I don't quite agree that this has nothing to do with PTP.

What is the difference between this CIPU PTP driver and other PTP drivers
under drivers/ptp? such as ptp_s390, ptp_vmw, ptp_pch, and others. Most of
these PTP drivers do not directly involve IEEE 1588 or networking as well.

> There should be a separate class
> for "hypervisor clocks", if not a common driver.

'hypervisor clock' is not very accurate. CIPU PTP can be used in VM and
bare metal scenarios, and bare metals do not need hypervisors.

Regards.

Re: [PATCH net-next v5 1/2] ptp: introduce Alibaba CIPU PHC driver

[Jakub Kicinski]

On Wed, 5 Nov 2025 18:22:19 +0800 Wen Gu wrote:
> On 2025/11/1 07:58, Jakub Kicinski wrote:
> > On Thu, 30 Oct 2025 20:13:13 +0800 Wen Gu wrote:  
> >> This adds a driver for Alibaba CIPU PTP clock. The CIPU, an underlying
> >> infrastructure of Alibaba Cloud, synchronizes time with atomic clocks
> >> via the network and provides microsecond or sub-microsecond precision
> >> timestamps for VMs and bare metals on cloud.
> >>
> >> User space processes, such as chrony, running in VMs or on bare metals
> >> can get the high precision time through the PTP device exposed by this
> >> driver.  
> > 
> > As mentioned on previous revisions this is a pure clock device which has
> > nothing to do with networking and PTP.  
> 
> I don't quite agree that this has nothing to do with PTP.
> 
> What is the difference between this CIPU PTP driver and other PTP drivers
> under drivers/ptp? such as ptp_s390, ptp_vmw, ptp_pch, and others. Most of
> these PTP drivers do not directly involve IEEE 1588 or networking as well.

We can't delete existing drivers. It used to be far less annoying
until every cloud vendor under the sun decided to hack up their own
implementation of something as simple as the clock.

> > There should be a separate class
> > for "hypervisor clocks", if not a common driver.  
> 
> 'hypervisor clock' is not very accurate. CIPU PTP can be used in VM and
> bare metal scenarios, and bare metals do not need hypervisors.

I know.

Re: [PATCH net-next v5 1/2] ptp: introduce Alibaba CIPU PHC driver

[Wen Gu]

On 2025/11/6 08:24, Jakub Kicinski wrote:
> On Wed, 5 Nov 2025 18:22:19 +0800 Wen Gu wrote:
>> On 2025/11/1 07:58, Jakub Kicinski wrote:
>>> On Thu, 30 Oct 2025 20:13:13 +0800 Wen Gu wrote:
>>>> This adds a driver for Alibaba CIPU PTP clock. The CIPU, an underlying
>>>> infrastructure of Alibaba Cloud, synchronizes time with atomic clocks
>>>> via the network and provides microsecond or sub-microsecond precision
>>>> timestamps for VMs and bare metals on cloud.
>>>>
>>>> User space processes, such as chrony, running in VMs or on bare metals
>>>> can get the high precision time through the PTP device exposed by this
>>>> driver.
>>>
>>> As mentioned on previous revisions this is a pure clock device which has
>>> nothing to do with networking and PTP.
>>
>> I don't quite agree that this has nothing to do with PTP.
>>
>> What is the difference between this CIPU PTP driver and other PTP drivers
>> under drivers/ptp? such as ptp_s390, ptp_vmw, ptp_pch, and others. Most of
>> these PTP drivers do not directly involve IEEE 1588 or networking as well.
> 

Sorry for the late reply due to a vacation.

> We can't delete existing drivers. It used to be far less annoying
> until every cloud vendor under the sun decided to hack up their own
> implementation of something as simple as the clock.
> 

So what kind of drivers do you think are qualified to be placed in the
drivers/ptp? I checked some docs, e.g.[1], and codes in drivers/ptp,
but I am not sure what the deciding factor is, assuming that exposing
a PTP character device is not sufficient.

[1] https://docs.kernel.org/driver-api/ptp.html

Regards.

>>> There should be a separate class
>>> for "hypervisor clocks", if not a common driver.
>>
>> 'hypervisor clock' is not very accurate. CIPU PTP can be used in VM and
>> bare metal scenarios, and bare metals do not need hypervisors.
> 
> I know.

Re: [PATCH net-next v5 1/2] ptp: introduce Alibaba CIPU PHC driver

[Jakub Kicinski]

On Thu, 27 Nov 2025 13:48:47 +0800 Wen Gu wrote:
> > We can't delete existing drivers. It used to be far less annoying
> > until every cloud vendor under the sun decided to hack up their own
> > implementation of something as simple as the clock.
> 
> So what kind of drivers do you think are qualified to be placed in the
> drivers/ptp? I checked some docs, e.g.[1], and codes in drivers/ptp,
> but I am not sure what the deciding factor is, assuming that exposing
> a PTP character device is not sufficient.
> 
> [1] https://docs.kernel.org/driver-api/ptp.html

Networking ones? I don't have a great answer. My point is basically
that we are networking maintainers. I have a good understanding of PTP
(the actual protocol) and TSN as these are networking technologies.
But I don't feel qualified to review purely time / clock related code.
I don't even know the UNIX/Linux clock API very well.

Sorry to put you in this position but the VM clocks should have some
other tree. Or at the very least some clock expert needs to review them.

Could you go complain to clock people? Or virtualization people?

Re: [PATCH net-next v5 1/2] ptp: introduce Alibaba CIPU PHC driver

[Wen Gu]

On 2025/11/28 00:36, Jakub Kicinski wrote:
> On Thu, 27 Nov 2025 13:48:47 +0800 Wen Gu wrote:
>>> We can't delete existing drivers. It used to be far less annoying
>>> until every cloud vendor under the sun decided to hack up their own
>>> implementation of something as simple as the clock.
>>
>> So what kind of drivers do you think are qualified to be placed in the
>> drivers/ptp? I checked some docs, e.g.[1], and codes in drivers/ptp,
>> but I am not sure what the deciding factor is, assuming that exposing
>> a PTP character device is not sufficient.
>>
>> [1] https://docs.kernel.org/driver-api/ptp.html
> 
> Networking ones? I don't have a great answer. My point is basically
> that we are networking maintainers. I have a good understanding of PTP
> (the actual protocol) and TSN as these are networking technologies.
> But I don't feel qualified to review purely time / clock related code.
> I don't even know the UNIX/Linux clock API very well.
> 

Searching the codebase for ptp_clock_register() shows that the PTP
implementations that related to the networking (IEEE 1588) are directly
embedded in the NIC drivers (drivers/net), e.g. ena_phc.c, ice_ptp.c,
igb_ptp.c, instead of being in drivers/ptp.

Most drivers under drivers/ptp are not directly related to networking
and operate independently of NICs. They maintain accuracy through their
own mechanisms.

> Sorry to put you in this position but the VM clocks should have some
> other tree. Or at the very least some clock expert needs to review them.
> 

I noticed you emphasized 'VM clock', but I don’t think it really matters
whether it’s a VM/cloud scenario or not. IMHO whether the PHC is provided
by a chip, FPGA, hypervisor or CIPU makes no fundamental difference.

> Could you go complain to clock people? Or virtualization people?

I understand that the PTP implementations in drivers/ptp aren't closely
related to networking though drivers/ptp is included in NETWORKING DRIVERS
in the MAINTAINER file.

I noticed that drivers/ptp/* is also inclued in PTP HARDWARE CLOCK SUPPORT.
This attribution seems more about 'clock'.

Hi @Richard Cochran, could you please review this? Thanks! :)

Regards.

Re: [PATCH net-next v5 1/2] ptp: introduce Alibaba CIPU PHC driver

[Jakub Kicinski]

On Fri, 28 Nov 2025 14:22:21 +0800 Wen Gu wrote:
> > Could you go complain to clock people? Or virtualization people?  
> 
> I understand that the PTP implementations in drivers/ptp aren't closely
> related to networking though drivers/ptp is included in NETWORKING DRIVERS
> in the MAINTAINER file.
> 
> I noticed that drivers/ptp/* is also inclued in PTP HARDWARE CLOCK SUPPORT.
> This attribution seems more about 'clock'.
> 
> Hi @Richard Cochran, could you please review this? Thanks! :)

It's Thanksgiving weekend in the US, Richard may be AFK so excuse my
speaking for him, but he mentioned in the past that he is also not
interested in becoming a maintainer for general clocks, unrelated 
to PTP.

Search the mailing list, there are at least 3 drivers like yours being
proposed. Maybe you can get together with also the KVM and VMclock
authors and form a new subsystem?

Re: [PATCH net-next v5 1/2] ptp: introduce Alibaba CIPU PHC driver

[Wen Gu]

On 2025/11/29 02:24, Jakub Kicinski wrote:
> On Fri, 28 Nov 2025 14:22:21 +0800 Wen Gu wrote:
>>> Could you go complain to clock people? Or virtualization people?
>>
>> I understand that the PTP implementations in drivers/ptp aren't closely
>> related to networking though drivers/ptp is included in NETWORKING DRIVERS
>> in the MAINTAINER file.
>>
>> I noticed that drivers/ptp/* is also inclued in PTP HARDWARE CLOCK SUPPORT.
>> This attribution seems more about 'clock'.
>>
>> Hi @Richard Cochran, could you please review this? Thanks! :)
> 
> It's Thanksgiving weekend in the US, Richard may be AFK so excuse my
> speaking for him, but he mentioned in the past that he is also not
> interested in becoming a maintainer for general clocks, unrelated
> to PTP.
> 

Wishing you a Happy Thanksgiving!

I think you misunderstood. I didn't encourage Richard to maintain
general clocks unrelated to PTP. Rather, I believe this driver should
belong to the PTP subsystem, and here are my reasons (which have been
mentioned in previous emails):

1. CIPU provides high-precision PHCs for VMs or bare metals, which
    are exposed as ptp_clock according to the definition in [1]. its
    usage is no different from other ptp devices. So this is a PTP
    driver.

[1] https://docs.kernel.org/driver-api/ptp.html

2. The PTP implementations that are independent of networking and
    NICs are placed under drivers/ptp. These devices are provided from
    chip/FPGA/hypervisor and maintain clock accuracy in their own unique
    ways. CIPU ptp driver is no different and should also be placed
    under the drivers/ptp from this perspective.

According to the MAINTAINERS file, drivers/ptp/* is maintained by the
NETWORKING DRIVERS and PTP HARDWARE CLOCK SUPPORT subsystems. Considering
you mentioned that drivers/ptp is not closely related to networking, I
think it might be more appropriate for the PTP HARDWARE CLOCK SUPPORT
subsystem maintainer to review it. After it merges into the upstream,
we will be its maintainers.

> Search the mailing list, there are at least 3 drivers like yours being
> proposed. Maybe you can get together with also the KVM and VMclock
> authors and form a new subsystem?

I think drivers under drivers/ptp are all similar. But aside from the
fact that they are all exposed as PTP devices and therefore classified
in the PTP subsystem, I haven't been able to find a way to classify
them into another class (note that CIPU ptp can't be considered a
VM/hypervisor clock class since bare metal scenario is also applicable).

Regards.

Re: [PATCH net-next v5 1/2] ptp: introduce Alibaba CIPU PHC driver

[Wen Gu]

On 2025/12/1 14:04, Wen Gu wrote:
> 
> 
> On 2025/11/29 02:24, Jakub Kicinski wrote:
>> On Fri, 28 Nov 2025 14:22:21 +0800 Wen Gu wrote:
>>>> Could you go complain to clock people? Or virtualization people?
>>>
>>> I understand that the PTP implementations in drivers/ptp aren't closely
>>> related to networking though drivers/ptp is included in NETWORKING DRIVERS
>>> in the MAINTAINER file.
>>>
>>> I noticed that drivers/ptp/* is also inclued in PTP HARDWARE CLOCK SUPPORT.
>>> This attribution seems more about 'clock'.
>>>
>>> Hi @Richard Cochran, could you please review this? Thanks! :)
>>
>> It's Thanksgiving weekend in the US, Richard may be AFK so excuse my
>> speaking for him, but he mentioned in the past that he is also not
>> interested in becoming a maintainer for general clocks, unrelated
>> to PTP.
>>
> 
> Wishing you a Happy Thanksgiving!
> 
> I think you misunderstood. I didn't encourage Richard to maintain
> general clocks unrelated to PTP. Rather, I believe this driver should
> belong to the PTP subsystem, and here are my reasons (which have been
> mentioned in previous emails):
> 
> 1. CIPU provides high-precision PHCs for VMs or bare metals, which
>     are exposed as ptp_clock according to the definition in [1]. its
>     usage is no different from other ptp devices. So this is a PTP
>     driver.
> 
> [1] https://docs.kernel.org/driver-api/ptp.html
> 
> 2. The PTP implementations that are independent of networking and
>     NICs are placed under drivers/ptp. These devices are provided from
>     chip/FPGA/hypervisor and maintain clock accuracy in their own unique
>     ways. CIPU ptp driver is no different and should also be placed
>     under the drivers/ptp from this perspective.
> 
> According to the MAINTAINERS file, drivers/ptp/* is maintained by the
> NETWORKING DRIVERS and PTP HARDWARE CLOCK SUPPORT subsystems. Considering
> you mentioned that drivers/ptp is not closely related to networking, I
> think it might be more appropriate for the PTP HARDWARE CLOCK SUPPORT
> subsystem maintainer to review it. After it merges into the upstream,
> we will be its maintainers.
> 
>> Search the mailing list, there are at least 3 drivers like yours being
>> proposed. Maybe you can get together with also the KVM and VMclock
>> authors and form a new subsystem?
> 
> I think drivers under drivers/ptp are all similar. But aside from the
> fact that they are all exposed as PTP devices and therefore classified
> in the PTP subsystem, I haven't been able to find a way to classify
> them into another class (note that CIPU ptp can't be considered a
> VM/hypervisor clock class since bare metal scenario is also applicable).
> 
> Regards.


Given that net-next is closed and the EOY break is here, I was wondering
whether the review discussion might continue during this period or should
wait until after the break.

Thanks.

Re: [PATCH net-next v5 1/2] ptp: introduce Alibaba CIPU PHC driver

[Jakub Kicinski]

On Fri, 12 Dec 2025 14:50:13 +0800 Wen Gu wrote:
> Given that net-next is closed and the EOY break is here, I was wondering
> whether the review discussion might continue during this period or should
> wait until after the break.

This is a somewhat frustrating thing to hear. My position is that
net-next is not the right home for this work, so its status should 
be irrelevant.

Re: [PATCH net-next v5 1/2] ptp: introduce Alibaba CIPU PHC driver

[Wen Gu]

On 2025/12/13 06:50, Jakub Kicinski wrote:
> On Fri, 12 Dec 2025 14:50:13 +0800 Wen Gu wrote:
>> Given that net-next is closed and the EOY break is here, I was wondering
>> whether the review discussion might continue during this period or should
>> wait until after the break.
> 
> This is a somewhat frustrating thing to hear. My position is that
> net-next is not the right home for this work, so its status should
> be irrelevant.

Hi Jakub, I'm sorry, but I still don't understand why you object to
this being a PTP clock driver and to placing it under `drivers/ptp`.
Could you please explain your reasons?

You mentioned that it's unrelated to networking, but most of the drivers
under `drivers/ptp` are also unrelated to networking. PTP implementations
that are independent of network drivers are placed here.

If the PTP HARDWARE CLOCK SUPPORT maintainers don't review it, which
subsystem should I go to?

If you're suggesting creating a new subsystem, I think we should first
answer this question: why can't it be part of the current ptp subsystem,
and what are the differences between the drivers under `drivers/ptp`
and those in the new subsystem?

Thanks, and sorry for bothering you during your EOY break.

Regards.

Re: [PATCH net-next v5 1/2] ptp: introduce Alibaba CIPU PHC driver

[Jakub Kicinski]

On Sun, 14 Dec 2025 22:03:57 +0800 Wen Gu wrote:
> If you're suggesting creating a new subsystem, I think we should first
> answer this question: why can't it be part of the current ptp subsystem,
> and what are the differences between the drivers under `drivers/ptp`
> and those in the new subsystem?

I can't explain it any better than I already did here:
https://lore.kernel.org/all/20251127083610.6b66a728@kernel.org/

I talked to Thomas Gleixner (added to CC) during LPC and he seemed
open to creating a PHC subsystem for pure time devices in virtualized
environments. Please work with him and other vendors trying to
upstream similar drivers.

Re: [PATCH net-next v5 1/2] ptp: introduce Alibaba CIPU PHC driver

[Wen Gu]

On 2025/12/17 05:58, Jakub Kicinski wrote:

> I talked to Thomas Gleixner (added to CC) during LPC and he seemed
> open to creating a PHC subsystem for pure time devices in virtualized
> environments. Please work with him and other vendors trying to
> upstream similar drivers.

Thank you for your patience and help.

I’ll work with Thomas and other potential vendors, likely starting with
an RFC to collect ideas and reach consensus on a dedicated subsystem for
PHC in non-NIC scenarios.

Regards.

Re: [PATCH net-next v5 1/2] ptp: introduce Alibaba CIPU PHC driver

[Wen Gu]

On 2025/12/17 05:58, Jakub Kicinski wrote:
> On Sun, 14 Dec 2025 22:03:57 +0800 Wen Gu wrote:
>> If you're suggesting creating a new subsystem, I think we should first
>> answer this question: why can't it be part of the current ptp subsystem,
>> and what are the differences between the drivers under `drivers/ptp`
>> and those in the new subsystem?
> 
> I can't explain it any better than I already did here:
> https://lore.kernel.org/all/20251127083610.6b66a728@kernel.org/
> 
> I talked to Thomas Gleixner (added to CC) during LPC and he seemed
> open to creating a PHC subsystem for pure time devices in virtualized
> environments. Please work with him and other vendors trying to
> upstream similar drivers.

Hi Jakub and Thomas,

I thought about it a bit more. If we create a new clock class
(say a "ptc"), its helpers and structure would likely end up being
almost identical to the current ptp ones, since the pure phc drivers
under drivers/ptp (e.g. ptp_kvm, ptp_vmw, ptp_s390, ptp_cipu) are
implemented on top of the existing ptp helpers. That would give us
two near-identical classes, which may be confusing.

Also, changing the userspace device node for existing pure phc drivers
from /dev/ptpX to something else (e.g. /dev/ptcX) seems impractical.
The same applies to ptp_cipu, since it is already used and relies on
exposing /dev/ptpX.

Given the historical baggage, it seems better to keep using the
existing ptp framework, but separate these pure phc drivers into a
new subsystem with a dedicated directory (e.g. drivers/phc/) and a
MAINTAINERS entry, moving them out of the netdev maintenance scope.
This should also address the concern that these pure phc drivers are
not a good fit to be maintained under the networking subsystem.

If this works for you, I'll send an RFC about this.

Regards.

Re: [PATCH net-next v5 1/2] ptp: introduce Alibaba CIPU PHC driver

[David Woodhouse]

[-- Attachment #1: Type: text/plain, Size: 2798 bytes --]

On Wed, 2025-11-05 at 16:24 -0800, Jakub Kicinski wrote:
> On Wed, 5 Nov 2025 18:22:19 +0800 Wen Gu wrote:
> > On 2025/11/1 07:58, Jakub Kicinski wrote:
> > > On Thu, 30 Oct 2025 20:13:13 +0800 Wen Gu wrote:  
> > > > This adds a driver for Alibaba CIPU PTP clock. The CIPU, an underlying
> > > > infrastructure of Alibaba Cloud, synchronizes time with atomic clocks
> > > > via the network and provides microsecond or sub-microsecond precision
> > > > timestamps for VMs and bare metals on cloud.
> > > > 
> > > > User space processes, such as chrony, running in VMs or on bare metals
> > > > can get the high precision time through the PTP device exposed by this
> > > > driver.  
> > > 
> > > As mentioned on previous revisions this is a pure clock device which has
> > > nothing to do with networking and PTP.  
> > 
> > I don't quite agree that this has nothing to do with PTP.
> > 
> > What is the difference between this CIPU PTP driver and other PTP drivers
> > under drivers/ptp? such as ptp_s390, ptp_vmw, ptp_pch, and others. Most of
> > these PTP drivers do not directly involve IEEE 1588 or networking as well.
> 
> We can't delete existing drivers. It used to be far less annoying
> until every cloud vendor under the sun decided to hack up their own
> implementation of something as simple as the clock.

Heh. In my defence, I hacked up a new one because none of the existing
options (including the KVM abomination) were any use. None of them
allow guests to rely on accurate time across live migration.

VMClock is designed specifically to solve that problem. It's now
published at https://uapi-group.org/specifications/specs/vmclock/ and
although the primary target is virtual machines, it discusses how it
could be used to build a hardware implementation using PCIe PTM.

As well as obviously implementing it in $DAYJOB, we added it to QEMU.

Although it *can* be used as a PHC providing a paired TAI timestamp, it
actually provides a y=mx+c relationship between the CPU counter (e.g.
TSC) and real time, not just a timestamp at a given point in time.

I'd like to integrate it as a first-class citizen in kernel
timekeeping, so that the kernel can directly both consume it, *and*
export the kernel's CLOCK_REALTIME to KVM guests.

I don't care what happens to the legacy snapshot-only ones though;
those can all go away as far as I'm concerned. I'd suggest that now
it's possible to do it *right*, there shouldn't be any *more* of the
legacy ones.

Having said that, it does seem rather harsh to refuse to accept this
one when there are so many other examples already in the tree. I'd
suggest that we accept it and then it can be moved to the new setup,
whatever that is, along with the other legacy snapshot-only PHCs.


[-- Attachment #2: smime.p7s --]
[-- Type: application/pkcs7-signature, Size: 5069 bytes --]

Re: [PATCH net-next v5 1/2] ptp: introduce Alibaba CIPU PHC driver

[Wen Gu]

On 2025/12/18 20:28, David Woodhouse wrote:

> 
> Having said that, it does seem rather harsh to refuse to accept this
> one when there are so many other examples already in the tree. I'd
> suggest that we accept it and then it can be moved to the new setup,
> whatever that is, along with the other legacy snapshot-only PHCs.
> 

That's also my thought.

That said, I'm open to either: accept it and re-home these similar
drivers when we have a better setup, or agree on a dedicated "pure
PHC" subsystem now and then merge it there.

Regards.

[PATCH net-next v5 2/2] ptp: add sysfs documentation for Alibaba CIPU PHC driver

[Wen Gu]

This adds documentation for the sysfs files exposed by the Alibaba
CIPU PHC driver.

Signed-off-by: Wen Gu <guwen@linux.alibaba.com>
---
 .../ABI/testing/sysfs-ptp-devices-cipu        | 227 ++++++++++++++++++
 MAINTAINERS                                   |   1 +
 2 files changed, 228 insertions(+)
 create mode 100644 Documentation/ABI/testing/sysfs-ptp-devices-cipu

diff --git a/Documentation/ABI/testing/sysfs-ptp-devices-cipu b/Documentation/ABI/testing/sysfs-ptp-devices-cipu
new file mode 100644
index 000000000000..0abf2fb8eb1e
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-ptp-devices-cipu
@@ -0,0 +1,227 @@
+What:           /sys/class/ptp/ptp<N>/device/cipu/ptp_gettm
+Date:           October 2025
+Contact:        Wen Gu <guwen@linux.alibaba.com>
+Description:
+                Count of PTP gettime64 and gettimex64 operations performed
+                on the Alibaba CIPU PTP device.
+
+What:           /sys/class/ptp/ptp<N>/device/cipu/ptp_gettm_inval_err
+Date:           October 2025
+Contact:        Wen Gu <guwen@linux.alibaba.com>
+Description:
+                Count of failed PTP gettime64 or gettimex64 operations due
+                to invalid timestamp.
+
+                Invalid timestamps are indicated by bit63 (PTP_CIPU_M_TS_ABN)
+                in the timestamp register being set.
+
+                The driver will also trigger device status check when this
+                occurs.
+
+What:           /sys/class/ptp/ptp<N>/device/cipu/ptp_gettm_tout_err
+Date:           October 2025
+Contact:        Wen Gu <guwen@linux.alibaba.com>
+Description:
+                Count of failed PTP gettime64 or gettimex64 operations due
+                to register read timeout (exceeding max_lat_ns).
+
+What:           /sys/class/ptp/ptp<N>/device/cipu/ptp_gettm_excd_thresh
+Date:           October 2025
+Contact:        Wen Gu <guwen@linux.alibaba.com>
+Description:
+                Count of times system time and PHC time offset exceeded
+                the configured threshold (thresh_us).
+
+                This is only recorded and does not affect the returned
+                timestamp.
+
+What:           /sys/class/ptp/ptp<N>/device/cipu/dev_clk_abn
+Date:           October 2025
+Contact:        Wen Gu <guwen@linux.alibaba.com>
+Description:
+                Count of atomic clock abnormal events (bit1 set in sync_stat).
+
+What:           /sys/class/ptp/ptp<N>/device/cipu/dev_clk_abn_rec
+Date:           October 2025
+Contact:        Wen Gu <guwen@linux.alibaba.com>
+Description:
+                Count of recovery from atomic clock abnormal events (bit1
+                cleared in sync_stat after being set).
+
+What:           /sys/class/ptp/ptp<N>/device/cipu/dev_maint
+Date:           October 2025
+Contact:        Wen Gu <guwen@linux.alibaba.com>
+Description:
+                Count of maintenance events (bit0 set in sync_stat).
+
+What:           /sys/class/ptp/ptp<N>/device/cipu/dev_maint_rec
+Date:           October 2025
+Contact:        Wen Gu <guwen@linux.alibaba.com>
+Description:
+                Count of recovery from maintenance events (bit0 cleared
+                in sync_stat).
+
+What:           /sys/class/ptp/ptp<N>/device/cipu/dev_maint_tout
+Date:           October 2025
+Contact:        Wen Gu <guwen@linux.alibaba.com>
+Description:
+                Count of maintenance events that failed to recover within
+                mt_tout_us timeout.
+
+What:           /sys/class/ptp/ptp<N>/device/cipu/dev_busy
+Date:           October 2025
+Contact:        Wen Gu <guwen@linux.alibaba.com>
+Description:
+                Count of device busy events (bit4 set in sync_stat).
+
+What:           /sys/class/ptp/ptp<N>/device/cipu/dev_busy_rec
+Date:           October 2025
+Contact:        Wen Gu <guwen@linux.alibaba.com>
+Description:
+                Count of recovery from device busy events (bit4 cleared
+                in sync_stat).
+
+What:           /sys/class/ptp/ptp<N>/device/cipu/dev_err
+Date:           October 2025
+Contact:        Wen Gu <guwen@linux.alibaba.com>
+Description:
+                Count of device error events (bit7 set in sync_stat).
+
+What:           /sys/class/ptp/ptp<N>/device/cipu/dev_err_rec
+Date:           October 2025
+Contact:        Wen Gu <guwen@linux.alibaba.com>
+Description:
+                Count of recovery from device error events (bit7 cleared
+                in sync_stat).
+
+What:           /sys/class/ptp/ptp<N>/device/cipu/drv_cap
+Date:           October 2025
+Contact:        Wen Gu <guwen@linux.alibaba.com>
+Description:
+                Driver capabilities bitmask (u32):
+
+                ========  ============================
+                bit 0     support TAI time mode
+                bit 1     support epoch base time mode
+                bit 2     support abnormal event IRQ
+                bit 3     support recovery event IRQ
+                bit 31:4  reserved
+                ========  ============================
+
+                Currently TAI time mode (bit0) is not supported.
+
+What:           /sys/class/ptp/ptp<N>/device/cipu/reg_dev_feat
+Date:           October 2025
+Contact:        Wen Gu <guwen@linux.alibaba.com>
+Description:
+                Device feature bitmask, same bit definitions as drv_cap.
+
+What:           /sys/class/ptp/ptp<N>/device/cipu/reg_gst_feat
+Date:           October 2025
+Contact:        Wen Gu <guwen@linux.alibaba.com>
+Description:
+                Feature bitmask negotiated by driver and device, same
+                bit definitions as drv_cap but only features supported
+                by both device and driver are set.
+
+What:           /sys/class/ptp/ptp<N>/device/cipu/reg_drv_ver
+Date:           October 2025
+Contact:        Wen Gu <guwen@linux.alibaba.com>
+Description:
+                Driver version encoding (u32):
+
+                =========  ===================
+                bit 7:0    subminor version
+                bit 15:8   minor version
+                bit 23:16  major version
+                bit 24     0 for intree driver
+                bit 31:25  reserved
+                =========  ===================
+
+What:           /sys/class/ptp/ptp<N>/device/cipu/reg_env_ver
+Date:           October 2025
+Contact:        Wen Gu <guwen@linux.alibaba.com>
+Description:
+                Environment encoding (u32):
+
+                =========  =======================
+                bit 7:0    kernel patchlevel
+                bit 15:8   kernel sublevel
+                bit 23:16  kernel version
+                bit 26:24  reserved
+                bit 31:27  0x1F for Linux upstream
+                =========  =======================
+
+What:           /sys/class/ptp/ptp<N>/device/cipu/reg_dev_stat
+Date:           October 2025
+Contact:        Wen Gu <guwen@linux.alibaba.com>
+Description:
+                Device status (u8):
+
+                =  =========================================
+                0  RESET, device reset
+                1  FEATURE_OK, feature negotiation complete
+                2  DRIVER_OK, fully configured, ready to use
+                =  =========================================
+
+What:           /sys/class/ptp/ptp<N>/device/cipu/reg_sync_stat
+Date:           October 2025
+Contact:        Wen Gu <guwen@linux.alibaba.com>
+Description:
+                Device sync status bitmask (u8):
+
+                =====  =====================
+                bit 0  maintenance
+                bit 1  atomic clock abnormal
+                bit 4  device busy
+                bit 7  device error
+                =====  =====================
+
+                other bits are reserved.
+
+What:           /sys/class/ptp/ptp<N>/device/cipu/reg_tm_prec_ns
+Date:           October 2025
+Contact:        Wen Gu <guwen@linux.alibaba.com>
+Description:
+                Time precision reported by device, in nanoseconds (u32).
+
+What:           /sys/class/ptp/ptp<N>/device/cipu/reg_epo_base_yr
+Date:           October 2025
+Contact:        Wen Gu <guwen@linux.alibaba.com>
+Description:
+                Epoch base year used when epoch mode is enabled (u32).
+
+What:           /sys/class/ptp/ptp<N>/device/cipu/reg_leap_sec
+Date:           October 2025
+Contact:        Wen Gu <guwen@linux.alibaba.com>
+Description:
+                Leap seconds offset reported by device, in seconds (u32).
+
+What:           /sys/class/ptp/ptp<N>/device/cipu/reg_max_lat_ns
+Date:           October 2025
+Contact:        Wen Gu <guwen@linux.alibaba.com>
+Description:
+                Maximum device register read latency tolerated,
+                in nanoseconds (u32).
+
+                Exceeding this is treated as timeout. e.g. see
+                ptp_gettm_tout_err.
+
+What:           /sys/class/ptp/ptp<N>/device/cipu/reg_mt_tout_us
+Date:           October 2025
+Contact:        Wen Gu <guwen@linux.alibaba.com>
+Description:
+                Maintenance recovery timeout in microseconds (u32).
+
+                If exceeded while maintenance status is set, reported as
+                dev_maint_tout event.
+
+What:           /sys/class/ptp/ptp<N>/device/cipu/reg_thresh_us
+Date:           October 2025
+Contact:        Wen Gu <guwen@linux.alibaba.com>
+Description:
+                Threshold (u32, in microseconds) for acceptable
+                PHC vs system time offset.
+
+                Exceeding this only increments ptp_gettm_excd_thresh
+                counter.
diff --git a/MAINTAINERS b/MAINTAINERS
index b1543fcd12ea..1a4f4a2a96ce 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -800,6 +800,7 @@ M:	Wen Gu <guwen@linux.alibaba.com>
 M:	Xuan Zhuo <xuanzhuo@linux.alibaba.com>
 L:	netdev@vger.kernel.org
 S:	Supported
+F:	Documentation/ABI/testing/sysfs-ptp-devices-cipu
 F:	drivers/ptp/ptp_cipu.c
 
 ALIBABA ELASTIC RDMA DRIVER
-- 
2.43.5