This page contains information about the functionality that is not yet available in a release version of KEDR framework. If you need the features described here, you could check out the most recent revision of the source code available in its repository and build KEDR framework from that source code.

The structure of LeakCheck

The resource leak detector provided by KEDR framework is now organized as follows.

• The LeakCheck core (kedr_leak_check.ko module) analyzes the information about allocation and deallocations and provides API for other components.
• One or more components obtain such information and pass it to the LeakCheck core via the API. Some of these components may be payload modules for KEDR, they may collect information about the calls to allocation/deallocation routines. Some may be kernel-mode components of other kinds, e.g., the tools to track the callback operations of the target module, etc. Even the target module itself can use LeakCheck API to inform the analyzer about some allocation/deallocation events which could be otherwise more difficult to detect (some kind of annotations could be used here).

LeakCheck API

Common notes

1. Assuming the include directory of KEDR is in the search path for header files, the kernel module using the LeakCheck API should use the following #include directive:

#include <kedr/leak_check/leak_check.h>

2. As the module uses functions exported by another module (LeakCheck core), it also needs the .symvers file of the latter, namely

<KEDR install prefix>/lib/modules/`uname -r`/symvers/kedr_leak_check.symvers

is /usr/local by default.

3. In the functions below, caller_address is the return address of the call to the corresponding allocation or deallocation function. That is the address of the machine instruction immediately following the call (x86-specific). The pre- and post-handlers in the payload modules for KEDR have caller_address variable for this purpose, so you can just use it there. If LeakCheck API is used in some other component rather than a KEDR payload module, it is the job of that component to properly determine the value to be passed as caller_address (see also "Annotations" example).

4. Currently, LeakCheck can analyze only one kernel module at a time. So, all the loaded components that use LeakCheck API should give LeakCheck the information only about that particular module.

kedr_lc_handle_alloc()

void
kedr_lc_handle_alloc(struct module *mod, const void *addr, size_t size, 
	const void *caller_address);

Call this function to inform LeakCheck core that the given kernel module, mod, has allocated a resource (e.g. memory block, some object, etc.) at the address addr in memory. addr must not be NULL or ZERO_SIZE_PTR.

The size of the resource is passed as size argument. If the resource is a memory block, size should be the size of this block. For other types of resources, it is also recommended to provide a meaningful value of size argument. In some cases, the size of the structure corresponding to the resource could be convenient to use here.

If the size cannot be obtained, pass 0 as size. This will be interpreted as "unknown size" by LeakCheck.

size must not be equal to (size_t)(-1), this value is reserved.

This function should be called after the resource has actually been successfully allocated.

kedr_lc_handle_free()

Call this function to inform LeakCheck core that the given kernel module, mod, has freed (released, deallocated, ...) the resource that was located at the given address in memory (addr). addr must not be NULL or ZERO_SIZE_PTR.

This function should be called before the resource is actually freed. This is because LeakCheck assumes that the calls to its API happen in exactly the same order as the corresponding allocation and deallocation calls in the code under analysis.

If kedr_lc_handle_free() was called after the deallocation, some other part of the code under analysis could get in between the actual deallocation and that call and allocate the resource. The chances are, the new resource will have the same address as the old one. As a result, a call to kedr_lc_handle_alloc() could also occur before the call to kedr_lc_handle_free() with the same addr value, which could make a mess.

Examples

The following examples are provided to demonstrate how to use LeakCheck to build custom analysis tools. The examples are located in the following directory: /share/kedr/examples/leak_check/

Example 1, "Mempool_ops"

The example demonstrates how to create plugins to LeakCheck using the template-based generation system provided by KEDR and to track custom allocation / deallocation operations.

The module built in this example tracks calls to mempool_alloc() and mempool_free() and uses LeakCheck to analyze consistency of these calls.

See the readme for the example for details.

If you would like to use LeakCheck to process allocation/deallocation events from the functions it currently does not track, the recommended way is to prepare a custom module like it is done in this example rather than to change the modules provided by KEDR framework.

Example 2, "Annotations"

This example demonstrates how to use LeakCheck API in a module that is not a plugin to KEDR by itself. One common use case is annotating custom resource allocation/deallocation operations in a module you develop or, at least, can change a bit and rebuild.

The module is almost the same in this example as in "sample_target" example. The difference is, device_create() and device_destroy() are annotated here with the special calls for LeakCheck to track these operations.

See the readme for the example as well as the comments in its source code for details.