How to build direct

Direct directory structure

The following is the directory structure of direct -

src/direct contains the OCaml code for direct.

src/manager contains the ecos based manager code, which has implementations of all the functions that we wrap in the user application. For example this is where you will find implementations of such functions as man_mutex_lock (for cyg_mutex_lock) or man_thread_delay (for cyg_thread_delay).

src/runtime contains the code that implements the runtime functionality of direct. It has implementations of functions that process cuts and manage the call stack.

src/util is used by src/runtime and contains an implementation of a hash table and a bloom filter.

src/cilModule is the place where Cesar's old Cilly based instrumentation layer resides. We don't use this anymore.

ecos is the directory where we have an installation of ecos for testing direct against the ecos Hardware Abstraction Layer (HAL).

ecos/include and ecos/lib contain files that we need to build and link user application code to run it using the ecos simulator.

examples/ecos is the place where all ecos based tests will live.

Building direct

First set the following environment variable -

ECOS_INSTALL = <your_direct_directory>/ecos

Next, in the direct top level directory do -

make all

This will build direct, the runtime layer and the manager. They can be built individually using the targets "direct", "runtime" and "manager".

Installing direct

In the direct top level directory do -

make install

This will create an "install" directory and place the following files in it -

Testing direct

First set the following environment variables -

ECOS_INSTALL = <your_direct_directory>/ecos DIRECT_INSTALL = <your_direct_directory>/install

Note that you need to do "make install" first to release direct.

Now, in the top level directory do -

make test

This will run a subset of the tests for direct. At this point it runs the following tests -

Cleaning up everything

make clean - cleans up direct and manager make spotless - cleans up the installation too

make testclean - cleans up the testcase shrapnel

Using Direct

The following environment variables need to be set -

# ECOS_INSTALL = <your_direct_directory>/ecos # DIRECT_INSTALL = <your_direct_directory>/install

<pre> Usage: direct [-c <configfilename>] [-t <threadname>]* [preprocessor options] [-debug <direct|src>] [-analysis <change|cov>] [-ref <prevrundirname>] [-run <duration>] [-compare] <C filenames>

Solves the coverage and measurement problem for multi-threaded C programs.

</pre>

-c <configfilename> is used to point direct to the configuration file. This file contains the set of all functions we want to wrap. Each such function is taken to be an event. The file direct/ecos/ecos.config contains a version of this file that we use for testing direct on ecos.

-t <threadname>

is used to specify the name of a thread. We expect to find as many cyg_thread_create calls as the number of -t options passed, one per thread.

-I <include_directories>

is used to specify include directories that the user application code requires. This will be passed along to a C preprocessor before direct processes the C file to extract the cdfg.

-preproc

is used to pass other preprocessing information to process the C files.

-debug

This flag when set to direct will make direct print out debug information in the ocaml layer. If the flag is set to src, then this will debug the direct runtime C code.

-analysis

The type of analysis (change|coverage). The default is change. This will make direct process the user code with respect to change impact analysis.

-ref

When direct does change impact analysis, it needs the directory of a previous run of the user application. This is passed through the -ref option. It can be the current running directory.

-run <duration>

this option can be used to automatically terminate the user program after <duration> time has elapsed from the start of the run. This is used when the user code does not explicitly issue an exit call by using cyg_test_exit().

-compare

when this flag is passed, direct will compare two runs. The results of the runs are expected to be in <filename1> and <filename2>. Each time the user code runs, the cuts are dumped to a file at this point. Using this flag will compare the files and print out the sequence leading to a new cut if any. It will in effect generate sequences for B\A where A is the set of traces for the first run and B is the set of traces from the second run. The sequence is stored in html form. A directory called .temp is created in the current working directory with all the html files needed to browse the sequence. A file called trace.html in the direct/scripts directory should be invoked from the current working directory using your favorite browser. This will bring up the sequence with buttons at the bottom of the page to navigate the sequence. A 21 line snippet of the user code around the events is displayed per thread on the same page. 10 lines above the event and 10 below. The thread that had the latest event will have the event shown in a different color.

-sensitivity n[%]

This option can be used to add a delay to every block of code. We use the pre-control points for delay injection. This mimics the non-determinism in the amount of time that each block of code takes to execute. The delay can be a proportional delay, if n% is specified, otherwise it is an absolute constant delay if just n is specified. A proportional delay will add n% of the block execution time as the delay for the block.

-help

Display this list of options

The final strings passed to direct are expected to be used C source filenames. There can be multiple source files.

Running direct

To run direct to instrument user code (called simple.c here), do the following

direct -c $ECOS_INSTALL/ecos.config -t infinite_m12 -t infinite_m21 -I $ECOS_INSTALL/include simple.c

Running direct will produce two files -

These files contain the instrumented C code in man_merged.c and some information for the runtime part of direct in man_info.c.

To build the instrumented code to run with the ecos simulator do the following -

gcc <optional_flag> -c -g -nostdlib -I$ECOS_INSTALL/include man_merged.c

gcc <optional_flag> -c -g -nostdlib -I$ECOS_INSTALL/include man_info.c

gcc <optional_flag> -g -nostdlib -L$(ECOS_INSTALL)/lib -Ttarget.ld man_merged.o man_info.o $(DIRECT_INSTALL)/libecos.a -o simple

The <optional_flag> parameter should be -m32 when running on a 64 bit platform.

The resulting executable file, which in this case is "simple" can then be run like any other unix program and debugged like any other unix C program.

Look at examples/ecos/simple for an example.

To run direct to generate cuts after a change has been made in your code, do the following,

direct -c $ECOS_INSTALL/ecos.config -t infinite_m12 -t infinite_m21 -I $ECOS_INSTALL/include -ref ./ simple.c

We are passing the -ref option with the current directory as the reference directory. The shrapnel from a previous run is expected to be here. The set of other files in a run directory that we need are listed and explained in a separate section below.

After running direct, build the application in the same way as before and then run it. This will produce the results of the new run.

The results of comparing the two traces, in effect generating sequences for A\B and B\A can be done using the following command,

direct -c $ECOS_INSTALL/ecos.config -compare

Auxillary files generated by direct

When direct analyzes the user code for change impact analysis, it generates a file called events.map which contains a mapping from new event IDs to old event IDs. These are substitutions for event IDs made by direct based on an analysis of how the user code has changed. It is good to check this file to make sure there are no discrepancies. If some new event ID does not get mapped to an old event ID when that piece of code hasn't changed then it will result in spurious new cuts.

This file contains a textual representation of the cuts seen in a run. If the index is 1, then the cuts are from a run without a reference directory to do change impact analysis. If the index is 2, the file contains cuts from a run after a change. It is triggered by the use of the -ref option, which tells direct that we want to analyze cuts with respect to a previous run.

These files are used to navigate the sequence of cuts seen that lead to a new cut in a browser. The file direct/scripts/trace.html should be the file that is loaded from the directory in which -compare was done.

Building applications to run on the ecos simulator for 64 bit platforms

Install gcc multilib - This enables gcc to compile 32 bit applications in a 64 bit environment. You need this because the ecos simulator is a 32 bit application.

Get the following 32 bit libraries in /usr/lib32

Now build the application for simulation using -

gcc -m32 -c -g -nostdlib -I$ECOS_INSTALL/include man_merged.c gcc -m32 -c -g -nostdlib -I$ECOS_INSTALL/include man_info.c gcc -m32 -g -nostdlib -L$ECOS_INSTALL/lib -Ttarget.ld man_merged.o man_info.o $DIRECT_INSTALL/libecos.a -o simple

Everything will work! Famous last words :-)

Building ecos

Note that we have an installation of ecos in <your_direct_directory>/ecos. This should work on all linux platforms, but just in case you want to build one of your own, here are the instructions. Good luck!

Install tcl-devel-package

If you are on a 64 bit platform, then set LD_LIBRARY_PATH to /usr/lib32

Invoke configtool

Use ecos/direct.ecc as your config file. This should work for both 32 and 64 bit linux.

Go to Build and choose "Generate Build Tree". Then choose "Library"

It will end in errors.

To fix the errors -

Replace "tail +2" with "tail -n +2" in the following makefiles -

direct_build/hal/synth/arch/v2_0/makefile direct_build/hal/synth/i386linux/v2_0/makefile

In directory direct_build do the following -

make -r -C hal/common/v2_0 /home/vishwa/ecos/<install_dir>/lib/extras.o make -r -C hal/synth/i386linux/v2_0 /home/vishwa/ecos/<install_dir>/lib/vectors.o

This will populate the direct_install directory with "include" and "lib" directories. The "lib" directory should now contains the following files -

Add the following line to target.ld -

.eh_frame_hdr : { *(.eh_frame_hdr) } > rom

just before the line

.eh_frame ALIGN (0x4) : { . = .; EH_FRAME_BEGIN = .; KEEP(*(.eh_frame)) FRAME_END = .; . = . + 8; } > rom = 0

This will fix the "no memory region specified for loadable section" error message.

You are done! You should have an ecos installation that should work at this point.

Direct/How to Build Direct (last edited 2009-08-03 22:58:21 by VishwaRaman)