docs/components/context-management-library.rst

20 with a context management library to handle the context of the CPU, managing the
26 In TF-A, the context is represented as a data structure used by the EL3 firmware
29 level and security state. The memory for the context data structures are allocated
48 need to maintain world-specific context to ensure that register entries from one
57 for maintaining world-specific context essential for a trusted system.
58 This includes implementing CPU context initialization and management routines,
74 Key principles followed in designing the context management library :
84 2. **Decentralized model for context management**
87 in EL3 responsible for their respective world context management.
90 PSCI Library (BL31)/context management library provides routines to help
91 initialize the Non-Secure world context.
156    context for different security states alongside high level feature enablement
161 #. ``context.S`` : consists of functions that save and restore some of the context
174 #. ``context.h`` : contains the helper macros and definitions for context entries.
178 #. ``context_debug.h`` : contains public interface to report context memory
182    context entries. Used by ``context.h``.
184 Apart from these files, we have some context related source files under ``BL1``
213 the Non-Secure, Realm and Secure security state context structures as listed below.
233 the Secure, Non-Secure and Realm context structure addresses to ensure proper
254 The members of the context structure used by the EL3 firmware to preserve the
283 CPUs maintain their context per world. The individual context memory allocation
293 handles memory allocation for ``Non-Secure`` world context for all CPUs.
302 world context of all CPUs.
311 context of all CPUs.
317 To summarize, the world-specific context structures are synchronized with
326 The CPU has been assigned context structures for every security state, which include
330 every CPU context takes place during both cold and warm boot paths.
338 allocated world-specific context memory.
341 of a Secure world image at S-EL2. If detected, it invokes the secure context
343 the Realm context gets initialized from the RMMD at EL3. Finally, before exiting
344 to the normal world, the Non-Secure context gets initialized via the context
364 wakes up it initialises its own context via ``cm_init_my_context( ep )`` using
368 During the warm bootup process, secondary CPUs have their secure context
385 their secure context initialised via the registered SPMD handler
401 context for each world (Non-Secure, Secure and Realm).
405 This function is responsible for the general context initialization that applies
407 world-specific context setup APIs.
414 world-specific context setup handlers listed above will be invoked once per-CPU
415 to set up the context for their execution.
472 during context initialization.
481   functions to enable the feature for the passed context only. To be called in
485   registers that are never context switched. The values they write must never
496 	void sme_enable(cpu_context_t *context);
499 	void sme_disable(cpu_context_t *context);
504 Apart from the CPU context structure, we have another structure to manage some
507 The Per-world context structure is intended for managing EL3 system registers with
508 identical values across all CPUs, requiring only a singular context entry for each
509 individual world. This structure operates independently of the CPU context
549 The firmware at EL3 has traditionally operated within the context of the incoming
560 is referred to as the EL3/Root context.
569 context save operation is not required.
581 EL3 execution context needs to setup at both boot time (cold and warm boot)