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