Re: [PATCH v4 net-next 1/7] ptp: Add ioctls for PHC timestamps with quality attributes

[Carolina Jubran <cjubran@nvidia.com>]

On 14/07/2026 5:03, Arthur Kiyanovski wrote:
>   
> +/*
> + * Clock status values for struct ptp_clock_attrs.status
> + */
> +enum ptp_clock_status {
> +	/* Clock synchronization status cannot be reliably determined */
> +	PTP_CLOCK_STATUS_UNKNOWN      = 0,
> +
> +	/* Clock is acquiring synchronization */
> +	PTP_CLOCK_STATUS_INITIALIZING = 1,
> +
> +	/* Clock is synchronized and maintained accurately by the device */
> +	PTP_CLOCK_STATUS_SYNCED       = 2,
> +
> +	/* Clock is drifting but remains within acceptable error bounds */
> +	PTP_CLOCK_STATUS_HOLDOVER     = 3,
> +
> +	/* Clock is drifting without adjustments or synchronization */
> +	PTP_CLOCK_STATUS_FREE_RUNNING = 4,
> +
> +	/* Clock is unreliable, the error_bound value cannot be trusted */
> +	PTP_CLOCK_STATUS_UNRELIABLE   = 5
> +};

Could you clarify the intended distinction between FREE_RUNNING and
UNRELIABLE? What does UNRELIABLE represent beyond FREE_RUNNING?


Also, how is userspace expected to relate clock_status to error_bound?
Are there defined thresholds for transitions between the states or are
these entirely device-specific?

> +
> +/*
> + * Clock timescale values for struct ptp_clock_attrs.timescale.
> + *
> + * These definitions describe the mathematical properties and reference
> + * epochs of the timescale provided by the PHC.
> + *
> + * Discipline: Describes the frequency/phase steering behavior.
> + * Continuity: Describes whether the timeline is uninterrupted.
> + */
> +enum ptp_clock_timescale {
> +	/* Unknown or unspecified timescale */
> +	PTP_TIMESCALE_UNKNOWN = 0,
> +
> +	/********************* Absolute Atomic Timescales *********************
> +	 * These timescales are continuous, monotonic standards based on atomic
> +	 * physics. They do not experience phase jumps.
> +	 **********************************************************************/
> +
> +	/**
> +	 * International Atomic Time (TAI)
> +	 * Epoch: 1958-01-01 00:00:00.
> +	 * Continuity: Strictly monotonic and continuous; no leap seconds.
> +	 * Discipline: Primary atomic reference; no phase jumps.
> +	 */
> +	PTP_TIMESCALE_TAI = 1,
> +
> +	/**
> +	 * Terrestrial Time (TT)
> +	 * Epoch: 1958-01-01 00:00:00.
> +	 * Continuity: Strictly monotonic and continuous; no leap seconds.
> +	 * Discipline: Defined as TAI + 32.184s constant offset.
> +	 */
> +	PTP_TIMESCALE_TT = 2,
> +
> +	/**
> +	 * Global Positioning System (GPS) Time
> +	 * Epoch: 1980-01-06 00:00:00.
> +	 * Continuity: Strictly monotonic and continuous; no leap seconds.
> +	 * Discipline: Defined by the GPS constellation; fixed offset from TAI.
> +	 */
> +	PTP_TIMESCALE_GPS = 3,
> +
> +	/****************** UTC-Based Timescales (Civil Time) *****************
> +	 * These timescales are derived from TAI but adjusted to align with
> +	 * the Earth's rotation, primarily through leap seconds.
> +	 **********************************************************************/
> +
> +	/**
> +	 * Coordinated Universal Time (UTC) - Wall-clock (CLOCK_REALTIME)
> +	 * Epoch: 1970-01-01 00:00:00 (Unix epoch).
> +	 * Continuity: Discontinuous; subject to 1-second leap second
> +	 *             phase jumps.
> +	 * Discipline: Frequency steered; incorporates leap second corrections.
> +	 *
> +	 * Note: Leap-smeared UTC MUST NOT be advertised as PTP_TIMESCALE_UTC.
> +	 * Smear algorithms are not standardized and the resulting timescale
> +	 * is ambiguous. Implementations using smeared UTC MUST advertise
> +	 * PTP_TIMESCALE_UNKNOWN or PTP_TIMESCALE_PROPRIETARY instead.
> +	 */
> +	PTP_TIMESCALE_UTC = 4,
> +
> +	/**
> +	 * POSIX Time (Unix Time)
> +	 * Epoch: 1970-01-01 00:00:00.
> +	 * Continuity: Discontinuous; leap seconds handled by
> +	 *             repeating/skipping values.
> +	 * Discipline: Follows UTC frequency steering and phase jumps.
> +	 */
> +	PTP_TIMESCALE_POSIX = 5,
> +
> +	/****************** System-Relative Monotonic Clocks ******************
> +	 * These timescales are relative to a system event (like boot)
> +	 * and are not synchronized to an external atomic standard.
> +	 **********************************************************************/
> +
> +	/**
> +	 * Monotonic System Clock (CLOCK_MONOTONIC)
> +	 * Epoch: Arbitrary (System boot time).
> +	 * Continuity: Strictly monotonic; no leap seconds.
> +	 * Discipline: Frequency steered to match system reference;
> +	 *             does not advance during suspend.
> +	 */
> +	PTP_TIMESCALE_MONOTONIC = 6,
> +
> +	/**
> +	 * Raw Monotonic System Clock (CLOCK_MONOTONIC_RAW)
> +	 * Epoch: Arbitrary (System boot time).
> +	 * Continuity: Strictly monotonic; no leap seconds.
> +	 * Discipline: Raw hardware oscillator; no frequency steering
> +	 *             or discipline.
> +	 */
> +	PTP_TIMESCALE_MONOTONIC_RAW = 7,
> +
> +	/**
> +	 * Boot Time System Clock (CLOCK_BOOTTIME)
> +	 * Epoch: Arbitrary (System boot time).
> +	 * Continuity: Strictly monotonic and continuous; no leap seconds.
> +	 * Discipline: Frequency steered to match system reference;
> +	 *             advances during suspend.
> +	 */
> +	PTP_TIMESCALE_BOOTTIME = 8,
> +
> +	/********************** Vendor-Specific Timescale *********************/
> +
> +	/* A proprietary or vendor-specific timescale with custom rules. */
> +	PTP_TIMESCALE_PROPRIETARY = 9,
> +};
> +
>   /*
>    * struct ptp_clock_time - represents a time value
>    *
> @@ -94,6 +225,119 @@ struct ptp_clock_time {
>   	__u32 reserved;
>   };
>   
> +/*
> + * Hardware counter identifiers for struct ptp_sys_time.sys_counter_id
> + */
> +enum ptp_counter_id {
> +	/* Counter value not available or type not specified */
> +	PTP_COUNTER_UNKNOWN = 0,
> +
> +	/* x86 Time Stamp Counter (TSC) */
> +	PTP_COUNTER_X86_TSC = 1,
> +
> +	/* ARM Generic Timer virtual counter */
> +	PTP_COUNTER_ARM_ARCH = 2,
> +};
> +
> +/* Valid flags for struct ptp_clock_attrs.valid */
> +#define PTP_ATTRS_VALID_ERROR_BOUND	(1 << 0)
> +#define PTP_ATTRS_VALID_TIMESCALE	(1 << 1)
> +#define PTP_ATTRS_VALID_STATUS		(1 << 2)
> +
> +/**
> + * struct ptp_clock_attrs - quality attributes for a PHC timestamp
> + *
> + * @valid:       Bitmask of PTP_ATTRS_VALID_* indicating which fields
> + *               are populated. Zero means no attributes available.
> + * @error_bound: Maximum error in nanoseconds. Valid only when
> + *               PTP_ATTRS_VALID_ERROR_BOUND is set.
> + * @timescale:   Clock timescale (enum ptp_clock_timescale). Valid only
> + *               when PTP_ATTRS_VALID_TIMESCALE is set.
> + * @status:      Synchronization status (enum ptp_clock_status). Valid
> + *               only when PTP_ATTRS_VALID_STATUS is set.
> + * @rsv:         Reserved for future use, must be zero.
> + */
> +struct ptp_clock_attrs {
> +	__u32 valid;
> +	__u32 error_bound;

Error relative to what? The advertised timescale's true time, or the
device's sync source? And is this a hard bound or an estimate?

> +	__u32 timescale;
> +	__u32 status;
> +	__u32 rsv[4];
> +};
> +
>