Skip to main content

IAR Embedded Workbench for Arm 9.70.x

Performing an analysis from the command line

In this section:

To use C-STAT to perform an analysis from the command line, you need:

  • ichecks.exe—use the ichecks tool to generate a manifest file that contains only the checks that you want to perform.

  • icstat.exe—use the icstat tool to perform a C-STAT static analysis on a project, with the manifest file as input.

For information about the checks, see C-STAT® checks.

The input to icstat consists of:

  • The source files for your application, with the compiler command lines.

  • The linker command line for your application.

  • A file that lists the enabled checks that will be performed (or more specifically, the tags for the checks). You create this file using the ichecks tool.

  • A file where the deviations from the performed checks will be stored in a database.

For an example of how to perform a static analysis using C-STAT, follow these steps based on two example source code files cstat1.c and ctat2.c. You can find these files in the directory target\src.

To perform a static analysis using C-STAT:

  1. Select which checks you want to perform by creating a manifest file using ichecks, for example like this:

    ichecks --default stdchecks --output checks.ch

    The checks.ch file lists all the checks that you have selected, in this case, all checks that are enabled by default for the stdchecks package (--default). The file will look like this:

    ARR-inv-index-pos
ARR-inv-index-ptr-pos
...

    To modify the file on check-level, you can manually add or delete checks from the file.

  2. Make sure that your project builds without errors.

  3. To analyze your application, specify your icstat commands. For example like this:

    icstat --db a.db --checks checks.ch analyze -- iccarm
compiler_opts cstat1.c
    icstat --db a.db --checks checks.ch analyze -- iccarm
compiler_opts cstat2.c
    icstat --db a.db --checks checks.ch link_analyze -- ilinkarm
linker_opts cstat1.o cstat2.o

    In these example command lines, --db specifies a file where the resulting database is stored, and the --checks option specifies the checks.ch manifest file. The commands will be executed serially.

    Alternatively, if you have many source files to be analyzed and want to speed up the analysis, you can use the commands command which means that you collect all your commands in a specific file in combination with --parallel. In this case, icstat will perform the analysis in parallel instead. The command line would then look like this:

    icstat --db a.db --checks checks.ch commands commands.txt --parallel 4

    commands.txt contains:

    analyze -- iccarm compiler_opts cstat1.c
analyze -- iccarm compiler_opts cstat2.c
link_analyze -- ilinkarm linker_opts cstat1.o cstat2.o

  4. After running icstat on the cstat1.c file, these messages are listed on the console and stored in the database (assuming all default checks are performed):

    "cstat1.c",12 Severity-High[PTR-null-assign]:Pointer `p' is assigned NULL, then dereferenced.
    "cstat1.c",13: ^ - if (input) is true
    "cstat1.c",15: ! - Pointer assigned NULL: p = foo()
    "cstat1.c",17: ! - Dereference of pointer `p'

"cstat1.c",17 Severity-High[SPC-uninit-var-some]:Variable `p' may be uninitialized.
    "cstat1.c",13: ^ - if (input) is false
    "cstat1.c",17: ! - Read of `*p'

    Note that the messages are followed by trace information, which describes the required execution path to trigger the deviation from the rule, including information about assumptions made on conditional statements.

  5. This message is listed for the cstat2.c file:

    "cstat2.c",7 Severity-High[ARR-inv-index]:Array `arr' 1st
subscript 20 is out of bounds [0,9].

  6. Edit the source files to remove the problem and repeat the analysis.

    Note

    C-STAT has a built-in preprocessor symbol, __CSTAT__, that you can use to explicitly include or exclude specific parts of source code from the analysis. There are also specific C-STAT pragma directives that suppress one or more checks for selected source lines, see Descriptions of compiler extensions for C-STAT.