Introduction

CoreMark's primary goals are simplicity and providing a method for testing only a processor's core features. For more information about EEMBC's comprehensive embedded benchmark suites, please see www.eembc.org.

For a more compute-intensive version of CoreMark that uses larger datasets and execution loops taken from common applications, please check out EEMBC's CoreMark-PRO benchmark, also on GitHub.

Building and Running

In a typical Linux system, to build and run the benchmark, type

> make

Full results are available in the files run1.log and run2.log. CoreMark result can be found in run1.log.

For information on using CoreMark with microcontrollers or embedded processor systems without an OS, please see barebones_porting.md.

Cross Compiling

For cross compile platforms please adjust core_portme.mak, core_portme.h (and possibly core_portme.c) according to the specific platform used. When porting to a new platform, it is recommended to copy one of the default port folders (e.g. mkdir <platform> && cp linux/* <platform>), adjust the porting files, and run:

% make PORT_DIR=<platform>

Make Targets

• run - Default target, creates run1.log and run2.log.
• run1.log - Run the benchmark with performance parameters, and output to run1.log
• run2.log - Run the benchmark with validation parameters, and output to run2.log
• run3.log - Run the benchmark with profile generation parameters, and output to run3.log
• compile - compile the benchmark executable
• link - link the benchmark executable
• check - test MD5 of sources that may not be modified
• clean - clean temporary files

Make flag: ITERATIONS

By default, the benchmark will run between 10-100 seconds. To override, use ITERATIONS=N

% make ITERATIONS=10

Will run the benchmark for 10 iterations. It is recommended to set a specific number of iterations in certain situations e.g.:

• Running with a simulator
• Measuring power/energy
• Timing cannot be restarted

Minimum required run time: Results are only valid for reporting if the benchmark ran for at least 10 secs!

Make flag: XCFLAGS

To add compiler flags from the command line, use XCFLAGS e.g.:

% make XCFLAGS="-DMULTITHREAD=4 -DUSE_FORK"

Make flag: CORE_DEBUG

Define to compile for a debug run if you get incorrect CRC.

% make XCFLAGS="-DCORE_DEBUG=1"

Make flag: REBUILD

Force a rebuild of the executable.

Systems Without make

The following files need to be compiled:

• core_list_join.c
• core_main.c
• core_matrix.c
• core_state.c
• core_util.c
• PORT_DIR/core_portme.c

For example:

% gcc -O2 -o coremark.exe core_list_join.c core_main.c core_matrix.c core_state.c core_util.c simple/core_portme.c -DPERFORMANCE_RUN=1 -DITERATIONS=1000
% ./coremark.exe > run1.log

The above will compile the benchmark for a performance run and 1000 iterations. Output is redirected to run1.log.

Parallel Execution

Use XCFLAGS=-DMULTITHREAD=N where N is number of threads to run in parallel. Several implementations are available to execute in multiple contexts, or you can implement your own in core_portme.c.

% make XCFLAGS="-DMULTITHREAD=4 -DUSE_PTHREAD -pthread"

The above will compile the benchmark for execution on 4 cores, using POSIX Threads API. Forking is also supported:

% make XCFLAGS="-DMULTITHREAD=4 -DUSE_FORK"

Note: linking may fail on the previous command if your linker does not automatically add the pthread library. If you encounter undefined reference errors, please modify the core_portme.mak file for your platform, (e.g. linux/core_portme.mak) and add -pthread to the LFLAGS_END parameter.

Run Parameters for the Benchmark Executable

CoreMark's executable takes several parameters as follows (but only if main() accepts arguments): 1st - A seed value used for initialization of data. 2nd - A seed value used for initialization of data. 3rd - A seed value used for initialization of data. 4th - Number of iterations (0 for auto : default value) 5th - Reserved for internal use. 6th - Reserved for internal use. 7th - For malloc users only, ovreride the size of the input data buffer.

The run target from make will run coremark with 2 different data initialization seeds.

Alternative parameters:

If not using malloc or command line arguments are not supported, the buffer size for the algorithms must be defined via the compiler define TOTAL_DATA_SIZE. TOTAL_DATA_SIZE must be set to 2000 bytes (default) for standard runs. The default for such a target when testing different configurations could be:

% make XCFLAGS="-DTOTAL_DATA_SIZE=6000 -DMAIN_HAS_NOARGC=1"

Submitting Results

CoreMark results can be submitted on the web. Open a web browser and go to the submission page. After registering an account you may enter a score.

Run Rules

What is and is not allowed.

Required

1. The benchmark needs to run for at least 10 seconds.
2. All validation must succeed for seeds 0,0,0x66 and 0x3415,0x3415,0x66, buffer size of 2000 bytes total.
   • If not using command line arguments to main:

	% make XCFLAGS="-DPERFORMANCE_RUN=1" REBUILD=1 run1.log
	% make XCFLAGS="-DVALIDATION_RUN=1" REBUILD=1 run2.log

3. If using profile guided optimization, profile must be generated using seeds of 8,8,8, and buffer size of 1200 bytes total.

    % make XCFLAGS="-DTOTAL_DATA_SIZE=1200 -DPROFILE_RUN=1" REBUILD=1 run3.log

4. All source files must be compiled with the same flags.
5. All data type sizes must match size in bits such that:
   • ee_u8 is an unsigned 8-bit datatype.
   • ee_s16 is a signed 16-bit datatype.
   • ee_u16 is an unsigned 16-bit datatype.
   • ee_s32 is a signed 32-bit datatype.
   • ee_u32 is an unsigned 32-bit datatype.

Allowed

1. Changing number of iterations
2. Changing toolchain and build/load/run options
3. Changing method of acquiring a data memory block
4. Changing the method of acquiring seed values
5. Changing implementation in core_portme.c
6. Changing configuration values in core_portme.h
7. Changing core_portme.mak

NOT ALLOWED

1. Changing of source file other then core_portme* (use make check to validate)

Reporting rules

Use the following syntax to report results on a data sheet:

CoreMark 1.0 : N / C [/ P] [/ M]

N - Number of iterations per second with seeds 0,0,0x66,size=2000)

C - Compiler version and flags

P - Parameters such as data and code allocation specifics

• This parameter may be omitted if all data was allocated on the heap in RAM.
• This parameter may not be omitted when reporting CoreMark/MHz

M - Type of parallel execution (if used) and number of contexts

• This parameter may be omitted if parallel execution was not used.

e.g.:

CoreMark 1.0 : 128 / GCC 4.1.2 -O2 -fprofile-use / Heap in TCRAM / FORK:2 

or

CoreMark 1.0 : 1400 / GCC 3.4 -O4 

If reporting scaling results, the results must be reported as follows:

CoreMark/MHz 1.0 : N / C / P [/ M]

P - When reporting scaling results, memory parameter must also indicate memory frequency:core frequency ratio.

1. If the core has cache and cache frequency to core frequency ratio is configurable, that must also be included.

e.g.:

CoreMark/MHz 1.0 : 1.47 / GCC 4.1.2 -O2 / DDR3(Heap) 30:1 Memory 1:1 Cache

Log File Format

The log files have the following format

2K performance run parameters for coremark.	(Run type)
CoreMark Size    	: 666					(Buffer size)
Total ticks			: 25875					(platform dependent value)
Total time (secs) 	: 25.875000				(actual time in seconds)
Iterations/Sec 		: 3864.734300			(Performance value to report)
Iterations			: 100000				(number of iterations used)
Compiler version	: GCC3.4.4				(Compiler and version)	
Compiler flags		: -O2					(Compiler and linker flags)
Memory location		: Code in flash, data in on chip RAM
seedcrc				: 0xe9f5				(identifier for the input seeds)
[0]crclist			: 0xe714				(validation for list part)
[0]crcmatrix		: 0x1fd7				(validation for matrix part)
[0]crcstate			: 0x8e3a				(validation for state part)
[0]crcfinal			: 0x33ff				(iteration dependent output)
Correct operation validated. See README.md for run and reporting rules.  (*Only when run is successful*)
CoreMark 1.0 : 6508.490622 / GCC3.4.4 -O2 / Heap 						  (*Only on a successful performance run*)

Theory of Operation

This section describes the initial goals of CoreMark and their implementation.

Small and easy to understand

• X number of source code lines for timed portion of the benchmark.
• Meaningful names for variables and functions.
• Comments for each block of code more than 10 lines long.

Portability

A thin abstraction layer will be provided for I/O and timing in a separate file. All I/O and timing of the benchmark will be done through this layer.

Code / data size

• Compile with gcc on x86 and make sure all sizes are according to requirements.
• If dynamic memory allocation is used, take total memory allocated into account as well.
• Avoid recursive functions and keep track of stack usage.
• Use the same memory block as data site for all algorithms, and initialize the data before each algorithm – while this means that initialization with data happens during the timed portion, it will only happen once during the timed portion and so have negligible effect on the results.

Controlled output

This may be the most difficult goal. Compilers are constantly improving and getting better at analyzing code. To create work that cannot be computed at compile time and must be computed at run time, we will rely on two assumptions:

• Some system functions (e.g. time, scanf) and parameters cannot be computed at compile time. In most cases, marking a variable volatile means the compiler is force to read this variable ever