feature: PTP driver

[paulgear]

This is my first cut at a fix for #1138.

A few comments:

• Most of the driver is modelled on the PPS driver, although it is a timer-driven rather than event-driven pattern.
• I have tried to limit the extent of code changes in existing files in the project.
• I'm not really happy with the way the polling intervals work, but because the observability code uses PollInterval rather than an f64 and I didn't want to make changes to the way that ntp-ctl consumes PollInterval, this means PTP devices must be polled on a power of 2 interval like NTP sources, even though technically they don't need to be.
• I'm also not really happy with the lack of root dispersion figures, but I'm not sure how this could be fixed.
• There's a separate ptp-time crate that I modelled on pps-time. It's under my GitHub namespace just so I could build the project successfully, but I'm happy to move it over to pendulum-project whenever it suits.
• I'm not a rustacean, and I struggle with a lot of the subtleties of the language, so I've used this PR as a way to get more familiar with Rust concepts and tools.
  • I'm not sure that it will meet your criteria for AI contributions; I have used generative AI extensively to help me with the heaving lifting of reviewing the code and also for the skeleton implementation using requirements-driven development. Some of the prompts I've used are provided in docs/development/prompts/ptp/, and you'll see generated commits in the git history.
  • However, I have hand-reviewed all of the code and written some of it manually. I think the design and structure are reasonably solid in that they reflect the existing patterns in the code. I'm reasonably happy that I understand the high-level details, but there might be little details which are a bit 🤦 to a native Rust speaker. I'm happy to adjust these under your guidance.
  • All of the documentation changes were hand-written.
• Here's a Grafana dashboard showing this code running over a roughly 14-hour period on one of my VMs: https://snapshots.raintank.io/dashboard/snapshot/mOiBklZGR6QAmO4BWm96xWJ30J1l35n1?orgId=0

[codecov]

Codecov Report

❌ Patch coverage is 0% with 17 lines in your changes missing coverage. Please review.
✅ Project coverage is 21.56%. Comparing base (ee03739) to head (b093b35).
⚠️ Report is 99 commits behind head on main.

Files with missing lines	Patch %	Lines
ntp-proto/src/system.rs	0.00%	17 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##             main    #1961       +/-   ##
===========================================
- Coverage   83.44%   21.56%   -61.89%     
===========================================
  Files          70       37       -33     
  Lines       19266     5816    -13450     
===========================================
- Hits        16076     1254    -14822     
- Misses       3190     4562     +1372     

Flag	Coverage Δ
fuzz-cookie_parsing_sound	0.45% <0.00%> (-0.25%)	⬇️
fuzz-duration_from_float	0.29% <0.00%> (-0.01%)	⬇️
fuzz-encrypted_client_parsing	7.77% <0.00%> (-1.27%)	⬇️
fuzz-encrypted_server_parsing	10.68% <0.00%> (-1.36%)	⬇️
fuzz-ipfilter	2.73% <0.00%> (-0.01%)	⬇️
fuzz-key_exchange_request_parsing	2.32% <0.00%> (-1.27%)	⬇️
fuzz-key_exchange_response_parsing	2.74% <0.00%> (-1.56%)	⬇️
fuzz-packet_keyset	4.10% <0.00%> (-2.24%)	⬇️
fuzz-packet_parsing_sound	8.67% <0.00%> (-0.15%)	⬇️
fuzz-record_encode_decode	3.21% <0.00%> (-0.01%)	⬇️
test-aarch64-apple-darwin	?
test-x86_64-unknown-linux-gnu	?
test-x86_64-unknown-linux-musl	?

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[davidv1992]

Thank you very much for this contribution. We have taken a preliminary look at this and it looks interesting and of sufficient quality that we would like to do a more complete review with the aim of including it.

However, given the way this was built and the extent to which this was built using AI we unfortunately will have to require you to explicitly confirm that despite that, you are sure that you have the rights to this contribution and that it is not infringing on anyone's else rights by being a derivative work. In other words, we need you to confirm that your contribution satisfies the requirements under https://github.com/pendulum-project/ntpd-rs/blob/main/CONTRIBUTING.md#respect-free-softwareopen-source-licenses

If you could do that for us that would clear the way for reviewing this. Otherwise, we unfortunately will have to respectfully decline this contribution.

[paulgear]

However, given the way this was built and the extent to which this was built using AI we unfortunately will have to require you to explicitly confirm that despite that, you are sure that you have the rights to this contribution and that it is not infringing on anyone's else rights by being a derivative work. In other words, we need you to confirm that your contribution satisfies the requirements under https://github.com/pendulum-project/ntpd-rs/blob/main/CONTRIBUTING.md#respect-free-softwareopen-source-licenses

Thanks for the reply, @davidv1992.

I am not an intellectual property lawyer, so I can't definitively affirm anything relating to rights or infringements of this code or any other code. My understanding as a non-professional is that the copyright status of AI-generated code is still unknown (at least in U.S. legal jurisdictions).

Here's what I can affirm:

• The ptp-time crate is a mechanical application of the pps-time crate's techniques to the Linux kernel PTP API. I've just pushed an update to its README to make explicit my position that ptp-time is a derived work of pps-time.
• The information about how the driver would be made came from the summary saved in https://github.com/paulgear/ntpd-rs/blob/feature/ptp-driver/docs/development/prompts/ptp/driver-analysis-combined.md. The only inputs to this summary were the existing ntpd-rs codebase, and my AI prompt requesting an analysis of the driver design in ntpd-rs.
• A large amount of the PTP code is simply a minor revision to the PPS code. For example:
  • https://github.com/pendulum-project/ntpd-rs/pull/1961/files#diff-792bb7f1e2559c423ffb318ee06499360c1bd20def8f6ec876a7eb91701ef110
  • https://github.com/pendulum-project/ntpd-rs/pull/1961/files#diff-c34bbdc0f28ac67819e016fc62b00e2d168e4e9efa2371e0aa48d0921d453487
  • https://github.com/pendulum-project/ntpd-rs/pull/1961/files#diff-0e33a225c5eba3c4e607e1b0709e4e1fa947f82b8b4ccc4ab0ad95442539ef15
  • https://github.com/pendulum-project/ntpd-rs/pull/1961/files#diff-3e011816376ad6b759e9818d22d9c77ca28800ba9d654d6724362d61d0b2bbba
• The only other implementation of NTP in Rust of which I am aware is Miroslav Lichvar's rsntp, on which I also worked recently. Its code bears no resemblance to ntpd-rs, and I did not use it in any way to inform my work on this feature (which is not really surprising given that the features are for completely different things).
  • That project, this one, and the pps-time crate are the only rust code I've really spent any time reading, apart from basic snippets in a couple of beginner textbooks.
• I did not at any point in the development of this feature knowingly derive code from any source other than ntpd-rs itself, the pps-time crate, and the AI models' existing knowledge of rust primitives.
• My intention is that this driver be considered a derivative work of ntpd-rs, and therefore fall under the existing license and copyright regime of ntpd-rs.
• I am the only person who worked on creating this feature. The AI models which I used for specification and code generation were Alibaba's Qwen3 Coder (via Cline, a Visual Studio Code extension) and Anthropic's Claude Sonnet 4 (via the Amazon Q Visual Studio Code extension). I reviewed all of the results to ensure that I understood them and that I was happy with their design, functionality, and to some extent, code style.
• If I do have any rights of ownership over this code and the ptp-time crate, I am happy to assign them to the Trifecta Tech Foundation (assuming the foundation is the correct copyright holder).

I hope the above satisfies your requirements.

[davidv1992]

Just as a heads up, we are internally discussing the path forward here, but this may take a little while as this is still a bit of an edge case for us.

[paulgear]

Just as a heads up, we are internally discussing the path forward here, but this may take a little while as this is still a bit of an edge case for us.

No worries - thanks for the update.

[paulgear]

Just as a heads up, we are internally discussing the path forward here, but this may take a little while as this is still a bit of an edge case for us.

Hi @davidv1992, I assume from the long silence that AI-assisted coding is not ever going to be OK with this project. The PR now has conflicts with main that need to be resolved. If you don't have any further interest in it, I suggest closing it.

Let me know if you'd like me to submit a new PR with just the specifications and documentation changes so that someone else can implement the feature manually.

[davidv1992]

Apologies for the long delay, there has been some internal problems that made this slip to the bottom of the pile and made our communication less then ideal. I will make sure we will get back to you before the end of the week.

[davidv1992]

Apologies for delaying this yet further, due to some communication issues internally in the team we are going to respond early next week, hopefully on monday.

[davidv1992]

Sorry to delay the answer in full yet again. @rnijveld can expand on what I can say, but he is unfortunately not available for another few days.

In short though, this PR fell by the wayside not just because of the use of AI, but also because of its size, structure with external dependencies, and some general technical debt on our side that we are in the process of addressing.

The use of AI on its own was not disqualifying in this particular case, but it did make review harder. I'll leave the specifics to @rnijveld as he did most of the legwork on this, and thus can give the first-hand picture.

On the technical debt side, we are currently not happy with how we handle non-ntp sources. The code for this is (as you may have experienced) quite repetitive, and doesn't generalize nicely. This is something we are now in the process of fixing. Once that is done, using ptp clocks as sources should be a very natural feature, and we are planning to implement that.

Unfortunately, due to problems on our end, good communication with you on all this fell through the track. Tracking tasks around reviews is something we are now working on, which should hopefully help avoid creating situations like this in the future. Our apologies that it did not go well this time.

[paulgear]

Thanks @davidv1992 - I'll close this PR now.