In this section:

Introduction

The C/C++test runtime library is a collection of helper functions and services used by source code instrumentation to emit coverage information at application runtime. Instrumented applications cannot be linked without the library. The runtime library can be linked to the final testable binary in multiple ways depending on tested project type.

In addition to providing basic services for instrumented code, the library is also used to adapt the code coverage solution to particular development environments, such as supporting non-standard transport for coverage results between tested embedded device and development host.

Pre-built Versions and Customized Builds

C/C++test ships with pre-built versions of the runtime library, which are suitable for use on the same platform on which CCE is installed. In most of the cases, collecting code coverage information from natively developed applications (i.e., MS Windows or Linux x86 and x86-64) can use pre-built versions of the runtime library.

All users developing cross-platform applications will need to prepare a custom build of the runtime library using a suitable cross compiler and possibly linker. Source code of the code coverage runtime library is shipped with CCE.

The process of preparing the runtime library custom build is typically limited to the compilation of runtime library source code. In some situations, you may need to install some fragments of source code to adapt code coverage to a particular development platform. This process is described in the following sections.

Using the Pre-built Runtime Library

The following binary files are included with the C/C++test:

Windows (x86 and x86-64) 

FileDescription
<INSTALL_DIR>/runtime/lib/cpptest.a32-bit static archive to be used with Cygwin GNU GCC compilers. To be added to linking command line
<INSTALL_DIR>/runtime/lib/cpptest.lib32-bit import library to be used with Microsoft CL compilers. To be added to linking command line
<INSTALL_DIR>/runtime/lib/cpptes64.lib64-bit import library to be used with Microsoft CL compilers. To be added to linking command line
<INSTALL_DIR>/bin/cpptest.dll32-bit Dynamic-link library to be used with Microsoft CL compilers. [INSTALL_DIR]/bin should be added to PATH environmental variable
<INSTALL_DIR>/bin/cpptest64.dll64-bit Dynamic-link library to be used with Microsoft CL compilers. [INSTALL_DIR]/bin should be added to PATH environmental variable

Linux (x86 and x86-64)

FileDescription
<INSTALL_DIR>/runtime/lib/libcpptest.so32-bit shared library. To be added linking command line. [INSTALL_DIR]/runtime/lib should be added to LD_LIBRARY_PATH
<INSTALL_DIR>/runtime/lib/libcpptest64.so64 bit shared library. To be added linking command line. [INSTALL_DIR]/runtime/lib should be added to LD_LIBRARY_PATH

If you need to use the runtime library in a form not provided as an out-of-the-box solution, prepare a custom build of the runtime library that matches specific development environment requirements. For more details, see Customizing the Runtime Library.

Integrating with the Linker Command Line

Integrating the C/C++test runtime library with a tested application linking process usually requires modifying the linker command line and, in some cases, the execution environment. This section describes how to modify the linking process when using the pre-built versions shipped with C/C++test.

Static library for Windows Cygwin GNU GCC compilers:

  1. Locate the linker command line in your build scripts
  2. Modify the build scripts so that the coverage runtime library is specified somewhere in the linker command line--preferably after all object files.

Dynamic-link library for MS CL compilers:

  1. Locate the linker command line in your build scripts
  2. Modify the build scripts so that the coverage runtime library is specified somewhere in the linker command line--preferably after all object files. For example:

    $(LXX) $(PRODUCT_OBJ) $(OFLAG_EXE)$(PROJ_EXECUTABLE) $(LXXFLAGS) $(SYSLIB) $(EXECUTABLE_LIB_LXX_OPTS) <INSTALL>/runtime/lib/cpptest.lib
  3. Make sure that the [INSTALL_DIR]/bin directory is added to your PATH environment variable so that the library can be located when the tested program is started. You may also consider copying cpptest.dll (or cpptest64.dll) file to the same directory as your executable file or to another location that is scanned for dynamic-link libraries during tested application startup.

Shared library for Linux GNU GCC compilers:

  1. Locate the linker command line in your build scripts
  2. Modify the build scripts so that the coverage runtime library is specified somewhere in the linker command line--preferably after all object files. For example:

    $(LXX) $(PRODUCT_OBJ) $(OFLAG_EXE)$(PROJ_EXECUTABLE) $(LXXFLAGS) $(SYSLIB) $(EXECUTABLE_LIB_LXX_OPTS) -L <INSTALL>/runtime/lib -lcpptest

    Note the addition of the -L [INSTALL_DIR]/runtime/lib and -lcpptest options.

  3. Make sure that shared library can be found by tested executable by modifying LD_LIBRARY_PATH environmental variable to include [INSTALL_DIR]/runtime/lib location.

Customizing the Runtime Library

You may need to customize the runtime library as a result of the following conditions:

  • Different form of binary file is required
  • Enabling a non-default communication channel for results transport
  • Installing custom implementation of communication channel for results transport
  • Enabling a non-default support for multithreaded applications
  • Installing custom implementation of support for multithreaded applications

Library Source Code Structure

The runtime library source code is shipped with C/C++test in the [INSTALL_DIR]/runtime directory. The following table describes the structure: 

ComponentDescription
include

Directory that contains the library include files.
include/cpptest.h - library public interface
include/cpptest/* - library private interface
The content of the include directory is not designed for environment specific modifications.

src

Directory that contains the library source code.
src/cpptest.c - the main and single source file of the runtime library
This file is designed for modifications and customizations.

MakefileBasic Makefile provided for building the runtime library.
targetDirectory that contains a set of Makefile include files with compiler specific options for preparing runtime library builds for most popular development environments.
channelDirectory that contains a set of Makefile include files with configuration for supported communication channels.

Switching Communication Channel Support

The runtime library supports data collection through various communication channels. The communication channel used depends on the development environment. In most cases, storing results in a file or files is appropriate, but in other TCP/IP sockets or RS232 transport may be required. Specific communication channels can be enabled by setting the value to a dedicated macro during cpptest.c library source file compilation. Add -D<MACRO> to the compilation command line to set the value. The following table provides the full list of communication channel control macros:  

ChannelDescription
CPPTEST_NULL_COMMUNICATIONEmpty implementation. If enabled no results will be sent. Suitable for initial test builds and debugging.
CPPTEST_FILE_COMMUNICATION

File-based implementation. ANSI C File I/O interface is used. If enabled, results will be written to a local drive file.

The following additional configuration macros are also provided:

CPPTEST_LOG_FILE_NAME: Name of the results file; default cpptest_results.clog

CPPTEST_LOG_FILE_APPEND: Creates new results file or appends to existing. Default value is 1 -> append, alternative 0 -> create new

CPPTEST_SPLIT_FILE_COMMUNICATION

File-based implementation. ANSI C File I/O interface is used. If enabled, results will be written into a series of local drive files.

You can configure this channel with the following macros:

CPPTEST_LOG_FILE_NAME: Name of the first results file in the series; the default is cpptest_results.clog. Other files will be named in sequence, for example, cpptest_results.clog.0001.

To pass the series to cpptestcli, ensure that all the files in the series are placed in the same directory and provide only the name of the first file as an input. When you run the cpptestcli command, other files will be merged with the first file in the series and removed from the directory.

CPPTEST_MAX_ALLOWED_NUMBER_OF_BYTES_PER_FILE: Specifies the maximum size of one file in the series; default 2000000000 bytes (2 GB).

CPPTEST_UNIX_SOCKET_COMMUNICATION

TCP/IP socket based implementation. POSIX API is used. If enabled results are sent to the specified TCP/IP port. The following additional configuration macros are provided:

CPPTEST_LOG_SOCKET_HOST: Specifies host IP address string

CPPTEST_LOG_SOCKET_PORT: Specifies the port number

CPPTEST_GETHOSTBYNAME_ENABLED: If set to 1, the host can be specified by domain name (requires gethostbyname function to be present)

CPPTEST_WIN_SOCKET_COMMUNICATIONAs above, MS Windows API is used.
CPPTEST_UNIX_SOCKET_UDP_COMMUNICATIONAs above, UDP based implementation.
CPPTEST_RS232_UNIX_COMMUNICATION

RS232 based implementation. POSIX API is used. If enabled then results are sent via the specified RS232 system device. The following additional configuration macros are provided:

CPPTEST_RS232_DEVICE_NAME: System device name

CPPTEST_RS232_BAUD_RATE: Transmission baud rate

CPPTEST_RS232_BYTE_SIZE: Byte size

CPPTEST_RS232_PARITY: Parity control

CPPTEST_RS232_STOP_BIT: Stop bit usage

CPPTEST_RS232_TIMEOUT: Transmission timeout value

CPPTEST_RS232_WIN_COMMUNICATIONAs above. MS Windows API is used.
CPPTEST_RS232_STM32F103ZE_COMMUNICATIONSTM32F103x USART based implementation. STM Cortex library interface is used (ST/STM32F10x/stm32f10x.h header file is required)
CPPTEST_HEW_SIMIO_COMMUNICATIONRenesas HEW simulator specific implementation.
CPPTEST_LAUTERBACH_FDX_COMMUNICATIONLauterbach TRACE32 based implementation (FDX used)
CPPTEST_ITM_COMMUNICATIONARM CoreSight ITM unit based communication. Requires CMSIS header files.
CPPTEST_CUSTOM_COMMUNICATIONEnables empty template for custom implementation

If the runtime library is being built with the provided Makefile, then one of the make configuration files provided in the [INSTALL_DIR]/runtime/channel directory can be used. See Integrating with Make-based Build Systems for details.

Installing Support for Custom Communication Channel

If none of the communication channel implementations fit into your development environment, then a custom implementation can be provided. The following instructions describe how to customize the runtime library so that it uses a custom implementation of a communication channel: 

  1. Make a copy of <INSTALL_DIR>/runtime/src/cpptest.c and open the file for editing.
  2. Locate the section 1.13 "Custom Communication Implementation.
    The custom communication implementation section contains empty templates for four different methods:

    FunctionDescription
    void cpptestInitializeStream(void)This function is responsible initializing the communication channel, for example creating and connecting to a socket or the initialization of UART device.
    void cpptestFinalizeStream(void)This function is responsible for finalizing the communication channel. For example, it may be responsible for closing TCP/IP socket.

    int cpptestSendData(const char *data, unsigned size)

    This function is responsible for sending size bytes from a data buffer.
    void cpptestFlushData(void)This function is responsible for flushing the data. Its meaning depends on the particular transport type. It may have a limited application in some implementations. In this case, it should be left empty.
  3. Provide the implementation for these methods that match your environment requirements.
  4. Compile cpptest.c with the following macro definition added to compilation command line:
    "-DCPPTEST_CUSTOM_COMMUNICATION"
  5. If the generated object file is insufficient, you can process the file even further to meet your needs (e.g., to create a shared library).

Switching Multithreading API Support

The runtime library contains support for multithreaded applications. POSIX, MS Windows, and VxWorks APIs are supported. You can enable support for a specific multithreading API by adding -D<MACRO> to the compilation command line during cpptest.c compilation. The following table describes the full list of multithreading API support control macros:

MacroDescription
CPPTEST_NO_THREADSEmpty implementation. Coverage runtime is not prepared to be used together with multithreaded applications
CPPTEST_WINDOWS_THREADSMS Windows multithreading API implementation
CPPTEST_UNIX_THREADSPOSIX multithreading API implementation
CPPTEST_VXWORKS_THREADSVxWorks multithreading API implementation

Installing Support for Custom Threading API

If you are using C/C++test with multithreaded applications that do not use a supported multithreading API, you can customize the runtime library to work with your multithreading API. There are following steps required:

  1. Make a copy of [INSTALL_DIR]/runtime/src/cpptest.c and open the file for editing
  2. Locate the section 2.5 "Custom Multithreading Implementation"
    Custom multithreading implementation section contains empty templates for two different methods:

    FunctionDescription
    static int cpptestLock(void)This function ensures synchronized operations inside the coverage tool runtime library. If a thread locks access to the runtime library service, it means an atomic operation is in progress and no other thread can use runtime library services. Once the lock is released other threads can use runtime library services
    static int cpptestUnlock(void)Releases the lock on runtime library services.
  3. Provide the implementation for the methods that matches your environment requirements.

  4. Compile cpptest.c with the following macro added to compilation command line:
    "-DCPPTEST_CUSTOM_THREADS"

  5. If the generated object file is insufficient, you can process the file even further to meet your needs (e.g., to create a shared library).

Building the Runtime Library

C/C++test ships with a simple Makefile (see Library Source Code Structure) which simplifies the process of building the runtime library. In many instances, however, the make file provided will not be required because the source code is already optimized for the building process. The only step that is always required is the compilation of the main cpptest.c source file. Any additional processing of the produced object file will depend on the particular development environment and its requirements, such as providing the runtime library as a shared library.

Building the Runtime Library Using the Provided Makefile

  1. Change directory to <INSTALL_DIR>/runtime.
  2. If compilation flags need to be modified (e.g., adding specific cross-compiler specific or definitions to enforce runtime library reconfiguration), provide a new make configuration file in the target subdirectory. For convenience, copy one of the existing target configuration files and modify its contents to fit your needs.

  3. Invoke the following command line to create a build subdirectory that contains a single object cpptest.<OBJ_EXT>, which can be used to link with the instrumented application.

    make TARGET_CFG=<target config file name> CHANNEL_FILE=<channel config file name>

    Your command line may resemble the following:

    make TARGET_CFG=gcc-static.mk CHANNEL_FILE=channel/unix-socket.mk

    Alternatively, you can provide the channel type:

    make TARGET_CFG=gcc-static.mk CHANNEL_TYPE=unix-socket
  4. If the coverage runtime library needs to be linked to from a shared library, dynamic link library, or any other type of binary, the Makefile needs to be customized for this purpose or a custom build needs to be setup.

User Build of the Runtime Library

To setup a user build of coverage tool runtime library perform the following steps:

  1. Copy the cpptest.c file from <INSTALL_DIR>/runtime/src/cpptest.c to your preferred location.
  2. Introduce any customizations as described in Customizing the Runtime Library.
  3. Set up a build system of your preference (e.g., IAR Embedded Workbench project or any other type of source code builder).
  4. Modify the compilation flags to contain the compiler include a flag (typically -I) with the following value:
    -I<INSTALL_DIR>runtime/include
  5. Add any required configuration defines (typically -D), for example:
    -DCPPTEST_FILE_COMMUNICATION -DCPPTEST_NO_THREADS
  6. Invoke the command to run your builder (for example, select build command in the IDE).
  7. Locate the resulting object file and use it to link with your instrumented application.


  • No labels