blob: ae0cfd9c2b87382126f4ed8a6e47f7dd99f55f2b [file] [log] [blame]
Dan Handley4def07d2018-03-01 18:44:00 +00001Arm CPU Specific Build Macros
Douglas Raillard6f625742017-06-28 15:23:03 +01002=============================
3
4
5.. section-numbering::
6 :suffix: .
7
8.. contents::
9
10This document describes the various build options present in the CPU specific
11operations framework to enable errata workarounds and to enable optimizations
12for a specific CPU on a platform.
13
Dimitris Papastamosf62ad322017-11-30 14:53:53 +000014Security Vulnerability Workarounds
15----------------------------------
16
Dan Handley4def07d2018-03-01 18:44:00 +000017TF-A exports a series of build flags which control which security
18vulnerability workarounds should be applied at runtime.
Dimitris Papastamosf62ad322017-11-30 14:53:53 +000019
20- ``WORKAROUND_CVE_2017_5715``: Enables the security workaround for
Dimitris Papastamos59dc4ef2018-03-28 12:06:40 +010021 `CVE-2017-5715`_. This flag can be set to 0 by the platform if none
22 of the PEs in the system need the workaround. Setting this flag to 0 provides
23 no performance benefit for non-affected platforms, it just helps to comply
24 with the recommendation in the spec regarding workaround discovery.
25 Defaults to 1.
Dimitris Papastamosf62ad322017-11-30 14:53:53 +000026
Dimitris Papastamosb8a25bb2018-04-05 14:38:26 +010027- ``WORKAROUND_CVE_2018_3639``: Enables the security workaround for
28 `CVE-2018-3639`_. Defaults to 1. The TF-A project recommends to keep
29 the default value of 1 even on platforms that are unaffected by
30 CVE-2018-3639, in order to comply with the recommendation in the spec
31 regarding workaround discovery.
32
Dimitris Papastamosfe007b22018-05-16 11:36:14 +010033- ``DYNAMIC_WORKAROUND_CVE_2018_3639``: Enables dynamic mitigation for
34 `CVE-2018-3639`_. This build option should be set to 1 if the target
35 platform contains at least 1 CPU that requires dynamic mitigation.
36 Defaults to 0.
37
Douglas Raillard6f625742017-06-28 15:23:03 +010038CPU Errata Workarounds
39----------------------
40
Dan Handley4def07d2018-03-01 18:44:00 +000041TF-A exports a series of build flags which control the errata workarounds that
42are applied to each CPU by the reset handler. The errata details can be found
43in the CPU specific errata documents published by Arm:
Douglas Raillard6f625742017-06-28 15:23:03 +010044
45- `Cortex-A53 MPCore Software Developers Errata Notice`_
46- `Cortex-A57 MPCore Software Developers Errata Notice`_
Eleanor Bonnici6de9b332017-08-02 18:33:41 +010047- `Cortex-A72 MPCore Software Developers Errata Notice`_
Douglas Raillard6f625742017-06-28 15:23:03 +010048
49The errata workarounds are implemented for a particular revision or a set of
50processor revisions. This is checked by the reset handler at runtime. Each
51errata workaround is identified by its ``ID`` as specified in the processor's
52errata notice document. The format of the define used to enable/disable the
53errata workaround is ``ERRATA_<Processor name>_<ID>``, where the ``Processor name``
54is for example ``A57`` for the ``Cortex_A57`` CPU.
55
56Refer to the section *CPU errata status reporting* in
Eleanor Bonnici45b52c22017-08-02 16:35:04 +010057`Firmware Design guide`_ for information on how to write errata workaround
58functions.
Douglas Raillard6f625742017-06-28 15:23:03 +010059
60All workarounds are disabled by default. The platform is responsible for
61enabling these workarounds according to its requirement by defining the
62errata workaround build flags in the platform specific makefile. In case
63these workarounds are enabled for the wrong CPU revision then the errata
64workaround is not applied. In the DEBUG build, this is indicated by
65printing a warning to the crash console.
66
67In the current implementation, a platform which has more than 1 variant
68with different revisions of a processor has no runtime mechanism available
69for it to specify which errata workarounds should be enabled or not.
70
John Tsichritzis8a677182018-07-23 09:11:59 +010071The value of the build flags is 0 by default, that is, disabled. A value of 1
72will enable it.
Douglas Raillard6f625742017-06-28 15:23:03 +010073
Ambroise Vincent75a1ada2019-03-04 16:56:26 +000074For 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
Ambroise Vincent5f2c6902019-03-05 09:54:21 +000079- ``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
Ambroise Vincent0b64c192019-02-28 16:23:53 +000082For 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
John Tsichritzis8a677182018-07-23 09:11:59 +010087For Cortex-A53, the following errata build flags are defined :
Douglas Raillard6f625742017-06-28 15:23:03 +010088
Ambroise Vincentbd393702019-02-21 14:16:24 +000089- ``ERRATA_A53_819472``: This applies errata 819472 workaround to all
90 CPUs. This needs to be enabled only for revision <= r0p1 of Cortex-A53.
91
92- ``ERRATA_A53_824069``: This applies errata 824069 workaround to all
93 CPUs. This needs to be enabled only for revision <= r0p2 of Cortex-A53.
94
Douglas Raillard6f625742017-06-28 15:23:03 +010095- ``ERRATA_A53_826319``: This applies errata 826319 workaround to Cortex-A53
96 CPU. This needs to be enabled only for revision <= r0p2 of the CPU.
97
Ambroise Vincentbd393702019-02-21 14:16:24 +000098- ``ERRATA_A53_827319``: This applies errata 827319 workaround to all
99 CPUs. This needs to be enabled only for revision <= r0p2 of Cortex-A53.
100
Douglas Raillardca6b1cb2017-07-17 14:14:52 +0100101- ``ERRATA_A53_835769``: This applies erratum 835769 workaround at compile and
102 link time to Cortex-A53 CPU. This needs to be enabled for some variants of
103 revision <= r0p4. This workaround can lead the linker to create ``*.stub``
104 sections.
105
Douglas Raillard6f625742017-06-28 15:23:03 +0100106- ``ERRATA_A53_836870``: This applies errata 836870 workaround to Cortex-A53
107 CPU. This needs to be enabled only for revision <= r0p3 of the CPU. From
108 r0p4 and onwards, this errata is enabled by default in hardware.
109
Douglas Raillardca6b1cb2017-07-17 14:14:52 +0100110- ``ERRATA_A53_843419``: This applies erratum 843419 workaround at link time
111 to Cortex-A53 CPU. This needs to be enabled for some variants of revision
112 <= r0p4. This workaround can lead the linker to emit ``*.stub`` sections
113 which are 4kB aligned.
114
Douglas Raillard6f625742017-06-28 15:23:03 +0100115- ``ERRATA_A53_855873``: This applies errata 855873 workaround to Cortex-A53
116 CPUs. Though the erratum is present in every revision of the CPU,
117 this workaround is only applied to CPUs from r0p3 onwards, which feature
Sandrine Bailleuxf3cacad2019-02-08 15:26:36 +0100118 a chicken bit in CPUACTLR_EL1 to enable a hardware workaround.
Douglas Raillard6f625742017-06-28 15:23:03 +0100119 Earlier revisions of the CPU have other errata which require the same
120 workaround in software, so they should be covered anyway.
121
Ambroise Vincent1afeee92019-02-21 16:20:43 +0000122For Cortex-A55, the following errata build flags are defined :
123
124- ``ERRATA_A55_768277``: This applies errata 768277 workaround to Cortex-A55
125 CPU. This needs to be enabled only for revision r0p0 of the CPU.
126
Ambroise Vincenta6cc6612019-02-21 16:25:37 +0000127- ``ERRATA_A55_778703``: This applies errata 778703 workaround to Cortex-A55
128 CPU. This needs to be enabled only for revision r0p0 of the CPU.
129
Ambroise Vincent6ab87d22019-02-21 16:27:34 +0000130- ``ERRATA_A55_798797``: This applies errata 798797 workaround to Cortex-A55
131 CPU. This needs to be enabled only for revision r0p0 of the CPU.
132
Ambroise Vincent6e789732019-02-21 16:29:16 +0000133- ``ERRATA_A55_846532``: This applies errata 846532 workaround to Cortex-A55
134 CPU. This needs to be enabled only for revision <= r0p1 of the CPU.
135
Ambroise Vincent47949f32019-02-21 16:29:50 +0000136- ``ERRATA_A55_903758``: This applies errata 903758 workaround to Cortex-A55
137 CPU. This needs to be enabled only for revision <= r0p1 of the CPU.
138
John Tsichritzis8a677182018-07-23 09:11:59 +0100139For Cortex-A57, the following errata build flags are defined :
Douglas Raillard6f625742017-06-28 15:23:03 +0100140
141- ``ERRATA_A57_806969``: This applies errata 806969 workaround to Cortex-A57
142 CPU. This needs to be enabled only for revision r0p0 of the CPU.
143
144- ``ERRATA_A57_813419``: This applies errata 813419 workaround to Cortex-A57
145 CPU. This needs to be enabled only for revision r0p0 of the CPU.
146
147- ``ERRATA_A57_813420``: This applies errata 813420 workaround to Cortex-A57
148 CPU. This needs to be enabled only for revision r0p0 of the CPU.
149
Ambroise Vincent0f6fbbd2019-02-21 16:35:07 +0000150- ``ERRATA_A57_814670``: This applies errata 814670 workaround to Cortex-A57
151 CPU. This needs to be enabled only for revision r0p0 of the CPU.
152
Ambroise Vincent5bd2c242019-02-21 16:35:49 +0000153- ``ERRATA_A57_817169``: This applies errata 817169 workaround to Cortex-A57
154 CPU. This needs to be enabled only for revision <= r0p1 of the CPU.
155
Douglas Raillard6f625742017-06-28 15:23:03 +0100156- ``ERRATA_A57_826974``: This applies errata 826974 workaround to Cortex-A57
157 CPU. This needs to be enabled only for revision <= r1p1 of the CPU.
158
159- ``ERRATA_A57_826977``: This applies errata 826977 workaround to Cortex-A57
160 CPU. This needs to be enabled only for revision <= r1p1 of the CPU.
161
162- ``ERRATA_A57_828024``: This applies errata 828024 workaround to Cortex-A57
163 CPU. This needs to be enabled only for revision <= r1p1 of the CPU.
164
165- ``ERRATA_A57_829520``: This applies errata 829520 workaround to Cortex-A57
166 CPU. This needs to be enabled only for revision <= r1p2 of the CPU.
167
168- ``ERRATA_A57_833471``: This applies errata 833471 workaround to Cortex-A57
169 CPU. This needs to be enabled only for revision <= r1p2 of the CPU.
170
Eleanor Bonnici45b52c22017-08-02 16:35:04 +0100171- ``ERRATA_A57_859972``: This applies errata 859972 workaround to Cortex-A57
172 CPU. This needs to be enabled only for revision <= r1p3 of the CPU.
173
Eleanor Bonnici6de9b332017-08-02 18:33:41 +0100174
John Tsichritzis8a677182018-07-23 09:11:59 +0100175For Cortex-A72, the following errata build flags are defined :
Eleanor Bonnici6de9b332017-08-02 18:33:41 +0100176
177- ``ERRATA_A72_859971``: This applies errata 859971 workaround to Cortex-A72
178 CPU. This needs to be enabled only for revision <= r0p3 of the CPU.
179
Louis Mayencourte6cab152019-02-21 16:38:16 +0000180For Cortex-A73, the following errata build flags are defined :
181
Louis Mayencourt25278ea2019-02-27 14:24:16 +0000182- ``ERRATA_A73_852427``: This applies errata 852427 workaround to Cortex-A73
183 CPU. This needs to be enabled only for revision r0p0 of the CPU.
184
Louis Mayencourte6cab152019-02-21 16:38:16 +0000185- ``ERRATA_A73_855423``: This applies errata 855423 workaround to Cortex-A73
186 CPU. This needs to be enabled only for revision <= r0p1 of the CPU.
187
Louis Mayencourt5f5d1ed2019-02-20 12:11:41 +0000188For Cortex-A75, the following errata build flags are defined :
189
190- ``ERRATA_A75_764081``: This applies errata 764081 workaround to Cortex-A75
191 CPU. This needs to be enabled only for revision r0p0 of the CPU.
192
Louis Mayencourt98551592019-02-25 14:57:57 +0000193- ``ERRATA_A75_790748``: This applies errata 790748 workaround to Cortex-A75
194 CPU. This needs to be enabled only for revision r0p0 of the CPU.
195
Louis Mayencourt508d7112019-02-21 17:35:07 +0000196For Cortex-A76, the following errata build flags are defined :
197
Louis Mayencourt5c6aa012019-02-25 15:17:44 +0000198- ``ERRATA_A76_1073348``: This applies errata 1073348 workaround to Cortex-A76
199 CPU. This needs to be enabled only for revision <= r1p0 of the CPU.
200
Louis Mayencourt508d7112019-02-21 17:35:07 +0000201- ``ERRATA_A76_1130799``: This applies errata 1130799 workaround to Cortex-A76
202 CPU. This needs to be enabled only for revision <= r2p0 of the CPU.
203
Louis Mayencourt5cc8c7b2019-02-25 11:37:38 +0000204- ``ERRATA_A76_1220197``: This applies errata 1220197 workaround to Cortex-A76
205 CPU. This needs to be enabled only for revision <= r2p0 of the CPU.
206
John Tsichritzis8a677182018-07-23 09:11:59 +0100207DSU Errata Workarounds
208----------------------
209
210Similar to CPU errata, TF-A also implements workarounds for DSU (DynamIQ
211Shared Unit) errata. The DSU errata details can be found in the respective Arm
212documentation:
213
214- `Arm DSU Software Developers Errata Notice`_.
215
216Each erratum is identified by an ``ID``, as defined in the DSU errata notice
217document. Thus, the build flags which enable/disable the errata workarounds
218have the format ``ERRATA_DSU_<ID>``. The implementation and application logic
219of DSU errata workarounds are similar to `CPU errata workarounds`_.
220
221For DSU errata, the following build flags are defined:
222
223- ``ERRATA_DSU_936184``: This applies errata 936184 workaround for the
224 affected DSU configurations. This errata applies only for those DSUs that
225 contain the ACP interface **and** the DSU revision is older than r2p0 (on
226 r2p0 it is fixed). However, please note that this workaround results in
227 increased DSU power consumption on idle.
228
Douglas Raillard6f625742017-06-28 15:23:03 +0100229CPU Specific optimizations
230--------------------------
231
232This section describes some of the optimizations allowed by the CPU micro
233architecture that can be enabled by the platform as desired.
234
235- ``SKIP_A57_L1_FLUSH_PWR_DWN``: This flag enables an optimization in the
236 Cortex-A57 cluster power down sequence by not flushing the Level 1 data
237 cache. The L1 data cache and the L2 unified cache are inclusive. A flush
238 of the L2 by set/way flushes any dirty lines from the L1 as well. This
239 is a known safe deviation from the Cortex-A57 TRM defined power down
240 sequence. Each Cortex-A57 based platform must make its own decision on
241 whether to use the optimization.
242
243- ``A53_DISABLE_NON_TEMPORAL_HINT``: This flag disables the cache non-temporal
244 hint. The LDNP/STNP instructions as implemented on Cortex-A53 do not behave
245 in a way most programmers expect, and will most probably result in a
Dan Handley4def07d2018-03-01 18:44:00 +0000246 significant speed degradation to any code that employs them. The Armv8-A
247 architecture (see Arm DDI 0487A.h, section D3.4.3) allows cores to ignore
Douglas Raillard6f625742017-06-28 15:23:03 +0100248 the non-temporal hint and treat LDNP/STNP as LDP/STP instead. Enabling this
249 flag enforces this behaviour. This needs to be enabled only for revisions
250 <= r0p3 of the CPU and is enabled by default.
251
252- ``A57_DISABLE_NON_TEMPORAL_HINT``: This flag has the same behaviour as
253 ``A53_DISABLE_NON_TEMPORAL_HINT`` but for Cortex-A57. This needs to be
254 enabled only for revisions <= r1p2 of the CPU and is enabled by default,
255 as recommended in section "4.7 Non-Temporal Loads/Stores" of the
256 `Cortex-A57 Software Optimization Guide`_.
257
258--------------
259
Dan Handley4def07d2018-03-01 18:44:00 +0000260*Copyright (c) 2014-2018, Arm Limited and Contributors. All rights reserved.*
Douglas Raillard6f625742017-06-28 15:23:03 +0100261
John Tsichritzisaf45d642018-09-04 10:56:53 +0100262.. _CVE-2017-5715: http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2017-5715
263.. _CVE-2018-3639: http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2018-3639
Paul Beesleydd4e9a72019-02-08 16:43:05 +0000264.. _Cortex-A53 MPCore Software Developers Errata Notice: http://infocenter.arm.com/help/topic/com.arm.doc.epm048406/index.html
265.. _Cortex-A57 MPCore Software Developers Errata Notice: http://infocenter.arm.com/help/topic/com.arm.doc.epm049219/index.html
Eleanor Bonnici6de9b332017-08-02 18:33:41 +0100266.. _Cortex-A72 MPCore Software Developers Errata Notice: http://infocenter.arm.com/help/topic/com.arm.doc.epm012079/index.html
Douglas Raillard6f625742017-06-28 15:23:03 +0100267.. _Firmware Design guide: firmware-design.rst
268.. _Cortex-A57 Software Optimization Guide: http://infocenter.arm.com/help/topic/com.arm.doc.uan0015b/Cortex_A57_Software_Optimization_Guide_external.pdf
Sandrine Bailleuxf3cacad2019-02-08 15:26:36 +0100269.. _Arm DSU Software Developers Errata Notice: http://infocenter.arm.com/help/topic/com.arm.doc.epm138168/index.html