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