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];
+};
+
