Documentation/ptp: correct the PTP clock driver page. - #20198
Merged
Merged
Conversation
The page did not match the code in several places. - Describe struct ptp_ops_s as it is: adjfine takes parts per billion, adjphase, getres and control exist, there is no getcaps, and gettime has a system timestamp argument. State which operations are optional and give the real ptp_clock_register() arguments. - Replace the CLOCKFD() macro, which does not exist, with the clock identifier built from CLOCK_SHIFT and CLOCK_FD, in all examples. - Fix the frequency values: struct timex freq is in parts per million with 16 fractional bits, so +10 ppm is 655360. - List the modes clock_adjtime() handles for a PTP clock (ADJ_SETOFFSET, ADJ_FREQUENCY, ADJ_OFFSET for the phase) and say that the others return -ENOTSUP. - PTP_CLOCK_GETTIME and PTP_CLOCK_SETTIME take a struct timespec. Add the ioctls that were missing. - The dummy driver uses CLOCK_REALTIME, not the monotonic clock. - Point to ptpd instead of ptp4l and timemaster, which are not part of NuttX, and use the real CONFIG_DEBUG_PTP options. Signed-off-by: Daniel P. Carvalho <danieloak@gmail.com> Assisted-by: Claude:claude-sonnet-5
github-actions
Bot
added
Area: Documentation
xiaoxiang781216
approved these changes
Sep 20, 2026
acassis
approved these changes
Sep 20, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The PTP clock driver page (
Documentation/components/drivers/special/ptp.rst) does not match the code in several places, so a driver written from it does not compile and the examples do not run. This PR corrects it. It changes documentation only.What was wrong, checked against
include/nuttx/timers/ptp_clock.h,drivers/timers/ptp_clock.candsched/clock:struct ptp_ops_s, notptp_clock_ops_s. It hasadjphase,getresandcontrol, it has nogetcaps(the capabilities are built by the upper half),adjfinetakes parts per billion, not scaled ppm, andgettimehas a system timestamp argument. The page now says which operations are optional (adjtimeis called without a check) and shows the realptp_clock_register(lower, max_adj, devno).CLOCKFD(fd)macro does not exist. The clock identifier is(fd << CLOCK_SHIFT) | CLOCK_FD, asnetutils/ptpdbuilds it. All the examples are fixed.struct timexfreqis in ppm with 16 fractional bits, so +10 ppm is 655360, not 10000000.ADJ_SETOFFSET,ADJ_FREQUENCYandADJ_OFFSET(a phase adjustment that needsadjphase) are handled for a PTP clock, one per call.ADJ_MAXERROR,ADJ_ESTERROR,ADJ_STATUSandADJ_TIMECONST, which the page listed as supported, return-ENOTSUP.PTP_CLOCK_GETTIMEandPTP_CLOCK_SETTIMEtake astruct timespec. The extended,*2and statistics ioctls were missing.CLOCK_REALTIME, not the monotonic clock.CONFIG_DEBUG_PTPandCONFIG_DEBUG_PTP_ERROR/WARN/INFO, notCONFIG_DEBUG_PTPCLK_*, and the example output was not what the driver prints, so it is removed.ptp4landtimemaster, which are not part of NuttX. It now points toptpd.Trailing whitespace inside the code blocks that were rewritten is removed as well.
Impact
Documentation only, no code change. The page
components/drivers/special/ptpchanges; theptpdpage that links to it is not touched.Testing
Built the documentation with Sphinx 6.2.1 and the packages of
Documentation/Pipfile, without-W: the build succeeds, the page renders, and none of the 19 warnings (duplicate C declarations in other pages) is from this file../tools/checkpatch.shpasses.Each statement was checked by reading the code named above; the examples were not compiled or run.