|
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [XEN PATCH v2] docs/fusa: add the Arm Generic Timer architecture specification
Describe how Xen uses the Arm Generic Timer over the lifetime of a VM: the two timers it exposes, how each relates to the system counter, what it sets up while creating a VM, and how it emulates the physical timer and handles the virtual one. Also describe freedom from interference between VMs. The timers are emulated per vCPU, so timer programming in one VM does not alter another's. The virtual timer is isolated by the per VM offset in CNTVOFF_EL2 and the per vCPU context saved and restored across context switches; the physical timer by the per vCPU state Xen keeps for the trapped accesses. A VM that reprograms its own physical timer clears its own pending condition, which the architecture requires of a timer given a new deadline and which affects no other VM. Add an architecture_specs index and reference it from the functional safety documentation index. Signed-off-by: Ayan Kumar Halder <ayan.kumar.halder@xxxxxxx> --- Changes in v2: - Dropped Matt's Reviewed-by: the patch changed materially after his review (timer-name capitalisation and the footnote conversion below were not in the reviewed version), so the tag is not carried forward. - Fixed typo "creeation" -> "creation" in the VM-creation section heading. (Matt) - Corrected the CNTV_TVAL_EL0 description from "compare value register" to "timer value register" (TVAL is the timer-value alias, CVAL is the comparator). (Matt) - Grammar: "The interrupt behave" -> "The interrupt behaves". (Matt) - Capitalised and hyphenated the timer names in the interrupt-id table: "Secure" / "Non-secure", matching Arm terminology. (Matt) - Converted the [1]/[2] references from a manual line block to proper RST footnotes (.. [1] / [2]_), so Sphinx renders numbered citations and cross-references. (Matt) - Added the arm64_generic_timer_plat_program_cntfrq_el0 design requirement to the Covers: list, so the architecture specification covers all of the generic-timer design requirements in docs/fusa/reqs/design-reqs/arm64/generic-timer.rst. - Added a blank line between the interrupt-id list-table and the following paragraph to silence a Sphinx "explicit markup ends without a blank line" warning. - Rebased onto current staging; split out from the v1 2/2 series as a standalone patch (arch spec only), adding the architecture_specs index and wiring it into docs/fusa/index.rst. .../fusa/architecture_specs/generic_timer.rst | 251 ++++++++++++++++++ docs/fusa/architecture_specs/index.rst | 9 + docs/fusa/index.rst | 1 + 3 files changed, 261 insertions(+) create mode 100644 docs/fusa/architecture_specs/generic_timer.rst create mode 100644 docs/fusa/architecture_specs/index.rst diff --git a/docs/fusa/architecture_specs/generic_timer.rst b/docs/fusa/architecture_specs/generic_timer.rst new file mode 100644 index 0000000000..bb2d066f8d --- /dev/null +++ b/docs/fusa/architecture_specs/generic_timer.rst @@ -0,0 +1,251 @@ +.. SPDX-License-Identifier: CC-BY-4.0 + +Generic Timer +============= + +`XenArch~arm64_generic_timer~1` + +Covers: + - `XenSwdgn~arm64_generic_timer_probe_dt~1` + - `XenSwdgn~arm64_generic_timer_read_freq~1` + - `XenSwdgn~arm64_generic_timer_access_cntkctlel1~1` + - `XenSwdgn~arm64_generic_timer_access_virtual_timer~1` + - `XenSwdgn~arm64_generic_timer_access_physical_timer~1` + - `XenSwdgn~arm64_generic_timer_trigger_virtual_interrupt~1` + - `XenSwdgn~arm64_generic_timer_trigger_physical_interrupt~1` + - `XenSwdgn~arm64_generic_timer_plat_program_cntfrq_el0~1` + +Needs: + - XenTestCase + +This document describes Xen's usage of the Arm Generic Timer during the +lifetime of a VM. + +Introduction +------------ + +The Generic Timer: + +- provides a system counter that measures the passing of time in real-time, +- supports virtual counters that measure the passing of virtual-time. That is, + a virtual counter can measure the passing of time on a particular + virtual machine, +- can trigger events after a period of time has passed. + +Types of timers +--------------- + +Xen exposes two types of timer over the lifetime of a VM: + +- physical timer +- virtual timer + +:: + + +------------------+ + | System Counter | + +--------+---------+ + | System Time Bus + +----------------------------+ + | | + | v + | +-------+ +----------+ + | | - |<------| CNTVOFF | + | +---+---+ +----------+ + | | + v v + +---------+ +---------+ + | CNTPCT | | CNTVCT | + +---------+ +---------+ + +---------+ +---------+ + | Physical| | Virtual | + | Timer | | Timer | + +---------+ +---------+ + ( PE ) + +The physical timer measures the passage of time in relation to the physical +counter, CNTPCT_EL0. The physical counter starts from zero when the system +counter starts, that is, at power-on or reset, so its value is not related to +when Xen booted. Xen derives its own system time (``NOW()`` / ``get_s_time()``) +from it by subtracting a snapshot of CNTPCT taken at boot, so that system time +is measured from Xen boot. The physical timer is accessed by the following +registers: + +- CNTPCT_EL0 - physical count value +- CNTP_CTL_EL0 - control register +- CNTP_CVAL_EL0 - compare value register +- CNTP_TVAL_EL0 - timer value register + +The virtual timer measures the passage of time in relation to the virtual +counter. It is used to broadcast the virtual time (physical - offset). Offset is +set by Xen (CNTVOFF_EL2 register) during VM creation. As a result, the virtual +time will report time from the creation of the VM. It is accessed by the +following registers: + +- CNTVCT_EL0 - virtual count value +- CNTV_CTL_EL0 - control register +- CNTV_CVAL_EL0 - compare value register +- CNTV_TVAL_EL0 - timer value register + +CNTFRQ_EL0 reports the frequency of the system counter. However, this register +is not populated by hardware. The register is writable at the highest +implemented Exception level and readable at all Exception levels. Firmware, +typically running at EL3, populates this register as part of early system +initialization. Higher-level software, like an operating system, can then use +the register to get the frequency. + +Xen reads the counter frequency from the device tree (the timer node's +``clock-frequency`` property, or the firmware-populated CNTFRQ_EL0) and relies +on that value being correct; it is a configuration input to Xen's system time, +not something Xen can independently cross-check against hardware. + +Generic timer usage during VM creation +-------------------------------------- + +While preparing the device tree for a VM, Xen creates a timer node (based on the +device tree bindings [2]_ and architecture specification [1]_) for the VM. For +this, the host device tree is expected to have a node for the generic timer. + +During the VM creation, Xen sets the offset (CNTVOFF_EL2) used to broadcast the +virtual time for a VM and assigns the following per processor interrupts for +timers. + +.. list-table:: + :header-rows: 1 + + * - Name + - Interrupt id + + * - Virtual timer + - 27 + + * - Physical Secure timer + - 29 + + * - Physical Non-secure timer + - 30 + +Xen reserves the 27, 29 and 30 interrupt ids in the virtual GIC. The exception +to this is for hardware VM, where the VM will be assigned interrupt numbers the +same as in the host device tree. + +The parent interrupt is linked to the Generic interrupt controller node. + +If the host device tree node for the generic timer contains the property +"clock-frequency", the same is passed on to the guest device tree. + +During the VM vCPU creation, Xen initializes the internal/background timers (one +for physical timer and one for virtual timer). + +Generic timer interface between Xen and VM +------------------------------------------ + +VM can make use of both the physical and virtual timer. + +Physical timer +^^^^^^^^^^^^^^ + +Xen traps VM's accesses to system registers related to physical timer (except +CNTPCT_EL0). This is done to allow Xen to emulate the physical timer for a VM, +that is, to check that the access is permitted and to translate the compare +value the VM programs, which is an absolute physical counter value, into Xen's +system time. Xen does not route the physical timer interrupt to guest or itself. +Instead, it makes use of the internal timer used for the physical timer +emulation to schedule the interrupt injection into the VM. + +The flow can be depicted as follows: + +:: + + +---------------------------------------------------+ + | VMs read or write | + | any of CNTP_CTL, CNTP_CVAL, CNTP_TVAL | + +-------------------------+-------------------------+ + | + v + +---------------------------------------------------+ + | MSR/MRS instruction is trapped by Xen | + +-------------------------+-------------------------+ + | + v + +---------------------------------------------------+ + | Xen reads or writes to the register | + | on behalf of VM | + | | + | 1. For read access : Xen returns the value from | + | the VM's vcpu physical timer context. | + | 2. For write access : Xen saves the value in the | + | VM's vcpu physical timer context. Depending | + | on the value, it schedules the internal timer | + | for interrupt injection. | + | | + | Increments the VM program counter | + | and returns control to VM. | + +---------------------------------------------------+ + +Virtual timer +^^^^^^^^^^^^^ + +Xen does not trap accesses to system registers related to virtual timer. +The timer context (i.e. content of timer registers) is saved/restored during the +vCPU context switch. At save time, Xen initializes an internal timer to make +sure the VM's vCPU is scheduled at the time of the next virtual timer interrupt. +The virtual timer interrupt is first routed to Xen, masked and injected into the +VM. The interrupt behaves in a level-sensitive manner, meaning the timer will +continue to signal the interrupt until one of the following situations occurs: + +- interrupt is masked +- timer is disabled +- firing condition is no longer met + +Xen masks the interrupt (using the CNTV_CTL_EL0 register) before injecting it +into the VM to avoid an interrupt storm that could otherwise occur if the VM +did not handle the interrupt properly. This masking is specific to the virtual +timer: Xen does not mask the physical timer when injecting its interrupt (see +the physical timer section above), and that difference is what the virtual and +physical deschedule test cases verify. + +Freedom from interference +------------------------- + +The Generic Timer is emulated per vCPU, so timer programming in one VM cannot +alter another VM's timer state. The mechanism differs between the two timers. + +Virtual timer isolation +^^^^^^^^^^^^^^^^^^^^^^^ + +Each VM has its own virtual time base, which Xen sets in CNTVOFF_EL2 during VM +creation, so the virtual count a VM reads is its own. The virtual timer +context, that is the compare and control registers, is saved and restored per +vCPU across context switches, and the internal timer Xen uses to schedule +interrupt injection is per vCPU as well. Every emulation path acts on the vCPU +that trapped, so one VM enabling, disabling or rearming its virtual timer does +not change what another VM's virtual timer is waiting for, nor when it fires. +This isolation assumes the per-vCPU virtual timer context is saved and restored +on every vCPU context switch; that save/restore is the premise the freedom-from- +interference claim depends on. + +Physical timer isolation +^^^^^^^^^^^^^^^^^^^^^^^^ + +The physical timer is fully emulated, and the compare value, control value and +pending condition Xen keeps on a VM's behalf are per vCPU. One VM's accesses +to CNTP_CTL_EL0, CNTP_CVAL_EL0 or CNTP_TVAL_EL0 are trapped and applied to its +own context only. + +A VM that writes CNTP_TVAL_EL0 or CNTP_CVAL_EL0 while its physical timer has a +pending condition clears that condition and re-arms the timer. This is the +behaviour the architecture requires of a timer that is given a new deadline, +and it affects only the VM that performs the write. It is not a loss of an +interrupt belonging to another VM. + +System counter isolation +^^^^^^^^^^^^^^^^^^^^^^^^ + +The system counter itself is read-only to a VM and monotonic, so concurrent +reads from several VMs cannot interfere with one another. Both timers derive +from it, the physical one directly and the virtual one through the per VM +offset described above. + +.. [1] Arm Architecture Reference Manual for A-profile architecture, Chapter 11 +.. [2] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/devicetree/bindings/timer/arm,arch_timer.yaml diff --git a/docs/fusa/architecture_specs/index.rst b/docs/fusa/architecture_specs/index.rst new file mode 100644 index 0000000000..395e3c1225 --- /dev/null +++ b/docs/fusa/architecture_specs/index.rst @@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: CC-BY-4.0 + +Architecture specifications +=========================== + +.. toctree:: + :maxdepth: 2 + + generic_timer diff --git a/docs/fusa/index.rst b/docs/fusa/index.rst index 5f1e8acfc4..b3c72ec7d4 100644 --- a/docs/fusa/index.rst +++ b/docs/fusa/index.rst @@ -7,3 +7,4 @@ Functional Safety documentation :maxdepth: 2 reqs/index + architecture_specs/index base-commit: c4a09c112c391ffc1aea33afff49ffb28156fbdb -- 2.25.1
|
 |
Lists.xenproject.org is hosted with RackSpace, monitoring our |