xlat v2: Update documentation
Update documentation to reflect the current state of the library.
Change-Id: Ic72f90ee322d2ebd6ea7f4296315700d6bc434e6
Signed-off-by: Antonio Nino Diaz <antonio.ninodiaz@arm.com>
diff --git a/docs/xlat-tables-lib-v2-design.rst b/docs/xlat-tables-lib-v2-design.rst
index d207f30..f07dfab 100644
--- a/docs/xlat-tables-lib-v2-design.rst
+++ b/docs/xlat-tables-lib-v2-design.rst
@@ -282,31 +282,49 @@
Code structure
~~~~~~~~~~~~~~
-The library is divided into 2 modules:
+The library is divided into 4 modules:
-The core module
- Provides the main functionality of the library.
+- **Core module**
- See `xlat\_tables\_internal.c`_.
+ Provides the main functionality of the library, such as the initialization of
+ translation tables contexts and mapping/unmapping memory regions. This module
+ provides functions such as ``mmap_add_region_ctx`` that let the caller specify
+ the translation tables context affected by them.
-The architectural module
- Provides functions that are dependent on the current execution state
- (AArch32/AArch64), such as the functions used for TLB invalidation or MMU
- setup.
+ See `xlat\_tables\_core.c`_.
- See `aarch32/xlat\_tables\_arch.c`_ and `aarch64/xlat\_tables\_arch.c`_.
+- **Active context module**
-Core module
-~~~~~~~~~~~
+ Instantiates the context that is used by the current BL image and provides
+ helpers to manipulate it, abstracting it from the rest of the code.
+ This module provides functions such as ``mmap_add_region``, that directly
+ affect the BL image using them.
+
+ See `xlat\_tables\_context.c`_.
+
+- **Utilities module**
+
+ Provides additional functionality like debug print of the current state of the
+ translation tables and helpers to query memory attributes and to modify them.
+
+ See `xlat\_tables\_utils.c`_.
+
+- **Architectural module**
+
+ Provides functions that are dependent on the current execution state
+ (AArch32/AArch64), such as the functions used for TLB invalidation, setup the
+ MMU, or calculate the Physical Address Space size. They do not need a
+ translation context to work on.
+
+ See `aarch32/xlat\_tables\_arch.c`_ and `aarch64/xlat\_tables\_arch.c`_.
From mmap regions to translation tables
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-All the APIs in this module work on a translation context. The translation
-context contains the list of ``mmap_region``, which holds the information of all
-the regions that are mapped at any given time. Whenever there is a request to
-map (resp. unmap) a memory region, it is added to (resp. removed from) the
-``mmap_region`` list.
+A translation context contains a list of ``mmap_region_t``, which holds the
+information of all the regions that are mapped at any given time. Whenever there
+is a request to map (resp. unmap) a memory region, it is added to (resp. removed
+from) the ``mmap_region_t`` list.
The mmap regions list is a conceptual way to represent the memory layout. At
some point, the library has to convert this information into actual translation
@@ -326,7 +344,7 @@
will take effect immediately.
The memory mapping algorithm
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The mapping function is implemented as a recursive algorithm. It is however
bound by the level of depth of the translation tables (the Armv8-A architecture
@@ -367,7 +385,7 @@
granularity.
TLB maintenance operations
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~
The library takes care of performing TLB maintenance operations when required.
For example, when the user requests removing a dynamic region, the library
@@ -391,17 +409,8 @@
invalid translation table entry [#tlb-no-invalid-entry]_, this means that this
mapping cannot be cached in the TLBs.
-.. [#tlb-reset-ref] See section D4.8 `Translation Lookaside Buffers (TLBs)`, subsection `TLB behavior at reset` in Armv8-A, rev B.a.
-
-.. [#tlb-no-invalid-entry] See section D4.9.1 `General TLB maintenance requirements` in Armv8-A, rev B.a.
-
-Architectural module
-~~~~~~~~~~~~~~~~~~~~
-
-This module contains functions that have different implementations for AArch32
-and AArch64. For example, it provides APIs to perform TLB maintenance operations,
-enable the MMU or calculate the Physical Address Space size. They do not need a
-translation context to work on.
+.. [#tlb-reset-ref] See section D4.9 `Translation Lookaside Buffers (TLBs)`, subsection `TLB behavior at reset` in Armv8-A, rev C.a.
+.. [#tlb-no-invalid-entry] See section D4.10.1 `General TLB maintenance requirements` in Armv8-A, rev C.a.
--------------
@@ -410,7 +419,9 @@
.. _lib/xlat\_tables\_v2: ../lib/xlat_tables_v2
.. _lib/xlat\_tables: ../lib/xlat_tables
.. _xlat\_tables\_v2.h: ../include/lib/xlat_tables/xlat_tables_v2.h
-.. _xlat\_tables\_internal.c: ../lib/xlat_tables_v2/xlat_tables_internal.c
+.. _xlat\_tables\_context.c: ../lib/xlat_tables_v2/xlat_tables_context.c
+.. _xlat\_tables\_core.c: ../lib/xlat_tables_v2/xlat_tables_core.c
+.. _xlat\_tables\_utils.c: ../lib/xlat_tables_v2/xlat_tables_utils.c
.. _aarch32/xlat\_tables\_arch.c: ../lib/xlat_tables_v2/aarch32/xlat_tables_arch.c
.. _aarch64/xlat\_tables\_arch.c: ../lib/xlat_tables_v2/aarch64/xlat_tables_arch.c
.. _Porting Guide: porting-guide.rst