Authoring Library Models

• When to Write Your Own Models
• Alternatives
• Writing and Including a Model
• Guidelines
• Examples

When to Write Your Own Models

There are two situations in which you should consider writing your own models for library (or other) functions.

• The function source code is not available (and there is no CodeSonar model provided). This is particularly likely to happen with third-party library functions.
• The function source code is available, but CodeSonar is not able to infer an important property of the function.
  One solution is to replace the function source code with a model of the function - either by removing the original definition of the function and replacing it with a model, or by using the csonar_replace_* mechanism. See Helping CodeSonar Out for other techniques that can be useful in this situation.

Alternatives

The following configuration file options allow model implementation to be completely avoided in certain cases.

Writing and Including a Model

If you have determined that you need to create your own model, you will need to write source code for the model and then include it in CodeSonar analyses of the appropriate project or projects.

There are two options for adding a new library model to your project: creating separate model files and augmenting project source code.

Separate model files

Building separate model files into the CodeSonar project before building and analyzing the software project allows you to separate the model source from the software project source.

Suppose that you have a project called myproj, a Makefile for building the normal software project, and you are writing library models suitable for compiling with gcc.

EDG_FRONTEND_OPTIONS_APPEND += -Icsonar_libmodels_path

EDG_FRONTEND_OPTIONS_APPEND += "-IC:\Program Files\CodeSecure\CodeSonar\codesonar\libmodels"

Augmenting software project source

Augmenting software project source allows you to avoid creating separate source files for models at all. This is both an advantage (fewer steps for building and analyzing, and fewer files to manage) and a potential disadvantage (your project source files are changed).

Suppose you have a project called myproj and a Makefile for building the normal software project.

/* project source file */
/* ... */
/* normal contents of source file */
/* ... */

#ifdef __CODESONAR__ 
/* put model code here */
#endif

/* ... */
/* remainder of normal contents of source file */
/* ... */

EDG_FRONTEND_OPTIONS_APPEND += -Icsonar_libmodels_path

EDG_FRONTEND_OPTIONS_APPEND += "-IC:\Program Files\CodeSecure\CodeSonar\codesonar\libmodels"

Guidelines

Where possible, a function model should be a real implementation of the function in terms of existing library functions. The models shipped with CodeSonar have been designed to express important relationships clearly and in many cases have useful warning checks associated with them. For example, if the function to be modeled carries out dynamic allocation then the model should call a suitable allocator model such as malloc().

The CodeSonar Extension API functions and macros provide useful functionality for cases where existing models can be used but additional modeling is needed, or where no existing model is suitable at all.

Library Model Macros and Functions describes the models that are most commonly called by other models, and notes the most useful CodeSonar extension macros.

When you are writing models, consider the following questions.

Do you want CodeSonar to treat your model as a library function?

If so, make sure symbol __CSURF_MARKER_LIBRARY_FUNCTION__ is defined at the start of the function. If a function f() is treated as a library function:

• f() is only analyzed if it is called at least once.
• If CodeSonar issues a warning inside the body of f(), the warning will be reported (only) at the call site to f().

What values does the function write and return, where are those values stored, and how are the values related to the function's formal parameters and to global variables in the program?

Consider the return value of the function (if any), as well as any parameters or non-local variables that the function writes to. Essentially, the model should read from and write to the correct memory addresses with the correct values under the correct conditions. Note that this includes accounting for offsets in arrays and other compound data types. Calling memset() is often useful in these cases.

Are there cases where the function doesn't return at all?

The model should fail to return in the same cases. One way to accomplish this is to call _exit().

Notes For Writing C++ Models

When you are modeling C++ functions, the following additional requirements apply.

• The model must have exactly the same type signature as the original function.
• If the model involves templates, they must have the same instantiation as in the original function.
• The source file containing the model must be compiled as C++.

Examples

Example 1: plus()

The return value of plus() is the sum of its arguments.

double plus(double x, double y) { return(x+y); }

Example 2: div()

The return value of div() depends on the values of both its arguments. Note that the model populates both fields of the return value with values correctly computed from the formal parameters. Using the "/" operator ensures that div() calls will be included in Division By Zero checks.

div_t div(int numer, int denom) {
    div_t rv;
    rv.quot = numer / denom;
    rv.rem = numer % denom;
    return rv;
}

Example 3: my_calloc()

Function my_calloc() is a allocator that initializes the allocated block. Note that the model's use of malloc() will cause my_calloc() to be included in Leak and Dynamic Allocation After Initialization checks.

void *my_calloc(size_t nelem, size_t elsize) {
    void *rv = malloc(nelem*elsize);
    int i;
    if( !rv ) return (void*)0;
    rv = memset(rv, 0, nelem*elsize);
    return rv;
}

Example 4: close_and_rest_a_while()

Function close_and_rest_a_while() closes a file and then waits (at least) a specified amount of time before returning. The model uses a call to close() to model the file-closing and a call to sleep() model the waiting. Note that this use of close() in the model will cause close_and_rest_a_while() to be included in Misaligned Object, Type Mismatch, Double Close, Use After Close, and Negative File Descriptor checks.

int close_and_rest_a_while(int fd, int secs) {
    int c = close(fd);
    sleep(secs);
    return(c);
}