[RFC] Defining a home/maintenance model for non-NIC PHC devices using the /dev/ptpX API

[RFC] Defining a home/maintenance model for non-NIC PHC devices using the /dev/ptpX API

[Wen Gu]

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/
[7] https://lore.kernel.org/netdev/20251127083610.6b66a728@kernel.org/

Thanks for any input.

Regards,
Wen Gu

Re: [RFC] Defining a home/maintenance model for non-NIC PHC devices using the /dev/ptpX API

[David Woodhouse]

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

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/
> [7] https://lore.kernel.org/netdev/20251127083610.6b66a728@kernel.org/
> 
> 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/

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.

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

Re: [RFC] Defining a home/maintenance model for non-NIC PHC devices using the /dev/ptpX API

[Sven Schnelle]

Hi Wen,

Wen Gu <guwen@linux.alibaba.com> writes:

> 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.)

I'm fine with splitting paths - but I would propose a different naming
scheme as 'pure' is not really a common term in the driver world (at
least in my perception, which might be wrong. How about the following
instead:

drivers/ptp/core    - API as written above
drivers/ptp/virtual - all PtP drivers somehow emulating a PtP clock
                      (like the ptp_s390 driver)
drivers/ptp/net     - all NIC related drivers.

Re: [RFC] Defining a home/maintenance model for non-NIC PHC devices using the /dev/ptpX API

[Vadim Fedorenko]

On 12/01/2026 11:00, Sven Schnelle wrote:
> Hi Wen,
> 
> Wen Gu <guwen@linux.alibaba.com> writes:
> 
>> 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.)
> 
> I'm fine with splitting paths - but I would propose a different naming
> scheme as 'pure' is not really a common term in the driver world (at
> least in my perception, which might be wrong. How about the following
> instead:
> 
> drivers/ptp/core    - API as written above
> drivers/ptp/virtual - all PtP drivers somehow emulating a PtP clock
>                        (like the ptp_s390 driver)
> drivers/ptp/net     - all NIC related drivers.
> 


Well, drivers/ptp/virtual is not really good, because some drivers are
for physical devices exporting PTP interface, but without NIC.
Another way is to split physical board drivers to another category, like
drivers/ptp/hardware. The main difference to virtual is that these 
devices can output signals on external physical pins as well as
timestamp inputs on physical pins.

Re: [RFC] Defining a home/maintenance model for non-NIC PHC devices using the /dev/ptpX API

[Andrew Lunn]

> > drivers/ptp/core    - API as written above
> > drivers/ptp/virtual - all PtP drivers somehow emulating a PtP clock
> >                        (like the ptp_s390 driver)
> > drivers/ptp/net     - all NIC related drivers.
> > 
> 
> 
> Well, drivers/ptp/virtual is not really good, because some drivers are
> for physical devices exporting PTP interface, but without NIC.

If the lack of a NIC is the differentiating property:

> > drivers/ptp/net     - all NIC related drivers.
> > drivers/ptp/netless - all related drivers which are not associated to a NIC.

Or

> > drivers/ptp/emulating - all drivers emulating a PtP clock

	Andrew

Re: [RFC] Defining a home/maintenance model for non-NIC PHC devices using the /dev/ptpX API

[Vadim Fedorenko]

On 12/01/2026 13:24, Andrew Lunn wrote:
>>> drivers/ptp/core    - API as written above
>>> drivers/ptp/virtual - all PtP drivers somehow emulating a PtP clock
>>>                         (like the ptp_s390 driver)
>>> drivers/ptp/net     - all NIC related drivers.
>>>
>>
>>
>> Well, drivers/ptp/virtual is not really good, because some drivers are
>> for physical devices exporting PTP interface, but without NIC.
> 
> If the lack of a NIC is the differentiating property:
> 
>>> drivers/ptp/net     - all NIC related drivers.
>>> drivers/ptp/netless - all related drivers which are not associated to a NIC.
> 
> Or
> 
>>> drivers/ptp/emulating - all drivers emulating a PtP clock

I would go with "emulating" then.

> 
> 	Andrew

Re: [RFC] Defining a home/maintenance model for non-NIC PHC devices using the /dev/ptpX API

[Richard Cochran]

On Fri, Jan 09, 2026 at 10:56:56AM +0800, Wen Gu wrote:

> 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.

Actually I disagree.

The PHC devices appear to user space as clockid_t.

The API for these works seamlessly and interchangeably with SYS-V clock IDs.

The path that is opened, whether /dev/ptpX or some new /dev/hwclkX etc
is a trivial detail that adds no burden to user space.

Thanks,
Richard

Re: [RFC] Defining a home/maintenance model for non-NIC PHC devices using the /dev/ptpX API

[Wen Gu]

On 2026/1/12 16:04, David Woodhouse wrote:
> 
> 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.
> 

Thanks for the feedback. The directory and naming will be improved.

> 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.
> 

Yes, we have slightly different requirements. The original motivation
for Alibaba CIPU PTP clock was to provide usable PTP clocks for cloud
services that require precise timing. Guest/VM time synchronization
was not the primary target.

However, I think the idea you mentioned is valuable for virtualization
scenario, eliminating the need for a userspace daemon and directly
calibrating the guest's CLOCK_REALTIME.

> 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/
> 
> 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.

I expect the drivers covered by "pure PHC" will be diverse, covering
a range of non-network/IEEE 1588-oriented implementations.
PHC drivers for virtualization scenarios could be one subset. Further
virtualization-specific optimizations can be considered as follow-up
work with the virtualization and timekeeping experts.

Regards.

Re: [RFC] Defining a home/maintenance model for non-NIC PHC devices using the /dev/ptpX API

[Wen Gu]

On 2026/1/12 22:52, Vadim Fedorenko wrote:
> On 12/01/2026 13:24, Andrew Lunn wrote:
>>>> drivers/ptp/core    - API as written above
>>>> drivers/ptp/virtual - all PtP drivers somehow emulating a PtP clock
>>>>                         (like the ptp_s390 driver)
>>>> drivers/ptp/net     - all NIC related drivers.
>>>>
>>>
>>>
>>> Well, drivers/ptp/virtual is not really good, because some drivers are
>>> for physical devices exporting PTP interface, but without NIC.
>>
>> If the lack of a NIC is the differentiating property:
>>
>>>> drivers/ptp/net     - all NIC related drivers.
>>>> drivers/ptp/netless - all related drivers which are not associated to a NIC.
>>
>> Or
>>
>>>> drivers/ptp/emulating - all drivers emulating a PtP clock
> 
> I would go with "emulating" then.
> 
>>
>>     Andrew

Thank you all for your suggestions.

The drivers under drivers/ptp can be divided into (to my knowledge):

1. Network/1588-oriented clocks, which allow the use of tools like
    ptp4l to synchronize the local PHC with an external reference clock
    (based on the network or other methods) via the 1588 protocol to
    maintain accuracy. Examples include:

    - ptp_dte
    - ptp_qoriq
    - ptp_ines
    - ptp_pch
    - ptp_idt82p33
    - ptp_clockmatrix
    - ptp_fc3
    - ptp_mock (mock/testing)
    - ptp_dfl_tod
    - ptp_netc
    - ptp_ocp (a special case which provides a grandmaster
               clock for a PTP enabled network, generally
               serves as the reference clock)

2. Platform/infrastructure/hypervisor-provided clocks. They don't
    require calibration by ptp4l based on 1588 and reference clocks,
    instead the underlay handle this. Users generally read the time.
    They include:

    - ptp_kvm
    - ptp_vmclock
    - ptp_vmw
    - ptp_s390
    - ptp_cipu (upstreaming)

 From this perspective, I agree that "emulating" could be an appropriate
name for the second ones.

And I would like to further group the first ones to "1588", thus
divide drivers/ptp to:

- drivers/ptp/core
- drivers/ptp/1588
- drivers/ptp/emulating

Regards.

Re: [RFC] Defining a home/maintenance model for non-NIC PHC devices using the /dev/ptpX API

[Wen Gu]

On 2026/1/13 12:21, Richard Cochran wrote:
> On Fri, Jan 09, 2026 at 10:56:56AM +0800, Wen Gu wrote:
> 
>> 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.
> 
> Actually I disagree.
> 
> The PHC devices appear to user space as clockid_t.
> 
> The API for these works seamlessly and interchangeably with SYS-V clock IDs.
> 
> The path that is opened, whether /dev/ptpX or some new /dev/hwclkX etc
> is a trivial detail that adds no burden to user space.
> 
> Thanks,
> Richard

Thanks, Richard.

This might be true for applications using the POSIX clock API.
(However in practice there is also an ecosystem aspect: apps
and scripts assume /dev/ptpX explicitly, introducing a new
clock path can still incur real adoption/compatibility costs.)

More importantly, the existing ecosystem also relies on the
ioctl APIs (PTP_* ioctls).

Taking chrony as an example. For PHC refclock, chrony's PHC
handler (RCL_PHC_driver) explicitly relies on PTP ioctls[1],

e.g.,

ioctl(fd, PTP_SYS_OFFSET_PRECISE/PTP_SYS_OFFSET_EXTENDED/PTP_SYS_OFFSET, etc)

So a new clock type and APIs would require non-trivial userspace
changes. That would be a lengthy process of adaptation and tool
availability across different distributions. Similar problems
may also arise in other tools.

That's why this RFC is not proposing new userspace APIs.

[1] https://gitlab.com/chrony/chrony/-/blob/master/refclock_phc.c?ref_type=heads#:~:text=static%20int%20phc_poll,%7D

Regards.

Re: [RFC] Defining a home/maintenance model for non-NIC PHC devices using the /dev/ptpX API

[Vadim Fedorenko]

On 14/01/2026 09:13, Wen Gu wrote:
> 
> 
> On 2026/1/12 22:52, Vadim Fedorenko wrote:
>> On 12/01/2026 13:24, Andrew Lunn wrote:
>>>>> drivers/ptp/core    - API as written above
>>>>> drivers/ptp/virtual - all PtP drivers somehow emulating a PtP clock
>>>>>                         (like the ptp_s390 driver)
>>>>> drivers/ptp/net     - all NIC related drivers.
>>>>>
>>>>
>>>>
>>>> Well, drivers/ptp/virtual is not really good, because some drivers are
>>>> for physical devices exporting PTP interface, but without NIC.
>>>
>>> If the lack of a NIC is the differentiating property:
>>>
>>>>> drivers/ptp/net     - all NIC related drivers.
>>>>> drivers/ptp/netless - all related drivers which are not associated 
>>>>> to a NIC.
>>>
>>> Or
>>>
>>>>> drivers/ptp/emulating - all drivers emulating a PtP clock
>>
>> I would go with "emulating" then.
>>
>>>
>>>     Andrew
> 
> Thank you all for your suggestions.
> 
> The drivers under drivers/ptp can be divided into (to my knowledge):
> 
> 1. Network/1588-oriented clocks, which allow the use of tools like
>     ptp4l to synchronize the local PHC with an external reference clock
>     (based on the network or other methods) via the 1588 protocol to
>     maintain accuracy. Examples include:
> 
>     - ptp_dte
>     - ptp_qoriq
>     - ptp_ines
>     - ptp_pch
>     - ptp_idt82p33
>     - ptp_clockmatrix
>     - ptp_fc3
>     - ptp_mock (mock/testing)
>     - ptp_dfl_tod
>     - ptp_netc
>     - ptp_ocp (a special case which provides a grandmaster
>                clock for a PTP enabled network, generally
>                serves as the reference clock)

ptp_ocp is a timecard driver, which doesn't require calibration by
ptp4l/ts2phc. OCP TimeCards have their own Atomic Clock onboard which
is disciplined by 1-PPS or 10mhz signal from configurable source. The
disciplining algorithm is implemented in Atomic Clock package
controller. The driver exposes ptp device mostly for reading the time.
So I believe it belongs to group 2 rather than 1588 group.

> 
> 2. Platform/infrastructure/hypervisor-provided clocks. They don't
>     require calibration by ptp4l based on 1588 and reference clocks,
>     instead the underlay handle this. Users generally read the time.
>     They include:
> 
>     - ptp_kvm
>     - ptp_vmclock
>     - ptp_vmw
>     - ptp_s390
>     - ptp_cipu (upstreaming)
> 
>  From this perspective, I agree that "emulating" could be an appropriate
> name for the second ones.
> 
> And I would like to further group the first ones to "1588", thus
> divide drivers/ptp to:
> 
> - drivers/ptp/core
> - drivers/ptp/1588
> - drivers/ptp/emulating
> 
> Regards.

Re: [RFC] Defining a home/maintenance model for non-NIC PHC devices using the /dev/ptpX API

[Wen Gu]

On 2026/1/14 18:50, Vadim Fedorenko wrote:
> On 14/01/2026 09:13, Wen Gu wrote:
>>
>> Thank you all for your suggestions.
>>
>> The drivers under drivers/ptp can be divided into (to my knowledge):
>>
>> 1. Network/1588-oriented clocks, which allow the use of tools like
>>     ptp4l to synchronize the local PHC with an external reference clock
>>     (based on the network or other methods) via the 1588 protocol to
>>     maintain accuracy. Examples include:
>>
>>     - ptp_dte
>>     - ptp_qoriq
>>     - ptp_ines
>>     - ptp_pch
>>     - ptp_idt82p33
>>     - ptp_clockmatrix
>>     - ptp_fc3
>>     - ptp_mock (mock/testing)
>>     - ptp_dfl_tod
>>     - ptp_netc
>>     - ptp_ocp (a special case which provides a grandmaster
>>                clock for a PTP enabled network, generally
>>                serves as the reference clock)
> 
> ptp_ocp is a timecard driver, which doesn't require calibration by
> ptp4l/ts2phc. OCP TimeCards have their own Atomic Clock onboard which
> is disciplined by 1-PPS or 10mhz signal from configurable source. The
> disciplining algorithm is implemented in Atomic Clock package
> controller. The driver exposes ptp device mostly for reading the time.
> So I believe it belongs to group 2 rather than 1588 group.
> 

Thank you for the correction and detailed explanation. I will move
ptp_ocp to group 2.

>>
>> 2. Platform/infrastructure/hypervisor-provided clocks. They don't
>>     require calibration by ptp4l based on 1588 and reference clocks,
>>     instead the underlay handle this. Users generally read the time.
>>     They include:
>>
>>     - ptp_kvm
>>     - ptp_vmclock
>>     - ptp_vmw
>>     - ptp_s390
>>     - ptp_cipu (upstreaming)
>>
>>  From this perspective, I agree that "emulating" could be an appropriate
>> name for the second ones.
>>
>> And I would like to further group the first ones to "1588", thus
>> divide drivers/ptp to:
>>
>> - drivers/ptp/core
>> - drivers/ptp/1588
>> - drivers/ptp/emulating
>>
>> Regards.

Re: [RFC] Defining a home/maintenance model for non-NIC PHC devices using the /dev/ptpX API

[Manivannan Sadhasivam]

Hi Wen,

On Fri, Jan 09, 2026 at 10:56:56AM +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.
> 

Thanks for starting the discussion. I sent out an email just today on this
topic [1] and learned about this thread afterwards.

> 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.
> 

Some Qcom MHI devices expose the high precision clock derived from GNSS/Cellular
network over the MHI registers and we recently sent out a series exposing them
as PHC [2]. Since this driver is closely tied with MHI bus, we added it as a
part of drivers/bus/mhi/.

> 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.
> 

+1

> #
> ## 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.
> 

If we get a consensus to move forward with exposing the device clocks as PHC, we
will respin the MHI driver and would love to get an ACK from the (new)
maintainers.

- Mani

[1] https://lore.kernel.org/all/vmwwnl3zv26lmmuqp2vqltg2fudalpc5jrw7k6ifg6l5cwlk3j@i7jm62zcsl67/
[2] https://lore.kernel.org/mhi/20250818-tsc_time_sync-v1-0-2747710693ba@oss.qualcomm.com/

-- 
மணிவண்ணன் சதாசிவம்

Re: [RFC] Defining a home/maintenance model for non-NIC PHC devices using the /dev/ptpX API

[Wen Gu]

On 2026/1/19 22:48, Manivannan Sadhasivam wrote:
> Hi Wen,
> 
> On Fri, Jan 09, 2026 at 10:56:56AM +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.
>>
> 
> Thanks for starting the discussion. I sent out an email just today on this
> topic [1] and learned about this thread afterwards.

[...]

> 
> Some Qcom MHI devices expose the high precision clock derived from GNSS/Cellular
> network over the MHI registers and we recently sent out a series exposing them
> as PHC [2]. Since this driver is closely tied with MHI bus, we added it as a
> part of drivers/bus/mhi/.
> 
Hi Manivannan,

Thanks for the note and for sharing the MHI PHC use case.

Yes, this is very similar to what motivated this RFC, there are more and
more PHC providers which are not tied to NIC/IEEE 1588.

[...]

>>
>> 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.
>>
> 
> +1
> 

[...]

> 
> If we get a consensus to move forward with exposing the device clocks as PHC, we
> will respin the MHI driver and would love to get an ACK from the (new)
> maintainers.
> 
> - Mani
> 
> [1] https://lore.kernel.org/all/vmwwnl3zv26lmmuqp2vqltg2fudalpc5jrw7k6ifg6l5cwlk3j@i7jm62zcsl67/
> [2] https://lore.kernel.org/mhi/20250818-tsc_time_sync-v1-0-2747710693ba@oss.qualcomm.com/
> 

Re: [RFC] Defining a home/maintenance model for non-NIC PHC devices using the /dev/ptpX API

[Wen Gu]

On 2026/1/9 10:56, Wen Gu wrote:
> 
> #
> ## 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.)
> 

Thanks for the feedback so far. It seems we are close to consensus on
the directory split, as [1] summarized:

- drivers/ptp/core       : PTP core infrastructure and API
- drivers/ptp/1588       : network/IEEE 1588 oriented PTP clocks
- drivers/ptp/emulating  : platform/hardware/hypervisor-provided pure clocks

For how the existing drivers in `drivers/ptp` are categorized into the
directories above, please also refer to [1] and the follow-up replies.

> 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.


Then the open item now is maintainership and the merge path.

Based on previous guidance[2] and the current MAINTAINERS structure,
it seems reasonable to have it maintained under the clock/timekeeping
domain (following the existing timekeeping pull chain), with a
dedicated MAINTAINERS entry.


Hi Thomas and clock/timekeeping maintainers,

Would you agree with this approach? If so, could you please advise on
the appropriate maintainer/reviewer for this MAINTAINERS entry?

Below is a strawman MAINTAINERS entry (happy to adjust):

EMULATING PTP CLOCK SUPPORT
L:     linux-kernel@vger.kernel.org
S:     Maintained
F:     drivers/ptp/emulating/*


We (Alibaba) are also willing to be the maintainer for this entry as
a fallback.

[1] https://lore.kernel.org/netdev/b5a60753-85ed-4d61-a652-568393e0dff3@linux.alibaba.com/
[2] https://lore.kernel.org/netdev/20251216135848.174e010f@kernel.org/

Regards.

Re: [RFC] Defining a home/maintenance model for non-NIC PHC devices using the /dev/ptpX API

[Imran Shaik]

On 21-01-2026 07:59 pm, Wen Gu wrote:
> 
> 
> On 2026/1/9 10:56, Wen Gu wrote:
>>
>> #
>> ## 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.)
>>
> 
> Thanks for the feedback so far. It seems we are close to consensus on
> the directory split, as [1] summarized:
> 
> - drivers/ptp/core       : PTP core infrastructure and API
> - drivers/ptp/1588       : network/IEEE 1588 oriented PTP clocks
> - drivers/ptp/emulating  : platform/hardware/hypervisor-provided pure 
> clocks
> 
> For how the existing drivers in `drivers/ptp` are categorized into the
> directories above, please also refer to [1] and the follow-up replies.
> 
>> 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.
> 
> 
> Then the open item now is maintainership and the merge path.
> 
> Based on previous guidance[2] and the current MAINTAINERS structure,
> it seems reasonable to have it maintained under the clock/timekeeping
> domain (following the existing timekeeping pull chain), with a
> dedicated MAINTAINERS entry.
> 
> 
> Hi Thomas and clock/timekeeping maintainers,
> 
> Would you agree with this approach? If so, could you please advise on
> the appropriate maintainer/reviewer for this MAINTAINERS entry?
> 
> Below is a strawman MAINTAINERS entry (happy to adjust):
> 
> EMULATING PTP CLOCK SUPPORT
> L:     linux-kernel@vger.kernel.org
> S:     Maintained
> F:     drivers/ptp/emulating/*
> 
> 
> We (Alibaba) are also willing to be the maintainer for this entry as
> a fallback.
> 
> [1] https://lore.kernel.org/netdev/b5a60753-85ed-4d61- 
> a652-568393e0dff3@linux.alibaba.com/
> [2] https://lore.kernel.org/netdev/20251216135848.174e010f@kernel.org/
> 
> Regards.
> 

Hi Wen,

Thanks for driving this discussion.

Is there a patch series posted that reflects the new proposal?

As Manivannan mentioned, some Qcom MHI devices have similar 
requirements. Once the reorganized changes are posted, we will also 
resend our patch series adopting the latest changes.

Thanks,
Imran

Re: [RFC] Defining a home/maintenance model for non-NIC PHC devices using the /dev/ptpX API

[Wen Gu]

On 2026/2/19 17:29, Imran Shaik wrote:
> 
> Hi Wen,
> 
> Thanks for driving this discussion.
> 
> Is there a patch series posted that reflects the new proposal?
> 
> As Manivannan mentioned, some Qcom MHI devices have similar requirements. Once the reorganized changes are posted, we will also resend our patch series adopting the latest changes.
> 
> Thanks,
> Imran

Hi Imran,

Yes, I will send a patch series reflecting the new proposal in the next couple of days.

Thanks.