KOCL (KAPow for OpenCL)
If you make use of this code, please acknowledge us by citing our article.
This is an academic tool. It was developed and has been tested with a single vendor toolchain and development board, and makes extensive use of undocumented, unsupported and hidden features. It is highly likely that this tool will not work properly with other software or hardware.
On your Linux development machine, you will need:
The KOCL Offline Compiler (KOC), since it's built on top of the Altera Offline Compiler (AOC), requires kernel code to exist in a separate
.cl file. Ensure that your kernel and host code are suitably split before continuing. There are a few sample applications available in
apps that conform to this standard; you can use one of these as-is, modify one of them or make your own that is similarly structured.
Make sure that at least the
hw and your application directories are on your development machine before continuing. Let's assume everything's inside directory
If your Altera install directory is not the default
hw/prime_env.sh as needed before continuing.
Set up your environment for KOC/AOC by executing:
Run the complete flow, from
.cl to instrumented bitstream, by executing:
KOCL/hw/KOC.py <path to .cl file>
There are several optional flags:
-k allows you to choose which kernels to instrument. You can supply
none or a space-separated list of kernel names. The default is
none will instrument none of your kernels: your build will have the same result as running
aoc instead. A subset might look like:
KOCL/hw/KOC.py KOCL/apps/int_add_mult/int_add_mult.cl -k "int_add int_mult"
-b allows you to choose the board you wish to target. We only support the Cyclone V at the moment, so leave this set to its default of
-n allows you to choose how many activity counters are added to each kernel. A higher value normally results in higher model accuracy but always results in extra area overhead. The default is
-w allows you to choose the width (in bits) of each activity counter. We only support 9-bit counters at the moment, so leave this set to its default of
Depending on the complexity of the required hardware, this could take several hours to complete.
Incorporating KOCL in Host Code
This section is optional. If you don't want to add power monitoring functionality to your host code, skip this section.
Include KOCL's header file in your host code to expose its functions:
Initialise KOCL by passing in how frequently you want measurements to be taken (in s):
KOCL_t* KOCL = KOCL_init(<update period>);
KOCL_init returns a pointer to a
KOCL_t structure. Pass this to all subsequent KOCL function calls.
KN + 1, where K is the number of instrumented kernels and N is the number of counters per module (specified with
-n), updates must occur to KOCL's model before its estimates are meaningful. To establish whether or not the required number of updates have occurred, use:
int built = KOCL_built(KOCL);
We offer two 'get' functions at the moment: you can either print the breakdown (to your terminal) or request kernel-level values (for use by your host code). To print, use:
To get a value for a specific kernel's power, use:
float kernel_power = KOCL_get(KOCL, <kernel name>);
You can also get a value for the static power using:
float static_power = KOCL_get(KOCL, "static");
When you've finished, clean up:
Make sure that at least the
sw directory is on your Cyclone V board before continuing. The makefile we use expects it to be at
Copy your application to the board. You will need the
.aocx file produced by KOCL, but nothing else: don't copy all of the build files (the subdirectory within the application directory)!
Configure the Altera OpenCL runtime:
Build your application:
cd <application directory> make
Ensure that the MSEL switches on the board are set, left to right, up-down-up-down-up-up.
Run your application:
Please contact James Davis if you have any problems with this tool or would like to offer any suggestions for its improvement.