STRUCT PTP_CLOCK_INFO(9)

📦 version 7.3.1, in nixpkgs unstable

💖 struct ptp_clock_info(9) — Kernel API Manual, bestie edition 💖

okay so grab a snack because we're diving into <hotpink>struct ptp_clock_info</hotpink>, straight out of the Kernel API Manual section 9, and honestly? it's giving the blueprint of a PTP hardware clock. iykyk ✨

🌸 NAME 🌸

struct ptp_clock_info — literally just describes a PTP hardware clock, that's the whole vibe 🕰️💅

🦋 SYNOPSIS 🦋

struct ptp_clock_info {
    struct module *owner;
    char name[PTP_CLOCK_NAME_LEN];
    s32 max_adj;
    int n_alarm;
    int n_ext_ts;
    int n_per_out;
    int n_pins;
    int n_per_lp;
    int pps;
    unsigned int supported_perout_flags;
    unsigned int supported_extts_flags;
    struct ptp_pin_desc *pin_config;
    int (*adjfine)(struct ptp_clock_info *ptp, long scaled_ppm);
    int (*adjphase)(struct ptp_clock_info *ptp, s32 phase);
    s32 (*getmaxphase)(struct ptp_clock_info *ptp);
    int (*adjtime)(struct ptp_clock_info *ptp, s64 delta);
    int (*gettime64)(struct ptp_clock_info *ptp, struct timespec64 *ts);
    int (*gettimex64)(struct ptp_clock_info *ptp, struct timespec64 *ts,
struct ptp_system_timestamp *sts);
    int (*getcrosststamp)(struct ptp_clock_info *ptp, struct
system_device_crosststamp *cts);
    int (*settime64)(struct ptp_clock_info *p, const struct timespec64
*ts);
    int (*getcycles64)(struct ptp_clock_info *ptp, struct timespec64
*ts);
    int (*getcyclesx64)(struct ptp_clock_info *ptp, struct timespec64
*ts, struct ptp_system_timestamp *sts);
    int (*getcrosscycles)(struct ptp_clock_info *ptp, struct
system_device_crosststamp *cts);
    int (*enable)(struct ptp_clock_info *ptp, struct ptp_clock_request
*request, int on);
    int (*verify)(struct ptp_clock_info *ptp, unsigned int pin, enum
ptp_pin_function func, unsigned int chan);
    long (*do_aux_work)(struct ptp_clock_info *ptp);
    int (*perout_loopback)(struct ptp_clock_info *ptp, unsigned int
index, int on);
 };

like, look at all those function pointers. main character energy fr fr 👑

🎀 Members 🎀

okay so here's the cast of characters, one by one:

  • owner — the clock driver should set this to THIS_MODULE. that's it, that's the whole job 🫶
  • name — a short "friendly name" to identify the clock and to help distinguish PHY based devices from MAC based ones. important: the string is not meant to be a unique id, so don't come for it for not being special 💀
  • max_adj — the maximum possible frequency adjustment, in parts per billon.
  • n_alarm — the number of programmable alarms ⏰
  • n_ext_ts — the number of external time stamp channels.
  • n_per_out — the number of programmable periodic signals.
  • n_pins — the number of programmable pins 📌
  • n_per_lp — the number of channels that support loopback the periodic output signal.
  • pps — indicates whether the clock supports a PPS callback.
  • supported_perout_flags — the set of flags the driver supports for the PTP_PEROUT_REQUEST ioctl. the PTP core will reject a request with any flag not specified here 🚫
  • supported_extts_flags — the set of flags the driver supports for the PTP_EXTTS_REQUEST ioctl. the PTP core will use this list to reject unsupported requests. PTP_ENABLE_FEATURE is assumed and does not need to be included. If PTP_STRICT_FLAGS is not set, then both PTP_RISING_EDGE and PTP_FALLING_EDGE will be assumed. Note that PTP_STRICT_FLAGS must be set if the drivers wants to honor PTP_EXTTS_REQUEST2 and any future flags. lowkey the most detail-dense member and i respect it 🙈
  • pin_config — array of length 'n_pins'. If the number of programmable pins is nonzero, then drivers must allocate and initialize this array. no skipping this step bestie ✨
  • adjfine — adjusts the frequency of the hardware clock. parameter scaled_ppm: Desired frequency offset from nominal frequency in parts per million, but with a 16 bit binary fractional field. fancy 🌈
  • adjphase — indicates that the PHC should use an internal servo algorithm to correct the provided phase offset. parameter delta: PHC servo phase adjustment target in nanoseconds.
  • getmaxphase — advertises maximum offset that can be provided to the hardware clock's phase control functionality through adjphase.
  • adjtime — shifts the time of the hardware clock. parameter delta: Desired change in nanoseconds.
  • gettime64 — reads the current time from the hardware clock. this method is deprecated 🚨 new drivers should implement the gettimex64 method instead. parameter ts: Holds the result.
  • gettimex64 — reads the current time from the hardware clock and optionally also the system clock. parameter ts: Holds the PHC timestamp. parameter sts: If not NULL, it holds a pair of timestamps from the system clock. The first reading is made right before reading the lowest bits of the PHC timestamp and the second reading immediately follows that. the timing of this is so precise it's honestly iconic 💅
  • getcrosststamp — reads the current time from the hardware clock and system clock simultaneously. parameter cts: Contains timestamp (device,system) pair, where system time is realtime and monotonic.
  • settime64 — set the current time on the hardware clock. parameter ts: Time value to set. (note the param here is named p, not ptp — keep it exactly as-is 🫡)
  • getcycles64 — reads the current free running cycle counter from the hardware clock. If getcycles64 and getcyclesx64 are not supported, then gettime64 or gettimex64 will be used as default implementation. parameter ts: Holds the result.
  • getcyclesx64 — reads the current free running cycle counter from the hardware clock and optionally also the system clock. If getcycles64 and getcyclesx64 are not supported, then gettimex64 will be used as default implementation if available. parameter ts: Holds the PHC timestamp. parameter sts: If not NULL, it holds a pair of timestamps from the system clock. The first reading is made right before reading the lowest bits of the PHC timestamp and the second reading immediately follows that. same energy, cycle counter edition 🌀
  • getcrosscycles — reads the current free running cycle counter from the hardware clock and system clock simultaneously. If getcycles64 and getcyclesx64 are not supported, then getcrosststamp will be used as default implementation if available. parameter cts: Contains timestamp (device,system) pair, where system time is realtime and monotonic.
  • enable — request driver to enable or disable an ancillary feature. parameter request: Desired resource to enable or disable. parameter on: Caller passes one to enable or zero to disable. simple, clean, slay 🔥
  • verify — confirm that a pin can perform a given function. The PTP Hardware Clock subsystem maintains the 'pin_config' array on behalf of the drivers, but the PHC subsystem assumes that every pin can perform every function. This hook gives drivers a way of telling the core about limitations on specific pins. This function must return zero if the function can be assigned to this pin, and nonzero otherwise. parameter pin: index of the pin in question. parameter func: the desired function to use. parameter chan: the function channel index to use. ngl this one's the vibe check for pins ✨
  • do_aux_work — request driver to perform auxiliary (periodic) operations. Driver should return delay of the next auxiliary work scheduling time (>=0) or negative value in case further scheduling is not required. negative = we're done here, bye 👋
  • perout_loopback — request driver to enable or disable the periodic output signal loopback. parameter index: index of the periodic output signal channel. parameter on: caller passes one to enable or zero to disable.

💜 Description 💜

clock operations ⏱️ that's the description. short king.

Drivers should embed their ptp_clock_info within a private structure, obtaining a reference to it using container_of. this is like, THE move, okay? 🫶

The callbacks must all return zero on success, non-zero otherwise. all of them. no exceptions, no cap 💯

⭐ SEE ALSO ⭐

go read these next, bestie, they're all linked up:

💡 friendly heads up: gettime64 is deprecated — use gettimex64 in new drivers, fr fr. and if you've got nonzero n_pins, you must allocate and initialize pin_config.

and that's the page!! 🎀 huge thank you to the <cyan>./include/linux</cyan> crew, dated <peach>October 2026</peach>, for bringing us <rainbow>struct ptp_clock_info(9)</rainbow> — periodt, go write a clock driver 💖🦋✨

📦 where this page comes from