index.md: Add introduction on parsing TF-M dependency versions by CI
There is a new feature in TF-M Open CI to automatically parse dependency
versions from CMake configs.
This patch add introduction on how to use this feature and how the CI
scripts works.
Signed-off-by: Xinyu Zhang <xinyu.zhang@arm.com>
Change-Id: I32378b296acadb154fe920c01e5d5b4a6bcf2d05
diff --git a/docs/index.md b/docs/index.md
index ca28860..8e3ff26 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -322,6 +322,8 @@
</div>
</figure>
+__Note:__ If any dependency version (MbedTLS, MCUBoot, etc.) is changed in TF-M patch, *Allow-CI* will automatically verify the TF-M patch together with the dependency in new version. If there is an unmerged patch in other TF-M repos, such as tf-m-tests or tf-m-extras, update the dependency version in TF-M configuration with the commit ID of that patch. And then trigger *Allow-CI* on the TF-M patch to update dependency version. The unmerged patch in dependency repo can also be verified together with the TF-M patch.
+
#### Nightly job
Nightly job is daily scheduled to check the health of latest HEAD on TF-M master branch. Email notification will be sent to [tf-m-ci-notifications](https://lists.trustedfirmware.org/mailman3/lists/tf-m-ci-notifications.lists.trustedfirmware.org/) mailing list once the job failed. [TF-M user guide](https://tf-m-user-guide.trustedfirmware.org/) posted to [trustedfirmware.org](https://www.trustedfirmware.org/) is also daily generated by tf-m-build-docs-nightly in nightly job.
@@ -869,7 +871,25 @@
</div>
</figure>
-#### Generate CMake build command
+#### Generate commands to build TF-M image
+
+Building TF-M image in a specific config consists of 4 steps in a tf-m-build-config job. Each step runs dedicated command. These commands are listed below in the order of build sequence.
+- set_compiler
+- cmake_config
+- cmake_build
+- post_build
+
+##### Set compiler commands
+
+There are several compilers in different versions installed in [CI docker image](https://git.trustedfirmware.org/ci/dockerfiles.git/tree/bionic-amd64-tf-m-build/Dockerfile?h=refs/heads/master#n13). To select correct compiler in correct version, each single tf-m-build-config job needs to run the commands to set compiler for current configuration.
+
+Compiler and its version are selected in the *seed_params* introduced in [CMake config commands](#cmake-config-commands) section. [Set compiler command](https://git.trustedfirmware.org/ci/tf-m-ci-scripts.git/tree/build_helper/build_helper_configs.py?h=refs/heads/master#n66) is to add specified compiler path into system PATH.
+
+```
+export PATH=$PATH:$%(compiler)s_PATH
+```
+
+##### CMake config commands
In each config group, values of following 9 TF-M build config parameters in *seed_params* are combined to generate all configs covered in this group.
@@ -904,9 +924,20 @@
}
```
-The combination of these 9 *seed_params* is filled into the [build config template](https://git.trustedfirmware.org/ci/tf-m-ci-scripts.git/tree/build_helper/build_helper_configs.py?h=TF-Mv1.8.0#n48) by Build Helper and finally generates the complete TF-M build command for this config.
+The combination of these 9 *seed_params* is filled into the [build config template](https://git.trustedfirmware.org/ci/tf-m-ci-scripts.git/tree/build_helper/build_helper_configs.py?h=TF-Mv1.8.0#n48) by Build Helper and finally generates the complete CMake config command for this config.
-To add some specific TF-M build parameters into the build command, a map of *"abbreviation: build command"* is added to [mapExtraParams](https://git.trustedfirmware.org/ci/tf-m-ci-scripts.git/tree/build_helper/build_helper_config_maps.py?h=TF-Mv1.8.0#n56) in build_helper_config_maps.py, and the abbreviation is added to *extra_params*. For example, *"PSOFF"* in config group *config_profile_m_arotless* is the abbreviation of build config *"-DTFM_PARTITION_PROTECTED_STORAGE=OFF "*.
+To add some specific CMake config parameters into the command, a map of *"abbreviation: config command"* is added to [mapExtraParams](https://git.trustedfirmware.org/ci/tf-m-ci-scripts.git/tree/build_helper/build_helper_config_maps.py?h=TF-Mv1.8.0#n56) in build_helper_config_maps.py, and the abbreviation is added to *extra_params*. For example, *"PSOFF"* in config group *config_profile_m_arotless* is the abbreviation of build config *"-DTFM_PARTITION_PROTECTED_STORAGE=OFF "*.
+
+##### CMake build command
+
+After CMake config is done, command for CMake build and install needs to be run. Typically the command is:
+```
+cmake --build <build_dir> -- install
+```
+
+##### Post build commands
+
+If any extra command is needed by some platforms after building TF-M by CMake, the command is added to [post_build](https://git.trustedfirmware.org/ci/tf-m-ci-scripts.git/tree/build_helper/build_helper_configs.py?h=refs/heads/master#n78). For example, Musca B1 needs to run *srec_cat* command to generate the final image, the command is added [here](https://git.trustedfirmware.org/ci/tf-m-ci-scripts.git/tree/build_helper/build_helper_configs.py?h=refs/heads/master#n78).
#### Filter out invalid configs
@@ -932,10 +963,6 @@
}
```
-#### Extra commands after building TF-M
-
-If any extra command is needed by some platforms after building TF-M, the command is added to [build_cmds](https://git.trustedfirmware.org/ci/tf-m-ci-scripts.git/tree/build_helper/build_helper_configs.py?h=TF-Mv1.8.0#n76). For example, Musca B1 needs to run *srec_cat* command to generate the final image, the command is added [here](https://git.trustedfirmware.org/ci/tf-m-ci-scripts.git/tree/build_helper/build_helper_configs.py?h=TF-Mv1.8.0#n77).
-
#### Config name format
To keep the config name short and clear, config tuple is converted to string in a brief format, by using abbreviations to map the long config parameters into a shorter format in [build_helper_config_maps.py](https://git.trustedfirmware.org/ci/tf-m-ci-scripts.git/tree/build_helper/build_helper_config_maps.py?h=TF-Mv1.8.0). The detailed conversion logic is [here](https://git.trustedfirmware.org/ci/tf-m-ci-scripts.git/tree/tfm_ci_pylib/tfm_build_manager.py?h=TF-Mv1.8.0#n573).
@@ -948,22 +975,22 @@
2. Run the following commands locally to verify whether the new config group works as expected.
- To generate all configs covered in the new config group, run command:
+ To list all configs covered in the new config group, run command:
```
python3 <path of tf-m-ci-scripts>/configs.py -g <group_name>
```
- To get build command for a specific config generated by Build Helper, run command:
+ To get specific type of commands (set_compiler, cmake_config, cmake_build, post_build) for a config generated by Build Helper, run command:
```
- python3 <path of tf-m-ci-scripts>/configs.py -b <config_name>
+ python3 <path of tf-m-ci-scripts>/configs.py <config_name> -b <command_type>
```
- To get the detailed values of each build parameters of a specifig config, run command:
+ To get the detailed values of each build parameters of a config, run command:
```
- python3 <path of tf-m-ci-scripts>/configs.py <config_name>
+ python3 <path of tf-m-ci-scripts>/configs.py <config_name> --config_params
```
3. Enable the new config group by adding it as the default group in job configs. Please take this patch for reference: https://review.trustedfirmware.org/c/ci/tf-m-job-configs/+/17841