SO/kprobe/checker

= KPROBE BASED TRACER TEST SUITE ==

Test suite for kprobe based tracer

== FILES ==

README
* this file

Makefile
* Makefile for automating the build process

_checker
* script to run all tests defined in _test/tracer_test.c

_test/Makefile
* test suite internal Makefile (creates necessary object files)

_test/tracer_test.c
* test suite for Kprobe Based Tracer

_test/tracer_test.h
* test suite header file

_test/tracer.h
* kprobe tracer header file (macros and structures)

_test/test.h
* useful macros for testing

_test/debug.h
* debugging macros

_test/util.h
* useful macros for generic use (error processing)

_helper/*
* helper kernel module for simulating kprobed ops

== BUILDING ==

Use the linux-kernel-labs build infrastructure, i.e run

make build

in the tools/labs/ folder.

If you want to do things by hand, you have to use the Makefile in the
current folder to run build the executable:

make

and the kernel module-specific Makefile command to build the kernel module:

make -C $(KDIR) M=$(KDIR)/tools/labs/skels/assignments/1-tracer/checker/_helper/ ARCH=x86 modules

== RUNNING ==

Use the linux-kernel-labs run infrastructure, i.e. run

make copy

This copies the skel/ subfolder in the future root filesystem image for the
QEMU/KVM virtual machine.

If you want to do things by hand, copy your tracer.ko module and _checker,
tracer_test and tracer_helper.ko to fsimg/root directory on your QEMU/KVM
virtual machine.

In order to run the test suite you can either use the _checker
script or run the tracer_test executable.

The _checker script runs all tests and computes assignment grade:

./_checker

In order to run a specific test pass the test number (1 .. 10) to the
tracer_test executable.

./tracer_test 5

== TESTS ==

Tests are basically unit tests. A single function in the test_fun_array (see
tracer_test.c) is called each time the tracer_test executable is invoked,
testing a single functionality (and assuming previous tests have been run and
passed).

The EXIT_IF_FAIL macro (see test.h) is unnecessary since after each test, the
program completes.

Each test function follows the unit test pattern: initialization, action,
evaluation. The test macro (see test.h) is invoked at the end of each test
for evaluating and grading the test.

== DEBUGGING ==

The debug.h header file consists of several macros useful for debugging
(dprintf, dlog). There are multiple uses of these macros throughout the above
files.

In order to turn debug messages on, you must define the DEBUG macro, either in
a header file, or, I suggest, in the Makefile. The LOG_LEVEL macro limits the
log message types that are to be printed, by default LOG_WARNING (see enum in
debug.h). You may redefine it in a header file or in the Makefile.

Rapid enabling of debug messages is achieved by commenting out the CPPFLAGS
line in the Makefile. It turns on debugging and enables all log messages
(LOG_DEBUG).

== OTHER ==

srand48() and drand48() are used for generating random numbers.