blob: f07dfab688af9bf545ca1d362cbf89d74fa42f19 [file] [log] [blame]
Antonio Nino Diazb5d68092017-05-23 11:49:22 +01001Translation Tables Library Design
2=================================
3
4
5.. section-numbering::
6 :suffix: .
7
8.. contents::
9
10
11This document describes the design of the translation tables library (version 2)
Dan Handley610e7e12018-03-01 18:44:00 +000012used by Trusted Firmware-A (TF-A). This library provides APIs to create page
Antonio Nino Diazb5d68092017-05-23 11:49:22 +010013tables based on a description of the memory layout, as well as setting up system
14registers related to the Memory Management Unit (MMU) and performing the
15required Translation Lookaside Buffer (TLB) maintenance operations.
16
17More specifically, some use cases that this library aims to support are:
18
19#. Statically allocate translation tables and populate them (at run-time) based
20 on a description of the memory layout. The memory layout is typically
21 provided by the platform port as a list of memory regions;
22
23#. Support for generating translation tables pertaining to a different
24 translation regime than the exception level the library code is executing at;
25
26#. Support for dynamic mapping and unmapping of regions, even while the MMU is
27 on. This can be used to temporarily map some memory regions and unmap them
28 later on when no longer needed;
29
30#. Support for non-identity virtual to physical mappings to compress the virtual
31 address space;
32
33#. Support for changing memory attributes of memory regions at run-time.
34
35
36About version 1 and version 2
37-----------------------------
38
39This document focuses on version 2 of the library, whose sources are available
40in the `lib/xlat\_tables\_v2`_ directory. Version 1 of the library can still be
41found in `lib/xlat\_tables`_ directory but it is less flexible and doesn't
42support dynamic mapping. Although potential bug fixes will be applied to both
43versions, future features enhancements will focus on version 2 and might not be
44back-ported to version 1. Therefore, it is recommended to use version 2,
45especially for new platform ports.
46
47However, please note that version 2 is still in active development and is not
48considered stable yet. Hence, compatibility breaks might be introduced.
49
50From this point onwards, this document will implicitly refer to version 2 of the
51library.
52
53
54Design concepts and interfaces
55------------------------------
56
57This section presents some of the key concepts and data structures used in the
58translation tables library.
59
60`mmap` regions
61~~~~~~~~~~~~~~
62
63An ``mmap_region`` is an abstract, concise way to represent a memory region to
64map. It is one of the key interfaces to the library. It is identified by:
65
66- its physical base address;
67- its virtual base address;
68- its size;
Sandrine Bailleux8f23fa82017-09-28 21:58:12 +010069- its attributes;
70- its mapping granularity (optional).
Antonio Nino Diazb5d68092017-05-23 11:49:22 +010071
72See the ``struct mmap_region`` type in `xlat\_tables\_v2.h`_.
73
74The user usually provides a list of such mmap regions to map and lets the
75library transpose that in a set of translation tables. As a result, the library
76might create new translation tables, update or split existing ones.
77
78The region attributes specify the type of memory (for example device or cached
79normal memory) as well as the memory access permissions (read-only or
Antonio Nino Diazdcf9d922017-10-04 16:52:15 +010080read-write, executable or not, secure or non-secure, and so on). In the case of
81the EL1&0 translation regime, the attributes also specify whether the region is
Antonio Nino Diaz8643a812018-06-21 14:39:16 +010082a User region (EL0) or Privileged region (EL1). See the ``MT_xxx`` definitions
83in `xlat\_tables\_v2.h`_. Note that for the EL1&0 translation regime the Execute
84Never attribute is set simultaneously for both EL1 and EL0.
Antonio Nino Diazb5d68092017-05-23 11:49:22 +010085
Sandrine Bailleux8f23fa82017-09-28 21:58:12 +010086The granularity controls the translation table level to go down to when mapping
87the region. For example, assuming the MMU has been configured to use a 4KB
88granule size, the library might map a 2MB memory region using either of the two
89following options:
90
91- using a single level-2 translation table entry;
92- using a level-2 intermediate entry to a level-3 translation table (which
93 contains 512 entries, each mapping 4KB).
94
95The first solution potentially requires less translation tables, hence
96potentially less memory. However, if part of this 2MB region is later remapped
97with different memory attributes, the library might need to split the existing
98page tables to refine the mappings. If a single level-2 entry has been used
99here, a level-3 table will need to be allocated on the fly and the level-2
100modified to point to this new level-3 table. This has a performance cost at
101run-time.
102
103If the user knows upfront that such a remapping operation is likely to happen
104then they might enforce a 4KB mapping granularity for this 2MB region from the
105beginning; remapping some of these 4KB pages on the fly then becomes a
106lightweight operation.
107
108The region's granularity is an optional field; if it is not specified the
109library will choose the mapping granularity for this region as it sees fit (more
110details can be found in `The memory mapping algorithm`_ section below).
Antonio Nino Diazb5d68092017-05-23 11:49:22 +0100111
112Translation Context
113~~~~~~~~~~~~~~~~~~~
114
115The library can create or modify translation tables pertaining to a different
116translation regime than the exception level the library code is executing at.
117For example, the library might be used by EL3 software (for instance BL31) to
118create translation tables pertaining to the S-EL1&0 translation regime.
119
120This flexibility comes from the use of *translation contexts*. A *translation
121context* constitutes the superset of information used by the library to track
122the status of a set of translation tables for a given translation regime.
123
124The library internally allocates a default translation context, which pertains
125to the translation regime of the current exception level. Additional contexts
126may be explicitly allocated and initialized using the
127``REGISTER_XLAT_CONTEXT()`` macro. Separate APIs are provided to act either on
128the default translation context or on an alternative one.
129
130To register a translation context, the user must provide the library with the
131following information:
132
133* A name.
134
135 The resulting translation context variable will be called after this name, to
136 which ``_xlat_ctx`` is appended. For example, if the macro name parameter is
137 ``foo``, the context variable name will be ``foo_xlat_ctx``.
138
139* The maximum number of `mmap` regions to map.
140
141 Should account for both static and dynamic regions, if applicable.
142
143* The number of sub-translation tables to allocate.
144
145 Number of translation tables to statically allocate for this context,
146 excluding the initial lookup level translation table, which is always
147 allocated. For example, if the initial lookup level is 1, this parameter would
148 specify the number of level-2 and level-3 translation tables to pre-allocate
149 for this context.
150
151* The size of the virtual address space.
152
153 Size in bytes of the virtual address space to map using this context. This
154 will incidentally determine the number of entries in the initial lookup level
155 translation table : the library will allocate as many entries as is required
156 to map the entire virtual address space.
157
158* The size of the physical address space.
159
160 Size in bytes of the physical address space to map using this context.
161
162The default translation context is internally initialized using information
163coming (for the most part) from platform-specific defines:
164
165- name: hard-coded to ``tf`` ; hence the name of the default context variable is
166 ``tf_xlat_ctx``;
167- number of `mmap` regions: ``MAX_MMAP_REGIONS``;
168- number of sub-translation tables: ``MAX_XLAT_TABLES``;
169- size of the virtual address space: ``PLAT_VIRT_ADDR_SPACE_SIZE``;
170- size of the physical address space: ``PLAT_PHY_ADDR_SPACE_SIZE``.
171
172Please refer to the `Porting Guide`_ for more details about these macros.
173
174
175Static and dynamic memory regions
176~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
177
178The library optionally supports dynamic memory mapping. This feature may be
179enabled using the ``PLAT_XLAT_TABLES_DYNAMIC`` platform build flag.
180
181When dynamic memory mapping is enabled, the library categorises mmap regions as
182*static* or *dynamic*.
183
184- *Static regions* are fixed for the lifetime of the system. They can only be
185 added early on, before the translation tables are created and populated. They
186 cannot be removed afterwards.
187
188- *Dynamic regions* can be added or removed any time.
189
190When the dynamic memory mapping feature is disabled, only static regions exist.
191
192The dynamic memory mapping feature may be used to map and unmap transient memory
193areas. This is useful when the user needs to access some memory for a fixed
194period of time, after which the memory may be discarded and reclaimed. For
195example, a memory region that is only required at boot time while the system is
196initializing, or to temporarily share a memory buffer between the normal world
197and trusted world. Note that it is up to the caller to ensure that these regions
198are not accessed concurrently while the regions are being added or removed.
199
200Although this feature provides some level of dynamic memory allocation, this
201does not allow dynamically allocating an arbitrary amount of memory at an
202arbitrary memory location. The user is still required to declare at compile-time
203the limits of these allocations ; the library will deny any mapping request that
204does not fit within this pre-allocated pool of memory.
205
206
207Library APIs
208------------
209
210The external APIs exposed by this library are declared and documented in the
211`xlat\_tables\_v2.h`_ header file. This should be the reference point for
212getting information about the usage of the different APIs this library
213provides. This section just provides some extra details and clarifications.
214
215Although the ``mmap_region`` structure is a publicly visible type, it is not
216recommended to populate these structures by hand. Instead, wherever APIs expect
217function arguments of type ``mmap_region_t``, these should be constructed using
218the ``MAP_REGION*()`` family of helper macros. This is to limit the risk of
219compatibility breaks, should the ``mmap_region`` structure type evolve in the
220future.
221
Sandrine Bailleux8f23fa82017-09-28 21:58:12 +0100222The ``MAP_REGION()`` and ``MAP_REGION_FLAT()`` macros do not allow specifying a
223mapping granularity, which leaves the library implementation free to choose
224it. However, in cases where a specific granularity is required, the
225``MAP_REGION2()`` macro might be used instead.
226
Antonio Nino Diazb5d68092017-05-23 11:49:22 +0100227As explained earlier in this document, when the dynamic mapping feature is
228disabled, there is no notion of dynamic regions. Conceptually, there are only
229static regions. For this reason (and to retain backward compatibility with the
230version 1 of the library), the APIs that map static regions do not embed the
231word *static* in their functions names (for example ``mmap_add_region()``), in
232contrast with the dynamic regions APIs (for example
233``mmap_add_dynamic_region()``).
234
235Although the definition of static and dynamic regions is not based on the state
236of the MMU, the two are still related in some way. Static regions can only be
237added before ``init_xlat_tables()`` is called and ``init_xlat_tables()`` must be
238called while the MMU is still off. As a result, static regions cannot be added
239once the MMU has been enabled. Dynamic regions can be added with the MMU on or
240off. In practice, the usual call flow would look like this:
241
242#. The MMU is initially off.
243
244#. Add some static regions, add some dynamic regions.
245
246#. Initialize translation tables based on the list of mmap regions (using one of
247 the ``init_xlat_tables*()`` APIs).
248
249#. At this point, it is no longer possible to add static regions. Dynamic
250 regions can still be added or removed.
251
252#. Enable the MMU.
253
254#. Dynamic regions can continue to be added or removed.
255
256Because static regions are added early on at boot time and are all in the
257control of the platform initialization code, the ``mmap_add*()`` family of APIs
258are not expected to fail. They do not return any error code.
259
260Nonetheless, these APIs will check upfront whether the region can be
261successfully added before updating the translation context structure. If the
262library detects that there is insufficient memory to meet the request, or that
263the new region will overlap another one in an invalid way, or if any other
264unexpected error is encountered, they will print an error message on the UART.
265Additionally, when asserts are enabled (typically in debug builds), an assertion
266will be triggered. Otherwise, the function call will just return straight away,
267without adding the offending memory region.
268
269
270Library limitations
271-------------------
272
273Dynamic regions are not allowed to overlap each other. Static regions are
274allowed to overlap as long as one of them is fully contained inside the other
275one. This is allowed for backwards compatibility with the previous behaviour in
276the version 1 of the library.
277
278
279Implementation details
280----------------------
281
282Code structure
283~~~~~~~~~~~~~~
284
Antonio Nino Diaz27818082018-07-03 14:56:31 +0100285The library is divided into 4 modules:
Antonio Nino Diazb5d68092017-05-23 11:49:22 +0100286
Antonio Nino Diaz27818082018-07-03 14:56:31 +0100287- **Core module**
Antonio Nino Diazb5d68092017-05-23 11:49:22 +0100288
Antonio Nino Diaz27818082018-07-03 14:56:31 +0100289 Provides the main functionality of the library, such as the initialization of
290 translation tables contexts and mapping/unmapping memory regions. This module
291 provides functions such as ``mmap_add_region_ctx`` that let the caller specify
292 the translation tables context affected by them.
Antonio Nino Diazb5d68092017-05-23 11:49:22 +0100293
Antonio Nino Diaz27818082018-07-03 14:56:31 +0100294 See `xlat\_tables\_core.c`_.
Antonio Nino Diazb5d68092017-05-23 11:49:22 +0100295
Antonio Nino Diaz27818082018-07-03 14:56:31 +0100296- **Active context module**
Antonio Nino Diazb5d68092017-05-23 11:49:22 +0100297
Antonio Nino Diaz27818082018-07-03 14:56:31 +0100298 Instantiates the context that is used by the current BL image and provides
299 helpers to manipulate it, abstracting it from the rest of the code.
300 This module provides functions such as ``mmap_add_region``, that directly
301 affect the BL image using them.
302
303 See `xlat\_tables\_context.c`_.
304
305- **Utilities module**
306
307 Provides additional functionality like debug print of the current state of the
308 translation tables and helpers to query memory attributes and to modify them.
309
310 See `xlat\_tables\_utils.c`_.
311
312- **Architectural module**
313
314 Provides functions that are dependent on the current execution state
315 (AArch32/AArch64), such as the functions used for TLB invalidation, setup the
316 MMU, or calculate the Physical Address Space size. They do not need a
317 translation context to work on.
318
319 See `aarch32/xlat\_tables\_arch.c`_ and `aarch64/xlat\_tables\_arch.c`_.
Antonio Nino Diazb5d68092017-05-23 11:49:22 +0100320
Sandrine Bailleux8f23fa82017-09-28 21:58:12 +0100321From mmap regions to translation tables
Antonio Nino Diaz27818082018-07-03 14:56:31 +0100322~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sandrine Bailleux8f23fa82017-09-28 21:58:12 +0100323
Antonio Nino Diaz27818082018-07-03 14:56:31 +0100324A translation context contains a list of ``mmap_region_t``, which holds the
325information of all the regions that are mapped at any given time. Whenever there
326is a request to map (resp. unmap) a memory region, it is added to (resp. removed
327from) the ``mmap_region_t`` list.
Antonio Nino Diazb5d68092017-05-23 11:49:22 +0100328
329The mmap regions list is a conceptual way to represent the memory layout. At
330some point, the library has to convert this information into actual translation
331tables to program into the MMU.
332
333Before the ``init_xlat_tables()`` API is called, the library only acts on the
334mmap regions list. Adding a static or dynamic region at this point through one
335of the ``mmap_add*()`` APIs does not affect the translation tables in any way,
336they only get registered in the internal mmap region list. It is only when the
337user calls the ``init_xlat_tables()`` that the translation tables are populated
338in memory based on the list of mmap regions registered so far. This is an
339optimization that allows creation of the initial set of translation tables in
340one go, rather than having to edit them every time while the MMU is disabled.
341
342After the ``init_xlat_tables()`` API has been called, only dynamic regions can
343be added. Changes to the translation tables (as well as the mmap regions list)
344will take effect immediately.
345
Sandrine Bailleux8f23fa82017-09-28 21:58:12 +0100346The memory mapping algorithm
Antonio Nino Diaz27818082018-07-03 14:56:31 +0100347~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sandrine Bailleux8f23fa82017-09-28 21:58:12 +0100348
Antonio Nino Diazb5d68092017-05-23 11:49:22 +0100349The mapping function is implemented as a recursive algorithm. It is however
Dan Handley610e7e12018-03-01 18:44:00 +0000350bound by the level of depth of the translation tables (the Armv8-A architecture
Antonio Nino Diazb5d68092017-05-23 11:49:22 +0100351allows up to 4 lookup levels).
352
Sandrine Bailleux8f23fa82017-09-28 21:58:12 +0100353By default [#granularity-ref]_, the algorithm will attempt to minimize the
354number of translation tables created to satisfy the user's request. It will
355favour mapping a region using the biggest possible blocks, only creating a
356sub-table if it is strictly necessary. This is to reduce the memory footprint of
357the firmware.
Antonio Nino Diazb5d68092017-05-23 11:49:22 +0100358
359The most common reason for needing a sub-table is when a specific mapping
360requires a finer granularity. Misaligned regions also require a finer
361granularity than what the user may had originally expected, using a lot more
362memory than expected. The reason is that all levels of translation are
363restricted to address translations of the same granularity as the size of the
364blocks of that level. For example, for a 4 KiB page size, a level 2 block entry
365can only translate up to a granularity of 2 MiB. If the Physical Address is not
366aligned to 2 MiB then additional level 3 tables are also needed.
367
368Note that not every translation level allows any type of descriptor. Depending
369on the page size, levels 0 and 1 of translation may only allow table
370descriptors. If a block entry could be able to describe a translation, but that
371level does not allow block descriptors, a table descriptor will have to be used
372instead, as well as additional tables at the next level.
373
374|Alignment Example|
375
376The mmap regions are sorted in a way that simplifies the code that maps
377them. Even though this ordering is only strictly needed for overlapping static
378regions, it must also be applied for dynamic regions to maintain a consistent
379order of all regions at all times. As each new region is mapped, existing
380entries in the translation tables are checked to ensure consistency. Please
381refer to the comments in the source code of the core module for more details
382about the sorting algorithm in use.
383
Sandrine Bailleux8f23fa82017-09-28 21:58:12 +0100384.. [#granularity-ref] That is, when mmap regions do not enforce their mapping
385 granularity.
386
387TLB maintenance operations
Antonio Nino Diaz27818082018-07-03 14:56:31 +0100388~~~~~~~~~~~~~~~~~~~~~~~~~~
Sandrine Bailleux8f23fa82017-09-28 21:58:12 +0100389
Antonio Nino Diazb5d68092017-05-23 11:49:22 +0100390The library takes care of performing TLB maintenance operations when required.
391For example, when the user requests removing a dynamic region, the library
392invalidates all TLB entries associated to that region to ensure that these
393changes are visible to subsequent execution, including speculative execution,
394that uses the changed translation table entries.
395
396A counter-example is the initialization of translation tables. In this case,
Dan Handley610e7e12018-03-01 18:44:00 +0000397explicit TLB maintenance is not required. The Armv8-A architecture guarantees
Antonio Nino Diazb5d68092017-05-23 11:49:22 +0100398that all TLBs are disabled from reset and their contents have no effect on
399address translation at reset [#tlb-reset-ref]_. Therefore, the TLBs invalidation
400is deferred to the ``enable_mmu*()`` family of functions, just before the MMU is
401turned on.
402
403TLB invalidation is not required when adding dynamic regions either. Dynamic
404regions are not allowed to overlap existing memory region. Therefore, if the
405dynamic mapping request is deemed legitimate, it automatically concerns memory
406that was not mapped in this translation regime and the library will have
407initialized its corresponding translation table entry to an invalid
408descriptor. Given that the TLBs are not architecturally permitted to hold any
409invalid translation table entry [#tlb-no-invalid-entry]_, this means that this
410mapping cannot be cached in the TLBs.
411
Antonio Nino Diaz27818082018-07-03 14:56:31 +0100412.. [#tlb-reset-ref] See section D4.9 `Translation Lookaside Buffers (TLBs)`, subsection `TLB behavior at reset` in Armv8-A, rev C.a.
413.. [#tlb-no-invalid-entry] See section D4.10.1 `General TLB maintenance requirements` in Armv8-A, rev C.a.
Antonio Nino Diazb5d68092017-05-23 11:49:22 +0100414
415--------------
416
Dan Handley610e7e12018-03-01 18:44:00 +0000417*Copyright (c) 2017-2018, Arm Limited and Contributors. All rights reserved.*
Antonio Nino Diazb5d68092017-05-23 11:49:22 +0100418
419.. _lib/xlat\_tables\_v2: ../lib/xlat_tables_v2
420.. _lib/xlat\_tables: ../lib/xlat_tables
421.. _xlat\_tables\_v2.h: ../include/lib/xlat_tables/xlat_tables_v2.h
Antonio Nino Diaz27818082018-07-03 14:56:31 +0100422.. _xlat\_tables\_context.c: ../lib/xlat_tables_v2/xlat_tables_context.c
423.. _xlat\_tables\_core.c: ../lib/xlat_tables_v2/xlat_tables_core.c
424.. _xlat\_tables\_utils.c: ../lib/xlat_tables_v2/xlat_tables_utils.c
Antonio Nino Diazb5d68092017-05-23 11:49:22 +0100425.. _aarch32/xlat\_tables\_arch.c: ../lib/xlat_tables_v2/aarch32/xlat_tables_arch.c
426.. _aarch64/xlat\_tables\_arch.c: ../lib/xlat_tables_v2/aarch64/xlat_tables_arch.c
427.. _Porting Guide: porting-guide.rst
428.. |Alignment Example| image:: ./diagrams/xlat_align.png?raw=true