docs/design/firmware-design.rst

14 (for example, secondary CPU boot, hotplug and idle). Normal world software can
40 primary CPU, and the remaining CPUs are considered secondary CPUs. The primary
41 CPU is chosen through platform-specific means. The cold boot path is mainly
42 executed by the primary CPU, other than essential CPU initialization executed by
44 the primary CPU has performed enough initialization to boot them.
46 Refer to the :ref:`CPU Reset` for more information on the effect of the
159 Whenever a CPU is released from reset, BL1 needs to distinguish between a warm
162 of a warm boot, a CPU is expected to continue execution from a separate
165 the :ref:`Porting Guide`) while the primary CPU executes the remaining cold boot
169 :ref:`CPU Reset` for more information on the effect of the
248 -  CPU initialization
250    BL1 calls the ``reset_handler`` macro/function which in turn calls the CPU
251    specific reset handler function (see the section: "CPU specific operations
290 #. BL1 prints the following string from the primary CPU to indicate successful
499 BL31 initializes the per-CPU data framework, which provides a cache of
500 frequently accessed per-CPU data optimised for fast, concurrent manipulation
501 on different CPUs. This buffer includes pointers to per-CPU contexts, crash
502 buffer, CPU reset and power down operations, PSCI data, platform data and so on.
538 that the primary CPU belongs to is ``ON``; any other cluster is ``OFF``. It also
539 initializes the locks that protect them. BL31 accesses the state of a CPU or
584 Required CPU state when calling ``bl31_entrypoint()`` during cold boot
587 This function must only be called by the primary CPU.
589 On entry to this function the calling primary CPU must be executing in AArch64
631 the CPU caches if it is provided by an earlier boot stage and then accessed by
706 Required CPU state for BL31 Warm boot initialization
709 When requesting a CPU power-on, or suspending a running CPU, TF-A provides
711 entry-point, to be invoked by the CPU immediately after the reset handler.
712 On entry to the Warm boot initialization function the calling CPU must be in
724 necessary system, cluster and CPU resources.
737 Required CPU state when entering during cold boot
740 This function must only be called by the primary CPU.
742 On entry to this function the calling primary CPU must be executing in AArch32
773 out of the CPU caches if it is provided by an earlier boot stage and then
794 Required CPU state for warm boot initialization
797 When requesting a CPU power-on, or suspending a running CPU, AArch32 EL3
866 #. CPU implementation service
868    This service will provide an interface to CPU implementation specific
905 framework running on the primary CPU during cold boot as part of the BL31
927 function is only invoked on the primary CPU during cold boot. If the service
928 uses per-CPU data this must either be initialized for all CPUs during this call,
929 or be done lazily when a CPU first issues an SMC call to that service. If
978 before restoring the stack and CPU state and returning from the original SMC.
1151    receipt of this SMC, the SPD service handler should switch the CPU context
1239 A dedicated per-CPU crash stack is maintained by BL31 and this is retrieved via
1240 the per-CPU pointer cache. The implementation attempts to minimise the memory
1350 TF-A implements a framework that allows CPU and platform ports to perform
1351 actions very early after a CPU is released from reset in both the cold and warm
1353 the BL1 and BL31 images. It in turn calls the platform and CPU specific reset
1356 Details for implementing a CPU specific reset handler can be found in
1397 CPU specific operations framework
1433 The CPU specific operations framework scales to accommodate a large number of
1435 any CPU optimization it wants to enable for each CPU. It can also specify
1436 the CPU errata workarounds to be applied for each CPU type during reset
1437 handling by defining CPU errata compile time macros. Details on these macros
1438 can be found in the :ref:`Arm CPU Specific Build Macros` document.
1440 The CPU specific operations framework depends on the ``cpu_ops`` structure which
1441 needs to be exported for each type of CPU in the platform. It is defined in
1446 The CPU specific files in ``lib/cpus`` export a ``cpu_ops`` data structure with
1447 suitable handlers for that CPU. For example, ``lib/cpus/aarch64/cortex_a53.S``
1448 exports the ``cpu_ops`` for Cortex-A53 CPU. According to the platform
1449 configuration, these CPU specific files must be included in the build by
1450 the platform makefile. The generic CPU specific operations framework code exists
1453 CPU PCS
1456 All assembly functions in CPU files are asked to follow a modified version of
1479 CPU specific Reset Handling
1482 After a reset, the state of the CPU when it calls generic reset handler is:
1489 the current CPU midr, finds the matching ``cpu_ops`` entry in the ``cpu_ops``
1493 handling for that CPU and also any errata workarounds enabled by the platform.
1500 CPU specific power down sequence
1504 entry is stored in per-CPU data by ``cpu_data_init_cpu_ops()`` so that it can be quickly
1507 Various CPU drivers register handlers to perform power down at certain power
1508 levels for that specific CPU. The PSCI service, upon receiving a power down
1510 sequence for a particular CPU. It uses the ``prepare_cpu_pwr_dwn()`` function to
1512 retrieves ``cpu_ops`` pointer member of per-CPU data, and from that, further
1514 requested power level is higher than what a CPU driver supports, the handler
1534 CPU specific register reporting during crash
1540 ``cpu_ops`` is invoked, which then returns the CPU specific register values to
1546 CPU errata implementation
1553 override build options to enable or disable errata as appropriate. The CPU
1555 to a given CPU.
1571 #. A CPU revision checker function: ``check_erratum_<cpu_name>_<erratum_id>``
1573    It should check whether this erratum applies on this revision of this CPU.
1574    It will be called with the CPU revision as its first parameter (x0) and
1611  letter and number name of the CPU.
1636 In a debug build of TF-A, on a CPU that comes out of reset, both BL1 and the
2247          * Index of the first CPU power domain node level 0 which has this node
2253          * Number of CPU power domains which are siblings of the domain indexed
2295          * Bit[0]       : choosing. This field is set when the CPU is
2302 It is a characteristic of Lamport's Bakery algorithm that the volatile per-CPU
2303 fields can be read by all CPUs but only written to by the owning CPU.
2305 Depending upon the data cache line size, the per-CPU fields of the
2307 These per-CPU fields can be read and written during lock contention by multiple
2314 CPU0 updates its per-CPU field with data cache enabled. This write updates a
2316 CPU1 updates its per-CPU field of the ``bakery_lock_t`` structure with data cache
2324 for a single CPU. The macro ``DEFINE_BAKERY_LOCK`` allocates all the bakery locks
2325 needed for a CPU into a section ``.bakery_lock``. The linker allocates the memory
2339          * Bit[0]       : choosing. This field is set when the CPU is
2346 The ``bakery_info_t`` represents a single per-CPU field of one lock and
2355     | `bakery_info_t`| <-- Lock_0 per-CPU field
2358     | `bakery_info_t`| <-- Lock_1 per-CPU field
2363     | `bakery_info_t`| <-- Lock_N per-CPU field
2371     | `bakery_info_t`| <-- Lock_0 per-CPU field
2374     | `bakery_info_t`| <-- Lock_1 per-CPU field
2379     | `bakery_info_t`| <-- Lock_N per-CPU field
2408    for each CPU are distributed across different cache lines.
2605 overlapping the secondary CPU stacks so that after the cold boot is done, this
2681 in a per-CPU cache line aligned memory region.
2703 These macros accept the CPU's MPIDR value, or its ordinal position
2722     x2: The `mpidr` of the CPU for which the timestamp has to be retrieved.
2774 CPU architecture extension, otherwise it defaults to base Armv8.0-A architecture.
2821    of the value of these build flags if the CPU supports it.