last edited: 2024-07-09 22:50:19 +0000


This page explains the special opcodes that can be used in M5 to do checkpoints etc. The m5 utility program (on our disk image and in util/m5/*) provides some of this functionality on the command line. In many cases it is best to insert the operation directly in the source code of your application of interest. You should be able to link with the appropriate libm5.a file and the m5ops.h header file has prototypes for all the functions. A tutorial on using the M5ops was given as a part of the gem5 2022 Bootcamp. A recording of this event can be found here.

Building M5 and libm5

In order to build m5 and libm5.a for your target ISA, run the following command in the util/m5/ directory.

scons build/{TARGET_ISA}/out/m5

The list of target ISAs is shown below.

Note if you are using a x86 system for other ISAs you need to have the cross-compiler installed. The name of the cross-compiler is shown inside the parentheses in the list above.

See util/m5/ for more details.

The m5 Utility (FS mode)

The m5 utility (see util/m5/) can be used in FS mode to issue special instructions to trigger simulation specific functionality. It currently offers the following options:

Other M5 ops

These are other M5 ops that aren’t useful in command line form.

Using gem5 ops in Java code

These ops can also be used in Java code. These ops allow gem5 ops to be called from within java programs like the following:

import jni.gem5Op;

public  class HelloWorld {

   public static void main(String[] args) {
       gem5Op gem5 = new gem5Op();
       System.out.println("Rpns0:" + gem5.rpns());
       System.out.println("Rpns1:" + gem5.rpns());

   static {

When building you need to make sure classpath includes gem5OpJni.jar:

javac -classpath $CLASSPATH:/path/to/gem5OpJni.jar

and when running you need to make sure both the java and library path are set:

java -classpath $CLASSPATH:/path/to/gem5OpJni.jar -Djava.library.path=/path/to/ HelloWorld

Using gem5 ops with Fortran code

gem5’s special opcodes (psuedo instructions) can be used with Fortran programs. In the Fortran code, one can add calls to C functions that invoke the special opcode. While creating the final binary, compile the object files for the Fortran program and the C program (for opcodes) together. I found the documentation provided here useful. Read the section -- Compiling a mixed C-Fortran program.

The idea of using gem5 ops with Fortran code is essentially to compile the m5 ops C code to an object file, and then link the object file against the binary calling the m5 ops. The C function calling convention in Fortran is such that, if the function name in C code is void foo_bar_(void), then in Fortran, you can call the function by call foo_bar.

Linking M5 to your C/C++ code

In order to link m5 to your code, first build libm5.a as described in the section above.


For example, this could be achieved by adding the following to your Makefile:

CFLAGS += -I$(GEM5_PATH)/include
LDFLAGS += -L$(GEM5_PATH)/util/m5/build/$(TARGET_ISA)/out -lm5

Here is a simple Makefile example:


GEM5_HOME=$(realpath ./)
$(info   GEM5_HOME is $(GEM5_HOME))



LDFLAGS=-L$(GEM5_HOME)/util/m5/build/$(TARGET_ISA)/out -lm5

OBJECTS= hello_world

all: hello_world

	$(CXX) -o $(OBJECTS) hello_world.cpp $(CFLAGS) $(LDFLAGS)

	rm -f $(OBJECTS)

Using the “_addr” version of M5ops

The “_addr” version of m5ops triggers the same simulation specific functionality as the default m5ops, but they use different trigger mechanisms. Below is a quote from the m5 utility explaining the trigger mechanisms.

The bare function name as defined in the header file will use the magic instruction based trigger mechanism, what would have historically been the default.

Some macros at the end of the header file will set up other declarations which mirror all of the other definitions, but with an “_addr” and “_semi” suffix. These other versions will trigger the same gem5 operations, but using the “magic” address or semihosting trigger mechanisms. While those functions will be unconditionally declared in the header file, a definition will exist in the library only if that trigger mechanism is supported for that ABI.

Note: The macros generating the “_addr” and “_semi” m5ops are called M5OP, which are defined in util/m5/abi/*/m5op_addr.S and util/m5/abi/*/m5op_semi.S.

In order to use the “_addr” version of m5ops, you need to include the m5_mmap.h header file, pass the “magic” address (e.g., “0xFFFF0000” for x86, and “0x10010000” for arm64/riscv) to m5op_addr, then call the map_m5_mem() to open /dev/mem. You can insert m5ops by adding “_addr” at the end of the original m5ops functions.

Here is a simple example using the “_addr” version of the m5ops:

#include <gem5/m5ops.h>
#include <m5_mmap.h>
#include <stdio.h>

#define GEM5

int main(void) {
#ifdef GEM5
    m5op_addr = 0xFFFF0000;

    printf("hello world!\n");

#ifdef GEM5

Note: You’ll need to add a new header location for the compiler to find the m5_mmap.h. If you are following the example Makefile above, you can add the following line below where CFLAGS is defined,

CFLAGS += $(GEM5_PATH)/util/m5/src/

When you run the applications with m5ops inserted in FS mode with a KVM CPU, this error might appear.

```illegal instruction (core dumped)```

This is because m5ops instructions are not valid instructions to the host. Using the “_addr” version of the m5ops can fix this issue, so it is necessary to use the “_addr” version if you want to integrate m5ops into your applications or use the m5 binary utility when running with KVM CPUs.