docs/design/cpu-specific-build-macros.rst

   1 Arm CPU Specific Build Macros
   2 =============================
   3
   4 This document describes the various build options present in the CPU specific
   5 operations framework to enable errata workarounds and to enable optimizations
   6 for a specific CPU on a platform.
   7
   8 Security Vulnerability Workarounds
   9 ----------------------------------
  10
  11 TF-A exports a series of build flags which control which security
  12 vulnerability workarounds should be applied at runtime.
  13
  14 -  ``WORKAROUND_CVE_2017_5715``: Enables the security workaround for
  15    `CVE-2017-5715`_. This flag can be set to 0 by the platform if none
  16    of the PEs in the system need the workaround. Setting this flag to 0 provides
  17    no performance benefit for non-affected platforms, it just helps to comply
  18    with the recommendation in the spec regarding workaround discovery.
  19    Defaults to 1.
  20
  21 -  ``WORKAROUND_CVE_2018_3639``: Enables the security workaround for
  22    `CVE-2018-3639`_. Defaults to 1. The TF-A project recommends to keep
  23    the default value of 1 even on platforms that are unaffected by
  24    CVE-2018-3639, in order to comply with the recommendation in the spec
  25    regarding workaround discovery.
  26
  27 -  ``DYNAMIC_WORKAROUND_CVE_2018_3639``: Enables dynamic mitigation for
  28    `CVE-2018-3639`_. This build option should be set to 1 if the target
  29    platform contains at least 1 CPU that requires dynamic mitigation.
  30    Defaults to 0.
  31
  32 .. _arm_cpu_macros_errata_workarounds:
  33
  34 CPU Errata Workarounds
  35 ----------------------
  36
  37 TF-A exports a series of build flags which control the errata workarounds that
  38 are applied to each CPU by the reset handler. The errata details can be found
  39 in the CPU specific errata documents published by Arm:
  40
  41 -  `Cortex-A53 MPCore Software Developers Errata Notice`_
  42 -  `Cortex-A57 MPCore Software Developers Errata Notice`_
  43 -  `Cortex-A72 MPCore Software Developers Errata Notice`_
  44
  45 The errata workarounds are implemented for a particular revision or a set of
  46 processor revisions. This is checked by the reset handler at runtime. Each
  47 errata workaround is identified by its ``ID`` as specified in the processor's
  48 errata notice document. The format of the define used to enable/disable the
  49 errata workaround is ``ERRATA_<Processor name>_<ID>``, where the ``Processor name``
  50 is for example ``A57`` for the ``Cortex_A57`` CPU.
  51
  52 Refer to :ref:`firmware_design_cpu_errata_reporting` for information on how to
  53 write errata workaround functions.
  54
  55 All workarounds are disabled by default. The platform is responsible for
  56 enabling these workarounds according to its requirement by defining the
  57 errata workaround build flags in the platform specific makefile. In case
  58 these workarounds are enabled for the wrong CPU revision then the errata
  59 workaround is not applied. In the DEBUG build, this is indicated by
  60 printing a warning to the crash console.
  61
  62 In the current implementation, a platform which has more than 1 variant
  63 with different revisions of a processor has no runtime mechanism available
  64 for it to specify which errata workarounds should be enabled or not.
  65
  66 The value of the build flags is 0 by default, that is, disabled. A value of 1
  67 will enable it.
  68
  69 For Cortex-A9, the following errata build flags are defined :
  70
  71 -  ``ERRATA_A9_794073``: This applies errata 794073 workaround to Cortex-A9
  72    CPU. This needs to be enabled for all revisions of the CPU.
  73
  74 For Cortex-A15, the following errata build flags are defined :
  75
  76 -  ``ERRATA_A15_816470``: This applies errata 816470 workaround to Cortex-A15
  77    CPU. This needs to be enabled only for revision >= r3p0 of the CPU.
  78
  79 -  ``ERRATA_A15_827671``: This applies errata 827671 workaround to Cortex-A15
  80    CPU. This needs to be enabled only for revision >= r3p0 of the CPU.
  81
  82 For Cortex-A17, the following errata build flags are defined :
  83
  84 -  ``ERRATA_A17_852421``: This applies errata 852421 workaround to Cortex-A17
  85    CPU. This needs to be enabled only for revision <= r1p2 of the CPU.
  86
  87 -  ``ERRATA_A17_852423``: This applies errata 852423 workaround to Cortex-A17
  88    CPU. This needs to be enabled only for revision <= r1p2 of the CPU.
  89
  90 For Cortex-A35, the following errata build flags are defined :
  91
  92 -  ``ERRATA_A35_855472``: This applies errata 855472 workaround to Cortex-A35
  93    CPUs. This needs to be enabled only for revision r0p0 of Cortex-A35.
  94
  95 For Cortex-A53, the following errata build flags are defined :
  96
  97 -  ``ERRATA_A53_819472``: This applies errata 819472 workaround to all
  98    CPUs. This needs to be enabled only for revision <= r0p1 of Cortex-A53.
  99
 100 -  ``ERRATA_A53_824069``: This applies errata 824069 workaround to all
 101    CPUs. This needs to be enabled only for revision <= r0p2 of Cortex-A53.
 102
 103 -  ``ERRATA_A53_826319``: This applies errata 826319 workaround to Cortex-A53
 104    CPU. This needs to be enabled only for revision <= r0p2 of the CPU.
 105
 106 -  ``ERRATA_A53_827319``: This applies errata 827319 workaround to all
 107    CPUs. This needs to be enabled only for revision <= r0p2 of Cortex-A53.
 108
 109 -  ``ERRATA_A53_835769``: This applies erratum 835769 workaround at compile and
 110    link time to Cortex-A53 CPU. This needs to be enabled for some variants of
 111    revision <= r0p4. This workaround can lead the linker to create ``*.stub``
 112    sections.
 113
 114 -  ``ERRATA_A53_836870``: This applies errata 836870 workaround to Cortex-A53
 115    CPU. This needs to be enabled only for revision <= r0p3 of the CPU. From
 116    r0p4 and onwards, this errata is enabled by default in hardware.
 117
 118 -  ``ERRATA_A53_843419``: This applies erratum 843419 workaround at link time
 119    to Cortex-A53 CPU.  This needs to be enabled for some variants of revision
 120    <= r0p4. This workaround can lead the linker to emit ``*.stub`` sections
 121    which are 4kB aligned.
 122
 123 -  ``ERRATA_A53_855873``: This applies errata 855873 workaround to Cortex-A53
 124    CPUs. Though the erratum is present in every revision of the CPU,
 125    this workaround is only applied to CPUs from r0p3 onwards, which feature
 126    a chicken bit in CPUACTLR_EL1 to enable a hardware workaround.
 127    Earlier revisions of the CPU have other errata which require the same
 128    workaround in software, so they should be covered anyway.
 129
 130 For Cortex-A55, the following errata build flags are defined :
 131
 132 -  ``ERRATA_A55_768277``: This applies errata 768277 workaround to Cortex-A55
 133    CPU. This needs to be enabled only for revision r0p0 of the CPU.
 134
 135 -  ``ERRATA_A55_778703``: This applies errata 778703 workaround to Cortex-A55
 136    CPU. This needs to be enabled only for revision r0p0 of the CPU.
 137
 138 -  ``ERRATA_A55_798797``: This applies errata 798797 workaround to Cortex-A55
 139    CPU. This needs to be enabled only for revision r0p0 of the CPU.
 140
 141 -  ``ERRATA_A55_846532``: This applies errata 846532 workaround to Cortex-A55
 142    CPU. This needs to be enabled only for revision <= r0p1 of the CPU.
 143
 144 -  ``ERRATA_A55_903758``: This applies errata 903758 workaround to Cortex-A55
 145    CPU. This needs to be enabled only for revision <= r0p1 of the CPU.
 146
 147 -  ``ERRATA_A55_1221012``: This applies errata 1221012 workaround to Cortex-A55
 148    CPU. This needs to be enabled only for revision <= r1p0 of the CPU.
 149
 150 For Cortex-A57, the following errata build flags are defined :
 151
 152 -  ``ERRATA_A57_806969``: This applies errata 806969 workaround to Cortex-A57
 153    CPU. This needs to be enabled only for revision r0p0 of the CPU.
 154
 155 -  ``ERRATA_A57_813419``: This applies errata 813419 workaround to Cortex-A57
 156    CPU. This needs to be enabled only for revision r0p0 of the CPU.
 157
 158 -  ``ERRATA_A57_813420``: This applies errata 813420 workaround to Cortex-A57
 159    CPU. This needs to be enabled only for revision r0p0 of the CPU.
 160
 161 -  ``ERRATA_A57_814670``: This applies errata 814670 workaround to Cortex-A57
 162    CPU. This needs to be enabled only for revision r0p0 of the CPU.
 163
 164 -  ``ERRATA_A57_817169``: This applies errata 817169 workaround to Cortex-A57
 165    CPU. This needs to be enabled only for revision <= r0p1 of the CPU.
 166
 167 -  ``ERRATA_A57_826974``: This applies errata 826974 workaround to Cortex-A57
 168    CPU. This needs to be enabled only for revision <= r1p1 of the CPU.
 169
 170 -  ``ERRATA_A57_826977``: This applies errata 826977 workaround to Cortex-A57
 171    CPU. This needs to be enabled only for revision <= r1p1 of the CPU.
 172
 173 -  ``ERRATA_A57_828024``: This applies errata 828024 workaround to Cortex-A57
 174    CPU. This needs to be enabled only for revision <= r1p1 of the CPU.
 175
 176 -  ``ERRATA_A57_829520``: This applies errata 829520 workaround to Cortex-A57
 177    CPU. This needs to be enabled only for revision <= r1p2 of the CPU.
 178
 179 -  ``ERRATA_A57_833471``: This applies errata 833471 workaround to Cortex-A57
 180    CPU. This needs to be enabled only for revision <= r1p2 of the CPU.
 181
 182 -  ``ERRATA_A57_859972``: This applies errata 859972 workaround to Cortex-A57
 183    CPU. This needs to be enabled only for revision <= r1p3 of the CPU.
 184
 185
 186 For Cortex-A72, the following errata build flags are defined :
 187
 188 -  ``ERRATA_A72_859971``: This applies errata 859971 workaround to Cortex-A72
 189    CPU. This needs to be enabled only for revision <= r0p3 of the CPU.
 190
 191 For Cortex-A73, the following errata build flags are defined :
 192
 193 -  ``ERRATA_A73_852427``: This applies errata 852427 workaround to Cortex-A73
 194    CPU. This needs to be enabled only for revision r0p0 of the CPU.
 195
 196 -  ``ERRATA_A73_855423``: This applies errata 855423 workaround to Cortex-A73
 197    CPU. This needs to be enabled only for revision <= r0p1 of the CPU.
 198
 199 For Cortex-A75, the following errata build flags are defined :
 200
 201 -  ``ERRATA_A75_764081``: This applies errata 764081 workaround to Cortex-A75
 202    CPU. This needs to be enabled only for revision r0p0 of the CPU.
 203
 204 -  ``ERRATA_A75_790748``: This applies errata 790748 workaround to Cortex-A75
 205     CPU. This needs to be enabled only for revision r0p0 of the CPU.
 206
 207 For Cortex-A76, the following errata build flags are defined :
 208
 209 -  ``ERRATA_A76_1073348``: This applies errata 1073348 workaround to Cortex-A76
 210    CPU. This needs to be enabled only for revision <= r1p0 of the CPU.
 211
 212 -  ``ERRATA_A76_1130799``: This applies errata 1130799 workaround to Cortex-A76
 213    CPU. This needs to be enabled only for revision <= r2p0 of the CPU.
 214
 215 -  ``ERRATA_A76_1220197``: This applies errata 1220197 workaround to Cortex-A76
 216    CPU. This needs to be enabled only for revision <= r2p0 of the CPU.
 217
 218 -  ``ERRATA_A76_1257314``: This applies errata 1257314 workaround to Cortex-A76
 219    CPU. This needs to be enabled only for revision <= r3p0 of the CPU.
 220
 221 -  ``ERRATA_A76_1262606``: This applies errata 1262606 workaround to Cortex-A76
 222    CPU. This needs to be enabled only for revision <= r3p0 of the CPU.
 223
 224 -  ``ERRATA_A76_1262888``: This applies errata 1262888 workaround to Cortex-A76
 225    CPU. This needs to be enabled only for revision <= r3p0 of the CPU.
 226
 227 -  ``ERRATA_A76_1275112``: This applies errata 1275112 workaround to Cortex-A76
 228    CPU. This needs to be enabled only for revision <= r3p0 of the CPU.
 229
 230 For Neoverse N1, the following errata build flags are defined :
 231
 232 -  ``ERRATA_N1_1073348``: This applies errata 1073348 workaround to Neoverse-N1
 233    CPU. This needs to be enabled only for revision r0p0 and r1p0 of the CPU.
 234
 235 -  ``ERRATA_N1_1130799``: This applies errata 1130799 workaround to Neoverse-N1
 236    CPU. This needs to be enabled only for revision <= r2p0 of the CPU.
 237
 238 -  ``ERRATA_N1_1165347``: This applies errata 1165347 workaround to Neoverse-N1
 239    CPU. This needs to be enabled only for revision <= r2p0 of the CPU.
 240
 241 -  ``ERRATA_N1_1207823``: This applies errata 1207823 workaround to Neoverse-N1
 242    CPU. This needs to be enabled only for revision <= r2p0 of the CPU.
 243
 244 -  ``ERRATA_N1_1220197``: This applies errata 1220197 workaround to Neoverse-N1
 245    CPU. This needs to be enabled only for revision <= r2p0 of the CPU.
 246
 247 -  ``ERRATA_N1_1257314``: This applies errata 1257314 workaround to Neoverse-N1
 248    CPU. This needs to be enabled only for revision <= r3p0 of the CPU.
 249
 250 -  ``ERRATA_N1_1262606``: This applies errata 1262606 workaround to Neoverse-N1
 251    CPU. This needs to be enabled only for revision <= r3p0 of the CPU.
 252
 253 -  ``ERRATA_N1_1262888``: This applies errata 1262888 workaround to Neoverse-N1
 254    CPU. This needs to be enabled only for revision <= r3p0 of the CPU.
 255
 256 -  ``ERRATA_N1_1275112``: This applies errata 1275112 workaround to Neoverse-N1
 257    CPU. This needs to be enabled only for revision <= r3p0 of the CPU.
 258
 259 -  ``ERRATA_N1_1315703``: This applies errata 1315703 workaround to Neoverse-N1
 260    CPU. This needs to be enabled only for revision <= r3p0 of the CPU.
 261
 262 -  ``ERRATA_N1_1542419``: This applies errata 1542419 workaround to Neoverse-N1
 263    CPU. This needs to be enabled only for revisions r3p0 - r4p0 of the CPU.
 264
 265 DSU Errata Workarounds
 266 ----------------------
 267
 268 Similar to CPU errata, TF-A also implements workarounds for DSU (DynamIQ
 269 Shared Unit) errata. The DSU errata details can be found in the respective Arm
 270 documentation:
 271
 272 - `Arm DSU Software Developers Errata Notice`_.
 273
 274 Each erratum is identified by an ``ID``, as defined in the DSU errata notice
 275 document. Thus, the build flags which enable/disable the errata workarounds
 276 have the format ``ERRATA_DSU_<ID>``. The implementation and application logic
 277 of DSU errata workarounds are similar to `CPU errata workarounds`_.
 278
 279 For DSU errata, the following build flags are defined:
 280
 281 -  ``ERRATA_DSU_798953``: This applies errata 798953 workaround for the
 282    affected DSU configurations. This errata applies only for those DSUs that
 283    revision is r0p0 (on r0p1 it is fixed). However, please note that this
 284    workaround results in increased DSU power consumption on idle.
 285
 286 -  ``ERRATA_DSU_936184``: This applies errata 936184 workaround for the
 287    affected DSU configurations. This errata applies only for those DSUs that
 288    contain the ACP interface **and** the DSU revision is older than r2p0 (on
 289    r2p0 it is fixed). However, please note that this workaround results in
 290    increased DSU power consumption on idle.
 291
 292 CPU Specific optimizations
 293 --------------------------
 294
 295 This section describes some of the optimizations allowed by the CPU micro
 296 architecture that can be enabled by the platform as desired.
 297
 298 -  ``SKIP_A57_L1_FLUSH_PWR_DWN``: This flag enables an optimization in the
 299    Cortex-A57 cluster power down sequence by not flushing the Level 1 data
 300    cache. The L1 data cache and the L2 unified cache are inclusive. A flush
 301    of the L2 by set/way flushes any dirty lines from the L1 as well. This
 302    is a known safe deviation from the Cortex-A57 TRM defined power down
 303    sequence. Each Cortex-A57 based platform must make its own decision on
 304    whether to use the optimization.
 305
 306 -  ``A53_DISABLE_NON_TEMPORAL_HINT``: This flag disables the cache non-temporal
 307    hint. The LDNP/STNP instructions as implemented on Cortex-A53 do not behave
 308    in a way most programmers expect, and will most probably result in a
 309    significant speed degradation to any code that employs them. The Armv8-A
 310    architecture (see Arm DDI 0487A.h, section D3.4.3) allows cores to ignore
 311    the non-temporal hint and treat LDNP/STNP as LDP/STP instead. Enabling this
 312    flag enforces this behaviour. This needs to be enabled only for revisions
 313    <= r0p3 of the CPU and is enabled by default.
 314
 315 -  ``A57_DISABLE_NON_TEMPORAL_HINT``: This flag has the same behaviour as
 316    ``A53_DISABLE_NON_TEMPORAL_HINT`` but for Cortex-A57. This needs to be
 317    enabled only for revisions <= r1p2 of the CPU and is enabled by default,
 318    as recommended in section "4.7 Non-Temporal Loads/Stores" of the
 319    `Cortex-A57 Software Optimization Guide`_.
 320
 321 --------------
 322
 323 *Copyright (c) 2014-2019, Arm Limited and Contributors. All rights reserved.*
 324
 325 .. _CVE-2017-5715: http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2017-5715
 326 .. _CVE-2018-3639: http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2018-3639
 327 .. _Cortex-A53 MPCore Software Developers Errata Notice: http://infocenter.arm.com/help/topic/com.arm.doc.epm048406/index.html
 328 .. _Cortex-A57 MPCore Software Developers Errata Notice: http://infocenter.arm.com/help/topic/com.arm.doc.epm049219/index.html
 329 .. _Cortex-A72 MPCore Software Developers Errata Notice: http://infocenter.arm.com/help/topic/com.arm.doc.epm012079/index.html
 330 .. _Cortex-A57 Software Optimization Guide: http://infocenter.arm.com/help/topic/com.arm.doc.uan0015b/Cortex_A57_Software_Optimization_Guide_external.pdf
 331 .. _Arm DSU Software Developers Errata Notice: http://infocenter.arm.com/help/topic/com.arm.doc.epm138168/index.html