How to test GCC on a simulator

Several GCC targets can be tested using simulators. These allow you to test GCC for a specific processor for which you don't have access to hardware, or for targets that have general characteristics you'd like to test, like endianness or word size.

All of the instructions here start out from a directory we'll call ${TOP}, which is initially empty.

Set up sources

Testing with a simulator requires use of a combined tree; you can't easily build newlib, required for simulator testing, outside of a combined tree, and the build of the other components is easiest in a combined tree.

The combined tree contains GCC sources plus several modules of the src tree: binutils and newlib for the build, gdb for the simulators, and dejagnu for the testing tools. If you already build with a combined tree you can use your current setup; if not, these instructions will get you the sources you need.

Check out initial CVS trees

If you don't yet have either tree you'll need to do an initial check-outs.

Check out mainline GCC:

cd ${TOP}
svn checkout svn://gcc.gnu.org/svn/gcc/trunk gcc
# This makes sure that file timestamps are in order initially.
cd ${TOP}/gcc
contrib/gcc_update --touch

Check out the src tree:

cd ${TOP}
cvs -d :pserver:anoncvs@sourceware.org:/cvs/src login
# You will be prompted for a password; reply with "anoncvs".
cvs -d :pserver:anoncvs@sourceware.org:/cvs/src co binutils newlib dejagnu gdb

Update CVS trees

You can update existing CVS trees rather than starting from scratch each time. Update the GCC tree using the gcc_update script, which touches generated files and handles directory changes in the tree. Be sure to do this from the directory in which you did the original check-out, NOT in the combined tree:

cd ${TOP}/gcc
contrib/gcc_update

Update the src tree with the same sequence of commands that you used to check out that tree initially, invoked from the src directory (NOT from within the combined tree).

Create a combined tree

Create a tree that consists of all of the files from the GCC and binutils/gdb/newlib source trees (including several simulators in src/sim), with the GCC files overriding the binutils/gdb/newlib files when there's a conflict. It's done this way because the GCC files are the master copy. To save on disk space, these commands actually make a tree of hard links rather than duplicating all the files:

cd ${TOP}
rm -rf combined
mkdir combined
cd src && find . -print | cpio -pdlm ../combined && cd ..
cd gcc && find . -print | cpio -pdlmu ../combined && cd ..

Build it

Use a recent version of GCC as the build compiler, no earlier than 2.95.

The target name suitable for the simulator is usually `*-elf' for a target `*'. There are some exceptions, for instance on powerpc it's powerpc-eabi or powerpc-eabisim. Here we build arm-elf.

cd ${TOP}
mkdir build install
cd build
../combined/configure \
    --target=arm-elf --prefix=${TOP}/install \
    --with-newlib --disable-gdbtk
make

Test it

The only trick here is that you want DejaGNU to use the simulator rather than trying to run the output on the build system. For example:

cd ${TOP}/build
make check-gcc RUNTESTFLAGS=--target_board=arm-sim

The only reliable way (apart from guessing that it's probably `*-sim') to find out the name of the target board is to look in the DejaGNU sources, in dejagnu/baseboards, for something that looks right. Or you can use this table of combinations that at one time compiled, usable as test-targets with the instructions above.

You can compare your test results against the archived results linked below to detect major problems. As always, if you're testing a patch you should compare your results with and without the patch.

The target characteristic can help you determine which targets to use to broaden the scope of your testing. A cc0 target uses a single condition code register, cc0, which is set as a side effect of most instructions. The compiler cannot insert other instructions between the instruction that sets cc0 and the one that uses it. Because of this, a cc0 target causes significantly different code to be generated and can matter more than word size and endianness in terms of detecting new breakage.

Target	Simulator	Comments	Test Results
arm-elf	arm-sim	32-bit word, little endian	3.3 20030509 (prerelease) 3.2.3 20030415 (prerelease)
fr30-elf	fr30-sim	32-bit word, big endian	3.3 20030509 (prerelease)
h8300-coff	h8300-sim	cc0 target, big endian	3.3 20030509 (prerelease) 3.2.3 20030415 (prerelease)
m32r-elf	m32r-sim	32-bit word, big endian	3.3
mips-elf	mips-sim	big endian	4.1.0 20051112 (experimental) 3.3 20030509 (prerelease)
mipsisa64-elf	mips-sim-idt64		3.4 20030605 (experimental)
mn10300-elf	mn10300-sim	cc0 target, little endian	3.3 20030509 (prerelease) 3.2.3 20030415 (prerelease)
powerpc-eabisim	powerpc-sim	32-bit word, big endian	3.4 20030301 (experimental)
sh-coff	sh-hms		3.3 20030509 (prerelease) 3.2.3 20030415 (prerelease)
sh-elf	sh-sim	big endian	4.2.0 20060226 (experimental) 3.4 20030605 (experimental) 3.3 20030509 (prerelease) 3.2.3 20030415 (prerelease)
sparc-elf	sparc-sim		3.3 20030507 (prerelease) 3.2.3 20030415 (prerelease)
v850-elf	v850-sim	cc0 target, 32-bit word, little endian	3.2.3 20030415 (prerelease)

Please send FSF & GNU inquiries & questions to gnu@gnu.org. There are also other ways to contact the FSF.

These pages are maintained by the GCC team.

For questions related to the use of GCC, please consult these web pages and the GCC manuals. If that fails, the gcc-help@gcc.gnu.org mailing list might help.
Please send comments on these web pages and the development of GCC to our developer mailing list at gcc@gnu.org or gcc@gcc.gnu.org. All of our lists have public archives.

Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.

Last modified 2006-06-21