In this section:

Introduction

Parasoft ASMTools is a collection of command line programs focused on structural analysis of assembly level code. The tools produce coverage reports for assembly instructions generated from C and C++ source code. The following tools are included:

• Asminst - This tool wraps original compile, archive, and link commands to produce instrumented objects, archives, and executables. 
• Asmcovbuf - This tool merges the static data generated by asminst with the dynamic coverage data that's generated when the instrumented executable runs.
• Asminfer - This tool provides additional analysis of the coverage information. Only switch tracking is supported.
• Asmdemangler - This tool is used in conjunction with the symbol demangler supplied by the compiler to provide labels for human readable function names to ASMTool reports.
• Asmreporter - This tool creates reports of the generated assembly interwoven with the original C and C++ code.

This documentation is intended to help you understand how the tools work together so that ASMTools can be implemented into your automated workflow.

System Requirements

Parasoft ASM Tools run on Windows and Linux.

Supported Compilers

Installation

Unpack the distribution file to a target location. This directory will contain all ASMTool files and will be referred to as <ASMTOOLS_INSTALL> in this manual.

Adding ASMTools to Path

For convenient access to the ASMTools executables, you can add the _<ASMTOOLS_INSTALL>_ directory to your path.

Windows cmd:

$ SET PATH=%PATH%;<ASMTOOLS_INSTALL>;<ASMTOOLS_INSTALL>/engine/bin

bash or cygwin:

$ export PATH=$PATH:<ASMTOOLS_INSTALL>:<ASMTOOLS_INSTALL>/engine/bin


You can also update the PATH environment variable on Windows to permanently add ASMTools to the path. Refer to the documentation for your version of Windows. 

Uninstalling ASMTools

Remove the '<ASMTOOLS_INSTALL>' directory from disk.

Setting the License

You can configure the settings in the asmtools.properties file located in the <ASMTOOLS_INSTALL> directory to activate your license.

# === LICENSE ===

# === LOCAL LICENSE ===
# Enables local license - be sure to specify password.
#asmtools.license.use_network=false

# Specifies password for the local license. 
#asmtools.license.local.password=[LICENSE PASSWORD]

# === NETWORK LICENSE ===
# Enables network license - be sure to configure license server settings.
#asmtools.license.use_network=true
#asmtools.license.network.host=[LICENSE SERVER HOST]
#asmtools.license.network.port=[LICENSE SERVER PORT]

ASMTools can use either a local or a network license.

Local License

Uncomment the following properties and specify the password you received from Parasoft in the asmtools.license.local.password property.

asmtools.license.use_network=false
asmtools.license.local.password=<LICENSE PASSWORD>

Network License

Uncomment the following properties and specify the License Server host and port (standalone License Server or DTP):

asmtools.license.use_network=true
asmtools.license.network.host=[LICENSE SERVER HOST]
asmtools.license.network.port=[LICENSE SERVER PORT]

General Workflow

You can integrate the ASMTools into simple compile/link commands or large-scale build systems. The following steps describe the general workflow:

1. Invoke asminst tool when compiling the original source into object code:
   This will generate assembly for each source file defined, instrument the assembly files, and assemble the result into object files in the originally defined locations. Asminst will also create tracking files for each source file. The static data will be be stored in a .pail file and will have the same base name and location as each constructed object. You will merge the data in this file with the dynamic data file produced when you run the asmcovbuf executable. Refer to the Asminst documentation for details.
    
2. Link the instrumented object files:
   Asminst performs additional build steps when a link line is encountered. These steps include generation and compilation of additional functions and storage for collecting coverage information during execution. Like instrumented compilation commands, the same static data artifact will be created for each link command run with asminst. Refer to the Asminst documentation for details.
    
3. Execute the final product:
   Run the instrumented result as originally intended and the instrumentation will collect data about what assembly has been executed. Coverage information will be collected and if the executable has file system access and terminates via an end of main() function, then the dynamic data will be written into a .padd file (also called the dynamic data file). The dynamic data file will take the same base name as the executable.
   
   For executable or library code that has no exit state, you can pause the execution environment and collect the dynamic data by reading the memory across a supplied address range. Refer to the Asminst documentation for details.
    
4. Merge dynamic data into the static data:
   Combine the static data (.pail file) with the coverage data (.padd file) using the Asmcovbuf tool. The coverage data will be merged into the .pail file.
    
5. Generate the coverage report:
   Run the Asmreporter tool on the merged .pail file to create a coverage report.