1###########################
2Code Generation With Jinja2
3###########################
4
5:Author: Mate Toth-Pal
6:Organization: Arm Limited
7:Contact: Mate Toth-Pal <mate.toth-pal@arm.com>
8
9***************************************
10Generating files from templates in TF-M
11***************************************
12
13Some of the files in TF-M are generated from template files. The files to be
14generated are listed in ``tools/tfm_generated_file_list.yaml``. For each
15generated file ``<path_to_file>/<filename>`` the template file is
16``<path_to_file>/<filename>.template``. The templates are populated with
17partition information from the partition manifests. The manifests to be used for
18the generation are listed in ``tools/tfm_manifest_list.yaml``.
19
20****************************************
21Custom generator script - Current method
22****************************************
23
24``tools/tfm_parse_manifest_list.py`` Python script is used to generate files
25from the templates. This script calls the ``tools/generate_from_template.py`` to
26parse the template files, and uses ``tools/keyword_substitution.py`` to
27substitute the keychains with actual values from the manifest files.
28
29*************************************
30Use Jinja2 template engine - proposal
31*************************************
32
33The proposal is to eliminate the template parser and substituter scripts, and
34call the Jinja2 template engine library from
35``tools/tfm_parse_manifest_list.py`` to do the substitution.
36
37More information on jinja2: http://jinja.pocoo.org/
38
39Changes needed:
40===============
41
42- ``tools/tfm_parse_manifest_list.py`` have to be modified to call the Jinja2
43  library instead of the custom scripts. The data structure required by the
44  library is very similar to the one required by the current scripts.
45- template files needs to be rewritten to the Jinja syntax: The control
46  characters to be replaced (like ``@!`` -> ``{%``) and ``for`` statements to be
47  added to iterate over the substitutions.
48
49Improvements over the current solution
50======================================
51
52- Compatible with Python 2.7 and Python 3, while current solution only supports
53  Python 2.7
54- More advanced functionality: direct control over the list of items for a
55  keychain, meta information on that list (like length)
56- Well documented (see website)
57- Jinja2 is free and open-source software, BSD licensed, just like TF-M. It is a
58  well established software in contrast with the current proprietary solution.
59
60*******
61Example
62*******
63
64Below code snippet enumerates services in Secure Partitions:
65
66.. code-block:: jinja
67
68    {% for partition in partitions %}
69        {% if partition.manifest.services %}
70            {% for service in partition.manifest.services %}
71                {do something for the service}
72            {% endfor %}
73        {% endif %}
74    {% endfor %}
75
76--------------
77
78*Copyright (c) 2019-2021, Arm Limited. All rights reserved.*
79