1.. SPDX-License-Identifier: BSD-3-Clause 2.. SPDX-FileCopyrightText: Copyright TF-RMM Contributors. 3 4 5.. _build_options_examples: 6 7##################### 8RMM Build Examples 9##################### 10 11The |RMM| supports a wide range of build configuration options. Some of these options 12are more regularly exercised by developers, while others are for **advanced** and 13**experimental** usage only. 14 15|RMM| can be built using either GNU(GCC) or :ref:`LLVM(Clang)<llvm_build>` 16toolchain. See :ref:`this section<getting_started_toolchain>` for toolchain 17setup and the supported versions. 18 19The build is performed in 2 stages: 20 21**Configure Stage:** In this stage, a default config file can be specified which configures 22a sane config for the chosen platform. If this default config needs to be modified, it is 23recommended to first perform a default config and then modify using the cmake ncurses as 24shown in :ref:`CMake UI Example<build_config_example>`. 25 26**Build Stage:** In this stage, the source build is performed by specifying the `--build` option. 27See any of the commands below for an example. 28 29.. note:: 30 31 It is recommended to clean build if any of the build options are changed from previous build. 32 33Below are some of the typical build and configuration examples frequently used in |RMM| development 34for the FVP Platform. Detailed configuration options are described :ref:`here<build_options_table>`. 35 36RMM also supports a ``fake_host`` build which can be used to build RMM for test 37and code analysis on the host machine. See 38:ref:`this section here<fake_host_build>` for more details. 39 401. Perform an initial default build with minimum configuration options: 41 42Build using gnu toolchain 43 44.. code-block:: bash 45 46 cmake -DRMM_CONFIG=fvp_defcfg -S ${RMM_SOURCE_DIR} -B ${RMM_BUILD_DIR} 47 cmake --build ${RMM_BUILD_DIR} 48 49Build using LLVM toolchain 50 51.. code-block:: bash 52 53 cmake -DRMM_CONFIG=fvp_defcfg -DRMM_TOOLCHAIN=llvm -S ${RMM_SOURCE_DIR} -B ${RMM_BUILD_DIR} 54 cmake --build ${RMM_BUILD_DIR} 55 56.. _build_config_example: 57 582. Perform an initial default config, then modify using ccmake ncurses UI: 59 60.. code-block:: bash 61 62 cmake -DRMM_CONFIG=fvp_defcfg -S ${RMM_SOURCE_DIR} -B ${RMM_BUILD_DIR} 63 ccmake -S ${RMM_SOURCE_DIR} -B ${RMM_BUILD_DIR} 64 cmake --build ${RMM_BUILD_DIR} 65 663. Perform a debug build and specify a log level: 67 68.. code-block:: bash 69 70 cmake -DRMM_CONFIG=fvp_defcfg -S ${RMM_SOURCE_DIR} -B ${RMM_BUILD_DIR} -DCMAKE_BUILD_TYPE=Debug -DLOG_LEVEL=50 71 cmake --build ${RMM_BUILD_DIR} 72 734. Perform a documentation build: 74 75.. code-block:: bash 76 77 cmake -DRMM_CONFIG=fvp_defcfg -S ${RMM_SOURCE_DIR} -B ${RMM_BUILD_DIR} -DRMM_DOCS=ON 78 cmake --build ${RMM_BUILD_DIR} -- docs 79 805. Perform a clean verbose build: 81 82.. code-block:: bash 83 84 cmake -DRMM_CONFIG=fvp_defcfg -S ${RMM_SOURCE_DIR} -B ${RMM_BUILD_DIR} 85 cmake --build ${RMM_BUILD_DIR} --clean-first --verbose 86 876. Perform a build with Ninja Genenerator: 88 89.. code-block:: bash 90 91 cmake -DRMM_CONFIG=fvp_defcfg -S ${RMM_SOURCE_DIR} -B ${RMM_BUILD_DIR} -DCMAKE_BUILD_TYPE=${BUILD_TYPE} -G "Ninja" -DLOG_LEVEL=50 92 cmake --build ${RMM_BUILD_DIR} 93 947. Perform a build with Ninja Multi Config Genenerator: 95 96.. code-block:: bash 97 98 cmake -DRMM_CONFIG=fvp_defcfg -S ${RMM_SOURCE_DIR} -B ${RMM_BUILD_DIR} -G "Ninja Multi-Config" -DLOG_LEVEL=50 99 cmake --build ${RMM_BUILD_DIR} --config ${BUILD_TYPE} 100 1018. Perform a Cppcheck static analysis: 102 103Refer to :ref:`Cppcheck Application Note` for details on installing and running cppcheck 104static analysis. 105 106.. code-block:: bash 107 108 cmake -DRMM_CONFIG=fvp_defcfg -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -S ${RMM_SOURCE_DIR} -B ${RMM_BUILD_DIR} 109 cmake --build ${RMM_BUILD_DIR} -- cppcheck 110 cat ${RMM_BUILD_DIR}/tools/cppcheck/cppcheck.xml 111 1129. Perform a Cppcheck static analysis with MISRA: 113 114Refer to :ref:`Cppcheck Application Note` for details on installing and running cppcheck 115static analysis. 116 117.. code-block:: bash 118 119 cmake -DRMM_CONFIG=fvp_defcfg -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -S ${RMM_SOURCE_DIR} -B ${RMM_BUILD_DIR} 120 cmake --build ${RMM_BUILD_DIR} -- cppcheck-misra 121 cat ${RMM_BUILD_DIR}/tools/cppcheck/cppcheck_misra.xml 122 12310. Perform a checkpatch analysis: 124 125Run checkpatch on commits in the current branch against BASE_COMMIT (default origin/master): 126 127.. code-block:: bash 128 129 cmake -DRMM_CONFIG=fvp_defcfg -S ${RMM_SOURCE_DIR} -B ${RMM_BUILD_DIR} 130 cmake --build ${RMM_BUILD_DIR} -- checkpatch 131 132Run checkpatch on entire codebase: 133 134.. code-block:: bash 135 136 cmake -DRMM_CONFIG=fvp_defcfg -S ${RMM_SOURCE_DIR} -B ${RMM_BUILD_DIR} 137 cmake --build ${RMM_BUILD_DIR} -- checkcodebase 138 13911. Perform a checkspdx analysis: 140 141Run checkspdx on commits in the current branch against BASE_COMMIT (default origin/master): 142 143.. code-block:: bash 144 145 cmake -DRMM_CONFIG=fvp_defcfg -S ${RMM_SOURCE_DIR} -B ${RMM_BUILD_DIR} 146 cmake --build ${RMM_BUILD_DIR} -- checkspdx-patch 147 148Run checkspdx on entire codebase: 149 150.. code-block:: bash 151 152 cmake -DRMM_CONFIG=fvp_defcfg -S ${RMM_SOURCE_DIR} -B ${RMM_BUILD_DIR} 153 cmake --build ${RMM_BUILD_DIR} -- checkspdx-codebase 154 15513. Check header file include order: 156 157Run checkincludes-patch on commits in the current branch against BASE_COMMIT (default origin/master): 158 159.. code-block:: bash 160 161 cmake -DRMM_CONFIG=fvp_defcfg -S ${RMM_SOURCE_DIR} -B ${RMM_BUILD_DIR} 162 cmake --build ${RMM_BUILD_DIR} -- checkincludes-patch 163 164Run checkincludes on entire codebase: 165 166.. code-block:: bash 167 168 cmake -DRMM_CONFIG=fvp_defcfg -S ${RMM_SOURCE_DIR} -B ${RMM_BUILD_DIR} 169 cmake --build ${RMM_BUILD_DIR} -- checkincludes-codebase 170 17114. Perform a clang-tidy analysis: 172 173Run clang-tidy on commits in the current branch against BASE_COMMIT (default 174origin/master): 175 176.. code-block:: bash 177 178 cmake -DRMM_CONFIG=fvp_defcfg -DRMM_TOOLCHAIN=llvm -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -S ${RMM_SOURCE_DIR} -B ${RMM_BUILD_DIR} 179 cmake --build ${RMM_BUILD_DIR} -- clang-tidy-patch 180 181Run clang-tidy on entire codebase: 182 183.. code-block:: bash 184 185 cmake -DRMM_CONFIG=fvp_defcfg -DRMM_TOOLCHAIN=llvm -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -S ${RMM_SOURCE_DIR} -B ${RMM_BUILD_DIR} 186 cmake --build ${RMM_BUILD_DIR} -- clang-tidy-codebase 187 188Note that clang-tidy will work with all configurations. It will only check the 189source files that are used for the specified configuration. 190 19115. Perform unit tests on development host: 192 193Build and run unit tests on host platform. It is recommended to enable the 194Debug build of RMM. 195 196.. code-block:: bash 197 198 cmake -DRMM_CONFIG=host_defcfg -DHOST_VARIANT=host_test -DCMAKE_BUILD_TYPE=Debug -S ${RMM_SOURCE_DIR} -B ${RMM_BUILD_DIR} 199 cmake --build ${RMM_BUILD_DIR} -- run-unittests 200 201Run unittests for a specific test group(s) (e.g. unittests whose group starts with 'xlat') 202 203.. code-block:: bash 204 205 cmake -DRMM_CONFIG=host_defcfg -DHOST_VARIANT=host_test -DCMAKE_BUILD_TYPE=Debug -S ${RMM_SOURCE_DIR} -B ${RMM_BUILD_DIR} 206 cmake --build ${RMM_BUILD_DIR} -- build -j 207 ${RMM_BUILD_DIR}/Debug/rmm_core.elf -gxlat -v -r${NUMBER_OF_TEST_ITERATIONS} 208 20916. Generate Coverage Report. 210 211It is possible to generate a coverage report for a last execution of the host 212platform (whichever the variant) by using the `run-coverage` build target. 213 214For example, to generate coverate report on the whole set of unittests: 215 216.. code-block:: bash 217 218 cmake -DRMM_CONFIG=host_defcfg -DHOST_VARIANT=host_test -DRMM_COVERAGE=ON -DCMAKE_BUILD_TYPE=Debug -S ${RMM_SOURCE_DIR} -B ${RMM_BUILD_DIR} 219 cmake --build ${RMM_BUILD_DIR} -- run-unittests 220 cmake --build ${RMM_BUILD_DIR} -- run-coverage 221 222Run coverage analysis on a specific set of unittests (e.g. unittests whose group starts with 'xlat') 223 224.. code-block:: bash 225 226 cmake -DRMM_CONFIG=host_defcfg -DHOST_VARIANT=host_test -DRMM_COVERAGE=ON -DCMAKE_BUILD_TYPE=Debug -S ${RMM_SOURCE_DIR} -B ${RMM_BUILD_DIR} 227 cmake --build ${RMM_BUILD_DIR} -- build -j 228 ${RMM_BUILD_DIR}/Debug/rmm_core.elf -gxlat 229 cmake --build ${RMM_BUILD_DIR} -- run-coverage 230 231Run coverage analysis on the `host_build` variant of host platform: 232 233.. code-block:: bash 234 235 cmake -DRMM_CONFIG=host_defcfg -DHOST_VARIANT=host_build -DRMM_COVERAGE=ON -DCMAKE_BUILD_TYPE=Debug -S ${RMM_SOURCE_DIR} -B ${RMM_BUILD_DIR} 236 ${RMM_BUILD_DIR}/Debug/rmm_core.elf 237 cmake --build ${RMM_BUILD_DIR} -- run-coverage 238 239The above commands will automatically generate the HTML coverage report in folder 240`build/Debug/coverage` within the build directory. The HTML generation can be 241disabled by setting `RMM_HTML_COV_REPORT=OFF`. 242 24317. Run CBMC analysis: 244 245Run ``COVERAGE``, ``ANALYSIS`` and ``ASSERT`` targets for CBMC. The results 246are generated in ``${RMM_BUILD_DIR}/tools/cbmc/cbmc_coverage_results``. 247 248.. code-block:: bash 249 250 cmake -DRMM_CONFIG=host_defcfg -DHOST_VARIANT=host_cbmc -S ${RMM_SOURCE_DIR} -B ${RMM_BUILD_DIR} 251 cmake --build ${RMM_BUILD_DIR} -- cbmc-coverage cbmc-analysis cbmc-assert 252 253Refer to :ref:`CBMC` Application Note for details on installing and running CBMC. 254 255.. _build_options_table: 256 257################### 258RMM Build Options 259################### 260 261The |RMM| build system supports the following CMake build options. 262 263.. csv-table:: RMM CMake Options Table 264 :header: "Option", "Valid values", "Default", "Description" 265 266 RMM_CONFIG , , ,"Platform build configuration, eg: fvp_defcfg for the FVP" 267 RMM_ARCH ,aarch64 | fake_host ,aarch64 ,"Target Architecture for RMM build" 268 RMM_MAX_SIZE , ,0x0 ,"Maximum size for RMM image" 269 MAX_CPUS , ,16 ,"Maximum number of CPUs supported by RMM" 270 GRANULE_SHIFT , ,12 ,"Granule Shift used by RMM" 271 RMM_CCA_TOKEN_BUFFER , ,1 ,"Number of pages to allocate in Aux granules for Realm CCA token" 272 RMM_DOCS ,ON | OFF ,OFF ,"RMM Documentation build" 273 CMAKE_BUILD_TYPE ,Debug | Release ,Release ,"CMake Build type" 274 CMAKE_CONFIGURATION_TYPES ,Debug & Release ,Debug & Release ,"Multi-generator configuration types" 275 CMAKE_DEFAULT_BUILD_TYPE ,Debug | Release ,Release ,"Default multi-generator configuration type" 276 RMM_PLATFORM ,fvp | host , ,"Platform to build" 277 RMM_TOOLCHAIN ,gnu | llvm , ,"Toolchain name" 278 LOG_LEVEL ,0 - 50 ,40(Debug) 20(Release) ,"Log level to apply for RMM (0 - 50)." 279 RMM_STATIC_ANALYSIS , , ,"Enable static analysis checkers" 280 PL011_GENERIC_SBSA_UART ,ON | OFF ,OFF ,"Enable Generic (SBSA Compliant) PL011. This a subset of PL011 UART" 281 PLAT_CMN_CTX_MAX_XLAT_TABLES , ,0 ,"Maximum number of translation tables used by the runtime context" 282 PLAT_CMN_EXTRA_MMAP_REGIONS , ,0 ,"Extra platform mmap regions that need to be mapped in S1 xlat tables" 283 PLAT_CMN_VIRT_ADDR_SPACE_WIDTH, ,38 ,"Stage 1 Virtual address space width in bits for this platform" 284 RMM_NUM_PAGES_PER_STACK , ,5 ,"Number of pages to use per CPU stack" 285 MBEDTLS_ECP_MAX_OPS ,248 - ,1000 ,"Number of max operations per ECC signing iteration" 286 RMM_FPU_USE_AT_REL2 ,ON | OFF ,OFF(fake_host) ON(aarch64),"Enable FPU/SIMD usage in RMM." 287 RMM_MAX_GRANULES , ,0 ,"Maximum number of memory granules available to the system" 288 RMM_MAX_COH_GRANULES , ,1 ,"Maximum number of coherent device granules available to the system" 289 RMM_MAX_NCOH_GRANULES , ,1 ,"Maximum number of non-coherent device granules available to the system" 290 HOST_VARIANT ,host_build | host_test | host_cbmc ,host_build ,"Variant to build for the host platform. Only available when RMM_PLATFORM=host" 291 HOST_DRAM_SIZE , ,0x20000000 ,"Host memory size that will be used as physical DRAM" 292 HOST_NCOH_DEV_SIZE , ,0xA000 ,"Host memory size that will be used as non-coherent device granules" 293 RMM_COVERAGE ,ON | OFF ,OFF ,"Enable coverage analysis" 294 RMM_HTML_COV_REPORT ,ON | OFF ,ON ,"Enable HTML output report for coverage analysis" 295 RMM_CBMC_VIEWER_OUTPUT ,ON | OFF ,OFF ,"Generate report of CBMC results using the tool cbmc-viewer" 296 RMM_CBMC_SINGLE_TESTBENCH , ,OFF ,"Run CBMC on a single testbench instead on all of them" 297 RMM_V1_1 ,ON | OFF ,OFF ,"Enable v1.1 features (experimental)" 298 ATTEST_PLAT_TOKEN_SIZE , ,0x1000 ,"Maximum size in bytes expected for the Attestation platform token" 299 PLAT_ARM_MAX_MEM_BANKS , ,2 ,"Maximum possible number of DRAM and COH/NCOH device memory banks allowed in Arm platform layer" 300 ATTEST_EL3_TOKEN_SIGN ,ON|OFF ,OFF ,"Use EL3 service to sign realm attestation token." 301 STACK_PROTECTOR ,ON | OFF ,OFF ,"Enable the stack protector compiler option." 302 303.. _llvm_build: 304 305################ 306RMM LLVM Build 307################ 308 309RMM can be built using LLVM Toolchain (Clang). To build using LLVM 310toolchain, set RMM_TOOLCHAIN=llvm during configuration stage. 311 312.. _fake_host_build: 313 314##################### 315RMM Fake Host Build 316##################### 317 318RMM also provides a ``fake_host`` target architecture which allows the code to 319be built natively on the host using the host toolchain. To build for 320``fake_host`` architecture, set RMM_CONFIG=host_defcfg during the 321configuration stage. 322