diff --git a/.gitignore b/.gitignore index b796a3e..59b81f7 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ website/public website/.hugo_build.lock website/resources/_gen +public/ diff --git a/README.md b/README.md index d41b54a..1737ccc 100644 --- a/README.md +++ b/README.md @@ -95,7 +95,7 @@ This section clarifies on terms and abbreviations used in specs and other docume - [*DPS*](specs/discoverable_partitions_specification.md) - Discovery Partition Specification - [*sysext*](specs/extension_image.md) – System Extension Image (type of DDI that is overlayed on top of `/usr/` and `/opt/` via overlayfs and can extend the underlying OS vendor resources in a composable, immutable fashion) -- [*UKI*](specs/unified_kernel_image.md) - Unified Kernel Images (UEFI boot stub + kernel + initrd + more) +- [*UKI*](specs/unified_kernel_image.md) – Unified Kernel Images (UEFI boot stub + kernel + initrd + more) - [*VMClock*](specs/vmclock.md) – Virtual Machine Clock (efficient time synchronisation for virtual machines) - [*VMGenID*](specs/vmgenid.md) – Virtual Machine Generation ID (mechanism for detecting VM rollback events) - [*VOA*](specs/file_hierarchy_for_the_verification_of_os_artifacts.md) – Verification of OS Artifacts diff --git a/specs/boot_loader_specification.md b/specs/boot_loader_specification.md index 8020ef0..a843852 100644 --- a/specs/boot_loader_specification.md +++ b/specs/boot_loader_specification.md @@ -12,8 +12,8 @@ aliases: # UAPI.1 The Boot Loader Specification -| Version | Changes | -|---------|---------| +| Version | Changes | +|---------|-----------------| | 1.0 | Initial Release | This document defines a set of file formats and naming conventions that allow diff --git a/specs/configuration_files_specification.md b/specs/configuration_files_specification.md index 7ca0eda..cb764e9 100644 --- a/specs/configuration_files_specification.md +++ b/specs/configuration_files_specification.md @@ -10,8 +10,8 @@ aliases: # UAPI.6 Configuration Files Specification -| Version | Changes | -|---------|---------| +| Version | Changes | +|---------|-----------------| | 1.0 | Initial Release | ## Introduction diff --git a/specs/discoverable_disk_image.md b/specs/discoverable_disk_image.md index d9e9caa..5e0633c 100644 --- a/specs/discoverable_disk_image.md +++ b/specs/discoverable_disk_image.md @@ -11,8 +11,8 @@ aliases: --- # UAPI.3 Discoverable Disk Images (DDI) -| Version | Changes | -|---------|---------| +| Version | Changes | +|---------|-----------------| | 1.0 | Initial Release | DDIs (Discoverable Disk Images) are self-describing file system images that follow the DPS ([Discoverable diff --git a/specs/discoverable_partitions_specification.md b/specs/discoverable_partitions_specification.md index 8593e03..35ddf3e 100644 --- a/specs/discoverable_partitions_specification.md +++ b/specs/discoverable_partitions_specification.md @@ -11,8 +11,8 @@ aliases: --- # UAPI.2 The Discoverable Partitions Specification (DPS) -| Version | Changes | -|---------|---------| +| Version | Changes | +|---------|-----------------| | 1.0 | Initial Release | _TL;DR: Let's automatically discover, mount and enable the root partition, diff --git a/specs/elf_dlopen_metadata.md b/specs/elf_dlopen_metadata.md index bd0708f..6ffdc12 100644 --- a/specs/elf_dlopen_metadata.md +++ b/specs/elf_dlopen_metadata.md @@ -12,8 +12,8 @@ aliases: # UAPI.12 `dlopen()` Metadata for ELF Files -| Version | Changes | -|---------|---------| +| Version | Changes | +|---------|-----------------| | 1.0 | Initial Release | ## Target Audience diff --git a/specs/extension_image.md b/specs/extension_image.md index 3b5e377..fc4cd25 100644 --- a/specs/extension_image.md +++ b/specs/extension_image.md @@ -11,8 +11,8 @@ aliases: --- # UAPI.4 Extension Images -| Version | Changes | -|---------|---------| +| Version | Changes | +|---------|-----------------| | 1.0 | Initial Release | Extension Images are DDIs ([Discoverable Disk Images](discoverable_disk_image.md)) that are @@ -207,39 +207,39 @@ incompatible host from loading it. Valid values: -|Architecture| -|------------| -|x86| -|x86-64| -|alpha| -|arc| -|arc-be| -|arm| -|arm-be| -|arm64| -|arm64-be| -|cris| -|ia64| -|loongarch64| -|m68k| -|mips| -|mips-le| -|mips64| -|mips64-le| -|parisc| -|parisc64| -|ppc| -|ppc-le| -|ppc64| -|ppc64-le| -|riscv32| -|riscv64| -|s390| -|s390x| -|sh| -|sh64| -|sparc64| -|sparc| -|tilegx| -|native| -|any| +| Architecture | +|--------------| +| x86 | +| x86-64 | +| alpha | +| arc | +| arc-be | +| arm | +| arm-be | +| arm64 | +| arm64-be | +| cris | +| ia64 | +| loongarch64 | +| m68k | +| mips | +| mips-le | +| mips64 | +| mips64-le | +| parisc | +| parisc64 | +| ppc | +| ppc-le | +| ppc64 | +| ppc64-le | +| riscv32 | +| riscv64 | +| s390 | +| s390x | +| sh | +| sh64 | +| sparc64 | +| sparc | +| tilegx | +| native | +| any | diff --git a/specs/file_hierarchy_for_the_verification_of_os_artifacts.md b/specs/file_hierarchy_for_the_verification_of_os_artifacts.md index fa87a9d..d35d830 100644 --- a/specs/file_hierarchy_for_the_verification_of_os_artifacts.md +++ b/specs/file_hierarchy_for_the_verification_of_os_artifacts.md @@ -12,8 +12,8 @@ aliases: # UAPI.11 File Hierarchy for the Verification of OS Artifacts (VOA) -| Version | Changes | -|---------|---------| +| Version | Changes | +|---------|------------------| | 0.1 | Work in progress | ## Motivation diff --git a/specs/linux_file_system_hierarchy.md b/specs/linux_file_system_hierarchy.md index c7a57a6..8bea2db 100644 --- a/specs/linux_file_system_hierarchy.md +++ b/specs/linux_file_system_hierarchy.md @@ -12,8 +12,8 @@ aliases: # UAPI.9 Linux File System Hierarchy -| Version | Changes | -|---------|---------| +| Version | Changes | +|---------|------------------| | 0.1 | Work in progress | ## Description diff --git a/specs/linux_tpm_pcr_registry.md b/specs/linux_tpm_pcr_registry.md index 4de6ad0..d7e9ad2 100644 --- a/specs/linux_tpm_pcr_registry.md +++ b/specs/linux_tpm_pcr_registry.md @@ -10,8 +10,8 @@ aliases: # 🔏 UAPI.7 Linux TPM PCR Registry 🗒️ -| Version | Changes | -|---------|---------| +| Version | Changes | +|---------|-----------------| | 1.0 | Initial Release | _TPM PCRs are a scarce resource, there are only 24 of them in typical standards compliant TPMs. @@ -73,12 +73,12 @@ In both cases it is important that data measured into the PCRs is carefully chos - - - - - - + + + + + + diff --git a/specs/osc_context.md b/specs/osc_context.md index c414a2f..bdee074 100644 --- a/specs/osc_context.md +++ b/specs/osc_context.md @@ -12,8 +12,8 @@ aliases: # UAPI.15 OSC 3008: Hierarchical Context Signalling -| Version | Changes | -|---------|---------| +| Version | Changes | +|---------|-----------------| | 1.0 | Initial release | A terminal connects a user with programs. Control of the program side of @@ -155,31 +155,31 @@ the start sequence. The sequence ends in ST. The following fields are currently defined for the start sequence: -| Field | Context Types | Description | -|---------------|---------------|-------------------------------------------------------------------------------------------------------------| -| `type=` | *all* | Declares the context type, one of the types described above | -| `user=` | *all* | UNIX user name the process issuing the sequence runs as | -| `hostname=` | *all* | UNIX host name of the system the process issuing the sequence runs on | -| `machineid=` | *all* | The machine ID (i.e. `/etc/machine-id`) of the system the process issuing the sequence runs on | -| `bootid=` | *all* | The boot ID (i.e. `/proc/sys/kernel/random/boot_id`) of the system the process issuing the sequence runs on | -| `pid=` | *all* | The numeric PID of the process issuing the sequence, in decimal notation | -| `pidfdid=` | *all* | The 64bit inode number of the pidfd of the process issuing the sequence, in decimal notation | -| `comm=` | *all* | The process name (i.e. `/proc/$PID/comm`, `PR_GET_NAME`) of the process issuing the sequence | -| `cwd=` | `shell`, `command` | The current working directory | -| `cmdline=` | `command` | The full command line of the invoked command | -| `vm=` | `vm` | The name of the VM being invoked | -| `container=` | `container` | The name of the container being invoked | -| `targetuser=` | `elevate`, `chpriv`, `vm`, `container`, `remote`, `session` | Target UNIX user name | -| `targethost=` | `remote` | Target UNIX, DNS host name, or IP address | -| `sessionid=` | `session` | New allocated session ID | +| Field | Context Types | Description | +|---------------|-------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------| +| `type=` | *all* | Declares the context type, one of the types described above | +| `user=` | *all* | UNIX user name the process issuing the sequence runs as | +| `hostname=` | *all* | UNIX host name of the system the process issuing the sequence runs on | +| `machineid=` | *all* | The machine ID (i.e. `/etc/machine-id`) of the system the process issuing the sequence runs on | +| `bootid=` | *all* | The boot ID (i.e. `/proc/sys/kernel/random/boot_id`) of the system the process issuing the sequence runs on | +| `pid=` | *all* | The numeric PID of the process issuing the sequence, in decimal notation | +| `pidfdid=` | *all* | The 64bit inode number of the pidfd of the process issuing the sequence, in decimal notation | +| `comm=` | *all* | The process name (i.e. `/proc/$PID/comm`, `PR_GET_NAME`) of the process issuing the sequence | +| `cwd=` | `shell`, `command` | The current working directory | +| `cmdline=` | `command` | The full command line of the invoked command | +| `vm=` | `vm` | The name of the VM being invoked | +| `container=` | `container` | The name of the container being invoked | +| `targetuser=` | `elevate`, `chpriv`, `vm`, `container`, `remote`, `session` | Target UNIX user name | +| `targethost=` | `remote` | Target UNIX, DNS host name, or IP address | +| `sessionid=` | `session` | New allocated session ID | The following fields are currently defined for the end sequence: -| Field | Context Types | Description | -|---------------|---------------|-------------------------------------------------------------------------------------------------------------| -| `exit=` | `command` | One of `success`, `failure`, `crash`, `interrupt`, indicating how the program terminated | -| `status=` | `command` | The command's numeric exit status, i.e. the 0…255 value a program returns | -| `signal=` | `command` | The termination signal of the command, if it died abnormally. A symbolic signal name. (`SIGKILL`, …) | +| Field | Context Types | Description | +|-----------|---------------|------------------------------------------------------------------------------------------------------| +| `exit=` | `command` | One of `success`, `failure`, `crash`, `interrupt`, indicating how the program terminated | +| `status=` | `command` | The command's numeric exit status, i.e. the 0…255 value a program returns | +| `signal=` | `command` | The termination signal of the command, if it died abnormally. A symbolic signal name. (`SIGKILL`, …) | All fields are optional, including the context type. However, it is generally recommended to always include the first 7 fields listed above, to make it easy diff --git a/specs/package_metadata_for_executable_files.md b/specs/package_metadata_for_executable_files.md index bfe1093..a3d000d 100644 --- a/specs/package_metadata_for_executable_files.md +++ b/specs/package_metadata_for_executable_files.md @@ -12,8 +12,8 @@ aliases: # UAPI.8 Package Metadata for Executable Files -| Version | Changes | -|---------|---------| +| Version | Changes | +|---------|-----------------| | 1.0 | Initial Release | ## Target Audience diff --git a/specs/unified_kernel_image.md b/specs/unified_kernel_image.md index 20ac8ec..440768f 100644 --- a/specs/unified_kernel_image.md +++ b/specs/unified_kernel_image.md @@ -11,8 +11,8 @@ aliases: --- # UAPI.5 Unified Kernel Images (UKI) -| Version | Changes | -|---------|---------| +| Version | Changes | +|---------|-----------------| | 1.0 | Initial Release | A Unified Kernel Image (UKI) is a combination of an UEFI boot stub program, diff --git a/specs/version_format_specification.md b/specs/version_format_specification.md index 902bab0..4ce04dc 100644 --- a/specs/version_format_specification.md +++ b/specs/version_format_specification.md @@ -11,8 +11,8 @@ aliases: # UAPI.10 Version Format Specification -| Version | Changes | -|---------|---------| +| Version | Changes | +|---------|-----------------| | 1.0 | Initial Release | This specification defines the format of version strings and their ordering. diff --git a/specs/vmclock.md b/specs/vmclock.md index d6a0864..e1e3499 100644 --- a/specs/vmclock.md +++ b/specs/vmclock.md @@ -12,8 +12,8 @@ aliases: # UAPI.13 VMClock: Efficient Time Synchronisation for Virtual Machines -| Version | Changes | -|---------|---------| +| Version | Changes | +|---------|-----------------| | 1.0 | Initial Release | The requirements for accurate synchronisation of application clocks against @@ -100,56 +100,208 @@ complete, as described below. ### Structure Fields -| Offset | Field | Description | -|--------|-------|-------------| -| 0x00 | `uint32_t magic` | Magic value `0x4b4c4356` ("VCLK") | -| 0x04 | `uint32_t size` | Size of region containing this structure (typically a full page at the granularity at which the hypervisor maps memory to the guest) | -| 0x08 | `uint16_t version` | This standard defines version 1. Since the `flags` field allows for extensions to the data structure without breaking backward compatibility, it is not anticipated that the `version` field will ever need to change. | -| 0x0a | `uint8_t counter_id` | The hardware counter used as the basis for clock readings. The values of this field correspond to the `VIRTIO_RTC_COUNTER_xxx` values: | -| | | • `0x00`: `VMCLOCK_COUNTER_ARM_VCNT`: The Arm architectural timer (virtual) | -| | | • `0x01`: `VMCLOCK_COUNTER_X86_TSC`: The x86 Time Stamp Counter | -| | | • `0xFF`: `VMCLOCK_COUNTER_INVALID`: No precision clock is advertised | -| 0x0b | `uint8_t time_type` | Indicates the type of clock exposed through this interface. The values of this field correspond to the `VIRTIO_RTC_CLOCK_xxx` values, except that smearing of clocks is not supported as it is antithetical to precision: | -| | | • `0x00`: `VMCLOCK_TIME_UTC` *(Not recommended)* | -| | | • `0x01`: `VMCLOCK_TIME_TAI` | -| | | • `0x02`: `VMCLOCK_MONOTONIC` | -| | | For UTC and TAI, the calculation results in a number of seconds since midnight on 1970-01-01. A monotonic clock has no defined epoch. Since UTC has leap seconds and a given numbered second may occur more than once, its use is **NOT RECOMMENDED** in VMClock. Implementations should advertise TAI, with a correct UTC offset. | -| 0x0c | `uint32_t seq_count` | This field is used to provide a sequence-based read/write lock for the non-constant fields which follow. To perform an update, the device will: | -| | | • Increment this field to an odd value (with the low bit set). | -| | | • Change other fields as appropriate. | -| | | • Increment this field again to an even value. | -| 0x10 | `uint64_t disruption_marker` | This field is changed each time there may be a disruption to the hardware counter referenced by `counter_id`, for example through live migration to a new hypervisor host. | -| 0x18 | `uint64_t flags` | Feature flags (see below) | -| 0x20 | `uint16_t pad` | Unused | -| 0x22 | `uint8_t clock_status` | Synchronisation status of the clock (see below) | -| 0x23 | `uint8_t leap_second_smearing_hint` | Smearing hint for guest OS (see below) | -| 0x24 | `int16_t tai_offset_sec` | Signed offset from TAI to UTC at the reference time specified in `time_sec` and `time_frac_sec`, in seconds. Valid if the corresponding bit in the flags field is set. Implementations SHOULD populate this field; the value at time of writing is 37. | -| 0x26 | `uint8_t leap_indicator` | Indicates the presence and direction of a leap second occurring in the near future or recent past (see below) | -| 0x27 | `uint8_t counter_period_shift` | Additional shift applied to all the `counter_period*_frac_sec` fixed-point fields. | -| 0x28 | `uint64_t counter_value` | Value of the hardware counter at the time represented by `time_sec` + `time_frac_sec`. | -| 0x30 | `uint64_t counter_period_frac_sec` | Period of a single counter tick, in units of 1 >> (64 + `counter_period_shift`) | -| 0x38 | `uint64_t counter_period_esterror_rate_frac_sec` | Estimated ± error of `counter_period_frac_sec` in the same units. | -| 0x40 | `uint64_t counter_period_maxerror_rate_frac_sec` | Maximum ± error of `counter_period_frac_sec` in the same units. | -| 0x48 | `uint64_t time_sec` | Reference time point, seconds since epoch defined by `time_type` field. | -| 0x50 | `uint64_t time_frac_sec` | Fractional part of reference time, in units of second / 2⁶⁴. | -| 0x58 | `uint64_t time_esterror_nanosec` | Estimated ± error of the time given in `time_sec` + `time_frac_sec`, in nanoseconds | -| 0x60 | `uint64_t time_maxerror_nanosec` | Maximum ± error of the time given in `time_sec` + `time_frac_sec`, in nanoseconds | -| 0x64 | `uint64_t vm_generation_count` | A change in this field indicates that the guest has been cloned or loaded from a snapshot (see below). | -| 0x68 | ... | The size of the memory region containing this structure is given in the `size` field, which will typically be a full 4KiB page. New fields may be added here, advertised by newly-defined bits in the `flags` field, without changing the `version` field. | +

PCR#

Used byFrom LocationMeasured ObjectsLogUse Reported By

PCR#

Used byFrom LocationMeasured ObjectsLogUse Reported By
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OffsetFieldDescription
0x00uint32_t magicMagic value 0x4b4c4356 (“VCLK”)
0x04uint32_t sizeSize of region containing this structure (typically a full page at + the granularity at which the hypervisor maps memory to the guest)
0x08uint16_t versionThis standard defines version 1. Since the flags field + allows for extensions to the data structure without breaking backward + compatibility, it is not anticipated that the version field + will ever need to change.
0x0auint8_t counter_idThe hardware counter used as the basis for clock readings. The + values of this field correspond to the + VIRTIO_RTC_COUNTER_xxx values: +
    +
  • 0x00: VMCLOCK_COUNTER_ARM_VCNT: The Arm + architectural timer (virtual)
    • +
  • 0x01: VMCLOCK_COUNTER_X86_TSC: The x86 + Time Stamp Counter
    • +
  • 0xFF: VMCLOCK_COUNTER_INVALID: No + precision clock is advertised
    • +
+
0x0buint8_t time_typeIndicates the type of clock exposed through this interface. The + values of this field correspond to the VIRTIO_RTC_CLOCK_xxx + values, except that smearing of clocks is not supported as it is + antithetical to precision: +
    +
  • 0x00: VMCLOCK_TIME_UTC (Not + recommended)
    • +
  • 0x01: VMCLOCK_TIME_TAI
    • +
  • 0x02: VMCLOCK_MONOTONIC
    • +
+ For UTC and TAI, the calculation results in a number of seconds + since midnight on 1970-01-01. A monotonic clock has no defined epoch. + Since UTC has leap seconds and a given numbered second may occur more + than once, its use is NOT RECOMMENDED in VMClock. + Implementations should advertise TAI, with a correct UTC offset. +
0x0cuint32_t seq_countThis field is used to provide a sequence-based read/write lock for + the non-constant fields which follow. To perform an update, the device + will: +
    +
  • Increment this field to an odd value (with the low bit set)
    • +
  • Change other fields as appropriate.
    • +
  • Increment this field again to an even value.
    • +
+
0x10uint64_t disruption_markerThis field is changed each time there may be a disruption to the + hardware counter referenced by counter_id, for example + through live migration to a new hypervisor host.
0x18uint64_t flagsFeature flags (see below)
0x20uint16_t padUnused
0x22uint8_t clock_statusSynchronisation status of the clock (see below)
0x23uint8_t leap_second_smearing_hintSmearing hint for guest OS (see below)
0x24int16_t tai_offset_secSigned offset from TAI to UTC at the reference time specified in + time_sec and time_frac_sec, in seconds. Valid + if the corresponding bit in the flags field is set. Implementations + SHOULD populate this field; the value at time of writing is 37.
0x26uint8_t leap_indicatorIndicates the presence and direction of a leap second occurring in + the near future or recent past (see below)
0x27uint8_t counter_period_shiftAdditional shift applied to all the + counter_period*_frac_sec fixed-point fields.
0x28uint64_t counter_valueValue of the hardware counter at the time represented by + time_sec + time_frac_sec.
0x30uint64_t counter_period_frac_secPeriod of a single counter tick, in units of 1 >> (64 + + counter_period_shift)
0x38uint64_t counter_period_esterror_rate_frac_secEstimated ± error of counter_period_frac_sec in the + same units.
0x40uint64_t counter_period_maxerror_rate_frac_secMaximum ± error of counter_period_frac_sec in the same + units.
0x48uint64_t time_secReference time point, seconds since epoch defined by + time_type field.
0x50uint64_t time_frac_secFractional part of reference time, in units of second / 2⁶⁴.
0x58uint64_t time_esterror_nanosecEstimated ± error of the time given in time_sec + + time_frac_sec, in nanoseconds
0x60uint64_t time_maxerror_nanosecMaximum ± error of the time given in time_sec + + time_frac_sec, in nanoseconds
0x64uint64_t vm_generation_countA change in this field indicates that the guest has been cloned or + loaded from a snapshot (see below).
0x68…The size of the memory region containing this structure is given in + the size field, which will typically be a full 4KiB page. + New fields may be added here, advertised by newly-defined bits in the + flags field, without changing the version + field.
### Feature Flags (0x18) -| Bit | Flag | Description | -|-----|------|-------------| -| 0 | `VMCLOCK_FLAG_TAI_OFFSET_VALID` | Indicates that the `tai_offset` field below contains a correct value. All implementations SHOULD set this bit. | -| 1 | `VMCLOCK_FLAG_DISRUPTION_SOON` | Indicates that a clock disruption event (e.g. live migration) is expected to happen in the next day or so. | -| 2 | `VMCLOCK_FLAG_DISRUPTION_IMMINENT` | Indicates that a clock disruption event is expected to happen within the next hour or so. | -| 3 | `VMCLOCK_FLAG_PERIOD_ESTERROR_VALID` | Indicates that `counter_period_esterror_rate_frac_sec` contains valid data. | -| 4 | `VMCLOCK_FLAG_PERIOD_MAXERROR_VALID` | Indicates that `counter_period_maxerror_rate_frac_sec` contains valid data. | -| 5 | `VMCLOCK_FLAG_TIME_ESTERROR_VALID` | Indicates that `time_esterror_nanosec` contains valid data. | -| 6 | `VMCLOCK_FLAG_TIME_MAXERROR_VALID` | Indicates that `time_maxerror_nanosec` contains valid data. | -| 7 | `VMCLOCK_FLAG_VM_GEN_COUNTER_PRESENT` | Indicates that the `vm_generation_counter` field is present. | -| 8 | `VMCLOCK_FLAG_NOTIFICATION_PRESENT` | Indicates that the VMClock device will send an interrupt or ACPI notification every time it updates `seq_count` to a new even value. | +| Bit | Flag | Description | +|-----|---------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------| +| 0 | `VMCLOCK_FLAG_TAI_OFFSET_VALID` | Indicates that the `tai_offset` field below contains a correct value. All implementations SHOULD set this bit. | +| 1 | `VMCLOCK_FLAG_DISRUPTION_SOON` | Indicates that a clock disruption event (e.g. live migration) is expected to happen in the next day or so. | +| 2 | `VMCLOCK_FLAG_DISRUPTION_IMMINENT` | Indicates that a clock disruption event is expected to happen within the next hour or so. | +| 3 | `VMCLOCK_FLAG_PERIOD_ESTERROR_VALID` | Indicates that `counter_period_esterror_rate_frac_sec` contains valid data. | +| 4 | `VMCLOCK_FLAG_PERIOD_MAXERROR_VALID` | Indicates that `counter_period_maxerror_rate_frac_sec` contains valid data. | +| 5 | `VMCLOCK_FLAG_TIME_ESTERROR_VALID` | Indicates that `time_esterror_nanosec` contains valid data. | +| 6 | `VMCLOCK_FLAG_TIME_MAXERROR_VALID` | Indicates that `time_maxerror_nanosec` contains valid data. | +| 7 | `VMCLOCK_FLAG_VM_GEN_COUNTER_PRESENT` | Indicates that the `vm_generation_counter` field is present. | +| 8 | `VMCLOCK_FLAG_NOTIFICATION_PRESENT` | Indicates that the VMClock device will send an interrupt or ACPI notification every time it updates `seq_count` to a new even value. | Unknown flags set by the device can safely be ignored. If a change in behaviour is required by a future version of this specification, it would come with a new @@ -158,13 +310,13 @@ compatibility with existing users. ### Clock Status (0x22) -| Value | Status | Description | -|-------|--------|-------------| -| 0x00 | `VMCLOCK_STATUS_UNKNOWN` | The clock is in an indeterminate state. Clock parameters in the VMClock structure are not valid and should not be relied upon. | -| 0x01 | `VMCLOCK_STATUS_INITIALIZING` | The clock is being initialized and is not yet synchronized. Clock parameters in the VMClock structure are not valid and should not be relied upon. | -| 0x02 | `VMCLOCK_STATUS_SYNCHRONIZED` | The clock is synchronized. Clock parameters in the VMClock structure are expected to be correct and may be relied upon. | -| 0x03 | `VMCLOCK_STATUS_FREERUNNING` | The clock has transitioned away from being synchronized and is in a free-running state. Clock parameters in the VMClock structure are expected to be valid and may be relied upon. | -| 0x04 | `VMCLOCK_STATUS_UNRELIABLE` | The clock is considered broken. Clock parameters in the VMClock structure should not be relied upon. | +| Value | Status | Description | +|-------|-------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| 0x00 | `VMCLOCK_STATUS_UNKNOWN` | The clock is in an indeterminate state. Clock parameters in the VMClock structure are not valid and should not be relied upon. | +| 0x01 | `VMCLOCK_STATUS_INITIALIZING` | The clock is being initialized and is not yet synchronized. Clock parameters in the VMClock structure are not valid and should not be relied upon. | +| 0x02 | `VMCLOCK_STATUS_SYNCHRONIZED` | The clock is synchronized. Clock parameters in the VMClock structure are expected to be correct and may be relied upon. | +| 0x03 | `VMCLOCK_STATUS_FREERUNNING` | The clock has transitioned away from being synchronized and is in a free-running state. Clock parameters in the VMClock structure are expected to be valid and may be relied upon. | +| 0x04 | `VMCLOCK_STATUS_UNRELIABLE` | The clock is considered broken. Clock parameters in the VMClock structure should not be relied upon. | ### Leap Second Smearing Hint (0x23) @@ -175,25 +327,25 @@ 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. -| Value | Hint | -|-------|------| -| 0x00 | `VMCLOCK_SMEARING_STRICT` | -| 0x01 | `VMCLOCK_SMEARING_NOON_LINEAR` | -| 0x02 | `VMCLOCK_SMEARING_UTC_SLS` | +| Value | Hint | +|-------|--------------------------------| +| 0x00 | `VMCLOCK_SMEARING_STRICT` | +| 0x01 | `VMCLOCK_SMEARING_NOON_LINEAR` | +| 0x02 | `VMCLOCK_SMEARING_UTC_SLS` | ### Leap Indicator (0x26) The value of this field shall be valid for the point in time referenced by the `time_sec` and `time_frac_sec` fields. -| Value | Indicator | Description | -|-------|-----------|-------------| -| 0x00 | `VMCLOCK_LEAP_NONE` | No known nearby leap second | -| 0x01 | `VMCLOCK_LEAP_PRE_POS` | A positive leap second will occur at the end of the present month | -| 0x02 | `VMCLOCK_LEAP_PRE_NEG` | A negative leap second will occur at the end of the present month | -| 0x03 | `VMCLOCK_LEAP_POS` | A positive leap second is currently occurring (set during the 23:59:60 second) | -| 0x04 | `VMCLOCK_LEAP_POST_POS` | A positive leap second occurred at the end of the previous month | -| 0x05 | `VMCLOCK_LEAP_POST_NEG` | A negative leap second occurred at the end of the previous month | +| Value | Indicator | Description | +|-------|-------------------------|--------------------------------------------------------------------------------| +| 0x00 | `VMCLOCK_LEAP_NONE` | No known nearby leap second | +| 0x01 | `VMCLOCK_LEAP_PRE_POS` | A positive leap second will occur at the end of the present month | +| 0x02 | `VMCLOCK_LEAP_PRE_NEG` | A negative leap second will occur at the end of the present month | +| 0x03 | `VMCLOCK_LEAP_POS` | A positive leap second is currently occurring (set during the 23:59:60 second) | +| 0x04 | `VMCLOCK_LEAP_POST_POS` | A positive leap second occurred at the end of the previous month | +| 0x05 | `VMCLOCK_LEAP_POST_NEG` | A negative leap second occurred at the end of the previous month | ### VM Generation Count (0x64) diff --git a/specs/vmgenid.md b/specs/vmgenid.md index fb9df93..a456376 100644 --- a/specs/vmgenid.md +++ b/specs/vmgenid.md @@ -12,8 +12,8 @@ aliases: # UAPI.14 VMGenID: Virtual Machine Generation ID -| Version | Changes | -|---------|---------| +| Version | Changes | +|---------|-----------------| | 1.0 | Initial Release | Virtual machine operations that restore a VM to an earlier point in time (such as applying snapshots, restoring from backup, cloning, or failover scenarios) can cause serious problems for applications that depend on unique identifiers or cryptographic entropy. The Virtual Machine Generation ID (VMGenID) device provides a mechanism for guest software to detect when such operations have occurred. @@ -26,10 +26,10 @@ The hypervisor provides 16 bytes in shared memory containing the generation ID. ### Structure Fields -| Offset | Field | Description | -|--------|-------|-------------| -| 0x00 | `uint64_t generation_id_low` | Lower 64 bits of the 128-bit generation ID | -| 0x08 | `uint64_t generation_id_high` | Upper 64 bits of the 128-bit generation ID | +| Offset | Field | Description | +|--------|-------------------------------|--------------------------------------------| +| 0x00 | `uint64_t generation_id_low` | Lower 64 bits of the 128-bit generation ID | +| 0x08 | `uint64_t generation_id_high` | Upper 64 bits of the 128-bit generation ID | The generation ID is a 128-bit cryptographically random value that is unique across all VM instances and time. All 128 bits are random; it is *not* a Version 4 UUID.