index.md: Fix docs format
Signed-off-by: Xinyu Zhang <xinyu.zhang@arm.com>
Change-Id: I56f75af74e1abbda9ae0a0bb92cd09048d4667a3
diff --git a/docs/index.md b/docs/index.md
index ee0e3d4..6c67091 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -295,15 +295,20 @@
## TF-M CI pipeline description
### Job classification
-TF-M jobs can be found at https://ci.trustedfirmware.org/view/TF-M/ and classified by use cases.
+TF-M jobs can be found at [https://ci.trustedfirmware.org/view/TF-M](https://ci.trustedfirmware.org/view/TF-M) and classified by use cases.
#### Per-patch job
Per-patch job is triggered by option *Allow-CI* in the _Reply_ button of each Gerrit review item to verify TF-M patches before merge. The job votes to Gerrit with a Code Review +1 if it passed and Code Review -1 once failed.
-<div style="text-align: center"><img src="images/TFM-images/TFM-per-patch-workflow.png" alt="alt text" title="Per-patch workflow" width=100%/><div style="text-align: left">
+<figure markdown>
+ <div style="text-align: center">
+ <img src="images/TFM-images/TFM-per-patch-workflow.png" alt="alt text" title="Per-patch workflow" width=100%/>
+ </div>
+</figure>
Following checks are covered in per-patch job:
+
* __Static check__: Include tf-m-cppcheck (using [CppCheck](https://cppcheck.sourceforge.io/)), tf-m-checkpatch (using [CheckPatch](https://github.com/torvalds/linux/blob/v5.9/scripts/checkpatch.pl)) and tf-m-static-checks (checking trailing spaces, etc.), which are three independent jobs.
* __Build configs__: Build TF-M images with tf-m-build-config jobs in parallel. Each job builds one config. Configs built by per-patch job are listed [here](https://ci.trustedfirmware.org/view/TF-M/job/tf-m-build-and-test/lastSuccessfulBuild/artifact/build_links.html).
* __Build docs__: Build TF-M [user guide](https://ci.trustedfirmware.org/job/tf-m-build-docs/lastSuccessfulBuild/artifact/trusted-firmware-m/build/docs/user_guide/html/index.html) and [reference manual](https://ci.trustedfirmware.org/job/tf-m-build-docs/lastSuccessfulBuild/artifact/trusted-firmware-m/build/docs/reference_manual/html/index.html) based on the current patch.
@@ -311,15 +316,24 @@
Every check job generates a vote to Gerrit with corresponding job link. There wil be a final __Verified +1__ from _TrustedFirmware Code Review_ once all checks passed. Otherwise a __Verfied -1__ will be voted.
-<div style="text-align: center"><img src="images/TFM-images/TFM-per-patch-vote.png" alt="alt text" title="Per-patch vote +1 to Gerrit" width=65%/><div style="text-align: left">
+<figure markdown>
+ <div style="text-align: center">
+ <img src="images/TFM-images/TFM-per-patch-vote.png" alt="alt text" title="Per-patch vote +1 to Gerrit" width=65%/>
+ </div>
+</figure>
#### 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.
-<div style="text-align: center"><img src="images/TFM-images/TFM-nightly-workflow.png" alt="alt text" title="Nighty workflow" width=100%/><div style="text-align: left">
+<figure markdown>
+ <div style="text-align: center">
+ <img src="images/TFM-images/TFM-nightly-workflow.png" alt="alt text" title="Nighty workflow" width=100%/>
+ </div>
+</figure>
Following checks are covered in nightly job:
+
* __Build configs__: Configs built by nightly job are listed [here](https://ci.trustedfirmware.org/view/TF-M/job/tf-m-nightly/lastSuccessfulBuild/artifact/build_links.html).
* __Build docs__: Build TF-M [user guide](https://tf-m-user-guide.trustedfirmware.org/) and [reference manual](https://ci.trustedfirmware.org/job/tf-m-build-docs-nightly/lastSuccessfulBuild/artifact/trusted-firmware-m/build/docs/reference_manual/html/index.html) based on the latest TF-M master branch and posted to [trustedfirmware.org](https://www.trustedfirmware.org/).
* __Test images__: Tests on following devices are covered in nightly job: AN519 FVP, AN521 FVP, AN521 FPGA, AN521 QEMU, AN552 FVP, Corstone1000 FVP, STM32L562E_DK, NXP/lpcxpresso55s69 and Cypress/PSOC64.
@@ -328,9 +342,14 @@
Release job is scheduled bi-weekly to make sure the latest TF-M on master branch could pass all release tests. It will also be manually triggered for release branch during release stage.
-<div style="text-align: center"><img src="images/TFM-images/TFM-release-workflow.png" alt="alt text" title="Release workflow" width=100%/><div style="text-align: left">
+<figure markdown>
+ <div style="text-align: center">
+ <img src="images/TFM-images/TFM-release-workflow.png" alt="alt text" title="Release workflow" width=100%/>
+ </div>
+</figure>
Following checks are covered in release job:
+
* __Build configs__: Configs built by release job are listed [here](https://ci.trustedfirmware.org/view/TF-M/job/tf-m-release/lastSuccessfulBuild/artifact/build_links.html).
* __Build docs__: Build TF-M [user guide](https://ci.trustedfirmware.org/job/tf-m-build-docs/lastSuccessfulBuild/artifact/trusted-firmware-m/build/docs/user_guide/html/index.html) and [reference manual](https://ci.trustedfirmware.org/job/tf-m-build-docs/lastSuccessfulBuild/artifact/trusted-firmware-m/build/docs/reference_manual/html/index.html) based on the current HEAD of master/release branch.
* __Test images__: Tests on following devices are covered in release job: AN519 FVP, AN521 FVP, AN521 FPGA, AN521 QEMU, AN552 FVP, Corstone1000 FVP, STM32L562E_DK, NXP/lpcxpresso55s69 and Cypress/PSOC64.
@@ -339,9 +358,14 @@
Code coverage job is scheduled weekly to monitor the code coverage of tests in the latest TF-M on master branch.
-<div style="text-align: center"><img src="images/TFM-images/TFM-cc-workflow.png" alt="alt text" title="Code coverage workflow" width=100%/><div style="text-align: left">
+<figure markdown>
+ <div style="text-align: center">
+ <img src="images/TFM-images/TFM-cc-workflow.png" alt="alt text" title="Code coverage workflow" width=100%/>
+ </div>
+</figure>
Following configs are covered in code coverage job:
+
* __Build configs__: Configs built by code coverage job are listed [here](https://ci.trustedfirmware.org/job/tf-m-code-coverage/lastSuccessfulBuild/artifact/build_links.html).
* __Test images__: Tests on AN521 FVP will be traced by [qa-tool](https://git.trustedfirmware.org/ci/qa-tools.git) to get the code coverage data.
@@ -351,27 +375,47 @@
Extra build job is daily scheduled to check whether the latest TF-M could be correctly built for platforms supported by TF-M. Images are only built but not tested in this job. Configs built by extra build job are listed [here](https://ci.trustedfirmware.org/view/TF-M/job/tf-m-extra-build/lastSuccessfulBuild/artifact/build_links.html).
-<div style="text-align: center"><img src="images/TFM-images/TFM-extra-build-workflow.png" alt="alt text" title="Extra build workflow" width=50%/><div style="text-align: left">
+<figure markdown>
+ <div style="text-align: center">
+ <img src="images/TFM-images/TFM-extra-build-workflow.png" alt="alt text" title="Extra build workflow" width=50%/>
+ </div>
+</figure>
### Job logs
For detailed logs, please go to the job link and choose __Console Output__ at the left column of the page.
-<div style="text-align: center"><img src="images/TFM-images/TFM-console-output.png" alt="alt text" title="Console Output" width=30%/><div style="text-align: left">
+<figure markdown>
+ <div style="text-align: center">
+ <img src="images/TFM-images/TFM-console-output.png" alt="alt text" title="Console Output" width=30%/>
+ </div>
+</figure>
And then search for the key word needs to be checked.
For example, search for "fail" to see the error cause.
-<div style="text-align: center"><img src="images/TFM-images/TFM-failure-log.png" alt="alt text" title="Failure Log" width=80%/><div style="text-align: left">
+<figure markdown>
+ <div style="text-align: center">
+ <img src="images/TFM-images/TFM-failure-log.png" alt="alt text" title="Failure Log" width=80%/>
+ </div>
+</figure>
Or seach for config name that needs to be checked.
-<div style="text-align: center"><img src="images/TFM-images/TFM-build-config-log.png" alt="alt text" title="Build Config Log" width=90%/><div style="text-align: left">
+<figure markdown>
+ <div style="text-align: center">
+ <img src="images/TFM-images/TFM-build-config-log.png" alt="alt text" title="Build Config Log" width=90%/>
+ </div>
+</figure>
-* __NOTE__: If LAVA test is run on FVP, LAVA link is only accessible to authorized users. Please check __TFM LOG__ to find the test result. If access to LAVA job is necessary, please contact tf-openci@lists.trustedfirmware.org for help.
+* __NOTE__: If LAVA test is run on FVP, LAVA link is only accessible to authorized users. Please check __TFM LOG__ to find the test result. If access to LAVA job is necessary, please contact [tf-openci@lists.trustedfirmware.org](tf-openci@lists.trustedfirmware.org) for help.
-<div style="text-align: center"><img src="images/TFM-images/TFM-FVP-test.png" alt="alt text" title="FVP test" width=60%/><div style="text-align: left">
+<figure markdown>
+ <div style="text-align: center">
+ <img src="images/TFM-images/TFM-FVP-test.png" alt="alt text" title="FVP test" width=60%/>
+ </div>
+</figure>
### Job artifacts
@@ -380,7 +424,11 @@
* __Build binary__: TF-M build binary of each config is available in corresponding tf-m-build-config job.
* __Result summary__: Summary of all build and test results in both csv and html formats are available in artifacts of tf-m-build-and-test, tf-m-nightly and tf-m-release correspondingly for per-patch, nightly and release jobs.
-<div style="text-align: center"><img src="images/TFM-images/TFM-result-summary.png" alt="alt text" title="Result Summary" width=40%/><div style="text-align: left">
+<figure markdown>
+ <div style="text-align: center">
+ <img src="images/TFM-images/TFM-result-summary.png" alt="alt text" title="Result Summary" width=40%/>
+ </div>
+</figure>
### Build environment
@@ -388,7 +436,11 @@
There are different versions of toolchain installed in CI workspace. Each tf-m-build-config job selects the needed version automatically. To check the chosen toolchain, search for the name of toolchain (arm-none-eabi-gcc, armclang) in the job console.
-<div style="text-align: center"><img src="images/TFM-images/TFM-toolchain-version.png" alt="alt text" title="Toolchain Version" width=50%/><div style="text-align: left">
+<figure markdown>
+ <div style="text-align: center">
+ <img src="images/TFM-images/TFM-toolchain-version.png" alt="alt text" title="Toolchain Version" width=50%/>
+ </div>
+</figure>
#### Dependencies
@@ -777,10 +829,12 @@
## TF-M CI scripts overview
TF-M Open CI has two repos:
+
* [tf-m-job-configs](https://git.trustedfirmware.org/ci/tf-m-job-configs.git): Job configs in [Jenkins Job Builder](#the-tf-jenkins-job-builder-jjb-configs) format.
* [tf-m-ci-scripts](https://git.trustedfirmware.org/ci/tf-m-ci-scripts.git): Scripts that run in Jenkins to build and test TF-M.
CI scripts use 2 tools to generate commands:
+
* Build helper: Generate commands for building TF-M images.
* LAVA helper: Generate config files for [LAVA instance](#tf-lava-instance) to run TF-M images and monitor the test results.
@@ -792,7 +846,11 @@
Build helper categorizes all the TF-M configs that are built in CI into different [groups](https://git.trustedfirmware.org/ci/tf-m-ci-scripts.git/tree/build_helper/build_helper_configs.py?h=refs/heads/release/1.7.x#n937), depending on CI jobs. The config groups for each CI job are set as the default value of [Filter Group](https://git.trustedfirmware.org/ci/tf-m-job-configs.git/tree/tf-m-nightly.yaml?h=refs/heads/release/1.7.x#n24), which is configured by [tf-m-job-configs](https://git.trustedfirmware.org/ci/tf-m-job-configs.git).
-<div style="text-align: center"><img src="images/TFM-images/TFM-filter-group.png" alt="alt text" title="Filter Group" width=70%/><div style="text-align: left">
+<figure markdown>
+ <div style="text-align: center">
+ <img src="images/TFM-images/TFM-filter-group.png" alt="alt text" title="Filter Group" width=70%/>
+ </div>
+</figure>
#### Generate CMake build command
@@ -812,21 +870,21 @@
For example, in config group [config_profile_m_arotless](https://git.trustedfirmware.org/ci/tf-m-ci-scripts.git/tree/build_helper/build_helper_configs.py?h=refs/heads/release/1.7.x#n376), 24 configs are generated by combining values in each seed params.
-``` python3
+```
config_profile_m_arotless = {"seed_params": {
- "tfm_platform": ["arm/musca_b1"],
- "compiler": ["GCC_10_3", "ARMCLANG_6_13"],
- "isolation_level": ["1"],
- "test_regression": [True, False],
- "test_psa_api": ["OFF"],
- "cmake_build_type": ["Debug", "Release", "Minsizerel"],
- "with_bl2": [True],
- "profile": ["profile_medium_arotless"],
- "extra_params": ["", "PSOFF"]
- },
- "common_params": _common_tfm_builder_cfg,
- "invalid": _common_tfm_invalid_configs + []
- }
+ "tfm_platform": ["arm/musca_b1"],
+ "compiler": ["GCC_10_3", "ARMCLANG_6_13"],
+ "isolation_level": ["1"],
+ "test_regression": [True, False],
+ "test_psa_api": ["OFF"],
+ "cmake_build_type": ["Debug", "Release", "Minsizerel"],
+ "with_bl2": [True],
+ "profile": ["profile_medium_arotless"],
+ "extra_params": ["", "PSOFF"]
+ },
+ "common_params": _common_tfm_builder_cfg,
+ "invalid": _common_tfm_invalid_configs + []
+ }
```
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=refs/heads/release/1.7.x#n48) by Build Helper and finally generates the complete TF-M build command for this config.
@@ -837,24 +895,24 @@
To filter out specific configs from the config group, a config tuple with all the 9 seed params in sequence is added to the *invalid* list. Character "\*" stands for all values of the corresponding config parameter. For example, in config group *config_profile_s*, all configs for AN519 built with GCC v10.3 in Minsizerel type is not contained in this group.
-``` python3
+```
config_profile_s = {"seed_params": {
- "tfm_platform": ["arm/mps2/an519", "arm/mps2/an521"],
- "compiler": ["GCC_10_3", "ARMCLANG_6_13"],
- "isolation_level": ["1"],
- "test_regression": [True, False],
- "test_psa_api": ["OFF"],
- "cmake_build_type": ["Debug", "Release", "Minsizerel"],
- "with_bl2": [True],
- "profile": ["profile_small"],
- "extra_params": ["PSOFF"]
- },
- "common_params": _common_tfm_builder_cfg,
- "invalid": _common_tfm_invalid_configs + [
- ("arm/mps2/an519", "GCC_10_3", "*", "*",
- "*", "Minsizerel", "*", "*", "*")
- ]
- }
+ "tfm_platform": ["arm/mps2/an519", "arm/mps2/an521"],
+ "compiler": ["GCC_10_3", "ARMCLANG_6_13"],
+ "isolation_level": ["1"],
+ "test_regression": [True, False],
+ "test_psa_api": ["OFF"],
+ "cmake_build_type": ["Debug", "Release", "Minsizerel"],
+ "with_bl2": [True],
+ "profile": ["profile_small"],
+ "extra_params": ["PSOFF"]
+ },
+ "common_params": _common_tfm_builder_cfg,
+ "invalid": _common_tfm_invalid_configs + [
+ ("arm/mps2/an519", "GCC_10_3", "*", "*",
+ "*", "Minsizerel", "*", "*", "*")
+ ]
+ }
```
#### Extra commands after building TF-M
@@ -868,28 +926,32 @@
#### How to add new configs
To support new TF-M features, it is recommanded to add a new config group for the new feature. Following steps are needed:
+
1. Add new config group in CI scripts. Please take this patch for reference: https://review.trustedfirmware.org/c/ci/tf-m-ci-scripts/+/17665
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:
- ``` bash
+
+ ```
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:
- ``` bash
+
+ ```
python3 <path of tf-m-ci-scripts>/configs.py -b <config_name>
```
To get the detailed values of each build parameters of a specifig config, run command:
- ``` bash
+
+ ```
python3 <path of tf-m-ci-scripts>/configs.py <config_name>
```
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
-4. Verify the changes on Staging CI. For details please refer to [Staging Trusted Firmware System](#staging-trusted-firmware-system) section. If any permission is needed, please contact tf-openci@lists.trustedfirmware.org for help.
+4. Verify the changes on Staging CI. For details please refer to [Staging Trusted Firmware System](#staging-trusted-firmware-system) section. If any permission is needed, please contact [tf-openci@lists.trustedfirmware.org](tf-openci@lists.trustedfirmware.org) for help.
### LAVA helper
@@ -902,6 +964,7 @@
To decide whether the test run as expected, LAVA server uses __*monitors*__ to monitor the target log strings. Once the specified string is matched by LAVA monitor before timeout, it means that the test works as expected. Otherwise the tests fail.
There are five kinds of LAVA monitors defined in TF-M Open CI:
+
* [monitors_no_reg_tests](https://git.trustedfirmware.org/ci/tf-m-ci-scripts.git/tree/lava_helper/lava_helper_configs.py?h=refs/heads/release/1.7.x#n33): Applied when regression tests are disabled.
* [monitors_mcuboot_tests](https://git.trustedfirmware.org/ci/tf-m-ci-scripts.git/tree/lava_helper/lava_helper_configs.py?h=refs/heads/release/1.7.x#n44): Applied when BL2 tests are enabled.
* [monitors_s_reg_tests](https://git.trustedfirmware.org/ci/tf-m-ci-scripts.git/tree/lava_helper/lava_helper_configs.py?h=refs/heads/release/1.7.x#n52): Applied when secure regression tests are enabled.
@@ -912,9 +975,9 @@
Platforms of [trustedfirmware.org](https://www.trustedfirmware.org/) members can be added to Open CI.
-To add physical boards, please contact tf-openci@lists.trustedfirmware.org for help.
+To add physical boards, please contact [tf-openci@lists.trustedfirmware.org](tf-openci@lists.trustedfirmware.org) for help.
-To add FVP, please follow the instructions in [FVP Doker Images](#fvp-docker-images) to upload the new FVP image. If any permission or resources are needed, please contact tf-openci@lists.trustedfirmware.org for help.
+To add FVP, please follow the instructions in [FVP Doker Images](#fvp-docker-images) to upload the new FVP image. If any permission or resources are needed, please contact [tf-openci@lists.trustedfirmware.org](tf-openci@lists.trustedfirmware.org) for help.
# TF LAVA Instance