daniel-p-carvalho opened a new pull request, #20198: URL: https://github.com/apache/nuttx/pull/20198
## 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.c` and `sched/clock`: - The operations structure is `struct ptp_ops_s`, not `ptp_clock_ops_s`. It has `adjphase`, `getres` and `control`, it has no `getcaps` (the capabilities are built by the upper half), `adjfine` takes parts per billion, not scaled ppm, and `gettime` has a system timestamp argument. The page now says which operations are optional (`adjtime` is called without a check) and shows the real `ptp_clock_register(lower, max_adj, devno)`. - The `CLOCKFD(fd)` macro does not exist. The clock identifier is `(fd << CLOCK_SHIFT) | CLOCK_FD`, as `netutils/ptpd` builds it. All the examples are fixed. - The frequency values were wrong. `struct timex` `freq` is in ppm with 16 fractional bits, so +10 ppm is 655360, not 10000000. - Only `ADJ_SETOFFSET`, `ADJ_FREQUENCY` and `ADJ_OFFSET` (a phase adjustment that needs `adjphase`) are handled for a PTP clock, one per call. `ADJ_MAXERROR`, `ADJ_ESTERROR`, `ADJ_STATUS` and `ADJ_TIMECONST`, which the page listed as supported, return `-ENOTSUP`. - `PTP_CLOCK_GETTIME` and `PTP_CLOCK_SETTIME` take a `struct timespec`. The extended, `*2` and statistics ioctls were missing. - The dummy driver uses `CLOCK_REALTIME`, not the monotonic clock. - The debug options are `CONFIG_DEBUG_PTP` and `CONFIG_DEBUG_PTP_ERROR/WARN/INFO`, not `CONFIG_DEBUG_PTPCLK_*`, and the example output was not what the driver prints, so it is removed. - The section on PTP daemons named `ptp4l` and `timemaster`, which are not part of NuttX. It now points to `ptpd`. Trailing whitespace inside the code blocks that were rewritten is removed as well. ## Impact Documentation only, no code change. The page `components/drivers/special/ptp` changes; the `ptpd` page 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.sh` passes. Each statement was checked by reading the code named above; the examples were not compiled or run. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
