Documentation/arch/powerpc/elf_hwcaps.rst

   1 .. _elf_hwcaps_powerpc:
   2
   3 ==================
   4 POWERPC ELF HWCAPs
   5 ==================
   6
   7 This document describes the usage and semantics of the powerpc ELF HWCAPs.
   8
   9
  10 1. Introduction
  11 ---------------
  12
  13 Some hardware or software features are only available on some CPU
  14 implementations, and/or with certain kernel configurations, but have no other
  15 discovery mechanism available to userspace code. The kernel exposes the
  16 presence of these features to userspace through a set of flags called HWCAPs,
  17 exposed in the auxiliary vector.
  18
  19 Userspace software can test for features by acquiring the AT_HWCAP or
  20 AT_HWCAP2 entry of the auxiliary vector, and testing whether the relevant
  21 flags are set, e.g.::
  22
  23         bool floating_point_is_present(void)
  24         {
  25                 unsigned long HWCAPs = getauxval(AT_HWCAP);
  26                 if (HWCAPs & PPC_FEATURE_HAS_FPU)
  27                         return true;
  28
  29                 return false;
  30         }
  31
  32 Where software relies on a feature described by a HWCAP, it should check the
  33 relevant HWCAP flag to verify that the feature is present before attempting to
  34 make use of the feature.
  35
  36 HWCAP is the preferred method to test for the presence of a feature rather
  37 than probing through other means, which may not be reliable or may cause
  38 unpredictable behaviour.
  39
  40 Software that targets a particular platform does not necessarily have to
  41 test for required or implied features. For example if the program requires
  42 FPU, VMX, VSX, it is not necessary to test those HWCAPs, and it may be
  43 impossible to do so if the compiler generates code requiring those features.
  44
  45 2. Facilities
  46 -------------
  47
  48 The Power ISA uses the term "facility" to describe a class of instructions,
  49 registers, interrupts, etc. The presence or absence of a facility indicates
  50 whether this class is available to be used, but the specifics depend on the
  51 ISA version. For example, if the VSX facility is available, the VSX
  52 instructions that can be used differ between the v3.0B and v3.1B ISA
  53 versions.
  54
  55 3. Categories
  56 -------------
  57
  58 The Power ISA before v3.0 uses the term "category" to describe certain
  59 classes of instructions and operating modes which may be optional or
  60 mutually exclusive, the exact meaning of the HWCAP flag may depend on
  61 context, e.g., the presence of the BOOKE feature implies that the server
  62 category is not implemented.
  63
  64 4. HWCAP allocation
  65 -------------------
  66
  67 HWCAPs are allocated as described in Power Architecture 64-Bit ELF V2 ABI
  68 Specification (which will be reflected in the kernel's uapi headers).
  69
  70 5. The HWCAPs exposed in AT_HWCAP
  71 ---------------------------------
  72
  73 PPC_FEATURE_32
  74     32-bit CPU
  75
  76 PPC_FEATURE_64
  77     64-bit CPU (userspace may be running in 32-bit mode).
  78
  79 PPC_FEATURE_601_INSTR
  80     The processor is PowerPC 601.
  81     Unused in the kernel since f0ed73f3fa2c ("powerpc: Remove PowerPC 601")
  82
  83 PPC_FEATURE_HAS_ALTIVEC
  84     Vector (aka Altivec, VMX) facility is available.
  85
  86 PPC_FEATURE_HAS_FPU
  87     Floating point facility is available.
  88
  89 PPC_FEATURE_HAS_MMU
  90     Memory management unit is present and enabled.
  91
  92 PPC_FEATURE_HAS_4xxMAC
  93     The processor is 40x or 44x family.
  94     Unused in the kernel since 732b32daef80 ("powerpc: Remove core support for 40x")
  95
  96 PPC_FEATURE_UNIFIED_CACHE
  97     The processor has a unified L1 cache for instructions and data, as
  98     found in NXP e200.
  99     Unused in the kernel since 39c8bf2b3cc1 ("powerpc: Retire e200 core (mpc555x processor)")
 100
 101 PPC_FEATURE_HAS_SPE
 102     Signal Processing Engine facility is available.
 103
 104 PPC_FEATURE_HAS_EFP_SINGLE
 105     Embedded Floating Point single precision operations are available.
 106
 107 PPC_FEATURE_HAS_EFP_DOUBLE
 108     Embedded Floating Point double precision operations are available.
 109
 110 PPC_FEATURE_NO_TB
 111     The timebase facility (mftb instruction) is not available.
 112     This is a 601 specific HWCAP, so if it is known that the processor
 113     running is not a 601, via other HWCAPs or other means, it is not
 114     required to test this bit before using the timebase.
 115     Unused in the kernel since f0ed73f3fa2c ("powerpc: Remove PowerPC 601")
 116
 117 PPC_FEATURE_POWER4
 118     The processor is POWER4 or PPC970/FX/MP.
 119     POWER4 support dropped from the kernel since 471d7ff8b51b ("powerpc/64s: Remove POWER4 support")
 120
 121 PPC_FEATURE_POWER5
 122     The processor is POWER5.
 123
 124 PPC_FEATURE_POWER5_PLUS
 125     The processor is POWER5+.
 126
 127 PPC_FEATURE_CELL
 128     The processor is Cell.
 129
 130 PPC_FEATURE_BOOKE
 131     The processor implements the embedded category ("BookE") architecture.
 132
 133 PPC_FEATURE_SMT
 134     The processor implements SMT.
 135
 136 PPC_FEATURE_ICACHE_SNOOP
 137     The processor icache is coherent with the dcache, and instruction storage
 138     can be made consistent with data storage for the purpose of executing
 139     instructions with the sequence (as described in, e.g., POWER9 Processor
 140     User's Manual, 4.6.2.2 Instruction Cache Block Invalidate (icbi))::
 141
 142         sync
 143         icbi (to any address)
 144         isync
 145
 146 PPC_FEATURE_ARCH_2_05
 147     The processor supports the v2.05 userlevel architecture. Processors
 148     supporting later architectures DO NOT set this feature.
 149
 150 PPC_FEATURE_PA6T
 151     The processor is PA6T.
 152
 153 PPC_FEATURE_HAS_DFP
 154     DFP facility is available.
 155
 156 PPC_FEATURE_POWER6_EXT
 157     The processor is POWER6.
 158
 159 PPC_FEATURE_ARCH_2_06
 160     The processor supports the v2.06 userlevel architecture. Processors
 161     supporting later architectures also set this feature.
 162
 163 PPC_FEATURE_HAS_VSX
 164     VSX facility is available.
 165
 166 PPC_FEATURE_PSERIES_PERFMON_COMPAT
 167     The processor supports architected PMU events in the range 0xE0-0xFF.
 168
 169 PPC_FEATURE_TRUE_LE
 170     The processor supports true little-endian mode.
 171
 172 PPC_FEATURE_PPC_LE
 173     The processor supports "PowerPC Little-Endian", that uses address
 174     munging to make storage access appear to be little-endian, but the
 175     data is stored in a different format that is unsuitable to be
 176     accessed by other agents not running in this mode.
 177
 178 6. The HWCAPs exposed in AT_HWCAP2
 179 ----------------------------------
 180
 181 PPC_FEATURE2_ARCH_2_07
 182     The processor supports the v2.07 userlevel architecture. Processors
 183     supporting later architectures also set this feature.
 184
 185 PPC_FEATURE2_HTM
 186     Transactional Memory feature is available.
 187
 188 PPC_FEATURE2_DSCR
 189     DSCR facility is available.
 190
 191 PPC_FEATURE2_EBB
 192     EBB facility is available.
 193
 194 PPC_FEATURE2_ISEL
 195     isel instruction is available. This is superseded by ARCH_2_07 and
 196     later.
 197
 198 PPC_FEATURE2_TAR
 199     TAR facility is available.
 200
 201 PPC_FEATURE2_VEC_CRYPTO
 202     v2.07 crypto instructions are available.
 203
 204 PPC_FEATURE2_HTM_NOSC
 205     System calls fail if called in a transactional state, see
 206     Documentation/arch/powerpc/syscall64-abi.rst
 207
 208 PPC_FEATURE2_ARCH_3_00
 209     The processor supports the v3.0B / v3.0C userlevel architecture. Processors
 210     supporting later architectures also set this feature.
 211
 212 PPC_FEATURE2_HAS_IEEE128
 213     IEEE 128-bit binary floating point is supported with VSX
 214     quad-precision instructions and data types.
 215
 216 PPC_FEATURE2_DARN
 217     darn instruction is available.
 218
 219 PPC_FEATURE2_SCV
 220     The scv 0 instruction may be used for system calls, see
 221     Documentation/arch/powerpc/syscall64-abi.rst.
 222
 223 PPC_FEATURE2_HTM_NO_SUSPEND
 224     A limited Transactional Memory facility that does not support suspend is
 225     available, see Documentation/arch/powerpc/transactional_memory.rst.
 226
 227 PPC_FEATURE2_ARCH_3_1
 228     The processor supports the v3.1 userlevel architecture. Processors
 229     supporting later architectures also set this feature.
 230
 231 PPC_FEATURE2_MMA
 232     MMA facility is available.