In this section:

Introduction

Asminst is a standalone command line tool instruments applications at the assembly code level— enabling you to view statistics about the application for both instruction and branch coverage. Asminst is intended to integrate seamlessly into existing build environments. This documentation is intended to help developers and build engineers understand how to automate asminst integration.

Supported Compilers

See Supported Compilers.

Before Starting

Asminst requires an assembler configuration argument (see Basic Usage). Use the following command to list the supported assembler acronyms:

asminst --supported-assemblers

Basic Usage

Run asminst with the assembler acronym and build commands to instrument objects, archives, and executables. For example:

$ asminst --assembler-acronym=ppc_ghs_4_2 -- ccppc -c foo.c -o foo.o

You can also use the short form of the --assembler-acronym flag (-a <string>) during invocation.

Asminst will produce a .pail file that contains the static data describing the result of the execution. The example above will produce an instrumented object called foo.o and a static data file called foo.o.pail that describes the object.

Run the instrumented executable and the dynamic coverage data will be stored in a .padd file. The following command generates an executable named foo.elf and static data describing the executable foo.elf.pail:

$ asminst --assembler-acronym=ppc_ghs_4_2 -- ccppc foo.o -o foo.elf

Executing the instrumented binary generates a dynamic coverage data file called foo.elf.padd:

$ ./foo.elf

Merge the .pail and .padd files to produce assembly-level coverage for the instrumented source. See Asmcovbuf for information on merging .pail and .padd files.

Analyzing a Single Source File that Produces an Executable

Compile and link style commands must be split into two steps. For example, the single command for compile and link is not supported:

$ ccppc foo.c -o Foo

Equivalent commands supported by asminst:

$ ccppc -c foo.c -o foo.o
$ ccppc foo.o -o Foo

Run asminst specifying the original compiler commands using the -- separator:

$ asminst --assembler-acronym=ppc_ghs_4_2 -- ccppc -c foo.c -o foo.o

Asminst will process foo.c and create an object file that includes instrumentation. A .pail file will also be created. This is the static data file that can be merged with the .padd dynamic coverage information file.

Run the link command to create an executable:

$ asminst --assembler-acronym=ppc_ghs_4_2 -- ccppc foo.o -o Foo

Run the executable to generate the dynamic coverage file (.padd) and use the Asmcovbuf to merge the .padd with the .pail file to generate the coverage.

Analyzing Makefile-based Projects

You can integrate asminst into a makefile-based project by prepending the existing compiler and linker variables with an invocation of asminst. The following example shows a makefile configured for the GHS PPC compiler: 

CC ?= ccppc
LD ?= ccppc
OBJ = foo.o
%.o: %.c
	$(CC) -c $^ -o $@
Foo: $(OBJ)
	$(CC) -o $@ $^

You can either modify the makefile to use asminst, or specify the CC and LD shell variables on the command, e.g.:

$ make CC="asminst --assembler-acronym=ppc_ghs_4_2 -- ccppc" LD="asminst -a ppc_ghs_4_2 -- ccppc"

Asminst must be prepend both compile and link lines for instrumentation to function correctly. Linking instrumented objects without asminst will lead to unresolved symbols.

Run the executable to generate the dynamic coverage file (.padd) and use the Asmcovbuf to merge the .padd with the .pail file to generate the coverage.

The following example shows a GNU makefile configured for the GNU C/C++ compiler:

GNU Makefile
CC ?= gcc
CPP ?= g++
LD ?= g++
AR ?= ar
OBJ = foo.o
%.o: %.c
    $(CC) -c $^ -o $@
Foo: $(OBJ)
    $(CC) -o $@ $^

You can either modify the makefile to use asminst, or specify the CC, CPP, LD, and AR shell variables on the command, e.g.:

$ make CC="asminst --assembler-acronym=x86_64_gcc -- gcc" CPP="asminst --assembler-acronym=x86_64_gcc -- g++" LD="asminst -a x86_64_gcc -- g++" AR="asminst -a gnu_ar -- ar"

In the above example, the variable LD is set to g++ instead of ld. If the ld command is used for linking, then the gnu_ld acronym must be used. 
If the compiler is used as the linker (as in the above example), then use the acronym corresponding to the target compiler instead of the gnu_ld  assembler acronym. In the above example, the target compiler is set to x86_64_gcc .

Asminst Options

The following options are supported. See the Release Notes for deprecated and ignored options.

Known Issues

PPC GHS: dblink warnings cause link time failures when debugging is enabled.

Asminst may fail when the instrumented assembly is being compiled with -G on the command line. A message of the following form will be in the error log files: 

.dblink: WARNING: 2 problems were encountered while processing debug information, see
  "[some file]" for details.

This occurs when dblink returns a non-zero exit code as warnings occur. The most likely cause of these warnings are how the ..eof and ..bof labels in a given translation unit shift slightly as a result of instrumentation.

Suppress the warnings by adding -dblink.args=-overlap to the command line to fix these errors. The warnings related to the incorrect location of ..bof and ..eof will be suppressed, allowing compilation to continue.

Troubleshooting

Enable verbose logging if you encounter any issues, e.g.:

$ asminst --log-dir=<file name> --verbose <original command>

Redirecting the output to a file will help any Parasoft Support personnel diagnose the issue. If a problem is encountered please contact Parasoft Support via www.parasoft.com/ticket, attaching the generated logging information obtained from the command above.