Using the CTC++ bitcov add-on

This document describes an architecture neutral approach, for absolutely minimising the memory consumption on very small system, typically Microcontrollers.

You should be able to use CTC++ with only a few or a few dozens bytes RAM. This is obtained by radically using the counter-arrays elements to bit size, removing the other auxiliary data instrumented in and removing the needage of the targ*.c target library files on the target itself.

Prerequisites

An installed CTC++ with the Host-Target Package.
CTC++ configured for the particular compiler (See Host-Target Package).
An ability to dump a particular array or variable to hard-drive. This can usually be done with a Debug Interface.
An additional array CTC_array[] or a known free memory area of reasonable size

Pitfalls

'\t' Tabs in file names or path. (See ctc2static)
Multiple compilations works, if the amount of counter has not changed for a particular file. Otherwise make clean, and remove MON.aux
Multiple compile directories, you have to set environment variable CTC_DATA_PATH here

Creating the target array `CTC_array[]`

You need to add an array named CTC_array on the target to hold the counter bits. The array content must be initialised to 0x0(!)

In one of your source files add at global scope

unsigned char CTC_array[0x100] = {0};

where 0x100 is an example of the minimum size needed for the array.

To estimate the size of the array, just make a "test compile" of the project and run on the generated MON.sym file following:

ctcpost -L MON.sym | any2mem

You see the size in bits, round up, add a little for safety and future code extensions.

(As an alternative, if you exactly know that a memory part is unused, e.g. memory starting at 0x9000 is unused, you can just add the start address -DCTC_ARRAY=0x9000 to OPT_ADD_COMPILE... Attention, you have to ensure, that this memory part is zero-initialised!)

The script ctc2static for enabling bitcov

The technical background is deeper explained in CTC++ User's Guide. To make this active, add ctc2static to the compiler section in your ctc.ini, e.g. RUN_AFTER_INSTR = ctc2static (Note: this is a comma separated list.)

Generated file `MON.aux`

During your CTC++ compilation, the following text files get generated:

MON.aux

The file MON.aux contains the auxiliary data needed later for actually transferring the coverage data on host.

Building

The project has to be build from one working directory. If you have multiple directories, and get multiple MON.aux files, then set environment variable CTC_DATA_PATH to some appropriate top-level directory.

The file MON.aux must initially be deleted, then the application has to be rebuild. The files can be re-build, if the amount of counters hasn't changed (e.g. not added/removed an if-statement in the meantime). In doubt, make clean, remove MON.aux.

Linking (target library)

The target library is unused, you can and should safely remove it from the ctc.ini setting.

The functionality of

ctc_append_all()
#pragma CTC APPEND
EMBED_FUNCTION_NAME

are removed and will not be compiled.

If you want them back for whatever reasons, feel free to have a look in huge_targets sub-directory here.

The in the Host-Target Package described method atexit() will not work.

Transferring the target coverage data

You should somehow transfer the target array or memory piece to host and dump/convert it binary to a file, e.g. MON.dmp

If you can for example dump this array in textual form, with e.g. right-clicking on that variable and save-as (or copy to clipboard), save it to a text-file MON.hexdump and it should be easy to write a script or tool to convert it back 1-to-1 in a binary file MON.dmp

Preparing the output

A Perl script dmp2txt is include , which takes as first argument

the binary dumped
a Intel hexdump
a Motorola s-record
Tektronix hexdump

MON.dmp and as second argument the MON.aux containing auxiliary data.

dmp2txt MON.dmp MON.aux > MON.txt

The resulting textual output is suitable for input for the ctc2dat utility.

dmp2txt MON.dmp MON.aux | ctc2dat

(Illustration)

  +------------------------+       +------------------------+
  | Array/Memory at target |       | MON.aux (compile time) |
  +------------------------+       +------------------------+
            |                                  |
            | transfer                         |
            V                                  |
  +------------------------+                   |
  | MON.dmp (dump array)   |                   |
  +------------------------+                   |
            |                                  |
            +----------------------------------+
                             |
                             V
                   +--------------------+
                   |      dmp2txt       |
                   +--------------------+
                             |
                             V
                   +--------------------+
                   |      ctc2dat       |
                   +--------------------+
                             |
                             V
                   +--------------------+
                   | regular MON.dat    |
                   +--------------------+

Just proceed from here on as described in CTC++ User's Guide.

Diagnosis

Quick diagnosis can be found in diagnosis.html in this directory.

Tools used

any2mem provides information for the actual size needed for CTC_array[]
dmp2txt converts a memory dump MON.dmp or a MON.hex (with using MON.aux) to input stream for the ctc2dat utility.
ctc2static is the CTC_AFTER_INSTR script, run only internally

Other usage

If the tool chain described fits your needs, but you have enough memory and want to use real counter (e.g. 32-bit counters), then have a look at readme-big.html in this directory.