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
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;
19 #. Support for dynamic mapping and unmapping of regions, even while the MMU is
26 #. Support for changing memory attributes of memory regions at run-time.
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:
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
73 read-write, executable or not, secure or non-secure, and so on). In the case of
81 granule size, the library might map a 2MB memory region using either of the two
89 potentially less memory.  However, if part of this 2MB region is later remapped
98 beginning; remapping some of these 4KB pages on the fly then becomes a
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
132 * The maximum number of `mmap` regions to map.
136 * The number of sub-translation tables to allocate.
138   Number of translation tables to statically allocate for this context,
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
151 * The size of the physical address space.
153   Size in bytes of the physical address space to map using this context.
158 - name: hard-coded to ``tf`` ; hence the name of the default context variable is
160 - number of `mmap` regions: ``MAX_MMAP_REGIONS``;
161 - number of sub-translation tables: ``MAX_XLAT_TABLES``;
162 - size of the virtual address space: ``PLAT_VIRT_ADDR_SPACE_SIZE``;
163 - size of the physical address space: ``PLAT_PHY_ADDR_SPACE_SIZE``.
177 - *Static regions* are fixed for the lifetime of the system. They can only be
187 period of time, after which the memory may be discarded and reclaimed. For
193 Although this feature provides some level of dynamic memory allocation, this
194 does not allow dynamically allocating an arbitrary amount of memory at an
196 the limits of these allocations ; the library will deny any mapping request that
197 does not fit within this pre-allocated pool of memory.
205 getting information about the usage of the different APIs this library
210 function arguments of type ``mmap_region_t``, these should be constructed using
211 the ``MAP_REGION*()`` family of helper macros. This is to limit the risk of
221 disabled, there is no notion of dynamic regions. Conceptually, there are only
223 version 1 of the library), the APIs that map static regions do not embed the
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
239 #. Initialize translation tables based on the list of mmap regions (using one of
250 control of the platform initialization code, the ``mmap_add*()`` family of APIs
267 allowed to overlap as long as one of them is fully contained inside the other
269 the version 1 of the library.
282   Provides the main functionality of the library, such as the initialization of
292   helpers to manipulate it, abstracting it from the rest of the code.
300   Provides additional functionality like debug print of the current state of the
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
328 of the ``mmap_add*()`` APIs does not affect the translation tables in any way,
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
343 bound by the level of depth of the translation tables (the Armv8-A architecture
347 number of translation tables created to satisfy the user's request. It will
349 sub-table if it is strictly necessary. This is to reduce the memory footprint of
355 memory than expected. The reason is that all levels of translation are
356 restricted to address translations of the same granularity as the size of the
357 blocks of that level.  For example, for a 4 KiB page size, a level 2 block entry
358 can only translate up to a granularity of 2 MiB. If the Physical Address is not
361 Note that not every translation level allows any type of descriptor. Depending
362 on the page size, levels 0 and 1 of translation may only allow table
372 order of all regions at all times. As each new region is mapped, existing
374 refer to the comments in the source code of the core module for more details
380 The library takes care of performing TLB maintenance operations when required.
386 A counter-example is the initialization of translation tables. In this case,
390 is deferred to the ``enable_mmu*()`` family of functions, just before the MMU is