amu.rst

  1.. _amu_index:
  2
  3=======================================================
  4Activity Monitors Unit (AMU) extension in AArch64 Linux
  5=======================================================
  6
  7Author: Ionela Voinescu <ionela.voinescu@arm.com>
  8
  9Date: 2019-09-10
 10
 11This document briefly describes the provision of Activity Monitors Unit
 12support in AArch64 Linux.
 13
 14
 15Architecture overview
 16---------------------
 17
 18The activity monitors extension is an optional extension introduced by the
 19ARMv8.4 CPU architecture.
 20
 21The activity monitors unit, implemented in each CPU, provides performance
 22counters intended for system management use. The AMU extension provides a
 23system register interface to the counter registers and also supports an
 24optional external memory-mapped interface.
 25
 26Version 1 of the Activity Monitors architecture implements a counter group
 27of four fixed and architecturally defined 64-bit event counters.
 28
 29  - CPU cycle counter: increments at the frequency of the CPU.
 30  - Constant counter: increments at the fixed frequency of the system
 31    clock.
 32  - Instructions retired: increments with every architecturally executed
 33    instruction.
 34  - Memory stall cycles: counts instruction dispatch stall cycles caused by
 35    misses in the last level cache within the clock domain.
 36
 37When in WFI or WFE these counters do not increment.
 38
 39The Activity Monitors architecture provides space for up to 16 architected
 40event counters. Future versions of the architecture may use this space to
 41implement additional architected event counters.
 42
 43Additionally, version 1 implements a counter group of up to 16 auxiliary
 4464-bit event counters.
 45
 46On cold reset all counters reset to 0.
 47
 48
 49Basic support
 50-------------
 51
 52The kernel can safely run a mix of CPUs with and without support for the
 53activity monitors extension. Therefore, when CONFIG_ARM64_AMU_EXTN is
 54selected we unconditionally enable the capability to allow any late CPU
 55(secondary or hotplugged) to detect and use the feature.
 56
 57When the feature is detected on a CPU, we flag the availability of the
 58feature but this does not guarantee the correct functionality of the
 59counters, only the presence of the extension.
 60
 61Firmware (code running at higher exception levels, e.g. arm-tf) support is
 62needed to:
 63
 64 - Enable access for lower exception levels (EL2 and EL1) to the AMU
 65   registers.
 66 - Enable the counters. If not enabled these will read as 0.
 67 - Save/restore the counters before/after the CPU is being put/brought up
 68   from the 'off' power state.
 69
 70When using kernels that have this feature enabled but boot with broken
 71firmware the user may experience panics or lockups when accessing the
 72counter registers. Even if these symptoms are not observed, the values
 73returned by the register reads might not correctly reflect reality. Most
 74commonly, the counters will read as 0, indicating that they are not
 75enabled.
 76
 77If proper support is not provided in firmware it's best to disable
 78CONFIG_ARM64_AMU_EXTN. To be noted that for security reasons, this does not
 79bypass the setting of AMUSERENR_EL0 to trap accesses from EL0 (userspace) to
 80EL1 (kernel). Therefore, firmware should still ensure accesses to AMU registers
 81are not trapped in EL2/EL3.
 82
 83The fixed counters of AMUv1 are accessible through the following system
 84register definitions:
 85
 86 - SYS_AMEVCNTR0_CORE_EL0
 87 - SYS_AMEVCNTR0_CONST_EL0
 88 - SYS_AMEVCNTR0_INST_RET_EL0
 89 - SYS_AMEVCNTR0_MEM_STALL_EL0
 90
 91Auxiliary platform specific counters can be accessed using
 92SYS_AMEVCNTR1_EL0(n), where n is a value between 0 and 15.
 93
 94Details can be found in: arch/arm64/include/asm/sysreg.h.
 95
 96
 97Userspace access
 98----------------
 99
100Currently, access from userspace to the AMU registers is disabled due to:
101
102 - Security reasons: they might expose information about code executed in
103   secure mode.
104 - Purpose: AMU counters are intended for system management use.
105
106Also, the presence of the feature is not visible to userspace.
107
108
109Virtualization
110--------------
111
112Currently, access from userspace (EL0) and kernelspace (EL1) on the KVM
113guest side is disabled due to:
114
115 - Security reasons: they might expose information about code executed
116   by other guests or the host.
117
118Any attempt to access the AMU registers will result in an UNDEFINED
119exception being injected into the guest.