Documentation/arm64/amu.rst

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