1 The m5 utility provides a command line and library interface for gem5
4 These operations are requested by the simulated software through some special
5 behavior which is recognized by gem5. gem5 will then perform the requested
6 operation which is outside the normal behavior of the simulated system.
12 There are a few different ways the simulated software can let gem5 know it
13 wants to perform an operation. Different CPU models have different constraints
14 depending on how they're implemented, and may not support all of these
17 Trigger | Native | KVM | Fast Model
18 -------------|---------|-----|------------
20 Address | ARM/X86 | Yes |
21 Semihosting | ARM | | Yes
23 ## "Magic" Instructions
25 This is the oldest trigger mechanism in gem5, and is supported by all of the
26 CPU models which interpret instructions one at a time using gem5's ISA
27 definitions. It works by co-opting instructions which normally are undefined,
28 and redefining them to trigger gem5 operations. Exactly what instructions
29 these are, how they encode what operation they go with, etc., vary from ISA to ISA.
31 When using the KVM CPU models, the instruction stream is executing on actual
32 physical hardware which won't treat these instructions specially. They will
33 retain their old behavior and, most likely, raise an undefined instruction
34 exception if executed.
36 Other external models, like ARM's Fast Model CPUs, also won't treat these
37 instructions specially.
39 ## "Magic" Address Range
41 This mechanism was added for the KVM CPUs so that they could trigger gem5
42 operations without having to recognize special instructions. This trigger is
43 based on a specially set aside range of physical addresses. When a read or
44 write is targetted at that range, instead of a normal device or memory access,
45 a gem5 operation is triggered.
47 Depending on the ISA, gem5 native CPUs should support this mechanism (see the
50 When using the KVM CPU, the special range of addresses are not registered as
51 memory, and so the KVM virtual machine will exit when they're accessed. gem5
52 will have a chance to recognize the special address, and can trigger the
55 When using an external model like ARM's Fast Model CPUs, these external
56 accesses will leave the CPU complex, and gem5 will be able to recognize them.
57 Unfortunately if the CPU has multiple threads of execution, gem5 won't be able
58 to tell which the access came from. Also, the memory access may not happen at a
59 precise point in the simulated instruction stream due to binary translation.
60 The architectural state may not be in a consistent state which is suitable to
61 extract arguments or inject a return value.
63 ### Default address range
65 Since x86 has a predictable address space layout, the "magic" address range can
66 be put in a predictable, default location, which is at 0xFFFF0000.
68 On other architectures, notably ARM, the address space is less predictable, and
69 it doesn't make sense to set a default location which won't be valid on all
74 This mechanism was added to support ARM's Fast Model CPUs. It extends ARM's
75 semihosting support, a mechanism which was already defined to interrupt normal
76 execution and trigger some sort of behavior in a containing host.
78 On ISAs which support semihosting (only ARM now, and probably going forward),
79 gem5 native CPUs can support semihosting instructions, and so should support
80 the semihosting trigger mechanism.
82 KVM CPUs use real hardware, and so semihosting instructions will not have
83 special behavior and will act like their normal counterparts (HLT, etc.).
91 To build either the command line utility or one of the versions of the library,
92 first identify what ABI(s) you're targetting.
94 ABI | Description | Triggers
95 ---------|--------------|----------
96 arm64 | 64 bit ARM | instruction, adddress, semihosting
97 arm | 32 bit ARM | instruction
98 thumb | ARM thumb | instruction
99 sparc | 64 bit SPARC | instruction
100 x86 | amd64/x86_64 | instruction, address
104 The m5 utility uses a scons based build system. gem5 itself also uses SCons,
105 but these builds are (mostly) not related and separate.
107 The SConscript for this utility is set up to use a build directory called
108 "build", similar to gem5 itself. The build directory is structured so that you
109 can ask scons to build a portion of it to help narrow down what you want to
114 There is a **build/native** directory which is for some test binaries which
115 test generic functionality and are compiled for the host, whatever that happens
116 to be. These can be run directly, unlike ABI specific tests which may be
117 possible to run directly depending on the host's architecture, but may not.
121 The first level subdirectories of the build directory (other than "native",
122 described above) is named after the ABI you're targetting. For instance, build
123 products for x86 would be in the **build/x86** subdirectory.
125 Within an ABI subdirectory will be linked copies of all the source files needed
126 for the build, and also "test" and "out" subdirectories.
130 The "test" subdirectory, for instance **build/x86/test**, holds the test
131 binaries for that ABI in a bin subdirectory, and the results of running those
132 tests (if requested and possible) in a "result" subdirectory.
136 The "out" subdirectory, for instance **build/x86/out**, holds the various final
137 build products. This includes:
139 - m5: The command line utility.
140 - libm5.a: C library.
141 - gem5OpJni.jar, libgem5OpJni.so, jni/gem5Op.class: Java support files.
142 - libgem5OpLua.so: Lua module/library.
148 There are some variables which set build options which need to be controlled on
149 a per ABI level. Currently, these are:
151 - CROSS_COMPILE: The cross compiler prefix.
152 - QEMU_ARCH: The QEMU architecture suffix.
154 To set these for a particular ABI, prefix the variable name with the ABI's name
155 and then a dot. For instance, to set the cross compiler prefix to
156 "x86_64-linux-gnu-" for x86, you would run scons like this:
159 scons x86.CROSS_COMPILE=x86_64-linux-gnu- build/x86/out/m5
162 ABI | QEMU_ARCH | CROSS_COMPILE
163 ---------|-----------|---------------------
164 arm64 | aarch64 | aarch64-linux-gnu-
165 arm | arm | arm-linux-gnueabihf-
166 thumb | arm | arm-linux-gnueabihf-
167 sparc | sparc64 | sparc64-linux-gnu-
170 Note that the default setting for the x86 cross compiler prefix is blank,
171 meaning that the native/host compiler will be used. If building on a non-x86
172 host, then you'll need to set an appopriate prefix and may be able to clear
173 some other prefix corresponding to that host.
175 ### SCons command line flags
177 --debug-build: Compile with the -g option, and -O0.
178 --no-test-xml: Exclude the test result XML files from the build.
179 --verbose: Show build command lines and full command output.
181 ## External dependency detection
183 In some cases, if an external dependency isn't detected, the build will
184 gracefully exclude some targets which depend on it. These include:
188 The SConscript will attempt to find the javac and jar programs. If it can't, it
189 will disable building the Java support files.
193 The SConscript will attempt to find lua51 support using pkg-config. If it
194 can't, it will disable building the lua module/library.
198 The SConscript will attempt to find various QEMU binaries so that it can run
199 non-native tests using QEMU's application level emulation. The name of the
200 binary it looks for depends on the ABI and is set to qemu-${QEMU_ARCH}. See
201 above for a description of per ABI build variables, including QEMU_ARCH.
203 If it can't find a program with that name, it will disable running non-native
204 test binaries for that ABI.
210 Tests are based on the googletest system. There are native tests which test
211 mechanisms which are not specific to any ABI and can be run on the host. These
212 are built using the native toolchain.
214 There are also tests for ABI specific mechanisms like the various trigger
215 types. These will be built using the cross compiler configured for a given ABI.
216 These tests can be run in QEMU in its application emulation mode, and the build
217 system can run them automatically if requested and if the required dependencies
220 The tests for the trigger mechanisms can't count on those mechanisms actually
221 working when running under QEMU, and so will try to set up intercepts which
222 will catch attempts to use them and verify that they were used correctly. When
223 running these tests under gem5, set the RUNNING_IN_GEM5 environment variable
224 which will tell the test to expect the trigger mechanism to actually work.
228 # Command line utility
230 The command line utility provides a way of triggering gem5 operations either
231 interactively through a terminal connection to the simulated system, or scripts
236 Any call to the utility should have the following structure:
239 m5 [call type] <command> [arguments]
242 Call type is optional and selects what trigger mechanism should be used. If
243 it's omitted, the default mechanism will be used. What the default mechanism is
244 varies based on the ABI.
246 ABI | Default call type
247 ---------|-------------------
254 The default is usually to use a magic instruction, which for most ABIs is the
255 only mechanism that's supported, and is what the m5 utility would
256 tradditionally have used. On x86, the address based mechanism is the default
257 since it's supported on all current CPU types which also support x86.
261 To override the default call type, you can use one of these arguments.
264 --addr [address override]
267 Selects the magic address call type. On most ABIs which don't have a default
268 magic address range, this argument must be followed by the address range to
269 use. On x86 if no address is specified, the default (0xFFFF0000) will be used.
275 Selects the magic instruction call type.
281 Selects the semihosting based call type.
283 ### Commands and arguments
285 To see a list of commands and the arguments they support, run the utility with
296 The C library provides a set of functions which can trigger gem5 operations
297 from within compiled programs.
299 ## Building in the library
301 To use the C library, include the header file located at
310 #include <gem5/m5ops.h>
313 That will declare the various functions which wrap each of the gem5 operations.
314 It includes another header file located at
317 include/gem5/asm/generic/m5ops.h
320 using a path relative to include. Be sure that include path will resolve based
321 on the settings of your compiler, or move or modify to fit the existing
324 As part of the linking step of your application, link in the libm5.a static
325 library archive which provides the definitions of those functions.
327 ## Trigger mechanisms
329 The bare function name as defined in the header file will use the magic
330 instruction based trigger mechanism, what would have historically been the
333 Some macros at the end of the header file will set up other declarations which
334 mirror all of the other definitions, but with an "_addr" and "_semi" suffix.
335 These other versions will trigger the same gem5 operations, but using the
336 "magic" address or semihosting trigger mechanisms. While those functions will
337 be unconditionally declared in the header file, a definition will exist in the
338 library only if that trigger mechanism is supported for that ABI.
344 In your java source, import the gem5Op class which will have methods for
345 calling each of the gem5 operations. The .so library will be loaded
352 These methods will all use the magic instruction based trigger mechanism.
358 The lua module is implemented in a file called libgem5OpLua.so, and should be
359 loaded using typical lua mechanisms. It will be built against lua 5.1.
363 In lua 5.1, all numeric values are (typically) represented as doubles. That
364 means that 64 bit integer argument values of any type, but in particular
365 addresses, can't be represented exactly. Calls to gem5 operations using that
366 type of argument or returning that type of value may not work properly.
368 In lua 5.3, numeric values can be represented by either a double or a proper
369 integer without having to rebuild the lua interpreter configured for one or the
370 other. If the module was ported to lua 5.3 then integer values could be passed
377 ## Java/lua cross compiling
379 When building the java or lua modules, a C cross compiler is used so that any
380 generated binary will be built for the target ABI. Unfortunately, other tools,
381 headers, etc, come from the host and may not be useable, or worse may be
382 subtley broken, when used to target a different ABI. To build these objects
383 correctly, we would need to use a proper cross build environment for their
384 corresponding languages. Something like this could likely be set up using a