Resource Checker

Overview

The resource checker allows applications to ensure they are properly cleaning up or dereferencing resources to avoid leaks. The resource checker currently detects leaks of reference counted memory and dangling IRQ locks.

Usage

The resource checker will always run against the application when Gantry is included as a module. This will check your app for proper usage of memory allocation and referencing/dereferencing.

Limitations

The resource checker relies on the spatch command provided by Coccinelle. Analysis will be skipped when Coccinelle is not available. Coccinelle is only officially provided for Linux and MacOS, a container may be required to run analysis on Windows.

The resource checker only detects memory leaks within the scope of a single function. See Memory Leak Detection for the rules around memory management. The resource checker currently only detects basic violations (something was allocated or referenced but not freed). It does not detect issues like double-frees. Note that the memory API itself protects against this.

Defining Custom Resources

If the application creates additional functions that allocate or reference memory, it can define a resource_functions.yaml file at the root of the application directory. The resource checker will automatically run analysis against the functions defined in the resource_functions.yaml. For example:

// Custom allocation function
int custom_alloc(void** block)
{
  void* new_block = NULL;
  int ret = mem_alloc(42, &new_block);
  if (ret != SUCCESS)
  {
     // Alloc didn't succeed so there is nothing to free
     NOT_REFERENCED(new_block);
     return ret;
  }

  *block = new_block;

  // The intent is to give ownership to the caller
  PASS_OWNERSHIP(new_block);
  return SUCCESS;
}

custom_alloc would be defined as the following function resource:

alloc_functions:
- name: custom_alloc
    single_param: false

This registers custom_alloc as a function that allocates memory and takes in a single parameter (the allocated block). If custom_alloc is used, the resource checker will automatically ensure that the memory is freed.

The resource_functions.yaml has the following options: alloc_functions for functions that allocate or reference memory and dealloc_functions for functions that free or dereference memory.

For each function, single_param must be set to true or false. When set to true, the resource checker knows that the first and only argument is the memory. When false, the resource checker treats the last argument as the allocated memory. The following is a snippet from Gantry’s built-in resource_functions.yaml:

alloc_functions:
- name: MEM_ALLOC
    single_param: false
- name: MEM_REF
    single_param: true
...

dealloc_functions:
- name: MEM_UNREF
    single_param: true
...