include/uapi/linux/vmclock-abi.h

Source file repositories/reference/linux-study-clean/include/uapi/linux/vmclock-abi.h

File Facts

System
Linux kernel
Corpus path
include/uapi/linux/vmclock-abi.h
Extension
.h
Size
9214 bytes
Lines
203
Domain
Core OS
Bucket
Core Kernel Interface
Inferred role
Core OS: implementation source
Status
source implementation candidate

Why This File Exists

Core operating-system implementation surface: boot, tasks, memory, VFS, syscall-facing interfaces, synchronization, credentials, and isolation.

Dependency Surface

Detected Declarations

Annotated Snippet

struct vmclock_abi {
	/* CONSTANT FIELDS */
	__le32 magic;
#define VMCLOCK_MAGIC	0x4b4c4356 /* "VCLK" */
	__le32 size;		/* Size of region containing this structure */
	__le16 version;	/* 1 */
	__u8 counter_id; /* Matches VIRTIO_RTC_COUNTER_xxx except INVALID */
#define VMCLOCK_COUNTER_ARM_VCNT	0
#define VMCLOCK_COUNTER_X86_TSC		1
#define VMCLOCK_COUNTER_INVALID		0xff
	__u8 time_type; /* Matches VIRTIO_RTC_TYPE_xxx */
#define VMCLOCK_TIME_UTC			0	/* Since 1970-01-01 00:00:00z */
#define VMCLOCK_TIME_TAI			1	/* Since 1970-01-01 00:00:00z */
#define VMCLOCK_TIME_MONOTONIC			2	/* Since undefined epoch */
#define VMCLOCK_TIME_INVALID_SMEARED		3	/* Not supported */
#define VMCLOCK_TIME_INVALID_MAYBE_SMEARED	4	/* Not supported */

	/* NON-CONSTANT FIELDS PROTECTED BY SEQCOUNT LOCK */
	__le32 seq_count;	/* Low bit means an update is in progress */
	/*
	 * This field changes to another non-repeating value when the CPU
	 * counter is disrupted, for example on live migration. This lets
	 * the guest know that it should discard any calibration it has
	 * performed of the counter against external sources (NTP/PTP/etc.).
	 */
	__le64 disruption_marker;
	__le64 flags;
	/* Indicates that the tai_offset_sec field is valid */
#define VMCLOCK_FLAG_TAI_OFFSET_VALID		(1 << 0)
	/*
	 * Optionally used to notify guests of pending maintenance events.
	 * A guest which provides latency-sensitive services may wish to
	 * remove itself from service if an event is coming up. Two flags
	 * indicate the approximate imminence of the event.
	 */
#define VMCLOCK_FLAG_DISRUPTION_SOON		(1 << 1) /* About a day */
#define VMCLOCK_FLAG_DISRUPTION_IMMINENT	(1 << 2) /* About an hour */
#define VMCLOCK_FLAG_PERIOD_ESTERROR_VALID	(1 << 3)
#define VMCLOCK_FLAG_PERIOD_MAXERROR_VALID	(1 << 4)
#define VMCLOCK_FLAG_TIME_ESTERROR_VALID	(1 << 5)
#define VMCLOCK_FLAG_TIME_MAXERROR_VALID	(1 << 6)
	/*
	 * If the MONOTONIC flag is set then (other than leap seconds) it is
	 * guaranteed that the time calculated according this structure at
	 * any given moment shall never appear to be later than the time
	 * calculated via the structure at any *later* moment.
	 *
	 * In particular, a timestamp based on a counter reading taken
	 * immediately after setting the low bit of seq_count (and the
	 * associated memory barrier), using the previously-valid time and
	 * period fields, shall never be later than a timestamp based on
	 * a counter reading taken immediately before *clearing* the low
	 * bit again after the update, using the about-to-be-valid fields.
	 */
#define VMCLOCK_FLAG_TIME_MONOTONIC		(1 << 7)
	/*
	 * If the VM_GEN_COUNTER_PRESENT flag is set, the hypervisor will
	 * bump the vm_generation_counter field every time the guest is
	 * loaded from some save state (restored from a snapshot).
	 */
#define VMCLOCK_FLAG_VM_GEN_COUNTER_PRESENT     (1 << 8)
	/*
	 * If the NOTIFICATION_PRESENT flag is set, the hypervisor will send
	 * a notification every time it updates seq_count to a new even number.
	 */
#define VMCLOCK_FLAG_NOTIFICATION_PRESENT       (1 << 9)

	__u8 pad[2];
	__u8 clock_status;
#define VMCLOCK_STATUS_UNKNOWN		0
#define VMCLOCK_STATUS_INITIALIZING	1
#define VMCLOCK_STATUS_SYNCHRONIZED	2
#define VMCLOCK_STATUS_FREERUNNING	3
#define VMCLOCK_STATUS_UNRELIABLE	4

	/*
	 * The time exposed through this device is never smeared. This field
	 * corresponds to the 'subtype' field in virtio-rtc, which indicates
	 * the smearing method. However in this case it provides a *hint* to
	 * the guest operating system, such that *if* the guest OS wants to
	 * provide its users with an alternative clock which does not follow
	 * UTC, it may do so in a fashion consistent with the other systems
	 * in the nearby environment.
	 */
	__u8 leap_second_smearing_hint; /* Matches VIRTIO_RTC_SUBTYPE_xxx */
#define VMCLOCK_SMEARING_STRICT		0
#define VMCLOCK_SMEARING_NOON_LINEAR	1
#define VMCLOCK_SMEARING_UTC_SLS	2
	__le16 tai_offset_sec; /* Actually two's complement signed */
	__u8 leap_indicator;

Annotation

Implementation Notes