原文参见:gem5 Build System
gem5建立系统是基于SCons的,SCons是一个Python的系统建立开源应用。更多信息参见http://www.scons.org。SCons的主文件名为SConstruct,放在源代码根目录下。其他的SCons文件命名为SConscript,放在其它位置,通常与相关文件同目录。
建立目标
gem5中,使用SCons建立目标的格式为<build dir>/<configuration>/<target>。例如:scons build/ARM/gem5.opt
<build dir>是以build结尾的文件夹路径。通常是build,但也可以指定位于其它位置的名为build的文件夹。同一build目录下的所有目标由假定由同一主机平台编译,并且共享相同的全局变量设置。这些全局变量设置位于build/variables.global文件中。
<configuration>(例子中的ARM)选择一系列编译时的建立选项用以控制模拟器功能,例如ISA种类、CPU模式、Ruby一致性协议等。这些单独配置变量存在build/variables目录下不同的文件中。这个位置可用于彻底清除一次build下的所有配置文件(例如使用rm -rf)的同时保留变量设置。
第一次建立一个特定的配置时,通过在build_opts目录下寻找配置名,决定默认的单独配置变量设置。如果想要创建一个在上述目录下找不到的配置名,用--default 告诉SCons需要使用build_opts或build/variables下的哪个文件作为默认文件。
<target>(例子中的gem5.opt)是要建立的gem5二进制类型,指定了要用到的编译器标志(compiler flags)集合。目前支持版本有:gem5.debug, gem5.opt, gem5.fast, gem5.prof, gem5.perf。
- gem5.debug 关闭了优化。保证变量不会被优化掉,功能不会被意料外的内联(inlined),以及控制流行为正常。该版本与gdb类的工具合作良好,然而关闭优化会造成该版本明显慢于其它版本。当使用gdb或valgrind等工具并且不希望任何细节被模糊掉时应该选择该版本,否则建议选择其它版本。
- gem5.opt 打开优化的同时保留了部分调试功能(例如,断言和DPRINTFs)。该版本良好地平衡了模拟速度与调试观察,是所有环境中最优的版本。
- gem5.fast 打开优化并关闭调试部分。最优的速度,代价是不能进行运行时错误检查与调试输出。如果确信所有功能可以正确运行并想要获得峰值性能,建议使用该版本。
- gem5.prof 类似于gem5.fast,但仍然保留了一些功能(instrumentation)可以用于gprof分析工具。该版本不常用,但可以用于找出gem5中应当被注意的部分以提升性能。
- gem5.perf 同gem5.prof,但是instrumentation使用google perftools,允许被google-pprof分析。该分析版本是gem5.prof的补充,可能可以在所有基于Linux的系统中替换gem5.prof。
Binary name | Optimizations | Run time debugging support | Profiling support |
gem5.debug | No | Yes | No |
gem5.opt | Yes | Yes | No |
gem5.fast | Yes | No | No |
gem5.prof | Yes | No | Yes |
gem5.perf | Yes | No | Yes |
命令行选项
gem5中SCons识别以下命令行选项:
Option | Effect |
–colors | Turn on colorized output |
–no-colors | Turn off colorized output |
–default | Override which existing build configuration or build_opts file to use for defaults |
–ignore-style | Disable style checking hooks |
–update-ref | Update test reference outputs |
–verbose | Print full tool command lines |
环境变量
以下环境变量由主机环境引入,用于SCons:Variable | Use |
AS | Assembler command |
AR | Archive tool command |
CC | C compiler command |
CXX | C++ compiler command |
HOME | User’s home directory |
LD_LIBRARY_PATH | Path to search for library files at loading time |
LIBRARY_PATH | Path to search for library files at linking time |
PATH | Path to search for programs |
PROTOC | protobuf compiler command |
PYTHONPATH | Path to search for python files |
RANLIB | Ranlib command |
SWIG | swig command |
M5_CONFIG | Where to look for the special “.m5” directory |
M5_DEFAULT_BINARY | The default build target which overrides the default default build/ALPHA/gem5.debug |
配置变量
这些配置变量用于控制gem5的建立方式。有些是全局变量,影响build目录中的所有配置;有些只影响当前正在build的配置。不同于命令行选项,这些变量在SCons调用之间保留它们的值。Global
Variable | Description | Default |
CC | C Compiler | CC environment variable or value determined by scons |
CXX | C++ Compiler | CXX environment variable or value determined by scons |
BATCH | Use batch pool for build and tests | False |
BATCH_CMD | Batch pool submission command | qdo |
M5_BUILD_CACHE | Cache built objects in this directory | False |
EXTRAS | Add extra directories to the compilation |
Per Configuration
Variable | Description | Default | Exported as config/*.hh |
CP_ANNOTATE | Enable critical path annotation capability | False | X |
CPU_MODELS | CPU Models | AtomicSimpleCPU,InOrderCPU,O3CPU,TimingSimpleCPU | |
PROTOCOL | Coherence protocol for Ruby | MI_example | X |
SS_COMPATIBLE_FP | Make floating-point results compatible with SimpleScalar | False | X |
TARGET_ISA | Target ISA: ALPHA, ARM, MIPS, POWER, X86 | alpha | X |
USE_CHECKER | Use checker for detailed CPU models | False | X |
USE_FENV | Use IEEE mode control | whether fenv.h was found on this host | X |
USE_POSIX_CLOCK | Use POSIX Clocks | whether posix clocks are available on this host | X |
设置配置变量的值
第一种方法是通过在建立目标时选择的配置名。从build_opts加载文件,其中包含部分预置值。注意,文件中的值是默认值,只在没有指明变量值时使用。这些文件用于定义配置gem5的合理起始点,并非用于配置一个特定的build。
如果在建立后,配置文件夹已经被创建的情况下,想要改变变量的值;或者覆盖一个已被创建的值,可以在命令行指明新的值。语法类似于在shell提示符中设置环境变量的值,但是在scons命令后使用。例如,为已建立的ALPHA创建MESI_CMP_directory协议,可以使用如下命令:
scons PROTOCOL=MESI_CMP_directory build/ALPHA/gem5.opt
可以在scons命令行后添加–-help查看所有的配置变量以及其值。这种方法可以确保所有设置都是如你所想,并且所有的变量名都没有拼写错误。如果一切顺利,则可以移除-–help并开始build。
回归运行/测试
gem5的回归系统内置于SCons。这保证了gem5二进制文件在必要的时候可以自动重建,测试只在可能有不同结果时重新运行。回归目标都在build目录下的tests中。测试输出文件路径确定了运行哪个测试以及如何运行。如下所示:
tests/<gem5 binary extension>/<test category>/<test name>/<architecture>/<operating system>/<configuration>/
可以省略路径,scons将自动build所有匹配指明的组件的可用测试。运行ALPHA配置下opt模式的所有快速测试,可以运行如下命令:
scons build/ALPHA/tests/opt/quick
回归框架集成在scons建立过程中,如果必要,在运行tests前上述命令将会(re)build ALPHA/gem5.opt。仅在test上一次被运行是rebuild前时,test会被重新运行。如果test的上一次运行仍然合法,基于上一次结果,只有一些简明的pass/fail信息会被输出,而不是完整的输出和统计数据。
回归测试基于运行时间被细分为quick和long两类。通过在目标路径上添加分类名可以运行特定类的test。例如:
scons build/ALPHA/tests/opt/long
附加test名可以运行特定测试:
scons build/ALPHA/tests/opt/quick/fs/10.linux-boot
更多信息见:
Regression Tests 。
一些”quick”测试要求在没有附加设置的前提下运行。一些测试基于EIO支持,需要通过EXTRAS机制将encumbered库建立到gem5中。其它测试依赖系统文件,如在系统中特定位置的特定磁盘映像和内核。这些文件通常可用,不难找到。其它测试,通常基于SPEC benchmarks并且不属于”quick”类的,需要严格许可证的输入文件,我们无法发布。除非拥有许可证,否则这些测试无法被运行。
添加源文件和调试标记
通过在SConscript文件中将要添加的文件声明为python类的实例。编译系统基于使用的指定类知道如何处理这些文件。例如,将C++源文件foo.cc添加到系统中,可以在foo.cc同目录下的Sconscript中加入:Source(‘foo.cc’)
编译系统自动查找并处理SConscript文件,可以在添加的文件附近创建一个文件或者拓展一个已经存在的文件。下表所示为源文件类型和功能。
Source file type | Description | Parameters | |
Name | Description | ||
PySource | Add a python source file to the named package | package | The name of the package |
source | The name of the python source file | ||
SimObject | Add a SimObject python file as a python source object and add it to a list of sim object modules | source | The relative path to the python file defining the SimObject. |
Source | Add a c/c++ source file to the build | source | Relative path to source file |
Werror | Whether to compile with -Werror. Defaults to True. | ||
swig | Whether to use flags suitable for a swig wrapper C++ file. Defaults to False. | ||
main | This file is part of main() for the gem5 binary. Defaults to False. | ||
skip_lib | Whether this file should be excluded from the library version of gem5. Defaults to False. | ||
SwigSource | Add a swig file to the build | package | Package for the python version of the source. |
source | Relative path to the swig input file. | ||
UnitTest | Add a unit test to the build | sources | A list or tuple of relative paths to the source files for the unit test. |
定义调试/跟踪标记的机制类似,但不是指定文件。一个复合跟踪标记用于控制一组跟踪标记。
Trace flag type | Description | Parameters | |
Name | Description | ||
DebugFlag | Add an individual trace flag to the build. | name | The name of the new trace flag. |
desc | A description for this flag. This is optional but recommended. | ||
CompoundFlag | Add a compound trace flag to the build. | name | The name of the new compound trace flag. |
flags | A list or tuple of the names of trace flags which this new compound trace flag will control. | ||
desc | A description for this flag. This is optional but recommended. |
使用EXTRAS
EATRAS scons变量可用于将其他的源文件目录编译进gem5,用冒号将路径分开。EATRAS是一种在gem5代码基础上编译的便利方式,不会将新源码与上游源码混淆。可以独立管理自己的代码。