docs/components/xlat-tables-lib-v2-design.rst

4 This document describes the design of the translation tables library (version 2)
6 tables based on a description of the memory layout, as well as setting up system
7 registers related to the Memory Management Unit (MMU) and performing the
13    on a description of the memory layout. The memory layout is typically
14    provided by the platform port as a list of memory regions;
17    translation regime than the exception level the library code is executing at;
19 #. Support for dynamic mapping and unmapping of regions, even while the MMU is
23 #. Support for non-identity virtual to physical mappings to compress the virtual
32 This document focuses on version 2 of the library, whose sources are available
33 in the ``lib/xlat_tables_v2`` directory. Version 1 of the library can still be
43 From this point onwards, this document will implicitly refer to version 2 of the
50 This section presents some of the key concepts and data structures used in the
57 map. It is one of the key interfaces to the library. It is identified by:
65 See the ``struct mmap_region`` type in ``xlat_tables_v2.h``.
67 The user usually provides a list of such mmap regions to map and lets the
68 library transpose that in a set of translation tables. As a result, the library
71 The region attributes specify the type of memory (for example device or cached
72 normal memory) as well as the memory access permissions (read-only or
73 read-write, executable or not, secure or non-secure, and so on). In the case of
74 the EL1&0 translation regime, the attributes also specify whether the region is
75 a User region (EL0) or Privileged region (EL1). See the ``MT_xxx`` definitions
76 in ``xlat_tables_v2.h``. Note that for the EL1&0 translation regime the Execute
79 The granularity controls the translation table level to go down to when mapping
80 the region. For example, assuming the MMU has been configured to use a 4KB
81 granule size, the library might map a 2MB memory region using either of the two
90 with different memory attributes, the library might need to split the existing
91 page tables to refine the mappings. If a single level-2 entry has been used
92 here, a level-3 table will need to be allocated on the fly and the level-2
96 If the user knows upfront that such a remapping operation is likely to happen
97 then they might enforce a 4KB mapping granularity for this 2MB region from the
98 beginning; remapping some of these 4KB pages on the fly then becomes a
101 The region's granularity is an optional field; if it is not specified the
102 library will choose the mapping granularity for this region as it sees fit (more
109 translation regime than the exception level the library code is executing at.
110 For example, the library might be used by EL3 software (for instance BL31) to
111 create translation tables pertaining to the S-EL1&0 translation regime.
113 This flexibility comes from the use of *translation contexts*. A *translation
114 context* constitutes the superset of information used by the library to track
115 the status of a set of translation tables for a given translation regime.
118 to the translation regime of the current exception level. Additional contexts
119 may be explicitly allocated and initialized using the
121 the default translation context or on an alternative one.
123 To register a translation context, the user must provide the library with the
129   which ``_xlat_ctx`` is appended. For example, if the macro name parameter is
130   ``foo``, the context variable name will be ``foo_xlat_ctx``.
139   excluding the initial lookup level translation table, which is always
140   allocated. For example, if the initial lookup level is 1, this parameter would
141   specify the number of level-2 and level-3 translation tables to pre-allocate
144 * The size of the virtual address space.
146   Size in bytes of the virtual address space to map using this context. This
147   will incidentally determine the number of entries in the initial lookup level
148   translation table : the library will allocate as many entries as is required
149   to map the entire virtual address space.
151 * The size of the physical address space.
153   Size in bytes of the physical address space to map using this context.
156 coming (for the most part) from platform-specific defines:
158 - name: hard-coded to ``tf`` ; hence the name of the default context variable is
162 - size of the virtual address space: ``PLAT_VIRT_ADDR_SPACE_SIZE``;
163 - size of the physical address space: ``PLAT_PHY_ADDR_SPACE_SIZE``.
165 Please refer to the :ref:`Porting Guide` for more details about these macros.
172 enabled using the ``PLAT_XLAT_TABLES_DYNAMIC`` platform build flag.
174 When dynamic memory mapping is enabled, the library categorises mmap regions as
177 - *Static regions* are fixed for the lifetime of the system. They can only be
178   added early on, before the translation tables are created and populated. They
183 When the dynamic memory mapping feature is disabled, only static regions exist.
186 areas. This is useful when the user needs to access some memory for a fixed
187 period of time, after which the memory may be discarded and reclaimed. For
188 example, a memory region that is only required at boot time while the system is
189 initializing, or to temporarily share a memory buffer between the normal world
190 and trusted world. Note that it is up to the caller to ensure that these regions
191 are not accessed concurrently while the regions are being added or removed.
196 the limits of these allocations ; the library will deny any mapping request that
203 The external APIs exposed by this library are declared and documented in the
204 ``xlat_tables_v2.h`` header file. This should be the reference point for
205 getting information about the usage of the different APIs this library
208 Although the ``mmap_region`` structure is a publicly visible type, it is not
211 the ``MAP_REGION*()`` family of helper macros. This is to limit the risk of
212 compatibility breaks, should the ``mmap_region`` structure type evolve in the
216 mapping granularity, which leaves the library implementation free to choose
217 it. However, in cases where a specific granularity is required, the
220 As explained earlier in this document, when the dynamic mapping feature is
222 static regions. For this reason (and to retain backward compatibility with the
223 version 1 of the library), the APIs that map static regions do not embed the
225 contrast with the dynamic regions APIs (for example
228 Although the definition of static and dynamic regions is not based on the state
229 of the MMU, the two are still related in some way. Static regions can only be
231 called while the MMU is still off. As a result, static regions cannot be added
232 once the MMU has been enabled. Dynamic regions can be added with the MMU on or
233 off. In practice, the usual call flow would look like this:
239 #. Initialize translation tables based on the list of mmap regions (using one of
240    the ``init_xlat_tables*()`` APIs).
245 #. Enable the MMU.
249 Because static regions are added early on at boot time and are all in the
250 control of the platform initialization code, the ``mmap_add*()`` family of APIs
253 Nonetheless, these APIs will check upfront whether the region can be
254 successfully added before updating the translation context structure. If the
255 library detects that there is insufficient memory to meet the request, or that
256 the new region will overlap another one in an invalid way, or if any other
257 unexpected error is encountered, they will print an error message on the UART.
259 will be triggered. Otherwise, the function call will just return straight away,
260 without adding the offending memory region.
267 allowed to overlap as long as one of them is fully contained inside the other
268 one. This is allowed for backwards compatibility with the previous behaviour in
269 the version 1 of the library.
282   Provides the main functionality of the library, such as the initialization of
284   provides functions such as ``mmap_add_region_ctx`` that let the caller specify
285   the translation tables context affected by them.
291   Instantiates the context that is used by the current BL image and provides
292   helpers to manipulate it, abstracting it from the rest of the code.
294   affect the BL image using them.
300   Provides additional functionality like debug print of the current state of the
307   Provides functions that are dependent on the current execution state
308   (AArch32/AArch64), such as the functions used for TLB invalidation, setup the
309   MMU, or calculate the Physical Address Space size. They do not need a
317 A translation context contains a list of ``mmap_region_t``, which holds the
318 information of all the regions that are mapped at any given time. Whenever there
320 from) the ``mmap_region_t`` list.
322 The mmap regions list is a conceptual way to represent the memory layout. At
323 some point, the library has to convert this information into actual translation
324 tables to program into the MMU.
326 Before the ``init_xlat_tables()`` API is called, the library only acts on the
328 of the ``mmap_add*()`` APIs does not affect the translation tables in any way,
329 they only get registered in the internal mmap region list. It is only when the
330 user calls the ``init_xlat_tables()`` that the translation tables are populated
331 in memory based on the list of mmap regions registered so far. This is an
332 optimization that allows creation of the initial set of translation tables in
333 one go, rather than having to edit them every time while the MMU is disabled.
335 After the ``init_xlat_tables()`` API has been called, only dynamic regions can
336 be added. Changes to the translation tables (as well as the mmap regions list)
343 bound by the level of depth of the translation tables (the Armv8-A architecture
346 By default [#granularity]_, the algorithm will attempt to minimize the
347 number of translation tables created to satisfy the user's request. It will
348 favour mapping a region using the biggest possible blocks, only creating a
349 sub-table if it is strictly necessary. This is to reduce the memory footprint of
350 the firmware.
354 granularity than what the user may had originally expected, using a lot more
356 restricted to address translations of the same granularity as the size of the
358 can only translate up to a granularity of 2 MiB. If the Physical Address is not
362 on the page size, levels 0 and 1 of translation may only allow table
365 instead, as well as additional tables at the next level.
369 The mmap regions are sorted in a way that simplifies the code that maps
373 entries in the translation tables are checked to ensure consistency. Please
374 refer to the comments in the source code of the core module for more details
375 about the sorting algorithm in use.
381 For example, when the user requests removing a dynamic region, the library
384 that uses the changed translation table entries.
386 A counter-example is the initialization of translation tables. In this case,
389 address translation at reset [#tlb-reset-ref]_. Therefore, the TLBs invalidation
390 is deferred to the ``enable_mmu*()`` family of functions, just before the MMU is
394 regions are not allowed to overlap existing memory region. Therefore, if the
396 that was not mapped in this translation regime and the library will have
398 descriptor. Given that the TLBs are not architecturally permitted to hold any
400 mapping cannot be cached in the TLBs.