blob: 477eeaa549005bdc696abaf20cdba51dd17973d8 [file] [log] [blame]
Dan Handley610e7e12018-03-01 18:44:00 +00001Trusted Firmware-A design
2=========================
Douglas Raillardd7c21b72017-06-28 15:23:03 +01003
4
5.. section-numbering::
6 :suffix: .
7
8.. contents::
9
Dan Handley610e7e12018-03-01 18:44:00 +000010Trusted Firmware-A (TF-A) implements a subset of the Trusted Board Boot
11Requirements (TBBR) Platform Design Document (PDD) [1]_ for Arm reference
Douglas Raillardd7c21b72017-06-28 15:23:03 +010012platforms. The TBB sequence starts when the platform is powered on and runs up
13to the stage where it hands-off control to firmware running in the normal
14world in DRAM. This is the cold boot path.
15
Dan Handley610e7e12018-03-01 18:44:00 +000016TF-A also implements the Power State Coordination Interface PDD [2]_ as a
17runtime service. PSCI is the interface from normal world software to firmware
18implementing power management use-cases (for example, secondary CPU boot,
19hotplug and idle). Normal world software can access TF-A runtime services via
20the Arm SMC (Secure Monitor Call) instruction. The SMC instruction must be
21used as mandated by the SMC Calling Convention [3]_.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010022
Dan Handley610e7e12018-03-01 18:44:00 +000023TF-A implements a framework for configuring and managing interrupts generated
24in either security state. The details of the interrupt management framework
25and its design can be found in TF-A Interrupt Management Design guide [4]_.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010026
Dan Handley610e7e12018-03-01 18:44:00 +000027TF-A also implements a library for setting up and managing the translation
28tables. The details of this library can be found in `Xlat_tables design`_.
Antonio Nino Diazb5d68092017-05-23 11:49:22 +010029
Dan Handley610e7e12018-03-01 18:44:00 +000030TF-A can be built to support either AArch64 or AArch32 execution state.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010031
32Cold boot
33---------
34
35The cold boot path starts when the platform is physically turned on. If
36``COLD_BOOT_SINGLE_CPU=0``, one of the CPUs released from reset is chosen as the
37primary CPU, and the remaining CPUs are considered secondary CPUs. The primary
38CPU is chosen through platform-specific means. The cold boot path is mainly
39executed by the primary CPU, other than essential CPU initialization executed by
40all CPUs. The secondary CPUs are kept in a safe platform-specific state until
41the primary CPU has performed enough initialization to boot them.
42
43Refer to the `Reset Design`_ for more information on the effect of the
44``COLD_BOOT_SINGLE_CPU`` platform build option.
45
Dan Handley610e7e12018-03-01 18:44:00 +000046The cold boot path in this implementation of TF-A depends on the execution
47state. For AArch64, it is divided into five steps (in order of execution):
Douglas Raillardd7c21b72017-06-28 15:23:03 +010048
49- Boot Loader stage 1 (BL1) *AP Trusted ROM*
50- Boot Loader stage 2 (BL2) *Trusted Boot Firmware*
51- Boot Loader stage 3-1 (BL31) *EL3 Runtime Software*
52- Boot Loader stage 3-2 (BL32) *Secure-EL1 Payload* (optional)
53- Boot Loader stage 3-3 (BL33) *Non-trusted Firmware*
54
55For AArch32, it is divided into four steps (in order of execution):
56
57- Boot Loader stage 1 (BL1) *AP Trusted ROM*
58- Boot Loader stage 2 (BL2) *Trusted Boot Firmware*
59- Boot Loader stage 3-2 (BL32) *EL3 Runtime Software*
60- Boot Loader stage 3-3 (BL33) *Non-trusted Firmware*
61
Dan Handley610e7e12018-03-01 18:44:00 +000062Arm development platforms (Fixed Virtual Platforms (FVPs) and Juno) implement a
Douglas Raillardd7c21b72017-06-28 15:23:03 +010063combination of the following types of memory regions. Each bootloader stage uses
64one or more of these memory regions.
65
66- Regions accessible from both non-secure and secure states. For example,
67 non-trusted SRAM, ROM and DRAM.
68- Regions accessible from only the secure state. For example, trusted SRAM and
69 ROM. The FVPs also implement the trusted DRAM which is statically
70 configured. Additionally, the Base FVPs and Juno development platform
71 configure the TrustZone Controller (TZC) to create a region in the DRAM
72 which is accessible only from the secure state.
73
74The sections below provide the following details:
75
Soby Mathewb1bf0442018-02-16 14:52:52 +000076- dynamic configuration of Boot Loader stages
Douglas Raillardd7c21b72017-06-28 15:23:03 +010077- initialization and execution of the first three stages during cold boot
78- specification of the EL3 Runtime Software (BL31 for AArch64 and BL32 for
79 AArch32) entrypoint requirements for use by alternative Trusted Boot
80 Firmware in place of the provided BL1 and BL2
81
Soby Mathewb1bf0442018-02-16 14:52:52 +000082Dynamic Configuration during cold boot
83~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
84
85Each of the Boot Loader stages may be dynamically configured if required by the
86platform. The Boot Loader stage may optionally specify a firmware
87configuration file and/or hardware configuration file as listed below:
88
89- HW_CONFIG - The hardware configuration file. Can be shared by all Boot Loader
90 stages and also by the Normal World Rich OS.
91- TB_FW_CONFIG - Trusted Boot Firmware configuration file. Shared between BL1
92 and BL2.
93- SOC_FW_CONFIG - SoC Firmware configuration file. Used by BL31.
94- TOS_FW_CONFIG - Trusted OS Firmware configuration file. Used by Trusted OS
95 (BL32).
96- NT_FW_CONFIG - Non Trusted Firmware configuration file. Used by Non-trusted
97 firmware (BL33).
98
99The Arm development platforms use the Flattened Device Tree format for the
100dynamic configuration files.
101
102Each Boot Loader stage can pass up to 4 arguments via registers to the next
103stage. BL2 passes the list of the next images to execute to the *EL3 Runtime
104Software* (BL31 for AArch64 and BL32 for AArch32) via `arg0`. All the other
105arguments are platform defined. The Arm development platforms use the following
106convention:
107
108- BL1 passes the address of a meminfo_t structure to BL2 via ``arg1``. This
109 structure contains the memory layout available to BL2.
110- When dynamic configuration files are present, the firmware configuration for
111 the next Boot Loader stage is populated in the first available argument and
112 the generic hardware configuration is passed the next available argument.
113 For example,
114
115 - If TB_FW_CONFIG is loaded by BL1, then its address is passed in ``arg0``
116 to BL2.
117 - If HW_CONFIG is loaded by BL1, then its address is passed in ``arg2`` to
118 BL2. Note, ``arg1`` is already used for meminfo_t.
119 - If SOC_FW_CONFIG is loaded by BL2, then its address is passed in ``arg1``
120 to BL31. Note, ``arg0`` is used to pass the list of executable images.
121 - Similarly, if HW_CONFIG is loaded by BL1 or BL2, then its address is
122 passed in ``arg2`` to BL31.
123 - For other BL3x images, if the firmware configuration file is loaded by
124 BL2, then its address is passed in ``arg0`` and if HW_CONFIG is loaded
125 then its address is passed in ``arg1``.
126
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100127BL1
128~~~
129
130This stage begins execution from the platform's reset vector at EL3. The reset
131address is platform dependent but it is usually located in a Trusted ROM area.
132The BL1 data section is copied to trusted SRAM at runtime.
133
Dan Handley610e7e12018-03-01 18:44:00 +0000134On the Arm development platforms, BL1 code starts execution from the reset
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100135vector defined by the constant ``BL1_RO_BASE``. The BL1 data section is copied
136to the top of trusted SRAM as defined by the constant ``BL1_RW_BASE``.
137
138The functionality implemented by this stage is as follows.
139
140Determination of boot path
141^^^^^^^^^^^^^^^^^^^^^^^^^^
142
143Whenever a CPU is released from reset, BL1 needs to distinguish between a warm
144boot and a cold boot. This is done using platform-specific mechanisms (see the
145``plat_get_my_entrypoint()`` function in the `Porting Guide`_). In the case of a
146warm boot, a CPU is expected to continue execution from a separate
147entrypoint. In the case of a cold boot, the secondary CPUs are placed in a safe
148platform-specific state (see the ``plat_secondary_cold_boot_setup()`` function in
149the `Porting Guide`_) while the primary CPU executes the remaining cold boot path
150as described in the following sections.
151
152This step only applies when ``PROGRAMMABLE_RESET_ADDRESS=0``. Refer to the
153`Reset Design`_ for more information on the effect of the
154``PROGRAMMABLE_RESET_ADDRESS`` platform build option.
155
156Architectural initialization
157^^^^^^^^^^^^^^^^^^^^^^^^^^^^
158
159BL1 performs minimal architectural initialization as follows.
160
161- Exception vectors
162
163 BL1 sets up simple exception vectors for both synchronous and asynchronous
164 exceptions. The default behavior upon receiving an exception is to populate
165 a status code in the general purpose register ``X0/R0`` and call the
166 ``plat_report_exception()`` function (see the `Porting Guide`_). The status
167 code is one of:
168
169 For AArch64:
170
171 ::
172
173 0x0 : Synchronous exception from Current EL with SP_EL0
174 0x1 : IRQ exception from Current EL with SP_EL0
175 0x2 : FIQ exception from Current EL with SP_EL0
176 0x3 : System Error exception from Current EL with SP_EL0
177 0x4 : Synchronous exception from Current EL with SP_ELx
178 0x5 : IRQ exception from Current EL with SP_ELx
179 0x6 : FIQ exception from Current EL with SP_ELx
180 0x7 : System Error exception from Current EL with SP_ELx
181 0x8 : Synchronous exception from Lower EL using aarch64
182 0x9 : IRQ exception from Lower EL using aarch64
183 0xa : FIQ exception from Lower EL using aarch64
184 0xb : System Error exception from Lower EL using aarch64
185 0xc : Synchronous exception from Lower EL using aarch32
186 0xd : IRQ exception from Lower EL using aarch32
187 0xe : FIQ exception from Lower EL using aarch32
188 0xf : System Error exception from Lower EL using aarch32
189
190 For AArch32:
191
192 ::
193
194 0x10 : User mode
195 0x11 : FIQ mode
196 0x12 : IRQ mode
197 0x13 : SVC mode
198 0x16 : Monitor mode
199 0x17 : Abort mode
200 0x1a : Hypervisor mode
201 0x1b : Undefined mode
202 0x1f : System mode
203
Dan Handley610e7e12018-03-01 18:44:00 +0000204 The ``plat_report_exception()`` implementation on the Arm FVP port programs
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100205 the Versatile Express System LED register in the following format to
206 indicate the occurence of an unexpected exception:
207
208 ::
209
210 SYS_LED[0] - Security state (Secure=0/Non-Secure=1)
211 SYS_LED[2:1] - Exception Level (EL3=0x3, EL2=0x2, EL1=0x1, EL0=0x0)
212 For AArch32 it is always 0x0
213 SYS_LED[7:3] - Exception Class (Sync/Async & origin). This is the value
214 of the status code
215
216 A write to the LED register reflects in the System LEDs (S6LED0..7) in the
217 CLCD window of the FVP.
218
219 BL1 does not expect to receive any exceptions other than the SMC exception.
220 For the latter, BL1 installs a simple stub. The stub expects to receive a
221 limited set of SMC types (determined by their function IDs in the general
222 purpose register ``X0/R0``):
223
224 - ``BL1_SMC_RUN_IMAGE``: This SMC is raised by BL2 to make BL1 pass control
225 to EL3 Runtime Software.
226 - All SMCs listed in section "BL1 SMC Interface" in the `Firmware Update`_
227 Design Guide are supported for AArch64 only. These SMCs are currently
228 not supported when BL1 is built for AArch32.
229
230 Any other SMC leads to an assertion failure.
231
232- CPU initialization
233
234 BL1 calls the ``reset_handler()`` function which in turn calls the CPU
235 specific reset handler function (see the section: "CPU specific operations
236 framework").
237
238- Control register setup (for AArch64)
239
240 - ``SCTLR_EL3``. Instruction cache is enabled by setting the ``SCTLR_EL3.I``
241 bit. Alignment and stack alignment checking is enabled by setting the
242 ``SCTLR_EL3.A`` and ``SCTLR_EL3.SA`` bits. Exception endianness is set to
243 little-endian by clearing the ``SCTLR_EL3.EE`` bit.
244
245 - ``SCR_EL3``. The register width of the next lower exception level is set
246 to AArch64 by setting the ``SCR.RW`` bit. The ``SCR.EA`` bit is set to trap
247 both External Aborts and SError Interrupts in EL3. The ``SCR.SIF`` bit is
248 also set to disable instruction fetches from Non-secure memory when in
249 secure state.
250
251 - ``CPTR_EL3``. Accesses to the ``CPACR_EL1`` register from EL1 or EL2, or the
252 ``CPTR_EL2`` register from EL2 are configured to not trap to EL3 by
253 clearing the ``CPTR_EL3.TCPAC`` bit. Access to the trace functionality is
254 configured not to trap to EL3 by clearing the ``CPTR_EL3.TTA`` bit.
255 Instructions that access the registers associated with Floating Point
256 and Advanced SIMD execution are configured to not trap to EL3 by
257 clearing the ``CPTR_EL3.TFP`` bit.
258
259 - ``DAIF``. The SError interrupt is enabled by clearing the SError interrupt
260 mask bit.
261
262 - ``MDCR_EL3``. The trap controls, ``MDCR_EL3.TDOSA``, ``MDCR_EL3.TDA`` and
263 ``MDCR_EL3.TPM``, are set so that accesses to the registers they control
264 do not trap to EL3. AArch64 Secure self-hosted debug is disabled by
265 setting the ``MDCR_EL3.SDD`` bit. Also ``MDCR_EL3.SPD32`` is set to
266 disable AArch32 Secure self-hosted privileged debug from S-EL1.
267
268- Control register setup (for AArch32)
269
270 - ``SCTLR``. Instruction cache is enabled by setting the ``SCTLR.I`` bit.
271 Alignment checking is enabled by setting the ``SCTLR.A`` bit.
272 Exception endianness is set to little-endian by clearing the
273 ``SCTLR.EE`` bit.
274
275 - ``SCR``. The ``SCR.SIF`` bit is set to disable instruction fetches from
276 Non-secure memory when in secure state.
277
278 - ``CPACR``. Allow execution of Advanced SIMD instructions at PL0 and PL1,
279 by clearing the ``CPACR.ASEDIS`` bit. Access to the trace functionality
280 is configured not to trap to undefined mode by clearing the
281 ``CPACR.TRCDIS`` bit.
282
283 - ``NSACR``. Enable non-secure access to Advanced SIMD functionality and
284 system register access to implemented trace registers.
285
286 - ``FPEXC``. Enable access to the Advanced SIMD and floating-point
287 functionality from all Exception levels.
288
289 - ``CPSR.A``. The Asynchronous data abort interrupt is enabled by clearing
290 the Asynchronous data abort interrupt mask bit.
291
292 - ``SDCR``. The ``SDCR.SPD`` field is set to disable AArch32 Secure
293 self-hosted privileged debug.
294
295Platform initialization
296^^^^^^^^^^^^^^^^^^^^^^^
297
Dan Handley610e7e12018-03-01 18:44:00 +0000298On Arm platforms, BL1 performs the following platform initializations:
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100299
300- Enable the Trusted Watchdog.
301- Initialize the console.
302- Configure the Interconnect to enable hardware coherency.
303- Enable the MMU and map the memory it needs to access.
304- Configure any required platform storage to load the next bootloader image
305 (BL2).
Soby Mathewb1bf0442018-02-16 14:52:52 +0000306- If the BL1 dynamic configuration file, ``TB_FW_CONFIG``, is available, then
307 load it to the platform defined address and make it available to BL2 via
308 ``arg0``.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100309
310Firmware Update detection and execution
311^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
312
313After performing platform setup, BL1 common code calls
314``bl1_plat_get_next_image_id()`` to determine if `Firmware Update`_ is required or
315to proceed with the normal boot process. If the platform code returns
316``BL2_IMAGE_ID`` then the normal boot sequence is executed as described in the
317next section, else BL1 assumes that `Firmware Update`_ is required and execution
318passes to the first image in the `Firmware Update`_ process. In either case, BL1
319retrieves a descriptor of the next image by calling ``bl1_plat_get_image_desc()``.
320The image descriptor contains an ``entry_point_info_t`` structure, which BL1
321uses to initialize the execution state of the next image.
322
323BL2 image load and execution
324^^^^^^^^^^^^^^^^^^^^^^^^^^^^
325
326In the normal boot flow, BL1 execution continues as follows:
327
328#. BL1 prints the following string from the primary CPU to indicate successful
329 execution of the BL1 stage:
330
331 ::
332
333 "Booting Trusted Firmware"
334
Soby Mathewb1bf0442018-02-16 14:52:52 +0000335#. BL1 loads a BL2 raw binary image from platform storage, at a
336 platform-specific base address. Prior to the load, BL1 invokes
337 ``bl1_plat_handle_pre_image_load()`` which allows the platform to update or
338 use the image information. If the BL2 image file is not present or if
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100339 there is not enough free trusted SRAM the following error message is
340 printed:
341
342 ::
343
344 "Failed to load BL2 firmware."
345
Soby Mathewb1bf0442018-02-16 14:52:52 +0000346#. BL1 invokes ``bl1_plat_handle_post_image_load()`` which again is intended
347 for platforms to take further action after image load. This function must
348 populate the necessary arguments for BL2, which may also include the memory
349 layout. Further description of the memory layout can be found later
350 in this document.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100351
352#. BL1 passes control to the BL2 image at Secure EL1 (for AArch64) or at
353 Secure SVC mode (for AArch32), starting from its load address.
354
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100355BL2
356~~~
357
358BL1 loads and passes control to BL2 at Secure-EL1 (for AArch64) or at Secure
359SVC mode (for AArch32) . BL2 is linked against and loaded at a platform-specific
360base address (more information can be found later in this document).
361The functionality implemented by BL2 is as follows.
362
363Architectural initialization
364^^^^^^^^^^^^^^^^^^^^^^^^^^^^
365
366For AArch64, BL2 performs the minimal architectural initialization required
Dan Handley610e7e12018-03-01 18:44:00 +0000367for subsequent stages of TF-A and normal world software. EL1 and EL0 are given
368access to Floating Point and Advanced SIMD registers by clearing the
369``CPACR.FPEN`` bits.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100370
371For AArch32, the minimal architectural initialization required for subsequent
Dan Handley610e7e12018-03-01 18:44:00 +0000372stages of TF-A and normal world software is taken care of in BL1 as both BL1
373and BL2 execute at PL1.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100374
375Platform initialization
376^^^^^^^^^^^^^^^^^^^^^^^
377
Dan Handley610e7e12018-03-01 18:44:00 +0000378On Arm platforms, BL2 performs the following platform initializations:
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100379
380- Initialize the console.
381- Configure any required platform storage to allow loading further bootloader
382 images.
383- Enable the MMU and map the memory it needs to access.
384- Perform platform security setup to allow access to controlled components.
385- Reserve some memory for passing information to the next bootloader image
386 EL3 Runtime Software and populate it.
387- Define the extents of memory available for loading each subsequent
388 bootloader image.
Soby Mathewb1bf0442018-02-16 14:52:52 +0000389- If BL1 has passed TB_FW_CONFIG dynamic configuration file in ``arg0``,
390 then parse it.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100391
392Image loading in BL2
393^^^^^^^^^^^^^^^^^^^^
394
395Image loading scheme in BL2 depends on ``LOAD_IMAGE_V2`` build option. If the
396flag is disabled, the BLxx images are loaded, by calling the respective
397load\_blxx() function from BL2 generic code. If the flag is enabled, the BL2
398generic code loads the images based on the list of loadable images provided
399by the platform. BL2 passes the list of executable images provided by the
400platform to the next handover BL image. By default, this flag is disabled for
401AArch64 and the AArch32 build is supported only if this flag is enabled.
402
Soby Mathewb1bf0442018-02-16 14:52:52 +0000403The list of loadable images provided by the platform may also contain
404dynamic configuration files. The files are loaded and can be parsed as
405needed in the ``bl2_plat_handle_post_image_load()`` function. These
406configuration files can be passed to next Boot Loader stages as arguments
407by updating the corresponding entrypoint information in this function.
408
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100409SCP\_BL2 (System Control Processor Firmware) image load
410^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
411
412Some systems have a separate System Control Processor (SCP) for power, clock,
413reset and system control. BL2 loads the optional SCP\_BL2 image from platform
414storage into a platform-specific region of secure memory. The subsequent
Dan Handley610e7e12018-03-01 18:44:00 +0000415handling of SCP\_BL2 is platform specific. For example, on the Juno Arm
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100416development platform port the image is transferred into SCP's internal memory
417using the Boot Over MHU (BOM) protocol after being loaded in the trusted SRAM
418memory. The SCP executes SCP\_BL2 and signals to the Application Processor (AP)
419for BL2 execution to continue.
420
421EL3 Runtime Software image load
422^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
423
424BL2 loads the EL3 Runtime Software image from platform storage into a platform-
425specific address in trusted SRAM. If there is not enough memory to load the
426image or image is missing it leads to an assertion failure. If ``LOAD_IMAGE_V2``
427is disabled and if image loads successfully, BL2 updates the amount of trusted
428SRAM used and available for use by EL3 Runtime Software. This information is
429populated at a platform-specific memory address.
430
431AArch64 BL32 (Secure-EL1 Payload) image load
432^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
433
434BL2 loads the optional BL32 image from platform storage into a platform-
435specific region of secure memory. The image executes in the secure world. BL2
436relies on BL31 to pass control to the BL32 image, if present. Hence, BL2
437populates a platform-specific area of memory with the entrypoint/load-address
438of the BL32 image. The value of the Saved Processor Status Register (``SPSR``)
439for entry into BL32 is not determined by BL2, it is initialized by the
440Secure-EL1 Payload Dispatcher (see later) within BL31, which is responsible for
441managing interaction with BL32. This information is passed to BL31.
442
443BL33 (Non-trusted Firmware) image load
444^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
445
446BL2 loads the BL33 image (e.g. UEFI or other test or boot software) from
447platform storage into non-secure memory as defined by the platform.
448
449BL2 relies on EL3 Runtime Software to pass control to BL33 once secure state
450initialization is complete. Hence, BL2 populates a platform-specific area of
451memory with the entrypoint and Saved Program Status Register (``SPSR``) of the
452normal world software image. The entrypoint is the load address of the BL33
453image. The ``SPSR`` is determined as specified in Section 5.13 of the
454`PSCI PDD`_. This information is passed to the EL3 Runtime Software.
455
456AArch64 BL31 (EL3 Runtime Software) execution
457^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
458
459BL2 execution continues as follows:
460
461#. BL2 passes control back to BL1 by raising an SMC, providing BL1 with the
462 BL31 entrypoint. The exception is handled by the SMC exception handler
463 installed by BL1.
464
465#. BL1 turns off the MMU and flushes the caches. It clears the
466 ``SCTLR_EL3.M/I/C`` bits, flushes the data cache to the point of coherency
467 and invalidates the TLBs.
468
469#. BL1 passes control to BL31 at the specified entrypoint at EL3.
470
Roberto Vargasb1584272017-11-20 13:36:10 +0000471Running BL2 at EL3 execution level
472~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
473
Dan Handley610e7e12018-03-01 18:44:00 +0000474Some platforms have a non-TF-A Boot ROM that expects the next boot stage
475to execute at EL3. On these platforms, TF-A BL1 is a waste of memory
476as its only purpose is to ensure TF-A BL2 is entered at S-EL1. To avoid
Roberto Vargasb1584272017-11-20 13:36:10 +0000477this waste, a special mode enables BL2 to execute at EL3, which allows
Dan Handley610e7e12018-03-01 18:44:00 +0000478a non-TF-A Boot ROM to load and jump directly to BL2. This mode is selected
Roberto Vargasb1584272017-11-20 13:36:10 +0000479when the build flag BL2_AT_EL3 is enabled. The main differences in this
480mode are:
481
482#. BL2 includes the reset code and the mailbox mechanism to differentiate
483 cold boot and warm boot. It runs at EL3 doing the arch
484 initialization required for EL3.
485
486#. BL2 does not receive the meminfo information from BL1 anymore. This
487 information can be passed by the Boot ROM or be internal to the
488 BL2 image.
489
490#. Since BL2 executes at EL3, BL2 jumps directly to the next image,
491 instead of invoking the RUN_IMAGE SMC call.
492
493
494We assume 3 different types of BootROM support on the platform:
495
496#. The Boot ROM always jumps to the same address, for both cold
497 and warm boot. In this case, we will need to keep a resident part
498 of BL2 whose memory cannot be reclaimed by any other image. The
499 linker script defines the symbols __TEXT_RESIDENT_START__ and
500 __TEXT_RESIDENT_END__ that allows the platform to configure
501 correctly the memory map.
502#. The platform has some mechanism to indicate the jump address to the
503 Boot ROM. Platform code can then program the jump address with
504 psci_warmboot_entrypoint during cold boot.
505#. The platform has some mechanism to program the reset address using
506 the PROGRAMMABLE_RESET_ADDRESS feature. Platform code can then
507 program the reset address with psci_warmboot_entrypoint during
508 cold boot, bypassing the boot ROM for warm boot.
509
510In the last 2 cases, no part of BL2 needs to remain resident at
511runtime. In the first 2 cases, we expect the Boot ROM to be able to
512differentiate between warm and cold boot, to avoid loading BL2 again
513during warm boot.
514
515This functionality can be tested with FVP loading the image directly
516in memory and changing the address where the system jumps at reset.
517For example:
518
519 -C cluster0.cpu0.RVBAR=0x4014000
520 --data cluster0.cpu0=bl2.bin@0x4014000
521
522With this configuration, FVP is like a platform of the first case,
523where the Boot ROM jumps always to the same address. For simplification,
524BL32 is loaded in DRAM in this case, to avoid other images reclaiming
525BL2 memory.
526
527
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100528AArch64 BL31
529~~~~~~~~~~~~
530
531The image for this stage is loaded by BL2 and BL1 passes control to BL31 at
532EL3. BL31 executes solely in trusted SRAM. BL31 is linked against and
533loaded at a platform-specific base address (more information can be found later
534in this document). The functionality implemented by BL31 is as follows.
535
536Architectural initialization
537^^^^^^^^^^^^^^^^^^^^^^^^^^^^
538
539Currently, BL31 performs a similar architectural initialization to BL1 as
540far as system register settings are concerned. Since BL1 code resides in ROM,
541architectural initialization in BL31 allows override of any previous
542initialization done by BL1.
543
544BL31 initializes the per-CPU data framework, which provides a cache of
545frequently accessed per-CPU data optimised for fast, concurrent manipulation
546on different CPUs. This buffer includes pointers to per-CPU contexts, crash
547buffer, CPU reset and power down operations, PSCI data, platform data and so on.
548
549It then replaces the exception vectors populated by BL1 with its own. BL31
550exception vectors implement more elaborate support for handling SMCs since this
551is the only mechanism to access the runtime services implemented by BL31 (PSCI
552for example). BL31 checks each SMC for validity as specified by the
553`SMC calling convention PDD`_ before passing control to the required SMC
554handler routine.
555
556BL31 programs the ``CNTFRQ_EL0`` register with the clock frequency of the system
557counter, which is provided by the platform.
558
559Platform initialization
560^^^^^^^^^^^^^^^^^^^^^^^
561
562BL31 performs detailed platform initialization, which enables normal world
563software to function correctly.
564
Dan Handley610e7e12018-03-01 18:44:00 +0000565On Arm platforms, this consists of the following:
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100566
567- Initialize the console.
568- Configure the Interconnect to enable hardware coherency.
569- Enable the MMU and map the memory it needs to access.
570- Initialize the generic interrupt controller.
571- Initialize the power controller device.
572- Detect the system topology.
573
574Runtime services initialization
575^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
576
577BL31 is responsible for initializing the runtime services. One of them is PSCI.
578
579As part of the PSCI initializations, BL31 detects the system topology. It also
580initializes the data structures that implement the state machine used to track
581the state of power domain nodes. The state can be one of ``OFF``, ``RUN`` or
582``RETENTION``. All secondary CPUs are initially in the ``OFF`` state. The cluster
583that the primary CPU belongs to is ``ON``; any other cluster is ``OFF``. It also
584initializes the locks that protect them. BL31 accesses the state of a CPU or
585cluster immediately after reset and before the data cache is enabled in the
586warm boot path. It is not currently possible to use 'exclusive' based spinlocks,
587therefore BL31 uses locks based on Lamport's Bakery algorithm instead.
588
589The runtime service framework and its initialization is described in more
590detail in the "EL3 runtime services framework" section below.
591
592Details about the status of the PSCI implementation are provided in the
593"Power State Coordination Interface" section below.
594
595AArch64 BL32 (Secure-EL1 Payload) image initialization
596^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
597
598If a BL32 image is present then there must be a matching Secure-EL1 Payload
599Dispatcher (SPD) service (see later for details). During initialization
600that service must register a function to carry out initialization of BL32
601once the runtime services are fully initialized. BL31 invokes such a
602registered function to initialize BL32 before running BL33. This initialization
603is not necessary for AArch32 SPs.
604
605Details on BL32 initialization and the SPD's role are described in the
606"Secure-EL1 Payloads and Dispatchers" section below.
607
608BL33 (Non-trusted Firmware) execution
609^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
610
611EL3 Runtime Software initializes the EL2 or EL1 processor context for normal-
612world cold boot, ensuring that no secure state information finds its way into
613the non-secure execution state. EL3 Runtime Software uses the entrypoint
614information provided by BL2 to jump to the Non-trusted firmware image (BL33)
615at the highest available Exception Level (EL2 if available, otherwise EL1).
616
617Using alternative Trusted Boot Firmware in place of BL1 & BL2 (AArch64 only)
618~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
619
620Some platforms have existing implementations of Trusted Boot Firmware that
Dan Handley610e7e12018-03-01 18:44:00 +0000621would like to use TF-A BL31 for the EL3 Runtime Software. To enable this
622firmware architecture it is important to provide a fully documented and stable
623interface between the Trusted Boot Firmware and BL31.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100624
625Future changes to the BL31 interface will be done in a backwards compatible
626way, and this enables these firmware components to be independently enhanced/
627updated to develop and exploit new functionality.
628
629Required CPU state when calling ``bl31_entrypoint()`` during cold boot
630^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
631
632This function must only be called by the primary CPU.
633
634On entry to this function the calling primary CPU must be executing in AArch64
635EL3, little-endian data access, and all interrupt sources masked:
636
637::
638
639 PSTATE.EL = 3
640 PSTATE.RW = 1
641 PSTATE.DAIF = 0xf
642 SCTLR_EL3.EE = 0
643
644X0 and X1 can be used to pass information from the Trusted Boot Firmware to the
645platform code in BL31:
646
647::
648
Dan Handley610e7e12018-03-01 18:44:00 +0000649 X0 : Reserved for common TF-A information
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100650 X1 : Platform specific information
651
652BL31 zero-init sections (e.g. ``.bss``) should not contain valid data on entry,
653these will be zero filled prior to invoking platform setup code.
654
655Use of the X0 and X1 parameters
656'''''''''''''''''''''''''''''''
657
658The parameters are platform specific and passed from ``bl31_entrypoint()`` to
659``bl31_early_platform_setup()``. The value of these parameters is never directly
660used by the common BL31 code.
661
662The convention is that ``X0`` conveys information regarding the BL31, BL32 and
663BL33 images from the Trusted Boot firmware and ``X1`` can be used for other
Dan Handley610e7e12018-03-01 18:44:00 +0000664platform specific purpose. This convention allows platforms which use TF-A's
665BL1 and BL2 images to transfer additional platform specific information from
666Secure Boot without conflicting with future evolution of TF-A using ``X0`` to
667pass a ``bl31_params`` structure.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100668
669BL31 common and SPD initialization code depends on image and entrypoint
670information about BL33 and BL32, which is provided via BL31 platform APIs.
671This information is required until the start of execution of BL33. This
672information can be provided in a platform defined manner, e.g. compiled into
673the platform code in BL31, or provided in a platform defined memory location
674by the Trusted Boot firmware, or passed from the Trusted Boot Firmware via the
675Cold boot Initialization parameters. This data may need to be cleaned out of
676the CPU caches if it is provided by an earlier boot stage and then accessed by
677BL31 platform code before the caches are enabled.
678
Dan Handley610e7e12018-03-01 18:44:00 +0000679TF-A's BL2 implementation passes a ``bl31_params`` structure in
680``X0`` and the Arm development platforms interpret this in the BL31 platform
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100681code.
682
683MMU, Data caches & Coherency
684''''''''''''''''''''''''''''
685
686BL31 does not depend on the enabled state of the MMU, data caches or
687interconnect coherency on entry to ``bl31_entrypoint()``. If these are disabled
688on entry, these should be enabled during ``bl31_plat_arch_setup()``.
689
690Data structures used in the BL31 cold boot interface
691''''''''''''''''''''''''''''''''''''''''''''''''''''
692
693These structures are designed to support compatibility and independent
694evolution of the structures and the firmware images. For example, a version of
695BL31 that can interpret the BL3x image information from different versions of
696BL2, a platform that uses an extended entry\_point\_info structure to convey
697additional register information to BL31, or a ELF image loader that can convey
698more details about the firmware images.
699
700To support these scenarios the structures are versioned and sized, which enables
701BL31 to detect which information is present and respond appropriately. The
702``param_header`` is defined to capture this information:
703
704.. code:: c
705
706 typedef struct param_header {
707 uint8_t type; /* type of the structure */
708 uint8_t version; /* version of this structure */
709 uint16_t size; /* size of this structure in bytes */
710 uint32_t attr; /* attributes: unused bits SBZ */
711 } param_header_t;
712
713The structures using this format are ``entry_point_info``, ``image_info`` and
714``bl31_params``. The code that allocates and populates these structures must set
715the header fields appropriately, and the ``SET_PARAM_HEAD()`` a macro is defined
716to simplify this action.
717
718Required CPU state for BL31 Warm boot initialization
719^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
720
Dan Handley610e7e12018-03-01 18:44:00 +0000721When requesting a CPU power-on, or suspending a running CPU, TF-A provides
722the platform power management code with a Warm boot initialization
723entry-point, to be invoked by the CPU immediately after the reset handler.
724On entry to the Warm boot initialization function the calling CPU must be in
725AArch64 EL3, little-endian data access and all interrupt sources masked:
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100726
727::
728
729 PSTATE.EL = 3
730 PSTATE.RW = 1
731 PSTATE.DAIF = 0xf
732 SCTLR_EL3.EE = 0
733
734The PSCI implementation will initialize the processor state and ensure that the
735platform power management code is then invoked as required to initialize all
736necessary system, cluster and CPU resources.
737
738AArch32 EL3 Runtime Software entrypoint interface
739~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
740
741To enable this firmware architecture it is important to provide a fully
742documented and stable interface between the Trusted Boot Firmware and the
743AArch32 EL3 Runtime Software.
744
745Future changes to the entrypoint interface will be done in a backwards
746compatible way, and this enables these firmware components to be independently
747enhanced/updated to develop and exploit new functionality.
748
749Required CPU state when entering during cold boot
750^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
751
752This function must only be called by the primary CPU.
753
754On entry to this function the calling primary CPU must be executing in AArch32
755EL3, little-endian data access, and all interrupt sources masked:
756
757::
758
759 PSTATE.AIF = 0x7
760 SCTLR.EE = 0
761
762R0 and R1 are used to pass information from the Trusted Boot Firmware to the
763platform code in AArch32 EL3 Runtime Software:
764
765::
766
Dan Handley610e7e12018-03-01 18:44:00 +0000767 R0 : Reserved for common TF-A information
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100768 R1 : Platform specific information
769
770Use of the R0 and R1 parameters
771'''''''''''''''''''''''''''''''
772
773The parameters are platform specific and the convention is that ``R0`` conveys
774information regarding the BL3x images from the Trusted Boot firmware and ``R1``
775can be used for other platform specific purpose. This convention allows
Dan Handley610e7e12018-03-01 18:44:00 +0000776platforms which use TF-A's BL1 and BL2 images to transfer additional platform
777specific information from Secure Boot without conflicting with future
778evolution of TF-A using ``R0`` to pass a ``bl_params`` structure.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100779
780The AArch32 EL3 Runtime Software is responsible for entry into BL33. This
781information can be obtained in a platform defined manner, e.g. compiled into
782the AArch32 EL3 Runtime Software, or provided in a platform defined memory
783location by the Trusted Boot firmware, or passed from the Trusted Boot Firmware
784via the Cold boot Initialization parameters. This data may need to be cleaned
785out of the CPU caches if it is provided by an earlier boot stage and then
786accessed by AArch32 EL3 Runtime Software before the caches are enabled.
787
Dan Handley610e7e12018-03-01 18:44:00 +0000788When using AArch32 EL3 Runtime Software, the Arm development platforms pass a
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100789``bl_params`` structure in ``R0`` from BL2 to be interpreted by AArch32 EL3 Runtime
790Software platform code.
791
792MMU, Data caches & Coherency
793''''''''''''''''''''''''''''
794
795AArch32 EL3 Runtime Software must not depend on the enabled state of the MMU,
796data caches or interconnect coherency in its entrypoint. They must be explicitly
797enabled if required.
798
799Data structures used in cold boot interface
800'''''''''''''''''''''''''''''''''''''''''''
801
802The AArch32 EL3 Runtime Software cold boot interface uses ``bl_params`` instead
803of ``bl31_params``. The ``bl_params`` structure is based on the convention
804described in AArch64 BL31 cold boot interface section.
805
806Required CPU state for warm boot initialization
807^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
808
809When requesting a CPU power-on, or suspending a running CPU, AArch32 EL3
810Runtime Software must ensure execution of a warm boot initialization entrypoint.
Dan Handley610e7e12018-03-01 18:44:00 +0000811If TF-A BL1 is used and the PROGRAMMABLE\_RESET\_ADDRESS build flag is false,
812then AArch32 EL3 Runtime Software must ensure that BL1 branches to the warm
813boot entrypoint by arranging for the BL1 platform function,
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100814plat\_get\_my\_entrypoint(), to return a non-zero value.
815
816In this case, the warm boot entrypoint must be in AArch32 EL3, little-endian
817data access and all interrupt sources masked:
818
819::
820
821 PSTATE.AIF = 0x7
822 SCTLR.EE = 0
823
Dan Handley610e7e12018-03-01 18:44:00 +0000824The warm boot entrypoint may be implemented by using TF-A
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100825``psci_warmboot_entrypoint()`` function. In that case, the platform must fulfil
826the pre-requisites mentioned in the `PSCI Library integration guide`_.
827
828EL3 runtime services framework
829------------------------------
830
831Software executing in the non-secure state and in the secure state at exception
832levels lower than EL3 will request runtime services using the Secure Monitor
833Call (SMC) instruction. These requests will follow the convention described in
834the SMC Calling Convention PDD (`SMCCC`_). The `SMCCC`_ assigns function
835identifiers to each SMC request and describes how arguments are passed and
836returned.
837
838The EL3 runtime services framework enables the development of services by
839different providers that can be easily integrated into final product firmware.
840The following sections describe the framework which facilitates the
841registration, initialization and use of runtime services in EL3 Runtime
842Software (BL31).
843
844The design of the runtime services depends heavily on the concepts and
845definitions described in the `SMCCC`_, in particular SMC Function IDs, Owning
846Entity Numbers (OEN), Fast and Yielding calls, and the SMC32 and SMC64 calling
847conventions. Please refer to that document for more detailed explanation of
848these terms.
849
850The following runtime services are expected to be implemented first. They have
851not all been instantiated in the current implementation.
852
853#. Standard service calls
854
855 This service is for management of the entire system. The Power State
856 Coordination Interface (`PSCI`_) is the first set of standard service calls
Dan Handley610e7e12018-03-01 18:44:00 +0000857 defined by Arm (see PSCI section later).
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100858
859#. Secure-EL1 Payload Dispatcher service
860
861 If a system runs a Trusted OS or other Secure-EL1 Payload (SP) then
862 it also requires a *Secure Monitor* at EL3 to switch the EL1 processor
863 context between the normal world (EL1/EL2) and trusted world (Secure-EL1).
864 The Secure Monitor will make these world switches in response to SMCs. The
865 `SMCCC`_ provides for such SMCs with the Trusted OS Call and Trusted
866 Application Call OEN ranges.
867
868 The interface between the EL3 Runtime Software and the Secure-EL1 Payload is
869 not defined by the `SMCCC`_ or any other standard. As a result, each
870 Secure-EL1 Payload requires a specific Secure Monitor that runs as a runtime
Dan Handley610e7e12018-03-01 18:44:00 +0000871 service - within TF-A this service is referred to as the Secure-EL1 Payload
872 Dispatcher (SPD).
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100873
Dan Handley610e7e12018-03-01 18:44:00 +0000874 TF-A provides a Test Secure-EL1 Payload (TSP) and its associated Dispatcher
875 (TSPD). Details of SPD design and TSP/TSPD operation are described in the
876 "Secure-EL1 Payloads and Dispatchers" section below.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100877
878#. CPU implementation service
879
880 This service will provide an interface to CPU implementation specific
881 services for a given platform e.g. access to processor errata workarounds.
882 This service is currently unimplemented.
883
Dan Handley610e7e12018-03-01 18:44:00 +0000884Additional services for Arm Architecture, SiP and OEM calls can be implemented.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100885Each implemented service handles a range of SMC function identifiers as
886described in the `SMCCC`_.
887
888Registration
889~~~~~~~~~~~~
890
891A runtime service is registered using the ``DECLARE_RT_SVC()`` macro, specifying
892the name of the service, the range of OENs covered, the type of service and
893initialization and call handler functions. This macro instantiates a ``const struct rt_svc_desc`` for the service with these details (see ``runtime_svc.h``).
894This structure is allocated in a special ELF section ``rt_svc_descs``, enabling
895the framework to find all service descriptors included into BL31.
896
897The specific service for a SMC Function is selected based on the OEN and call
898type of the Function ID, and the framework uses that information in the service
899descriptor to identify the handler for the SMC Call.
900
901The service descriptors do not include information to identify the precise set
902of SMC function identifiers supported by this service implementation, the
903security state from which such calls are valid nor the capability to support
90464-bit and/or 32-bit callers (using SMC32 or SMC64). Responding appropriately
905to these aspects of a SMC call is the responsibility of the service
906implementation, the framework is focused on integration of services from
907different providers and minimizing the time taken by the framework before the
908service handler is invoked.
909
910Details of the parameters, requirements and behavior of the initialization and
911call handling functions are provided in the following sections.
912
913Initialization
914~~~~~~~~~~~~~~
915
916``runtime_svc_init()`` in ``runtime_svc.c`` initializes the runtime services
917framework running on the primary CPU during cold boot as part of the BL31
918initialization. This happens prior to initializing a Trusted OS and running
919Normal world boot firmware that might in turn use these services.
920Initialization involves validating each of the declared runtime service
921descriptors, calling the service initialization function and populating the
922index used for runtime lookup of the service.
923
924The BL31 linker script collects all of the declared service descriptors into a
925single array and defines symbols that allow the framework to locate and traverse
926the array, and determine its size.
927
928The framework does basic validation of each descriptor to halt firmware
929initialization if service declaration errors are detected. The framework does
930not check descriptors for the following error conditions, and may behave in an
931unpredictable manner under such scenarios:
932
933#. Overlapping OEN ranges
934#. Multiple descriptors for the same range of OENs and ``call_type``
935#. Incorrect range of owning entity numbers for a given ``call_type``
936
937Once validated, the service ``init()`` callback is invoked. This function carries
938out any essential EL3 initialization before servicing requests. The ``init()``
939function is only invoked on the primary CPU during cold boot. If the service
940uses per-CPU data this must either be initialized for all CPUs during this call,
941or be done lazily when a CPU first issues an SMC call to that service. If
942``init()`` returns anything other than ``0``, this is treated as an initialization
943error and the service is ignored: this does not cause the firmware to halt.
944
945The OEN and call type fields present in the SMC Function ID cover a total of
946128 distinct services, but in practice a single descriptor can cover a range of
947OENs, e.g. SMCs to call a Trusted OS function. To optimize the lookup of a
948service handler, the framework uses an array of 128 indices that map every
949distinct OEN/call-type combination either to one of the declared services or to
950indicate the service is not handled. This ``rt_svc_descs_indices[]`` array is
951populated for all of the OENs covered by a service after the service ``init()``
952function has reported success. So a service that fails to initialize will never
953have it's ``handle()`` function invoked.
954
955The following figure shows how the ``rt_svc_descs_indices[]`` index maps the SMC
956Function ID call type and OEN onto a specific service handler in the
957``rt_svc_descs[]`` array.
958
959|Image 1|
960
961Handling an SMC
962~~~~~~~~~~~~~~~
963
964When the EL3 runtime services framework receives a Secure Monitor Call, the SMC
965Function ID is passed in W0 from the lower exception level (as per the
966`SMCCC`_). If the calling register width is AArch32, it is invalid to invoke an
967SMC Function which indicates the SMC64 calling convention: such calls are
968ignored and return the Unknown SMC Function Identifier result code ``0xFFFFFFFF``
969in R0/X0.
970
971Bit[31] (fast/yielding call) and bits[29:24] (owning entity number) of the SMC
972Function ID are combined to index into the ``rt_svc_descs_indices[]`` array. The
973resulting value might indicate a service that has no handler, in this case the
974framework will also report an Unknown SMC Function ID. Otherwise, the value is
975used as a further index into the ``rt_svc_descs[]`` array to locate the required
976service and handler.
977
978The service's ``handle()`` callback is provided with five of the SMC parameters
979directly, the others are saved into memory for retrieval (if needed) by the
980handler. The handler is also provided with an opaque ``handle`` for use with the
981supporting library for parameter retrieval, setting return values and context
982manipulation; and with ``flags`` indicating the security state of the caller. The
983framework finally sets up the execution stack for the handler, and invokes the
984services ``handle()`` function.
985
986On return from the handler the result registers are populated in X0-X3 before
987restoring the stack and CPU state and returning from the original SMC.
988
989Power State Coordination Interface
990----------------------------------
991
992TODO: Provide design walkthrough of PSCI implementation.
993
Roberto Vargasd963e3e2017-09-12 10:28:35 +0100994The PSCI v1.1 specification categorizes APIs as optional and mandatory. All the
995mandatory APIs in PSCI v1.1, PSCI v1.0 and in PSCI v0.2 draft specification
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100996`Power State Coordination Interface PDD`_ are implemented. The table lists
Roberto Vargasd963e3e2017-09-12 10:28:35 +0100997the PSCI v1.1 APIs and their support in generic code.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100998
999An API implementation might have a dependency on platform code e.g. CPU\_SUSPEND
1000requires the platform to export a part of the implementation. Hence the level
1001of support of the mandatory APIs depends upon the support exported by the
1002platform port as well. The Juno and FVP (all variants) platforms export all the
1003required support.
1004
1005+-----------------------------+-------------+-------------------------------+
Roberto Vargasd963e3e2017-09-12 10:28:35 +01001006| PSCI v1.1 API | Supported | Comments |
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001007+=============================+=============+===============================+
Roberto Vargasd963e3e2017-09-12 10:28:35 +01001008| ``PSCI_VERSION`` | Yes | The version returned is 1.1 |
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001009+-----------------------------+-------------+-------------------------------+
1010| ``CPU_SUSPEND`` | Yes\* | |
1011+-----------------------------+-------------+-------------------------------+
1012| ``CPU_OFF`` | Yes\* | |
1013+-----------------------------+-------------+-------------------------------+
1014| ``CPU_ON`` | Yes\* | |
1015+-----------------------------+-------------+-------------------------------+
1016| ``AFFINITY_INFO`` | Yes | |
1017+-----------------------------+-------------+-------------------------------+
1018| ``MIGRATE`` | Yes\*\* | |
1019+-----------------------------+-------------+-------------------------------+
1020| ``MIGRATE_INFO_TYPE`` | Yes\*\* | |
1021+-----------------------------+-------------+-------------------------------+
1022| ``MIGRATE_INFO_CPU`` | Yes\*\* | |
1023+-----------------------------+-------------+-------------------------------+
1024| ``SYSTEM_OFF`` | Yes\* | |
1025+-----------------------------+-------------+-------------------------------+
1026| ``SYSTEM_RESET`` | Yes\* | |
1027+-----------------------------+-------------+-------------------------------+
1028| ``PSCI_FEATURES`` | Yes | |
1029+-----------------------------+-------------+-------------------------------+
1030| ``CPU_FREEZE`` | No | |
1031+-----------------------------+-------------+-------------------------------+
1032| ``CPU_DEFAULT_SUSPEND`` | No | |
1033+-----------------------------+-------------+-------------------------------+
1034| ``NODE_HW_STATE`` | Yes\* | |
1035+-----------------------------+-------------+-------------------------------+
1036| ``SYSTEM_SUSPEND`` | Yes\* | |
1037+-----------------------------+-------------+-------------------------------+
1038| ``PSCI_SET_SUSPEND_MODE`` | No | |
1039+-----------------------------+-------------+-------------------------------+
1040| ``PSCI_STAT_RESIDENCY`` | Yes\* | |
1041+-----------------------------+-------------+-------------------------------+
1042| ``PSCI_STAT_COUNT`` | Yes\* | |
1043+-----------------------------+-------------+-------------------------------+
Roberto Vargasd963e3e2017-09-12 10:28:35 +01001044| ``SYSTEM_RESET2`` | Yes\* | |
1045+-----------------------------+-------------+-------------------------------+
1046| ``MEM_PROTECT`` | Yes\* | |
1047+-----------------------------+-------------+-------------------------------+
1048| ``MEM_PROTECT_CHECK_RANGE`` | Yes\* | |
1049+-----------------------------+-------------+-------------------------------+
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001050
1051\*Note : These PSCI APIs require platform power management hooks to be
1052registered with the generic PSCI code to be supported.
1053
1054\*\*Note : These PSCI APIs require appropriate Secure Payload Dispatcher
1055hooks to be registered with the generic PSCI code to be supported.
1056
Dan Handley610e7e12018-03-01 18:44:00 +00001057The PSCI implementation in TF-A is a library which can be integrated with
1058AArch64 or AArch32 EL3 Runtime Software for Armv8-A systems. A guide to
1059integrating PSCI library with AArch32 EL3 Runtime Software can be found
1060`here`_.
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001061
1062Secure-EL1 Payloads and Dispatchers
1063-----------------------------------
1064
1065On a production system that includes a Trusted OS running in Secure-EL1/EL0,
1066the Trusted OS is coupled with a companion runtime service in the BL31
1067firmware. This service is responsible for the initialisation of the Trusted
1068OS and all communications with it. The Trusted OS is the BL32 stage of the
Dan Handley610e7e12018-03-01 18:44:00 +00001069boot flow in TF-A. The firmware will attempt to locate, load and execute a
1070BL32 image.
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001071
Dan Handley610e7e12018-03-01 18:44:00 +00001072TF-A uses a more general term for the BL32 software that runs at Secure-EL1 -
1073the *Secure-EL1 Payload* - as it is not always a Trusted OS.
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001074
Dan Handley610e7e12018-03-01 18:44:00 +00001075TF-A provides a Test Secure-EL1 Payload (TSP) and a Test Secure-EL1 Payload
1076Dispatcher (TSPD) service as an example of how a Trusted OS is supported on a
1077production system using the Runtime Services Framework. On such a system, the
1078Test BL32 image and service are replaced by the Trusted OS and its dispatcher
1079service. The TF-A build system expects that the dispatcher will define the
1080build flag ``NEED_BL32`` to enable it to include the BL32 in the build either
1081as a binary or to compile from source depending on whether the ``BL32`` build
1082option is specified or not.
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001083
1084The TSP runs in Secure-EL1. It is designed to demonstrate synchronous
1085communication with the normal-world software running in EL1/EL2. Communication
1086is initiated by the normal-world software
1087
1088- either directly through a Fast SMC (as defined in the `SMCCC`_)
1089
1090- or indirectly through a `PSCI`_ SMC. The `PSCI`_ implementation in turn
1091 informs the TSPD about the requested power management operation. This allows
1092 the TSP to prepare for or respond to the power state change
1093
1094The TSPD service is responsible for.
1095
1096- Initializing the TSP
1097
1098- Routing requests and responses between the secure and the non-secure
1099 states during the two types of communications just described
1100
1101Initializing a BL32 Image
1102~~~~~~~~~~~~~~~~~~~~~~~~~
1103
1104The Secure-EL1 Payload Dispatcher (SPD) service is responsible for initializing
1105the BL32 image. It needs access to the information passed by BL2 to BL31 to do
1106so. This is provided by:
1107
1108.. code:: c
1109
1110 entry_point_info_t *bl31_plat_get_next_image_ep_info(uint32_t);
1111
1112which returns a reference to the ``entry_point_info`` structure corresponding to
1113the image which will be run in the specified security state. The SPD uses this
1114API to get entry point information for the SECURE image, BL32.
1115
1116In the absence of a BL32 image, BL31 passes control to the normal world
1117bootloader image (BL33). When the BL32 image is present, it is typical
1118that the SPD wants control to be passed to BL32 first and then later to BL33.
1119
1120To do this the SPD has to register a BL32 initialization function during
1121initialization of the SPD service. The BL32 initialization function has this
1122prototype:
1123
1124.. code:: c
1125
1126 int32_t init(void);
1127
1128and is registered using the ``bl31_register_bl32_init()`` function.
1129
Dan Handley610e7e12018-03-01 18:44:00 +00001130TF-A supports two approaches for the SPD to pass control to BL32 before
1131returning through EL3 and running the non-trusted firmware (BL33):
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001132
1133#. In the BL32 setup function, use ``bl31_set_next_image_type()`` to
1134 request that the exit from ``bl31_main()`` is to the BL32 entrypoint in
1135 Secure-EL1. BL31 will exit to BL32 using the asynchronous method by
1136 calling ``bl31_prepare_next_image_entry()`` and ``el3_exit()``.
1137
1138 When the BL32 has completed initialization at Secure-EL1, it returns to
1139 BL31 by issuing an SMC, using a Function ID allocated to the SPD. On
1140 receipt of this SMC, the SPD service handler should switch the CPU context
1141 from trusted to normal world and use the ``bl31_set_next_image_type()`` and
1142 ``bl31_prepare_next_image_entry()`` functions to set up the initial return to
1143 the normal world firmware BL33. On return from the handler the framework
1144 will exit to EL2 and run BL33.
1145
1146#. The BL32 setup function registers an initialization function using
1147 ``bl31_register_bl32_init()`` which provides a SPD-defined mechanism to
1148 invoke a 'world-switch synchronous call' to Secure-EL1 to run the BL32
1149 entrypoint.
Dan Handley610e7e12018-03-01 18:44:00 +00001150 NOTE: The Test SPD service included with TF-A provides one implementation
1151 of such a mechanism.
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001152
1153 On completion BL32 returns control to BL31 via a SMC, and on receipt the
1154 SPD service handler invokes the synchronous call return mechanism to return
1155 to the BL32 initialization function. On return from this function,
1156 ``bl31_main()`` will set up the return to the normal world firmware BL33 and
1157 continue the boot process in the normal world.
1158
Jeenu Viswambharanb60420a2017-08-24 15:43:44 +01001159Crash Reporting in BL31
1160-----------------------
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001161
1162BL31 implements a scheme for reporting the processor state when an unhandled
1163exception is encountered. The reporting mechanism attempts to preserve all the
1164register contents and report it via a dedicated UART (PL011 console). BL31
1165reports the general purpose, EL3, Secure EL1 and some EL2 state registers.
1166
1167A dedicated per-CPU crash stack is maintained by BL31 and this is retrieved via
1168the per-CPU pointer cache. The implementation attempts to minimise the memory
1169required for this feature. The file ``crash_reporting.S`` contains the
1170implementation for crash reporting.
1171
1172The sample crash output is shown below.
1173
1174::
1175
1176 x0 :0x000000004F00007C
1177 x1 :0x0000000007FFFFFF
1178 x2 :0x0000000004014D50
1179 x3 :0x0000000000000000
1180 x4 :0x0000000088007998
1181 x5 :0x00000000001343AC
1182 x6 :0x0000000000000016
1183 x7 :0x00000000000B8A38
1184 x8 :0x00000000001343AC
1185 x9 :0x00000000000101A8
1186 x10 :0x0000000000000002
1187 x11 :0x000000000000011C
1188 x12 :0x00000000FEFDC644
1189 x13 :0x00000000FED93FFC
1190 x14 :0x0000000000247950
1191 x15 :0x00000000000007A2
1192 x16 :0x00000000000007A4
1193 x17 :0x0000000000247950
1194 x18 :0x0000000000000000
1195 x19 :0x00000000FFFFFFFF
1196 x20 :0x0000000004014D50
1197 x21 :0x000000000400A38C
1198 x22 :0x0000000000247950
1199 x23 :0x0000000000000010
1200 x24 :0x0000000000000024
1201 x25 :0x00000000FEFDC868
1202 x26 :0x00000000FEFDC86A
1203 x27 :0x00000000019EDEDC
1204 x28 :0x000000000A7CFDAA
1205 x29 :0x0000000004010780
1206 x30 :0x000000000400F004
1207 scr_el3 :0x0000000000000D3D
1208 sctlr_el3 :0x0000000000C8181F
1209 cptr_el3 :0x0000000000000000
1210 tcr_el3 :0x0000000080803520
1211 daif :0x00000000000003C0
1212 mair_el3 :0x00000000000004FF
1213 spsr_el3 :0x00000000800003CC
1214 elr_el3 :0x000000000400C0CC
1215 ttbr0_el3 :0x00000000040172A0
1216 esr_el3 :0x0000000096000210
1217 sp_el3 :0x0000000004014D50
1218 far_el3 :0x000000004F00007C
1219 spsr_el1 :0x0000000000000000
1220 elr_el1 :0x0000000000000000
1221 spsr_abt :0x0000000000000000
1222 spsr_und :0x0000000000000000
1223 spsr_irq :0x0000000000000000
1224 spsr_fiq :0x0000000000000000
1225 sctlr_el1 :0x0000000030C81807
1226 actlr_el1 :0x0000000000000000
1227 cpacr_el1 :0x0000000000300000
1228 csselr_el1 :0x0000000000000002
1229 sp_el1 :0x0000000004028800
1230 esr_el1 :0x0000000000000000
1231 ttbr0_el1 :0x000000000402C200
1232 ttbr1_el1 :0x0000000000000000
1233 mair_el1 :0x00000000000004FF
1234 amair_el1 :0x0000000000000000
1235 tcr_el1 :0x0000000000003520
1236 tpidr_el1 :0x0000000000000000
1237 tpidr_el0 :0x0000000000000000
1238 tpidrro_el0 :0x0000000000000000
1239 dacr32_el2 :0x0000000000000000
1240 ifsr32_el2 :0x0000000000000000
1241 par_el1 :0x0000000000000000
1242 far_el1 :0x0000000000000000
1243 afsr0_el1 :0x0000000000000000
1244 afsr1_el1 :0x0000000000000000
1245 contextidr_el1 :0x0000000000000000
1246 vbar_el1 :0x0000000004027000
1247 cntp_ctl_el0 :0x0000000000000000
1248 cntp_cval_el0 :0x0000000000000000
1249 cntv_ctl_el0 :0x0000000000000000
1250 cntv_cval_el0 :0x0000000000000000
1251 cntkctl_el1 :0x0000000000000000
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001252 sp_el0 :0x0000000004010780
1253
1254Guidelines for Reset Handlers
1255-----------------------------
1256
Dan Handley610e7e12018-03-01 18:44:00 +00001257TF-A implements a framework that allows CPU and platform ports to perform
1258actions very early after a CPU is released from reset in both the cold and warm
1259boot paths. This is done by calling the ``reset_handler()`` function in both
1260the BL1 and BL31 images. It in turn calls the platform and CPU specific reset
1261handling functions.
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001262
1263Details for implementing a CPU specific reset handler can be found in
1264Section 8. Details for implementing a platform specific reset handler can be
1265found in the `Porting Guide`_ (see the ``plat_reset_handler()`` function).
1266
1267When adding functionality to a reset handler, keep in mind that if a different
1268reset handling behavior is required between the first and the subsequent
1269invocations of the reset handling code, this should be detected at runtime.
1270In other words, the reset handler should be able to detect whether an action has
1271already been performed and act as appropriate. Possible courses of actions are,
1272e.g. skip the action the second time, or undo/redo it.
1273
Jeenu Viswambharanaeb267c2017-09-22 08:32:09 +01001274Configuring secure interrupts
1275-----------------------------
1276
1277The GIC driver is responsible for performing initial configuration of secure
1278interrupts on the platform. To this end, the platform is expected to provide the
1279GIC driver (either GICv2 or GICv3, as selected by the platform) with the
1280interrupt configuration during the driver initialisation.
1281
1282There are two ways to specify secure interrupt configuration:
1283
1284#. Array of secure interrupt properties: In this scheme, in both GICv2 and GICv3
1285 driver data structures, the ``interrupt_props`` member points to an array of
1286 interrupt properties. Each element of the array specifies the interrupt
1287 number and its configuration, viz. priority, group, configuration. Each
1288 element of the array shall be populated by the macro ``INTR_PROP_DESC()``.
1289 The macro takes the following arguments:
1290
1291 - 10-bit interrupt number,
1292
1293 - 8-bit interrupt priority,
1294
1295 - Interrupt type (one of ``INTR_TYPE_EL3``, ``INTR_TYPE_S_EL1``,
1296 ``INTR_TYPE_NS``),
1297
1298 - Interrupt configuration (either ``GIC_INTR_CFG_LEVEL`` or
1299 ``GIC_INTR_CFG_EDGE``).
1300
1301#. Array of secure interrupts: In this scheme, the GIC driver is provided an
1302 array of secure interrupt numbers. The GIC driver, at the time of
1303 initialisation, iterates through the array and assigns each interrupt
1304 the appropriate group.
1305
1306 - For the GICv2 driver, in ``gicv2_driver_data`` structure, the
1307 ``g0_interrupt_array`` member of the should point to the array of
1308 interrupts to be assigned to *Group 0*, and the ``g0_interrupt_num``
1309 member of the should be set to the number of interrupts in the array.
1310
1311 - For the GICv3 driver, in ``gicv3_driver_data`` structure:
1312
1313 - The ``g0_interrupt_array`` member of the should point to the array of
1314 interrupts to be assigned to *Group 0*, and the ``g0_interrupt_num``
1315 member of the should be set to the number of interrupts in the array.
1316
1317 - The ``g1s_interrupt_array`` member of the should point to the array of
1318 interrupts to be assigned to *Group 1 Secure*, and the
1319 ``g1s_interrupt_num`` member of the should be set to the number of
1320 interrupts in the array.
1321
1322 **Note that this scheme is deprecated.**
1323
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001324CPU specific operations framework
1325---------------------------------
1326
Dan Handley610e7e12018-03-01 18:44:00 +00001327Certain aspects of the Armv8-A architecture are implementation defined,
1328that is, certain behaviours are not architecturally defined, but must be
1329defined and documented by individual processor implementations. TF-A
1330implements a framework which categorises the common implementation defined
1331behaviours and allows a processor to export its implementation of that
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001332behaviour. The categories are:
1333
1334#. Processor specific reset sequence.
1335
1336#. Processor specific power down sequences.
1337
1338#. Processor specific register dumping as a part of crash reporting.
1339
1340#. Errata status reporting.
1341
1342Each of the above categories fulfils a different requirement.
1343
1344#. allows any processor specific initialization before the caches and MMU
1345 are turned on, like implementation of errata workarounds, entry into
1346 the intra-cluster coherency domain etc.
1347
1348#. allows each processor to implement the power down sequence mandated in
1349 its Technical Reference Manual (TRM).
1350
1351#. allows a processor to provide additional information to the developer
1352 in the event of a crash, for example Cortex-A53 has registers which
1353 can expose the data cache contents.
1354
1355#. allows a processor to define a function that inspects and reports the status
1356 of all errata workarounds on that processor.
1357
1358Please note that only 2. is mandated by the TRM.
1359
1360The CPU specific operations framework scales to accommodate a large number of
1361different CPUs during power down and reset handling. The platform can specify
1362any CPU optimization it wants to enable for each CPU. It can also specify
1363the CPU errata workarounds to be applied for each CPU type during reset
1364handling by defining CPU errata compile time macros. Details on these macros
1365can be found in the `cpu-specific-build-macros.rst`_ file.
1366
1367The CPU specific operations framework depends on the ``cpu_ops`` structure which
1368needs to be exported for each type of CPU in the platform. It is defined in
1369``include/lib/cpus/aarch64/cpu_macros.S`` and has the following fields : ``midr``,
1370``reset_func()``, ``cpu_pwr_down_ops`` (array of power down functions) and
1371``cpu_reg_dump()``.
1372
1373The CPU specific files in ``lib/cpus`` export a ``cpu_ops`` data structure with
1374suitable handlers for that CPU. For example, ``lib/cpus/aarch64/cortex_a53.S``
1375exports the ``cpu_ops`` for Cortex-A53 CPU. According to the platform
1376configuration, these CPU specific files must be included in the build by
1377the platform makefile. The generic CPU specific operations framework code exists
1378in ``lib/cpus/aarch64/cpu_helpers.S``.
1379
1380CPU specific Reset Handling
1381~~~~~~~~~~~~~~~~~~~~~~~~~~~
1382
1383After a reset, the state of the CPU when it calls generic reset handler is:
1384MMU turned off, both instruction and data caches turned off and not part
1385of any coherency domain.
1386
1387The BL entrypoint code first invokes the ``plat_reset_handler()`` to allow
1388the platform to perform any system initialization required and any system
1389errata workarounds that needs to be applied. The ``get_cpu_ops_ptr()`` reads
1390the current CPU midr, finds the matching ``cpu_ops`` entry in the ``cpu_ops``
1391array and returns it. Note that only the part number and implementer fields
1392in midr are used to find the matching ``cpu_ops`` entry. The ``reset_func()`` in
1393the returned ``cpu_ops`` is then invoked which executes the required reset
1394handling for that CPU and also any errata workarounds enabled by the platform.
1395This function must preserve the values of general purpose registers x20 to x29.
1396
1397Refer to Section "Guidelines for Reset Handlers" for general guidelines
1398regarding placement of code in a reset handler.
1399
1400CPU specific power down sequence
1401~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1402
1403During the BL31 initialization sequence, the pointer to the matching ``cpu_ops``
1404entry is stored in per-CPU data by ``init_cpu_ops()`` so that it can be quickly
1405retrieved during power down sequences.
1406
1407Various CPU drivers register handlers to perform power down at certain power
1408levels for that specific CPU. The PSCI service, upon receiving a power down
1409request, determines the highest power level at which to execute power down
1410sequence for a particular CPU. It uses the ``prepare_cpu_pwr_dwn()`` function to
1411pick the right power down handler for the requested level. The function
1412retrieves ``cpu_ops`` pointer member of per-CPU data, and from that, further
1413retrieves ``cpu_pwr_down_ops`` array, and indexes into the required level. If the
1414requested power level is higher than what a CPU driver supports, the handler
1415registered for highest level is invoked.
1416
1417At runtime the platform hooks for power down are invoked by the PSCI service to
1418perform platform specific operations during a power down sequence, for example
1419turning off CCI coherency during a cluster power down.
1420
1421CPU specific register reporting during crash
1422~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1423
1424If the crash reporting is enabled in BL31, when a crash occurs, the crash
1425reporting framework calls ``do_cpu_reg_dump`` which retrieves the matching
1426``cpu_ops`` using ``get_cpu_ops_ptr()`` function. The ``cpu_reg_dump()`` in
1427``cpu_ops`` is invoked, which then returns the CPU specific register values to
1428be reported and a pointer to the ASCII list of register names in a format
1429expected by the crash reporting framework.
1430
1431CPU errata status reporting
1432~~~~~~~~~~~~~~~~~~~~~~~~~~~
1433
Dan Handley610e7e12018-03-01 18:44:00 +00001434Errata workarounds for CPUs supported in TF-A are applied during both cold and
1435warm boots, shortly after reset. Individual Errata workarounds are enabled as
1436build options. Some errata workarounds have potential run-time implications;
1437therefore some are enabled by default, others not. Platform ports shall
1438override build options to enable or disable errata as appropriate. The CPU
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001439drivers take care of applying errata workarounds that are enabled and applicable
1440to a given CPU. Refer to the section titled *CPU Errata Workarounds* in `CPUBM`_
1441for more information.
1442
1443Functions in CPU drivers that apply errata workaround must follow the
1444conventions listed below.
1445
1446The errata workaround must be authored as two separate functions:
1447
1448- One that checks for errata. This function must determine whether that errata
1449 applies to the current CPU. Typically this involves matching the current
1450 CPUs revision and variant against a value that's known to be affected by the
1451 errata. If the function determines that the errata applies to this CPU, it
1452 must return ``ERRATA_APPLIES``; otherwise, it must return
1453 ``ERRATA_NOT_APPLIES``. The utility functions ``cpu_get_rev_var`` and
1454 ``cpu_rev_var_ls`` functions may come in handy for this purpose.
1455
1456For an errata identified as ``E``, the check function must be named
1457``check_errata_E``.
1458
1459This function will be invoked at different times, both from assembly and from
1460C run time. Therefore it must follow AAPCS, and must not use stack.
1461
1462- Another one that applies the errata workaround. This function would call the
1463 check function described above, and applies errata workaround if required.
1464
1465CPU drivers that apply errata workaround can optionally implement an assembly
1466function that report the status of errata workarounds pertaining to that CPU.
1467For a driver that registers the CPU, for example, ``cpux`` via. ``declare_cpu_ops``
1468macro, the errata reporting function, if it exists, must be named
1469``cpux_errata_report``. This function will always be called with MMU enabled; it
1470must follow AAPCS and may use stack.
1471
Dan Handley610e7e12018-03-01 18:44:00 +00001472In a debug build of TF-A, on a CPU that comes out of reset, both BL1 and the
1473runtime firmware (BL31 in AArch64, and BL32 in AArch32) will invoke errata
1474status reporting function, if one exists, for that type of CPU.
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001475
1476To report the status of each errata workaround, the function shall use the
1477assembler macro ``report_errata``, passing it:
1478
1479- The build option that enables the errata;
1480
1481- The name of the CPU: this must be the same identifier that CPU driver
1482 registered itself with, using ``declare_cpu_ops``;
1483
1484- And the errata identifier: the identifier must match what's used in the
1485 errata's check function described above.
1486
1487The errata status reporting function will be called once per CPU type/errata
1488combination during the software's active life time.
1489
Dan Handley610e7e12018-03-01 18:44:00 +00001490It's expected that whenever an errata workaround is submitted to TF-A, the
1491errata reporting function is appropriately extended to report its status as
1492well.
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001493
1494Reporting the status of errata workaround is for informational purpose only; it
1495has no functional significance.
1496
1497Memory layout of BL images
1498--------------------------
1499
1500Each bootloader image can be divided in 2 parts:
1501
1502- the static contents of the image. These are data actually stored in the
1503 binary on the disk. In the ELF terminology, they are called ``PROGBITS``
1504 sections;
1505
1506- the run-time contents of the image. These are data that don't occupy any
1507 space in the binary on the disk. The ELF binary just contains some
1508 metadata indicating where these data will be stored at run-time and the
1509 corresponding sections need to be allocated and initialized at run-time.
1510 In the ELF terminology, they are called ``NOBITS`` sections.
1511
1512All PROGBITS sections are grouped together at the beginning of the image,
Dan Handley610e7e12018-03-01 18:44:00 +00001513followed by all NOBITS sections. This is true for all TF-A images and it is
1514governed by the linker scripts. This ensures that the raw binary images are
1515as small as possible. If a NOBITS section was inserted in between PROGBITS
1516sections then the resulting binary file would contain zero bytes in place of
1517this NOBITS section, making the image unnecessarily bigger. Smaller images
1518allow faster loading from the FIP to the main memory.
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001519
1520Linker scripts and symbols
1521~~~~~~~~~~~~~~~~~~~~~~~~~~
1522
1523Each bootloader stage image layout is described by its own linker script. The
1524linker scripts export some symbols into the program symbol table. Their values
Dan Handley610e7e12018-03-01 18:44:00 +00001525correspond to particular addresses. TF-A code can refer to these symbols to
1526figure out the image memory layout.
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001527
Dan Handley610e7e12018-03-01 18:44:00 +00001528Linker symbols follow the following naming convention in TF-A.
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001529
1530- ``__<SECTION>_START__``
1531
1532 Start address of a given section named ``<SECTION>``.
1533
1534- ``__<SECTION>_END__``
1535
1536 End address of a given section named ``<SECTION>``. If there is an alignment
1537 constraint on the section's end address then ``__<SECTION>_END__`` corresponds
1538 to the end address of the section's actual contents, rounded up to the right
1539 boundary. Refer to the value of ``__<SECTION>_UNALIGNED_END__`` to know the
1540 actual end address of the section's contents.
1541
1542- ``__<SECTION>_UNALIGNED_END__``
1543
1544 End address of a given section named ``<SECTION>`` without any padding or
1545 rounding up due to some alignment constraint.
1546
1547- ``__<SECTION>_SIZE__``
1548
1549 Size (in bytes) of a given section named ``<SECTION>``. If there is an
1550 alignment constraint on the section's end address then ``__<SECTION>_SIZE__``
1551 corresponds to the size of the section's actual contents, rounded up to the
1552 right boundary. In other words, ``__<SECTION>_SIZE__ = __<SECTION>_END__ - _<SECTION>_START__``. Refer to the value of ``__<SECTION>_UNALIGNED_SIZE__``
1553 to know the actual size of the section's contents.
1554
1555- ``__<SECTION>_UNALIGNED_SIZE__``
1556
1557 Size (in bytes) of a given section named ``<SECTION>`` without any padding or
1558 rounding up due to some alignment constraint. In other words,
1559 ``__<SECTION>_UNALIGNED_SIZE__ = __<SECTION>_UNALIGNED_END__ - __<SECTION>_START__``.
1560
Dan Handley610e7e12018-03-01 18:44:00 +00001561Some of the linker symbols are mandatory as TF-A code relies on them to be
1562defined. They are listed in the following subsections. Some of them must be
1563provided for each bootloader stage and some are specific to a given bootloader
1564stage.
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001565
1566The linker scripts define some extra, optional symbols. They are not actually
1567used by any code but they help in understanding the bootloader images' memory
1568layout as they are easy to spot in the link map files.
1569
1570Common linker symbols
1571^^^^^^^^^^^^^^^^^^^^^
1572
1573All BL images share the following requirements:
1574
1575- The BSS section must be zero-initialised before executing any C code.
1576- The coherent memory section (if enabled) must be zero-initialised as well.
1577- The MMU setup code needs to know the extents of the coherent and read-only
1578 memory regions to set the right memory attributes. When
1579 ``SEPARATE_CODE_AND_RODATA=1``, it needs to know more specifically how the
1580 read-only memory region is divided between code and data.
1581
1582The following linker symbols are defined for this purpose:
1583
1584- ``__BSS_START__``
1585- ``__BSS_SIZE__``
1586- ``__COHERENT_RAM_START__`` Must be aligned on a page-size boundary.
1587- ``__COHERENT_RAM_END__`` Must be aligned on a page-size boundary.
1588- ``__COHERENT_RAM_UNALIGNED_SIZE__``
1589- ``__RO_START__``
1590- ``__RO_END__``
1591- ``__TEXT_START__``
1592- ``__TEXT_END__``
1593- ``__RODATA_START__``
1594- ``__RODATA_END__``
1595
1596BL1's linker symbols
1597^^^^^^^^^^^^^^^^^^^^
1598
1599BL1 being the ROM image, it has additional requirements. BL1 resides in ROM and
1600it is entirely executed in place but it needs some read-write memory for its
1601mutable data. Its ``.data`` section (i.e. its allocated read-write data) must be
1602relocated from ROM to RAM before executing any C code.
1603
1604The following additional linker symbols are defined for BL1:
1605
1606- ``__BL1_ROM_END__`` End address of BL1's ROM contents, covering its code
1607 and ``.data`` section in ROM.
1608- ``__DATA_ROM_START__`` Start address of the ``.data`` section in ROM. Must be
1609 aligned on a 16-byte boundary.
1610- ``__DATA_RAM_START__`` Address in RAM where the ``.data`` section should be
1611 copied over. Must be aligned on a 16-byte boundary.
1612- ``__DATA_SIZE__`` Size of the ``.data`` section (in ROM or RAM).
1613- ``__BL1_RAM_START__`` Start address of BL1 read-write data.
1614- ``__BL1_RAM_END__`` End address of BL1 read-write data.
1615
1616How to choose the right base addresses for each bootloader stage image
1617~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1618
Dan Handley610e7e12018-03-01 18:44:00 +00001619There is currently no support for dynamic image loading in TF-A. This means
1620that all bootloader images need to be linked against their ultimate runtime
1621locations and the base addresses of each image must be chosen carefully such
1622that images don't overlap each other in an undesired way. As the code grows,
1623the base addresses might need adjustments to cope with the new memory layout.
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001624
1625The memory layout is completely specific to the platform and so there is no
1626general recipe for choosing the right base addresses for each bootloader image.
1627However, there are tools to aid in understanding the memory layout. These are
1628the link map files: ``build/<platform>/<build-type>/bl<x>/bl<x>.map``, with ``<x>``
1629being the stage bootloader. They provide a detailed view of the memory usage of
1630each image. Among other useful information, they provide the end address of
1631each image.
1632
1633- ``bl1.map`` link map file provides ``__BL1_RAM_END__`` address.
1634- ``bl2.map`` link map file provides ``__BL2_END__`` address.
1635- ``bl31.map`` link map file provides ``__BL31_END__`` address.
1636- ``bl32.map`` link map file provides ``__BL32_END__`` address.
1637
1638For each bootloader image, the platform code must provide its start address
1639as well as a limit address that it must not overstep. The latter is used in the
1640linker scripts to check that the image doesn't grow past that address. If that
1641happens, the linker will issue a message similar to the following:
1642
1643::
1644
1645 aarch64-none-elf-ld: BLx has exceeded its limit.
1646
1647Additionally, if the platform memory layout implies some image overlaying like
1648on FVP, BL31 and TSP need to know the limit address that their PROGBITS
1649sections must not overstep. The platform code must provide those.
1650
Dan Handley610e7e12018-03-01 18:44:00 +00001651When LOAD\_IMAGE\_V2 is disabled, TF-A provides a mechanism to verify at boot
1652time that the memory to load a new image is free to prevent overwriting a
1653previously loaded image. For this mechanism to work, the platform must specify
1654the memory available in the system as regions, where each region consists of
1655base address, total size and the free area within it (as defined in the
1656``meminfo_t`` structure). TF-A retrieves these memory regions by calling the
1657corresponding platform API:
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001658
1659- ``meminfo_t *bl1_plat_sec_mem_layout(void)``
1660- ``meminfo_t *bl2_plat_sec_mem_layout(void)``
1661- ``void bl2_plat_get_scp_bl2_meminfo(meminfo_t *scp_bl2_meminfo)``
1662- ``void bl2_plat_get_bl32_meminfo(meminfo_t *bl32_meminfo)``
1663- ``void bl2_plat_get_bl33_meminfo(meminfo_t *bl33_meminfo)``
1664
1665For example, in the case of BL1 loading BL2, ``bl1_plat_sec_mem_layout()`` will
1666return the region defined by the platform where BL1 intends to load BL2. The
1667``load_image()`` function will check that the memory where BL2 will be loaded is
1668within the specified region and marked as free.
1669
1670The actual number of regions and their base addresses and sizes is platform
1671specific. The platform may return the same region or define a different one for
1672each API. However, the overlap verification mechanism applies only to a single
1673region. Hence, it is the platform responsibility to guarantee that different
1674regions do not overlap, or that if they do, the overlapping images are not
1675accessed at the same time. This could be used, for example, to load temporary
1676images (e.g. certificates) or firmware images prior to being transfered to its
1677corresponding processor (e.g. the SCP BL2 image).
1678
1679To reduce fragmentation and simplify the tracking of free memory, all the free
1680memory within a region is always located in one single buffer defined by its
Dan Handley610e7e12018-03-01 18:44:00 +00001681base address and size. TF-A implements a top/bottom load approach:
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001682after a new image is loaded, it checks how much memory remains free above and
1683below the image. The smallest area is marked as unavailable, while the larger
1684area becomes the new free memory buffer. Platforms should take this behaviour
1685into account when defining the base address for each of the images. For example,
1686if an image is loaded near the middle of the region, small changes in image size
1687could cause a flip between a top load and a bottom load, which may result in an
1688unexpected memory layout.
1689
1690The following diagram is an example of an image loaded in the bottom part of
1691the memory region. The region is initially free (nothing has been loaded yet):
1692
1693::
1694
1695 Memory region
1696 +----------+
1697 | |
1698 | | <<<<<<<<<<<<< Free
1699 | |
1700 |----------| +------------+
1701 | image | <<<<<<<<<<<<< | image |
1702 |----------| +------------+
1703 | xxxxxxxx | <<<<<<<<<<<<< Marked as unavailable
1704 +----------+
1705
1706And the following diagram is an example of an image loaded in the top part:
1707
1708::
1709
1710 Memory region
1711 +----------+
1712 | xxxxxxxx | <<<<<<<<<<<<< Marked as unavailable
1713 |----------| +------------+
1714 | image | <<<<<<<<<<<<< | image |
1715 |----------| +------------+
1716 | |
1717 | | <<<<<<<<<<<<< Free
1718 | |
1719 +----------+
1720
Dan Handley610e7e12018-03-01 18:44:00 +00001721When LOAD\_IMAGE\_V2 is enabled, TF-A does not provide any mechanism to verify
1722at boot time that the memory to load a new image is free to prevent overwriting
1723a previously loaded image. The platform must specify the memory available in
1724the system for all the relevant BL images to be loaded.
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001725
1726For example, in the case of BL1 loading BL2, ``bl1_plat_sec_mem_layout()`` will
1727return the region defined by the platform where BL1 intends to load BL2. The
1728``load_image()`` function performs bounds check for the image size based on the
1729base and maximum image size provided by the platforms. Platforms must take
1730this behaviour into account when defining the base/size for each of the images.
1731
Dan Handley610e7e12018-03-01 18:44:00 +00001732Memory layout on Arm development platforms
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001733^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1734
Dan Handley610e7e12018-03-01 18:44:00 +00001735The following list describes the memory layout on the Arm development platforms:
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001736
1737- A 4KB page of shared memory is used for communication between Trusted
1738 Firmware and the platform's power controller. This is located at the base of
1739 Trusted SRAM. The amount of Trusted SRAM available to load the bootloader
1740 images is reduced by the size of the shared memory.
1741
1742 The shared memory is used to store the CPUs' entrypoint mailbox. On Juno,
1743 this is also used for the MHU payload when passing messages to and from the
1744 SCP.
1745
1746- On FVP, BL1 is originally sitting in the Trusted ROM at address ``0x0``. On
1747 Juno, BL1 resides in flash memory at address ``0x0BEC0000``. BL1 read-write
1748 data are relocated to the top of Trusted SRAM at runtime.
1749
1750- EL3 Runtime Software, BL31 for AArch64 and BL32 for AArch32 (e.g. SP\_MIN),
1751 is loaded at the top of the Trusted SRAM, such that its NOBITS sections will
1752 overwrite BL1 R/W data. This implies that BL1 global variables remain valid
1753 only until execution reaches the EL3 Runtime Software entry point during a
1754 cold boot.
1755
1756- BL2 is loaded below EL3 Runtime Software.
1757
1758- On Juno, SCP\_BL2 is loaded temporarily into the EL3 Runtime Software memory
1759 region and transfered to the SCP before being overwritten by EL3 Runtime
1760 Software.
1761
1762- BL32 (for AArch64) can be loaded in one of the following locations:
1763
1764 - Trusted SRAM
1765 - Trusted DRAM (FVP only)
1766 - Secure region of DRAM (top 16MB of DRAM configured by the TrustZone
1767 controller)
1768
1769 When BL32 (for AArch64) is loaded into Trusted SRAM, its NOBITS sections
1770 are allowed to overlay BL2. This memory layout is designed to give the
1771 BL32 image as much memory as possible when it is loaded into Trusted SRAM.
1772
1773When LOAD\_IMAGE\_V2 is disabled the memory regions for the overlap detection
1774mechanism at boot time are defined as follows (shown per API):
1775
1776- ``meminfo_t *bl1_plat_sec_mem_layout(void)``
1777
1778 This region corresponds to the whole Trusted SRAM except for the shared
1779 memory at the base. This region is initially free. At boot time, BL1 will
1780 mark the BL1(rw) section within this region as occupied. The BL1(rw) section
1781 is placed at the top of Trusted SRAM.
1782
1783- ``meminfo_t *bl2_plat_sec_mem_layout(void)``
1784
1785 This region corresponds to the whole Trusted SRAM as defined by
1786 ``bl1_plat_sec_mem_layout()``, but with the BL1(rw) section marked as
1787 occupied. This memory region is used to check that BL2 and BL31 do not
1788 overlap with each other. BL2\_BASE and BL1\_RW\_BASE are carefully chosen so
1789 that the memory for BL31 is top loaded above BL2.
1790
1791- ``void bl2_plat_get_scp_bl2_meminfo(meminfo_t *scp_bl2_meminfo)``
1792
1793 This region is an exact copy of the region defined by
1794 ``bl2_plat_sec_mem_layout()``. Being a disconnected copy means that all the
Dan Handley610e7e12018-03-01 18:44:00 +00001795 changes made to this region by the TF-A will not be propagated. This
1796 approach is valid because the SCP BL2 image is loaded temporarily while it
1797 is being transferred to the SCP, so this memory is reused afterwards.
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001798
1799- ``void bl2_plat_get_bl32_meminfo(meminfo_t *bl32_meminfo)``
1800
Dan Handley610e7e12018-03-01 18:44:00 +00001801 This region depends on the location of the BL32 image. Currently, Arm
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001802 platforms support three different locations (detailed below): Trusted SRAM,
1803 Trusted DRAM and the TZC-Secured DRAM.
1804
1805- ``void bl2_plat_get_bl33_meminfo(meminfo_t *bl33_meminfo)``
1806
1807 This region corresponds to the Non-Secure DDR-DRAM, excluding the
1808 TZC-Secured area.
1809
1810The location of the BL32 image will result in different memory maps. This is
1811illustrated for both FVP and Juno in the following diagrams, using the TSP as
1812an example.
1813
1814Note: Loading the BL32 image in TZC secured DRAM doesn't change the memory
1815layout of the other images in Trusted SRAM.
1816
1817**FVP with TSP in Trusted SRAM (default option):**
1818(These diagrams only cover the AArch64 case)
1819
1820::
1821
1822 Trusted SRAM
1823 0x04040000 +----------+ loaded by BL2 ------------------
1824 | BL1 (rw) | <<<<<<<<<<<<< | BL31 NOBITS |
1825 |----------| <<<<<<<<<<<<< |----------------|
1826 | | <<<<<<<<<<<<< | BL31 PROGBITS |
1827 |----------| ------------------
1828 | BL2 | <<<<<<<<<<<<< | BL32 NOBITS |
1829 |----------| <<<<<<<<<<<<< |----------------|
1830 | | <<<<<<<<<<<<< | BL32 PROGBITS |
1831 0x04001000 +----------+ ------------------
1832 | Shared |
1833 0x04000000 +----------+
1834
1835 Trusted ROM
1836 0x04000000 +----------+
1837 | BL1 (ro) |
1838 0x00000000 +----------+
1839
Soby Mathewb1bf0442018-02-16 14:52:52 +00001840**FVP with TSP in Trusted DRAM with TB_FW_CONFIG and HW_CONFIG :**
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001841
1842::
1843
Soby Mathewb1bf0442018-02-16 14:52:52 +00001844 DRAM
1845 0xffffffff +--------------+
1846 : :
1847 |--------------|
1848 | HW_CONFIG |
1849 0x83000000 |--------------| (non-secure)
1850 | |
1851 0x80000000 +--------------+
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001852
Soby Mathewb1bf0442018-02-16 14:52:52 +00001853 Trusted DRAM
1854 0x08000000 +--------------+
1855 | BL32 |
1856 0x06000000 +--------------+
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001857
Soby Mathewb1bf0442018-02-16 14:52:52 +00001858 Trusted SRAM
1859 0x04040000 +--------------+ loaded by BL2 ------------------
1860 | BL1 (rw) | <<<<<<<<<<<<< | BL31 NOBITS |
1861 |--------------| <<<<<<<<<<<<< |----------------|
1862 | | <<<<<<<<<<<<< | BL31 PROGBITS |
1863 |--------------| ------------------
1864 | BL2 |
1865 |--------------|
1866 | |
1867 |--------------|
1868 | TB_FW_CONFIG |
1869 |--------------|
1870 0x04001000 +--------------+
1871 | Shared |
1872 0x04000000 +--------------+
1873
1874 Trusted ROM
1875 0x04000000 +--------------+
1876 | BL1 (ro) |
1877 0x00000000 +--------------+
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001878
1879**FVP with TSP in TZC-Secured DRAM:**
1880
1881::
1882
1883 DRAM
1884 0xffffffff +----------+
Soby Mathewb1bf0442018-02-16 14:52:52 +00001885 | BL32 | (secure)
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001886 0xff000000 +----------+
1887 | |
1888 : : (non-secure)
1889 | |
1890 0x80000000 +----------+
1891
1892 Trusted SRAM
1893 0x04040000 +----------+ loaded by BL2 ------------------
1894 | BL1 (rw) | <<<<<<<<<<<<< | BL31 NOBITS |
1895 |----------| <<<<<<<<<<<<< |----------------|
1896 | | <<<<<<<<<<<<< | BL31 PROGBITS |
1897 |----------| ------------------
1898 | BL2 |
1899 |----------|
1900 | |
1901 0x04001000 +----------+
1902 | Shared |
1903 0x04000000 +----------+
1904
1905 Trusted ROM
1906 0x04000000 +----------+
1907 | BL1 (ro) |
1908 0x00000000 +----------+
1909
1910**Juno with BL32 in Trusted SRAM (default option):**
1911
1912::
1913
1914 Flash0
1915 0x0C000000 +----------+
1916 : :
1917 0x0BED0000 |----------|
1918 | BL1 (ro) |
1919 0x0BEC0000 |----------|
1920 : :
1921 0x08000000 +----------+ BL31 is loaded
1922 after SCP_BL2 has
1923 Trusted SRAM been sent to SCP
1924 0x04040000 +----------+ loaded by BL2 ------------------
1925 | BL1 (rw) | <<<<<<<<<<<<< | BL31 NOBITS |
1926 |----------| <<<<<<<<<<<<< |----------------|
1927 | SCP_BL2 | <<<<<<<<<<<<< | BL31 PROGBITS |
1928 |----------| ------------------
1929 | BL2 | <<<<<<<<<<<<< | BL32 NOBITS |
1930 |----------| <<<<<<<<<<<<< |----------------|
1931 | | <<<<<<<<<<<<< | BL32 PROGBITS |
1932 0x04001000 +----------+ ------------------
1933 | MHU |
1934 0x04000000 +----------+
1935
1936**Juno with BL32 in TZC-secured DRAM:**
1937
1938::
1939
1940 DRAM
1941 0xFFE00000 +----------+
Soby Mathewb1bf0442018-02-16 14:52:52 +00001942 | BL32 | (secure)
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001943 0xFF000000 |----------|
1944 | |
1945 : : (non-secure)
1946 | |
1947 0x80000000 +----------+
1948
1949 Flash0
1950 0x0C000000 +----------+
1951 : :
1952 0x0BED0000 |----------|
1953 | BL1 (ro) |
1954 0x0BEC0000 |----------|
1955 : :
1956 0x08000000 +----------+ BL31 is loaded
1957 after SCP_BL2 has
1958 Trusted SRAM been sent to SCP
1959 0x04040000 +----------+ loaded by BL2 ------------------
1960 | BL1 (rw) | <<<<<<<<<<<<< | BL31 NOBITS |
1961 |----------| <<<<<<<<<<<<< |----------------|
1962 | SCP_BL2 | <<<<<<<<<<<<< | BL31 PROGBITS |
1963 |----------| ------------------
1964 | BL2 |
1965 |----------|
1966 | |
1967 0x04001000 +----------+
1968 | MHU |
1969 0x04000000 +----------+
1970
1971Firmware Image Package (FIP)
1972----------------------------
1973
1974Using a Firmware Image Package (FIP) allows for packing bootloader images (and
Dan Handley610e7e12018-03-01 18:44:00 +00001975potentially other payloads) into a single archive that can be loaded by TF-A
1976from non-volatile platform storage. A driver to load images from a FIP has
1977been added to the storage layer and allows a package to be read from supported
1978platform storage. A tool to create Firmware Image Packages is also provided
1979and described below.
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001980
1981Firmware Image Package layout
1982~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1983
1984The FIP layout consists of a table of contents (ToC) followed by payload data.
1985The ToC itself has a header followed by one or more table entries. The ToC is
Jett Zhou75566102017-11-24 16:03:58 +08001986terminated by an end marker entry, and since the size of the ToC is 0 bytes,
1987the offset equals the total size of the FIP file. All ToC entries describe some
1988payload data that has been appended to the end of the binary package. With the
1989information provided in the ToC entry the corresponding payload data can be
1990retrieved.
Douglas Raillardd7c21b72017-06-28 15:23:03 +01001991
1992::
1993
1994 ------------------
1995 | ToC Header |
1996 |----------------|
1997 | ToC Entry 0 |
1998 |----------------|
1999 | ToC Entry 1 |
2000 |----------------|
2001 | ToC End Marker |
2002 |----------------|
2003 | |
2004 | Data 0 |
2005 | |
2006 |----------------|
2007 | |
2008 | Data 1 |
2009 | |
2010 ------------------
2011
2012The ToC header and entry formats are described in the header file
2013``include/tools_share/firmware_image_package.h``. This file is used by both the
Dan Handley610e7e12018-03-01 18:44:00 +00002014tool and TF-A.
Douglas Raillardd7c21b72017-06-28 15:23:03 +01002015
2016The ToC header has the following fields:
2017
2018::
2019
2020 `name`: The name of the ToC. This is currently used to validate the header.
2021 `serial_number`: A non-zero number provided by the creation tool
2022 `flags`: Flags associated with this data.
2023 Bits 0-31: Reserved
2024 Bits 32-47: Platform defined
2025 Bits 48-63: Reserved
2026
2027A ToC entry has the following fields:
2028
2029::
2030
2031 `uuid`: All files are referred to by a pre-defined Universally Unique
2032 IDentifier [UUID] . The UUIDs are defined in
2033 `include/tools_share/firmware_image_package.h`. The platform translates
2034 the requested image name into the corresponding UUID when accessing the
2035 package.
2036 `offset_address`: The offset address at which the corresponding payload data
2037 can be found. The offset is calculated from the ToC base address.
2038 `size`: The size of the corresponding payload data in bytes.
Etienne Carriere7421bf12017-08-23 15:43:33 +02002039 `flags`: Flags associated with this entry. None are yet defined.
Douglas Raillardd7c21b72017-06-28 15:23:03 +01002040
2041Firmware Image Package creation tool
2042~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2043
Dan Handley610e7e12018-03-01 18:44:00 +00002044The FIP creation tool can be used to pack specified images into a binary
2045package that can be loaded by TF-A from platform storage. The tool currently
2046only supports packing bootloader images. Additional image definitions can be
2047added to the tool as required.
Douglas Raillardd7c21b72017-06-28 15:23:03 +01002048
2049The tool can be found in ``tools/fiptool``.
2050
2051Loading from a Firmware Image Package (FIP)
2052~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2053
2054The Firmware Image Package (FIP) driver can load images from a binary package on
Dan Handley610e7e12018-03-01 18:44:00 +00002055non-volatile platform storage. For the Arm development platforms, this is
Douglas Raillardd7c21b72017-06-28 15:23:03 +01002056currently NOR FLASH.
2057
2058Bootloader images are loaded according to the platform policy as specified by
Dan Handley610e7e12018-03-01 18:44:00 +00002059the function ``plat_get_image_source()``. For the Arm development platforms, this
Douglas Raillardd7c21b72017-06-28 15:23:03 +01002060means the platform will attempt to load images from a Firmware Image Package
2061located at the start of NOR FLASH0.
2062
Dan Handley610e7e12018-03-01 18:44:00 +00002063The Arm development platforms' policy is to only allow loading of a known set of
Douglas Raillardd7c21b72017-06-28 15:23:03 +01002064images. The platform policy can be modified to allow additional images.
2065
Dan Handley610e7e12018-03-01 18:44:00 +00002066Use of coherent memory in TF-A
2067------------------------------
Douglas Raillardd7c21b72017-06-28 15:23:03 +01002068
2069There might be loss of coherency when physical memory with mismatched
2070shareability, cacheability and memory attributes is accessed by multiple CPUs
Dan Handley610e7e12018-03-01 18:44:00 +00002071(refer to section B2.9 of `Arm ARM`_ for more details). This possibility occurs
2072in TF-A during power up/down sequences when coherency, MMU and caches are
2073turned on/off incrementally.
Douglas Raillardd7c21b72017-06-28 15:23:03 +01002074
Dan Handley610e7e12018-03-01 18:44:00 +00002075TF-A defines coherent memory as a region of memory with Device nGnRE attributes
2076in the translation tables. The translation granule size in TF-A is 4KB. This
2077is the smallest possible size of the coherent memory region.
Douglas Raillardd7c21b72017-06-28 15:23:03 +01002078
2079By default, all data structures which are susceptible to accesses with
2080mismatched attributes from various CPUs are allocated in a coherent memory
2081region (refer to section 2.1 of `Porting Guide`_). The coherent memory region
2082accesses are Outer Shareable, non-cacheable and they can be accessed
2083with the Device nGnRE attributes when the MMU is turned on. Hence, at the
Dan Handley610e7e12018-03-01 18:44:00 +00002084expense of at least an extra page of memory, TF-A is able to work around
2085coherency issues due to mismatched memory attributes.
Douglas Raillardd7c21b72017-06-28 15:23:03 +01002086
2087The alternative to the above approach is to allocate the susceptible data
2088structures in Normal WriteBack WriteAllocate Inner shareable memory. This
2089approach requires the data structures to be designed so that it is possible to
2090work around the issue of mismatched memory attributes by performing software
2091cache maintenance on them.
2092
Dan Handley610e7e12018-03-01 18:44:00 +00002093Disabling the use of coherent memory in TF-A
2094~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Douglas Raillardd7c21b72017-06-28 15:23:03 +01002095
2096It might be desirable to avoid the cost of allocating coherent memory on
Dan Handley610e7e12018-03-01 18:44:00 +00002097platforms which are memory constrained. TF-A enables inclusion of coherent
2098memory in firmware images through the build flag ``USE_COHERENT_MEM``.
Douglas Raillardd7c21b72017-06-28 15:23:03 +01002099This flag is enabled by default. It can be disabled to choose the second
2100approach described above.
2101
2102The below sections analyze the data structures allocated in the coherent memory
2103region and the changes required to allocate them in normal memory.
2104
2105Coherent memory usage in PSCI implementation
2106~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2107
2108The ``psci_non_cpu_pd_nodes`` data structure stores the platform's power domain
2109tree information for state management of power domains. By default, this data
Dan Handley610e7e12018-03-01 18:44:00 +00002110structure is allocated in the coherent memory region in TF-A because it can be
2111accessed by multple CPUs, either with caches enabled or disabled.
Douglas Raillardd7c21b72017-06-28 15:23:03 +01002112
2113.. code:: c
2114
2115 typedef struct non_cpu_pwr_domain_node {
2116 /*
2117 * Index of the first CPU power domain node level 0 which has this node
2118 * as its parent.
2119 */
2120 unsigned int cpu_start_idx;
2121
2122 /*
2123 * Number of CPU power domains which are siblings of the domain indexed
2124 * by 'cpu_start_idx' i.e. all the domains in the range 'cpu_start_idx
2125 * -> cpu_start_idx + ncpus' have this node as their parent.
2126 */
2127 unsigned int ncpus;
2128
2129 /*
2130 * Index of the parent power domain node.
2131 * TODO: Figure out whether to whether using pointer is more efficient.
2132 */
2133 unsigned int parent_node;
2134
2135 plat_local_state_t local_state;
2136
2137 unsigned char level;
2138
2139 /* For indexing the psci_lock array*/
2140 unsigned char lock_index;
2141 } non_cpu_pd_node_t;
2142
2143In order to move this data structure to normal memory, the use of each of its
2144fields must be analyzed. Fields like ``cpu_start_idx``, ``ncpus``, ``parent_node``
2145``level`` and ``lock_index`` are only written once during cold boot. Hence removing
2146them from coherent memory involves only doing a clean and invalidate of the
2147cache lines after these fields are written.
2148
2149The field ``local_state`` can be concurrently accessed by multiple CPUs in
2150different cache states. A Lamport's Bakery lock ``psci_locks`` is used to ensure
2151mutual exlusion to this field and a clean and invalidate is needed after it
2152is written.
2153
2154Bakery lock data
2155~~~~~~~~~~~~~~~~
2156
2157The bakery lock data structure ``bakery_lock_t`` is allocated in coherent memory
2158and is accessed by multiple CPUs with mismatched attributes. ``bakery_lock_t`` is
2159defined as follows:
2160
2161.. code:: c
2162
2163 typedef struct bakery_lock {
2164 /*
2165 * The lock_data is a bit-field of 2 members:
2166 * Bit[0] : choosing. This field is set when the CPU is
2167 * choosing its bakery number.
2168 * Bits[1 - 15] : number. This is the bakery number allocated.
2169 */
2170 volatile uint16_t lock_data[BAKERY_LOCK_MAX_CPUS];
2171 } bakery_lock_t;
2172
2173It is a characteristic of Lamport's Bakery algorithm that the volatile per-CPU
2174fields can be read by all CPUs but only written to by the owning CPU.
2175
2176Depending upon the data cache line size, the per-CPU fields of the
2177``bakery_lock_t`` structure for multiple CPUs may exist on a single cache line.
2178These per-CPU fields can be read and written during lock contention by multiple
2179CPUs with mismatched memory attributes. Since these fields are a part of the
2180lock implementation, they do not have access to any other locking primitive to
2181safeguard against the resulting coherency issues. As a result, simple software
2182cache maintenance is not enough to allocate them in coherent memory. Consider
2183the following example.
2184
2185CPU0 updates its per-CPU field with data cache enabled. This write updates a
2186local cache line which contains a copy of the fields for other CPUs as well. Now
2187CPU1 updates its per-CPU field of the ``bakery_lock_t`` structure with data cache
2188disabled. CPU1 then issues a DCIVAC operation to invalidate any stale copies of
2189its field in any other cache line in the system. This operation will invalidate
2190the update made by CPU0 as well.
2191
2192To use bakery locks when ``USE_COHERENT_MEM`` is disabled, the lock data structure
2193has been redesigned. The changes utilise the characteristic of Lamport's Bakery
2194algorithm mentioned earlier. The bakery\_lock structure only allocates the memory
2195for a single CPU. The macro ``DEFINE_BAKERY_LOCK`` allocates all the bakery locks
2196needed for a CPU into a section ``bakery_lock``. The linker allocates the memory
2197for other cores by using the total size allocated for the bakery\_lock section
2198and multiplying it with (PLATFORM\_CORE\_COUNT - 1). This enables software to
2199perform software cache maintenance on the lock data structure without running
2200into coherency issues associated with mismatched attributes.
2201
2202The bakery lock data structure ``bakery_info_t`` is defined for use when
2203``USE_COHERENT_MEM`` is disabled as follows:
2204
2205.. code:: c
2206
2207 typedef struct bakery_info {
2208 /*
2209 * The lock_data is a bit-field of 2 members:
2210 * Bit[0] : choosing. This field is set when the CPU is
2211 * choosing its bakery number.
2212 * Bits[1 - 15] : number. This is the bakery number allocated.
2213 */
2214 volatile uint16_t lock_data;
2215 } bakery_info_t;
2216
2217The ``bakery_info_t`` represents a single per-CPU field of one lock and
2218the combination of corresponding ``bakery_info_t`` structures for all CPUs in the
2219system represents the complete bakery lock. The view in memory for a system
2220with n bakery locks are:
2221
2222::
2223
2224 bakery_lock section start
2225 |----------------|
2226 | `bakery_info_t`| <-- Lock_0 per-CPU field
2227 | Lock_0 | for CPU0
2228 |----------------|
2229 | `bakery_info_t`| <-- Lock_1 per-CPU field
2230 | Lock_1 | for CPU0
2231 |----------------|
2232 | .... |
2233 |----------------|
2234 | `bakery_info_t`| <-- Lock_N per-CPU field
2235 | Lock_N | for CPU0
2236 ------------------
2237 | XXXXX |
2238 | Padding to |
2239 | next Cache WB | <--- Calculate PERCPU_BAKERY_LOCK_SIZE, allocate
2240 | Granule | continuous memory for remaining CPUs.
2241 ------------------
2242 | `bakery_info_t`| <-- Lock_0 per-CPU field
2243 | Lock_0 | for CPU1
2244 |----------------|
2245 | `bakery_info_t`| <-- Lock_1 per-CPU field
2246 | Lock_1 | for CPU1
2247 |----------------|
2248 | .... |
2249 |----------------|
2250 | `bakery_info_t`| <-- Lock_N per-CPU field
2251 | Lock_N | for CPU1
2252 ------------------
2253 | XXXXX |
2254 | Padding to |
2255 | next Cache WB |
2256 | Granule |
2257 ------------------
2258
2259Consider a system of 2 CPUs with 'N' bakery locks as shown above. For an
2260operation on Lock\_N, the corresponding ``bakery_info_t`` in both CPU0 and CPU1
2261``bakery_lock`` section need to be fetched and appropriate cache operations need
2262to be performed for each access.
2263
Dan Handley610e7e12018-03-01 18:44:00 +00002264On Arm Platforms, bakery locks are used in psci (``psci_locks``) and power controller
Douglas Raillardd7c21b72017-06-28 15:23:03 +01002265driver (``arm_lock``).
2266
2267Non Functional Impact of removing coherent memory
2268~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2269
2270Removal of the coherent memory region leads to the additional software overhead
2271of performing cache maintenance for the affected data structures. However, since
2272the memory where the data structures are allocated is cacheable, the overhead is
2273mostly mitigated by an increase in performance.
2274
2275There is however a performance impact for bakery locks, due to:
2276
2277- Additional cache maintenance operations, and
2278- Multiple cache line reads for each lock operation, since the bakery locks
2279 for each CPU are distributed across different cache lines.
2280
2281The implementation has been optimized to minimize this additional overhead.
2282Measurements indicate that when bakery locks are allocated in Normal memory, the
2283minimum latency of acquiring a lock is on an average 3-4 micro seconds whereas
2284in Device memory the same is 2 micro seconds. The measurements were done on the
Dan Handley610e7e12018-03-01 18:44:00 +00002285Juno Arm development platform.
Douglas Raillardd7c21b72017-06-28 15:23:03 +01002286
2287As mentioned earlier, almost a page of memory can be saved by disabling
2288``USE_COHERENT_MEM``. Each platform needs to consider these trade-offs to decide
2289whether coherent memory should be used. If a platform disables
2290``USE_COHERENT_MEM`` and needs to use bakery locks in the porting layer, it can
2291optionally define macro ``PLAT_PERCPU_BAKERY_LOCK_SIZE`` (see the
2292`Porting Guide`_). Refer to the reference platform code for examples.
2293
2294Isolating code and read-only data on separate memory pages
2295----------------------------------------------------------
2296
Dan Handley610e7e12018-03-01 18:44:00 +00002297In the Armv8-A VMSA, translation table entries include fields that define the
Douglas Raillardd7c21b72017-06-28 15:23:03 +01002298properties of the target memory region, such as its access permissions. The
2299smallest unit of memory that can be addressed by a translation table entry is
2300a memory page. Therefore, if software needs to set different permissions on two
2301memory regions then it needs to map them using different memory pages.
2302
2303The default memory layout for each BL image is as follows:
2304
2305::
2306
2307 | ... |
2308 +-------------------+
2309 | Read-write data |
2310 +-------------------+ Page boundary
2311 | <Padding> |
2312 +-------------------+
2313 | Exception vectors |
2314 +-------------------+ 2 KB boundary
2315 | <Padding> |
2316 +-------------------+
2317 | Read-only data |
2318 +-------------------+
2319 | Code |
2320 +-------------------+ BLx_BASE
2321
2322Note: The 2KB alignment for the exception vectors is an architectural
2323requirement.
2324
2325The read-write data start on a new memory page so that they can be mapped with
2326read-write permissions, whereas the code and read-only data below are configured
2327as read-only.
2328
2329However, the read-only data are not aligned on a page boundary. They are
2330contiguous to the code. Therefore, the end of the code section and the beginning
2331of the read-only data one might share a memory page. This forces both to be
2332mapped with the same memory attributes. As the code needs to be executable, this
2333means that the read-only data stored on the same memory page as the code are
2334executable as well. This could potentially be exploited as part of a security
2335attack.
2336
2337TF provides the build flag ``SEPARATE_CODE_AND_RODATA`` to isolate the code and
2338read-only data on separate memory pages. This in turn allows independent control
2339of the access permissions for the code and read-only data. In this case,
2340platform code gets a finer-grained view of the image layout and can
2341appropriately map the code region as executable and the read-only data as
2342execute-never.
2343
2344This has an impact on memory footprint, as padding bytes need to be introduced
2345between the code and read-only data to ensure the segragation of the two. To
2346limit the memory cost, this flag also changes the memory layout such that the
2347code and exception vectors are now contiguous, like so:
2348
2349::
2350
2351 | ... |
2352 +-------------------+
2353 | Read-write data |
2354 +-------------------+ Page boundary
2355 | <Padding> |
2356 +-------------------+
2357 | Read-only data |
2358 +-------------------+ Page boundary
2359 | <Padding> |
2360 +-------------------+
2361 | Exception vectors |
2362 +-------------------+ 2 KB boundary
2363 | <Padding> |
2364 +-------------------+
2365 | Code |
2366 +-------------------+ BLx_BASE
2367
2368With this more condensed memory layout, the separation of read-only data will
2369add zero or one page to the memory footprint of each BL image. Each platform
2370should consider the trade-off between memory footprint and security.
2371
Dan Handley610e7e12018-03-01 18:44:00 +00002372This build flag is disabled by default, minimising memory footprint. On Arm
Douglas Raillardd7c21b72017-06-28 15:23:03 +01002373platforms, it is enabled.
2374
Jeenu Viswambharane3f22002017-09-22 08:32:10 +01002375Publish and Subscribe Framework
2376-------------------------------
2377
2378The Publish and Subscribe Framework allows EL3 components to define and publish
2379events, to which other EL3 components can subscribe.
2380
2381The following macros are provided by the framework:
2382
2383- ``REGISTER_PUBSUB_EVENT(event)``: Defines an event, and takes one argument,
2384 the event name, which must be a valid C identifier. All calls to
2385 ``REGISTER_PUBSUB_EVENT`` macro must be placed in the file
2386 ``pubsub_events.h``.
2387
2388- ``PUBLISH_EVENT_ARG(event, arg)``: Publishes a defined event, by iterating
2389 subscribed handlers and calling them in turn. The handlers will be passed the
2390 parameter ``arg``. The expected use-case is to broadcast an event.
2391
2392- ``PUBLISH_EVENT(event)``: Like ``PUBLISH_EVENT_ARG``, except that the value
2393 ``NULL`` is passed to subscribed handlers.
2394
2395- ``SUBSCRIBE_TO_EVENT(event, handler)``: Registers the ``handler`` to
2396 subscribe to ``event``. The handler will be executed whenever the ``event``
2397 is published.
2398
2399- ``for_each_subscriber(event, subscriber)``: Iterates through all handlers
2400 subscribed for ``event``. ``subscriber`` must be a local variable of type
2401 ``pubsub_cb_t *``, and will point to each subscribed handler in turn during
2402 iteration. This macro can be used for those patterns that none of the
2403 ``PUBLISH_EVENT_*()`` macros cover.
2404
2405Publishing an event that wasn't defined using ``REGISTER_PUBSUB_EVENT`` will
2406result in build error. Subscribing to an undefined event however won't.
2407
2408Subscribed handlers must be of type ``pubsub_cb_t``, with following function
2409signature:
2410
2411::
2412
2413 typedef void* (*pubsub_cb_t)(const void *arg);
2414
2415There may be arbitrary number of handlers registered to the same event. The
2416order in which subscribed handlers are notified when that event is published is
2417not defined. Subscribed handlers may be executed in any order; handlers should
2418not assume any relative ordering amongst them.
2419
2420Publishing an event on a PE will result in subscribed handlers executing on that
2421PE only; it won't cause handlers to execute on a different PE.
2422
2423Note that publishing an event on a PE blocks until all the subscribed handlers
2424finish executing on the PE.
2425
Dan Handley610e7e12018-03-01 18:44:00 +00002426TF-A generic code publishes and subscribes to some events within. Platform
2427ports are discouraged from subscribing to them. These events may be withdrawn,
2428renamed, or have their semantics altered in the future. Platforms may however
2429register, publish, and subscribe to platform-specific events.
Dimitris Papastamosa7921b92017-10-13 15:27:58 +01002430
Jeenu Viswambharane3f22002017-09-22 08:32:10 +01002431Publish and Subscribe Example
2432~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2433
2434A publisher that wants to publish event ``foo`` would:
2435
2436- Define the event ``foo`` in the ``pubsub_events.h``.
2437
2438 ::
2439
2440 REGISTER_PUBSUB_EVENT(foo);
2441
2442- Depending on the nature of event, use one of ``PUBLISH_EVENT_*()`` macros to
2443 publish the event at the appropriate path and time of execution.
2444
2445A subscriber that wants to subscribe to event ``foo`` published above would
2446implement:
2447
2448::
2449
2450 void *foo_handler(const void *arg)
2451 {
2452 void *result;
2453
2454 /* Do handling ... */
2455
2456 return result;
2457 }
2458
2459 SUBSCRIBE_TO_EVENT(foo, foo_handler);
2460
Douglas Raillardd7c21b72017-06-28 15:23:03 +01002461Performance Measurement Framework
2462---------------------------------
2463
2464The Performance Measurement Framework (PMF) facilitates collection of
Dan Handley610e7e12018-03-01 18:44:00 +00002465timestamps by registered services and provides interfaces to retrieve them
2466from within TF-A. A platform can choose to expose appropriate SMCs to
2467retrieve these collected timestamps.
Douglas Raillardd7c21b72017-06-28 15:23:03 +01002468
2469By default, the global physical counter is used for the timestamp
2470value and is read via ``CNTPCT_EL0``. The framework allows to retrieve
2471timestamps captured by other CPUs.
2472
2473Timestamp identifier format
2474~~~~~~~~~~~~~~~~~~~~~~~~~~~
2475
2476A PMF timestamp is uniquely identified across the system via the
2477timestamp ID or ``tid``. The ``tid`` is composed as follows:
2478
2479::
2480
2481 Bits 0-7: The local timestamp identifier.
2482 Bits 8-9: Reserved.
2483 Bits 10-15: The service identifier.
2484 Bits 16-31: Reserved.
2485
2486#. The service identifier. Each PMF service is identified by a
2487 service name and a service identifier. Both the service name and
2488 identifier are unique within the system as a whole.
2489
2490#. The local timestamp identifier. This identifier is unique within a given
2491 service.
2492
2493Registering a PMF service
2494~~~~~~~~~~~~~~~~~~~~~~~~~
2495
2496To register a PMF service, the ``PMF_REGISTER_SERVICE()`` macro from ``pmf.h``
2497is used. The arguments required are the service name, the service ID,
2498the total number of local timestamps to be captured and a set of flags.
2499
2500The ``flags`` field can be specified as a bitwise-OR of the following values:
2501
2502::
2503
2504 PMF_STORE_ENABLE: The timestamp is stored in memory for later retrieval.
2505 PMF_DUMP_ENABLE: The timestamp is dumped on the serial console.
2506
2507The ``PMF_REGISTER_SERVICE()`` reserves memory to store captured
2508timestamps in a PMF specific linker section at build time.
2509Additionally, it defines necessary functions to capture and
2510retrieve a particular timestamp for the given service at runtime.
2511
Dan Handley610e7e12018-03-01 18:44:00 +00002512The macro ``PMF_REGISTER_SERVICE()`` only enables capturing PMF timestamps
2513from within TF-A. In order to retrieve timestamps from outside of TF-A, the
Douglas Raillardd7c21b72017-06-28 15:23:03 +01002514``PMF_REGISTER_SERVICE_SMC()`` macro must be used instead. This macro
2515accepts the same set of arguments as the ``PMF_REGISTER_SERVICE()``
2516macro but additionally supports retrieving timestamps using SMCs.
2517
2518Capturing a timestamp
2519~~~~~~~~~~~~~~~~~~~~~
2520
2521PMF timestamps are stored in a per-service timestamp region. On a
2522system with multiple CPUs, each timestamp is captured and stored
2523in a per-CPU cache line aligned memory region.
2524
2525Having registered the service, the ``PMF_CAPTURE_TIMESTAMP()`` macro can be
2526used to capture a timestamp at the location where it is used. The macro
2527takes the service name, a local timestamp identifier and a flag as arguments.
2528
2529The ``flags`` field argument can be zero, or ``PMF_CACHE_MAINT`` which
2530instructs PMF to do cache maintenance following the capture. Cache
2531maintenance is required if any of the service's timestamps are captured
2532with data cache disabled.
2533
2534To capture a timestamp in assembly code, the caller should use
2535``pmf_calc_timestamp_addr`` macro (defined in ``pmf_asm_macros.S``) to
2536calculate the address of where the timestamp would be stored. The
2537caller should then read ``CNTPCT_EL0`` register to obtain the timestamp
2538and store it at the determined address for later retrieval.
2539
2540Retrieving a timestamp
2541~~~~~~~~~~~~~~~~~~~~~~
2542
Dan Handley610e7e12018-03-01 18:44:00 +00002543From within TF-A, timestamps for individual CPUs can be retrieved using either
2544``PMF_GET_TIMESTAMP_BY_MPIDR()`` or ``PMF_GET_TIMESTAMP_BY_INDEX()`` macros.
2545These macros accept the CPU's MPIDR value, or its ordinal position
2546respectively.
Douglas Raillardd7c21b72017-06-28 15:23:03 +01002547
Dan Handley610e7e12018-03-01 18:44:00 +00002548From outside TF-A, timestamps for individual CPUs can be retrieved by calling
2549into ``pmf_smc_handler()``.
Douglas Raillardd7c21b72017-06-28 15:23:03 +01002550
2551.. code:: c
2552
2553 Interface : pmf_smc_handler()
2554 Argument : unsigned int smc_fid, u_register_t x1,
2555 u_register_t x2, u_register_t x3,
2556 u_register_t x4, void *cookie,
2557 void *handle, u_register_t flags
2558 Return : uintptr_t
2559
2560 smc_fid: Holds the SMC identifier which is either `PMF_SMC_GET_TIMESTAMP_32`
2561 when the caller of the SMC is running in AArch32 mode
2562 or `PMF_SMC_GET_TIMESTAMP_64` when the caller is running in AArch64 mode.
2563 x1: Timestamp identifier.
2564 x2: The `mpidr` of the CPU for which the timestamp has to be retrieved.
2565 This can be the `mpidr` of a different core to the one initiating
2566 the SMC. In that case, service specific cache maintenance may be
2567 required to ensure the updated copy of the timestamp is returned.
2568 x3: A flags value that is either 0 or `PMF_CACHE_MAINT`. If
2569 `PMF_CACHE_MAINT` is passed, then the PMF code will perform a
2570 cache invalidate before reading the timestamp. This ensures
2571 an updated copy is returned.
2572
2573The remaining arguments, ``x4``, ``cookie``, ``handle`` and ``flags`` are unused
2574in this implementation.
2575
2576PMF code structure
2577~~~~~~~~~~~~~~~~~~
2578
2579#. ``pmf_main.c`` consists of core functions that implement service registration,
2580 initialization, storing, dumping and retrieving timestamps.
2581
2582#. ``pmf_smc.c`` contains the SMC handling for registered PMF services.
2583
2584#. ``pmf.h`` contains the public interface to Performance Measurement Framework.
2585
2586#. ``pmf_asm_macros.S`` consists of macros to facilitate capturing timestamps in
2587 assembly code.
2588
2589#. ``pmf_helpers.h`` is an internal header used by ``pmf.h``.
2590
Dan Handley610e7e12018-03-01 18:44:00 +00002591Armv8-A Architecture Extensions
2592-------------------------------
Douglas Raillardd7c21b72017-06-28 15:23:03 +01002593
Dan Handley610e7e12018-03-01 18:44:00 +00002594TF-A makes use of Armv8-A Architecture Extensions where applicable. This
2595section lists the usage of Architecture Extensions, and build flags
2596controlling them.
Douglas Raillardd7c21b72017-06-28 15:23:03 +01002597
2598In general, and unless individually mentioned, the build options
2599``ARM_ARCH_MAJOR`` and ``ARM_ARCH_MINOR`` selects the Architecture Extension to
Dan Handley610e7e12018-03-01 18:44:00 +00002600target when building TF-A. Subsequent Arm Architecture Extensions are backward
2601compatible with previous versions.
Douglas Raillardd7c21b72017-06-28 15:23:03 +01002602
2603The build system only requires that ``ARM_ARCH_MAJOR`` and ``ARM_ARCH_MINOR`` have a
2604valid numeric value. These build options only control whether or not
Dan Handley610e7e12018-03-01 18:44:00 +00002605Architecture Extension-specific code is included in the build. Otherwise, TF-A
2606targets the base Armv8.0-A architecture; i.e. as if ``ARM_ARCH_MAJOR`` == 8
2607and ``ARM_ARCH_MINOR`` == 0, which are also their respective default values.
Douglas Raillardd7c21b72017-06-28 15:23:03 +01002608
2609See also the *Summary of build options* in `User Guide`_.
2610
2611For details on the Architecture Extension and available features, please refer
2612to the respective Architecture Extension Supplement.
2613
Dan Handley610e7e12018-03-01 18:44:00 +00002614Armv8.1-A
2615~~~~~~~~~
Douglas Raillardd7c21b72017-06-28 15:23:03 +01002616
2617This Architecture Extension is targeted when ``ARM_ARCH_MAJOR`` >= 8, or when
2618``ARM_ARCH_MAJOR`` == 8 and ``ARM_ARCH_MINOR`` >= 1.
2619
2620- The Compare and Swap instruction is used to implement spinlocks. Otherwise,
2621 the load-/store-exclusive instruction pair is used.
2622
Dan Handley610e7e12018-03-01 18:44:00 +00002623Armv8.2-A
2624~~~~~~~~~
Isla Mitchellc4a1a072017-08-07 11:20:13 +01002625
2626This Architecture Extension is targeted when ``ARM_ARCH_MAJOR`` == 8 and
2627``ARM_ARCH_MINOR`` >= 2.
2628
2629- The Common not Private (CnP) bit is enabled to indicate that multiple
Sandrine Bailleuxfee6e262018-01-29 14:48:15 +01002630 Processing Elements in the same Inner Shareable domain use the same
2631 translation table entries for a given stage of translation for a particular
2632 translation regime.
Isla Mitchellc4a1a072017-08-07 11:20:13 +01002633
Dan Handley610e7e12018-03-01 18:44:00 +00002634Armv7-A
2635~~~~~~~
Etienne Carriere1374fcb2017-11-08 13:48:40 +01002636
2637This Architecture Extension is targeted when ``ARM_ARCH_MAJOR`` == 7.
2638
Dan Handley610e7e12018-03-01 18:44:00 +00002639There are several Armv7-A extensions available. Obviously the TrustZone
2640extension is mandatory to support the TF-A bootloader and runtime services.
Etienne Carriere1374fcb2017-11-08 13:48:40 +01002641
Dan Handley610e7e12018-03-01 18:44:00 +00002642Platform implementing an Armv7-A system can to define from its target
Etienne Carriere1374fcb2017-11-08 13:48:40 +01002643Cortex-A architecture through ``ARM_CORTEX_A<X> = yes`` in their
2644``plaform.mk`` script. For example ``ARM_CORTEX_A15=yes`` for a
2645Cortex-A15 target.
2646
2647Platform can also set ``ARM_WITH_NEON=yes`` to enable neon support.
2648Note that using neon at runtime has constraints on non secure wolrd context.
Dan Handley610e7e12018-03-01 18:44:00 +00002649TF-A does not yet provide VFP context management.
Etienne Carriere1374fcb2017-11-08 13:48:40 +01002650
2651Directive ``ARM_CORTEX_A<x>`` and ``ARM_WITH_NEON`` are used to set
2652the toolchain target architecture directive.
2653
2654Platform may choose to not define straight the toolchain target architecture
2655directive by defining ``MARCH32_DIRECTIVE``.
2656I.e:
2657
2658::
2659
2660 MARCH32_DIRECTIVE := -mach=armv7-a
2661
Douglas Raillardd7c21b72017-06-28 15:23:03 +01002662Code Structure
2663--------------
2664
Dan Handley610e7e12018-03-01 18:44:00 +00002665TF-A code is logically divided between the three boot loader stages mentioned
2666in the previous sections. The code is also divided into the following
2667categories (present as directories in the source code):
Douglas Raillardd7c21b72017-06-28 15:23:03 +01002668
2669- **Platform specific.** Choice of architecture specific code depends upon
2670 the platform.
2671- **Common code.** This is platform and architecture agnostic code.
2672- **Library code.** This code comprises of functionality commonly used by all
2673 other code. The PSCI implementation and other EL3 runtime frameworks reside
2674 as Library components.
2675- **Stage specific.** Code specific to a boot stage.
2676- **Drivers.**
2677- **Services.** EL3 runtime services (eg: SPD). Specific SPD services
2678 reside in the ``services/spd`` directory (e.g. ``services/spd/tspd``).
2679
2680Each boot loader stage uses code from one or more of the above mentioned
2681categories. Based upon the above, the code layout looks like this:
2682
2683::
2684
2685 Directory Used by BL1? Used by BL2? Used by BL31?
2686 bl1 Yes No No
2687 bl2 No Yes No
2688 bl31 No No Yes
2689 plat Yes Yes Yes
2690 drivers Yes No Yes
2691 common Yes Yes Yes
2692 lib Yes Yes Yes
2693 services No No Yes
2694
2695The build system provides a non configurable build option IMAGE\_BLx for each
2696boot loader stage (where x = BL stage). e.g. for BL1 , IMAGE\_BL1 will be
Dan Handley610e7e12018-03-01 18:44:00 +00002697defined by the build system. This enables TF-A to compile certain code only
2698for specific boot loader stages
Douglas Raillardd7c21b72017-06-28 15:23:03 +01002699
2700All assembler files have the ``.S`` extension. The linker source files for each
2701boot stage have the extension ``.ld.S``. These are processed by GCC to create the
2702linker scripts which have the extension ``.ld``.
2703
2704FDTs provide a description of the hardware platform and are used by the Linux
2705kernel at boot time. These can be found in the ``fdts`` directory.
2706
2707References
2708----------
2709
Dan Handley610e7e12018-03-01 18:44:00 +00002710.. [#] Trusted Board Boot Requirements CLIENT PDD (Arm DEN0006C-1). Available
2711 under NDA through your Arm account representative.
Douglas Raillard30d7b362017-06-28 16:14:55 +01002712.. [#] `Power State Coordination Interface PDD`_
2713.. [#] `SMC Calling Convention PDD`_
Dan Handley610e7e12018-03-01 18:44:00 +00002714.. [#] `TF-A Interrupt Management Design guide`_.
Douglas Raillardd7c21b72017-06-28 15:23:03 +01002715
2716--------------
2717
Dan Handley610e7e12018-03-01 18:44:00 +00002718*Copyright (c) 2013-2018, Arm Limited and Contributors. All rights reserved.*
Douglas Raillardd7c21b72017-06-28 15:23:03 +01002719
2720.. _Reset Design: ./reset-design.rst
2721.. _Porting Guide: ./porting-guide.rst
2722.. _Firmware Update: ./firmware-update.rst
2723.. _PSCI PDD: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf
2724.. _SMC calling convention PDD: http://infocenter.arm.com/help/topic/com.arm.doc.den0028b/ARM_DEN0028B_SMC_Calling_Convention.pdf
2725.. _PSCI Library integration guide: ./psci-lib-integration-guide.rst
2726.. _SMCCC: http://infocenter.arm.com/help/topic/com.arm.doc.den0028b/ARM_DEN0028B_SMC_Calling_Convention.pdf
2727.. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf
2728.. _Power State Coordination Interface PDD: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf
2729.. _here: ./psci-lib-integration-guide.rst
2730.. _cpu-specific-build-macros.rst: ./cpu-specific-build-macros.rst
2731.. _CPUBM: ./cpu-specific-build-macros.rst
Dan Handley610e7e12018-03-01 18:44:00 +00002732.. _Arm ARM: http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0487a.e/index.html
Douglas Raillardd7c21b72017-06-28 15:23:03 +01002733.. _User Guide: ./user-guide.rst
2734.. _SMC Calling Convention PDD: http://infocenter.arm.com/help/topic/com.arm.doc.den0028b/ARM_DEN0028B_SMC_Calling_Convention.pdf
Dan Handley610e7e12018-03-01 18:44:00 +00002735.. _TF-A Interrupt Management Design guide: ./interrupt-framework-design.rst
Antonio Nino Diazb5d68092017-05-23 11:49:22 +01002736.. _Xlat_tables design: xlat-tables-lib-v2-design.rst
Douglas Raillardd7c21b72017-06-28 15:23:03 +01002737
2738.. |Image 1| image:: diagrams/rt-svc-descs-layout.png?raw=true