On Fri, 2026-01-09 at 10:56 +0800, Wen Gu wrote:

Hi all,

This is an RFC to discuss the appropriate upstream home and maintenance
model for a class of devices/drivers which expose a high-precision clock
to userspace via the existing PHC interface (/dev/ptpX + standard PTP_*
ioctls), but are not tied to a traditional NIC/IEEE1588 packet
timestamping pipeline.

Examples already in the tree include (non-exhaustive):

- drivers/ptp/ptp_kvm.c [1]
- drivers/ptp/ptp_vmw.c [2]
- drivers/ptp/ptp_s390.c [3]

There are also examples living in their respective subsystem (out of
scope for this RFC),
e.g. drivers/hv/hv_util.c [4] and drivers/virtio/virtio_rtc_ptp.c [5].

We (Alibaba Cloud) also posted a driver for a CIPU-provided high-precision
clock for review [6]. Based on existing in-tree precedent, we placed it
under drivers/ptp/ and sent it to the netdev list.

During review, concerns were raised that such "non-NIC / pure" PHC drivers
are not a good fit for netdev maintainership [7], since they are primarily
time/clock devices rather than networking protocol features.

As a result, I’m sending this RFC to align on a consistent upstream home
and maintainer model for this class of drivers, both for the existing ones
and future additions.

#
## Observation 1: PHC core/API are already not bound to NIC/IEEE1588
#

Although PHC support is original associated with NIC-based IEEE 1588
timestamping, the kernel tree already contains multiple non-NIC PHC
implementations (examples above), including long-standing and recently
added drivers. This reflects the reality that the PHC interface is no
longer tightly bound to NIC/IEEE1588 implementations.

This is enabled by the PHC interface's clean design, it provides a
well-scoped, layered abstraction that separates the userspace access
mechanism (/dev/ptpX + standard ioctl semantics) from the underlying
clock implementation and discipline method (NIC/IEEE1588 packet timestamping
pipeline, virtualization-provided clocks, platform/firmware time services,
etc.). The interface defines only generic clock-operation semantics, without
baking in assumptions about how the clock is produced or synchronized.

Because of this elegant decoupling, the PHC API naturally fits
"pure time source" devices as long as they can provide a stable, precise
hardware clock. In practice, PHC has effectively become Linux’s common
API for high-precision device clocks, rather than inherently bound to
an IEEE1588 NIC implementation.

#
## Observation 2: the PHC (/dev/ptpX) has an established userspace ecosystem
#

The PHC character device interface (/dev/ptpX + standard PTP_* ioctls) is
a mature, stable, and widely deployed userspace API for accessing
high-precision clocks on Linux. It is already the common interface consumed
by existing software stacks (e.g. chrony, and other applications built around
PHC devices)

Introducing a new clock type or a new userspace API (e.g. /dev/XXX) would
require widespread userspace changes, duplicated tooling, and long-term
fragmentation. This RFC is explicitly NOT proposing a new userspace API.

#
## Goal
#

Establish an appropriate upstream home and maintainer model for "pure time
source" PHC drivers. If they are not suitable to be maintained under netdev,
we need a clear place and maintainer(s) for them, and a consistent policy
for accepting new ones.

#
## Proposal
#

1. Reorganize drivers/ptp/ to make the interface/implementation split
    explicit,

    * drivers/ptp/core      : PTP core infrastructure and API.
                              (e.g. ptp_chardev.c, ptp_clock.c,
                               ptp_sysfs.c, etc.)

    * drivers/ptp/pure      : Non-network ("pure clock") implementation,
                              they are typically platform/architecture/
                              virtualization-provided time sources.
                              (e.g. ptp_kvm, ptp_vmw, ptp_vmclock,
                               ptp_s390, etc.)

    * drivers/ptp/*         : Network timestamping oriented implementation,
                              they primarily used together with IEEE1588
                              over the network.
                              (e.g. ptp_qoriq, ptp_pch, ptp_dp83640,
                               ptp_idt82p33 etc.)

2. Transition drivers/ptp/pure from netdev maintainership to
    clock/time maintainership (with an appropriate MAINTAINERS entry,
    e.g. PURE TIME PHC), since these PHC implementations are primarily
    clock devices and not network-oriented. New similar drivers can be
    added under drivers/ptp/pure as well.


Possible alternatives (please suggest others):

- Move/align "pure time source" PHC drivers under an existing
   timekeeping/clocksource/virt area, without changing the userspace API.


I’d like to drive this discussion towards consensus, and I’m happy to
adapt our series to match whatever direction is agreed upon.

[1] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=a0e136d436ded817c0aade72efdefa56a00b4e5e
[2] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=7d10001e20e46ad6ad95622164686bc2cbfc9802
[3] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=2d7de7a3010d713fb89b7ba99e6fdc14475ad106
[4] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=3716a49a81ba19dda7202633a68b28564ba95eb5
[5] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=9a17125a18f9ae1e1233a8e2d919059445b9d6fd
[6] https://lore.kernel.org/netdev/20251030121314.56729-1-guwen@linux.alibaba.com/ (local)
[7] https://lore.kernel.org/netdev/20251127083610.6b66a728@kernel.org/ (local)

Thanks for any input.

Thanks for starting this discussion.

I agree that the existing 'pure' PHC drivers should keep the option of
presenting themselves as PTP devices to userspace. I would probably
have suggested moving them out of drivers/ptp/… to somewhere else under
drivers/ entirely, but that's bikeshedding.

I do think we have slightly different requirements for the pure PHCs
too though, particularly the virt-focused ones. It would be good if we
could set a guest's clock from them at startup, and the primary focus
of them is for calibrating the guest's CLOCK_REALTIME. Which means we
do actually care about consuming UTC offset and leap second information
from them, not just TAI.

I'd also like microvms to be able to consume time directly, especially
from vmclock, without needing a full-blown NTP-capable userspace. I've
experimented with simulating 1PPS support to feed into the kernel's
timekeeping, although I don't think that's the best answer: 
https://lore.kernel.org/all/87cb97d5a26d0f4909d2ba2545c4b43281109470.camel@infradead.org/ (local)

We could do with harmonising the workarounds for kvmclock too. I made
sure the vmclock driver reports its timestamp pairs in terms of either
CSID_X86_TSC or CSID_X86_KVM_CLK as appropriate, but ptp_kvm *only*
uses kvmclock (which is daft, since anyone who cares about accurate
time will be using tsc). I was thinking that interface of the pure PHC
drivers could be really simple, and our new infrastructure could
provide the ptp_clock_info glue, including the kvmclock conversion if
needed. And *also* hook them in for setting the clock at startup, and
even calibrating CLOCK_REALTIME.