From ebcfde0f5e9900a2fea4f27e36c90bef5a2020e9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?F=C3=A1bio=20Coutada?= Date: Mon, 6 Jul 2026 23:16:33 +0100 Subject: [PATCH] feat(docs): extract RVS PDF manuals and regenerate index - Extract 28 non-empty RVS PDFs from src/scov/RVS/ to docs-extracted/ - Preserve full source tree structure under docs-extracted/src/scov/RVS/ - Regenerate docs-extracted/index.md to include all 65 extracted documents - List 21 empty PDFs that could not be extracted --- docs-extracted/index.md | 127 +- .../rapitaskviewer/RapiTask_User_Guide.md | 1309 +++ .../doc/Installation_and_Licensing_Guide.md | 1744 +++ .../src/scov/RVS/doc/Integration_Guide.md | 2702 +++++ .../src/scov/RVS/doc/Migration_Guide.md | 1506 +++ .../RVS/doc/RapiTask/RapiTask_User_Guide.md | 1309 +++ .../RVS/doc/RapiTest/RapiTest_User_Guide.md | 1211 ++ .../Spreadsheet_Test_Format_Cheat_Sheet.md | 108 + .../Spreadsheet_Test_Format_User_Guide.md | 3029 +++++ .../Integration_Library_Implementation.md | 1036 ++ .../scov/RVS/doc/Reference/RVS_Annotations.md | 4670 ++++++++ .../src/scov/RVS/doc/Reference/RVS_Files.md | 1833 +++ .../src/scov/RVS/doc/Reference/RVS_Filters.md | 3000 +++++ .../src/scov/RVS/doc/Troubleshooting_Guide.md | 9891 +++++++++++++++++ .../scov/RVS/doc/Using_RVS_with_Jenkins.md | 947 ++ .../Compilers/rvs-ig-compilers-cl500.md | 228 + .../Compilers/rvs-ig-compilers-dcc.md | 164 + .../Compilers/rvs-ig-compilers-gcc.md | 331 + .../Compilers/rvs-ig-compilers-ghs_multi.md | 259 + .../rvs-ig-compilers-tasking_classic_cc166.md | 181 + .../rvs-ig-compilers-tasking_vxtoolset.md | 264 + .../Compilers/rvs-ig-visualstudio.md | 358 + .../Cpus/rvs-ig-cpus-armsim.md | 170 + .../Cpus/rvs-ig-cpus-c166.md | 512 + .../Cpus/rvs-ig-cpus-powerpc.md | 466 + .../Cpus/rvs-ig-cpus-st_arm_cortex.md | 338 + .../rvs-ig-collection-trace32.md | 280 + .../rvs-ig-collection-vx1000.md | 538 + .../Data Collection/rvs-ig-collection-xcp.md | 479 + 29 files changed, 38947 insertions(+), 43 deletions(-) create mode 100644 docs-extracted/src/scov/RVS/auxd/rapitaskviewer/RapiTask_User_Guide.md create mode 100644 docs-extracted/src/scov/RVS/doc/Installation_and_Licensing_Guide.md create mode 100644 docs-extracted/src/scov/RVS/doc/Integration_Guide.md create mode 100644 docs-extracted/src/scov/RVS/doc/Migration_Guide.md create mode 100644 docs-extracted/src/scov/RVS/doc/RapiTask/RapiTask_User_Guide.md create mode 100644 docs-extracted/src/scov/RVS/doc/RapiTest/RapiTest_User_Guide.md create mode 100644 docs-extracted/src/scov/RVS/doc/RapiTest/Spreadsheet_Test_Format_Cheat_Sheet.md create mode 100644 docs-extracted/src/scov/RVS/doc/RapiTest/Spreadsheet_Test_Format_User_Guide.md create mode 100644 docs-extracted/src/scov/RVS/doc/Reference/Integration_Library_Implementation.md create mode 100644 docs-extracted/src/scov/RVS/doc/Reference/RVS_Annotations.md create mode 100644 docs-extracted/src/scov/RVS/doc/Reference/RVS_Files.md create mode 100644 docs-extracted/src/scov/RVS/doc/Reference/RVS_Filters.md create mode 100644 docs-extracted/src/scov/RVS/doc/Troubleshooting_Guide.md create mode 100644 docs-extracted/src/scov/RVS/doc/Using_RVS_with_Jenkins.md create mode 100644 docs-extracted/src/scov/RVS/integration_resources/reference/integration_annexes/Compilers/rvs-ig-compilers-cl500.md create mode 100644 docs-extracted/src/scov/RVS/integration_resources/reference/integration_annexes/Compilers/rvs-ig-compilers-dcc.md create mode 100644 docs-extracted/src/scov/RVS/integration_resources/reference/integration_annexes/Compilers/rvs-ig-compilers-gcc.md create mode 100644 docs-extracted/src/scov/RVS/integration_resources/reference/integration_annexes/Compilers/rvs-ig-compilers-ghs_multi.md create mode 100644 docs-extracted/src/scov/RVS/integration_resources/reference/integration_annexes/Compilers/rvs-ig-compilers-tasking_classic_cc166.md create mode 100644 docs-extracted/src/scov/RVS/integration_resources/reference/integration_annexes/Compilers/rvs-ig-compilers-tasking_vxtoolset.md create mode 100644 docs-extracted/src/scov/RVS/integration_resources/reference/integration_annexes/Compilers/rvs-ig-visualstudio.md create mode 100644 docs-extracted/src/scov/RVS/integration_resources/reference/integration_annexes/Cpus/rvs-ig-cpus-armsim.md create mode 100644 docs-extracted/src/scov/RVS/integration_resources/reference/integration_annexes/Cpus/rvs-ig-cpus-c166.md create mode 100644 docs-extracted/src/scov/RVS/integration_resources/reference/integration_annexes/Cpus/rvs-ig-cpus-powerpc.md create mode 100644 docs-extracted/src/scov/RVS/integration_resources/reference/integration_annexes/Cpus/rvs-ig-cpus-st_arm_cortex.md create mode 100644 docs-extracted/src/scov/RVS/integration_resources/reference/integration_annexes/Data Collection/rvs-ig-collection-trace32.md create mode 100644 docs-extracted/src/scov/RVS/integration_resources/reference/integration_annexes/Data Collection/rvs-ig-collection-vx1000.md create mode 100644 docs-extracted/src/scov/RVS/integration_resources/reference/integration_annexes/Data Collection/rvs-ig-collection-xcp.md diff --git a/docs-extracted/index.md b/docs-extracted/index.md index 0c5aae5be..973fca2bd 100644 --- a/docs-extracted/index.md +++ b/docs-extracted/index.md @@ -1,62 +1,103 @@ --- title: "PikeOS Documentation Extract Index" -generated: "2026-07-06T23:06:49.724638" +generated: "2026-07-06T23:16:13.532186" --- # PikeOS Documentation Extract Index -This index lists all 37 PikeOS PDF manuals that were successfully extracted to markdown. -Eight PDFs were empty (0 bytes) and could not be extracted; they are listed at the end. +This index lists all 65 PikeOS PDF manuals that were successfully extracted to markdown. +Empty (0-byte) PDFs could not be extracted and are listed at the end. | Document | Category | Source PDF | |----------|----------|------------| -| [As User Manual](cdk/as-user-manual.md) | cdk | `docs/cdk/as-user-manual.pdf` | -| [Binutils User Manual](cdk/binutils-user-manual.md) | cdk | `docs/cdk/binutils-user-manual.pdf` | -| [Cpp Preprocessor User Manual](cdk/cpp-preprocessor-user-manual.md) | cdk | `docs/cdk/cpp-preprocessor-user-manual.pdf` | -| [Cpplib Internals](cdk/cpplib-internals.md) | cdk | `docs/cdk/cpplib-internals.pdf` | -| [Gcc Installation Manual](cdk/gcc-installation-manual.md) | cdk | `docs/cdk/gcc-installation-manual.pdf` | -| [Ld User Manual](cdk/ld-user-manual.md) | cdk | `docs/cdk/ld-user-manual.pdf` | -| [Anis Reference Manual](development/anis-reference-manual.md) | development | `docs/development/anis-reference-manual.pdf` | -| [Cfs Reference Manual](development/cfs-reference-manual.md) | development | `docs/development/cfs-reference-manual.pdf` | -| [Instrumentation Monitoring Reference Manual](development/instrumentation-monitoring-reference-manual.md) | development | `docs/development/instrumentation-monitoring-reference-manual.pdf` | -| [Kernel Reference Manual](development/kernel-reference-manual.md) | development | `docs/development/kernel-reference-manual.pdf` | -| [Libstand Reference Manual](development/libstand-reference-manual.md) | development | `docs/development/libstand-reference-manual.pdf` | -| [Psp Development Guide](development/psp-development-guide.md) | development | `docs/development/psp-development-guide.pdf` | -| [Pssw Reference Manual](development/pssw-reference-manual.md) | development | `docs/development/pssw-reference-manual.pdf` | -| [Test Framework Reference Manual](development/test-framework-reference-manual.md) | development | `docs/development/test-framework-reference-manual.pdf` | -| [Volume Provider Reference Manual](development/volume-provider-reference-manual.md) | development | `docs/development/volume-provider-reference-manual.pdf` | -| [Hardware Virtualization](hardware-virtualization/hardware-virtualization.md) | hardware-virtualization | `docs/hardware-virtualization/hardware-virtualization.pdf` | -| [Pikeos Installation Guide](pikeos-installation-guide.md) | general | `docs/pikeos-installation-guide.pdf` | -| [Pikeos C Programming Environment](pikeos-native/pikeos-c-programming-environment.md) | pikeos-native | `docs/pikeos-native/pikeos-c-programming-environment.pdf` | -| [Pikeos Cxx Programming Environment](pikeos-native/pikeos-cxx-programming-environment.md) | pikeos-native | `docs/pikeos-native/pikeos-cxx-programming-environment.pdf` | -| [Pikeos Native Api Extensions](pikeos-native/pikeos-native-api-extensions.md) | pikeos-native | `docs/pikeos-native/pikeos-native-api-extensions.pdf` | -| [Platform Manual Arm](platform/platform-manual-ARM.md) | platform | `docs/platform/platform-manual-ARM.pdf` | -| [Platform Manual Arm 64Bit](platform/platform-manual-ARM_64bit.md) | platform | `docs/platform/platform-manual-ARM_64bit.pdf` | -| [Platform Manual Ppc E500](platform/platform-manual-PPC_e500.md) | platform | `docs/platform/platform-manual-PPC_e500.pdf` | -| [Platform Manual Ppc E500Mc 4G](platform/platform-manual-PPC_e500mc-4g.md) | platform | `docs/platform/platform-manual-PPC_e500mc-4g.pdf` | -| [Platform Manual Ppc E500Mc](platform/platform-manual-PPC_e500mc.md) | platform | `docs/platform/platform-manual-PPC_e500mc.pdf` | -| [Platform Manual Ppc E5500](platform/platform-manual-PPC_e5500.md) | platform | `docs/platform/platform-manual-PPC_e5500.pdf` | -| [Platform Manual X86 Amd64](platform/platform-manual-x86_amd64.md) | platform | `docs/platform/platform-manual-x86_amd64.pdf` | -| [Posix Conformance](posix/posix-conformance.md) | posix | `docs/posix/posix-conformance.pdf` | -| [Posix Cxx](posix/posix-cxx.md) | posix | `docs/posix/posix-cxx.pdf` | -| [Posix Lwip](posix/posix-lwip.md) | posix | `docs/posix/posix-lwip.pdf` | -| [Releasenotes Anis 5.0.3](releasenotes/releasenotes-anis-5.0.3.md) | releasenotes | `docs/releasenotes/releasenotes-anis-5.0.3.pdf` | -| [Releasenotes Apex 5.0.3](releasenotes/releasenotes-apex-5.0.3.md) | releasenotes | `docs/releasenotes/releasenotes-apex-5.0.3.pdf` | -| [Releasenotes Bsp 5.0.3](releasenotes/releasenotes-bsp-5.0.3.md) | releasenotes | `docs/releasenotes/releasenotes-bsp-5.0.3.pdf` | -| [Releasenotes Cfs 5.0.3](releasenotes/releasenotes-cfs-5.0.3.md) | releasenotes | `docs/releasenotes/releasenotes-cfs-5.0.3.pdf` | -| [Releasenotes Hwvirt 5.0.3](releasenotes/releasenotes-hwvirt-5.0.3.md) | releasenotes | `docs/releasenotes/releasenotes-hwvirt-5.0.3.pdf` | -| [Releasenotes Pikeos 5.0.3](releasenotes/releasenotes-pikeos-5.0.3.md) | releasenotes | `docs/releasenotes/releasenotes-pikeos-5.0.3.pdf` | -| [Releasenotes Posix 5.0.3](releasenotes/releasenotes-posix-5.0.3.md) | releasenotes | `docs/releasenotes/releasenotes-posix-5.0.3.pdf` | +| [As User Manual](cdk/as-user-manual.md) | `cdk` | `docs/cdk/as-user-manual.pdf` | +| [Binutils User Manual](cdk/binutils-user-manual.md) | `cdk` | `docs/cdk/binutils-user-manual.pdf` | +| [Cpp Preprocessor User Manual](cdk/cpp-preprocessor-user-manual.md) | `cdk` | `docs/cdk/cpp-preprocessor-user-manual.pdf` | +| [Cpplib Internals](cdk/cpplib-internals.md) | `cdk` | `docs/cdk/cpplib-internals.pdf` | +| [Gcc Installation Manual](cdk/gcc-installation-manual.md) | `cdk` | `docs/cdk/gcc-installation-manual.pdf` | +| [Ld User Manual](cdk/ld-user-manual.md) | `cdk` | `docs/cdk/ld-user-manual.pdf` | +| [Anis Reference Manual](development/anis-reference-manual.md) | `development` | `docs/development/anis-reference-manual.pdf` | +| [Cfs Reference Manual](development/cfs-reference-manual.md) | `development` | `docs/development/cfs-reference-manual.pdf` | +| [Instrumentation Monitoring Reference Manual](development/instrumentation-monitoring-reference-manual.md) | `development` | `docs/development/instrumentation-monitoring-reference-manual.pdf` | +| [Kernel Reference Manual](development/kernel-reference-manual.md) | `development` | `docs/development/kernel-reference-manual.pdf` | +| [Libstand Reference Manual](development/libstand-reference-manual.md) | `development` | `docs/development/libstand-reference-manual.pdf` | +| [Psp Development Guide](development/psp-development-guide.md) | `development` | `docs/development/psp-development-guide.pdf` | +| [Pssw Reference Manual](development/pssw-reference-manual.md) | `development` | `docs/development/pssw-reference-manual.pdf` | +| [Test Framework Reference Manual](development/test-framework-reference-manual.md) | `development` | `docs/development/test-framework-reference-manual.pdf` | +| [Volume Provider Reference Manual](development/volume-provider-reference-manual.md) | `development` | `docs/development/volume-provider-reference-manual.pdf` | +| [Hardware Virtualization](hardware-virtualization/hardware-virtualization.md) | `hardware-virtualization` | `docs/hardware-virtualization/hardware-virtualization.pdf` | +| [Pikeos Installation Guide](pikeos-installation-guide.md) | `general` | `docs/pikeos-installation-guide.pdf` | +| [Pikeos C Programming Environment](pikeos-native/pikeos-c-programming-environment.md) | `pikeos-native` | `docs/pikeos-native/pikeos-c-programming-environment.pdf` | +| [Pikeos Cxx Programming Environment](pikeos-native/pikeos-cxx-programming-environment.md) | `pikeos-native` | `docs/pikeos-native/pikeos-cxx-programming-environment.pdf` | +| [Pikeos Native Api Extensions](pikeos-native/pikeos-native-api-extensions.md) | `pikeos-native` | `docs/pikeos-native/pikeos-native-api-extensions.pdf` | +| [Platform Manual Arm](platform/platform-manual-ARM.md) | `platform` | `docs/platform/platform-manual-ARM.pdf` | +| [Platform Manual Arm 64Bit](platform/platform-manual-ARM_64bit.md) | `platform` | `docs/platform/platform-manual-ARM_64bit.pdf` | +| [Platform Manual Ppc E500](platform/platform-manual-PPC_e500.md) | `platform` | `docs/platform/platform-manual-PPC_e500.pdf` | +| [Platform Manual Ppc E500Mc 4G](platform/platform-manual-PPC_e500mc-4g.md) | `platform` | `docs/platform/platform-manual-PPC_e500mc-4g.pdf` | +| [Platform Manual Ppc E500Mc](platform/platform-manual-PPC_e500mc.md) | `platform` | `docs/platform/platform-manual-PPC_e500mc.pdf` | +| [Platform Manual Ppc E5500](platform/platform-manual-PPC_e5500.md) | `platform` | `docs/platform/platform-manual-PPC_e5500.pdf` | +| [Platform Manual X86 Amd64](platform/platform-manual-x86_amd64.md) | `platform` | `docs/platform/platform-manual-x86_amd64.pdf` | +| [Posix Conformance](posix/posix-conformance.md) | `posix` | `docs/posix/posix-conformance.pdf` | +| [Posix Cxx](posix/posix-cxx.md) | `posix` | `docs/posix/posix-cxx.pdf` | +| [Posix Lwip](posix/posix-lwip.md) | `posix` | `docs/posix/posix-lwip.pdf` | +| [Releasenotes Anis 5.0.3](releasenotes/releasenotes-anis-5.0.3.md) | `releasenotes` | `docs/releasenotes/releasenotes-anis-5.0.3.pdf` | +| [Releasenotes Apex 5.0.3](releasenotes/releasenotes-apex-5.0.3.md) | `releasenotes` | `docs/releasenotes/releasenotes-apex-5.0.3.pdf` | +| [Releasenotes Bsp 5.0.3](releasenotes/releasenotes-bsp-5.0.3.md) | `releasenotes` | `docs/releasenotes/releasenotes-bsp-5.0.3.pdf` | +| [Releasenotes Cfs 5.0.3](releasenotes/releasenotes-cfs-5.0.3.md) | `releasenotes` | `docs/releasenotes/releasenotes-cfs-5.0.3.pdf` | +| [Releasenotes Hwvirt 5.0.3](releasenotes/releasenotes-hwvirt-5.0.3.md) | `releasenotes` | `docs/releasenotes/releasenotes-hwvirt-5.0.3.pdf` | +| [Releasenotes Pikeos 5.0.3](releasenotes/releasenotes-pikeos-5.0.3.md) | `releasenotes` | `docs/releasenotes/releasenotes-pikeos-5.0.3.pdf` | +| [Releasenotes Posix 5.0.3](releasenotes/releasenotes-posix-5.0.3.md) | `releasenotes` | `docs/releasenotes/releasenotes-posix-5.0.3.pdf` | +| [Rapitask User Guide](src/scov/RVS/auxd/rapitaskviewer/RapiTask_User_Guide.md) | `src/scov/RVS/auxd/rapitaskviewer` | `./src/scov/RVS/auxd/rapitaskviewer/RapiTask_User_Guide.pdf` | +| [Installation And Licensing Guide](src/scov/RVS/doc/Installation_and_Licensing_Guide.md) | `src/scov/RVS/doc` | `./src/scov/RVS/doc/Installation_and_Licensing_Guide.pdf` | +| [Integration Guide](src/scov/RVS/doc/Integration_Guide.md) | `src/scov/RVS/doc` | `./src/scov/RVS/doc/Integration_Guide.pdf` | +| [Migration Guide](src/scov/RVS/doc/Migration_Guide.md) | `src/scov/RVS/doc` | `./src/scov/RVS/doc/Migration_Guide.pdf` | +| [Rapitask User Guide](src/scov/RVS/doc/RapiTask/RapiTask_User_Guide.md) | `src/scov/RVS/doc/RapiTask` | `./src/scov/RVS/doc/RapiTask/RapiTask_User_Guide.pdf` | +| [Rapitest User Guide](src/scov/RVS/doc/RapiTest/RapiTest_User_Guide.md) | `src/scov/RVS/doc/RapiTest` | `./src/scov/RVS/doc/RapiTest/RapiTest_User_Guide.pdf` | +| [Spreadsheet Test Format Cheat Sheet](src/scov/RVS/doc/RapiTest/Spreadsheet_Test_Format_Cheat_Sheet.md) | `src/scov/RVS/doc/RapiTest` | `./src/scov/RVS/doc/RapiTest/Spreadsheet_Test_Format_Cheat_Sheet.pdf` | +| [Spreadsheet Test Format User Guide](src/scov/RVS/doc/RapiTest/Spreadsheet_Test_Format_User_Guide.md) | `src/scov/RVS/doc/RapiTest` | `./src/scov/RVS/doc/RapiTest/Spreadsheet_Test_Format_User_Guide.pdf` | +| [Integration Library Implementation](src/scov/RVS/doc/Reference/Integration_Library_Implementation.md) | `src/scov/RVS/doc/Reference` | `./src/scov/RVS/doc/Reference/Integration_Library_Implementation.pdf` | +| [Rvs Annotations](src/scov/RVS/doc/Reference/RVS_Annotations.md) | `src/scov/RVS/doc/Reference` | `./src/scov/RVS/doc/Reference/RVS_Annotations.pdf` | +| [Rvs Files](src/scov/RVS/doc/Reference/RVS_Files.md) | `src/scov/RVS/doc/Reference` | `./src/scov/RVS/doc/Reference/RVS_Files.pdf` | +| [Rvs Filters](src/scov/RVS/doc/Reference/RVS_Filters.md) | `src/scov/RVS/doc/Reference` | `./src/scov/RVS/doc/Reference/RVS_Filters.pdf` | +| [Troubleshooting Guide](src/scov/RVS/doc/Troubleshooting_Guide.md) | `src/scov/RVS/doc` | `./src/scov/RVS/doc/Troubleshooting_Guide.pdf` | +| [Using Rvs With Jenkins](src/scov/RVS/doc/Using_RVS_with_Jenkins.md) | `src/scov/RVS/doc` | `./src/scov/RVS/doc/Using_RVS_with_Jenkins.pdf` | +| [Rvs Ig Compilers Cl500](src/scov/RVS/integration_resources/reference/integration_annexes/Compilers/rvs-ig-compilers-cl500.md) | `src/scov/RVS/integration_resources/reference/integration_annexes/Compilers` | `./src/scov/RVS/integration_resources/reference/integration_annexes/Compilers/rvs-ig-compilers-cl500.pdf` | +| [Rvs Ig Compilers Dcc](src/scov/RVS/integration_resources/reference/integration_annexes/Compilers/rvs-ig-compilers-dcc.md) | `src/scov/RVS/integration_resources/reference/integration_annexes/Compilers` | `./src/scov/RVS/integration_resources/reference/integration_annexes/Compilers/rvs-ig-compilers-dcc.pdf` | +| [Rvs Ig Compilers Gcc](src/scov/RVS/integration_resources/reference/integration_annexes/Compilers/rvs-ig-compilers-gcc.md) | `src/scov/RVS/integration_resources/reference/integration_annexes/Compilers` | `./src/scov/RVS/integration_resources/reference/integration_annexes/Compilers/rvs-ig-compilers-gcc.pdf` | +| [Rvs Ig Compilers Ghs Multi](src/scov/RVS/integration_resources/reference/integration_annexes/Compilers/rvs-ig-compilers-ghs_multi.md) | `src/scov/RVS/integration_resources/reference/integration_annexes/Compilers` | `./src/scov/RVS/integration_resources/reference/integration_annexes/Compilers/rvs-ig-compilers-ghs_multi.pdf` | +| [Rvs Ig Compilers Tasking Classic Cc166](src/scov/RVS/integration_resources/reference/integration_annexes/Compilers/rvs-ig-compilers-tasking_classic_cc166.md) | `src/scov/RVS/integration_resources/reference/integration_annexes/Compilers` | `./src/scov/RVS/integration_resources/reference/integration_annexes/Compilers/rvs-ig-compilers-tasking_classic_cc166.pdf` | +| [Rvs Ig Compilers Tasking Vxtoolset](src/scov/RVS/integration_resources/reference/integration_annexes/Compilers/rvs-ig-compilers-tasking_vxtoolset.md) | `src/scov/RVS/integration_resources/reference/integration_annexes/Compilers` | `./src/scov/RVS/integration_resources/reference/integration_annexes/Compilers/rvs-ig-compilers-tasking_vxtoolset.pdf` | +| [Rvs Ig Visualstudio](src/scov/RVS/integration_resources/reference/integration_annexes/Compilers/rvs-ig-visualstudio.md) | `src/scov/RVS/integration_resources/reference/integration_annexes/Compilers` | `./src/scov/RVS/integration_resources/reference/integration_annexes/Compilers/rvs-ig-visualstudio.pdf` | +| [Rvs Ig Cpus Armsim](src/scov/RVS/integration_resources/reference/integration_annexes/Cpus/rvs-ig-cpus-armsim.md) | `src/scov/RVS/integration_resources/reference/integration_annexes/Cpus` | `./src/scov/RVS/integration_resources/reference/integration_annexes/Cpus/rvs-ig-cpus-armsim.pdf` | +| [Rvs Ig Cpus C166](src/scov/RVS/integration_resources/reference/integration_annexes/Cpus/rvs-ig-cpus-c166.md) | `src/scov/RVS/integration_resources/reference/integration_annexes/Cpus` | `./src/scov/RVS/integration_resources/reference/integration_annexes/Cpus/rvs-ig-cpus-c166.pdf` | +| [Rvs Ig Cpus Powerpc](src/scov/RVS/integration_resources/reference/integration_annexes/Cpus/rvs-ig-cpus-powerpc.md) | `src/scov/RVS/integration_resources/reference/integration_annexes/Cpus` | `./src/scov/RVS/integration_resources/reference/integration_annexes/Cpus/rvs-ig-cpus-powerpc.pdf` | +| [Rvs Ig Cpus St Arm Cortex](src/scov/RVS/integration_resources/reference/integration_annexes/Cpus/rvs-ig-cpus-st_arm_cortex.md) | `src/scov/RVS/integration_resources/reference/integration_annexes/Cpus` | `./src/scov/RVS/integration_resources/reference/integration_annexes/Cpus/rvs-ig-cpus-st_arm_cortex.pdf` | +| [Rvs Ig Collection Trace32](src/scov/RVS/integration_resources/reference/integration_annexes/Data Collection/rvs-ig-collection-trace32.md) | `src/scov/RVS/integration_resources/reference/integration_annexes/Data Collection` | `./src/scov/RVS/integration_resources/reference/integration_annexes/Data Collection/rvs-ig-collection-trace32.pdf` | +| [Rvs Ig Collection Vx1000](src/scov/RVS/integration_resources/reference/integration_annexes/Data Collection/rvs-ig-collection-vx1000.md) | `src/scov/RVS/integration_resources/reference/integration_annexes/Data Collection` | `./src/scov/RVS/integration_resources/reference/integration_annexes/Data Collection/rvs-ig-collection-vx1000.pdf` | +| [Rvs Ig Collection Xcp](src/scov/RVS/integration_resources/reference/integration_annexes/Data Collection/rvs-ig-collection-xcp.md) | `src/scov/RVS/integration_resources/reference/integration_annexes/Data Collection` | `./src/scov/RVS/integration_resources/reference/integration_annexes/Data Collection/rvs-ig-collection-xcp.pdf` | ## Empty PDFs (not extracted) | Source PDF | |------------| -| `docs/codeo-user-manual.pdf` | -| `docs/pikeos-tutorials.pdf` | -| `docs/pikeos-user-manual.pdf` | | `docs/apex/apex-personality.pdf` | | `docs/cdk/gcc-internals.pdf` | | `docs/cdk/gcc-user-manual.pdf` | +| `docs/codeo-user-manual.pdf` | | `docs/development/driver-reference-manual.pdf` | +| `docs/pikeos-tutorials.pdf` | +| `docs/pikeos-user-manual.pdf` | | `docs/posix/posix-personality.pdf` | +| `src/documentation/apex/apex-personality.pdf` | +| `src/documentation/cdk/gcc-internals.pdf` | +| `src/documentation/cdk/gcc-user-manual.pdf` | +| `src/documentation/codeo-user-manual.pdf` | +| `src/documentation/development/driver-reference-manual.pdf` | +| `src/documentation/pikeos-tutorials.pdf` | +| `src/documentation/pikeos-user-manual.pdf` | +| `src/documentation/posix/posix-personality.pdf` | +| `src/scov/RVS/doc/RTBx2xxx_User_Guide.pdf` | +| `src/scov/RVS/doc/RVS_User_Guide.pdf` | +| `src/scov/RVS/doc/RapiCover/RapiCover_User_Guide.pdf` | +| `src/scov/RVS/doc/RapiTime/RapiTime_User_Guide.pdf` | +| `src/scov/RVS/doc/Reference/RVS_Command_Line_Tools.pdf` | diff --git a/docs-extracted/src/scov/RVS/auxd/rapitaskviewer/RapiTask_User_Guide.md b/docs-extracted/src/scov/RVS/auxd/rapitaskviewer/RapiTask_User_Guide.md new file mode 100644 index 000000000..fc8675cb0 --- /dev/null +++ b/docs-extracted/src/scov/RVS/auxd/rapitaskviewer/RapiTask_User_Guide.md @@ -0,0 +1,1309 @@ +--- +title: "Rapitask User Guide" +source: "./src/scov/RVS/auxd/rapitaskviewer/RapiTask_User_Guide.pdf" +category: "src/scov/RVS/auxd/rapitaskviewer" +pages: 44 +extracted: "2026-07-06T23:13:31.450845" +--- + +# Rapitask User Guide + +> Extracted from `./src/scov/RVS/auxd/rapitaskviewer/RapiTask_User_Guide.pdf` (44 pages). +> Figures, diagrams, and tables may not render accurately in plain text. + +User Guide + Version WF20190404 +Disclaimer +The information, text, and graphics contained within this document are +provided for information purposes only by Rapita Systems Ltd. Rapita +Systems Ltd. does not warrant the accuracy or completeness of the +information, text, and other items contained in this document. + + +Copyright and Trademarks +All rights reserved. Information and images contained within this docu- +ment are copyright and the property of Rapita Systems Ltd. or Percepio +AB. All trademarks are hereby acknowledged to be the properties of +their respective owners. + + +Acknowledgements +RapiTask is built using Percepio AB technology. Rapita Systems' tools +are built using AdaCore's GNAT Pro compiler. + + +Rapita Systems Ltd. +Registered in the UK, number 5011090. +Registered address: +Atlas House +Link Business Park +Osbaldwick Link Road +York +YO10 3JB +UK +Phone: +44 (0) 1904 413 945 +http://www.rapitasystems.com/ +This document copyright © 2012-2019, Rapita Systems Ltd. + +Document build 118520 + +ID: DOC/12055 + Table of Contents + + 1. About this guide ............................................................... 5 + 1.1. Who should read this guide? ................................................... 5 + + 1.2. Structure of this guide ........................................................... 5 + + 1.3. Notation ............................................................................ 6 + + 1.4. RVS documentation map ........................................................ 6 + + 1.5. Support ............................................................................. 8 + + + 2. What is RapiTask? ............................................................ 9 + 2.1. Using RVS ......................................................................... 9 + + 2.2. Using RapiTask .................................................................. 13 + + + 3. Using RapiTask to produce results .................................. 15 + 3.1. Setting up RapiTask ............................................................. 15 + + 3.2. Creating a project ............................................................... 15 + + 3.3. Deploying an integration ....................................................... 17 + + 3.4. Preparing an integration ........................................................ 17 + + 3.5. Setting entry point(s) ............................................................ 18 + + 3.6. Refining your analysis .......................................................... 19 + + 3.7. Running an integration ......................................................... 19 + + 3.8. Configuring a project ........................................................... 20 + + + 4. Analyzing scheduling results ........................................... 23 + + 5. RapiTask Viewer .............................................................. 27 + 5.1. Starting RapiTask Viewer ....................................................... 27 + + 5.2. Using RapiTask Viewer ......................................................... 27 + + +RapiTask User Guide vWF20190404 3 + Table of Contents + + + 5.3. Terminology ...................................................................... 29 + + 5.4. Main Window .................................................................... 29 + + 5.5. Finder window ................................................................... 32 + + 5.6. CPU Load Graph ................................................................ 33 + + 5.7. Scheduling Intensity ............................................................. 34 + + 5.8. Actor Instance Graphs ......................................................... 35 + + + 6. Collecting data without instrumenting tasks .................... 37 + 6.1. Instrumenting the context switch routine ..................................... 37 + + 6.2. Producing trace files ............................................................ 38 + + 6.3. Converting trace files to XML trace files ..................................... 38 + + 6.4. Analyzing results ................................................................ 39 + + + 7. Using the command-line ................................................. 41 + + 8. Troubleshooting .............................................................. 43 + + +4 RapiTask User Guide vWF20190404 +1 About this guide + The RapiTask User Guide describes how to use RapiTask to obtain system sched- + uling information while running software on an embedded target or simulator. Fur- + ther, it describes how to view and analyze RapiTask results. + +1.1 Who should read this guide? + This document is intended for RVS users who have an existing RapiTask integration + and want to use this to obtain system scheduling information when they run their + software. + +1.2 Structure of this guide + Chapter 1: About this guide + Describes the purpose and layout of the RapiTask User Guide and the notation + used throughout the document. + + Chapter 2: What is RapiTask? + Describes the features of RapiTask and the process it uses to determine the sched- + uling behavior of embedded software. + + Chapter 3: Using RapiTask to produce results + Describes how to set up RapiTask, and how to use it to create and run a project + to collect scheduling data. + + Chapter 4: Analyzing scheduling results + Explains how to view and compare reports, and how to copy and export report + data to various file formats. + + Chapter 5: RapiTask Viewer + Describes how to use the RapiTask Viewer to analyze RapiTask data. + + Chapter 6: Collecting data without instrumenting tasks + Describes how to use RapiTask to collect task-level scheduling information without + needing to instrument individual tasks in your system. + + Chapter 7: Using the command-line + Describes how to use RapiTask from the command-line. + + Chapter 8: Troubleshooting + Describes how to troubleshoot problems you encounter while using RapiTask. + + +RapiTask User Guide vWF20190404 5 +Notation About this guide + + +1.3 Notation + This document uses the following notation: + • References to other documents and to other chapters or sections in this doc- + ument are written in italics, for example Chapter 1: About this guide. When + reading an electronic copy of this document, you can click on a reference to + navigate to the location of the referenced element. + • Names of RVS applications are formatted in bold italics, for example RVS + Project Manager. + • References to areas or elements in user interfaces are formatted in italics, for + example the Report Navigator. + • Menus, menu choices and button labels are formatted in bold, for example + File » Print or OK. Where buttons have icons, these are shown before their + Label in in-line text, for example Save. + • Names of RVS tools are formatted in bold, for example rvsdriver. + • References to HTML links appear as underlined text, for example + www.rapitasystems.com. + • Folder and file names are formatted in a monospaced font. + • Command-line tools and their commands, annotations and examples are for- + matted in a monospaced font. These are either written in-line with text + or as separate text blocks. When written in-line with text, they are formatted + like the following: rvsdriver, default_instrument, rvs_instr.h. + When written as a separate text block, they are formatted like the examples + below: + rvsdriver --project rvs.rvsprj --all + + #pragma RVS instrument( "function_name", "FALSE" ) + + • When referencing Ada code, the term functions refers to both functions and + procedures. + +1.4 RVS documentation map + This document is part of the Rapita Verification Suite (RVS) document set, which + contains the following documents: + + RVS Installation and Licensing Guide + Describes how to install RVS tools, and licensing options for them. + + RVS Integration Guide + Describes how to integrate RVS tools into build and target environments. + + RVS User Guide + Describes how to set up and run RVS projects, analyze data and export verification + results. + + +6 RapiTask User Guide vWF20190404 +About this guide RVS documentation map + + + RapiTest User Guide + Describes how to use RapiTest to manage test projects. + + Spreadsheet Test Format User Guide + Describes how to write tests for RapiTest in the Spreadsheet Test Format. + + RapiCover User Guide + Describes how to use RapiCover to measure code coverage and address cover- + age holes. + + RapiTime User Guide + Describes how to use RapiTime to measure timing metrics including worst-case + execution time, and how to use these metrics to identify the best optimization + candidates. + + RapiTask User Guide + Describes how to use RapiTask to measure system level task timing information, + visualize traces and gain insight into runtime behavior. + + RTBx 2xxx User Guide + Describes how to use the RTBx data logger. + + RVS Integration Library Implementation Guide + Describes how to implement RVS integration libraries. This document is for use by + readers with a thorough understanding of the implementation of RVS. + + RVS Files Reference Guide + Describes RVS-specific files including input, intermediate and output files. + + RVS Filters Guide + Describes RVS filters, which are used to convert raw trace data into a format that + RVS can analyze, and how to write them. + + RVS Command Line Tools Reference Guide + Describes the command-line tools used by RVS, including a list of available com- + mand options. + + RVS Annotations Reference Guide + Describes the annotations you can use to control instrumentation and analysis + with RVS. + + RVS Troubleshooting Guide + Describes the error and warning messages you may encounter when using RVS + tools, and how to address them. + + RVS Migration Guide + Describes how to migrate between using different versions of RVS. + + +RapiTask User Guide vWF20190404 7 +Support About this guide + + +1.5 Support + For support issues, please contact Rapita Systems Ltd. by any of the following + means: + + Email + support@rapitasystems.com + + Telephone + +44 (0) 1904 413 945 + + Website + www.rapitasystems.com + + To register for support, visit www.rapitasystems.com/register. More than one user + can register per license. + + +8 RapiTask User Guide vWF20190404 +2 What is RapiTask? + RapiTask is a Rapita Verification Suite (RVS) tool designed to collect detailed sys- + tem level task timing information while embedded software runs on target or on + a cycle-accurate simulator. + + RapiTask can analyze tested software to produce a range of scheduling metrics + including the following: + • Core utilization – the number of cores each task ran on. + • CPU utilization – the percentage of CPU utilization for each task on the cores + it ran on. + • Execution time – the time taken to complete each task, excluding time when + the task was not running. + • Response time – the time taken to complete each task, including time when + the task was not running. + • Periodicity – the time between successive executions of each task, counting + from each time it started to the next. + • Separation time – the time between completion of each task and the time it + next started. + • Fragmentation – the number of fragments each task was executed in. + + RapiTask integrates with existing build systems and targets. The RVS Project Man- + ager included with RapiTask lets you apply scheduling instrumentation to your + source code, run your build system to produce result data, and analyze results. + Alternatively, you can run RapiTask through the command-line. + + This chapter describes the key features of the Rapita Verification Suite (RVS), the + suite of verification tools that RapiTask is a part of, before describing the key fea- + tures of RapiTask itself. RVS has core features that determine, in part, how to use + RapiTask. These features are described in the next section. + +2.1 Using RVS + To use RVS, it must be integrated into your existing target build system so you + can collect verification data when you run your code on target. Alternatively, you + can use RVS on host architectures or with simulators. For more information on + RVS integrations, see the RVS Integration Guide. After RVS has been installed and + integrated into your development environment, you can use RVS tools to produce, + analyze and export verification results. A high-level overview of the stages involved + in using RVS is shown in Figure 2.1. + + +RapiTask User Guide vWF20190404 9 +Using RVS What is RapiTask? + + + Figure 2.1: Overview of using RVS + + You can use RVS from both the RVS Project Manager user-interface and com- + mand-line scripts. The RVS User Guide describes how to use these tools in detail. + +2.1.1 Testing with RVS + RVS tools collect verification data during software tests including the following + types: + • System tests – tests of the entire system to ensure that its overall functional + behavior meets high-level requirements. + • Integration tests – tests of the integration between software components to + ensure that they interact properly. + • Unit tests – tests of individual software components designed to ensure that + they meet low-level requirements. + +2.1.2 RVS projects + RVS projects store data about your source code, RVS Integrations and Analyses + that you configure, and settings you provide RVS about your Target. This informa- + tion is all stored in a project file that has the .rvsprj extension. + + The structure of RVS project files is designed to reduce the effort needed for your + testing processes. Settings are grouped into Project, Integration, Analysis + + +10 RapiTask User Guide vWF20190404 +What is RapiTask? Using RVS + + + and Target settings. Each RVS project can have any number of Integrations, + Analyses and Targets. + + Each RVS Integration uses a single Analysis on a single Target. This hierarchical + structure lets you reuse Analyses and Targets between different Integrations, re- + ducing the number of options you must select when configuring new Integrations, + as shown in Figure 2.2. + + + Figure 2.2: RVS integration hierarchy + + As an example, you may want to run both coverage and timing analysis on your + source code, both on your target and host systems. Because timing metrics col- + lected on your host system would not be very useful, you decide not to run timing + integrations on your host system. In this example, you could create the following + integrations: + • Coverage-host + • Coverage-target + • Timing-target + + Because of the RVS project file structure, you need only configure settings for two + targets and two analyses in your project file, and enter an Integration Name for + each of your integrations. + +2.1.3 RVS integrations + In an RVS integration, a specific RVS Analysis is run on a specific Target. This is + done over several discrete stages, as shown in Figure 2.3. Understanding these + stages will help you get the most from RVS. + + +RapiTask User Guide vWF20190404 11 +Using RVS What is RapiTask? + + + Figure 2.3: The RVS workflow + + RVS projects have two distinct workflows, as shown in Figure 2.3. The dual-pass + integration mode is the default and recommended mode. In this mode, you can run + static and dynamic analyses at separate steps, so you need only run static analysis + once during your project rather than each time you run a new integration. This may + save you a lot of computational effort. In the single-pass integration mode, you + must carry out static and dynamic analyses at the same time. + + Figure 2.3 shows the stages of RVS integrations. Some or all of these stages are + carried out when you run RVS, depending on which options RVS is called with. + The actions carried out in each RVS stage are described below: + • Deploy – the folders and integration library needed to run an integration are + created. + • Clean – intermediate files are deleted from integration folders. + • Prepare – source code files are statically analyzed. + • Build – source code files are instrumented, and compiled and linked into ex- + ecutable files that will work on target. + + +12 RapiTask User Guide vWF20190404 +What is RapiTask? Using RapiTask + + + • Run – instrumented executable files from the build stage are run on target. + • Report – verification data obtained from running executable code on target is + written into a report file that can be viewed in the RVS Project Manager. + • Export – verification data obtained from running executable code on target is + written to an output file. + + You can invoke the stages above from both the RVS Project Manager and the + command-line. When you invoke a stage, a script customized to work with the + specific build and target system is run. Because this script is customized, the + workflow shown in Figure 2.3 is applicable to any development environment. + +2.2 Using RapiTask + This section describes key features of using RapiTask. + +2.2.1 How does RapiTask work? + In the standard workflow, RapiTask takes a copy of input source code and injects + additional code into it. The injected code instruments the source code for sched- + uling analysis. The code is compiled and linked into an executable that is run on + the target hardware or simulator. While the executable is run, scheduling data is + collected. Finally, this is written to an output report. This process is summarized + in Figure 2.4. + + + Figure 2.4: How RapiTask works + + In the code injection stage, RapiTask injects instrumentation points (ipoints) in- + to source code. When instrumented code is compiled and linked, ipoints are ex- + panded so scheduling data can be collected when the executable is run on tar- + + +RapiTask User Guide vWF20190404 13 +Using RapiTask What is RapiTask? + + + get. How ipoints are expanded is specific to the target the code is run on and the + method used to collect data. These concepts are discussed in more detail in the + RVS Integration Guide. + +2.2.2 Analyzing scheduling behavior + RapiTask lets you analyze the scheduling behavior in your system so you can iden- + tify problem areas and focus optimization efforts where they will have the most + effect. + + If a task in your software never executes, RapiTask can determine the reason why. + This may be, for example, because higher priority tasks use all the CPU time and + the scheduler never lets the task execute. By identifying this automatically, Rapi- + Task reduces the effort you need to spend to fix the problem. + + If your system runs too slow, you can identify why using RapiTask charts and the + trace view. This may show, for example, that a task is suffering interference from + other tasks or interrupts and has become a bottleneck. You can use this informa- + tion to focus your efforts optimizing the areas of code that actually contribute to + slow execution. + + +14 RapiTask User Guide vWF20190404 + Using RapiTask to +3 produce results + This chapter describes what you need to do to set up a RapiTask project and run + it to produce results. It contains the following sections: + • Setting up RapiTask + • Creating a project + • Deploying an integration + • Preparing an integration + • Setting entry point(s) + • Refining your analysis + • Running an integration + • Configuring a project + +3.1 Setting up RapiTask + To use RapiTask you need to have RVS installed and integrated into your develop- + ment environment. This is outside the scope of this guide; for more information + on installing and integrating RVS see the RVS Installation and Licensing Guide and + RVS Integration Guide respectively. + +3.2 Creating a project + To create a RapiTask project, open the RVS Project Manager application. You can + do this on Windows systems from the Start menu (Start » RVS » RVS Project + Manager). + + When the RVS Project Manager opens for the first time, it opens on the Welcome + page, see Figure 3.1. From this page, create a new project by clicking Create + a new project in the Get started section. + + +RapiTask User Guide vWF20190404 15 +Creating a project Using RapiTask to produce results + + + Figure 3.1: RVS Project Manager Welcome page + + Tip + + If the Welcome page is not open, you can open it by opening the Help + menu and selecting Welcome Page. + + Alternatively, you can create a New RVS Project from the File menu. + + + The New RVS Project Wizard opens, which guides you through project creation. + For a description of each of the options available when you create a new project, + read the on-screen help text or see Section 4.2 in the RVS User Guide. When + prompted, select the Scheduling analysis task and a default profile suitable for + your needs, see Figure 3.2. + + + Figure 3.2: Scheduling analysis settings + + +16 RapiTask User Guide vWF20190404 +Using RapiTask to produce results Deploying an integration + + + Tip + + Mandatory settings in the New RVS Project Wizard are formatted in bold + text. You cannot continue to the next page in the New RVS Project Wizard + unless you have entered all mandatory settings on the current page. Set- + tings in default text formatting are optional. + + When you finish creating your project, RapiTask creates a project folder and a + project file containing your settings on your file system. You can now run tests with + this project file using either the RVS Project Manager or the command-line. + +3.3 Deploying an integration + Before you can use RapiTask to analyze source code, you must deploy an RVS + integration library. Integration libraries contain definitions for RVS functions that tell + RapiTask how to instrument code and collect data from an executable when it runs. + + To deploy an integration using the RVS Project Manager, do the following: + 1. Open the project and select the Integration you want to deploy in the RVS + Project Manager. To change the active integration, use the Active integra- + tion drop-down menu on the project overview page. + 2. Click Deploy in the Actions section of the project overview page. + 3. Confirm by clicking OK. + + Note + + If your project has already been deployed, you must manually delete the in- + tegration library it is using before you can deploy it again. + + Integration libraries are deployed from a template depending on the settings in + the RVS project file. Templates are suitable for most on-host integrations out of + the box. If you want to use RapiTask to analyze software executed on embedded + hardware, however, you may need to edit your deployed integration library. This + should be carried out during the integration process – for more information, see + the RVS Integration Guide and RVS Integration Library Implementation Guide. + +3.4 Preparing an integration + In the Prepare stage of dual-pass integrations, RapiTask statically analyzes and + instruments source code. For more information on the RVS workflow, see Sec- + tion 2.1.3: RVS integrations. + + You only need to Prepare each project once throughout your testing process, + assuming your code does not change. + + To prepare an integration using the RVS Project Manager, do the following: + + +RapiTask User Guide vWF20190404 17 +Setting entry point(s) Using RapiTask to produce results + + + 1. Open the project and select the Integration you want to prepare in the + RVS Project Manager. To change the active integration, use the Active in- + tegration drop-down menu on the project overview page. + 2. Click Prepare in the Actions section of the project overview page. Alterna- + tively, click the Prepare button on the toolbar. + 3. On the dialog window that opens, select whether or not to Clean your inte- + gration and Enable console debug. We recommend that you clean your + integration, to ensure that all the files your integration requires are present. + 4. Confirm by clicking OK. + + + Figure 3.3: Preparing an integration + + When RapiTask prepares an integration, it collects static information about your + source code and writes this to a report. At this stage, you must set the entry point(s) + to your source code and can refine the analysis you want to apply before running + the integration to produce results. + +3.5 Setting entry point(s) + Before RapiTask can build and run your code to produce results, you must set + the entry point(s) to your source code. This lets RapiTask insert pragmas into your + source code that are needed to analyze the scheduling behavior of your code. + + To set entry point(s) to your source code, do the following: + 1. Open the project and select the Integration you want to set entry point(s) + for in the RVS Project Manager. To change the active integration, use the + Active integration drop-down menu on the project overview page. + 2. Select the Analysis tab at the bottom of the project overview page. + 3. Your source code is displayed in the Source code section on the left of the + window. You may not be able to see some nested entries. To expand an entry, + + +18 RapiTask User Guide vWF20190404 +Using RapiTask to produce results Refining your analysis + + + click the icon to the left of it. Select the function(s) you want to set as entry + points, right-click and select Add entry point(s). + 4. The functions are now displayed in the Analysis settings section on the right + of the window. To return to the project overview page, click the Overview tab + at the bottom of the window. + + + Figure 3.4: Setting an entry point + +3.6 Refining your analysis + Before running an integration, you may want to refine the analysis applied by Rap- + iTask, for example to configure the folders, files and functions in your source code + that RapiTask analyzes. To learn how to do so, see Chapter 5 in the RVS User Guide. + +3.7 Running an integration + When running an integration, RapiTask instruments source code for scheduling + analysis, builds instrumented source code into an executable, runs this and writes + the scheduling data obtained to a report file. + + It does this by executing multiple integration stages: Build, Run and Report. You + can run all of these stages together in the RVS Project Manager. For more infor- + mation on the RVS workflow, see Section 2.1.3: RVS integrations. + + To run an integration using the RVS Project Manager, do the following: + 1. Open the project and select the Integration you want to run in the RVS + Project Manager. To change the active integration, use the Active integra- + tion drop-down menu on the project overview page. + + +RapiTask User Guide vWF20190404 19 +Configuring a project Using RapiTask to produce results + + + 2. Click Build & Run in the Actions section of the project overview page. Alter- + natively, click the Build & Run button on the toolbar. + 3. On the dialog window that opens, select settings for the run. Instrumentation + is only applied to your source code if the Include instrumentation option is + checked. The Keep results from previous run option instructs RapiTask to + merge instrumentation data from previous runs into a combined report file. + 4. Confirm by clicking OK. + + Your results open automatically at the end of the run if Open results automatically + was checked. If not, open them by clicking the Results button on the toolbar. + For more information on viewing your results, see Chapter 4: Analyzing scheduling + results. + + Note + + In some cases, you may want to generate executable code using RapiTask + but not run it. If this is the case, you can execute the RVS Build stage with- + out executing the Run stage. To do this, select Build from the Project + menu or click the More actions button beside the Build & Run action + and select Build. + + After this, you will need to invoke the RVS Report stage to generate a re- + port. To do this, select Report from the Project menu or click the + More actions button beside the Build & Run action and select Re- + port. + + +3.8 Configuring a project + Some advanced configuration options are not available in the New RVS Project + Wizard. You may want to change these options for your project. + + To configure options for your project, click on the Configure button on the + project overview page. This opens the RVS Config Editor, see Figure 3.5. For more + information on configuration settings, see Section 4.11 in the RVS User Guide. + + +20 RapiTask User Guide vWF20190404 +Using RapiTask to produce results Configuring a project + + + Figure 3.5: The RVS Config Editor + + When you Save your configuration, your new settings are saved to your project + file. To return to the RVS Project Manager, click Close. + + +RapiTask User Guide vWF20190404 21 +This page intentionally left blank + Analyzing scheduling +4 results + Note + + This chapter provides a short introduction to viewing and analyzing Rapi- + Task results. For a comprehensive reference of features related to viewing + and analyzing results, see Chapter 6 in the RVS User Guide. + + + Note + + RVS includes prebuilt example reports that you can view and use to explore + the concepts in this chapter. To access these, open the Help menu » Exam- + ple Reports. + + + When RapiTask collects data from tests it outputs it into a report file with the .rvd + extension. You can view and analyze this data in the RVS Project Manager and + the RapiTask Viewer. + + To view RapiTask reports, first open the RVS Project Manager. You can do this on + Windows systems by using the Windows Start menu (Start » RVS » RVS Project + Manager). + + You can open a report file in the RVS Project Manager in multiple ways: + • If you have previously prepared or run a RapiTask integration, click the Re- + sults button on the toolbar. This opens the last report generated by RapiTask + for the selected integration. + • To open any report in your file system, open the File menu and select Open + Report, then select the report you want to open. + • To open a report you have viewed recently, open the File menu and the Recent + Reports submenu, then select the report you want to open. + + When you open your report, a report details window opens with the Overview tab + selected. This tab contains general information about your integration including + when it was run and which device it was run on. We recommend you check the + Overview tab to ensure you are viewing the correct report. + + Click the Tasks tab. A page opens showing the scheduling data collected when + your program was executed, see Figure 4.1. + + +RapiTask User Guide vWF20190404 23 + Analyzing scheduling results + + + Figure 4.1: Task Summary + + The chart at the top of this page shows the average CPU utilization for each task in + your source code. This is calculated as the time spent executing the task divided + by the total duration of the trace file. + + The table below the chart shows statistics about the tasks that executed. This + includes data on execution time, response time, periodicity, separation and frag- + mentation. By default, each column shows the average value. Expand the column + headings to show minimum and maximum values. + + Hover over each of the column headings to show a tooltip describing the metrics + in the report. These terms are described in more detail in Section 5.3: Terminology. + + Double-click on the name of a task in the task summary page. This filters the report + to show only data for that task, see Figure 4.2. + + +24 RapiTask User Guide vWF20190404 +Analyzing scheduling results + + + Figure 4.2: Task View, showing CPU Utilization over time + + When viewing a single Task, the chart shows CPU utilization over time. The width + of the slices can be changed in the Report Properties dialog, accessible via the + spanner icon at the top of the page. + + Click the RapiTask Viewer icon on the toolbar. This opens the RapiTask Viewer, + which you can use to investigate the scheduling behavior of your program in detail. + + Click the Synchronize button. This synchronizes the RVS Project Manager + and the RapiTask Viewer. While the applications are synchronized, clicking on a + blue dot by a task in the RVS Project Manager jumps to that time in the RapiTask + Viewer, and clicking on an element in the RapiTask Viewer opens it in the RVS + Project Manager. + + The RapiTask Viewer provides more in-depth graphs and tables showing the + scheduling behavior of your system, see Chapter 5: RapiTask Viewer. + + This chapter provided a short introduction to viewing RapiTask results. For a com- + prehensive reference of features related to viewing and analyzing results, see + Chapter 6 in the RVS User Guide. + + +RapiTask User Guide vWF20190404 25 +This page intentionally left blank +5 RapiTask Viewer + + + Figure 5.1: RapiTask Overview + + RapiTask provides several interlinked views of the runtime behavior of your appli- + cation. RapiTask shows information about the scheduling and timing of tasks and + interrupts. + + RapiTask contains several advanced features that help you to quickly understand + your trace data. For instance, RapiTask provides various high level views such as + the CPU load graph that make it easier to find anomalies in a trace. + +5.1 Starting RapiTask Viewer + When viewing a RapiTask report, the RapiTask toolbar provides access to the Rap- + iTask Viewer. Figure 5.2 shows the location of this toolbar. + + + Figure 5.2: RapiTask Toolbar + + The first button opens the RapiTask Viewer, while the second button synchronizes + the two applications: + • Clicking on a cell containing a blue dot in the RVS Project Manager jumps to + that time in the RapiTask Viewer. + • Clicking on an element in the RapiTask Viewer opens it in the RVS Project + Manager. + +5.2 Using RapiTask Viewer + RapiTask provides several graphical views which give different perspectives of the + system's runtime behavior. These views are based on a trace of task scheduling + + +RapiTask User Guide vWF20190404 27 +Using RapiTask Viewer RapiTask Viewer + + + and function calls. You may also choose to include interrupt service routines (ISRs) + as well as application events. + + This section gives a quick overview of the available features. More detailed infor- + mation is given in later sections. + + + Figure 5.3: Main View, containing the trace view (left) and the tool panel (right) + + The main trace view provides all recorded information on a vertical time line. This + view is complemented by several additional views providing high level overviews + or focused views from different perspectives. The task scheduling is presented + using color coded rectangles, where the color helps identify the actor. By actor we + mean a thread of execution: a task or interrupt. + + +28 RapiTask User Guide vWF20190404 +RapiTask Viewer Terminology + + +5.3 Terminology + Actor A task or an Interrupt Service Routine (ISR) + or function. + Actor Instance An execution of an actor. For interrupt ser- + vice routines, this means from start to fin- + ish of the ISR handler. For tasks, this is ap- + plication-dependent but typically means + one iteration in the main loop. An Actor In- + stance consists of one or more fragments, + depending on preemptions, blocking and + interrupts. + Execution Time The amount of CPU time used by an Actor + Instance, excluding preemptions. + Response Time The wall-clock time from the start of an ac- + tor instance until it finishes. Note that the + Response Time is counted from the start + of execution, not from when the task be- + comes ready to execute. + Fragment A time interval when a specific actor exe- + cutes uninterrupted. Fragments are visual- + ized as colored rectangles in the schedul- + ing trace. A fragment belongs to a specific + Actor Instance. + Fragmentation The number of fragments within an Actor + Instance. If an Actor Instance executes in + full without preemptions, the fragmentation + of the instance is 1. + ISR Interrupt Service Routine, i.e. the handler of + an interrupt. + Periodicity The time between two consecutive in- + stances of an actor, counted from the start + of the previous actor instance to the start of + the current actor instance. + Separation The time between two consecutive in- + stances of an actor, counted from the end + of the previous actor instance to the start of + the current actor instance. + + +5.4 Main Window +5.4.1 Trace View + Figure 5.3 shows the main view of RapiTask. All of the recorded events are present- + ed on a vertical time-line going downwards. The main component of this view is an + execution trace, which displays actor fragments as color-coded rectangles. The + colors are unique for each actor, and are assigned based on scheduling priority. + + +RapiTask User Guide vWF20190404 29 +Main Window RapiTask Viewer + + + To the left of Figure 5.3 are labels showing actor names. When zooming out, the + name labels are filtered so that only some are shown. Repeated labels of the same + actor are hidden, in favor of labels for less frequent actors. However, there is always + at least one label per visible actor, and you can click in the trace to show the + corresponding actor name label. + + Double-clicking on an actor opens a focused view showing all instances of the + actor. + + View Modes + + The execution of tasks and interrupts can be visualized using three view modes, + which you can switch between quickly to optimize the display according to your + requirements. The modes are: + • Split View Mode: Shows tasks and interrupts in two columns, with indentation + like the Merged View Mode. This removes the "noise" from interrupts by pre- + senting them separately. This is the default visualization mode. (Shortcut: S.) + • Gantt View Mode: Shows one column per task and interrupt. This is the pre- + ferred view mode for spotting rare actor instances and for visualizing periodic + behavior. (Shortcut: G.) + • Merged View Mode: Shows all tasks and interrupts in a single column, with + sideways indentation to show preemption and blocking. This gives the best + sense of execution order. (Shortcut: M.) + + Zoom and navigation features + + To navigate the trace, you can use the mouse wheel or the scroll bar (on the right). + You can also drag the view by holding down the mouse wheel or middle mouse + button. The arrow buttons and page up/down buttons can also be used when the + main trace view area has focus. + + Note + + When searching for a particular location, it is often easiest to use the Finder + (Section 5.5) or one of the graphical overviews to find it. When using anoth- + er view to navigate the trace, you can click or double-click to focus the trace + view on this location. All graphical views also support selecting a time inter- + val (by pressing the left mouse button and dragging) and showing this inter- + val in the trace view. + + + To zoom in or out, use the zoom buttons on the tool panel, the number pad + and + - buttons or the zoom options in the right-click menu. You can also zoom with your + mouse wheel when holding down the CTRL key. The scroll-to-zoom behavior is + always active when Scroll Lock is enabled. If your mouse features back and + forward buttons, you can use these to zoom in and out quickly. + + +30 RapiTask User Guide vWF20190404 +RapiTask Viewer Main Window + + + Tool Panel + + To the right of the trace view is the tool panel. At the top is the Actor Information + display (Figure 5.4), which shows information about the selected actor and the + currently selected actor instance (such as timing, fragmentation and any events + that occur). Property values for the selected instance are displayed as well as actor + average, maximum and minimum execution time. Double-clicking on maximum or + minimum values shows the corresponding instance in the trace. + + + Figure 5.4: Actor information + + Below the Actor Information display are buttons to navigate to the previous and + next instance of the same actor. + + You can set the view size (zoom level) by typing the desired view size into the view + size text box and pressing enter. Under the view size setting are the grid settings, + used to control the white and gray stripes in the trace view. The stripes show the + time scale of the grid in the trace view. + + Below the view settings are buttons to zoom in and out. Below these zoom buttons + are a series of three controls to allow the view mode to be set. From left to right, + the controls set Gantt view mode, Merged view mode and Split view mode. + + At the bottom of the tool panel is the visibility filter box, which controls what is + displayed in the trace view. By default; all actors are visible. Unchecking an actor + will not hide it completely, but cause its fragments to be drawn as outlined gray + rectangles. + + +RapiTask User Guide vWF20190404 31 +Finder window RapiTask Viewer + + +5.4.2 Menu options + File + + The File menu features standard options such as Reload File and Exit. It also + includes the specialized options Save Current View As Image and Export Actor + Data. + + Save Current View As Image lets you export the current trace view to an image, + e.g. for documentation or for sharing an issue with colleagues. + + Export Actor Data lets you export actor instance data to a text file. The exported + data includes start time, execution time, response time and fragmentation of each + instance of the selected actors. You can export it as tab separated fields for import + into other tools, or space aligned columns for easy reading. + + Find + + The Find menu lets you find previous or next instances quickly from a selected + instance. It also lets you open the Finder dialog, which you can also open using + the shortcut CTRL-F. + + View + + The View menu lets you configure the trace view and open other views. These + other views are described in Section 5.6 through Section 5.8. + + Trace Details shows properties of the current trace, such as the number of events, + the length of the trace and other technical details. + + Trace View Settings lets you configure the trace view, such as the colors of actors + and whether to display bookmarks or not. + + Trace View Mode lets you set the View Mode (e.g. Gantt or Split) as described + above. + + Show Tool Panel lets you toggle the visibility of the tool panel to the right. This can + be useful if you want to make the application window smaller, e.g. when multiple + views are open. + + Bookmarks + + The Bookmark menu lets you create and organize bookmarks. If you want to share + bookmarks with colleagues, you can export and import them using the respective + menu options. Any bookmarks will also be displayed in this menu. + +5.5 Finder window +5.5.1 Overview + The Finder window lets you find actor instances quickly by using various filters. + The Finder also lets you jump to particular points in time. + + +32 RapiTask User Guide vWF20190404 +RapiTask Viewer CPU Load Graph + + + Figure 5.5: Finder view + +5.5.2 Actor Instances Tab + The Actor Instances tab lets you find and follow actor instances matching various + search criteria. + + To the left is a list of actors in the trace. Select one or more actors to obtain a list + of instances. You can select multiple actors by holding down CTRL and clicking. + When one or more actors are selected, the navigation buttons are enabled. + + To the right is a filter which is enabled when a single actor is selected. Only in- + stances where the values are between the At Least and At Most values are + included in the search. By default, the boxes contain the lowest and highest value + of all instances, so that all instances are included. Note that the filter is not avail- + able if you have multiple actors selected. + +5.5.3 Time Point Tab + The Time Point tab lets you jump to a specific point in the trace by entering a + timestamp and pressing Enter. + +5.6 CPU Load Graph +5.6.1 Overview + The CPU Load Graph displays CPU usage over time, per actor and in total. By + default, it shows all actors except the idle task. The analysis works by dividing the + trace into a number of intervals (the default is 100). The CPU usage for an actor in + an interval is the amount of CPU time used by the actor within the interval divided + by the length of the interval. For each interval, all actors that execute in that interval + are drawn as rectangles stacked on top of each other. The height of each actor's + rectangle represents the CPU usage for that actor in that time interval and the + combined height is the total CPU usage for that interval. + + +RapiTask User Guide vWF20190404 33 +Scheduling Intensity RapiTask Viewer + + + Figure 5.6: CPU load graph + + To customize the view, use the Select Actor(s) menu. There you can select which + actors you wish to include in the view. If the graph is "noisy" (due to short intervals), + you can reduce the number of intervals through the Resolution menu. For a more + detailed graph, you can increase the number of intervals by selecting a higher + resolution. In order to focus on a specific area, you can click and drag to select + an interval and use the Zoom menu or right-click to zoom in on it. You can also + use the Zoom or right-click menu to show the selection or current view in the trace + view or in all open views. + + Clicking an actor in the graph will display information about that actor in the clicked + interval, and double-clicking an actor will center the trace view on that interval. A + gray outlined rectangle shows the interval of the current trace view. This rectangle + may be very narrow and appear as a line if the trace view is small. In this case, + you can zoom in to show the interval in more detail. + +5.7 Scheduling Intensity +5.7.1 Overview + This view displays the frequency of context switches over time. By default, it shows + the whole trace divided into 100 intervals. For each time interval, a bar is drawn + for each actor beginning or resuming execution at least once in that interval. The + height of the bars represents the number of times that actor has begun or resumed + execution in the given interval, i.e., the number of fragments of the actor. + + The number of intervals can be controlled through the Resolution menu. You can + click and drag to select an interval and use the Zoom or right-click menu to zoom + in on that selection, to show it in the trace view or to show it in all open views. + + +34 RapiTask User Guide vWF20190404 +RapiTask Viewer Actor Instance Graphs + + + Note + + When zooming in the Scheduling Intensity view, the interval length decreas- + es to show a more detailed graph. When significantly zoomed, or if your + trace is short, you might get empty space in the graph corresponding to in- + tervals where no context switches occur. + + +5.8 Actor Instance Graphs +5.8.1 Overview + The Actor Instance Graph window displays a graph showing timing properties of + actor instances: execution time, response time, response interference and frag- + mentation. Each data point in the graph represents a specific actor instance, where + the x-axis indicates the instance start time and the y-axis the property value. + • Execution Time: The amount of CPU time used by an actor instance, exclud- + ing preemptions. + • Response Time: The wall-clock time from the start of an actor instance until it + finishes. Note that the Response Time is counted from the start of execution, + not from when the task becomes ready to execute. + • Response Interference: The relation between execution time and response + time. A value of 30% means that the response time is 30% longer than the + execution time, i.e., due to preempting tasks, interrupts or blocking. A value of + 0% means that the response time is equal to the execution time, i.e., that the + actor instance executed to completion without context switches. + • Fragmentation: The number of fragments within an actor instance, e.g., due + to context switching. If an actor instance executes in full without preemptions, + the fragmentation of the instance is 1. + + Clicking a plotted instance will show and highlight it in the trace view. You can filter + actors using the Filter menu or by clicking on an actor in the legend to the right. + + If you want to focus on a specific area, you can click and drag to select an interval + and use the Zoom menu or right-click to zoom in on it. You can also use the Zoom + or right-click menu to show the selection or current view in the trace view or in all + open views. + + This view can be used to identify long-running tasks using the execution and re- + sponse time graphs, or potential scheduling problems using the fragmentation + and interference graphs. + + +RapiTask User Guide vWF20190404 35 +This page intentionally left blank + Collecting data without +6 instrumenting tasks + When collecting system event traces, you may not be able to instrument the in- + dividual tasks in your system, or may not want to so that you can collect results + in fewer builds on resource-constrained targets. To support this, RapiTask has an + OS-only mode that only requires you to instrument your system's context switch + routine, and not the individual tasks in your system, see Figure 6.1. + + + Figure 6.1: Collecting task-level timing data without instrumenting tasks + + This chapter describes how to set up, run, and analyze results from a RapiTask + OS-only mode analysis, which involves the following steps: + 1. Instrumenting the context switch routine + 2. Producing trace files + 3. Converting trace files to XML trace files + 4. Analyzing results + +6.1 Instrumenting the context switch routine + To collect task-level timing without instrumenting the tasks in your system, your + system's context switch routine must be manually instrumented so that it includes + an RVS instrumentation point marking the start and end of execution of each task. + + Unlike when using RapiTask normally, instrumentation of the context switch routine + must be applied manually. The following example shows a simple context switch + routine instrumented appropriately. + + +RapiTask User Guide vWF20190404 37 +Producing trace files Collecting data without instrumenting tasks + + + Example 6.1: Context switch routine instrumentation + + void TaskSwitchContext( void ) + { + RVS_I(5); // Context switch out + + // Find the highest priority task pending and switch to it + TopReadyPriority = TopPriority; + while( ReadyTasksLists[ TopReadyPriority ].Pending == 0 ) + { + TopReadyPriority -= 1; + } + TaskSwitchFrames(CurrentTask, + ReadyTasksLists[ TopReadyPriority ]); + CurrentTask = ReadyTasksLists[ TopReadyPriority ]; + + RVS_I(6); // Context switch in + RVS_I(CurrentTask.Ident); // New task ID + } + + + If you need help instrumenting your context switch routine, contact + support@rapitasystems.com. + +6.2 Producing trace files + When instrumented appropriately, one or more Rapita Systems trace (RPZ) files + will be produced while your system is running. These are needed for further analy- + sis. + +6.3 Converting trace files to XML trace files + To analyze results from RapiTask when used in OS-only mode, you must first pro- + duce an XML trace (XMLTRC) file by converting the Rapita Systems trace (RPZ) + files produced during the analysis. To do this, you can use the RVS command-line + tool taskparser_os. + + taskparser_os produces XMLTRC files, requiring the following as inputs: + • One or more Rapita Systems trace (RPZ) files. + • The system's clock frequency, in Hertz. + • A task list file containing a list of mappings between task IDs in input RPZ + files and task names in the output XMLTRC file. + + The task list file must be in a comma separated format, with newlines between + subsequent tasks, as in the following example: + + +38 RapiTask User Guide vWF20190404 +Collecting data without instrumenting tasks Analyzing results + + + Example 6.2: Task list file syntax + + 100,HighTick + 200,Poller + 300,MidFast + 400,MidSlow + 500,Background + + + The example below shows how to convert the trace file trace1.rpz to + results.xmltrc using the mapping file mapping.txt: + + Example 6.3: Converting trace files to XML trace files + + taskparser_os trace1.rpz --task-list mapping.txt --clock-hz 50000000 + --output results.xmltrc + + + For more information on taskparser_os, see Chapter 17 in the RVS Command + Line Tools Reference Guide. + +6.4 Analyzing results + You can view XMLTRC files produced by RapiTask OS-only analysis in the Rapi- + Task Viewer. + + For more information on viewing results in the RapiTask Viewer, see Chapter 5: + RapiTask Viewer. + + +RapiTask User Guide vWF20190404 39 +This page intentionally left blank +7 Using the command-line + Whenever RapiTask is run, whether through the RVS Project Manager or the com- + mand-line, it is run using rvsdriver, which manages all of the back-end tools in- + volved in RVS integrations, see Section 2.1: Using RVS. + + The RVS Project Manager includes a Custom Command utility that makes it easy + to configure rvsdriver runs. You can use this utility to run custom commands from + within the RVS Project Manager or to generate scripts to use RVS outside the + RVS Project Manager. + + For more information on using the Custom Command utility, see Chapter 8 in the + RVS User Guide. + + +RapiTask User Guide vWF20190404 41 +This page intentionally left blank +8 Troubleshooting + This chapter describes what to do if you encounter any problems while using Rap- + iTask. + + Many problems that occur when using RapiTask are related to its integration with a + development and target environment. For information on the integration process, + see the RVS Integration Guide. + + If you receive a warning or error message while using RapiTask, you can look up + the cause of the error and learn how to resolve it in the RVS Troubleshooting Guide. + This document also describes known issues in RapiTask and other RVS tools. + + If you encounter a problem while using RapiTask, feel free to contact us at + support@rapitasystems.com or +44 (0) 1904 413 945. Please supply as + much information as possible about your problem, so we can resolve it promptly. + + For more information on the RVS troubleshooting process, see the RVS User + Guide. + + +RapiTask User Guide vWF20190404 43 +This page intentionally left blank + diff --git a/docs-extracted/src/scov/RVS/doc/Installation_and_Licensing_Guide.md b/docs-extracted/src/scov/RVS/doc/Installation_and_Licensing_Guide.md new file mode 100644 index 000000000..9b1b5f5e6 --- /dev/null +++ b/docs-extracted/src/scov/RVS/doc/Installation_and_Licensing_Guide.md @@ -0,0 +1,1744 @@ +--- +title: "Installation And Licensing Guide" +source: "./src/scov/RVS/doc/Installation_and_Licensing_Guide.pdf" +category: "src/scov/RVS/doc" +pages: 44 +extracted: "2026-07-06T23:13:31.498239" +--- + +# Installation And Licensing Guide + +> Extracted from `./src/scov/RVS/doc/Installation_and_Licensing_Guide.pdf` (44 pages). +> Figures, diagrams, and tables may not render accurately in plain text. + +Installation and +Licensing Guide + Version WF20190404 +Disclaimer +The information, text, and graphics contained within this document are +provided for information purposes only by Rapita Systems Ltd. Rapita +Systems Ltd. does not warrant the accuracy or completeness of the +information, text, and other items contained in this document. + + +Copyright and Trademarks +All rights reserved. Information and images contained within this doc- +ument are copyright and the property of Rapita Systems Ltd. All trade- +marks are hereby acknowledged to be the properties of their respective +owners. + + +Acknowledgments +Rapita Systems' tools are built using AdaCore's GNAT Pro compiler. + + +Rapita Systems Ltd. +Registered in the UK, number 5011090. +Registered address: +Atlas House +Link Business Park +Osbaldwick Link Road +York +YO10 3JB +UK +Phone: +44 (0) 1904 413 945 +http://www.rapitasystems.com/ +This document copyright © 2013-2019, Rapita Systems Ltd. + +Document build 118520 + +ID: DOC/13001 + Table of Contents + + 1. About this guide ............................................................... 5 + 1.1. Who should read this guide? ................................................... 5 + + 1.2. Structure of this guide ........................................................... 5 + + 1.3. Notation ............................................................................ 6 + + 1.4. RVS documentation map ........................................................ 6 + + 1.5. Support ............................................................................. 8 + + + 2. Installing and maintaining RVS ......................................... 9 + 2.1. System requirements ............................................................. 9 + + 2.2. Installing RVS .................................................................... 11 + + 2.3. Checking RVS installations .................................................... 18 + + 2.4. Uninstalling RVS ................................................................. 18 + + + 3. RVS licensing and license management .......................... 19 + 3.1. RVS license options ............................................................. 19 + + 3.2. License duration, expiry and renewal ........................................ 20 + + 3.3. The RVS License Manager .................................................... 21 + + 3.4. USB license keys ................................................................ 21 + + + 4. RVS floating license configuration ................................... 23 + 4.1. RVS License Server requirements ............................................ 23 + + 4.2. Installing the RVS License Server ............................................. 25 + + 4.3. Configuring the RVS License Server ......................................... 27 + + 4.4. Using the RVS License Server ................................................ 29 + + 4.5. Troubleshooting RVS License Server problems ............................. 31 + + 4.6. License server log files ......................................................... 31 + + +RVS Installation and Licensing Guide vWF20190404 3 + Table of Contents + + + 4.7. Configuring a client machine to use a license server ...................... 33 + + 4.8. Uninstalling the RVS License Server .......................................... 35 + + + 5. RVS License Manager ..................................................... 37 + 5.1. Adding a license ................................................................ 37 + + 5.2. Checking installation and license details .................................... 38 + + 5.3. Managing license servers used by a client .................................. 38 + + 5.4. Installing USB license key drivers ............................................. 38 + + 5.5. Updating USB license keys .................................................... 39 + + + 6. RVS files and folders ...................................................... 41 + + A. Third-party licenses used by RVS ................................... 43 + + +4 RVS Installation and Licensing Guide vWF20190404 +1 About this guide + The RVS Installation and Licensing Guide explains the license options for RVS, + and describes how to install license server software on a host machine. + +1.1 Who should read this guide? + This guide is intended for users or system administrators responsible for the in- + stallation of software on a single machine or the installation, configuration and + maintenance of software within an organization. + +1.2 Structure of this guide + This document includes the following chapters: + + Chapter 1: About this guide + Describes the purpose and layout of the RVS Installation and Licensing Guide and + the notation used throughout the document. + + Chapter 2: Installing and maintaining RVS + Describes how to install and uninstall RVS, and upgrade existing installations. + + Chapter 3: RVS licensing and license management + Describes licensing options for using RVS, how to check license details and up- + date licenses. + + Chapter 4: RVS floating license configuration + Describes how to use RVS with a floating license, including how to install the RVS + License Server software and configure the server so clients can receive tokens + from it. + + Chapter 5: RVS License Manager + Describes how to use the RVS License Manager to check details for, manage + and update RVS licenses. + + Chapter 6: RVS files and folders + Describes the files and folders installed by RVS and where these are located on + Windows and Linux operating systems. + + Appendix A: Third-party licenses used by RVS + Describes where to find information on software components, libraries, and im- + ages released with RVS under third party licenses. + + +RVS Installation and Licensing Guide vWF20190404 5 +Notation About this guide + + +1.3 Notation + This document uses the following notation: + • References to other documents and to other chapters or sections in this doc- + ument are written in italics, for example Chapter 1: About this guide. When + reading an electronic copy of this document, you can click on a reference to + navigate to the location of the referenced element. + • Names of RVS applications are formatted in bold italics, for example RVS + Project Manager. + • References to areas or elements in user interfaces are formatted in italics, for + example the Report Navigator. + • Menus, menu choices and button labels are formatted in bold, for example + File » Print or OK. Where buttons have icons, these are shown before their + Label in in-line text, for example Save. + • Names of RVS tools are formatted in bold, for example rvsdriver. + • References to HTML links appear as underlined text, for example + www.rapitasystems.com. + • Folder and file names are formatted in a monospaced font. + • Command-line tools and their commands, annotations and examples are for- + matted in a monospaced font. These are either written in-line with text + or as separate text blocks. When written in-line with text, they are formatted + like the following: rvsdriver, default_instrument, rvs_instr.h. + When written as a separate text block, they are formatted like the examples + below: + rvsdriver --project rvs.rvsprj --all + + #pragma RVS instrument( "function_name", "FALSE" ) + + • When referencing Ada code, the term functions refers to both functions and + procedures. + +1.4 RVS documentation map + This document is part of the Rapita Verification Suite (RVS) document set, which + contains the following documents: + + RVS Installation and Licensing Guide + Describes how to install RVS tools, and licensing options for them. + + RVS Integration Guide + Describes how to integrate RVS tools into build and target environments. + + RVS User Guide + Describes how to set up and run RVS projects, analyze data and export verification + results. + + +6 RVS Installation and Licensing Guide vWF20190404 +About this guide RVS documentation map + + + RapiTest User Guide + Describes how to use RapiTest to manage test projects. + + Spreadsheet Test Format User Guide + Describes how to write tests for RapiTest in the Spreadsheet Test Format. + + RapiCover User Guide + Describes how to use RapiCover to measure code coverage and address cover- + age holes. + + RapiTime User Guide + Describes how to use RapiTime to measure timing metrics including worst-case + execution time, and how to use these metrics to identify the best optimization + candidates. + + RapiTask User Guide + Describes how to use RapiTask to measure system level task timing information, + visualize traces and gain insight into runtime behavior. + + RTBx 2xxx User Guide + Describes how to use the RTBx data logger. + + RVS Integration Library Implementation Guide + Describes how to implement RVS integration libraries. This document is for use by + readers with a thorough understanding of the implementation of RVS. + + RVS Files Reference Guide + Describes RVS-specific files including input, intermediate and output files. + + RVS Filters Guide + Describes RVS filters, which are used to convert raw trace data into a format that + RVS can analyze, and how to write them. + + RVS Command Line Tools Reference Guide + Describes the command-line tools used by RVS, including a list of available com- + mand options. + + RVS Annotations Reference Guide + Describes the annotations you can use to control instrumentation and analysis + with RVS. + + RVS Troubleshooting Guide + Describes the error and warning messages you may encounter when using RVS + tools, and how to address them. + + RVS Migration Guide + Describes how to migrate between using different versions of RVS. + + +RVS Installation and Licensing Guide vWF20190404 7 +Support About this guide + + +1.5 Support + For support issues, please contact Rapita Systems Ltd. by any of the following + means: + + Email + support@rapitasystems.com + + Telephone + +44 (0) 1904 413 945 + + Website + www.rapitasystems.com + + To register for support, visit www.rapitasystems.com/register. More than one user + can register per license. + + +8 RVS Installation and Licensing Guide vWF20190404 + Installing and maintaining +2 RVS + This chapter lists system requirements for RVS and describes how to install, main- + tain and uninstall the RVS software. + + Note + + While the RVS software is only supported for use on certain systems, RVS + can be used to analyze software run on almost any system. RVS can be + qualified for use on any supported system. + + +2.1 System requirements + RVS software should be installed on a PC that meets the following requirements: + • Processor: 2GHz Core 2 minimum, 3.5GHz i5 recommended. + • RAM: 3GB minimum, 8GB recommended. + • Display: 1280x1024 minimum, 1920x1080 recommended. + • Disk drive: At least 2GB of free disk space is required for the installation. More + space will be required to run RVS analysis. The amount of space required de- + pends on the complexity of the software being analyzed. An SSD is recom- + mended for best performance. + • A DVD-ROM drive or a means of downloading the installation files from the + Rapita Systems Ltd. website. + • If using a node-locked license: an available USB port to connect the license + key. + • If using a floating license: a network interface supporting TCP/IP to connect + to the license server. + +2.1.1 Supported operating systems + RVS is available in versions that support Microsoft Windows and GNU/Linux op- + erating systems. + + The following desktop versions of Windows are supported: + • Windows 10 (32-bit and 64-bit) + • Windows 8.1 (32-bit and 64-bit) + • Windows 8 (32-bit and 64-bit) + • Windows 7 (32-bit and 64-bit) + • Windows Vista (32-bit and 64-bit) - Deprecated + + +RVS Installation and Licensing Guide vWF20190404 9 +System requirements Installing and maintaining RVS + + + • Windows XP (32-bit only) - Deprecated + + The following server versions of Windows are supported: + • Windows Server 2016 + • Windows Server 2012 R2 + • Windows Server 2012 + • Windows Server 2008 R2 + • Windows Server 2008 - Deprecated + • Windows Server 2003 R2 - Deprecated + • Windows Server 2003 - Deprecated + + Note + + RVS may run with a reduced set of features when used on versions of Win- + dows that are deprecated. + + + Note + + 64-bit versions of RVS running on 64-bit versions of Windows do not sup- + port USB node locked licenses. If you have a USB node locked license you + must install the 32-bit version of RVS on 64-bit Windows. + + + Note + + If you want to use RVS to produce verification results through Jenkins, you + should install RVS for the same architecture as your Jenkins installation (on + Windows systems, this is usually 32-bit). + + The cli components of RVS are supported on any 32-bit or 64-bit Linux distribution + with glibc 2.5 or newer (e.g. CentOS/Redhat versions >= 5). + + The GUI components of RVS require GTK2 libraries to be installed via your + distribution's package manager and have been verified to work on the following + distributions. + • Ubuntu 18.04 (64-bit) + • Ubuntu 16.04 (64-bit) + • Ubuntu 14.04 (64-bit) + + Note + + If you are going to use RapiTask, we recommend that you install the latest + version of Mono from your system repository so you can use the RapiTask + Viewer to view results. + + +10 RVS Installation and Licensing Guide vWF20190404 +Installing and maintaining RVS Installing RVS + + + Note + + 32-bit compatibility and development libraries are required when RVS is in- + stalled on 64-bit versions of Linux in order to use the pre-wrapped version + of GNAT GPL for tutorials, examples and on-host integrations. You will need + to install these separately via your distribution's package manager. + + +2.2 Installing RVS + This section describes how to how install RVS on both Windows and Linux sys- + tems. + +2.2.1 Pre-installation checklist + Before installing RVS, you should check that: + • The system RVS will be installed on meets the system requirements listed in + Section 2.1: System requirements. + • You have the correct installer for RVS. This may be on a DVD or a downloaded + file. Registered users can download installers from the Rapita Systems Ltd. + website at http://www.rapitasystems.com/spd/downloads. + • You have administrative access to the system you are installing RVS on. + • If you are using a node-locked license, the USB license key is available. + • If you are using a network license, the RVS License Server IP address and + port number are available, and the RVS License Server is installed, running + and accessible. See Chapter 4: RVS floating license configuration for more + information on network licensing and the RVS License Server. + + +RVS Installation and Licensing Guide vWF20190404 11 +Installing RVS Installing and maintaining RVS + + +2.2.2 Installing RVS on Windows + + Note + + This section describes how to install RVS manually on a Windows PC. If you + want to install RVS silently using a command-line script (to install it on mul- + tiple machines at once, for example), follow Section 2.2.3: Installing RVS + silently on Windows instead. + + + To install RVS on Windows, follow these steps: + 1. Close all applications on your PC. + 2. Locate the RVS installer executable. If installing from a DVD, this is in the root + directory of the DVD-ROM. + 3. Run the installer executable by double-clicking on it. + + Note + + If the file was downloaded from the Internet, you may receive a Windows + Security dialog asking for confirmation before the installer can run. If this + happens, click Run to continue the installation process. + + + Note + + You may receive a User Account Control dialog asking you to confirm run- + ning the installer. If you do, click Yes to continue. + + + The installer unpacks files and displays a welcome screen. Click Next to + continue. + 4. The installer displays the RVS Software License Agreement. Please read the + terms of the license agreement carefully. To accept the license agreement, + select I accept the agreement, then click Next. + 5. By default, RVS is installed in the directory C:\RVS. You can + change this location if necessary. Confirm the installation directory by clicking + Next. + 6. The installer add shortcuts to the Windows Start menu that you can use to + run RVS applications. You can change the shortcut directory if necessary. + Confirm the shortcut directory by clicking Next. + 7. The installer asks which version of RVS you want to set as the default version. + This sets file associations and the RVS_PATH environment variable, which + is used to run RVS. + + When you first install RVS, you can choose to set the version you are installing + as the default, or not to set a default. + + +12 RVS Installation and Licensing Guide vWF20190404 +Installing and maintaining RVS Installing RVS + + + If you already have a default RVS version set, you can choose to overwrite + this or keep it as the default. After making a choice, click Next. + 8. The installer asks what type of license you will use to run RVS. Select an + appropriate option and click Next. For more information on RVS licenses, + see Chapter 3: RVS licensing and license management. + + If you select the Floating license type, you must provide details about your + license server. Enter these details and then click Next. To test connection to + the server, click Test connection. + + Note + + For details about your license server, consult your network administrator. + + + Important + + The RVS tools do not currently support proxy authentication, so this option + can only be used with a proxy server that does not require authentication. + + 9. This page lets you specify which version of RVS to install, and which optional + features to install along with the core RVS tools. RVS is supplied in two ver- + sions, optimized for Aerospace or Automotive applications. Select the ap- + propriate version using the radio buttons. + + You can use the check boxes to select which optional RVS components to + install. After making your selection, click Next to continue. + 10. For the Aerospace version, if you have a GNAT Pro license, you can choose + to install support for the GNAT Pro compiler (RVS supports GNAT Pro ver- + sions 7.2, 7.3, 7.4, 17, 18 and 19, with limited support for 6.1, 6.4 and 7.1). + Click Next to continue. + 11. The installer is now ready to install RVS. After reviewing the options you have + selected, click Install. + + The installer now installs RVS on your system. This may take a few minutes. + 12. If you selected the Node locked license type, the USB license key drivers + are installed, and a message confirms that they were installed successfully. + Click OK to continue. + + When the installation is complete, the installer displays a message indicating + that RVS has been installed successfully. Click Finish to exit the installer. + + +RVS Installation and Licensing Guide vWF20190404 13 +Installing RVS Installing and maintaining RVS + + + Note + + To use some RVS applications, the Microsoft .NET Framework 4.0 must + be installed on your system. If this is not already installed and your sys- + tem has an Internet connection, the framework installer runs. If your sys- + tem does not have an Internet connection you can install the frame- + work manually using the standalone installer, which is available at + http://www.microsoft.com/en-gb/download + /details.aspx?id=17718. + + +14 RVS Installation and Licensing Guide vWF20190404 +Installing and maintaining RVS Installing RVS + + +2.2.3 Installing RVS silently on Windows + + Note + + This section describes how to install RVS silently on multiple machines. If + you want to install RVS manually on a single PC, follow Section 2.2.2: In- + stalling RVS on Windows instead. + + You can configure RVS to install silently on Windows through command-line + scripts. The options and parameters for RVS silent installs on Windows are shown + in Table 2.1, and Example 2.1 shows an example silent install script. + + Table 2.1 Windows RVS silent install options + Option Description + /GNATPRO=[True|False] Specifies whether to install GNATPro + /LICENSE_TYPE=[node|floating|skip] Specifies the type of RVS license that will + be used for the install + /LICENSE_SERVER_ADDR=
Specifies the address of the license server + /LICENSE_SERVER_PORT= Specifies the port of the license server + /LICENSE_SERVER_KEY= Specifies a license group key, if used + /SET_AS_DEFAULT=[always| Specify whether to set this version as the + if_newer_version|if_only_version|never] default RVS version + /DIR="C:\path\to\rvs" Specifies the installation directory for RVS + /GROUP="RVS" Specifies the name of the Windows Start + menu folder + /MERGETASKS=[RVS_Auto|RVS_Aero] Specifies the type of RVS product to install + /SILENT Specifies silent install (installation progress + shown) + /VERYSILENT Specifies silent install (no installation + progress shown) + /NOICONS Specifies not to add a Windows Start + menu folder for RVS + + Example 2.1: Example Windows silent installation script + + ./setup-rvs.exe /DIR="C:\RVS" /MERGETASKS=RVS_Aero /GNATPRO=False + /SET_AS_DEFAULT=always /LICENSE_TYPE=floating + /LICENSE_SERVER_ADDR=licserv.domain.com /LICENSE_SERVER_PORT=1234 + /LICENSE_SERVER_KEY=myGroupKey-1234 /SILENT + + +RVS Installation and Licensing Guide vWF20190404 15 +Installing RVS Installing and maintaining RVS + + +2.2.4 Installing RVS on Linux + To install RVS on Linux, follow these steps: + 1. Close all applications on your PC. + 2. Open a terminal window and change to the directory containing the RVS + installer executable. + + If installing from DVD, the installation file needs to be copied to a writable + directory on the machine. The installation file is located in the root directory + of the DVD-ROM drive. + 3. Unpack the installer using the command + tar -xzf setup-rvs_.tgz + + 4. When the installer has been unpacked, change to the directory containing + the extracted files (setup-rvs_). + 5. As the root user, run the install.sh script. + ./install.sh + + + We recommend that you run the script as a root user, either using the sudo + command or by switching to the root user account using the su command. + 6. Press Enter to display the RVS license agreement. To accept the agreement, + press Y and then the Enter key. + 7. The installer suggests a location to install RVS tools. To accept the suggested + location, press Enter. To install the tools in a different location, type the path + to this location and press Enter to confirm. + 8. The installer suggests a location where links to the tool executables will be + created. To accept the default location, press Enter. To create links in a dif- + ferent location, type the path to this location and press Enter to confirm. + + Note + + If you choose a location for links that is not included on the system path, + you will need to add this location to the PATH environment variable before + you can run RVS tools. + + 9. The installer suggests a location where links to the tool libraries will be cre- + ated. To accept the default location, press Enter. To create links in a different + location, type the path to this location and press Enter to confirm. + + Note + + If you choose a location for links that is not included on the system library + path, you will need to modify the LD_LIBRARY_PATH environment vari- + able to include this location before you can run RVS tools. + + +16 RVS Installation and Licensing Guide vWF20190404 +Installing and maintaining RVS Installing RVS + + + 10. The installer asks what type of license you will use to run RVS. Select Node + locked, Floating, or Already installed by typing N, F or A and then press Enter. + + If you select the Floating license type, you must provide details about your + license server. Enter the IP address of the license server, the port number + and a group key if you are using one, pressing Enter after each. The installer + checks the details by trying to connect to the license server, which may take + a few minutes. + + For more information on RVS license types and options, see Chapter 3: RVS + licensing and license management. + + Note + + If the check fails, you can re-enter the license server details to check again + or ignore the error and proceed with the installation. You can change license + server details after finishing the installation, see Section 4.7: Configuring a + client machine to use a license server. + + 11. RVS is supplied in two versions, optimized for Aerospace (Aero) or Automo- + tive (Auto) applications. The installer asks which version you want to install. + Select Aero by typing 1 or Auto by typing 2, and then press Enter. + 12. If you selected Aero and have a GNAT Pro license, you can choose to install + support for the GNAT Pro compiler. + 13. The installer is now ready to install RVS. After reviewing the options you have + selected, type Y and press Enter to confirm the installation. + + The installer now installs RVS on your system. This may take a few minutes. + + If any of the details are incorrect, type N to exit the installation, and re-run the + install.sh script again with the correct details. + 14. If a node locked license is used, you must install drivers for the USB license + key. See Section 3.4.2: Installing USB license key drivers to learn how to do + this. + + +RVS Installation and Licensing Guide vWF20190404 17 +Checking RVS installations Installing and maintaining RVS + + +2.3 Checking RVS installations + This section describes how to check that RVS has been correctly installed and a + valid license key is available. + + To do this, use the Version and License Info tool, rvsinfo. To access this, open the + RVS License Manager. On Windows systems, access this from the Start menu + (Start » Programs » RVS » RVS License Manager). On Linux systems, open it + by executing licensemanager.exe from the RVS\bin directory. After the + application starts, open the Version and License Info page. + + When you do this, the tool scans installed RVS components and information about + your system and license server. This may take a while. After the scan, your results + are displayed. + + You can also run the command rvsinfo from a terminal to check your installation. + +2.4 Uninstalling RVS + This section describes how to uninstall RVS on both Windows and Linux operating + systems. + +2.4.1 Uninstalling RVS on Windows + On Windows, uninstall RVS from the Windows Control Panel. + +2.4.2 Uninstalling RVS on Linux + On Linux, uninstall RVS by doing the following: + 1. Open a terminal and change to the directory containing the version of RVS + you want to uninstall. + 2. As the root user, run the ./uninstall.sh script. + + Depending on your distribution, you may be able to use the sudo command + to run as root, or you may need to switch to the root user account using su + first. + 3. A message appears asking you to confirm the uninstallation. RVS will be + uninstalled by removing application menu item(s), file association(s) and + links created during installation. To confirm, press Y and then the Enter key. + 4. Once the uninstallation script has finished, remove the directory where RVS + was installed. + + If another version of RVS is still installed on your system, you may need to repair + it. To repair an installation, follow these steps: + 1. Change to the directory where the remaining version of RVS is installed. + 2. As the root user, run ./install.sh to re-run the installer. Install RVS to + the location it is currently installed in to repair the installation. + + +18 RVS Installation and Licensing Guide vWF20190404 + RVS licensing and license +3 management + This chapter describes licensing options for using RVS, how to check license de- + tails and update licenses. + +3.1 RVS license options + You can use RVS through two different types of license: + • A floating license makes it easy for multiple people within an organization to + use RVS in a shared environment such as a shared server, thin client system + or virtual machine. + • A node-locked license lets a single user run RVS at once on a computer to + which a USB license key is plugged in. + + Trial versions of RVS work using a license code that lets you use RVS for a fixed + period of time (normally five weeks from when the trial was requested). + +3.1.1 Floating license + A floating license lets multiple users use RVS on multiple computers by running + the RVS License Server on a networked machine accessible by all computers that + have RVS installed. Floating licenses can be used anywhere within a country or + geographical region agreed prior to the license being issued. + + When a user runs RVS, a token is requested from the license server. When they + stop using RVS, the token is returned to the server. If the maximum number of + tokens has been issued, token requests are denied by the server. + + The RVS License Server verifies the license using either a USB license key plugged + into a USB port on the machine hosting the license server or a file license locked + to the server's host ID. + + USB license keys configured for use with a floating license have a tag with a Key + ID number starting with the letter S attached, see Figure 3.1. + + Key Id + Sxxxxxx + + support @rapit asyst em s.com + + Figure 3.1: Floating key label + + +RVS Installation and Licensing Guide vWF20190404 19 +License duration, expiry and renewal RVS licensing and license management + + + For more information on using RVS with a floating license, see Chapter 4: RVS + floating license configuration. + +3.1.2 Node-locked license + A node-locked license lets a single user use RVS on a computer by plugging a + USB license key into it. This key is used to verify that RVS is properly licensed. If + the key is not found, RVS will not run. + + Important + + A node-locked license entitles you to install RVS on any number of ma- + chines, but does not allow you to install RVS on shared user machines, thin + clients, systems that use remote desktop, or servers, and does not allow + you to use RVS in continuous integration environments. + + USB license keys configured for use with node-locked licenses have a tag with a + Key ID number starting with the letter N attached, see Figure 3.2. + + Key Id + Nxxxxxx + + support @rapit asyst em s.com + + Figure 3.2: Node-locked key label + + Important + + To use a node-locked license, USB license key drivers must be installed on + the machine running RVS. You need administrative access to the system to + install these drivers. If necessary, please consult your system administrator. + + + Important + + 64-bit versions of RVS running on 64-bit versions of Windows do not sup- + port node locked licenses. If you have a node locked license you must in- + stall the 32-bit version of RVS on 64-bit Windows. + + +3.2 License duration, expiry and renewal + RVS products are licensed on either an annual or perpetual basis. Annual licenses + include support and maintenance for the duration of the license period. Perpetual + licenses include support and maintenance for the first year. After this, support and + maintenance must be purchased separately. + + +20 RVS Installation and Licensing Guide vWF20190404 +RVS licensing and license management The RVS License Manager + + + Annual RVS licenses expire after one year from the purchase date unless a different + date was agreed when the license was purchased. To ensure uninterrupted access + to RVS tools, licenses should be renewed before they expire. + + Perpetual licenses never expire, however upgrades and technical support are only + available if a support agreement is in place. + + For details of how to check the RVS license details, see Check installation and + license details. For queries about license durations or expiry dates, contact + support@rapitasystems.com. + +3.3 The RVS License Manager + The RVS License Manager lets you check details about your RVS licenses, man- + age which licenses are used, install software for USB license keys and update + your license. For more information on using this application, see Chapter 5: RVS + License Manager. + +3.4 USB license keys + Most RVS licenses use a USB license key to verify that a computer (node-locked + licenses) or license server (floating licenses) has one or more valid RVS licenses. + This section describes USB license keys and how to install drivers for them and + update them. + +3.4.1 Power requirements + The clock in the USB license key is powered by an internal battery. The battery + lifetime is at least four years when the USB license key is not connected to a com- + puter. The typical lifetime is longer, particularly in situations where the key spends + a significant proportion of time connected to a powered USB port (such as when + used with a license server). + + When the USB license key battery is depleted, the RVS tools will be unable to + locate a valid license even when the key is connected and the red light is on. In + this case, contact us for assistance at support@rapitasystems.com. + +3.4.2 Installing USB license key drivers + This section describes how to install USB license key drivers on both Windows + and Linux systems. + + On Windows systems, drivers are installed during the installation process if you + select the Node-locked license type during installation. If they were not, use the + RVS License Manager to install them by following the instructions in Install USB + license key drivers. + + On Linux systems, you have to install drivers manually. There are three versions + of the driver installation package, each of which suits a different style of package + management. These are: + + +RVS Installation and Licensing Guide vWF20190404 21 +USB license keys RVS licensing and license management + + + • A .rpm package suitable for RedHat, SuSE and other distributions that use + the RPM package manager. + • A .deb package suitable for Debian, Ubuntu and other distributions that use + the Debian package management system. + • A directory containing the files and installation scripts for manual installation + on systems which do not support either RPM or Debian-style packages. + + To install a driver, follow these steps: + 1. Open a terminal and change to the directory where the RVS tools are in- + stalled. + 2. Change to the drivers directory. + 3. Change to the directory containing the appropriate driver package for your + distribution. + 4. Invoke the appropriate package manager or script to install the driver pack- + age. + + Important + + Root access is needed to install the driver package. + + a. For distributions that support RPM packages, the command to install + a package is normally + rpm -i .rpm + + b. For distributions that support Debian packages, the command to install + a package is normally + dpkg -i .deb + + c. For distributions that do not support RPM or Debian packages, run the + dinst script to install the driver components + +3.4.3 Updating USB license keys + The USB license key stores the license expiry date and which RVS features are + licensed. When you renew a license or purchase new features, you must update + the key. + + To update USB license keys, you must do the following: + 1. Generate a key information file (.c2v file). + 2. Send this file to Rapita Systems so we can produce a file (.v2c file) to update + the key. + 3. Use the .v2c file to update the key. + + To do this, use the RVS License Manager as described in Update licenses. + + +22 RVS Installation and Licensing Guide vWF20190404 + RVS floating license +4 configuration + This chapter describes how to use RVS with a floating license. It includes infor- + mation on installing the RVS License Server and explains how to configure client + machines so they can obtain license tokens from the server. + +4.1 RVS License Server requirements + This section describes requirements for the version of the RVS License Server used + and system requirements for the machine the license server software is installed + on. + +4.1.1 Version requirements + Updates to the RVS License Server are released at the same time as releases of + RVS and share the same version numbering scheme. + + From time to time, Rapita Systems Ltd. may make changes to the licensing mech- + anism, for example to add new tool features. Because of this, you should ensure + that the installed version of the RVS License Server is the same as, or newer than, + the installed version of RVS. When you upgrade RVS to a new version, you should + also upgrade the RVS License Server. + + The RVS License Server is backwards-compatible with all previous releases of + RVS, so newer versions of the license server can serve license tokens to older + RVS versions. + +4.1.2 System requirements + The RVS License Server has the same system requirements as RVS, see Sec- + tion 2.1 for details. It also has the following requirements: + • For USB license keys: a USB port must be available to connect the license key, + unless a file license is used. The license key contains information about the + licensing period, licensed products and the number of available licenses. + • A wired Ethernet interface that supports TCP/IP must be available to allow + clients to connect to the license server. + + +RVS Installation and Licensing Guide vWF20190404 23 +RVS License Server requirements RVS floating license configuration + + + Important + + Administrative access is needed to install the RVS License Server. During + the installation process, changes must be made to the system configuration + to run the license server as a daemon (Linux) or system service (Windows). + If a USB license key is being used, administrative access is needed to in- + stall drivers for it. Please consult your system administrator if you need to + obtain administrative access to the system. + + + Important + + If your network is protected by a firewall, you may need to alter the firewall + configuration to allow computers running RVS to connect to the license + server. If this is needed, please consult your network administrator. + + +24 RVS Installation and Licensing Guide vWF20190404 +RVS floating license configuration Installing the RVS License Server + + +4.2 Installing the RVS License Server + This section describes how to install the RVS License Server on computers running + Windows or Linux operating systems. + + Important + + For USB license keys: To run the RVS License Server via Remote Desktop, + you must install the server as a Windows system service. This is because + access to USB license keys is not available from a Remote Desktop ses- + sion. + + +4.2.1 Pre-installation checklist + Before installing the RVS License Server, you should check that: + • The system the RVS License Server will be installed on meets the system re- + quirements described in Section 4.1.2: System requirements. + • You have the correct installer for the RVS license server. The in- + staller may be a DVD or a downloaded file. Registered users + can download installers from the Rapita Systems Ltd. website at + http://www.rapitasystems.com/spd/downloads. We recom- + mend that you install the latest version of the RVS License Server. + • You have administrative access to the system you are installing the RVS Li- + cense Server on. + • For USB license keys: you have physical access to the machine so you can + connect the USB license key when necessary. + +4.2.2 Installing the RVS License Server on Windows + To install the RVS License Server on Windows, follow these steps: + 1. Close all applications on your server. + 2. Locate the RVS License Server installer executable. If installing from a DVD, + this is in the root directory of the DVD-ROM. + 3. Run the installer executable by double-clicking on it. The installer unpacks + files and displays a welcome screen. Click Next to continue. + + Note + + If the installer was downloaded from the Internet, you may receive a Win- + dows Security dialog asking for confirmation before you can run it. If this + happens, click Run to continue. + + +RVS Installation and Licensing Guide vWF20190404 25 +Installing the RVS License Server RVS floating license configuration + + + Note + + You may receive a User Account Control dialog asking you to confirm run- + ning the installer. If you do, click Yes to continue. + + 4. The installer displays the RVS Software License Agreement. Please read the + terms of the license agreement carefully. + + To accept the license agreement, select I accept the agreement, then click + Next. + 5. By default, the RVS License Server will be installed in the directory + C:\RVS_licserv. You can change this location if necessary. Confirm the + installation directory by clicking Next. + 6. If the RVS License Server has already been installed on the system, you are + prompted to uninstall the previous version. You must do this before a new + version can be installed. + 7. The RVS License Server can be installed in the following configurations: + + Windows system service or manual startup. A system service runs in the back- + ground on system startup. We recommend that you choose Windows system + service unless you need to manually control the RVS License Server. + + File License or USB License Key. You should choose the type of license that + you have been sent by Rapita Systems Ltd. If you have not yet been issued + a file license, but will be in the future, select File License. + + Select the configuration to use for your server, then click Next. + 8. You are now asked to select the Start menu location for the RVS License + Server. Click Next to continue. + 9. The installer is now ready to install the RVS License Server. After reviewing + the options you have selected, click Install. + + The installer now installs the RVS License Server on your system. This may + take a few minutes. + + If you selected to install the RVS License Server as a Windows system ser- + vice, this starts during the installation. + + For USB key licenses: USB license key drivers are installed during the instal- + lation process. A message confirms that they have been installed success- + fully. Click OK to continue. + 10. When the installation is complete, the installer displays a message indicating + that the RVS License Server has been installed successfully. Leave the Open + RVS License Server Control Panel box ticked, and click Finish to exit the + installer. + + +26 RVS Installation and Licensing Guide vWF20190404 +RVS floating license configuration Configuring the RVS License Server + + + 11. You should now check that the server has started up correctly (see Sec- + tion 4.4.3). You may need to perform more configuration steps if you are us- + ing a USB license key (see Section 4.3.1) or a file license (see Section 4.3.2). + +4.2.3 Installing the RVS License Server on Linux + To install the RVS License Server on Linux, follow these steps: + 1. Close all applications on your server. + 2. Open a terminal window, and change to the directory containing the RVS + License Server installer executable. + + If installing from a DVD, copy the installer executable to a writable directory + on the machine. This executable is in the root directory of the DVD-ROM. + 3. Unpack the license server software using the command + tar -xzf setup-licenseserver_.tgz + + 4. Change to the directory containing the extracted files + (setup-licenseserver_). + 5. For USB key licenses: You must install drivers for the USB license key before + you can run the license server. Follow Section 3.4.2 to install these drivers. + 6. The RVS License Server executable licserv can be executed directly from + the bin directory. + + When run using the command licserv --start, the RVS License Server + runs as a service and does not daemonize (it remains attached to the current + terminal session and will close when you close the terminal). To run RVS + License Server as a daemon, you can use a command such as + nohup licserv --start --log /var/log/licserv.log & + + 7. It may be helpful to add entries to your system startup scripts to start the + license server when your system starts. Please consult your distribution doc- + umentation or system administrator for information on how to edit startup + scripts in your distribution. + 8. You should now check that the server has started correctly (see Sec- + tion 4.4.3). You may need to perform additional configuration steps if you + are using a USB license key (see Section 4.3.1) or a file license (see Sec- + tion 4.3.2). + +4.3 Configuring the RVS License Server + After installing the RVS License Server, you may need to configure or install one or + more licenses for it. You can do this using the RVS License Server Control Panel + (on Windows) or the licserv command line utility (on Windows and Linux). + + +RVS Installation and Licensing Guide vWF20190404 27 +Configuring the RVS License Server RVS floating license configuration + + + Note + + The RVS License Server must usually be in either the running or suspended + state for you to change its configuration. Section 4.5 describes the states + the RVS License Server may be in. + + +4.3.1 Configuring a USB license key + If you are using a USB license key, you may need to change the TCP/IP port the + RVS License Server uses to serve license tokens and run its web interface. By + default, it uses port 6849. You can change this when the RVS License Server is in + either the running or suspended state (see Section 4.5) and the USB license key + is plugged into your server by doing the following: + + Using the RVS License Server Control Panel (Windows): + 1. Open the RVS License Server Control Panel from the Windows Start menu + (Start » RVS License Server » RVS License Server Control Panel). + 2. Click Set License Server Port and enter a valid TCP/IP port number in the + range 1024-65534. + + Using the command line (Linux or Windows): + • Call licserv as follows + licserv --usb-license-key-port + where is a valid TCP/IP port in the range 1024-65534. + + After setting the port number, check that the server has started up correctly (see + Section 4.4.3: Checking the RVS License Server status). + + Important + + The port you select must not be used by any other application running on + the same machine as the RVS License Server. + + + Important + + If any parts of your network are protected by a firewall, you may need to al- + ter the firewall configuration so computers running RVS can connect to the + license server. If you need to do this, please consult your network adminis- + trator. + + + Note + + On Windows, you can only change the USB license key port configuration + via Remote Desktop if the RVS License Server is running as a Windows sys- + tem service. This is because access to USB license keys is not available + within a Remote Desktop session. + + +28 RVS Installation and Licensing Guide vWF20190404 +RVS floating license configuration Using the RVS License Server + + +4.3.2 Installing and configuring file licenses + If you use a file license to run the RVS License Server, you must install the license. + File licenses are issued by Rapita Systems Ltd. and are locked to the host ID of + your server. + + To request a file license, first obtain the host ID of your server by clicking Get Host + ID in the RVS License Server Control Panel (Windows) or providing the + licserv get_hostid command in the command line (Windows or Linux). + Send this to us at support@rapitasystems.com with your license file request. + + When you receive a license file, copy it to your desktop or the home directory on + the server. When the RVS License Server is in either the running or suspended + state (see Section 4.5), you can install the file as follows: + + Using the RVS License Server Control Panel (Windows): + 1. Open the RVS License Server Control Panel from the Windows Start menu + (Start » RVS License Server » RVS License Server Control Panel). + 2. Click Install License File and choose a license file using the dialog box. + + Using the command line (Linux or Windows): + • Call licserv as follows + licserv --install-file + where is the path to the license file. + + After installing the license file, check that the server has started up correctly (see + Section 4.4.3). + + You may also need to change the port number for the license file. The proce- + dure is the same as that described in Section 4.3.1, but using the argument + --file-port instead of --usb-license-key-port on the command line. + +4.4 Using the RVS License Server + This section describes the means by which you can use the RVS License Server on + Windows and Linux systems, how to check the status of the RVS License Server + and scan license usage. + +4.4.1 RVS License Server Control Panel + Using the RVS License Server Control Panel is the easiest way to manage the + RVS License Server. This application is only available on Windows systems. You + can use it to do the following: + 1. Manually start and stop the RVS License Server as a Windows system ser- + vice or normal user-mode process (depending on the configuration chosen + during installation). + 2. Force the RVS License Server to enter the suspended or initializing states + by clicking the Suspend or Resume buttons. For more information on the + + +RVS Installation and Licensing Guide vWF20190404 29 +Using the RVS License Server RVS floating license configuration + + + states the RVS License Server can be in, see Section 4.5: Troubleshooting + RVS License Server problems. + 3. Set the port number used by a USB license key or license file (see Sec- + tion 4.3.1: Configuring a USB license key). + 4. Install a license file (see Section 4.3.2: Installing and configuring file licenses). + 5. View detailed status of the RVS License Server by opening the server's web + page or creating a Version and License Information (rvsinfo) report. + 6. Obtain the host ID of the server. + + To open the RVS License Server Control Panel, use the Windows Start menu + (Start » RVS License Server » RVS License Server Control Panel). + +4.4.2 RVS License Server command line utility + On Windows and Linux, you can use the licserv command line utility to control + or query the RVS License Server. The operations you can carry out using licserv + are the same as those described in Section 4.4.1: RVS License Server Control + Panel. For a summary of the command line options, run licserv --help or + see Chapter 10 in the RVS Command Line Tools Reference Guide. + +4.4.3 Checking the RVS License Server status + After installing or updating the RVS License Server or any file or USB license keys + you use, you should check that the server is working correctly. We recommend + that you do this by taking the following steps: + 1. Windows users + Open the RVS License Server Control Panel (from the Windows Start + menu) and look at the state of the server, which is displayed at the top of the + control panel. If the RVS License Server is working correctly, this should be + either running or initializing. If it is not, see Section 4.5: Troubleshooting RVS + License Server problems. + 2. Linux users + Call licserv using the command + licserv --status + to print the current state of the server. If the RVS License Server has been + started, this should be either running or initializing. If it is not, see Section 4.5: + Troubleshooting RVS License Server problems. + 3. As an additional check, the RVS License Server runs an embedded web serv- + er that provides a status page that can be checked from a web browser on + other PCs. To access this, visit the URL http://: + where a.b.c.d is the IP address of the server and port is its port. If you + cannot open this page from other PCs, see Section 4.5: Troubleshooting RVS + License Server problems. + 4. You can view information on the features provided by the license by running + the Version and License Information (rvsinfo) tool to generate a report. + + +30 RVS Installation and Licensing Guide vWF20190404 +RVS floating license configuration Troubleshooting RVS License Server problems + + + Windows users can open this report by clicking Run rvsinfo tool in the RVS + License Server Control Panel. Linux users can do so by calling licserv with + the licserv --info command. + +4.4.4 Scanning license usage + The RVS License Server status may be queried from a script or program by run- + ning the rvsinfo tool with either the -a or -i options, see Chapter 13 in the RVS + Command Line Tools Reference Guide. When you use these options, rvsinfo pro- + duces a report showing a list of active users and available groups. License usage + reports are written in a format that can be parsed easily by third-party tools. + + If multiple license servers are configured, license usage information is combined + from all of them. + +4.5 Troubleshooting RVS License Server problems + The RVS License Server is always in one of four states. These are initializing, sus- + pended, running and stopped. + + When the RVS License Server starts, it enters the initializing state. Initialization ei- + ther succeeds or fails and produces an error. If it succeeds, the RVS License Serv- + er enters the running state and starts serving license tokens. If an error prevents + startup, RVS License Server enters the suspended state and waits for the error to + be resolved by the user. + + If RVS License Server is suspended, you can view a summary of the error in + the RVS License Server Control Panel or by calling licserv with the lic- + serv --status command. + + Errors may be due to a configuration problem, for example that the license file is + not installed or the TCP/IP port is not available. If this is the case, follow Section 4.3: + Configuring the RVS License Server to learn how to reconfigure the RVS License + Server. + + Sometimes an error may require more detailed debugging. In this case, you can + find further details by opening a debug log file. Windows users can open the log + file folder by clicking Open Log Folder in the RVS License Server Control Panel. + Linux users should use the --log option with licserv --start to write a + debug log. For more information on the log files produced by the RVS License + Server, see Section 4.6: License server log files. + +4.6 License server log files + The RVS License Server can write two types of log file. The debug log records + events affecting the license server, while the audit log records license usage infor- + mation. + + On Windows systems, you can open the folder containing log files by click- + ing Open Log Folder in the RVS License Server Control Panel. When the + + +RVS Installation and Licensing Guide vWF20190404 31 +License server log files RVS floating license configuration + + + license server is configured to run as a service, log information is written to + the RVSLicenseServer folder in the Windows LogFiles location (normally + C:\Windows\System32\LogFiles). When configured for manual startup, + log information is written to the log folder in the install location (the default in- + stall location is C:\RVS_licserv). In both cases, the debug log is written to + log.txt and the audit log is written to audit.txt. + + On Linux systems, you must specify locations for the RVS License Server to store + log files. If you do not, no log files will be generated. To do this, use the --log + and --audit-log options of licserv. You can also use this method on Windows + systems. + + You can specify a maximum size for both types of log file using the --rotate + option. This option lets you specify a maximum size for the files in megabytes. + When this size is reached for a file, the existing file is no longer written to and is + renamed to add a numerical suffix, such as log.txt.1. A new file is then creat- + ed with the original name. Numerical suffixes are chosen as the smallest positive + integer that does not conflict with existing files. + + When the license server restarts, new log messages are appended to existing log + files. If, for any reason, the license server cannot write to or rename a log file, it + will stop writing to that file. However, it will continue to operate normally in all other + respects. + +4.6.1 Debug log file + The debug log file records event affecting the license server. It records messages + such as license expiration, server shut down, disconnection of USB license keys + and connection errors. This file is useful for troubleshooting problems with the li- + cense server as it records information that may otherwise be hidden by the mech- + anisms for running services (on Windows) or background processes (on Linux). + +4.6.2 Audit log file + The audit log records license usage information. It has a fixed text format that can + be parsed easily by third-party tools. + + Example 4.1: License server audit log + + 14:17:12 (rapita) OUT: "GROUP1" user1@12.34.5.6 + 14:17:20 (rapita) IN: "GROUP1" user1@12.34.5.6 + 14:18:51 (rapita) OUT: "GROUP2" user2@12.34.5.7 + 14:18:53 (rapita) DENIED: "GROUP2" user3@12.34.5.8 (Licensed number + of users already reached.) + 14:18:59 (rapita) IN: "GROUP2" user2@12.34.5.7 + 14:19:09 (rapita) UNSUPPORTED: "RVS" user4@12.34.5.9 + + + A typical audit log is shown in Example 4.1. Each line begins with a timestamp + (given in local time) followed by (rapita) and a record type, which is one of + the following: + + +32 RVS Installation and Licensing Guide vWF20190404 + Configuring a client machine to use a license +RVS floating license configuration + server + + • OUT: a license token has been granted to a user + • IN: a license token has been returned to the server by a user + • DENIED: a license token was not granted to a user because all tokens of that + type are already in use + • UNSUPPORTED: a license token was not granted to a user because that user + did not provide a valid group key + + The next item is the group key name, contained within quotation marks. In the + example above, the group keys are GROUP1 and GROUP2. These correspond to + different pools of license tokens with different feature sets. + + The feature name is followed by the user's username and IP address, e.g. + user1@12.34.5.6. + + The final item on the each line is not always present. This is a comment, in paren- + theses, that gives more information about the access when this is available. + +4.7 Configuring a client machine to use a license + server + You can set the license server a client uses both during the RVS installation process + and after. For information on installing RVS, see Chapter 2: Installing and maintain- + ing RVS. + + The RVS License Manager lets you see and configure license server settings + used by clients of the RVS License Server. For information on how to use the RVS + License Manager to configure a client machine to use the license server, see + Chapter 5: RVS License Manager. + +4.7.1 The RVS license file + License server settings are stored in an RVS license file, rvsconfig.ini. + + In some cases, you may need to locate this file. For example, if your license set- + tings are controlled by a license file installed by your system administrator and you + do not have privileges to edit this file, you may want to copy the file so that you + can edit license settings. + + The easiest way to find the location of the RVS license file is by opening the Ver- + sion and License Info page of the RVS License Manager, see Check installation + and license details. This opens a HTML page that displays the location of all RVS + license files on the system under the heading "License Information", and indicates + which one is active. + + If more than one license file is present on the system, the one used to control + license settings is determined by the following order of precedence, based on the + location of the file: + + +RVS Installation and Licensing Guide vWF20190404 33 +Configuring a client machine to use a license + RVS floating license configuration +server + + + Windows + 1. The path stored in the environment variable %RAPITA_CONFIG_PATH% + 2. The current directory + 3. The user directory (%USERPROFILE%) + 4. The rapita directory within the user application data directory + (%APPDATA%\rapita) + 5. The directory within %PATH% containing the RVS tool currently being execut- + ed + 6. The bin directory where the RVS tools were installed, according to the Win- + dows registry path (HKCU\SOFTWARE\Rapita Systems\RVS\Path) + 7. The rapita directory within the common application data directory + (%ALLUSERSPROFILE%\Application Data\rapita) + 8. The common application data directory (%ALLUSERSPROFILE%) + + Linux + 1. The path stored in the environment variable $RAPITA_CONFIG_PATH + 2. The current directory + 3. The user directory ($HOME) + 4. The .rapita directory within the user application data directory + ($HOME/.rapita) + 5. The directory within $PATH containing the RVS tool currently being executed + 6. The /etc/rapita/ directory + + If you copy an existing rvsconfig.ini file to a location higher in the order of + precedence on your local file system, the new file will be used to control license + server settings the next time you start the RVS License Manager. + +4.7.2 Installing USB license key drivers + To use RVS with a USB license key, you need to install drivers for it. + + On Windows systems, drivers are installed during the installation process if you + select the Node locked license type during installation. If they were not, use the + RVS License Manager to install them by following the instructions in Install USB + license key drivers. + + On Linux systems, you have to install drivers manually. To learn how to do so, + follow the instructions given in Section 3.4.2: Installing USB license key drivers + +4.7.3 Updating floating licenses + If you need to update your RVS license, the USB license key or file license you are + using must be updated. If you are using a file license, we will send you an updated + + +34 RVS Installation and Licensing Guide vWF20190404 +RVS floating license configuration Uninstalling the RVS License Server + + + version of the file license. To use this updated version, simply replace your existing + file license with the new one. + + If you are using a USB license key, this must be updated. To learn how to do this, + see For more information on the overall process of updating USB license keys, + see Section 3.4.3: Updating USB license keys. + +4.7.4 Accessing the license server via a proxy server + In some environments, you may need to access the license server through a proxy + server. You can configure RVS tools to use a HTTP proxy for the license server + connection during installation, see Chapter 2. + + Note + + Consult your network administrator for the IP address and port details of + your proxy server. + + + Important + + RVS tools do not currently support proxy authentication, so this option can + only be used with a proxy server that does not require authentication. + + +4.7.5 Group keys + RVS licenses can be assigned to groups of users. Using this mechanism, licenses + can be associated with particular groups within an organization. For example, one + group may need full RVS licenses while another only requires licenses for Rapi- + Cover. License groups are set when license keys are created by Rapita Systems + Ltd.. + + + Note + + In most cases, group keys are not needed. + + If an incorrect group key is specified, the Version and + License Information tool will report an error, such as: + No license for key GROUP3 found on this server. + + Contact your license server administrator or support@rapitasystems.com + for a list of group keys associated with your license. + + +4.8 Uninstalling the RVS License Server + On Windows, uninstall the RVS License Server from the Windows Control Panel. + +RVS Installation and Licensing Guide vWF20190404 35 +Uninstalling the RVS License Server RVS floating license configuration + + + On Linux, remove any references to the RVS License Server executable licserv + from the system startup and shutdown scripts, stop the license server and remove + the executable files from the system. + + +36 RVS Installation and Licensing Guide vWF20190404 +5 RVS License Manager + The RVS License Manager lets you check details about your RVS licenses, man- + age which licenses are used, install software for USB license keys and update + your license. This chapter describes how to use the RVS License Manager to do + the following: + • Add licenses + • Check installation and license details + • Manage the license servers used with floating licenses + • Install USB license key drivers + • Update licenses + + To open the RVS License Manager on Windows systems, use the Start menu + (Start » RVS » RVS License Manager). + + To do so on Linux systems, run licensemanager in the RVS\bin directory. + +5.1 Adding a license + If you did not configure a license during your installation of RVS, the RVS License + Manager opens on the Welcome page, see Figure 5.1. You can use this page to + get started running RVS with a node locked or floating license. + + + Figure 5.1: Welcome page + + +RVS Installation and Licensing Guide vWF20190404 37 +Checking installation and license details RVS License Manager + + + To set the client up to use a floating license served by an RVS License Server, click + Add Server. Configure the server and click Save to save your changes. + + The client now attempts to connect to the RVS License Server. For more informa- + tion on the RVS License Server, see Chapter 4: RVS floating license configuration + + If you are using a node locked license, you must have drivers for the USB license + key installed on your system so the license can be used: + • If you are running RVS on Windows and did not install these drivers during + RVS installation, click Install USB license key driver and follow the on-screen + instructions to install them. + • If you are running RVS on Linux, you must install them manually. See Sec- + tion 3.4.2: Installing USB license key drivers to learn how to do this. + + If you already have a license configured, the Welcome page is not shown. You can + add new licenses from the License servers or File license pages. + +5.2 Checking installation and license details + To check installation and license details from the RVS License Manager, open the + Version and License Info page. When you open this page for the first time, it scans + your system for installed RVS components and information about your system and + license server. This may take a while. After the scan, your results are displayed. + +5.3 Managing license servers used by a client + If you are using an RVS License Server to distribute RVS licenses across a network, + you can view details for the license servers configured for your system as well as + add, edit or remove servers and group keys. + + To do so, open the License servers page. This displays a list of active license + servers along with their group keys. + + Clients request a license from the top entry in the list, and if this fails request a + license from the next entry in the list until a license has been served or all entries + have been tried. + +5.4 Installing USB license key drivers + If you are using a USB license key license with RVS, you need to install drivers + for it. These can be installed during the RVS installation process. If they were not, + you may need to install them separately. You need administrative access to install + USB license key drivers. + + To install USB license key drivers from the RVS License Manager Welcome page, + click Install USB license key drivers (see Add licenses). Follow the on-screen + instructions to install the drivers. + + +38 RVS Installation and Licensing Guide vWF20190404 +RVS License Manager Updating USB license keys + + + The Welcome page does not show if you already have a license on your system. + If this is the case, open the USB License page, which shows details about your + USB license. Click Install drivers and follow the on-screen instructions. + + Note + + You cannot install drivers for Linux systems in this way. To learn how to in- + stall USB license key drivers for Linux systems, see Section 3.4.2: Installing + USB license key drivers. + + +5.5 Updating USB license keys + You can use the RVS License Manager to update USB license keys to extend the + duration of your license or add new RVS features to it. + + Note + + The update process requires the RVS license update tool, which is only + available for Windows operating systems. If you normally run RVS on Lin- + ux and require a standalone version of this tool to update your USB license + key, contact us at support@rapitasystems.com. + + + The update process involves three stages, during which you must: + 1. Generate a key information file (.c2v file). + 2. Send this file to Rapita Systems so we can produce a file (.v2c file) to update + the key. + 3. Use the .v2c file to update the key. + + To begin the update process, open the USB License page of the RVS License + Manager while the USB license key you want to update is plugged into the system + you are using. This page shows information about the license stored on the USB + license key including its expiration date and features available using the key. + + Click Update key to open the RVS license update tool. You may receive a User + Account Control dialog asking you to confirm running it. If you do, click Yes to + continue. + + To generate the key information file, click Collect information, use the file browser + to select a location and filename and Save the file. + + Note + + If you are updating a license server key, you must suspend the RVS License + Server before collecting USB license key information, as described in Sec- + tion 4.4.1: RVS License Server Control Panel. + + +RVS Installation and Licensing Guide vWF20190404 39 +Updating USB license keys RVS License Manager + + + Next, email the key information file to support@rapitasystems.com, making sure + to include the Key ID (see Figure 3.2: Node-locked key label) in the email. We will + process the license update, generate a license update file to update the key and + send this to you. + + When you have received a license update file (v2c file), do the following to update + the license key: + 1. If you are updating a license server key, suspend the RVS License Server, + see Section 4.4.1: RVS License Server Control Panel. + 2. Open the RVS license update tool from the RVS License Manager (click + Update key on the USB License page). + 3. Select the Apply License Update tab, use the browser to select the update + file and click Apply update. + 4. If necessary, return the USB license key to the machine that needs updating. + 5. If you are updating a license server key, resume the RVS License Server as + described in Section 4.4.1: RVS License Server Control Panel. + + After you apply an update, we recommend that you check the license information + as described in Check installation and license details. + + Important + + When updating a floating license, the license server must be in the sus- + pended or stopped before the license key is updated. The license update + will not apply correctly if the license server remains running, even if the up- + date is carried out on a different computer. + + See Section 4.4.1: RVS License Server Control Panel for information on how + to suspend the license server, and Section 4.4.3: Checking the RVS License + Server status for information on how to check a floating license after updat- + ing it. + + +40 RVS Installation and Licensing Guide vWF20190404 +6 RVS files and folders + This chapter describes the files and folders installed by RVS and where these are + located on Windows and Linux operating systems. + + RVS installs files to two locations: + • is the location where the main RVS package is in- + stalled. This is usually C:\RVS on Windows machines, or + /usr/local/pkg/RVS/v on Linux machines. + • The user's home directory. RVS creates subdirectories for tutorials, and a home + directory for the RVS Shell. + + The RVS folder structure is as follows: + • + • auxd – contains supporting files and tools including + • rvsenv – the executables forming the RVS Shell (an MSys shell pro- + viding commonly used Linux tools). + • bin – contains the RVS tools, which are described in Chapter 2 in the RVS + Command Line Tools Reference Guide. + • doc – contains PDF copies of the RVS documentation. + • drivers – contains the driver for the USB license key. + • examples – contains pre-generated example RVS project and report + files. + • integration_resources – contains tools, scripts and reference + documentation to support RVS integrations. + • packages: contains information about the installed RVS components. + • tutorials: contains the RVS tutorial master files. These should not be + altered. + • unins: contains uninstallation executables for Windows installations. + + RVS creates the rvshome directory in your home directory. This is the Home + directory for the RVS Shell. + + When using the RVS tutorials, RVS creates tutorial workspaces as sub- + folders in your home directory. On Windows, these are stored in the + AppData/Local/rapita/v subfolder of your home directory. + + +RVS Installation and Licensing Guide vWF20190404 41 +This page intentionally left blank + Third-party licenses used +A by RVS + RVS includes software components, libraries and images released under external + licenses. + + Information about these components and licenses is supplied with the RVS soft- + ware installation, and can be found in /doc/licenses after RVS + has been installed. + + +RVS Installation and Licensing Guide vWF20190404 43 +This page intentionally left blank + diff --git a/docs-extracted/src/scov/RVS/doc/Integration_Guide.md b/docs-extracted/src/scov/RVS/doc/Integration_Guide.md new file mode 100644 index 000000000..7050ef0f6 --- /dev/null +++ b/docs-extracted/src/scov/RVS/doc/Integration_Guide.md @@ -0,0 +1,2702 @@ +--- +title: "Integration Guide" +source: "./src/scov/RVS/doc/Integration_Guide.pdf" +category: "src/scov/RVS/doc" +pages: 74 +extracted: "2026-07-06T23:13:31.570561" +--- + +# Integration Guide + +> Extracted from `./src/scov/RVS/doc/Integration_Guide.pdf` (74 pages). +> Figures, diagrams, and tables may not render accurately in plain text. + +Integration Guide + Version WF20190404 +Disclaimer +The information, text, and graphics contained within this document are +provided for information purposes only by Rapita Systems Ltd. Rapita +Systems Ltd. does not warrant the accuracy or completeness of the +information, text, and other items contained in this document. + + +Copyright and Trademarks +All rights reserved. Information and images contained within this doc- +ument are copyright and the property of Rapita Systems Ltd. All trade- +marks are hereby acknowledged to be the properties of their respective +owners. + + +Acknowledgments +Rapita Systems' tools are built using AdaCore's GNAT Pro compiler. + + +Rapita Systems Ltd. +Registered in the UK, number 5011090. +Registered address: +Atlas House +Link Business Park +Osbaldwick Link Road +York +YO10 3JB +UK +Phone: +44 (0) 1904 413 945 +http://www.rapitasystems.com/ +This document copyright © 2011-2019, Rapita Systems Ltd. + +Document build 118520 + +ID: DOC/12003 + Table of Contents + + 1. About this guide ............................................................... 5 + 1.1. Who should read this guide? ................................................... 5 + + 1.2. Structure of this guide ........................................................... 5 + + 1.3. RVS tutorials ....................................................................... 6 + + 1.4. Notation ............................................................................ 6 + + 1.5. RVS documentation map ........................................................ 7 + + 1.6. Support ............................................................................. 9 + + + 2. What is an RVS integration? ............................................ 11 + 2.1. RVS integrations ................................................................. 11 + + 2.2. Running an integration ......................................................... 12 + + + 3. Getting started ................................................................ 15 + 3.1. Next steps ........................................................................ 17 + + + 4. Integrating with a build system ....................................... 19 + 4.1. Selecting an integration strategy .............................................. 20 + + 4.2. Compiler wrappers .............................................................. 21 + + 4.3. Clone integrations ............................................................... 28 + + 4.4. Custom integrations ............................................................ 31 + + 4.5. Using clonehelper to clone source files ...................................... 31 + + 4.6. Using ihelper to link RVS files ................................................. 32 + + 4.7. Checklist .......................................................................... 35 + + + 5. Integrating with a target .................................................. 37 + 5.1. Selecting a data collection strategy .......................................... 37 + + +RVS Integration Guide vWF20190404 3 + Table of Contents + + + 5.2. Implementing a data collection strategy ..................................... 40 + + 5.3. Checklist .......................................................................... 41 + + + 6. Converting data .............................................................. 43 + 6.1. Conversion strategies ........................................................... 43 + + 6.2. Data converters .................................................................. 43 + + 6.3. Specifying data files and converters ......................................... 44 + + 6.4. Checklist .......................................................................... 46 + + + 7. Integrating with extended programming languages ......... 47 + 7.1. Adding a compiler extension to your project ................................ 47 + + + 8. Using the command-line ................................................. 49 + + 9. Customizing integrations ................................................. 51 + 9.1. Custom recipes .................................................................. 51 + + 9.2. Editing RVS integration scripts ................................................ 53 + + + 10. Integration resources .................................................... 55 + + A. Appendix ........................................................................ 57 + A.1. Integrating RVS with Ada projects ............................................ 57 + + A.2. Using different integration strategies in a single RVS integration ......... 62 + + A.3. Working with limited resources: RapiTime and RapiTask .................. 63 + + +4 RVS Integration Guide vWF20190404 +1 About this guide + The RVS Integration Guide describes how to integrate the Rapita Verification Suite + (RVS) to work in a development environment. + +1.1 Who should read this guide? + This document is intended for users wanting to integrate RVS into a development + environment. The development environment comprises the source files, build sys- + tem and target architecture used to build and run software. The reader should + have a good understanding of this environment before reading this guide. + + This document assumes that the reader can already build and run software on their + target architecture. It further assumes that the reader is familiar with the general + process of using RVS, and understands RVS terminology. For more information + on this, see the RVS User Guide. + +1.2 Structure of this guide + This document includes the following chapters: + + Chapter 1: About this guide + Describes the purpose and layout of the RVS Integration Guide and the notation + used throughout the document. + + Chapter 2: What is an RVS integration? + Describes what RVS integrations are, and how they can be used to run RVS. + + Chapter 3: Getting started + Describes an example RVS integration, showing how simple projects can be con- + figured entirely through the RVS Project Manager. + + Chapter 4: Integrating with a build system + Describes what must be done to integrate RVS alongside an existing a build sys- + tem. + + Chapter 5: Integrating with a target + Describes what must be done to integrate RVS to collect data from different target + architectures. + + Chapter 6: Converting data + Describes what must be done to convert output data into a format usable by RVS. + + +RVS Integration Guide vWF20190404 5 +RVS tutorials About this guide + + + Chapter 7: Integrating with extended programming languages + Describes how to extend RVS integrations to support analysis of code written with + language extensions over common standards. + + Chapter 8: Using the command-line + Describes how to run RVS integrations from the command-line. + + Chapter 9: Customizing integrations + Describes how to customize RVS integrations. + + Chapter 10: Integration resources + Describes resources that are helpful while integrating RVS into a development + environment, including reference documentation. + + Appendix A: Appendix + Describes important factors when using RVS with Ada projects, how to use mul- + tiple integration strategies in a single project and considerations when using + RapiTime or RapiTask on targets with limited resources. + +1.2.1 Integration Annexes + Information on how to integrate RVS with specific build systems and targets + can be found in the Integration Annexes distributed with an RVS installation in + RVS_install_path/integration_resources/integration_annexes. + These annexes describe how to use RVS with specific compilers, processors, data + collection methods and operating systems. + + For further information about integrating RVS with a specific target, or if there is no + Integration Annex for your target, contact the Rapita Systems support team. + +1.3 RVS tutorials + RVS comes with a set of tutorials that explain and demonstrate how to use RVS + through a series of practical exercises. + + You can access the RVS tutorials from the RVS Project Manager Welcome page + or Help menu. + + Tutorial + + Many sections of this guide include a Tutorial box. + + Each box highlights an RVS tutorial demonstrating the contents of the sec- + tion. + + +1.4 Notation + This document uses the following notation: + + +6 RVS Integration Guide vWF20190404 +About this guide RVS documentation map + + + • References to other documents and to other chapters or sections in this doc- + ument are written in italics, for example Chapter 1: About this guide. When + reading an electronic copy of this document, you can click on a reference to + navigate to the location of the referenced element. + • Names of RVS applications are formatted in bold italics, for example RVS + Project Manager. + • References to areas or elements in user interfaces are formatted in italics, for + example the Report Navigator. + • Menus, menu choices and button labels are formatted in bold, for example + File » Print or OK. Where buttons have icons, these are shown before their + Label in in-line text, for example Save. + • Names of RVS tools are formatted in bold, for example rvsdriver. + • References to HTML links appear as underlined text, for example + www.rapitasystems.com. + • Folder and file names are formatted in a monospaced font. + • Command-line tools and their commands, annotations and examples are for- + matted in a monospaced font. These are either written in-line with text + or as separate text blocks. When written in-line with text, they are formatted + like the following: rvsdriver, default_instrument, rvs_instr.h. + When written as a separate text block, they are formatted like the examples + below: + rvsdriver --project rvs.rvsprj --all + + #pragma RVS instrument( "function_name", "FALSE" ) + + • When referencing Ada code, the term functions refers to both functions and + procedures. + +1.5 RVS documentation map + This document is part of the Rapita Verification Suite (RVS) document set, which + contains the following documents: + + RVS Installation and Licensing Guide + Describes how to install RVS tools, and licensing options for them. + + RVS Integration Guide + Describes how to integrate RVS tools into build and target environments. + + RVS User Guide + Describes how to set up and run RVS projects, analyze data and export verification + results. + + RapiTest User Guide + Describes how to use RapiTest to manage test projects. + + +RVS Integration Guide vWF20190404 7 +RVS documentation map About this guide + + + Spreadsheet Test Format User Guide + Describes how to write tests for RapiTest in the Spreadsheet Test Format. + + RapiCover User Guide + Describes how to use RapiCover to measure code coverage and address cover- + age holes. + + RapiTime User Guide + Describes how to use RapiTime to measure timing metrics including worst-case + execution time, and how to use these metrics to identify the best optimization + candidates. + + RapiTask User Guide + Describes how to use RapiTask to measure system level task timing information, + visualize traces and gain insight into runtime behavior. + + RTBx 2xxx User Guide + Describes how to use the RTBx data logger. + + RVS Integration Library Implementation Guide + Describes how to implement RVS integration libraries. This document is for use by + readers with a thorough understanding of the implementation of RVS. + + RVS Files Reference Guide + Describes RVS-specific files including input, intermediate and output files. + + RVS Filters Guide + Describes RVS filters, which are used to convert raw trace data into a format that + RVS can analyze, and how to write them. + + RVS Command Line Tools Reference Guide + Describes the command-line tools used by RVS, including a list of available com- + mand options. + + RVS Annotations Reference Guide + Describes the annotations you can use to control instrumentation and analysis + with RVS. + + RVS Troubleshooting Guide + Describes the error and warning messages you may encounter when using RVS + tools, and how to address them. + + RVS Migration Guide + Describes how to migrate between using different versions of RVS. + + +8 RVS Integration Guide vWF20190404 +About this guide Support + + +1.6 Support + For support issues, please contact Rapita Systems Ltd. by any of the following + means: + + Email + support@rapitasystems.com + + Telephone + +44 (0) 1904 413 945 + + Website + www.rapitasystems.com + + To register for support, visit www.rapitasystems.com/register. More than one user + can register per license. + + +RVS Integration Guide vWF20190404 9 +This page intentionally left blank + What is an RVS +2 integration? + To understand RVS integrations, it is helpful to first understand how RVS works. + This is summarized in Figure 2.1. + + + Figure 2.1: How RVS works + + In its standard workflow, RVS takes a copy of input source code and injects addi- + tional code into it so that RVS can collect verification data. The code is compiled + and linked into an executable that is run on the target hardware, host system or + simulator. While the executable is run, verification data is generated. This data is + collected either while the executable is run or after it finishes execution. Finally, + verification data is written to an output report. + +2.1 RVS integrations + An RVS integration extends your existing development environment so verification + data can be produced while running test executables – these may be run by RVS or + otherwise. After a robust RVS integration has been achieved, using RVS to produce + results requires minimal effort. Three major steps are involved in setting up an RVS + integration: + 1. Integrating RVS with your build system. + 2. Selecting and implementing a method to collect data from your target. + 3. Converting raw verification data into a format that RVS can understand. + + +RVS Integration Guide vWF20190404 11 +Running an integration What is an RVS integration? + + + These fit into your existing build system as shown in Figure 2.2. + + + Figure 2.2: Steps in an RVS integration + + In the first step, you must integrate RVS with the existing build system. There are + many strategies to do this, such as using compiler wrappers, creating a copy of + source files, or manually editing the build system to insert calls to RVS tools. In + many cases there is a quick and simple way to integrate RVS with a build system. + + In the next step, you must select and implement an appropriate data collection + strategy. You will likely only have to do this if you want to use RVS to collect verifi- + cation data from an embedded target. This involves creating an integration library + containing the functionality needed to collect data from your target. This is often + the most complex step in integrating RVS. RVS comes packaged with templates + that you can use to develop your own library if necessary. + + In the final step, you may need to configure a strategy to convert raw data into a + format that RVS can understand. In some cases, this is not necessary as output + data can already be recognized by RVS. + + This guide assumes that you achieve these steps one after the other, in the order + above. To do this, you will set up an RVS project file in the RVS Project Manager + that contains an Integration you can use to collect data from your embedded + target. + +2.2 Running an integration + After you have configured an RVS Integration suitable for use in your develop- + ment environment, you can run this using either the RVS Project Manager or a + + +12 RVS Integration Guide vWF20190404 +What is an RVS integration? Running an integration + + + command-line terminal. When you use the RVS Project Manager to run an RVS + integration, it sends commands to a command-line tool called rvsdriver. This tool + manages other command-line tools that perform specific tasks such as parsing + coverage data (covparser) or combining reports (rvdutils). + + For more information on rvsdriver and other RVS command-line tools, see Chap- + ter 8 in the RVS User Guide and the RVS Command Line Tools Reference Guide, + respectively. + + Standard RVS integrations follow one of the two workflows shown in Figure 2.3. + + + Figure 2.3: RVS workflows + + The dual-pass integration mode is the default and recommended mode to use + RVS. In this mode, static and dynamic analyses are made during separate builds + of the source code. This means that you need only run static analysis once during + your project, saving computational effort. In the single-pass integration mode, you + must carry out static and dynamic analyses at the same time. This guide describes + how to set up dual-pass integrations. + + +RVS Integration Guide vWF20190404 13 +Running an integration What is an RVS integration? + + + Note + + Single-pass and dual-pass integration modes are not functionally equiva- + lent, and using a dual-pass integration mode makes it easier to use some + RVS features. For more information on single-pass integrations, contact + support@rapitasystems.com. + + Figure 2.3 shows the stages of RVS integrations. Some or all of these stages are + carried out when you run RVS, depending on which options rvsdriver is called + with, see Chapter 8: Using the command-line. The actions carried out in each RVS + stage are described below: + • Deploy – the folders and integration library needed to run an integration are + created. + • Clean – intermediate files are deleted from integration folders. + • Prepare – source code files are statically analyzed and have instrumentation + applied to them. + • Build – source code files are statically analyzed, instrumented, and compiled + and linked into executable files that will work on target. + • Run – instrumented executable files from the build stage are run on target. + • Report – verification data obtained from running executable code on target is + written into a report file that can be viewed in the RVS Project Manager. + • Export – verification data obtained from running executable code on target is + written to an output file. + + You can invoke these stages from the RVS Project Manager, or by calling rvs- + driver directly from the command-line. When you invoke a stage, rvsdriver runs + a script that calls the RVS command-line tools needed to execute the stage. + + Each RVS integration stage includes three hooks: + • An optional Prehook that, when present, performs operations necessary to run + before the Action hook. + • A mandatory Action hook that performs the main operations necessary in the + integration stage. + • An optional Posthook that, when present, performs operations necessary to + run after the Action hook. + + RVS integrations based on standard templates usually only include an Action + hook. Standard integrations can be customized in various ways to produce differ- + ent functionality, see Chapter 9: Customizing integrations. + + +14 RVS Integration Guide vWF20190404 +3 Getting started + This chapter describes how to create an RVS project that includes relevant com- + mands and settings needed to execute a build system and run analysis using one + of the RVS tools. + + Depending on your development environment, more steps may be needed to in- + tegrate RVS into it. These are discussed in subsequent chapters in this guide. + + To begin, you must have RVS installed on your system and have an appropriate + license configured. For more information, see the RVS Installation and Licensing + Guide. + + Next, create an RVS project suitable for your needs using the RVS Project Man- + ager application. Open this application on Windows systems from the Start menu + (Start » RVS » RVS Project Manager). + + When the RVS Project Manager opens for the first time, it opens on the Welcome + page, see Figure 3.1. From this page, create a new project by clicking Create + a new project in the Get started section. + + + Figure 3.1: RVS Project Manager Welcome page + + Tip + + If the Welcome page is not open, create a New RVS Project from the + File menu. + + +RVS Integration Guide vWF20190404 15 + Getting started + + + The New RVS Project Wizard opens, which guides you through project creation. + To create a project suitable for your needs, follow the instructions below as you + work through the wizard: + 1. On the Project Settings page, give your project a name and select the main + language used in your source code. + 2. On the Analysis Settings page, provide a name for your analysis and select + settings depending on the type(s) of RVS analysis you want to apply. For + more information, see the RVS User Guide. + 3. On the Target Settings page, provide a name for the target you'll be running + your test executable on. Optionally, provide the commands to run during RVS + integration stages (see Section 2.2: Running an integration) and the folder + to run them in. These should be the same commands you normally use to + invoke various stages of your build system. + + Note + + RVS uses the system's default shell to invoke commands. For your integra- + tion to succeed, the commands you enter on the Target Settings page must + be valid for this shell. + + On Windows systems, the default shell is cmd.exe. + + 4. On the Integration Settings page, provide a name for your integration and + select an Integration Strategy. For more information on integration strategies, + see Chapter 4: Integrating with a build system. If you have RapiTest installed, + select either the Managed or Unmanaged or Testing Mode, to either use + RapiTest to create a test harness or not. + 5. On the Export Settings page, optionally provide settings for an export to add + to your integration. RVS exports let you export data into formats other than + the RVS report format, which you can only view in the RVS Project Manager. + For more information, see the RVS User Guide. + 6. On the Summary page, review your settings to ensure that they are correct. + + After you click Finish, RVS creates a folder containing the files it needs to run, + including the project file. + + Before you can use an RVS project to analyze source code, you must deploy an + RVS integration library. This includes definitions for RVS functions that tell RVS how + to instrument code and collect data from an executable when it runs. + + RVS copies files from a template folder to create an integration library during the + Deploy stage of an integration. To deploy an integration library for an integration + using the RVS Project Manager, click Deploy in the Actions section of the project + overview page that is open, and confirm by clicking OK. For more information on + deploying RVS integrations, see Section 4.3 in the RVS User Guide. + + +16 RVS Integration Guide vWF20190404 +Getting started Next steps + + + This deploys an integration library from a standard template based on your project + settings. While template libraries for on-host integrations can often be used out- + of-the-box, you may need to manually edit libraries for on-target integrations. + +3.1 Next steps + For some on-host integrations, you may now be able to use RVS to produce re- + sults. For more complex integrations such as ones using the clone strategy or + where the test executable is run on an embedded target, more steps must be + carried out first. + + To check if your integration works, click Prepare in the Actions section of the + project overview page (see Figure 3.2), then click OK in the dialog that opens. + + + Figure 3.2: Preparing your integration + + If the console reports an error, you may need to perform more steps to integrate + RVS with your build system. To learn how to do this, follow Chapter 4: Integrating + with a build system. + + If the console eventually displays that rvsdriver completed successfully, you + may be able to run RVS to produce results and analyze them, if you are running + an on-host integration. To learn how to do so, follow the RVS User Guide. + + If you want to use RVS to collect data from tests run on an embedded target, + continue to Chapter 5: Integrating with a target to further the integration process. + + +RVS Integration Guide vWF20190404 17 +This page intentionally left blank + Integrating with a build +4 system + This chapter assumes that you have created an RVS project suitable for the pro- + gramming language of your source code. If you have not done this, we recom- + mend that you learn how to by reading Chapter 3: Getting started. + + Important + + This chapter describes the options available for integrating RVS with vari- + ous build systems, and factors that may be important when deciding which + strategy to use. + + RVS is flexible and there are many options for integration, which are not all + described herein. Further, the number of factors involved mean that, while + some strategies may be more efficient in certain cases, no one strategy is + universally appropriate. + + We can provide expert assistance with integrating RVS with your build sys- + tem. For more information, contact support@rapitasystems.com. + + For RVS to collect verification data, it must be integrated with the build system + used to produce and run an executable. When it is, you can run your build system + using the RVS Project Manager. + + RVS build system integrations must allow RVS to do the following: + 1. Collect information on all source files in a project during the Prepare stage + of an integration – to know which files need to be analyzed, and collect static + information on the source code, RVS must be able to observe, collect and + store information on all source files in the project. + 2. Inject code into preprocessed files to apply RVS analysis during the Build + stage of an integration – to apply RVS analysis, RVS tools inject code into + preprocessed source code. This injected code may apply RVS instrumenta- + tion (for coverage or timing analysis with RapiCover or RapiTime, for exam- + ple) or create a test harness for functional testing (RapiTest). + 3. Add RVS integration libraries to preprocessed code during the Build stage of + an integration – for RVS to collect results, an RVS integration library must be + included in the binary produced by the build system. RVS integration libraries + contain the functions needed to collect data such as results from functional + tests, coverage or timing results from the target system. For more information + on RVS integration libraries, see Section 5.2: Implementing a data collection + strategy. + + For more information on the stages of RVS integrations, see Section 2.2: Running + an integration. + + +RVS Integration Guide vWF20190404 19 +Selecting an integration strategy Integrating with a build system + + +4.1 Selecting an integration strategy + There are multiple ways to integrate RVS with build systems. These include: + • Using compiler wrappers – a wrapper intercepts calls made to your compiler + so RVS can observe and instrument source code automatically. This strategy + is described in Section 4.2: Compiler wrappers. + • Using a clone strategy – a copy is made of all the files needed to run the + build system, and source files are replaced with instrumented versions. This + strategy is described in Section 4.3: Clone integrations. + • Using a custom strategy – custom strategies are the most flexible strategies + to implement, but also the most complex. These strategies may involve adding + calls to RVS tools directly to your build system, using RVS compiler wrappers, + and using parts of the typical clone integration strategy. This strategy is de- + scribed in Section 4.4: Custom integrations. + + The language of your source code is important when determining which integration + strategy to use. If your project includes Ada code, special considerations must be + taken when selecting an integration strategy. These are described in Section A.1: + Integrating RVS with Ada projects, and it is strongly recommended that you read + through them before continuing. + + Note + + You can use different integration strategies for the Prepare and Build + stages of RVS integrations. For example, you could use a clone strategy for + the Prepare stage and a compiler wrapper strategy for the Build stage. To + learn how to do this, see Section A.2: Using different integration strategies in + a single RVS integration. + + When selecting an integration strategy, you should consider how much effort the + strategy will take to implement. The compiler wrapper strategy usually requires + the least effort to apply and maintain, and is the preferred option when it can be + used. Among other reasons, this is because this strategy often requires the fewest + modifications to be made to your build system. + + +20 RVS Integration Guide vWF20190404 +Integrating with a build system Compiler wrappers + + +4.2 Compiler wrappers + A compiler wrapper is an executable that offers an efficient way of integrating RVS + with your build system by intercepting calls made to your compiler, see Figure 4.1. + The use of compiler wrappers is often the preferred integration strategy as it re- + quires the least modification to the build system and automates more stages of + the integration that other strategies. + + + Figure 4.1: Compiler wrappers + + Compiler wrappers intercept calls to the compiler they wrap. They ensure that RVS + tasks such as source code instrumentation happen before the call to the original + compiler happens. They do the following during an RVS integration: + • During the Prepare stage, they automatically store information on all source + files in the system. + • During the Build stage, they automatically inject RVS code into preprocessed + versions of source files from the project and add RVS integration libraries to + the system. + + We include wrappers for a number of commonly-used compilers in your RVS in- + stallation. If you have a compiler that we don't have a wrapper for, contact us at + support@rapitasystems.com for support options. + + +RVS Integration Guide vWF20190404 21 +Compiler wrappers Integrating with a build system + + +4.2.1 Using compiler wrappers + To select a compiler wrapper integration strategy, select Compiler Wrapper as the + Integration Strategy when creating an RVS project, see Chapter 3: Getting started. + + There are three ways to integrate RVS with a build system using a compiler wrap- + per: + • Wrapping in-place + • Calling a wrapper from the PATH + • Calling a wrapper from your build system + + The most efficient strategy to take depends on your development environment and + how much access you have to it. This may be influenced by your IT policy. + + The build system is often the most complicated part of the development environ- + ment, and integration strategies that do not modify it are generally more reliable + and incur lower maintenance costs. Figure 4.2 shows how to select the most effi- + cient strategy assuming that compilers are stored in an accessible location and + you want to avoid making changes to the build system as much as possible. + + + Figure 4.2: Selecting a compiler wrapper integration strategy + + Note + + GNAT compilers, which must be used during the Prepare stage of Ada inte- + grations, must be wrapped in-place. + + +22 RVS Integration Guide vWF20190404 +Integrating with a build system Compiler wrappers + + + Note + + Visual Studio compilers from versions up to Visual Studio 2008 must be + wrapped in-place. Compilers from Visual Studio 2010 and above, however, + can be wrapped either in-place or through other methods. + + For more information on integrating RVS with Visual Studio, including how to + wrap Visual Studio compilers, see the Visual Studio Integration Annex. + + To learn more about each integration method, and how to apply it, see the following + sections. + +4.2.2 Wrapping in-place + The simplest strategy to integrate RVS with your build system using compiler wrap- + pers is often to wrap the compiler in-place. For some compilers, such as GNAT, + this is the only wrapper strategy that can be used. + + Wrapping a compiler in-place involves renaming the compiler in its directory and + putting the compiler wrapper in its place. For example, to wrap the GCC compiler, + gcc is renamed to gcc_orig in its directory, and the wrapper (called gcc) is + added to the same directory. As such, this strategy can only be used if you have + access to the directory containing the compiler. + + To wrap a compiler in-place on Windows, use the RVS Compiler Wrapper config- + uration utility as follows: + 1. Launch the RVS Project Manager. + 2. From the Help menu, select Compiler Wrapper Installer to launch the RVS + Compiler Wrapper configuration utility. + 3. On the Compiler Selection screen, select the compiler you want to wrap. + 4. On the Compiler Location screen, provide the file path to your compiler. + 5. On the Task Selection screen, select Wrap the compiler. If your compiler has + already been wrapped, this option is replaced with Re-wrap the compiler. + + To wrap a compiler in-place on Linux: + 1. Open a terminal and navigate to the root of your RVS installation. + 2. Run the following command to check the compilers supported and what + their codes are i.e. for GNAT use 'GNAT': ./auxd/python/bin/python3 ./ + integration_resources/compiler_wrappers/setup.py --help + 3. Run the following command to wrap the compiler ./auxd/python/bin/ + python3 ./integration_resources/compiler_wrappers/setup.py --mode + install --compiler --dir /path/to/compiler + + e.g. to wrap GNAT under /usr/local/pkg/gnat run ./auxd/python/ + bin/python3 ./integration_resources/compiler_wrappers/setup.py -- + mode install --compiler GNAT --dir /usr/local/pkg/gnat + + +RVS Integration Guide vWF20190404 23 +Compiler wrappers Integrating with a build system + + + Note + + RVS is shipped with a pre-wrapped version of GNAT GPL 2014, which is lo- + cated in the RVS/auxd/x86/gnat-gpl-wrapped folder. + + If you are integrating RVS with an Ada project, you may want to use this + compiler to build your source code during the Prepare stage of your in- + tegration, see Section A.2: Using different integration strategies in a single + RVS integration. + + + Assuming you have followed this guide so far, you should now be able to use RVS + to produce verification data; continue to Section 4.7: Checklist. + +4.2.3 Calling a wrapper from the PATH + One strategy to run RVS using a compiler wrapper is to change the PATH set by + RVS when invoking your build system to point to the wrapper instead of your com- + piler. When using this strategy, you should ensure that the compiler is only called + from the PATH in the build system. If it is not, you should also change the build + system as described in Section 4.2.4: Calling a wrapper from your build system. + + This strategy involves adding a wrapper with the same name as your compiler to + your file system and editing the PATH RVS uses so that it calls the wrapper rather + than the compiler. + + The compiler wrappers included in RVS are located in the + rvs/integration_resources/compiler_wrappers directory. Wrap- + per executable names end with _wrap to distinguish them from the compilers + they wrap, for example gcc_wrap. + + To use this strategy, copy the wrapper for your compiler somewhere outside the + read-only RVS directory, and rename it to have the same name as your compiler + (gcc, for example). + + Next, edit the path RVS uses by doing the following: + 1. Open your project in the RVS Project Manager. + 2. Click Configure in the Actions section of the project overview page to + open the configuration options page. + 3. Open the Environment page from the sidebar, which is nested under + Project. + 4. Type the path to the wrapper before $((PATH)) in the Path Variable section. + 5. Save and Close your configuration using the buttons at the top-left + of the window. + + +24 RVS Integration Guide vWF20190404 +Integrating with a build system Compiler wrappers + + + Figure 4.3: Calling a wrapper from the PATH + + Assuming that you have followed this guide so far, you should now be able to use + RVS to produce verification data; continue to Section 4.7: Checklist. + +4.2.4 Calling a wrapper from your build system + One strategy to run RVS using a compiler wrapper is to change your build scripts + so they call the compiler wrapper instead of your compiler. Build scripts are often + the most complicated part of a build system, and other compiler wrapper integra- + tion strategies are recommended where applicable. + + RVS compiler wrappers are located in the + rvs/integration_resources/compiler_wrappers directory. Wrap- + per executable names end _wrap to distinguish them from the compilers they + wrap, for example gcc_wrap. + + To use these wrappers, you must edit your build scripts to call the wrapper rather + than your compiler. You must replace all calls to your compiler in the build script to + call the wrapper instead – this may mean simply changing an environment variable + in your build scripts, or changing the script in multiple places. + + After editing your build scripts to call the compiler wrapper, you must also configure + the wrapper in the RVS Project Manager by doing the following: + 1. Open your project in the RVS Project Manager. + 2. Click Configure in the Actions section of the project overview page to + open the configuration options page. + 3. On the sidebar, expand your target and open the Compiler Wrapper + page. + 4. Click Add to add a compiler wrapper. + 5. Beside the Wrapper path field, click Browse and select the wrapper you are + using. + 6. Beside the Compiler path field, click Browse and select the compiler you are + using from your file system. + + +RVS Integration Guide vWF20190404 25 +Compiler wrappers Integrating with a build system + + + 7. Save and Close your configuration using the buttons at the top-left + of the window. + + + Figure 4.4: Calling a wrapper from your build system + + Assuming you have followed this guide so far, you should now be able to use RVS + to produce verification data; continue to Section 4.7: Checklist. + +4.2.5 Modifying compiler wrapper integrations + In many cases, little or no modification of an integration is needed for compiler + wrapper strategies to work efficiently. You may, however, need to, or want to, make + some changes, as described in the following sections. + + Including RVS libraries + + By default, compiler wrappers add RVS integration libraries to source code by + linking the libraries together with your other source files during the Build stage + of the integration. For this strategy to work, you may need to configure RVS with + additional information about your linking strategy. + + If your build system links files in multiple stages, you must instruct RVS during + which linker invocation you want RVS to link libraries by specifying link triggers. To + do so, do the following: + 1. Open your project in the RVS Project Manager. + 2. Click Configure in the Actions section of the project overview page. + 3. Click Advanced Configuration in the sidebar to the left of the window. + 4. Select the Rvslib Link Trigger[+] entry, which is nested under Target List. You + can use the filter function to find this more easily. + + +26 RVS Integration Guide vWF20190404 +Integrating with a build system Compiler wrappers + + + 5. In the New Item field, click Add. + 6. In the Rvslib Link Trigger[] entry that appears, configure settings + so that RVS knows when to link libraries: + • In the Trigger Option Type entry, you can select the type of options to be + matched against; any, file, flag or tool specific options. + • In the Argument Pattern and Value Pattern entries, specify glob patterns + to match against option arguments and values that identify a linker invo- + cation, respectively. + • In the Match State entry, specify a Value of true to configure RVS to link + libraries when elements are matched according to the entries above, or + a Value of false to configure RVS not to do so. + 7. If you need to specify more link triggers, add more from the Rvslib Link Trig- + ger[+] entry and configure them as appropriate. If you have added multiple + link triggers, RVS determines when to link libraries by applying a Boolean + operation on those triggers (and by default). If you need to change this be- + havior, change the Value field in the Rvslib Link Condition State entry. + 8. Click the Save and Close buttons to save your changes and return to + the RVS Project Manager. + + Figure 4.5 shows an example in which RVS has been configured to link RVS li- + braries when the -o main.elf flag is observed. + + + Figure 4.5: Specifying link triggers + + +RVS Integration Guide vWF20190404 27 +Clone integrations Integrating with a build system + + +4.3 Clone integrations + One way to integrate RVS to work within your development environment is to use + a clone strategy. Using this strategy, RVS creates a copy (clone) of your source + files and the files needed to build your code, injects RVS code and instrumentation + into the copied code for RVS analysis, then compiles and links files, including an + RVS library, to produce an executable from which verification results are collected, + see Figure 4.6. + + + Figure 4.6: Clone integration workflow + + +28 RVS Integration Guide vWF20190404 +Integrating with a build system Clone integrations + + + When using a clone strategy, RVS must be able to: + 1. Observe and clone all preprocessed source files in the project during the + Prepare stage of the integration. To learn how to configure an RVS clone in- + tegration to do this, see Section 4.3.2: Observing preprocessed source files. + 2. Inject RVS code into the cloned versions of preprocessed source files and + compile and link these during the Build stage of the integration. To learn how + to configure an RVS clone integration to do this, see Section 4.3.3: Injecting + RVS code into cloned preprocessed files. + 3. Add RVS integration libraries to cloned source files and compile and link + these during the Build stage of the integration. To learn how to configure an + RVS clone integration to do this, see Section 4.3.4: Adding RVS integration + libraries. + + To select a clone integration strategy, select Clone as the Integration Strategy when + creating an RVS project, see Chapter 3: Getting started. + +4.3.1 Editing clone integration settings + You can configure many of the clone settings applied in your project from the + Clone page of the RVS Config Editor, see Figure 4.7. To access this page, + open your project in the RVS Project Manager, click Configure on the project + overview page, and click Clone, which is nested under Targets. + + + Figure 4.7: Clone settings page + + +RVS Integration Guide vWF20190404 29 +Clone integrations Integrating with a build system + + +4.3.2 Observing preprocessed source files + + Important + + To observe preprocessed source files from your project, these files must be + preserved by your build system. Preprocessed files can be preserved by + using compiler flags; when using the gcc compiler, for example, you can + save preprocessed files by using the -save-temps flag. + + For more information, contact support@rapitasystems.com + + + The first requirement when implementing an RVS clone integration strategy is that + RVS can observe all of the preprocessed source files in a project. There are mul- + tiple ways in which RVS can do this: + • It can scan the file system for files matching specific file extensions within and + under a specified folder after the build system has been run. This is the sim- + plest and default method and is described in the section called “Scanning the + file system for preprocessed files” on p. 30. + • You can configure your build system to store information on source files in your + project by using the RVS clonehelper tool. This is described in the section + called “Storing source file information with clonehelper” on p. 31. + + You can use both methods above in a single integration. + + Important + + If you use multiple methods to instruct RVS which preprocessed source files + are present in your project, you must ensure that each file is only provided + to RVS once. Otherwise, unexpected behavior may occur. + + + Scanning the file system for preprocessed files + + By default, during clone integrations, RVS scans the Root Source Folder and all + folders under it for files with a specific Pproc File Pattern, depending on the project + language(s). It then clones each such file and stores information associated with + the source and cloned files in order to apply subsequent processing. + + You can edit these settings from the Clone page in your RVS project (see Sec- + tion 4.3.1: Editing clone integration settings): + • To edit the directories that RVS scans for preprocessed files, change the Root + Source Folder setting. + • To edit the file extensions that RVS treats as preprocessed files, change the + respective Pproc File Pattern settings. + • To disable automatic scanning for preprocessed files, set Auto-scan For Pre- + processed Files to False. + + +30 RVS Integration Guide vWF20190404 +Integrating with a build system Custom integrations + + + Storing source file information with clonehelper + + You can configure your build system to store information on source files in your + project by adding calls to the RVS clonehelper tool directly to your build system. + + To learn how to do so, see Section 4.5: Using clonehelper to clone source files. + +4.3.3 Injecting RVS code into cloned preprocessed files + The second requirement when implementing an RVS clone integration strategy is + that RVS can inject RVS code into cloned preprocessed files and compile and link + these files during the Build stage of the integration. To do this, during the Build + stage of an integration, RVS automatically overlays the original source files to be + compiled with preprocessed versions of them, which were collected during the + Prepare stage of the integration. + +4.3.4 Adding RVS integration libraries + The final requirement when implementing an RVS clone integration strategy is that + RVS integration libraries are added when source files are compiled and linked dur- + ing the Build stage of the integration. To configure RVS to add integration libraries, + you must modify your build system. + + You can use the RVS ihelper tool to help you do this, see Section 4.6.2: Injecting + RVS integration libraries using ihelper. + +4.4 Custom integrations + Custom integrations are flexible, giving you a blank slate from which to configure + an integration. This involves making changes to your build system. + + As with all RVS integrations, in custom integrations, RVS must be able to: + • Collect information on all source files in your project during the Prepare stage + of an integration – to configure this, you can use clonehelper as described in + Section 4.5: Using clonehelper to clone source files. + • Inject code into preprocessed source files from your project during the Build + stage of an integration – to configure this, you can use ihelper as described + in Section 4.6.1: Overlaying source files using ihelper. + • Add RVS integration libraries to preprocessed code during the Build stage of + an integration – to configure this, you can use ihelper as described in Sec- + tion 4.6.2: Injecting RVS integration libraries using ihelper. + + To select a clone integration strategy, select Custom as the Integration Strategy + when creating an RVS project, see Chapter 3: Getting started. + +4.5 Using clonehelper to clone source files + The RVS tool clonehelper is designed to help you clone source files so they can + be instrumented by RVS. + + +RVS Integration Guide vWF20190404 31 +Using ihelper to link RVS files Integrating with a build system + + + Example 4.1 shows an example of a clonehelper call in a build system that uses + gcc to build C code using Make. + + Example 4.1: Storing source file information with clonehelper + + 1 GCCEXE?=gcc + 2 SRCS_C=$(shell ls src/*.c) + 3 OBJS=$(SRCS_C:.c=.o) + 4 + 5 ifeq ($(RVS_BUILD_STAGE),prepare) + 6 RVS_CFLAGS:=-save-temps=obj -DRVS + 7 endif + 8 + 9 all: build run + 10 @echo ========== Complete ========== + 11 + 12 build : $(OBJS) + 13 @echo ========== Build ========== + 14 $(GCCEXE) -o all.exe $(OBJS) + 15 + 16 %.o : %.c + 17 $(GCCEXE) -c -o $@ $(RVS_CFLAGS) $< + 18 clonehelper $< + + + The conditional RVS_BUILD_STAGE segment beginning on line 5 configures + RVS to apply the -save-temps=obj compiler flag when running the Prepare stage + of an RVS integration to ensure that preprocessed files are preserved during com- + pilation. + + The RVS_BUILD_STAGE variable is set by the master RVS tool, rvsdriver, which + will be called when you run your RVS integration. When running the Prepare stage + of an integration, rvsdriver sets the value of this variable to prepare. + + Thus, by including the conditional RVS_CFLAGS variable in the %.o rule that gen- + erates object files (line 17), we instruct the compiler to save preprocessed files + when we Prepare the integration and invoke the build systems with rvsdriver. + + For more information on rvsdriver, see Chapter 12 in the RVS Command Line Tools + Reference Guide. + + The clonehelper $< command on line 18 calls clonehelper for each com- + piled .c file. This stores information RVS needs to instrument each file and, by + default, moves preserved preprocessed files to the intermediates folder in + the RVS project. + + For more information on clonehelper, see Chapter 5 in the RVS Command Line + Tools Reference Guide. + +4.6 Using ihelper to link RVS files + The RVS tool ihelper is designed to help you modify build systems to achieve + RVS integrations with them. ihelper can perform a variety of actions including the + following: + + +32 RVS Integration Guide vWF20190404 +Integrating with a build system Using ihelper to link RVS files + + + • Overlaying source files with instrumented versions of them, see Section 4.6.1: + Overlaying source files using ihelper. + • Injecting RVS library files into a project, see Section 4.6.2: Injecting RVS inte- + gration libraries using ihelper. + + For more information on ihelper, see Chapter 9 in the RVS Command Line Tools + Reference Guide. + +4.6.1 Overlaying source files using ihelper + You can use ihelper to overlay instrumented RVS files over the source files your + build system would compile normally. This is typically done by adding calls to + ihelper manually to a build system. + + Example 4.2 shows an example of an ihelper overlay call in a build system that + uses gcc to build C code using Make. This example builds on the one shown in + Section 4.5: Using clonehelper to clone source files. + Example 4.2: Overlaying source files with ihelper + + 1 GCCEXE?=gcc + 2 SRCS_C=$(shell ls src/*.c) + 3 OBJS=$(SRCS_C:.c=.o) + 4 + 5 ifeq ($(RVS_BUILD_STAGE),prepare) + 6 RVS_CFLAGS:=-save-temps=obj -DRVS + 7 endif + 8 + 9 all: build run + 9 @echo ========== Complete ========== + 10 + 11 build : $(OBJS) + 12 @echo ========== Build ========== + 13 $(GCCEXE) -o all.exe $(OBJS) + 14 + 15 %.o : %.c + 16 $(GCCEXE) -c -o $@ $(RVS_CFLAGS) $(shell ihelper --overlay $<) + 17 clonehelper $< + + + The $(shell ihelper --overlay $<) command on line 16 calls ihelper + to overlay the input .c file with the version of the same file instrumented by RVS. + + For more information on ihelper and the --overlay option, see Chapter 9 in the + RVS Command Line Tools Reference Guide. + +4.6.2 Injecting RVS integration libraries using ihelper + You can use ihelper to configure the injection of RVS integration libraries when + you link files during your project. This is typically done by adding calls to ihelper + manually to a build system. + + Example 4.3 shows an example, where ihelper calls are used to inject RVS in- + tegration libraries in a build system that uses gcc to build C code using Make. + + +RVS Integration Guide vWF20190404 33 +Using ihelper to link RVS files Integrating with a build system + + + This example builds on the ones shown in Section 4.5: Using clonehelper to clone + source files and Section 4.6.1: Overlaying source files using ihelper. + + Example 4.3: Adding integration libraries with ihelper + + 1 GCCEXE?=gcc + 2 SRCS_C=$(shell ls src/*.c) + 3 OBJS=$(SRCS_C:.c=.o) + 4 + 5 ifeq ($(RVS_BUILD_STAGE),prepare) + 6 RVS_CFLAGS:=-save-temps=obj -DRVS + 7 endif + 8 RVS_CFLAGS+=$(shell ihelper --prearg -I --libinc) + 9 + 10 all: build run + 11 @echo ========== Complete ========== + 12 + 13 build : $(OBJS) $(shell ihelper --fmt-make --libobjs) + 14 @echo ========== Build ========== + 15 $(GCCEXE) -o all.exe $(OBJS) $(shell ihelper --libobjs) + 16 + 17 %.o : %.c + 18 $(GCCEXE) -c -o $@ $(RVS_CFLAGS) $(shell ihelper --overlay $<) + 19 clonehelper $< + + + The ihelper call added to the RVS_CFLAGS variable on line 8 configures ihelper + to prepend each compiler call made during the %.o rule with a command to add + RVS include paths so the build system can find RVS header files. + + The commands in the build rule instruct the build system to include RVS libraries + when building code. The $(shell ihelper --fmt-make --libobjs) + command on line 13 instructs make to build the RVS libraries along with other + objects. The $(shell ihelper --libobjs) command on line 15 instructs + gcc to link RVS libraries along with other objects in the system. + + For more information on ihelper and the options used in the example above, see + Chapter 9 in the RVS Command Line Tools Reference Guide. + + +34 RVS Integration Guide vWF20190404 +Integrating with a build system Checklist + + +4.7 Checklist + When you have selected and implemented an appropriate strategy to apply during + both the Prepare and Build stages of an integration, you should be able to run an + integration to produce verification data if you are running your test executable on + a host system. To learn how to do so, see Chapter 4 in the RVS User Guide. + + If you want to learn how to use RVS to collect verification data from an embedded + target, continue to Chapter 5: Integrating with a target. + + +RVS Integration Guide vWF20190404 35 +This page intentionally left blank +5 Integrating with a target + This chapter assumes that you have created an RVS project suitable for the pro- + gramming language of your source code and use with your build system. If you + have not done this, we recommend that you learn how to by reading Chapter 3: + Getting started and Chapter 4: Integrating with a build system. + + If you want to use RVS to collect verification data from an embedded target, you + must select and implement an appropriate data collection strategy. When this has + been done, you can use the RVS Project Manager to invoke your build system and + collect verification data from your target. This involves two stages: selecting a data + collection strategy, and creating an integration library suitable for that strategy. + +5.1 Selecting a data collection strategy + This section describes various strategies that can be used to integrate RVS to + collect data from an embedded target. With an appropriate strategy, RVS can be + integrated with almost any target. When selecting a strategy, you should consider + your target hardware, the analyses you want to perform and any auxiliary hardware + you have available. + + When selecting a strategy, the following factors are important: + • Execution time overhead – RVS calls take time to execute, but should not + cause your system to violate timing restraints such as watchdog timers. Be- + cause of this, lightweight instrumentation points are preferred. + • Memory – it may be beneficial to store temporary RVS data in a buffer. If not + enough memory is available for this, the data can be streamed to an external + device for storage, such as on an RTBx. + • Code size – each instrumentation point requires space when compiled into + object code. This can be a limiting factor when determining a collection strat- + egy due to the limited space available on many embedded targets. + • Bandwidth – if RVS data is stored externally, the speed at which data can be + transferred to external storage is important. + • Off-target data processing time – if RVS data needs to be filtered and this is + not done as it is created, it must be filtered afterwards. For programs compiled + from large code bases, this can take a long time. + + The most appropriate strategy to use depends on the analysis you want to per- + form with RVS. If you want to use RVS to run unit tests (with RapiTest) or analyze + structural code coverage (with RapiCover), the best strategy differs to that if you + want to use it to run timing (RapiTime) or tasking (RapiTask) analysis. If you want + to use RVS to analyze timing or tasking behavior, this will have a large influence + + +RVS Integration Guide vWF20190404 37 +Selecting a data collection strategy Integrating with a target + + + on your data collection strategy due to the large volume of data involved and the + need to preserve the original execution time behavior as much as possible. + + The next sections describe how to select a strategy to collect data for: + • RapiCover and RapiTest + • RapiTime and RapiTask + +5.1.1 RapiCover and RapiTest strategies + Most often, the best way to collect data for RapiTest or RapiCover is to use a map. + A map stores RVS data in memory on the target while the program executes. The + same memory location can be overwritten, for example if a function is instrumented + for coverage analysis and is observed more than once. After the program finishes, + RVS data is extracted. A map incurs low execution time and memory overheads + and is easy to implement. + + If your target has limited memory, you can use a LiveMap to transfer RVS data + onto external memory as the program executes. While this has very low on-target + overheads, your system must have enough bandwidth to support streaming the + trace as it is produced. + + If your system's bandwidth is a limiting factor, you can use a DiffMap to collect RVS + data from it. Using this method, a standard map is created on your target. Every + time unique RVS data is stored to this map, it is transferred off-target. Because + only unique data is transferred, the off-target data processing time needed is lower + than for a LiveMap. This method requires the same amount of memory available + on your target as needed for a standard map. + + A summary of the strategies discussed above is shown in Table 5.1. + Table 5.1 RapiCover and RapiTest data collection strategies + Collection Hardware required Execution Memory Code size Bandwidth + method time overhead overhead overhead + overhead + Map Any target data link, Medium Low Low – None + e.g. debugger, eth- medium + ernet. + LiveMap RTBx or a logic ana- Low Negligible Low High + lyzer. Access to I/O + pins. + DiffMap RTBx or a logic ana- Medium Low Medium Low + lyzer. Access to I/O + pins. + +5.1.2 RapiTime and RapiTask strategies + To collect data that can be used for analysis with RapiTime or RapiTask, you must + use a trace. Traces collect both an identifier (ID) and timestamp for each instru- + mentation point (ipoint) encountered in the executable. + + +38 RVS Integration Guide vWF20190404 +Integrating with a target Selecting a data collection strategy + + + There are multiple types of trace and the most appropriate strategy to use depends + on the hardware you have available, see below: + • Memory trace – a trace is stored in memory. Timestamps are provided by the + target hardware, which writes each ipoint ID and timestamp to a buffer. The + in-memory trace may be extracted, for example, while the executable runs by + using an ethernet connection or debugger. + • File trace – this works like a memory trace, but data is written to a file instead of + memory. To use this strategy, it must be possible to write to permanent storage + such as a hard disk. + • I/O trace – ipoint IDs are written to an output port (for example GPIO pins) + connected to a RTBx or logic analyzer. The external hardware timestamps the + ID and stores trace data. + • Address trace – an address or range of addresses is reserved to encode each + ipoint ID. An RTBx, logic analyzer or trace-enabled debugger monitors each + address and timestamps data when data is written to the address. + + A summary of these strategies is shown in Table 5.2. + + Table 5.2 Trace collection methods + + Collection Hardware required Execution Memory Code size + method time overhead overhead + overhead + Memory trace Any target data link, e.g. Medium – High Medium + debugger, ethernet. high + File trace Data storage device. Medium – Low Medium + high + I/O trace An RTBx or logic analyz- Low Very low Medium + er. + Access to I/O pins. + Address trace An RTBx or logic analyz- Low Very low Low + er. + Connectivity to address + bus. + + All trace collection techniques involve collecting a large amount of trace da- + ta. This incurs a large off-target data processing time overhead. To reduce this + overhead, you may want to consider using the RTBx, which filters timestamped + verification data produced at high rates on-the-fly. For more information, con- + tact enquiries@rapitasystems.com or visit https://www.rapitasystems.com/prod- + ucts/rtbx. + + Note + + More information on using RapiTime or RapiTask on hardware with limited + resources is available in Section A.3. + + +RVS Integration Guide vWF20190404 39 +Implementing a data collection strategy Integrating with a target + + +5.2 Implementing a data collection strategy + When you have selected an appropriate data collection strategy, you must imple- + ment it. This involves developing an integration library that instructs your build sys- + tem how to collect data from your target. + + If you have reached this point in the integration, RVS should already have deployed + a template integration library for your project. If you have not yet created an RVS + project, follow Chapter 3: Getting started. + + RVS automatically deploys a template integration library based on the options you + have configured in your RVS project after you create it using the New RVS Project + Wizard. To locate this, open the Project menu in the RVS Project Manager and + select Open project folder. In this folder, open the folder prefixed rvs and + then the folder prefixed with rvslib. The files in this folder comprise a template + integration library, which must be configured to work with your target hardware. + + Developing an integration library for a specific target requires a good understand- + ing of how to configure data input and output to and from an embedded target, and + of the RVS API. The following calls are included in most RVS integration libraries: + • RVS_Init (RVS.Init for Ada) – this instructs RVS to set up the environ- + ment it needs to begin data collection. It is usually the first RVS function called + during an integration. + • RVS_Build_Id (RVS.Build_Id for Ada) – this optional call sets a build + version identifier based on, for example, the source code revision used in the + integration. + • RVS_Begin_Test (RVS.Begin_Test for Ada) – this instructs RVS to start + a new test that can be referenced with a test identifier. It is optional, but can + be used to assign unique identifiers to each test for easier processing later. + • RVS_Ipoint (RVS.Ipoint for Ada) – this instructs RVS to register that a + point in the program has been hit during its execution. Examples of how this is + achieved include setting a bit on an I/O port or writing an ipoint identifier to a + file. If data is timestamped, this function may also configure how this is done. + This function is not normally referenced directly, but expanded from macros + such as RVS_I or inline functions in the source code. + • RVS_End_Test (RVS.End_Test for Ada) – this instructs RVS to end a test. + • RVS_Output (RVS.Output for Ada) – this instructs RVS to output data, + often at the end of a test run. For example, it may instruct RVS how to upload + data stored in memory at the end of a test. + + The RVS Integration Library Implementation Guide describes how to implement + RVS integration libraries including more detailed information about the API calls + above, and which you need to implement depending on your analysis settings + and data collection method. This is aimed for use by readers with a thorough + understanding of how RVS works. + + +40 RVS Integration Guide vWF20190404 +Integrating with a target Checklist + + + For more information on how to integrate RVS to work with specific com- + pilers, data collection methods or hardware, you can read the Integra- + tion Annexes included in your RVS installation. To locate these, open the + RVS/integration_resources/integration_annexes folder. + + We offer support integrating RVS to work with your embedded target. The main + outcome of this is a robust integration library that lets you use RVS to collect data + from your target. For more information, contact support@rapitasystems.com. + +5.2.1 Configuring RVS to use an integration library + For RVS to be able to collect data from your embedded target, a library must be + deployed for the integration. By default, RVS deploys a template library, which is + selected depending on your project settings, for example the language of your + source code and your data collection strategy. If we have provided you with a + custom library, or you have developed one yourself, you will have to configure RVS + to deploy this library instead. + + To configure RVS to use an integration library, open your project in the RVS Project + Manager. On the main project page, click Configure. Click on the page for your + integration (if this is not shown, click the arrow next to Integrations to show it). In + the Integration Library field, click Browse, locate and select the integration library + on your file system, and click OK. Finally, Save and Close your changes + using the buttons at the top of the window. The library you selected will be used + for your integration from now on. + +5.3 Checklist + If you have followed this guide so far, you should now be able to run your inte- + gration to produce verification data from your target. To learn how to do so, see + Chapter 4 in the RVS User Guide. + + You may need to convert your raw data into an output format that RVS understands. + To learn how to do this, continue to Chapter 6: Converting data. + + +RVS Integration Guide vWF20190404 41 +This page intentionally left blank +6 Converting data + This chapter assumes that you have created an RVS project suitable for the pro- + gramming language of your source code and use with your build system and tar- + get. If you have not done this, we recommend that you learn how to by reading + Chapter 3: Getting started, Chapter 4: Integrating with a build system and Chap- + ter 5: Integrating with a target. + + Verification data that RVS analyzes may be stored in different formats. To allow + RVS to analyze your data, you may need to configure a strategy to convert raw + data into a suitable output format. + +6.1 Conversion strategies + To convert data into a suitable output format, one or more data converters should + be configured to apply a transform to the raw data. Data conversion could range + from a simple procedure such as removing spurious ipoints from the beginning + of a single trace file to a complex one involving sequential chains of converters + operating on multiple input files. + +6.2 Data converters + Each converter takes one or more input files and converts them into one or more + output files by using RVS filters or running external tools. Common operations + performed by converters include the following: + • Translating data from raw formats into formats suitable for RVS analysis + • Splitting raw data into multiple files or merging multiple input files into a single + output file + • Removing specific ipoints or sequences of them + • Replacing specific patterns of ipoints with others + + Figure 6.1 shows a simple example conversion strategy. + + +RVS Integration Guide vWF20190404 43 +Specifying data files and converters Converting data + + + Figure 6.1: Example conversion + + The input file in Figure 6.1 is a memory dump. The first and only conversion stage + uses a read filter to extract only RVS ipoint data from the memory dump. At this + point, the trace file can be used by RVS. + + We provide support for using RVS filters to convert your data. For more information + on RVS filters, see the RVS Filters Guide. If you want us to write filters to convert + the raw data collected from your target, contact support@rapitasystems.com. + +6.3 Specifying data files and converters + Before you can convert data to a suitable output format, you must first specify the + data files that you need to convert. To do this, follow the steps below: + 1. Open the project and select the Integration you want to specify data files + for in the RVS Project Manager. To change the active integration, use the + Active integration drop-down menu on the project overview page. + 2. Click Configure in the Actions section of the project overview page. + 3. Click Data Files on the sidebar to show a list of data files in the integration. + 4. When you first create an integration, RVS sets up a default data file. This is set + up based on the options you select when creating the integration. While the + default can be used for most on-host integrations, you may need to specify + different data files for on-target integrations. To do so, you can Edit the de- + fault data file, and Add new ones if necessary. + + +44 RVS Integration Guide vWF20190404 +Converting data Specifying data files and converters + + + 5. For each data file you specify, provide the path and name of the file on your + file system and the file format (see Chapter 5: Integrating with a target). In + most cases, you can leave the Target Metrics section as auto. + 6. Make sure to Save your changes. + + + Figure 6.2: Specifying data files + + After you have specified the data files created during your project, add converters + to apply to them by doing the following: + 1. On the page for the data file (nested under Data Files in your Integration), + click Add beside the Converters section. + 2. In the wizard that opens, type a Name for the converter, see Figure 6.3. If you + have already set up a converter and want to reuse it, select it from the drop- + down menu. This fills in the other fields on this page using the converter's + existing settings. + 3. If you are using an RVS filter to convert your data, select it from your file + system by using the Add button in the Filter File section. You can specify + multiple filters to use for each converter. In this case, filters are called in the + order shown in the Filter File list. + 4. If you are using an external tool to convert your data, provide the com- + mand-line arguments to run it in the External Command Lines section. + 5. Click Finish to add the new converter. + 6. Make sure you Save your changes before you Close the window. + + +RVS Integration Guide vWF20190404 45 +Checklist Converting data + + + Figure 6.3: Setting up converters + + Note + + We recommend that you do not enter settings for both RVS filters and ex- + ternal tools for a single converter. If your conversion strategy uses both of + these, we recommend that you set up multiple converters to implement it. + + +6.4 Checklist + If you have followed this guide so far, you should now be able to run your integra- + tion to produce and view verification data from your target. To do this, open your + RVS project in the RVS Project Manager and click Run in the Actions section of + the project overview page. + + +46 RVS Integration Guide vWF20190404 + Integrating with extended +7 programming languages + RVS can analyze code written in various standards of C and C++ programming + languages by default. For more information on the standards supported, see the + Rapita Systems Ltd. website. + + If your code is extended beyond common standards to include additional key- + words or functionality, RVS must be instructed how to analyze any non-standard + language features you may be using when parsing and instrumenting code. RVS + supports this through the use of compiler extensions, which you can add to your + project. + +7.1 Adding a compiler extension to your project + Note + + If you are using compiler wrappers to integrate RVS with your build sys- + tem, and are using a language extension for which support is already avail- + able, you do not need to add a compiler extension to your project – the RVS + compiler wrapper automatically adds any extensions needed based on your + compiler. + + + RVS installations include compiler extensions for many common compilers in the + RVS/integration_resources/compiler_extensions folder. + + To add a compiler extension to your project, do the following: + • Open your project in the RVS Project Manager. + • Click Configure in the Actions section of the project overview page. + • Click Advanced Configuration in the sidebar to the left of the window. + • Select the C Extensions or C++ Extensions entry. You can use the filter function + to find these more easily. + • Add the extension you need in the Value field. To add an ex- + tension, type the filename of the extension as it appears in + your RVS/integration_resources/compiler_extensions fold- + er, without the file extensions, e.g. ANSI, see Figure 7.1. + + To specify multiple compiler extensions, enter the extensions as a space-sep- + arated list. + • Save and Close your configuration using the buttons at the top-left of + the window. + + +RVS Integration Guide vWF20190404 47 + Integrating with extended programming lan- +Adding a compiler extension to your project + guages + + + Figure 7.1: Adding compiler extensions + + If you need us to develop support for the language features you're using, we'd be + happy to help you. Contact support@rapitasystems.com for more information. + + Important + + We recommend that you do not modify compiler extension files. If you do + so and you are qualifying RVS to use for producing certification evidence, + your qualification may be invalidated. + + +48 RVS Integration Guide vWF20190404 +8 Using the command-line + You can run RVS integrations from the command-line, for example by using the + RVS Shell command-line application included in RVS installations. You can + access this application on Windows systems from the Start menu (Start » RVS + » RVS Shell). + + Even when you run an RVS integration through the RVS Project Manager, it is run + using rvsdriver, which manages all of the back-end tools involved in RVS integra- + tions, see Section 2.2: Running an integration. + + For more information on using rvsdriver, see Chapter 12 in the RVS Command + Line Tools Reference Guide. + + +RVS Integration Guide vWF20190404 49 +This page intentionally left blank +9 Customizing integrations + RVS integrations are typically based on a standard workflow, as described in Sec- + tion 2.2: Running an integration This chapter describes how to customize RVS in- + tegrations to produce different functionality. + + You can customize RVS integrations in two main ways: + • Using custom recipes to run RVS integration stages in a different workflow. + • Editing the scripts called when RVS integration stages are invoked to cus- + tomize what happens during each RVS integration stage. + + These approaches to customizing integrations are described in the following sec- + tions. + +9.1 Custom recipes + You can specify custom recipes that use existing RVS integration stages but apply + these in a different workflow. + + Custom recipes support automation when using RVS. For example, you may spec- + ify a custom recipe that runs the RVS Build, Run and Report stages multiple times + to support integrations that collect data from multiple builds. You can run custom + recipes through both the RVS Project Manager and the command-line. + +9.1.1 Writing custom recipes + Custom recipes are script files that can be written in a variety of formats. + + This guide will not describe how to write these files. If you want assistance pro- + ducing custom recipes, contact support@rapitasystems.com. + +9.1.2 Adding custom recipes to RVS projects + To add a custom recipe to an existing RVS project, do the following: + 1. Open your project in the RVS Project Manager. + 2. Click Configure in the Actions section of the project overview page. + 3. Click Advanced Configuration in the sidebar to the left of the window. + 4. Select the Integration Recipe[+] entry, which is nested under Project. You + can use the filter function to find this more easily. + 5. In the New Item field, provide a name for the recipe you want to add, then + click Add. + 6. In the Recipe stages entry for the recipe you just added, provide the names + of the RVS integration stages that you may want to use the recipe in in the + + +RVS Integration Guide vWF20190404 51 +Custom recipes Customizing integrations + + + Value field, for example Prepare, Build or Report, see Section 2.2: Running + an integration. Setting Recipe stages is optional, but this will let you run the + recipe easily through the RVS Project Manager, see Section : Running cus- + tom recipes through the RVS Project Manager. + 7. In the Integration script entry, click Browse and select the script file you want + to use from your file system. + 8. Click Save and Close to save your changes and return to the RVS + Project Manager. + +9.1.3 Running custom recipes + You can run custom recipes through both the RVS Project Manager and the com- + mand-line (by using rvsdriver). + + Running custom recipes through the RVS Project Manager + + You can run custom recipes from the project overview page in the RVS Project + Manager if you have set valid Recipe stages for the custom recipe, see Sec- + tion 9.1.2: Adding custom recipes to RVS projects. + + When you have set a Recipe stage, it appears as an advanced option in the Actions + section of the project overview page, which you can access by clicking the + button. + + In Figure 9.1, for example, we have specified a recipe for the Run stage, MyCus- + tomRecipe. + + + Figure 9.1: Running custom recipes through the RVS Project Manager + + To run a custom recipe, click the button beside the action it is assigned to and + click the name of the recipe. + + Running custom recipes through the command-line + + To run a custom recipe through the command-line, call rvsdriver with the + --recipe option, as in the following example: + + +52 RVS Integration Guide vWF20190404 +Customizing integrations Editing RVS integration scripts + + rvsdriver --project MyRVSProject.rvsprj --recipe MyCustomRecipe + + +9.2 Editing RVS integration scripts + By default, when an RVS stage is invoked (see Section 2.2: Running an integration), + a script is called, see Section 2.2: Running an integration. These scripts determine + what occurs during that stage of an integration. The default scripts are written in + JavaScript, but scripts can be written in a variety of formats. The default integra- + tion scripts are located in the RVS/integration_resources/rvsdriver + folder, and have the same filename as the RVS integration stage during which they + are called, for example run.js. + + By default, run.js determines what occurs during the run hook of an inte- + gration. If you have a good understanding of JavaScript and the RVS integra- + tion workflow, you can write an alternative to use in place of this file. Alternative- + ly, you can write a script in another suitable scripting language to replace this + one. You can also add up to two additional scripts; one that runs before the + main script, and one that runs after. The js_builtins.html document in the + RVS/integration_resources/reference folder contains a reference of + built-in JavaScript functions that may be useful when setting up JavaScript files. + + Warning + + We recommend that you do not modify any of the default scripts included in + your integration library. + + To change the file that RVS uses during the run hook of an integration, do the + following: + 1. Open the project in the RVS Project Manager. + 2. On the project overview page, click Configure. + 3. Click Advanced Configuration. + 4. Scroll down in the table until you find the Run Script field and select it. + 5. Click Browse beside the Value field, locate and select the JavaScript file you + want to use, and click Open. + 6. Save and Close your changes using the buttons at the top of the + window. + + In the same way, you can add a file to run before or after the run hook by changing + the Run Prehook or Run Posthook settings. You can also change the Working folder + where the script executes commands; this defaults to the project's working folder. + + Just like you can for the run stage, you can customize what occurs during other + RVS stages such as clean and prepare by modifying the scripts run during them. + + +RVS Integration Guide vWF20190404 53 +This page intentionally left blank +10 Integration resources + RVS comes with many resources that are available to help inte- + grate RVS into a development environment. These are stored in the + RVS/integration_resources folder, which contains the following subfold- + ers: + • clone_scripts – scripts for the clone integration strategy, see Section 4.2: + Compiler wrappers. + • code_generators – scripts used to generate unit test code for RapiTest. + • compiler_extensions – scripts needed to use RVS to analyze code that + is built using compilers with specific extensions. + • compiler_wrappers – tools for the compiler wrapper integration strategy, + see Section 4.3: Clone integrations. + • map_templates – integration library templates for implementation of the + RVS map API on various platforms. + • plugins – plugins for running RVS with third-party tools. + • quoting_codecs – scripts needed to integrate RVS with various third-party + tools that use specific quoting mechanisms. + • reference – additional documentation about the integration workflow for + use by integrators (see below). + • scripts – scripts used by default for the various stages of RVS integrations. + • taskparser_os – resources for running RapiTask in OS-only mode. + • templates – scripts used by default for the various stages of RVS integra- + tions. + • test_converters – scripts used for converting RapiTest tests between + different formats. + + +RVS Integration Guide vWF20190404 55 + Integration resources + + + Integration reference documentation is stored in the + RVS/integration_resources/reference folder. This folder contains + subfolders and documents including the following: + • integration_annexes – this folder contains additional documentation + for integrations involving specific platforms. + • cext.html – this contains reference documentation for using RVS compiler + extensions. + • js_builtins.html – this contains a reference of built-in JavaScript func- + tions that may be useful when setting up integration scripts for use with RVS, + see Chapter 9: Customizing integrations. + • riclib_doc.html – this contains a reference of settings for RIClib, the + RVS integration API. Access to these settings is available via the RVS Config + Editor, particularly on the Advanced Configuration tab (see Section 4.11 in the + RVS User Guide). + • rvs_integrations.html – this contains a knowledge map that con- + tains information about integration concepts, terminology and the integration + process and includes examples and links to other documentation where ap- + propriate. + • rvsdriver_vars.html – this contains information about the variables + passed from rvsdriver to integration scripts. + • rvsdriver_workflow.png – this figure shows the rvsdriver integration + stages in more detail than the figure shown in Figure 2.3. + • tool_roles.html – this describes the purpose of some of the RVS com- + mand-line tools, in which hooks of an RVS integration they are used. For more + information on the RVS command-line tools, see the RVS Command Line Tools + Reference Guide. + + +56 RVS Integration Guide vWF20190404 +A Appendix +A.1 Integrating RVS with Ada projects + RVS must observe all of the source files in a project during the Prepare stage of + an integration. When integrating with Ada projects, RVS uses a common strategy + to observe these files, which is to read ADT files generated by a supported GNAT + compiler. These contain a tree-based representation of the source code structure, + which can be used for later analysis. If you are using a non-GNAT Ada compiler, + you will need to generate ADT files using a GNAT compiler during the Prepare + stage of your integrations. + + Note + + You only need to use a GNAT compiler during the Prepare stage of RVS in- + tegrations, you can use your normal compiler during the Build stage. + + Not all versions of GNAT can produce ADT files that can be read by RVS, as the + ADT file format changes between compiler versions. The versions of GNAT sup- + ported by RVS are: + • GNAT Pro 7.2 + • GNAT Pro 7.3 + • GNAT Pro 7.4 + • GNAT Pro 17 + • GNAT Pro 18 + • GNAT Pro 19 + • GNAT GPL 2014 + • GNAT GPL 2015 + • GNAT GPL 2016 + + The preferred versions to use with RVS are GNAT Pro 19 and GNAT GPL 2016, + as these contain some bugfixes to ADT generation not present in earlier versions. + However, if you are working with an older codebase, you may find earlier versions + of GNAT more compatible with your source code. + + RVS has limited support for the following legacy versions of GNAT: + • GNAT Pro 6.1 + • GNAT Pro 6.4 + • GNAT Pro 7.1 + + +RVS Integration Guide vWF20190404 57 +Integrating RVS with Ada projects Appendix + + + As described in Chapter 4: Integrating with a build system, two main strategies can + be used to integrate RVS with your build system: compiler wrapper and clone + strategies. + + RVS is shipped with the GNAT GPL 2014 compiler and a wrapper for this compiler. + If you can use this compiler with your system, or you already use a GNAT compiler + that has a compiler wrapper available, you can use the compiler wrapper strategy, + see Section 4.2: Compiler wrappers. This is preferable as it requires less modifi- + cation to your build system. If no wrapper is available for your compiler, but you + want us to add support for it, contact support@rapitasystems.com. + + If you cannot use a compiler wrapper strategy, you can use a clone strategy to + copy your source files and then process these using a GNAT compiler during + the Prepare stage of your integrations. This requires more extensive modifica- + tion to your build system than using a compiler wrapper strategy. For more in- + formation on the clone strategy, see Section 4.3: Clone integrations or contact + support@rapitasystems.com. + + The rest of this section describes some factors that should be considered when + generating ADT files with GNAT, depending on your existing build system: + • Section A.1.1 explains important factors when generating ADT files if your cur- + rent compiler is a GNAT compiler supported by RVS. + • Section A.1.2 explains important factors when generating ADT files if your cur- + rent compiler is a GNAT compiler that is not supported by RVS. + • Section A.1.3 explains important factors when generating ADT files if your cur- + rent compiler is not a GNAT compiler. + +A.1.1 Generating ADT files when the project is built using a + supported GNAT compiler + If your software is built using a supported GNAT compiler, the build process must + be changed so that it produces ADT files during the Prepare stage of an RVS + integration. These files are not normally produced during compilation. + + When gnatmake is used to invoke the build, ADT files can be generated by in- + cluding the -gnatt option on the gnatmake commandline: + Example A.1: Call to gnatmake including -gnatt option + gnatmake -gnatt ... sourcefile.adb + + + This is handled automatically by compiler wrappers but must be configured man- + ually when using a clone integration strategy. + +A.1.2 Generating ADT files when the project is built using an + unsupported GNAT compiler + If your software is built using a version of GNAT that is not supported by RVS, + you will need to use a supported GNAT compiler to generate ADT files. The build + + +58 RVS Integration Guide vWF20190404 +Appendix Integrating RVS with Ada projects + + + process must also be changed so that it uses this compiler to generate ADT files + during the Prepare stage of an RVS integration. + + The following sections describe factors that should be considered when switching + from an unsupported GNAT compiler to a supported one: + • Calling the GNAT compiler + • Modifying the GNAT search path + + Calling the GNAT compiler + + The build system must be modified so that it includes a call to the GNAT compiler + used to generate ADT files. This call should include the -gnatc option, which + stops the build process after the compilation stage. + + When gnatmake is used to invoke the build, add an additional call to the ADT + compiler's gnatmake with the -gnatt option to generate ADT files: + + Example A.2: Additional call to ADT gnatmake + + # Extra call to ADT gnatmake to generate ADT files + /path/to/supported/gnatmake -gnatt -gnatc sourcefile.adb + + # Original call to target gnatmake + gnatmake ... sourcefile.adb + + + This is handled automatically by compiler wrappers, but must be configured man- + ually when using a clone integration strategy. + + Modifying the GNAT search path + + If your source code requires a particular runtime or access to libraries that are not + supplied with the regular x86 version of GNAT, you may need to add the directo- + ries containing the appropriate package specification files to the ADT compiler's + search path. + +A.1.3 Generating ADT files when the project is built using a non- + GNAT compiler + If your software is built using a non-GNAT compiler, you will need to use a support- + ed GNAT compiler to generate ADT files. The build process must also be changed + so that it uses this compiler to generate ADT files during the Prepare stage of an + RVS integration. + + RVS is shipped with the GNAT GPL 2014 compiler, which you may be able to use + to generate ADT files. Alternatively, if you have access to it, we recommend that + you use GNAT Pro 17, or GNAT GPL 2016 if you do not have access to GNAT Pro. + + The following sections describe factors that should be considered when switching + to a GNAT compiler from a non-GNAT one: + + +RVS Integration Guide vWF20190404 59 +Integrating RVS with Ada projects Appendix + + + • Dealing with file names + • Calling a GNAT compiler + • Modifying the GNAT search path + + Dealing with file names + + GNAT compilers follow strict rules for defining the file names used for package + specifications, package bodies and separately-defined subprograms. GNAT as- + sumes that specifications are in files with .ads extensions, bodies and separates + are in files with .adb extensions, and that files are named based on the name of + the package or subprogram they contain. + + If your source code does not follow these naming conventions, you will need to + supply configuration pragmas to the GNAT compiler so that it can identify your + source files. These pragmas are passed to the compiler via a text file named + gnat.adc, which must be located in the current working directory. + + Configuration pragmas let you specify a systematic naming convention for file + names that correspond to specifications, bodies and subunits. For example, if your + codebase uses .ada files and discriminates between specifications and bodies + by prefixes _s and _b at the end of the file name, you can use the following + pragmas to allow GNAT to correctly identify your source files: + + Example A.3: Using configuration pragmas to read files + + pragma Source_File_Name (Spec_File_Name => "*_s.ada"); + pragma Source_File_name (Body_File_Name => "*_b.ada"); + + + If your codebase does not use a systematic naming convention, you will need + to supply a configuration pragma for each unit, indicating which source files con- + tain the relevant specification and body code, for example by using the following + pragmas: + + Example A.4: Using configuration pragmas to read files: extended + + pragma Source_File_Name (My_Units.Stacks, Spec_File_Name => + "myunitst_a.ada"); + pragma Source_File_name (My_Units.Stacks, Body_File_Name => + "myunitst.ada"); + + + Alternatively, you can use the gnatchop tool to automatically produce input files + with file names that can be understood by GNAT, without overwriting the original + files. If your code is structured with package specification and body in the same + file, you will need to use gnatchop to create input files that can be understood + by GNAT. + + For more information on GNAT configuration pragmas and to learn how to use + gnatchop, see the GNAT User Guide. If you need help generating GNAT-compat- + ible file names for use with RVS, contact support@rapitasystems.com. + + +60 RVS Integration Guide vWF20190404 +Appendix Integrating RVS with Ada projects + + + Calling a GNAT compiler + + The build system must be modified so that it includes a call to the GNAT compiler + used to generate ADT files. This call should include the -gnatc option, which + stops the build process after the compilation stage. + + When gnatmake is used to invoke the build, add an additional call to the ADT + compiler's gnatmake with the -gnatt option to generate ADT files: + + Example A.5: Additional call to ADT gnatmake + + # Extra call to ADT gnatmake to generate ADT files + /path/to/supported/gnatmake -gnatt -gnatc sourcefile.adb + + # Original call to target gnatmake + gnatmake ... sourcefile.adb + + + This is handled automatically by compiler wrappers, but must be configured man- + ually when using a clone integration strategy. + + Modifying the GNAT search path + + If your source code requires a particular runtime or access to libraries that are not + supplied with the regular x86 version of GNAT, you may need to add the directo- + ries containing the appropriate package specification files to the ADT compiler's + search path. + + +RVS Integration Guide vWF20190404 61 +Using different integration strategies in a single + Appendix +RVS integration + +A.2 Using different integration strategies in a single + RVS integration + Sometimes, you may need to use different integration strategies in the Prepare + and Build stages of an RVS integration. + + By default, RVS uses the Integration Strategy specified when creating an RVS + project using the New RVS Project Wizard for both the Prepare and Build stages. + + You can specify a different strategy to use for the Prepare stage by doing the + following: + 1. Open the project in the RVS Project Manager. + 2. Click Configure in the Actions section of the project overview page. + 3. Click Advanced Configuration in the sidebar to the left of the window. + 4. Using the search bar in the middle of the page, search for Prepara- + tion strategy. + 5. Select the Preparation strategy for the integration you want to modify and + change the contents of the Value field to either wrapper or clone. + + +62 RVS Integration Guide vWF20190404 + Working with limited resources: RapiTime and +Appendix + RapiTask + +A.3 Working with limited resources: RapiTime and + RapiTask + If your target hardware has resource constraints, you may need to make special + considerations when using RapiTime or RapiTask to collect data from it. This chap- + ter describes how you can work around various resource constraints that your tar- + get hardware may have: + • Section A.3.1: Working with limited data memory describes considerations + when using RapiTime or RapiTask on targets with limited available data mem- + ory. + • Section A.3.2: Working with limited code memory describes considerations + when using RapiTime or RapiTask on targets with limited available code mem- + ory. + • Section A.3.3: Working with limited CPU time describes considerations when + using RapiTime or RapiTask on targets with limited available CPU time. + • Section A.3.4: Working with limited data collection bandwidth describes con- + siderations when using RapiTime or RapiTask on targets with limited available + bandwidth for data collection. + +A.3.1 Working with limited data memory + If you are using an in-memory trace, sufficient data memory must be available to + store the trace. The amount of memory needed depends on how much code you + are analyzing (the size of the analysis scope) and the instrumentation applied to + your code. + + If you do not have enough data memory available to store a trace, you can do + the following: + • Reduce the size of your analysis scope and/or the depth of instrumentation – + To learn how to do so, see Section 9.2 in the RapiTime User Guide. This will + reduce the number of instrumentation points executed during the test so less + data memory is required. + • Generate timing data incrementally by instrumenting parts of the software at + once, rather than the entire application, and merging results into a final report + later. See Section 9.10 in the RapiTime User Guide to learn how to do this. + • Use an IO trace or address trace to collect data rather than an in-memory trace + (if supported by the target platform). These data collection mechanisms does + not require data memory to be available. For more information on RapiTime + and RapiTask data collection strategies, see RapiTime and RapiTask. + • Use an in-memory trace of a fixed size which is periodically dumped to an IO + port, allowing a smaller buffer to be used. It will be necessary to consider the + execution time overheads of dumping the trace, and how frequently the trace + needs to be dumped, to understand the impact of this approach. + + +RVS Integration Guide vWF20190404 63 +Working with limited resources: RapiTime and + Appendix +RapiTask + +A.3.2 Working with limited code memory + Each instrumentation point added by RapiTime or RapiTask incurs a code memory + overhead. If the amount of code memory available is insufficient, you can do the + following: + + • Reduce the level of instrumentation. If it is acceptable to the specific situation, + selecting a lower level of instrumentation will reduce the number of instrumen- + tation points generated. + • Generate timing data incrementally by instrumenting parts of the software at + once, rather than the entire application, and merging results into a final report + later. See Section 9.10 in the RapiTime User Guide to learn how to do this. + • Call, rather than in-line, instrumentation points. Normally it is recommended + that instrumentation points are inlined functions or macros, as this helps to + maximize performance. However, if the number of machine instructions in the + instrumentation point is larger than the number of instructions to call a function, + the amount of code memory required can be reduced by calling the function + instead. + • Optimize the instrumentation point functions to minimize the number of ma- + chine instructions they use. Depending on the system, it may be possible to + reduce the size of the code required for instrumentation points by making use + of inline assembly code. + • Use an IO trace or an address trace if supported by the target platform, see + RapiTime and RapiTask. This means that instrumentation points can normally + be implemented using a small number of instructions (possibly one), to write + a constant value to a known address/IO port. + +A.3.3 Working with limited CPU time + If the application is time-constrained (for example, if it must complete within one + frame of a partitioned RTOS, or if it must respond before a watchdog times out) the + additional execution time introduced by instrumentation may cause timing prob- + lems. If timing problems are encountered, the following actions can be taken: + + • Reduce the level of instrumentation. If it is acceptable to the specific situation, + selecting a lower level of instrumentation will reduce the number of instrumen- + tation points generated, and therefore reduce the number of times the instru- + mentation point function must be executed. + • Generate timing data incrementally by instrumenting parts of the software at + once, rather than the entire application, and merging results into a final report + later. See Section 9.10 in the RapiTime User Guide to learn how to do this. + • Avoid instrumenting commonly-called functions. This avoids the problem + where a single function is called many times (and consequently the execution + time of a test case includes many instances of this function’s instrumentation). + • Ensure instrumentation points are in-lined rather than called. + + +64 RVS Integration Guide vWF20190404 + Working with limited resources: RapiTime and +Appendix + RapiTask + + • Optimize the instrumentation point functions to minimize the number of ma- + chine instructions they use. Depending on the system, it may be possible to + reduce the size of the code required for instrumentation points by making use + of inline assembly code. + • Use an IO trace or an address trace if supported by the target platform, see + RapiTime and RapiTask. This means that instrumentation points are normally + implemented using a small number of instructions (possibly one), to write a + constant value to a known address/IO port. + +A.3.4 Working with limited data collection bandwidth + An important part of RapiTime or RapiTask's integration with a target is the col- + lection of data from the target to the host. There are a number of circumstances + where the bandwidth of the connection between the host and the target can have + an impact on the data collection process: + + • The IO trace uses a port with a limited number of pins. In some cases, the + number of IO pins that can to be used for tracing purposes are limited. In this + situation, you can use the IdPack feature to reduce the number of bits needed + for instrumentation, see Section . + • The IO trace uses a slow port. If the IO trace is connected to a port that is + running much slower than the processor, it is possible that several instrumen- + tation points close to each other may cause problems. In this case, it may + be necessary to remove some of the instrumentation to increase the time be- + tween the execution of consecutive instrumentation points. + • The communications channel used to download blocks of data is slow. In this + situation, it may be possible to compress the blocks of data on target before + transmitting them back to the host. RVS uses a proprietary data compression + algorithm (which generates .rpz files). If you require a target-specific library + to carry out this compression, please contact support@rapitasystems.com. + + Reducing the number of bits required for instrumentation + + Sometimes, target hardware has a limited number of output pins that can be used + for tracing purposes. To ensure that the instrumentation can be reported via these + pins, there are three approaches that can be taken. In order of increasing com- + plexity, these are: + • Reducing the instrumentation identifier space via the --nbits option for the + instrumenter. + • Automatically reallocating the instrumentation identifier space with IdPack + rewriting or remapping. + • Manually reallocating the instrumentation identifier space with IdPack config- + uration. + + The following sections describe these approaches. + + +RVS Integration Guide vWF20190404 65 +Working with limited resources: RapiTime and + Appendix +RapiTask + + Reducing instrumentation identifier space with --nbits + When code is instrumented, the RVS instrumentation tools must allocate an iden- + tifier to each inserted instrumentation point. The policy used for the allocation of + ipoint IDs depends on whether the instrumentation requires that ipoint IDs are + unique across the entire system, or whether they can be reused across different + functions. The use of unique ipoint IDs is specified with the -u option to the in- + strumenter. + + In general, the use of a coverage map requires unique ipoint IDs, whereas with + trace data the execution of specific functions can be inferred from the ordering of + ipoints within the trace. Table A.1 shows the ipoint allocation policy where unique + ipoints are required, and Table A.2 shows the policy for non-unique ipoints. + + Table A.1 Ipoint allocation (unique ipoints specified) + + Value Purpose + 0 Unused + 1-9 Reserved for special purposes in manual instrumentation. + n + 10 to 2 -1 Master ipoints. Unique IDs allocated to all instrumentation points. + + + Table A.2 Ipoint allocation (non-unique ipoints) + + Value Purpose + 0 Unused + 1-9 Reserved for special purposes in manual instrumentation. + 10 to X Non-master ipoints. Allocated to instrumentation points within + functions and re-used between different functions (starting at 10 + and working upwards to X). + n + Y to 2 -1 Master ipoints. Unique IDs allocated to function entry and exit + n + points (starting at 2 -1 and working downwards to Y). + + Where non-unique ipoint IDs are used, the value of X (as shown in Table A.2) is + the number of ipoints required to instrument the most complex function. Where + the instrumentation policy for the entire application is FUNCTIONS, X will be 10 + (i.e. there are no non-master ipoints). The value of Y depends on the number of + function entries and exits. In order for the instrumentation to succeed, the range + of master ipoints and the range of non-master ipoints must not overlap, i.e. the + value of X must be less than the value of Y. + + The upper limit on the value of ipoint IDs can be set by the --nbits option, + passed to the instrumenter (cins, cppins or adains). The value of the --nbits + option should be set to the number of output pins available on the target. Providing + the ipoint ranges do not overlap, the instrumentation will be successful. Should an + overlap occur, RVS will return an error message. The default value of the --nbits + option is 16. + + +66 RVS Integration Guide vWF20190404 + Working with limited resources: RapiTime and +Appendix + RapiTask + + Automatic ipoint reallocation with IdPack + RVS provides the IdPack feature to reduce the number of IDs required for a specific + application. It does this by removing the distinction between master ipoints and + non-master ipoints. + + There are two stages to automatically reallocate ipoint IDs with IdPack: + 1. Allocate unique ipoint identifiers to the application, using the -u and + --nbits options during instrumentation (Example A.6). + 2. Reallocate the identifiers, either by rewriting the instrumented source code + (Example A.7), or by means of a mapping file (Example A.8). + Example A.6: Allocating unique ipoint IDs for IdPack + + cins --exf build.exf -c rvs_instr.h -d build -u --nbits 31 -l + files.txt + + + After the instrumenter has generated unique ipoint identifiers, these are reallocated + into the reduced identifier space by xstutils. There are two methods for reallocating + identifiers: + • Rewriting. The parameters of the ipoint calls in the instrumented source code + are rewritten into the IdPacked range of values. This approach is recommend- + ed, as it results in fewer files being recompiled when changes occur. + • Remapping. The reallocation of instrumentation identifiers is done in a sepa- + rate file, which must be included by all instrumented source files. + + In both cases, the number of output pins (i.e. the number of bits available) is + passed to xstutils via the --idpack-nbits option. By default, IdPack observes + the reserved range of identifiers (0 to 9). This can be overridden to add additional + values to the range of permitted identifiers using the --idpack-start option. + + To create the .rvd using the rewriting approach, a list of instrumented files needs + to be created which is then passed to xstutils using to the --ipoint-rewrite + option (Example A.7). + Example A.7: Rewriting ipoint IDs with IdPack + + xstutils -r my_root *.xsc -o my_root.rvd --ipoint-rewrite + instr_files.txt --idpack-nbits 7 + + + Using the remapping approach, the rvs_ipoint.h header file needs to include + a remap file, which is produced by xstutils using the command shown in Exam- + ple A.8 + Example A.8: Generating an ipoint remapping file with IdPack + + xstutils -r my_root *.xsc -o my_root.rvd --ipoint-remap remap.h -- + idpack-nbits 7 + + +RVS Integration Guide vWF20190404 67 +Working with limited resources: RapiTime and + Appendix +RapiTask + + Where ipoint IDs are modified by either rewriting or remapping, the instrumented + source code must be compiled after the xstutils command has been executed. + + Using IdPack on multiple roots + When it is necessary to analyze multiple root functions but also use IdPack func- + tionality, all the required root functions must be specified on the initial run of xs- + tutils to avoid recompilation. This is because the mapping between the original + ipoint IDs and the IdPacked ones is only valid for the specified root functions; all + ipoints that cannot be reached by the root functions are removed. Thus, if it is later + necessary to analyze a new root function (not originally specified on the xstutils + command line), a new IdPack remapping must be generated using xstutils and + the instrumented code then recompiled. + + When xstutils is executed with the IdPack options and with more than one -r + option it: + 1. Generates an IdPack mapping suitable for all root functions. + 2. Generates one .rvd file per root. The names of the rvd files follow the + format..rvd. + + Note + + Since there are several .rvd files, one for each root, processing of the + trace data file must either be done: + • By running timeparser with the trace data file on each individual.rvd. + • By first splitting the trace data file into a number of files (using traceuti- + ls) and then processing each (spawned) trace data file with the relevant + .rvd file using timeparser. + + + Advanced IdPack usage + Sometimes the number of bits available to write ipoint IDs is not sufficient to in- + strument the entire source code. In these cases, use the --idpack-cfg option + to xstutils, which inserts calls to a tailored ipoint routine depending on the number + of bits required to output the ipoint ID. The ipoint routine can be tailored to output + ipoint IDs to a fast or slow output port, or to initiate multiple writes to allow larger + ipoint IDs to be built up from a sequence of smaller values. + + For example, assume that you plan to record the trace data using an output port + and that you need 1000 different ipoint IDs to instrument the source code, but only + 7 bits are available on the output port. The way to record 1000 different values + from a 7-bit output port is to do multiple writes to the output port. + + To do this, you should define two ipoint routines: a short type (RVS_I_Short) for + values 1 to 127 (which can be coded in 7 bits), and a long type (RVS_I_Long) for + values 128 - 1000. Whenever it is executed, RVS_I_Short results in one write + of 3 bits (for example RVS_I_Short(4) = write 0x4). And when RVS_I_Long + + +68 RVS Integration Guide vWF20190404 + Working with limited resources: RapiTime and +Appendix + RapiTask + + is executed it results in two writes: a zero followed by a 3-bit value(for example + RVS_I_Long(9) = write 0x0 then 0x2). With the correct configuration to xstutils, + the source code is instrumented using RVS_I_Short as often as possible to + keep the number of multiple writes low. + + The --idpack-cfg option allows you to control the IdPack feature via an IdPack + configuration file, which instructs xstutils to produce several types of ipoint and to + use them in a priority ordering (i.e. try to use the short ones most often). + + In the IdPack configuration file, you specify groups of ipoints, and you associate + with each group a range of permissible ipoint IDs together with a name which is + appended to the ipoint routine in the source code (to distinguish this group from + the others). + + The IdPack configuration file is a text file that must comply with the following gram- + mar: + FILE: UNCHANGED? GROUP+ + UNCHANGED: '[' 'unchanged' ']' RANGEID NAME? + GROUP: '[' 'group' ID ']' RANGEID NAME? UNIQIDS? + RANGEID: 'range' '=' RANGEDEF + NAME: 'name' '=' STRING + UNIQIDS: 'uniq_ids' '=' BOOL + BOOL: 'TRUE' + | 'FALSE' + STRING: '"' [a-zA-Z_]+ '"' + ID: [a-zA-Z_][a-zA-Z_0-9]* + RANGEDEF: SET + | RANGE + | '(' RANGEDEF ')' + | RANGEDEF '-' RANGEDEF + | RANGEDEF '+' RANGEDEF + SET: '{' NUM {',' NUM}* '}' + RANGE: '[' NUM '..' NUM ']' + NUM: DIGIT DIGIT* + DIGIT: '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' + where: + • Each non-terminal symbol appears in upper case. For example, FILE and SET + are both non-terminals. Repetitive non-terminal symbols are enclosed in brace + brackets {}. + • Each terminal symbol is enclosed between single quotes. For example, '+' + represents the character literal +. + • * matches the preceding element zero or more times. + matches the preced- + ing element one or more times. ? matches the preceding element zero or one + time. + • Character classes are enclosed between square brackets []. For example, [a- + z] specifies a range which matches any lower-case character from 'a' to 'z'. + + The grammar permits an optional group of ipoints to be specified as unchanged, + indicating that xstutils will not remap any ipoint IDs in the specified range. Typically, + this is needed when particular ipoints are used to instrument interrupts or the OS. + + +RVS Integration Guide vWF20190404 69 +Working with limited resources: RapiTime and + Appendix +RapiTask + + Warning + + Unchanged ipoints must be placed manually in the source code before + cins runs. + + + xstutils uses the order that the (other) groups appear in the IdPack configuration + file as the priority it should employ when searching for a remapped ipoint ID. For + example, if it cannot find a suitable remapped ipoint ID from the range specified + by the first group then it continues onto the second group, and so on. + + The grammar also permits a group of ipoints to have unique remapped IDs (indi- + cated by uniq_ids = TRUE), which is needed for black-boxed functions and + master ipoints of root functions. At least one group must be selected for unique + IDs (it is possible to select several groups). As the number of unique IDs required + is usually low, the group selected for unique IDs is usually the most expensive one. + + Note that the ipoint IDs of all groups should be disjointed. If an ID is present in + multiple groups, a warning will be issued and the ID will be assigned to the first + group in the file in which it appears. + + Example use of --idpack-cfg option + + Assume that you have the following requirements on remapped ipoint IDs: + • Ipoint IDs between 500 and 510, except 505 and 506, are reserved for instru- + mentation of interrupts and the OS. This is the first group of ipoint IDs. + • Availability of a 3-bit output port to which ipoint IDs are written. Therefore, val- + ues in the range 1 to 7 can be written in a single write (0 is a reserved ipoint + ID and cannot be used) and should be used as often as possible. This is the + second group of ipoint IDs. + • When ipoint IDs from the second group are not sufficient for the remapping, + two writes can be used (a 0 followed by a value from 1 to 7), allowing values + between 8 and 14. This is the third group of ipoint IDs. + • When ipoints IDs from any other group are not sufficient for the remapping, + use values between 1 and 511, except for those used by the other groups. + This requires 5 writes (two 0 and then three values from 1 to 7). This is the + fourth group of ipoint IDs. + + Also use values from this group whenever a unique ipoint ID is needed (this is + indicated by the line uniq_ids = TRUE). + + These requirements are met using the configuration file shown in Example A.9 + + +70 RVS Integration Guide vWF20190404 + Working with limited resources: RapiTime and +Appendix + RapiTask + + Example A.9: Example IdPack configuration file + + # 1/ Unchanged ipoints + [unchanged] + range = [500..510] - {505, 506} + name = "OS" + + # 2/ Short ipoints (One 3-bit write) + [group short] + range = [1..7] + name = "Short" + + # 3/ Long ipoints (Two 3-bit writes) + [group long] + range = [8..14] + name="Long" + + # 4/ Very_Long ipoints (Five 3-bit writes) + [group very_long] + range = (([1..511] - [1..14]) - [500..510]) + {505, 506} + name="Very_Long" + uniq_ids = TRUE + + + Note that, during the remapping performed by xstutils, the ipoint routine in the + source code is appended with the name specified by the group. For example, + if the remapped ID of an ipoint is taken from the fourth group, then the ipoint + routine appears as RVS_I_Very_Long in the source code once xstutils has + completed. + + The command line for xstutils that uses this configuration file is shown in Exam- + ple A.10. + + + Example A.10: Using xstutils with an IdPack configuration file + + xstutils -r my_root *.xsc -o my_root.rvd--ipoint-rewrite + files_instr3bits.txt --idpack-cfg my_idpack.cfg + + + Example A.11 shows a source code section to which this remapping has been + applied: + + +RVS Integration Guide vWF20190404 71 +Working with limited resources: RapiTime and + Appendix +RapiTask + + Example A.11: Source file instrumented using --idpack-cfg + + ... + int + my_fun(unsigned int x) + {RVS_I_Very_Long(511) ;{ + int choice, r; + + if (x>6) {RVS_I_Long(13) ;{ + choice = 6; + }} else {RVS_I_Short(1) ;{ + choice = x; + }} + + switch (choice) { + case 0 :RVS_I_Short(6) ; r = 5; + case 1 :RVS_I_Short(7) ; r = 6; + case 2 :RVS_I_Long(11) ; r = 7; + case 3 :RVS_I_Long(9) ; r = 15; + case 4 :RVS_I_Short(2) ; r = 16; + case 5 :RVS_I_Short(4) ; r = 17; + case 6 :RVS_I_Short(3) ; r = 50; + break; + default : RVS_I_Short(5) ;} + + if (buffer_full ()) {{ + /* Manual Ipoint added by user with ID 500 */ + RVS_I_OS(500) ; + }}else {RVS_I_Short(7) ;} + + {RVS_I_Very_Long(506) ;return r;} + }} + ... + + + In this instrumented source code, all ipoint groups are used. ipoints 511 and 506 + are from the 'Very_Long' group because they must be unique (entry/exit of the root + function), which was specified in the configuration file. Ipoints 1 to 7 ('Short') were + not sufficient to instrument the source code, therefore 'Long' ipoints have been + used as well. Finally, ipoint 500 (which was manually added) is allocated to the + 'OS' group and its value is left unchanged. + + IdPack Caveats + After using the IdPack options, master ipoint IDs will no longer be unique. With + fewer bits, the same ID is typically repeated many times in an .rvd file. This makes + it difficult to manually follow the source code path represented by an execution + trace. However, timeparser is able to easily follow the path represented by the + trace data. In case of a parsing error being detected by timeparser, the error + message displayed identifies ipoints using their IDs (which are not unique) and + their position in the source code (file name and line number, which is unique). + + Since the master Ipoints are no longer unique, you can no longer use the + --discover-fptr option with timeparser. Instead, you must provide explic- + it call_to annotations to resolve function pointers. See Section 8.1 in the RVS + Annotations Reference Guide for details on how to use these annotations. + + +72 RVS Integration Guide vWF20190404 + Working with limited resources: RapiTime and +Appendix + RapiTask + + Note + + Debugging unresolved function pointer destinations is significantly more + difficult when an integration uses IdPack. It is strongly recommended that + you resolve all function pointer destinations and provide appropriate anno- + tations before enabling IdPack. + + The IdPack options ensure that some special ipoints still have a unique ID. These + special ipoints are: the entries and exits of the root function(s) and the ipoints + added by the black_box annotation (see Section 7.2 in the RVS Annotations + Reference Guide). The unique IDs used for these ipoints start at 10 by default (this + can be changed using the --idpack-start option). + + +RVS Integration Guide vWF20190404 73 +This page intentionally left blank + diff --git a/docs-extracted/src/scov/RVS/doc/Migration_Guide.md b/docs-extracted/src/scov/RVS/doc/Migration_Guide.md new file mode 100644 index 000000000..21fd0a1bb --- /dev/null +++ b/docs-extracted/src/scov/RVS/doc/Migration_Guide.md @@ -0,0 +1,1506 @@ +--- +title: "Migration Guide" +source: "./src/scov/RVS/doc/Migration_Guide.pdf" +category: "src/scov/RVS/doc" +pages: 38 +extracted: "2026-07-06T23:13:31.620591" +--- + +# Migration Guide + +> Extracted from `./src/scov/RVS/doc/Migration_Guide.pdf` (38 pages). +> Figures, diagrams, and tables may not render accurately in plain text. + +Migration Guide + Version WF20190404 +Disclaimer +The information, text, and graphics contained within this document are +provided for information purposes only by Rapita Systems Ltd. Rapita +Systems Ltd. does not warrant the accuracy or completeness of the +information, text, and other items contained in this document. + + +Copyright and Trademarks +All rights reserved. Information and images contained within this doc- +ument are copyright and the property of Rapita Systems Ltd. All trade- +marks are hereby acknowledged to be the properties of their respective +owners. + + +Acknowledgments +Rapita Systems' tools are built using AdaCore's GNAT Pro compiler. + + +Rapita Systems Ltd. +Registered in the UK, number 5011090. +Registered address: +Atlas House +Link Business Park +Osbaldwick Link Road +York +YO10 3JB +UK +Phone: +44 (0) 1904 413 945 +http://www.rapitasystems.com/ +This document copyright © 2011-2019, Rapita Systems Ltd. + +Document build 118520 + +ID: DOC/12006 + Table of Contents + +1. RVS versions .................................................................... 5 + +2. General migration considerations ..................................... 6 + +3. Migrating from v3.7 to WF20190404 .................................. 8 + 3.1. New features ...................................................................... 8 + + 3.2. Changed features ................................................................. 8 + + 3.3. Deprecated features ............................................................ 10 + + 3.4. Removed features ............................................................... 10 + + +4. Migrating from RapiTest v1.4a ......................................... 11 + 4.1. Changed features ............................................................... 11 + + +5. Migrating from v3.6 to v3.7 ............................................. 13 + 5.1. New features ..................................................................... 13 + + 5.2. Changed features ............................................................... 14 + + 5.3. Deprecated features ............................................................ 17 + + 5.4. Removed features ............................................................... 17 + + +6. Migrating from v3.5 to v3.6 ............................................. 18 + 6.1. New features ..................................................................... 18 + + 6.2. Changed features ............................................................... 18 + + 6.3. Deprecated features ............................................................ 19 + + 6.4. Removed features ............................................................... 19 + + +7. Migrating from v3.4 to v3.5 ............................................. 21 + 7.1. New features ..................................................................... 21 + + + 3 +Migration Guide Migration Guide + + + 7.2. Changed features ............................................................... 22 + + 7.3. Deprecated features ............................................................ 23 + + 7.4. Removed features ............................................................... 23 + + + 8. Migrating from v3.3 to v3.4 ............................................. 24 + 8.1. New features ..................................................................... 24 + + 8.2. Deprecated features ............................................................ 26 + + + 9. Migrating from v3.2 to v3.3 ............................................. 27 + 9.1. New features ..................................................................... 27 + + 9.2. File format modifications ....................................................... 28 + + 9.3. Deprecated features ............................................................ 29 + + + 10. Migrating from v3.1 to v3.2 ............................................ 30 + 10.1. New features ................................................................... 30 + + 10.2. Deprecated features ........................................................... 31 + + 10.3. Annotations ..................................................................... 31 + + 10.4. Command line tools ........................................................... 33 + + + 11. Migrating from v3.0 to v3.1 ............................................ 35 + 11.1. Instrumentation library ......................................................... 35 + + 11.2. Command line tools ........................................................... 36 + + 11.3. Integration ....................................................................... 37 + + + 4 +1 RVS versions + Rapita Systems Ltd. releases new versions of RVS regularly. Users are encouraged + to update in order to gain access to new features and ensure that they are up to + date with bug fixes and other improvements. + + Releases fall into one of three categories: + • Major release (.0 - for example 3.0). These releases contain significant + new functionality and may have considerable changes from previous versions. + • Minor release (. - for example 3.6). These releases contain new + tools and features but the behavior remains broadly the same as the previous + version. + • Incremental release (. - for example 3.6a). These releases only + contain bug fixes. + + New major and minor versions may add, remove or change the behavior of some + tool features. When you upgrade to a new major or minor version, you may need + to change your integration if it uses options or features that have been modified. + This guide contains information about the changes that you need to make to your + integration as part of the update process, and includes general considerations + (in Chapter 2: General migration considerations), as well as a series of chapters + describing migration between specific RVS major and minor versions. + + Incremental releases do not introduce new features or make changes to tool be- + havior, so you do not need to make changes to upgrade to the latest incremental + release if it is based on the same major/minor version as your current release. + + Note + + In some cases (for example to test a fix for a reported bug) we may supply + wavefront or bugfix releases outside the official release cycle. These releas- + es are for testing purposes only and are not intended for production use. + + You should not continue to use a wavefront or bugfix version after an official + release containing the required functionality has been released. Rapita Sys- + tems Ltd. is unable to provide support for unofficial versions after this point. + + Any results or intermediate files generated with wavefront or bugfix releases + should be used for testing purposes only and should be deleted and regen- + erated with an official version when it is available. Rapita Systems Ltd. can- + not guarantee that any files generated with unofficial releases will be com- + patible with future official versions. + + + 5 + General migration +2 considerations + When upgrading to a later version of RVS, you may need to perform steps to + migrate your integration such that it is compatible with the new version. + + Important + + During the migration process, you may need to copy files from your existing + installation to the version you are upgrading to. + + As such, when installing a new version of RVS on your file system, it is im- + portant to make sure that you do not uninstall the version you are upgrading + from until you have finished the migration process. + + + Changes to some RVS file types and workflows may occur frequently between + different RVS versions. These are listed below, along with migration considerations + related to them: + • RVS project files – the schema for RVS project files (which have the .rvsprj + extension) may change between major, minor or incremental versions. When + opening a project file with an earlier version in the RVS Project Manager, you + will be asked if you want to upgrade the file to the latest version. Files must + be upgraded to the latest project file version before they can be used. Once + upgraded, files may not be backwards-compatible with earlier versions. + • Instrumentation – the placement of instrumentation points (i.e. the number of + instrumentation points and their locations) may change between major, minor + or incremental versions. + • RVD file format – the RVD file's internal database schema may change be- + tween major, minor or incremental versions. Files generated with earlier ver- + sions will be automatically upgraded when they are opened in the RVS Project + Manager or modified by command line tools. Once upgraded, the files may + not be backwards-compatible with earlier versions. New features introduced + with major or minor versions may require the RVD file to contain information + that may not be present in RVD files that were generated with an earlier ver- + sion. If you wish to use new features, it is recommended that you regenerate + your RVD files using the new version. + • Justifications – the justification XML schema may change between major, mi- + nor or incremental versions. Files generated with earlier versions are automati- + cally upgraded when they are opened in the RVS Project Manager or modified + by command line tools. Once upgraded, the files may not be backwards-com- + patible with earlier versions. + + + 6 +General migration considerations General migration considerations + + + • XSC files – the XSC file format may change between major, minor or incre- + mental versions. Files generated using earlier versions should be deleted and + re-generated using the new version. + • EXF (exchange) files – the exchange file format may change between major, + minor or incremental versions. Files generated using earlier versions should + be deleted and re-generated using the new version. + + Guidance for migrating between specific RVS versions is provided in the follow- + ing chapters. If you have any questions during the migration process, contact + support@rapitasystems.com, who will be happy to help you. + + + 7 + Migrating from v3.7 to +3 WF20190404 + This chapter highlights the changes and enhancements made to RVS since the + last release. + + Note + + This section describes changes that are being made during active develop- + ment of RVS and are subject to change without notice prior to the official re- + lease of the next version. + + +3.1 New features +3.1.1 RapiTest is now part of RVS + RapiTest is now part of RVS. For information on migrating from RapiTest v1.4a to + WF20190404, see Chapter 4: Migrating from RapiTest v1.4a. + +3.1.2 Support for new GNAT compilers + Support for the following GNAT compilers has been added: + • GNAT Pro 18 + • GNAT Pro 19 + +3.1.3 New C/C++ parser + We have introduced a new C/C++ parser, which is used by default in RVS inte- + grations. In most cases, no changes to your integration will be needed except in + the following cases: + • If you use custom CEXT files you may need to rewrite them, see the RVS Inte- + gration Guide for details. + • If you have a manual integration and call the RVS instrumenters from a different + directory to the one from which you call your compiler to preprocess source + code, you may need to update your integration to use the --working-dir + option of cins/cppins, see the RVS Command Line Tools Reference Guide. + +3.2 Changed features +3.2.1 Python support in RVS + RVS includes Python to support the use of trace filters and integration scripts. We + have updated the version of Python that we use from Python 2.7 to Python 3.6. + + + 8 +Migrating from v3.7 to WF20190404 Migrating from v3.7 to WF20190404 + + + Any existing Python trace filters or scripts that are run through RVS tools that use + Python 2.x specific constructs will need to be updated. + + Due to this change, Python is no longer supported out-of-the-box on Windows + XP/Windows Server 2003. If you cannot upgrade to a newer version of Win- + dows and currently extend RVS using Python filters or scripts, please contact + support@rapitasystems.com for help. + +3.2.2 Command-line handling + We have changed how RVS handles command-lines to improve the robustness + of integrations. While RVS previously interpreted command-lines, it now passes + them directly to the system shell. + + As a result of this change, command-lines that previously ran correctly may need + updating. In most cases, this update will be handled automatically when affected + project files are upgraded. In some cases, however, you may need to review com- + mand-lines to ensure that they are valid for running on your system. + +3.2.3 Coverage exports + We have updated coverage export files: + • They now include information on coverage options that may affect your results. + • Elements that used to be listed as Not Instrumented are now listed as + Unknown, and no longer include addressed items. + If you use scripts to analyze coverage export files, you may need to update your + scripts to be compatible with new exports. + + Additionally, if you analyze the coverage options used to produce results, you may + find it more efficient doing this from coverage exports rather than whatever means + you currently use to do so. + +3.2.4 Parsing of ADT files + We have changed the default behavior of ADT analysis to only analyze the first + source file in each ADT file. Previously, this behavior needed to be specified by + using the --first-unit-only option of adains, which has now been depre- + cated. + + If any of your existing integrations use the --first-unit-only option, we + recommend that you remove this option from them. + + If any of your existing integrations do not use the --first-unit-only option, + you may need to update them if all of the following are true: + • Your code includes generic Ada packages. + • Your integration is not managed by rvsdriver, and invokes adains directly. + • Your integration invokes adains with a subset of all ADT files, rather than all + ADT files produced by the compiler. + + + 9 +Migrating from v3.7 to WF20190404 Migrating from v3.7 to WF20190404 + + + In these cases, you must update affected integrations to explicitly pass ADT files + corresponding to generic packages to adains. + + For more information, contact support@rapitasystems.com. + +3.3 Deprecated features +3.3.1 Windows XP/Vista and Windows Server 2003/2003 R2/2008 + support + Support for Windows XP/Vista and Windows Server 2003/2003 R2/2008 has now + been deprecated and will be removed in a future version of RVS. We recommend + that users run RVS on a more recent version of Windows as RVS may run with a + reduced set of features when used on versions of Windows that are deprecated. + +3.3.2 Legacy integration support + Integration support using compiler wrappers and clone scripts from versions of + RVS v3.6 and older was deprecated in RVS v3.7. We have moved tools that sup- + port these legacy integrations out of the main installer and into an add-on installer, + setup-rvs-legacy-integration-support. If you want to use legacy + tools, you will have to install this separately. + + The new add-on installer will be removed in a future version of RVS. We recom- + mend that users upgrade their integrations to use the new style integrations as + described in the RVS Integration Guide. + +3.3.3 Deprecated options + We have deprecated the following options: + • --first-unit-only (adains) + + This option has been deprecated as the behavior it specified is now the default + behavior of adains, see Section 3.2.4: Parsing of ADT files. + +3.4 Removed features +3.4.1 Support for GNAT compilers + Support for the following GNAT compilers has been removed: + • GNAT Pro 6.0 + + + 10 + Migrating from RapiTest +4 v1.4a + RapiTest is now part of RVS. This chapter highlights the changes and enhance- + ments made to RVS since the RapiTest v1.4a release. + +4.1 Changed features +4.1.1 Changed names of data structures used to store RapiTest + data + We have renamed the following data structures, which are used to store RapiTest + data in standard integration libraries: + • rapiunit_data is now named rapitest_data. + • rapiunit_header is now named rapitest_header. + + For integrations that use the Managed testing mode, analysis will fail if RapiTest + data is not stored in the updated data structure names shown above. As such, + if you have existing integration libraries that include RapiTest analysis, you must + update the names of the data structures by editing your integration library files. + + By default, RVS integration libraries are deployed in the + rvs_ folder. + +4.1.2 Changed name of RVS commit stage + We have renamed the Commit stage of dual-pass RVS integrations to Build. + + Per this change, we have renamed the rvsdriver option --commit to --build. + If you have command-line scripts that call rvsdriver with the --commit option, + you will need to update them to use the --build option instead. + +4.1.3 Called operator + We have changed how the RapiTest called operator works: + • Previously, when the Control flow configuration setting was used, this operator + used to only be valid when used with either a blank Value (specifying that the + stub was called once at this point in the test sequence) or a : Value (specifying + that the operator should be ignored). Now, when the Control flow configuration + setting is used, a numeric Value specifies that a stub is called this number of + times in the test sequence, and a blank Value is invalid. + • Previously, when both the called operator and an operator that checks val- + ues (such as check), were both specified multiple times for the same sub- + program, the Value used for the checking operator cycled between each Val- + + + 11 +Migrating from RapiTest v1.4a Migrating from RapiTest v1.4a + + + ue specified. Now, the Value specified for the checking operator will apply a + number of times based on the Value given for the called operator. + + For an example, see Figure 4.1. Previously, this test would check that the return + values from 5 consecutive calls to stub1 were 64, 128, 64, 128 and 64. + Now, this test will check that the the return values from 5 consecutive calls to + stub1 are 64, 64, 128, 128 and 128. + + + Figure 4.1: Called operator and checking operations + + If you have tests that may be affected by these changes, you should review them + to ensure that this change has not caused your existing tests to no longer be valid. + + For more information on the behavior of the called operator, see the Spread- + sheet Test Format User Guide. + + + 12 + Migrating from v3.6 to +5 v3.7 + This chapter highlights the changes and enhancements to RVS that have been + introduced in the 3.7 release. + +5.1 New features +5.1.1 RVS Project Manager + A new user-interface has been added that lets you manage RVS projects. Using + this application, you can create, run, view and export results during an RVS project. + For more information, see the RVS User Guide. + +5.1.2 New integration workflow + A new integration workflow has been added to make it easier to integrate RVS + into development environments. A new file type, the RVS project file (.rvsprj + extension), has also been added, which contains all of the information needed to + run RVS projects. + + We recommend that you create a new integration for your project using the RVS + Project Manager. This generates an RVS project file suitable for running it. To + learn how to do this, see the RVS Integration Guide. + + Next, with the project file open in the RVS Project Manager, deploy your integra- + tion. This sets up an integration library that you can use to migrate your existing + integration. To learn how to deploy an integration, see Section 4.3 in the RVS User + Guide. + + After deploying an integration library, you may need to follow one or more of the + steps below: + • If your integration uses compiler wrappers, uninstall your old compiler wrap- + pers, and install new ones as described in Section 4.2 in the RVS Integration + Guide. This is recommended as new compiler wrappers have been added to, + and old ones have been deprecated and will be removed in a future version + of RVS, see Section 5.1.3: New compiler wrappers. + • If your existing RVS integration library was modified from + a standard template, migrate your modified integration library + files to the integration libraries in your new project folder: + /RVS_/rvslib. + • If your existing RVS integration specifies extra tool options in a rvs.conf + file, specify these as Extra Tool Options in your new project through the RVS + Project Manager, as described in Section 4.11.12 in the RVS User Guide. + + + 13 +Migrating from v3.6 to v3.7 Migrating from v3.6 to v3.7 + + + • If your existing integration uses an excluded file list to speci- + fy functions to explicitly exclude from instrumentation, copy your + existing excluded_file.config file (by default, this should + be in the RVS/config directory) to your new project fold- + er /rvs_, and rename the + file as excluded-files.txt. The file must be renamed as + excluded-files.txt is now the default file for specifying excluded files. + • If your existing integration uses modified compiler extensions to work + with your build system, copy any files with modified extensions + to the compiler extensions folder in your RVS installation directory: + RVS/integration_resources/compiler_extensions. + • If your existing integration uses RVS annotations, copy these from + your existing annotation files (by default, these should be in the + RVS/annot directory) to the corresponding files in your new project folder: + /rvs_/annotations. + • If your existing integration uses RVS filters to process verification da- + ta, copy your filter files to the filters folder in your new project folder: + /rvs_/filters. + + If your integration is heavily customized, you may need to perform addition- + al migration steps to the ones listed above. To discuss this, or any ques- + tions you may have while migrating to the new integration workflow, contact + support@rapitasystems.com. + +5.1.3 New compiler wrappers + New versions of compiler wrappers have been added, which work with the new + integration workflow. Compiler wrappers from previous RVS versions are depre- + cated in RVS v3.7. In a future version of RVS, we will stop supporting the use of + these wrappers. + + The new wrappers are implemented as simple loader functions that load neces- + sary code. As a result of this change, you will no longer need to re-wrap your com- + piler each time you upgrade to a new version of RVS, and should be able to use + the same wrapper with any future versions. + + If your existing integration uses a compiler wrapper, we recommend that you up- + grade it to use the new wrappers as described in the RVS Integration Guide. + If you would like assistance upgrading to the new compiler wrappers, contact + support@rapitasystems.com. + +5.2 Changed features +5.2.1 Hosting license servers and configuring licenses + We have changed the software used to configure and run RVS license servers. + This is now done using the new RVS License Server Control Panel. If you were + + + 14 +Migrating from v3.6 to v3.7 Migrating from v3.6 to v3.7 + + + hosting an RVS license server, we recommend that you install and use the new + software as described in Chapter 4 in the RVS Installation and Licensing Guide. + + We have also changed how to configure licenses used by local RVS installations. + The new RVS License Manager lets you check details about your RVS licenses, + manage which licenses are used, install software for USB license keys and update + your license. This is installed with RVS and you can access it from the Windows + Start menu (Start » RVS » RVS License Manager) and the RVS Project Manager, + see Chapter 5 in the RVS Installation and Licensing Guide. + +5.2.2 Identifying the default RVS version + We have added a new environment variable to RVS, RVS_PATH. You can use this + to call the RVS tools from your build system. The default version is stored in the + registry as it was in previous versions, but its location has been moved to support + the use of multiple RVS versions on the same system. We recommend that you + use the RVS_PATH environment variable rather than querying the registry to call + RVS tools. + + Now, when you install a new version of RVS, you can select to keep the existing + default version or overwrite it with the version you are installing. When you uninstall + a default version, the most recently installed version on your file system becomes + the default. + +5.2.3 RVS maps + We have introduced a new RVS map data structure for the collection of RVS data, + the universal map. This replaces the old coverage map structure, which has been + deprecated and will be removed in a future version of RVS. + + If you have an existing integration that uses the old coverage map structure, we + recommend migrating to the new universal map structure. To do this, you should: + • Replace the --coverage-map option to rvdutils with --create-map. + • Update your integration library to be compatible with the new RVS map API. + To do so, contact support@rapitasystems.com for assistance. + + Note that the --coverage-map option to instrumenters should be left un- + changed. + + Note + + When deciding whether to upgrade to the universal map structure, you + should consider the following limitations: + • The --segment option is not currently supported for universal maps. + • The --static-init option is not currently supported for universal + maps. + + If you would like assistance migrating to the universal map structure, contact + support@rapitasystems.com. + + + 15 +Migrating from v3.6 to v3.7 Migrating from v3.6 to v3.7 + + + If you do not wish to upgrade to the universal map structure and your + integration uses a customized coverage map template, you should copy + your existing template from RVS/bin/covmap in your old installation to + RVS/integration_resources/covmap in the new installation. This is due + to a change in the base directory for map templates, and the default directory + searched for by the --map-template option of rvdutils. + +5.2.4 Changed how compiler wrappers collect tool version + information + We have changed the way compiler wrappers collect information on the RVS tool + version they are operating on so that they are more robust. + + Compiler wrappers now collect this information in the following way: + • If the wrapper executable being invoked is in a directory up to three folders + deeper than the root RVS folder (for example in the default wrapper folder, + RVS/integration_resources/compiler_wrappers/wrapper), + the wrapper uses the tools in this RVS directory. + • If the above is not the case, the wrapper collects tool information by reading + the RVS_PATH environment variable. The RVS_PATH environment variable + is automatically set by RVS based on the installed version of RVS, see Sec- + tion 5.2.2: Identifying the default RVS version. + + If an enabled compiler wrapper is called and it cannot collect RVS tool version in- + formation by either method listed above, the wrapper will halt execution and report + an error. If this occurs, contact support@rapitasystems.com for assistance. + +5.2.5 Coverage export format + We have added a summary of tool options that may affect coverage results to + coverage export files generated by covexport and the RVS Project Manager. + + If you are post-processing coverage export files, check that the post-processing + behavior is still as expected. + +5.2.6 RVS Tutorials + The old RVS tutorials have been removed, and replaced with improved tutorials + that reflect the workflow for running RVS through the RVS Project Manager. The + new tutorials are easier to follow and run from within the RVS Project Manager. + For more information, see the new RVS User Guide. + +5.2.7 User documentation + The user documentation for RVS v3.7 has been overhauled. + + The RVS Integration Guide has been rewritten to represent the new integration + workflow. Information that used to be in this document on writing RVS filters has + been moved to the RVS Filters Guide. + + + 16 +Migrating from v3.6 to v3.7 Migrating from v3.6 to v3.7 + + + An RVS User Guide has been added, which describes features shared by multiple + RVS products. + + The RVS Reference Guide has been split into a series of more focused individual + documents. These new documents are: + • The RVS Command Line Tools Reference Guide, which describes the low-level + command-line tools used by RVS and includes the command options that can + be used with each tool. + • The RVS Annotations Reference Guide, which describes annotations you can + use to control instrumentation and analysis with RVS. + • The RVS Files Reference Guide, which describes RVS-specific files including + input, intermediate and output files. + • The RVS Filters Guide, which describes RVS filters, which are used to convert + raw trace data into a format that RVS can analyze, and how to write them. + • The RVS Troubleshooting Guide, which describes error and warning messages + you may encounter when using RVS, and how to address them. + + You can access user documentation in RVS 3.7 directly through the RVS Project + Manager (Help menu > Help Topics) and in PDF form in the RVS documentation + folder (RVS/doc). + +5.3 Deprecated features +5.3.1 Compiler wrappers + Compiler wrappers from previous RVS versions are now deprecated and will be + removed in a future version of RVS. We recommend that users upgrade their in- + tegrations to use the new style compiler wrappers as described in the RVS Inte- + gration Guide. + +5.4 Removed features +5.4.1 Coverage data collection via trace + We have removed support for collecting coverage data via an RVS trace format. + We now recommend that coverage data is collected using a map or LiveMap + format. + + If your integration previously collected coverage data via a trace, you will likely + need to modify your integration library to use a LiveMap strategy using either direct + or buffered write. For help doing so, contact support@rapitasystems.com. + + Note + + If your trace coverage integration called RVS instrumenter tools with the + --assume-src-order option, you will need to remove these calls; this + option has also been removed as it is no longer relevant. + + + 17 + Migrating from v3.5 to +6 v3.6 + This chapter highlights the changes and enhancements to RVS that have been + introduced in the 3.6 release. + +6.1 New features +6.1.1 Support for new GNAT compilers + Support for the following GNAT compilers has been added in v3.6: + • GNAT Pro 17 + • GNAT GPL 2015 + • GNAT GPL 2016 + +6.1.2 Support for TASKING Classic compiler + Support for the TASKING Classic compiler has been added in v3.6. + + If you are using the TASKING Classic compiler, you should use the --cext + TASKING_CLASSIC option to specify your compiler. + +6.2 Changed features +6.2.1 Changed option for TASKING VX compiler + The --cext option has had two parameters added in v3.6, to support the + TASKING Classic compiler, see Section 6.1.2. + + If you are using the TASKING VX compiler, and were previously using the -- + cext TASKING option to specify your compiler, you now need to use the -- + cext TASKING_VX option. + +6.2.2 Changed covparser to allow parsing of multiple tests per + command-line + covparser has been changed to let you configure processing of data to multiple + tests in a single command-line. This required a significant syntax change in cov- + parser. + + In previous versions, you could provide the --test-id, --test-name and map + or trace file.rpz or file.txt files in any order without ambiguity. + + In v3.6, you must enter test_id, test_name and file.rpz options in cov- + parser using a defined syntax. For more information on this, see the RVS Com- + mand Line Tools Reference Guide. + + + 18 +Migrating from v3.5 to v3.6 Migrating from v3.5 to v3.6 + + + As a consequence of this syntax change, the default test name has been removed. + Previously, if you did not enter a --test-name option, your test name would be + set to Default. In v3.6, no default name is assigned. + +6.2.3 Changed default_instrument annotations + The handling of the default_instrument annotation has been made + stricter. In v3.6, you must always specify a default_instrument annota- + tion, and this must include an instrumentation profile. If you do not specify a + default_instrument annotation, or include an instrumentation profile, RVS + will generate an error. + + You can update existing integrations that do not specify a + default_instrument annotation by defining + #pragma RVS default_instrument ("FALSE", "NONE"); + before any other annotations. + +6.3 Deprecated features +6.3.1 Deprecated options + The following xstutils options are now deprecated: + • --VCS-regexp + + This option should be replaced by --build-id. + +6.4 Removed features +6.4.1 Removed GNAT compilers + Support for the following GNAT compilers has been removed in v3.6: + • GNAT GPL 2007 + • GNAT GPL 2008 + • GNAT GPL 2009 + • GNAT GPL 2010 + • GNAT GPL 2011 + • GNAT GPL 2012 + • GNAT GPL 2013 + + Users of these GNAT GPL compilers should upgrade to GNAT GPL 2016, which + may be downloaded from libre.adacore.com. RVS v3.6 supports GNAT GPL 2014 + through to GNAT GPL 2016. + +6.4.2 Removed compiler wrappers + Support for the following legacy compiler wrappers, that were replaced in v3.4, + have been removed in v3.6: + + + 19 +Migrating from v3.5 to v3.6 Migrating from v3.5 to v3.6 + + + • ms_visual_studio + • greenhills + + If you use these compiler wrappers, you should upgrade to the new style + compiler wrappers. For help with this, contact Rapita Systems support at + support@rapitasystems.com. + + + 20 + Migrating from v3.4 to +7 v3.5 + This chapter highlights the changes and enhancements to RVS that have been + introduced in the 3.5 release. + +7.1 New features +7.1.1 Support for new GNAT compilers + Support for the following GNAT compilers have been added in v3.5: + • GNAT Pro 7.3 + • GNAT Pro 7.4 + +7.1.2 New compiler wrappers + The following compiler wrappers have been added in v3.5: + • GNAT + • cl500 + • cl2000 + +7.1.3 New options + The following options have been introduced in v3.5 (see the RVS Command Line + Tools Reference Guide for more information): + • adains --literal-rename-ignore + • cins, cppins --auto-extend-bbox + • cins, cppins --mcdc-optim-single-condition + • taskparser --faster + • rvdutils --remove-coverage + • covexport --decision-coverage + • covexport --no-line-numbers + +7.1.4 New instrumentation profiles + The following instrumentation profiles have been introduced in v3.5 (see the RVS + Command Line Tools Reference Guide for more information): + • MANUAL + + + 21 +Migrating from v3.4 to v3.5 Migrating from v3.4 to v3.5 + + +7.2 Changed features +7.2.1 adains output location + adains will now issue a warning if it is called without specifying a location for the + instrumented output. + + To prevent this warning, amend your integration so that the call to adains specifies + an output location. + +7.2.2 Changed instrumentation profiles + In previous versions the NONE profile would still generate ipoints if explicitly re- + quested by the user (for example, using the instrumentation_point anno- + tation). + + With the introduction of the new MANUAL profile, the NONE profile has been up- + dated so that it will never insert ipoints. If ipoints need to be manually inserted then + the profile should be changed from NONE to MANUAL (see the RVS Command + Line Tools Reference Guide for more information). + +7.2.3 Change to instrumentation of code in header files + In previous versions, functions contained in header files would be instrumented + without the use of the --instrument-h option if they were the subject of a spe- + cific instrument annotation, or if they contained manual instrumentation points + (using the instrumentation_point annotation). + + In RVS 3.5 and later, these methods will only cause the instrumentation of code + in header files if the --instrument-h option is present. You will need to set + this option in your integration if you need to instrument any code contained in a + header file. If you use a ctree file to generate instrumentation, you should review + the list of functions to be instrumented and enable the --instrument-h option + if necessary. + +7.2.4 Change to instrumentation library + When using adains with the --case-is-mcdc-decision option, it is nec- + essary to update your instrumentation library to make use of a more ef- + ficient implementation of the DM ipoint. For an example of the required + implementation, see the template instrumentation libraries located in the + integration_resources/template_rvslib/coverage folder of + your RVS installation. + +7.2.5 Coverage of literal functions/renamed functions in Ada + Calls to literal renamed functions are now identified as elements requiring cover- + age, which may result in RVS 3.5 reporting lower overall coverage than earlier ver- + sions. To restore the previous behavior, add the new --literal-rename-ig- + nore option to adains. + + + 22 +Migrating from v3.4 to v3.5 Migrating from v3.4 to v3.5 + + +7.2.6 Change to covexport output + covexport now uses "-" in situations where there are no elements to cover (i.e. + coverage achieved/required is "0/0"). Previously, "0%" was output in this case. + + If you have any automated processing of the covexport output that relies on the + "0%" value you may need to update this to take account of this change. + +7.3 Deprecated features +7.3.1 Deprecated options + The following taskparser options are now deprecated: + • --disable-parser-2 + + This option is now enabled by default: taskparser will parse traces in the same + way as timeparser. The --faster option must be specified to revert to the + parser used in RVS 3.3 and 3.4. + + The following xstutils outputs are now deprecated: + • .fctree + +7.4 Removed features +7.4.1 Removed options + The following xstutils options have been removed: + • --all-roots + + This option is no longer needed and should be replaced by a specific list of + roots via -r ROOT1 -r ROOT2 etc... or --no-root. + + + 23 + Migrating from v3.3 to +8 v3.4 + This chapter highlights the changes and enhancements to RVS that have been + introduced in the 3.4 release. + +8.1 New features +8.1.1 New coverage justification mechanism + RVS 3.4 introduces a new mechanism to create, store, manage and migrate jus- + tifications which can be used to address areas of missing coverage. + + This new mechanism replaces the justification system that was provided in previ- + ous versions of RVS: + • CSV format justifications (supplied to covexport) are no longer supported. + • Tagged justification annotations (where the justification annotation is located + in a separate justification file) are no longer supported. + • Justification annotations included in-line with the source code are still sup- + ported. They will be shown in the RVS Report Viewer but cannot be edited or + deleted. + + Justification files that were used with previous versions of the tool must be con- + verted before they can be used with RVS 3.4. For a small number of justifications + this can be done manually using the facilities provided by the RVS Report Viewer. + For guidance on using these facilities, see the RapiCover User Guide. + + If you require assistance with converting a larger number of justifications to the new + format, please contact Rapita Systems support at support@rapitasystems.com + for advice. + +8.1.2 New options + The following options have been introduced in v3.4 (see the RVS Command Line + Tools Reference Guide for more information): + • adains --ada83 + • adains --coverage-livemap + • adains --incr-coverage + • cins --coverage-livemap + • cins --incr-coverage + • cins --incr-coverage-macro + • cins --mcdc-key-type + + + 24 +Migrating from v3.3 to v3.4 Migrating from v3.3 to v3.4 + + + • covexport --show-justification-tags + • covparser --livemap + • covparser --livemap-bit-check + • covparser --livemap-bits + • covparser --livemap-reset + • cppins --coverage-livemap + • cppins --incr-coverage + • cppins --incr-coverage-macro + • cppins --mcdc-key-type + • rvdutils --import-justifications + • rvdutils --inherit-justifications + • rvdutils --no-inherit-justifications + • traceutils --split + • xstutils --import-justifications + +8.1.3 New annotations + The following annotations have been introduced in v3.4 (see the RVS Command + Line Tools Reference Guide for more information): + • uncertain_return – for coverage, indicates that a call to a function is not + guaranteed to return and that an extra ipoint should be inserted before the call + +8.1.4 New compiler wrappers + New compiler wrappers for GCC and DCC have been introduced in v3.4. + + General information about compiler wrappers can be found in Section 4.2 in the + RVS Integration Guide. Each compiler also has an integration annex containing + compiler-specific documentation. + + Integrations using earlier versions of the compiler wrappers will still continue to + work with RVS 3.4, however it will be necessary to migrate to the new wrappers in + order to fully support the new features that have been introduced in this release. + Some modifications are necessary in order to use the new wrappers in an existing + integration: + • -RVSCOVMAP has been deprecated in favor of the new - + RVSCOLLECTION=covmap. + • Option -RVSASPATH is no longer supported. If your integration requires this + option, continue to use the legacy wrapper. + • Option -RVSARPATH is no longer supported. If your integration requires this + option, continue to use the legacy wrapper. + • Option -RVSQUIET is no longer supported. Instead use -RVSSILENT. + + + 25 +Migrating from v3.3 to v3.4 Migrating from v3.3 to v3.4 + + + • Options -RVSNOCCWRAP, -RVSNOLINKWRAP, -RVSNOARWRAP are no longer + supported. If your integration requires these options, continue to use the lega- + cy wrapper. + • Options -RVSNOREPORT is no longer supported. Instead use -RVSRE- + PORTENABLE to specify an RVD trigger string. + • Instrumentation and analysis annotations are now specified in + the files annot/rvs_instr.h, annot/rvs_analysis.c and + annot/rvs_fptr.c inside the project RVS folder. + • Options are now passed to individual tools via configuration files found in + /config/.config. + + For further assistance, please contact Rapita Systems support at + support@rapitasystems.com. + +8.2 Deprecated features +8.2.1 Deprecated options + The following adains options are now deprecated: + • --gnatmake-D + + This option is no longer required as adains is now able to automatically detect + when ADT files were generated using gnatmake -D. + • --no-t_RVS_wrap_end + + This option is no longer required as adains does not generate the + t_RVS_wrap_end controlled type within instrumented Ada code. In v3.3, + t_RVS_wrap_end was used to instrument some function calls and return + statements. v3.4 instruments the same Ada code using other approaches + which do not require the use of controlled types. + + The following rvdutils option has been removed: + • --add-annotations + + With the new justification system, the functionality provided by this option + has been replaced by rvdutils --import-justifications. Justifications + must first be converted to the new justification store format. If you require as- + sistance converting your existing justifications to the new format please con- + tact Rapita Systems support at support@rapitasystems.com. + + + 26 + Migrating from v3.2 to +9 v3.3 + This chapter highlights the changes and enhancements to RVS that have been + introduced in the 3.3 release. + +9.1 New features +9.1.1 Support for new GNAT compilers + adains now support .adt files generated by GNAT GPL 2013 and 2014 as well + as GNAT PRO 7.1 and 7.2. + +9.1.2 New options + The following options have been introduced in v3.3 (see the RVS Command Line + Tools Reference Guide for more information): + • adains --no-fwrap + • adains --max-line-length + • adains --dummy-instr + • adains --no-incr-build disables + • adains --RVS-I + • adains --case-is-mcdc-decision + • adains --instr-elab + • adains --segment + • cins, cppins --remove-hline + • cins --cext-config + • adains, cins, cppins --coverage-trace + • adains, cins, cppins --coverage-trace-F + • adains, cins, cppins --coverage-trace-TF + • adains, cins, cppins --coverage-trace-VAL + • adains, cins, cppins --instr-CAST10-literal + • adains, cins, cppins --instr-CAST10-traditional + • covparser --cpu + • covparser, timeparser, taskparser --build-id + • rvdutils --remove-cpu-data + • rvdutils --segment + + + 27 +Migrating from v3.2 to v3.3 Migrating from v3.2 to v3.3 + + + • rvdutils --map-template + • rvdutils --add-annotations + • rvdutils --exclusions + • taskparser --cpu + • taskparser --time-units + • xstutils --stubbed + • --ignore-warning and --ignore-warning-list + • licserv --audit-log and --rotate + +9.1.3 New annotations + The following annotations have been introduced in v3.3 (see the RVS Command + Line Tools Reference Guide for more information): + • allow_function_wrap to locally override the effect of option + --no-fwrap + • disable_inherited_justifications to disable automatic justifica- + tion inheritance. + • New annotation tag syntax ["file.ext:line"] for linking external anno- + tations to a particular source code line. + +9.1.4 New instrumentation profiles + The following instrumentation profiles have been introduced in v3.3 (see the RVS + Command Line Tools Reference Guide for more information): + • COV_178_DAL_A equivalent to function + statement + decision + MC/DC + coverage. + • COV_178_DAL_B equivalent to function + statement + decision coverage. + • COV_178_DAL_C equivalent to function + statement coverage. + • COV_MCDC replaces the deprecated profiles COV_MCDC_MAP, + COV_MCDC_TF, COV_MCDC_F and COV_MCDC_VAL. + +9.2 File format modifications +9.2.1 RapiCover XML output + The XML schema for the output of the covexport tool has been modified to avoid + the double use of the 'coverage' element. + + The 'coverage' element child of a 'decision' element has been renamed 'covdata'. + The 'coverage' element retains attribute 'class' and all other attributes ('required', + 'not_instrumented', 'addressed', 'achieved', 'addressed_perc', 'achieved_perc' and + 'total_perc') have be transferred to element 'covdata'. + + + 28 +Migrating from v3.2 to v3.3 Migrating from v3.2 to v3.3 + + +9.3 Deprecated features + The following instrumentation profiles are now deprecated: + • COV_MCDC_MAP + + Replaced by COV_MCDC and option --coverage-map. + • COV_MCDC_F + + Replaced by COV_MCDC and option --coverage-trace-F. + • COV_MCDC_TF + + Replaced by COV_MCDC and option --coverage-trace-TF. + • COV_MCDC_VAL + + Replaced by COV_MCDC and option --coverage-trace-VAL. + + The following options of covexport are now deprecated: + • --justifications + + Replaced by rvdutils --add-annotations. + • --inherit-justification + + Replaced by annotation disable_inherited_justifications. + • --exclusions + + Replaced by rvdutils --exclusions. + • --migrate-justifications-to + + + 29 + Migrating from v3.1 to +10 v3.2 + This chapter highlights the changes and enhancements to RVS that have been + introduced in the 3.2 release. + +10.1 New features +10.1.1 Feedback tool + The RVS feedback tool now provides a convenient method of sending feedback to + the Rapita Systems support team. The interface allows relevant information to be + packaged easily into a feedback report, while also providing the ability to exclude + sensitive data. + + The feedback tool can be accessed in any of the following ways: + • automatically (if a command-line tool reports an unexpected error and the + --debug-report option has been specified) + + Note + + To disable this feature, include the --send-feedback never option + when calling the command-line tools. + + • from the feedbacktool command line program + • manually from the RVS Report Viewer Help menu + +10.1.2 .NET for RapiTask + For installations of RapiTask, it is necessary to have the .NET framework installed. + + For Windows operating systems, please check that version 4.0 of the .NET frame- + work is installed. + + For Linux and Unix systems, a version of Mono is shipped with the installer and + will automatically be used by RapiTask. + +10.1.3 RVD file structure + It is now possible to store multiple reports in a single RVD file. This feature was + added to support multiple traces when using RapiTask to analyze data from mul- + ti-core systems. Additionally, several other RVS tools now use multi-report RVD + files as a convenience to store data for multiple root functions within a single file. + (Previously, individual files were required for each root function.) + + 30 +Migrating from v3.1 to v3.2 Migrating from v3.1 to v3.2 + + + Note + + The RVS Report Viewer allows you to view each report in an RVD file individ- + ually. + + This functionality affects existing builds that specify multiple roots. For example: + xstutils -r root1 -r root2 -r root3 <...> + would previously have produced three separate RVD files (one for each root). The + new functionality will produce a single RVD file. + + There may be cases where you wish to disable this feature. This can be accom- + plished with the --no-package option in xstutils. For example: + xstutils -r root1 -r root2 -r root3 --no-package <...> + will produce three separate RVD files. + +10.2 Deprecated features + The previously deprecated program traceparser has been removed from the 3.2 + release. (It has been replaced by covparser and timeparser.) + +10.3 Annotations +10.3.1 Profiles + The following additional annotation profiles have been added to RapiCover to pro- + vide greater coverage options when processing map data. They also provide spe- + cific profiles for branch coverage. + + COV_FUNCTIONS_MAP + Add instrumentation to measure function coverage optimized for a map. Instru- + mentation points are added at the entry and exit points of functions as well as + before some function calls. + + COV_STATEMENTS_MAP + Add instrumentation to measure statement coverage optimized for a map. Instru- + mentation points are added at the entry and exit points of functions and after all + blocks of statements. + + COV_DECISIONS_MAP + Add instrumentation to measure decision coverage optimized for a map. Instru- + mentation points are added at the entry and exit points of functions and at the + beginning of all branches. + + COV_BRANCHES + Add instrumentation to measure branch coverage. Instrumentation points are + added at the entry and exit points of functions and at the beginning of all branches. + + + 31 +Migrating from v3.1 to v3.2 Migrating from v3.1 to v3.2 + + + COV_BRANCHES_MAP + The same functionality as COV_BRANCHES, but provides optimized instrumenta- + tion for map coverage. + + COV_CALLS_MAP + Add instrumentation to measure call coverage optimized for a map. Instrumenta- + tion points are added at the entry and exit points of functions, and before function + calls. + +10.3.2 default_instrument + If no profile is specified, or if a default_instrument annotation is not provid- + ed, this will now generate an error. (Previous versions of RVS did not require this + annotation to be specified.) + + Note + + For backward compatibility, the previous behavior can be restored by defin- + ing + #pragma RVS default_instrument ("FALSE", "TIME_FULL"); + before any other annotations. + + +10.3.3 Analysis annotations + The ignore_path pragma for RapiTime has been enhanced through the provi- + sion of a new option to provide a path id. The optional ("path_id") tag allows + you to set an identity for a particular path and ignore that path specifically. For + example: + + C/C++ + #pragma RVS ignore_path; + #pragma RVS ignore_path ("path_id"); + /*##RVS ignore_path */ + + + C++ + //##RVS ignore_path + //##RVS ignore_path ("path_id") + + + Ada + pragma RVS (ignore_path); + pragma RVS (ignore_path ("path_id")); + + + For more information regarding the use of this tool, see Section 8.12 in the RVS + Annotations Reference Guide. + + + 32 +Migrating from v3.1 to v3.2 Migrating from v3.1 to v3.2 + + +10.4 Command line tools +10.4.1 cins -I + The -I annotation is used to specify the path to search for the original C source + files. This option is needed when the location of the original source files (not the + preprocessed cins input files) is unable to be resolved from the location of the + relative paths stored in the preprocessed source when running cins. It allows the + content of these source files to be browsed in the RVS Report Viewer. This option + can be used multiple times to list a number of directories for cins to search. cins + searches the directories in the order that they appear on the command line. + + For example: consider a set of source files in a directory called original. These + files have been preprocessed, and the output has been redirected to a directory + called build. In order to instrument the preprocessed files, cins must be given + the location of the original source files. The following command will do this: + cins [...] -I original *.p + + +10.4.2 xstutils -r + The -r option for xstutils has been improved to allow wildcards to be used when + specifying a root. The following wildcards and patterns are supported: + + Pattern Matches + * any string of 0 or more characters + ? any single character + elmt1 elmt2 ... concatenation (elmt1 then elmt2 ...) + [char char ...] any character listed + [char - char] any character in the given range + {elmt, elmt, ...} alternation (matches any of elmt) + + +10.4.3 xstutils --all-roots + The --all-roots option has been added to generate an .rvd file with auto- + mated root discovery. The source code will be searched for functions that are not + called from another function. All functions with no calls to them will be treated as + a root. + +10.4.4 xstutils --cpu + The --cpu option is used to specify that a root function (and all following root + functions) were executed on a particular core of a multi-core hardware configura- + tion. This data will be used by taskparser when analyzing trace data. + + For example, in the following call to xstutils the user has specified that root1 and + root2 were executed on CPU 0, while root3 was executed on CPU 1.: + + 33 +Migrating from v3.1 to v3.2 Migrating from v3.1 to v3.2 + + xstutils --cpu 0 -r root1 -r root2 --cpu 1 -r root3 <...> + + + Note + + CPU numbering must begin with 0 and contain no gaps. + + + 34 + Migrating from v3.0 to +11 v3.1 + Version 3.1c of RVS introduced the ability to record coverage data as a map. This + method of calculating coverage improves the efficiency of RapiCover, and also + allows decisions with more than 12 conditions to be analyzed for MCDC coverage. + + This chapter highlights key changes to the command line tools, instrumentation + libraries and integration relating to this new feature. + + Note + + Users of RapiCover performing coverage using a trace-based integration + are not affected by this change. + + +11.1 Instrumentation library + In order to process coverage data with RapiCover v3.1c and above, the instru- + mentation library used to link with the analyzed software and record coverage map + data must be upgraded to match the latest version. + +11.1.1 Generic instrumentation library + Generic implementations of the instrumentation library are provided with the RVS + installation for both C/C++ and Ada in the following locations: + + integration_resources\template_rvslib\map\C + integration_resources\template_rvslib\map\Ada + integration_resources\template_rvslib\trace\C + integration_resources\template_rvslib\trace\Ada + +11.1.2 Custom instrumentation library + Background + + When integrating RVS with your software, it is likely that you will have to customize + the provided instrumentation library (see Section 11.1.1) to meet your require- + ments. + + Note + + If you have an existing RapiCover map-based integration, it is likely that you + have already developed a custom implementation library to fit your build + process and/or hardware target. If this is the case, you should use this ex- + isting library as a starting point for further customization. + + + 35 +Migrating from v3.0 to v3.1 Migrating from v3.0 to v3.1 + + + Migration guide + + The relevant file to edit is rvs.c (for C/C++) or rvs.adb (for Ada). + + The functions RVS_Init, RVS_Begin_Test, RVS_Build_Id, RVS_CM, + RVS_DM, RVS_DML, RVS_CMS and RVS_DMS should not be modified and can be + directly copied from the latest reference implementation of rvs.c (or rvs.adb). + + Depending of the data extraction mechanism used in your integration, you may + have to adapt the RVS_Output function. In order to do this, you should start + from the reference implementation in the latest rvs.c (or rvs.adb) and perform + the same adaptations as the one applied to the old version of the instrumentation + library. + + Note + + If you are extracting the coverage map data via a memory dump (e.g. using + a debugger) then the implementation of RVS_Output is unchanged (i.e. it + simply calls rvs_coverage_reset). + + + Note + + If RVS_Output does not write the content of the coverage map to a file, + you can delete all file I/O operations and related include files and variables. + + If you need assistance to adapt the new reference implementation, please contact + support@rapitasystems.com with the current version of your instrumenta- + tion library. + +11.2 Command line tools +11.2.1 rvdutils + Option --compact-map of rvdutils is now deprecated, as RVS 3.1c and above + produces more compact map data by default. + + Option --map-size as been added to rvdutils. This option allows the user to + specify the maximum amount of memory available for storing the coverage map + on the target. This option is only required when instrumenting decisions with more + than 12 conditions (this was not supported by the previous version of RVS) with + the profile COV_MCDC_MAP. If your code does not contain any such decision, you + will not have to use this option. + + Note + + This option is only required when instrumenting decisions with more than 12 + conditions with the profile COV_MCDC_MAP. This was not supported by RVS + prior to version 3.1c. + + + 36 +Migrating from v3.0 to v3.1 Migrating from v3.0 to v3.1 + + +11.3 Integration +11.3.1 Data extraction + ... via RVS_Output + + If your current RVS integration uses RVS_Output to extract the coverage data, + you should continue to use the same I/O mechanism with the new version of + RVS_Output. + + The reference implementation provides an example (file-based) implementation. + Note that the RVS_Output function is simpler in version 3.1c and above, as it is + simply exporting the content of the coverage map, byte-by-byte. As a result, the + data processing (see Section 11.3.2) part of the integration will need have to be + modified if you were using this function. + + ... via memory dump + + If you integration uses a debugger to extract coverage map data, (i.e. by setting a + breakpoint on RVS_Output and then performing a memory dump) you will not + need to change the data processing part of the integration. + + You will, however, need to change the way you perform the memory dump, as the + symbol names have changed. In particular, the memory area start is now indicated + by symbol rvs_mcdc_data and extends for *rvs_mcdc_size bytes. + + For example, the gdb command to dump this area of memory in C/C++ is: + dump binary memory mem.bin rvs_mcdc_data (rvs_mcdc_data + +(*rvs_mcdc_size)) + To do the same in Ada, the command is: + dump binary memory mem.bin (&rvs_map.mcdc_data) + (&rvs_map.mcdc_data(rvs_map.mcdc_size)) + + + Warning + + The size of the area to dump is stored at the address rvs_mcdc_size, + and is now variable. + + +11.3.2 Data processing + In previous versions of RVS, data extracted via the RVS_Output function was + directly usable by covparser with the --map option, whereas data extracted as a + memory dump (e.g. using a debugger) had to be processed by a 'memory dump' + filter (e.g. map.memdump.flt). + + In the new version of the instrumentation library, the RVS_Output function is the + equivalent of performing a memory dump. Thus, the 'memory dump' filter should + always be used to preprocess the coverage map data before passing it to cov- + + + 37 +Migrating from v3.0 to v3.1 Migrating from v3.0 to v3.1 + + + parser. This can be done by adding a call to traceutils with the -f option before + calling covparser. For example: + traceutils -f map.memdump.flt mem_covmap.txt -o covmap.rpz + covparser report.rvd --map covmap.rpz + + + 38 + diff --git a/docs-extracted/src/scov/RVS/doc/RapiTask/RapiTask_User_Guide.md b/docs-extracted/src/scov/RVS/doc/RapiTask/RapiTask_User_Guide.md new file mode 100644 index 000000000..6a3b43494 --- /dev/null +++ b/docs-extracted/src/scov/RVS/doc/RapiTask/RapiTask_User_Guide.md @@ -0,0 +1,1309 @@ +--- +title: "Rapitask User Guide" +source: "./src/scov/RVS/doc/RapiTask/RapiTask_User_Guide.pdf" +category: "src/scov/RVS/doc/RapiTask" +pages: 44 +extracted: "2026-07-06T23:15:57.218312" +--- + +# Rapitask User Guide + +> Extracted from `./src/scov/RVS/doc/RapiTask/RapiTask_User_Guide.pdf` (44 pages). +> Figures, diagrams, and tables may not render accurately in plain text. + +User Guide + Version WF20190404 +Disclaimer +The information, text, and graphics contained within this document are +provided for information purposes only by Rapita Systems Ltd. Rapita +Systems Ltd. does not warrant the accuracy or completeness of the +information, text, and other items contained in this document. + + +Copyright and Trademarks +All rights reserved. Information and images contained within this docu- +ment are copyright and the property of Rapita Systems Ltd. or Percepio +AB. All trademarks are hereby acknowledged to be the properties of +their respective owners. + + +Acknowledgements +RapiTask is built using Percepio AB technology. Rapita Systems' tools +are built using AdaCore's GNAT Pro compiler. + + +Rapita Systems Ltd. +Registered in the UK, number 5011090. +Registered address: +Atlas House +Link Business Park +Osbaldwick Link Road +York +YO10 3JB +UK +Phone: +44 (0) 1904 413 945 +http://www.rapitasystems.com/ +This document copyright © 2012-2019, Rapita Systems Ltd. + +Document build 118520 + +ID: DOC/12055 + Table of Contents + + 1. About this guide ............................................................... 5 + 1.1. Who should read this guide? ................................................... 5 + + 1.2. Structure of this guide ........................................................... 5 + + 1.3. Notation ............................................................................ 6 + + 1.4. RVS documentation map ........................................................ 6 + + 1.5. Support ............................................................................. 8 + + + 2. What is RapiTask? ............................................................ 9 + 2.1. Using RVS ......................................................................... 9 + + 2.2. Using RapiTask .................................................................. 13 + + + 3. Using RapiTask to produce results .................................. 15 + 3.1. Setting up RapiTask ............................................................. 15 + + 3.2. Creating a project ............................................................... 15 + + 3.3. Deploying an integration ....................................................... 17 + + 3.4. Preparing an integration ........................................................ 17 + + 3.5. Setting entry point(s) ............................................................ 18 + + 3.6. Refining your analysis .......................................................... 19 + + 3.7. Running an integration ......................................................... 19 + + 3.8. Configuring a project ........................................................... 20 + + + 4. Analyzing scheduling results ........................................... 23 + + 5. RapiTask Viewer .............................................................. 27 + 5.1. Starting RapiTask Viewer ....................................................... 27 + + 5.2. Using RapiTask Viewer ......................................................... 27 + + +RapiTask User Guide vWF20190404 3 + Table of Contents + + + 5.3. Terminology ...................................................................... 29 + + 5.4. Main Window .................................................................... 29 + + 5.5. Finder window ................................................................... 32 + + 5.6. CPU Load Graph ................................................................ 33 + + 5.7. Scheduling Intensity ............................................................. 34 + + 5.8. Actor Instance Graphs ......................................................... 35 + + + 6. Collecting data without instrumenting tasks .................... 37 + 6.1. Instrumenting the context switch routine ..................................... 37 + + 6.2. Producing trace files ............................................................ 38 + + 6.3. Converting trace files to XML trace files ..................................... 38 + + 6.4. Analyzing results ................................................................ 39 + + + 7. Using the command-line ................................................. 41 + + 8. Troubleshooting .............................................................. 43 + + +4 RapiTask User Guide vWF20190404 +1 About this guide + The RapiTask User Guide describes how to use RapiTask to obtain system sched- + uling information while running software on an embedded target or simulator. Fur- + ther, it describes how to view and analyze RapiTask results. + +1.1 Who should read this guide? + This document is intended for RVS users who have an existing RapiTask integration + and want to use this to obtain system scheduling information when they run their + software. + +1.2 Structure of this guide + Chapter 1: About this guide + Describes the purpose and layout of the RapiTask User Guide and the notation + used throughout the document. + + Chapter 2: What is RapiTask? + Describes the features of RapiTask and the process it uses to determine the sched- + uling behavior of embedded software. + + Chapter 3: Using RapiTask to produce results + Describes how to set up RapiTask, and how to use it to create and run a project + to collect scheduling data. + + Chapter 4: Analyzing scheduling results + Explains how to view and compare reports, and how to copy and export report + data to various file formats. + + Chapter 5: RapiTask Viewer + Describes how to use the RapiTask Viewer to analyze RapiTask data. + + Chapter 6: Collecting data without instrumenting tasks + Describes how to use RapiTask to collect task-level scheduling information without + needing to instrument individual tasks in your system. + + Chapter 7: Using the command-line + Describes how to use RapiTask from the command-line. + + Chapter 8: Troubleshooting + Describes how to troubleshoot problems you encounter while using RapiTask. + + +RapiTask User Guide vWF20190404 5 +Notation About this guide + + +1.3 Notation + This document uses the following notation: + • References to other documents and to other chapters or sections in this doc- + ument are written in italics, for example Chapter 1: About this guide. When + reading an electronic copy of this document, you can click on a reference to + navigate to the location of the referenced element. + • Names of RVS applications are formatted in bold italics, for example RVS + Project Manager. + • References to areas or elements in user interfaces are formatted in italics, for + example the Report Navigator. + • Menus, menu choices and button labels are formatted in bold, for example + File » Print or OK. Where buttons have icons, these are shown before their + Label in in-line text, for example Save. + • Names of RVS tools are formatted in bold, for example rvsdriver. + • References to HTML links appear as underlined text, for example + www.rapitasystems.com. + • Folder and file names are formatted in a monospaced font. + • Command-line tools and their commands, annotations and examples are for- + matted in a monospaced font. These are either written in-line with text + or as separate text blocks. When written in-line with text, they are formatted + like the following: rvsdriver, default_instrument, rvs_instr.h. + When written as a separate text block, they are formatted like the examples + below: + rvsdriver --project rvs.rvsprj --all + + #pragma RVS instrument( "function_name", "FALSE" ) + + • When referencing Ada code, the term functions refers to both functions and + procedures. + +1.4 RVS documentation map + This document is part of the Rapita Verification Suite (RVS) document set, which + contains the following documents: + + RVS Installation and Licensing Guide + Describes how to install RVS tools, and licensing options for them. + + RVS Integration Guide + Describes how to integrate RVS tools into build and target environments. + + RVS User Guide + Describes how to set up and run RVS projects, analyze data and export verification + results. + + +6 RapiTask User Guide vWF20190404 +About this guide RVS documentation map + + + RapiTest User Guide + Describes how to use RapiTest to manage test projects. + + Spreadsheet Test Format User Guide + Describes how to write tests for RapiTest in the Spreadsheet Test Format. + + RapiCover User Guide + Describes how to use RapiCover to measure code coverage and address cover- + age holes. + + RapiTime User Guide + Describes how to use RapiTime to measure timing metrics including worst-case + execution time, and how to use these metrics to identify the best optimization + candidates. + + RapiTask User Guide + Describes how to use RapiTask to measure system level task timing information, + visualize traces and gain insight into runtime behavior. + + RTBx 2xxx User Guide + Describes how to use the RTBx data logger. + + RVS Integration Library Implementation Guide + Describes how to implement RVS integration libraries. This document is for use by + readers with a thorough understanding of the implementation of RVS. + + RVS Files Reference Guide + Describes RVS-specific files including input, intermediate and output files. + + RVS Filters Guide + Describes RVS filters, which are used to convert raw trace data into a format that + RVS can analyze, and how to write them. + + RVS Command Line Tools Reference Guide + Describes the command-line tools used by RVS, including a list of available com- + mand options. + + RVS Annotations Reference Guide + Describes the annotations you can use to control instrumentation and analysis + with RVS. + + RVS Troubleshooting Guide + Describes the error and warning messages you may encounter when using RVS + tools, and how to address them. + + RVS Migration Guide + Describes how to migrate between using different versions of RVS. + + +RapiTask User Guide vWF20190404 7 +Support About this guide + + +1.5 Support + For support issues, please contact Rapita Systems Ltd. by any of the following + means: + + Email + support@rapitasystems.com + + Telephone + +44 (0) 1904 413 945 + + Website + www.rapitasystems.com + + To register for support, visit www.rapitasystems.com/register. More than one user + can register per license. + + +8 RapiTask User Guide vWF20190404 +2 What is RapiTask? + RapiTask is a Rapita Verification Suite (RVS) tool designed to collect detailed sys- + tem level task timing information while embedded software runs on target or on + a cycle-accurate simulator. + + RapiTask can analyze tested software to produce a range of scheduling metrics + including the following: + • Core utilization – the number of cores each task ran on. + • CPU utilization – the percentage of CPU utilization for each task on the cores + it ran on. + • Execution time – the time taken to complete each task, excluding time when + the task was not running. + • Response time – the time taken to complete each task, including time when + the task was not running. + • Periodicity – the time between successive executions of each task, counting + from each time it started to the next. + • Separation time – the time between completion of each task and the time it + next started. + • Fragmentation – the number of fragments each task was executed in. + + RapiTask integrates with existing build systems and targets. The RVS Project Man- + ager included with RapiTask lets you apply scheduling instrumentation to your + source code, run your build system to produce result data, and analyze results. + Alternatively, you can run RapiTask through the command-line. + + This chapter describes the key features of the Rapita Verification Suite (RVS), the + suite of verification tools that RapiTask is a part of, before describing the key fea- + tures of RapiTask itself. RVS has core features that determine, in part, how to use + RapiTask. These features are described in the next section. + +2.1 Using RVS + To use RVS, it must be integrated into your existing target build system so you + can collect verification data when you run your code on target. Alternatively, you + can use RVS on host architectures or with simulators. For more information on + RVS integrations, see the RVS Integration Guide. After RVS has been installed and + integrated into your development environment, you can use RVS tools to produce, + analyze and export verification results. A high-level overview of the stages involved + in using RVS is shown in Figure 2.1. + + +RapiTask User Guide vWF20190404 9 +Using RVS What is RapiTask? + + + Figure 2.1: Overview of using RVS + + You can use RVS from both the RVS Project Manager user-interface and com- + mand-line scripts. The RVS User Guide describes how to use these tools in detail. + +2.1.1 Testing with RVS + RVS tools collect verification data during software tests including the following + types: + • System tests – tests of the entire system to ensure that its overall functional + behavior meets high-level requirements. + • Integration tests – tests of the integration between software components to + ensure that they interact properly. + • Unit tests – tests of individual software components designed to ensure that + they meet low-level requirements. + +2.1.2 RVS projects + RVS projects store data about your source code, RVS Integrations and Analyses + that you configure, and settings you provide RVS about your Target. This informa- + tion is all stored in a project file that has the .rvsprj extension. + + The structure of RVS project files is designed to reduce the effort needed for your + testing processes. Settings are grouped into Project, Integration, Analysis + + +10 RapiTask User Guide vWF20190404 +What is RapiTask? Using RVS + + + and Target settings. Each RVS project can have any number of Integrations, + Analyses and Targets. + + Each RVS Integration uses a single Analysis on a single Target. This hierarchical + structure lets you reuse Analyses and Targets between different Integrations, re- + ducing the number of options you must select when configuring new Integrations, + as shown in Figure 2.2. + + + Figure 2.2: RVS integration hierarchy + + As an example, you may want to run both coverage and timing analysis on your + source code, both on your target and host systems. Because timing metrics col- + lected on your host system would not be very useful, you decide not to run timing + integrations on your host system. In this example, you could create the following + integrations: + • Coverage-host + • Coverage-target + • Timing-target + + Because of the RVS project file structure, you need only configure settings for two + targets and two analyses in your project file, and enter an Integration Name for + each of your integrations. + +2.1.3 RVS integrations + In an RVS integration, a specific RVS Analysis is run on a specific Target. This is + done over several discrete stages, as shown in Figure 2.3. Understanding these + stages will help you get the most from RVS. + + +RapiTask User Guide vWF20190404 11 +Using RVS What is RapiTask? + + + Figure 2.3: The RVS workflow + + RVS projects have two distinct workflows, as shown in Figure 2.3. The dual-pass + integration mode is the default and recommended mode. In this mode, you can run + static and dynamic analyses at separate steps, so you need only run static analysis + once during your project rather than each time you run a new integration. This may + save you a lot of computational effort. In the single-pass integration mode, you + must carry out static and dynamic analyses at the same time. + + Figure 2.3 shows the stages of RVS integrations. Some or all of these stages are + carried out when you run RVS, depending on which options RVS is called with. + The actions carried out in each RVS stage are described below: + • Deploy – the folders and integration library needed to run an integration are + created. + • Clean – intermediate files are deleted from integration folders. + • Prepare – source code files are statically analyzed. + • Build – source code files are instrumented, and compiled and linked into ex- + ecutable files that will work on target. + + +12 RapiTask User Guide vWF20190404 +What is RapiTask? Using RapiTask + + + • Run – instrumented executable files from the build stage are run on target. + • Report – verification data obtained from running executable code on target is + written into a report file that can be viewed in the RVS Project Manager. + • Export – verification data obtained from running executable code on target is + written to an output file. + + You can invoke the stages above from both the RVS Project Manager and the + command-line. When you invoke a stage, a script customized to work with the + specific build and target system is run. Because this script is customized, the + workflow shown in Figure 2.3 is applicable to any development environment. + +2.2 Using RapiTask + This section describes key features of using RapiTask. + +2.2.1 How does RapiTask work? + In the standard workflow, RapiTask takes a copy of input source code and injects + additional code into it. The injected code instruments the source code for sched- + uling analysis. The code is compiled and linked into an executable that is run on + the target hardware or simulator. While the executable is run, scheduling data is + collected. Finally, this is written to an output report. This process is summarized + in Figure 2.4. + + + Figure 2.4: How RapiTask works + + In the code injection stage, RapiTask injects instrumentation points (ipoints) in- + to source code. When instrumented code is compiled and linked, ipoints are ex- + panded so scheduling data can be collected when the executable is run on tar- + + +RapiTask User Guide vWF20190404 13 +Using RapiTask What is RapiTask? + + + get. How ipoints are expanded is specific to the target the code is run on and the + method used to collect data. These concepts are discussed in more detail in the + RVS Integration Guide. + +2.2.2 Analyzing scheduling behavior + RapiTask lets you analyze the scheduling behavior in your system so you can iden- + tify problem areas and focus optimization efforts where they will have the most + effect. + + If a task in your software never executes, RapiTask can determine the reason why. + This may be, for example, because higher priority tasks use all the CPU time and + the scheduler never lets the task execute. By identifying this automatically, Rapi- + Task reduces the effort you need to spend to fix the problem. + + If your system runs too slow, you can identify why using RapiTask charts and the + trace view. This may show, for example, that a task is suffering interference from + other tasks or interrupts and has become a bottleneck. You can use this informa- + tion to focus your efforts optimizing the areas of code that actually contribute to + slow execution. + + +14 RapiTask User Guide vWF20190404 + Using RapiTask to +3 produce results + This chapter describes what you need to do to set up a RapiTask project and run + it to produce results. It contains the following sections: + • Setting up RapiTask + • Creating a project + • Deploying an integration + • Preparing an integration + • Setting entry point(s) + • Refining your analysis + • Running an integration + • Configuring a project + +3.1 Setting up RapiTask + To use RapiTask you need to have RVS installed and integrated into your develop- + ment environment. This is outside the scope of this guide; for more information + on installing and integrating RVS see the RVS Installation and Licensing Guide and + RVS Integration Guide respectively. + +3.2 Creating a project + To create a RapiTask project, open the RVS Project Manager application. You can + do this on Windows systems from the Start menu (Start » RVS » RVS Project + Manager). + + When the RVS Project Manager opens for the first time, it opens on the Welcome + page, see Figure 3.1. From this page, create a new project by clicking Create + a new project in the Get started section. + + +RapiTask User Guide vWF20190404 15 +Creating a project Using RapiTask to produce results + + + Figure 3.1: RVS Project Manager Welcome page + + Tip + + If the Welcome page is not open, you can open it by opening the Help + menu and selecting Welcome Page. + + Alternatively, you can create a New RVS Project from the File menu. + + + The New RVS Project Wizard opens, which guides you through project creation. + For a description of each of the options available when you create a new project, + read the on-screen help text or see Section 4.2 in the RVS User Guide. When + prompted, select the Scheduling analysis task and a default profile suitable for + your needs, see Figure 3.2. + + + Figure 3.2: Scheduling analysis settings + + +16 RapiTask User Guide vWF20190404 +Using RapiTask to produce results Deploying an integration + + + Tip + + Mandatory settings in the New RVS Project Wizard are formatted in bold + text. You cannot continue to the next page in the New RVS Project Wizard + unless you have entered all mandatory settings on the current page. Set- + tings in default text formatting are optional. + + When you finish creating your project, RapiTask creates a project folder and a + project file containing your settings on your file system. You can now run tests with + this project file using either the RVS Project Manager or the command-line. + +3.3 Deploying an integration + Before you can use RapiTask to analyze source code, you must deploy an RVS + integration library. Integration libraries contain definitions for RVS functions that tell + RapiTask how to instrument code and collect data from an executable when it runs. + + To deploy an integration using the RVS Project Manager, do the following: + 1. Open the project and select the Integration you want to deploy in the RVS + Project Manager. To change the active integration, use the Active integra- + tion drop-down menu on the project overview page. + 2. Click Deploy in the Actions section of the project overview page. + 3. Confirm by clicking OK. + + Note + + If your project has already been deployed, you must manually delete the in- + tegration library it is using before you can deploy it again. + + Integration libraries are deployed from a template depending on the settings in + the RVS project file. Templates are suitable for most on-host integrations out of + the box. If you want to use RapiTask to analyze software executed on embedded + hardware, however, you may need to edit your deployed integration library. This + should be carried out during the integration process – for more information, see + the RVS Integration Guide and RVS Integration Library Implementation Guide. + +3.4 Preparing an integration + In the Prepare stage of dual-pass integrations, RapiTask statically analyzes and + instruments source code. For more information on the RVS workflow, see Sec- + tion 2.1.3: RVS integrations. + + You only need to Prepare each project once throughout your testing process, + assuming your code does not change. + + To prepare an integration using the RVS Project Manager, do the following: + + +RapiTask User Guide vWF20190404 17 +Setting entry point(s) Using RapiTask to produce results + + + 1. Open the project and select the Integration you want to prepare in the + RVS Project Manager. To change the active integration, use the Active in- + tegration drop-down menu on the project overview page. + 2. Click Prepare in the Actions section of the project overview page. Alterna- + tively, click the Prepare button on the toolbar. + 3. On the dialog window that opens, select whether or not to Clean your inte- + gration and Enable console debug. We recommend that you clean your + integration, to ensure that all the files your integration requires are present. + 4. Confirm by clicking OK. + + + Figure 3.3: Preparing an integration + + When RapiTask prepares an integration, it collects static information about your + source code and writes this to a report. At this stage, you must set the entry point(s) + to your source code and can refine the analysis you want to apply before running + the integration to produce results. + +3.5 Setting entry point(s) + Before RapiTask can build and run your code to produce results, you must set + the entry point(s) to your source code. This lets RapiTask insert pragmas into your + source code that are needed to analyze the scheduling behavior of your code. + + To set entry point(s) to your source code, do the following: + 1. Open the project and select the Integration you want to set entry point(s) + for in the RVS Project Manager. To change the active integration, use the + Active integration drop-down menu on the project overview page. + 2. Select the Analysis tab at the bottom of the project overview page. + 3. Your source code is displayed in the Source code section on the left of the + window. You may not be able to see some nested entries. To expand an entry, + + +18 RapiTask User Guide vWF20190404 +Using RapiTask to produce results Refining your analysis + + + click the icon to the left of it. Select the function(s) you want to set as entry + points, right-click and select Add entry point(s). + 4. The functions are now displayed in the Analysis settings section on the right + of the window. To return to the project overview page, click the Overview tab + at the bottom of the window. + + + Figure 3.4: Setting an entry point + +3.6 Refining your analysis + Before running an integration, you may want to refine the analysis applied by Rap- + iTask, for example to configure the folders, files and functions in your source code + that RapiTask analyzes. To learn how to do so, see Chapter 5 in the RVS User Guide. + +3.7 Running an integration + When running an integration, RapiTask instruments source code for scheduling + analysis, builds instrumented source code into an executable, runs this and writes + the scheduling data obtained to a report file. + + It does this by executing multiple integration stages: Build, Run and Report. You + can run all of these stages together in the RVS Project Manager. For more infor- + mation on the RVS workflow, see Section 2.1.3: RVS integrations. + + To run an integration using the RVS Project Manager, do the following: + 1. Open the project and select the Integration you want to run in the RVS + Project Manager. To change the active integration, use the Active integra- + tion drop-down menu on the project overview page. + + +RapiTask User Guide vWF20190404 19 +Configuring a project Using RapiTask to produce results + + + 2. Click Build & Run in the Actions section of the project overview page. Alter- + natively, click the Build & Run button on the toolbar. + 3. On the dialog window that opens, select settings for the run. Instrumentation + is only applied to your source code if the Include instrumentation option is + checked. The Keep results from previous run option instructs RapiTask to + merge instrumentation data from previous runs into a combined report file. + 4. Confirm by clicking OK. + + Your results open automatically at the end of the run if Open results automatically + was checked. If not, open them by clicking the Results button on the toolbar. + For more information on viewing your results, see Chapter 4: Analyzing scheduling + results. + + Note + + In some cases, you may want to generate executable code using RapiTask + but not run it. If this is the case, you can execute the RVS Build stage with- + out executing the Run stage. To do this, select Build from the Project + menu or click the More actions button beside the Build & Run action + and select Build. + + After this, you will need to invoke the RVS Report stage to generate a re- + port. To do this, select Report from the Project menu or click the + More actions button beside the Build & Run action and select Re- + port. + + +3.8 Configuring a project + Some advanced configuration options are not available in the New RVS Project + Wizard. You may want to change these options for your project. + + To configure options for your project, click on the Configure button on the + project overview page. This opens the RVS Config Editor, see Figure 3.5. For more + information on configuration settings, see Section 4.11 in the RVS User Guide. + + +20 RapiTask User Guide vWF20190404 +Using RapiTask to produce results Configuring a project + + + Figure 3.5: The RVS Config Editor + + When you Save your configuration, your new settings are saved to your project + file. To return to the RVS Project Manager, click Close. + + +RapiTask User Guide vWF20190404 21 +This page intentionally left blank + Analyzing scheduling +4 results + Note + + This chapter provides a short introduction to viewing and analyzing Rapi- + Task results. For a comprehensive reference of features related to viewing + and analyzing results, see Chapter 6 in the RVS User Guide. + + + Note + + RVS includes prebuilt example reports that you can view and use to explore + the concepts in this chapter. To access these, open the Help menu » Exam- + ple Reports. + + + When RapiTask collects data from tests it outputs it into a report file with the .rvd + extension. You can view and analyze this data in the RVS Project Manager and + the RapiTask Viewer. + + To view RapiTask reports, first open the RVS Project Manager. You can do this on + Windows systems by using the Windows Start menu (Start » RVS » RVS Project + Manager). + + You can open a report file in the RVS Project Manager in multiple ways: + • If you have previously prepared or run a RapiTask integration, click the Re- + sults button on the toolbar. This opens the last report generated by RapiTask + for the selected integration. + • To open any report in your file system, open the File menu and select Open + Report, then select the report you want to open. + • To open a report you have viewed recently, open the File menu and the Recent + Reports submenu, then select the report you want to open. + + When you open your report, a report details window opens with the Overview tab + selected. This tab contains general information about your integration including + when it was run and which device it was run on. We recommend you check the + Overview tab to ensure you are viewing the correct report. + + Click the Tasks tab. A page opens showing the scheduling data collected when + your program was executed, see Figure 4.1. + + +RapiTask User Guide vWF20190404 23 + Analyzing scheduling results + + + Figure 4.1: Task Summary + + The chart at the top of this page shows the average CPU utilization for each task in + your source code. This is calculated as the time spent executing the task divided + by the total duration of the trace file. + + The table below the chart shows statistics about the tasks that executed. This + includes data on execution time, response time, periodicity, separation and frag- + mentation. By default, each column shows the average value. Expand the column + headings to show minimum and maximum values. + + Hover over each of the column headings to show a tooltip describing the metrics + in the report. These terms are described in more detail in Section 5.3: Terminology. + + Double-click on the name of a task in the task summary page. This filters the report + to show only data for that task, see Figure 4.2. + + +24 RapiTask User Guide vWF20190404 +Analyzing scheduling results + + + Figure 4.2: Task View, showing CPU Utilization over time + + When viewing a single Task, the chart shows CPU utilization over time. The width + of the slices can be changed in the Report Properties dialog, accessible via the + spanner icon at the top of the page. + + Click the RapiTask Viewer icon on the toolbar. This opens the RapiTask Viewer, + which you can use to investigate the scheduling behavior of your program in detail. + + Click the Synchronize button. This synchronizes the RVS Project Manager + and the RapiTask Viewer. While the applications are synchronized, clicking on a + blue dot by a task in the RVS Project Manager jumps to that time in the RapiTask + Viewer, and clicking on an element in the RapiTask Viewer opens it in the RVS + Project Manager. + + The RapiTask Viewer provides more in-depth graphs and tables showing the + scheduling behavior of your system, see Chapter 5: RapiTask Viewer. + + This chapter provided a short introduction to viewing RapiTask results. For a com- + prehensive reference of features related to viewing and analyzing results, see + Chapter 6 in the RVS User Guide. + + +RapiTask User Guide vWF20190404 25 +This page intentionally left blank +5 RapiTask Viewer + + + Figure 5.1: RapiTask Overview + + RapiTask provides several interlinked views of the runtime behavior of your appli- + cation. RapiTask shows information about the scheduling and timing of tasks and + interrupts. + + RapiTask contains several advanced features that help you to quickly understand + your trace data. For instance, RapiTask provides various high level views such as + the CPU load graph that make it easier to find anomalies in a trace. + +5.1 Starting RapiTask Viewer + When viewing a RapiTask report, the RapiTask toolbar provides access to the Rap- + iTask Viewer. Figure 5.2 shows the location of this toolbar. + + + Figure 5.2: RapiTask Toolbar + + The first button opens the RapiTask Viewer, while the second button synchronizes + the two applications: + • Clicking on a cell containing a blue dot in the RVS Project Manager jumps to + that time in the RapiTask Viewer. + • Clicking on an element in the RapiTask Viewer opens it in the RVS Project + Manager. + +5.2 Using RapiTask Viewer + RapiTask provides several graphical views which give different perspectives of the + system's runtime behavior. These views are based on a trace of task scheduling + + +RapiTask User Guide vWF20190404 27 +Using RapiTask Viewer RapiTask Viewer + + + and function calls. You may also choose to include interrupt service routines (ISRs) + as well as application events. + + This section gives a quick overview of the available features. More detailed infor- + mation is given in later sections. + + + Figure 5.3: Main View, containing the trace view (left) and the tool panel (right) + + The main trace view provides all recorded information on a vertical time line. This + view is complemented by several additional views providing high level overviews + or focused views from different perspectives. The task scheduling is presented + using color coded rectangles, where the color helps identify the actor. By actor we + mean a thread of execution: a task or interrupt. + + +28 RapiTask User Guide vWF20190404 +RapiTask Viewer Terminology + + +5.3 Terminology + Actor A task or an Interrupt Service Routine (ISR) + or function. + Actor Instance An execution of an actor. For interrupt ser- + vice routines, this means from start to fin- + ish of the ISR handler. For tasks, this is ap- + plication-dependent but typically means + one iteration in the main loop. An Actor In- + stance consists of one or more fragments, + depending on preemptions, blocking and + interrupts. + Execution Time The amount of CPU time used by an Actor + Instance, excluding preemptions. + Response Time The wall-clock time from the start of an ac- + tor instance until it finishes. Note that the + Response Time is counted from the start + of execution, not from when the task be- + comes ready to execute. + Fragment A time interval when a specific actor exe- + cutes uninterrupted. Fragments are visual- + ized as colored rectangles in the schedul- + ing trace. A fragment belongs to a specific + Actor Instance. + Fragmentation The number of fragments within an Actor + Instance. If an Actor Instance executes in + full without preemptions, the fragmentation + of the instance is 1. + ISR Interrupt Service Routine, i.e. the handler of + an interrupt. + Periodicity The time between two consecutive in- + stances of an actor, counted from the start + of the previous actor instance to the start of + the current actor instance. + Separation The time between two consecutive in- + stances of an actor, counted from the end + of the previous actor instance to the start of + the current actor instance. + + +5.4 Main Window +5.4.1 Trace View + Figure 5.3 shows the main view of RapiTask. All of the recorded events are present- + ed on a vertical time-line going downwards. The main component of this view is an + execution trace, which displays actor fragments as color-coded rectangles. The + colors are unique for each actor, and are assigned based on scheduling priority. + + +RapiTask User Guide vWF20190404 29 +Main Window RapiTask Viewer + + + To the left of Figure 5.3 are labels showing actor names. When zooming out, the + name labels are filtered so that only some are shown. Repeated labels of the same + actor are hidden, in favor of labels for less frequent actors. However, there is always + at least one label per visible actor, and you can click in the trace to show the + corresponding actor name label. + + Double-clicking on an actor opens a focused view showing all instances of the + actor. + + View Modes + + The execution of tasks and interrupts can be visualized using three view modes, + which you can switch between quickly to optimize the display according to your + requirements. The modes are: + • Split View Mode: Shows tasks and interrupts in two columns, with indentation + like the Merged View Mode. This removes the "noise" from interrupts by pre- + senting them separately. This is the default visualization mode. (Shortcut: S.) + • Gantt View Mode: Shows one column per task and interrupt. This is the pre- + ferred view mode for spotting rare actor instances and for visualizing periodic + behavior. (Shortcut: G.) + • Merged View Mode: Shows all tasks and interrupts in a single column, with + sideways indentation to show preemption and blocking. This gives the best + sense of execution order. (Shortcut: M.) + + Zoom and navigation features + + To navigate the trace, you can use the mouse wheel or the scroll bar (on the right). + You can also drag the view by holding down the mouse wheel or middle mouse + button. The arrow buttons and page up/down buttons can also be used when the + main trace view area has focus. + + Note + + When searching for a particular location, it is often easiest to use the Finder + (Section 5.5) or one of the graphical overviews to find it. When using anoth- + er view to navigate the trace, you can click or double-click to focus the trace + view on this location. All graphical views also support selecting a time inter- + val (by pressing the left mouse button and dragging) and showing this inter- + val in the trace view. + + + To zoom in or out, use the zoom buttons on the tool panel, the number pad + and + - buttons or the zoom options in the right-click menu. You can also zoom with your + mouse wheel when holding down the CTRL key. The scroll-to-zoom behavior is + always active when Scroll Lock is enabled. If your mouse features back and + forward buttons, you can use these to zoom in and out quickly. + + +30 RapiTask User Guide vWF20190404 +RapiTask Viewer Main Window + + + Tool Panel + + To the right of the trace view is the tool panel. At the top is the Actor Information + display (Figure 5.4), which shows information about the selected actor and the + currently selected actor instance (such as timing, fragmentation and any events + that occur). Property values for the selected instance are displayed as well as actor + average, maximum and minimum execution time. Double-clicking on maximum or + minimum values shows the corresponding instance in the trace. + + + Figure 5.4: Actor information + + Below the Actor Information display are buttons to navigate to the previous and + next instance of the same actor. + + You can set the view size (zoom level) by typing the desired view size into the view + size text box and pressing enter. Under the view size setting are the grid settings, + used to control the white and gray stripes in the trace view. The stripes show the + time scale of the grid in the trace view. + + Below the view settings are buttons to zoom in and out. Below these zoom buttons + are a series of three controls to allow the view mode to be set. From left to right, + the controls set Gantt view mode, Merged view mode and Split view mode. + + At the bottom of the tool panel is the visibility filter box, which controls what is + displayed in the trace view. By default; all actors are visible. Unchecking an actor + will not hide it completely, but cause its fragments to be drawn as outlined gray + rectangles. + + +RapiTask User Guide vWF20190404 31 +Finder window RapiTask Viewer + + +5.4.2 Menu options + File + + The File menu features standard options such as Reload File and Exit. It also + includes the specialized options Save Current View As Image and Export Actor + Data. + + Save Current View As Image lets you export the current trace view to an image, + e.g. for documentation or for sharing an issue with colleagues. + + Export Actor Data lets you export actor instance data to a text file. The exported + data includes start time, execution time, response time and fragmentation of each + instance of the selected actors. You can export it as tab separated fields for import + into other tools, or space aligned columns for easy reading. + + Find + + The Find menu lets you find previous or next instances quickly from a selected + instance. It also lets you open the Finder dialog, which you can also open using + the shortcut CTRL-F. + + View + + The View menu lets you configure the trace view and open other views. These + other views are described in Section 5.6 through Section 5.8. + + Trace Details shows properties of the current trace, such as the number of events, + the length of the trace and other technical details. + + Trace View Settings lets you configure the trace view, such as the colors of actors + and whether to display bookmarks or not. + + Trace View Mode lets you set the View Mode (e.g. Gantt or Split) as described + above. + + Show Tool Panel lets you toggle the visibility of the tool panel to the right. This can + be useful if you want to make the application window smaller, e.g. when multiple + views are open. + + Bookmarks + + The Bookmark menu lets you create and organize bookmarks. If you want to share + bookmarks with colleagues, you can export and import them using the respective + menu options. Any bookmarks will also be displayed in this menu. + +5.5 Finder window +5.5.1 Overview + The Finder window lets you find actor instances quickly by using various filters. + The Finder also lets you jump to particular points in time. + + +32 RapiTask User Guide vWF20190404 +RapiTask Viewer CPU Load Graph + + + Figure 5.5: Finder view + +5.5.2 Actor Instances Tab + The Actor Instances tab lets you find and follow actor instances matching various + search criteria. + + To the left is a list of actors in the trace. Select one or more actors to obtain a list + of instances. You can select multiple actors by holding down CTRL and clicking. + When one or more actors are selected, the navigation buttons are enabled. + + To the right is a filter which is enabled when a single actor is selected. Only in- + stances where the values are between the At Least and At Most values are + included in the search. By default, the boxes contain the lowest and highest value + of all instances, so that all instances are included. Note that the filter is not avail- + able if you have multiple actors selected. + +5.5.3 Time Point Tab + The Time Point tab lets you jump to a specific point in the trace by entering a + timestamp and pressing Enter. + +5.6 CPU Load Graph +5.6.1 Overview + The CPU Load Graph displays CPU usage over time, per actor and in total. By + default, it shows all actors except the idle task. The analysis works by dividing the + trace into a number of intervals (the default is 100). The CPU usage for an actor in + an interval is the amount of CPU time used by the actor within the interval divided + by the length of the interval. For each interval, all actors that execute in that interval + are drawn as rectangles stacked on top of each other. The height of each actor's + rectangle represents the CPU usage for that actor in that time interval and the + combined height is the total CPU usage for that interval. + + +RapiTask User Guide vWF20190404 33 +Scheduling Intensity RapiTask Viewer + + + Figure 5.6: CPU load graph + + To customize the view, use the Select Actor(s) menu. There you can select which + actors you wish to include in the view. If the graph is "noisy" (due to short intervals), + you can reduce the number of intervals through the Resolution menu. For a more + detailed graph, you can increase the number of intervals by selecting a higher + resolution. In order to focus on a specific area, you can click and drag to select + an interval and use the Zoom menu or right-click to zoom in on it. You can also + use the Zoom or right-click menu to show the selection or current view in the trace + view or in all open views. + + Clicking an actor in the graph will display information about that actor in the clicked + interval, and double-clicking an actor will center the trace view on that interval. A + gray outlined rectangle shows the interval of the current trace view. This rectangle + may be very narrow and appear as a line if the trace view is small. In this case, + you can zoom in to show the interval in more detail. + +5.7 Scheduling Intensity +5.7.1 Overview + This view displays the frequency of context switches over time. By default, it shows + the whole trace divided into 100 intervals. For each time interval, a bar is drawn + for each actor beginning or resuming execution at least once in that interval. The + height of the bars represents the number of times that actor has begun or resumed + execution in the given interval, i.e., the number of fragments of the actor. + + The number of intervals can be controlled through the Resolution menu. You can + click and drag to select an interval and use the Zoom or right-click menu to zoom + in on that selection, to show it in the trace view or to show it in all open views. + + +34 RapiTask User Guide vWF20190404 +RapiTask Viewer Actor Instance Graphs + + + Note + + When zooming in the Scheduling Intensity view, the interval length decreas- + es to show a more detailed graph. When significantly zoomed, or if your + trace is short, you might get empty space in the graph corresponding to in- + tervals where no context switches occur. + + +5.8 Actor Instance Graphs +5.8.1 Overview + The Actor Instance Graph window displays a graph showing timing properties of + actor instances: execution time, response time, response interference and frag- + mentation. Each data point in the graph represents a specific actor instance, where + the x-axis indicates the instance start time and the y-axis the property value. + • Execution Time: The amount of CPU time used by an actor instance, exclud- + ing preemptions. + • Response Time: The wall-clock time from the start of an actor instance until it + finishes. Note that the Response Time is counted from the start of execution, + not from when the task becomes ready to execute. + • Response Interference: The relation between execution time and response + time. A value of 30% means that the response time is 30% longer than the + execution time, i.e., due to preempting tasks, interrupts or blocking. A value of + 0% means that the response time is equal to the execution time, i.e., that the + actor instance executed to completion without context switches. + • Fragmentation: The number of fragments within an actor instance, e.g., due + to context switching. If an actor instance executes in full without preemptions, + the fragmentation of the instance is 1. + + Clicking a plotted instance will show and highlight it in the trace view. You can filter + actors using the Filter menu or by clicking on an actor in the legend to the right. + + If you want to focus on a specific area, you can click and drag to select an interval + and use the Zoom menu or right-click to zoom in on it. You can also use the Zoom + or right-click menu to show the selection or current view in the trace view or in all + open views. + + This view can be used to identify long-running tasks using the execution and re- + sponse time graphs, or potential scheduling problems using the fragmentation + and interference graphs. + + +RapiTask User Guide vWF20190404 35 +This page intentionally left blank + Collecting data without +6 instrumenting tasks + When collecting system event traces, you may not be able to instrument the in- + dividual tasks in your system, or may not want to so that you can collect results + in fewer builds on resource-constrained targets. To support this, RapiTask has an + OS-only mode that only requires you to instrument your system's context switch + routine, and not the individual tasks in your system, see Figure 6.1. + + + Figure 6.1: Collecting task-level timing data without instrumenting tasks + + This chapter describes how to set up, run, and analyze results from a RapiTask + OS-only mode analysis, which involves the following steps: + 1. Instrumenting the context switch routine + 2. Producing trace files + 3. Converting trace files to XML trace files + 4. Analyzing results + +6.1 Instrumenting the context switch routine + To collect task-level timing without instrumenting the tasks in your system, your + system's context switch routine must be manually instrumented so that it includes + an RVS instrumentation point marking the start and end of execution of each task. + + Unlike when using RapiTask normally, instrumentation of the context switch routine + must be applied manually. The following example shows a simple context switch + routine instrumented appropriately. + + +RapiTask User Guide vWF20190404 37 +Producing trace files Collecting data without instrumenting tasks + + + Example 6.1: Context switch routine instrumentation + + void TaskSwitchContext( void ) + { + RVS_I(5); // Context switch out + + // Find the highest priority task pending and switch to it + TopReadyPriority = TopPriority; + while( ReadyTasksLists[ TopReadyPriority ].Pending == 0 ) + { + TopReadyPriority -= 1; + } + TaskSwitchFrames(CurrentTask, + ReadyTasksLists[ TopReadyPriority ]); + CurrentTask = ReadyTasksLists[ TopReadyPriority ]; + + RVS_I(6); // Context switch in + RVS_I(CurrentTask.Ident); // New task ID + } + + + If you need help instrumenting your context switch routine, contact + support@rapitasystems.com. + +6.2 Producing trace files + When instrumented appropriately, one or more Rapita Systems trace (RPZ) files + will be produced while your system is running. These are needed for further analy- + sis. + +6.3 Converting trace files to XML trace files + To analyze results from RapiTask when used in OS-only mode, you must first pro- + duce an XML trace (XMLTRC) file by converting the Rapita Systems trace (RPZ) + files produced during the analysis. To do this, you can use the RVS command-line + tool taskparser_os. + + taskparser_os produces XMLTRC files, requiring the following as inputs: + • One or more Rapita Systems trace (RPZ) files. + • The system's clock frequency, in Hertz. + • A task list file containing a list of mappings between task IDs in input RPZ + files and task names in the output XMLTRC file. + + The task list file must be in a comma separated format, with newlines between + subsequent tasks, as in the following example: + + +38 RapiTask User Guide vWF20190404 +Collecting data without instrumenting tasks Analyzing results + + + Example 6.2: Task list file syntax + + 100,HighTick + 200,Poller + 300,MidFast + 400,MidSlow + 500,Background + + + The example below shows how to convert the trace file trace1.rpz to + results.xmltrc using the mapping file mapping.txt: + + Example 6.3: Converting trace files to XML trace files + + taskparser_os trace1.rpz --task-list mapping.txt --clock-hz 50000000 + --output results.xmltrc + + + For more information on taskparser_os, see Chapter 17 in the RVS Command + Line Tools Reference Guide. + +6.4 Analyzing results + You can view XMLTRC files produced by RapiTask OS-only analysis in the Rapi- + Task Viewer. + + For more information on viewing results in the RapiTask Viewer, see Chapter 5: + RapiTask Viewer. + + +RapiTask User Guide vWF20190404 39 +This page intentionally left blank +7 Using the command-line + Whenever RapiTask is run, whether through the RVS Project Manager or the com- + mand-line, it is run using rvsdriver, which manages all of the back-end tools in- + volved in RVS integrations, see Section 2.1: Using RVS. + + The RVS Project Manager includes a Custom Command utility that makes it easy + to configure rvsdriver runs. You can use this utility to run custom commands from + within the RVS Project Manager or to generate scripts to use RVS outside the + RVS Project Manager. + + For more information on using the Custom Command utility, see Chapter 8 in the + RVS User Guide. + + +RapiTask User Guide vWF20190404 41 +This page intentionally left blank +8 Troubleshooting + This chapter describes what to do if you encounter any problems while using Rap- + iTask. + + Many problems that occur when using RapiTask are related to its integration with a + development and target environment. For information on the integration process, + see the RVS Integration Guide. + + If you receive a warning or error message while using RapiTask, you can look up + the cause of the error and learn how to resolve it in the RVS Troubleshooting Guide. + This document also describes known issues in RapiTask and other RVS tools. + + If you encounter a problem while using RapiTask, feel free to contact us at + support@rapitasystems.com or +44 (0) 1904 413 945. Please supply as + much information as possible about your problem, so we can resolve it promptly. + + For more information on the RVS troubleshooting process, see the RVS User + Guide. + + +RapiTask User Guide vWF20190404 43 +This page intentionally left blank + diff --git a/docs-extracted/src/scov/RVS/doc/RapiTest/RapiTest_User_Guide.md b/docs-extracted/src/scov/RVS/doc/RapiTest/RapiTest_User_Guide.md new file mode 100644 index 000000000..c14f5b7e4 --- /dev/null +++ b/docs-extracted/src/scov/RVS/doc/RapiTest/RapiTest_User_Guide.md @@ -0,0 +1,1211 @@ +--- +title: "Rapitest User Guide" +source: "./src/scov/RVS/doc/RapiTest/RapiTest_User_Guide.pdf" +category: "src/scov/RVS/doc/RapiTest" +pages: 42 +extracted: "2026-07-06T23:15:57.271775" +--- + +# Rapitest User Guide + +> Extracted from `./src/scov/RVS/doc/RapiTest/RapiTest_User_Guide.pdf` (42 pages). +> Figures, diagrams, and tables may not render accurately in plain text. + +User Guide + Version WF20190404 +Disclaimer +The information, text, and graphics contained within this document are +provided for information purposes only by Rapita Systems Ltd. Rapita +Systems Ltd. does not warrant the accuracy or completeness of the +information, text, and other items contained in this document. + + +Copyright and Trademarks +All rights reserved. Information and images contained within this doc- +ument are copyright and the property of Rapita Systems Ltd. All trade- +marks are hereby acknowledged to be the properties of their respective +owners. + + +Acknowledgments +Rapita Systems' tools are built using AdaCore's GNAT Pro compiler. + + +Rapita Systems Ltd. +Registered in the UK, number 5011090. +Registered address: +Atlas House +Link Business Park +Osbaldwick Link Road +York +YO10 3JB +UK +Phone: +44 (0) 1904 413 945 +http://www.rapitasystems.com/ +This document copyright © 2016-2019, Rapita Systems Ltd. + +Document build 118520 + +ID: DOC/16113 + Table of Contents + + 1. About this guide ............................................................... 5 + 1.1. Who should read this guide? ................................................... 5 + 1.2. Structure of this guide ........................................................... 5 + 1.3. RVS tutorials ....................................................................... 5 + 1.4. Notation ............................................................................ 6 + 1.5. RVS documentation map ........................................................ 6 + 1.6. Support ............................................................................. 8 + + + 2. What is RapiTest? ............................................................. 9 + 2.1. Using RVS ......................................................................... 9 + 2.2. Using RapiTest ................................................................... 13 + + + 3. Testing using RapiTest .................................................... 17 + 3.1. Introduction to managed testing .............................................. 17 + 3.2. Writing tests for RapiTest ....................................................... 19 + + + 4. Using RapiTest to produce results ................................... 21 + 4.1. Setting up RapiTest ............................................................. 21 + 4.2. Creating a project ............................................................... 21 + 4.3. Deploying an integration ....................................................... 23 + 4.4. Preparing an integration ........................................................ 23 + 4.5. Setting entry points ............................................................. 24 + 4.6. Adding tests ...................................................................... 26 + 4.7. Running an integration ......................................................... 28 + 4.8. Configuring a project ........................................................... 29 + + + 5. Analyzing test results ...................................................... 31 + +RapiTest User Guide vWF20190404 3 + Table of Contents + + + 6. Exporting results ............................................................. 37 + + 7. Using the command-line ................................................. 39 + + 8. Troubleshooting .............................................................. 41 + + +4 RapiTest User Guide vWF20190404 +1 About this guide + The RapiTest User Guide explains how to use RapiTest to manage testing process- + es during the development of software for critical systems. + +1.1 Who should read this guide? + This document is intended for users who already have an integration of RapiTest, + and want to use this to run and analyze results from tests. + +1.2 Structure of this guide + This document includes the following chapters: + + Chapter 1: About this guide + Describes the purpose and layout of the RapiTest User Guide and the notation + used throughout the document. + + Chapter 2: What is RapiTest? + Describes the features of RapiTest and the process it uses to apply and run re- + quirements-based tests. + + Chapter 3: Testing using RapiTest + Describes some concepts of testing with RapiTest, and how to write tests for use + with RapiTest. + + Chapter 4: Using RapiTest to produce results + Describes how to set up RapiTest, and how to use it to create and run a test project. + + Chapter 5: Analyzing test results + Describes how to analyze RapiTest test results using the RVS Project Manager. + + Chapter 6: Exporting results + Describes how to export results from RapiTest projects. + + Chapter 7: Using the command-line + Describes how to use RapiTest from the command-line. + + Chapter 8: Troubleshooting + Describes how to troubleshoot problems you encounter while using RapiTest. + +1.3 RVS tutorials + RVS comes with a set of tutorials that explain and demonstrate how to use RVS + through a series of practical exercises. + + +RapiTest User Guide vWF20190404 5 +Notation About this guide + + + You can access the RVS tutorials from the RVS Project Manager Welcome page + or Help menu. + + Tutorial + + Many sections of this guide include a Tutorial box. + + Each box highlights an RVS tutorial demonstrating the contents of the sec- + tion. + + +1.4 Notation + This document uses the following notation: + • References to other documents and to other chapters or sections in this doc- + ument are written in italics, for example Chapter 1: About this guide. When + reading an electronic copy of this document, you can click on a reference to + navigate to the location of the referenced element. + • Names of RVS applications are formatted in bold italics, for example RVS + Project Manager. + • References to areas or elements in user interfaces are formatted in italics, for + example the Report Navigator. + • Menus, menu choices and button labels are formatted in bold, for example + File » Print or OK. Where buttons have icons, these are shown before their + Label in in-line text, for example Save. + • Names of RVS tools are formatted in bold, for example rvsdriver. + • References to HTML links appear as underlined text, for example + www.rapitasystems.com. + • Folder and file names are formatted in a monospaced font. + • Command-line tools and their commands, annotations and examples are for- + matted in a monospaced font. These are either written in-line with text + or as separate text blocks. When written in-line with text, they are formatted + like the following: rvsdriver, default_instrument, rvs_instr.h. + When written as a separate text block, they are formatted like the examples + below: + rvsdriver --project rvs.rvsprj --all + + #pragma RVS instrument( "function_name", "FALSE" ) + + • When referencing Ada code, the term functions refers to both functions and + procedures. + +1.5 RVS documentation map + This document is part of the Rapita Verification Suite (RVS) document set, which + contains the following documents: + +6 RapiTest User Guide vWF20190404 +About this guide RVS documentation map + + + RVS Installation and Licensing Guide + Describes how to install RVS tools, and licensing options for them. + + RVS Integration Guide + Describes how to integrate RVS tools into build and target environments. + + RVS User Guide + Describes how to set up and run RVS projects, analyze data and export verification + results. + + RapiTest User Guide + Describes how to use RapiTest to manage test projects. + + Spreadsheet Test Format User Guide + Describes how to write tests for RapiTest in the Spreadsheet Test Format. + + RapiCover User Guide + Describes how to use RapiCover to measure code coverage and address cover- + age holes. + + RapiTime User Guide + Describes how to use RapiTime to measure timing metrics including worst-case + execution time, and how to use these metrics to identify the best optimization + candidates. + + RapiTask User Guide + Describes how to use RapiTask to measure system level task timing information, + visualize traces and gain insight into runtime behavior. + + RTBx 2xxx User Guide + Describes how to use the RTBx data logger. + + RVS Integration Library Implementation Guide + Describes how to implement RVS integration libraries. This document is for use by + readers with a thorough understanding of the implementation of RVS. + + RVS Files Reference Guide + Describes RVS-specific files including input, intermediate and output files. + + RVS Filters Guide + Describes RVS filters, which are used to convert raw trace data into a format that + RVS can analyze, and how to write them. + + RVS Command Line Tools Reference Guide + Describes the command-line tools used by RVS, including a list of available com- + mand options. + + +RapiTest User Guide vWF20190404 7 +Support About this guide + + + RVS Annotations Reference Guide + Describes the annotations you can use to control instrumentation and analysis + with RVS. + + RVS Troubleshooting Guide + Describes the error and warning messages you may encounter when using RVS + tools, and how to address them. + + RVS Migration Guide + Describes how to migrate between using different versions of RVS. + +1.6 Support + For support issues, please contact Rapita Systems Ltd. by any of the following + means: + + Email + support@rapitasystems.com + + Telephone + +44 (0) 1904 413 945 + + Website + www.rapitasystems.com + + To register for support, visit www.rapitasystems.com/register. More than one user + can register per license. + + +8 RapiTest User Guide vWF20190404 +2 What is RapiTest? + RapiTest is a Rapita Verification Suite (RVS) tool designed to manage and auto- + mate testing processes used in the development of software for critical embedded + systems. RapiTest integrates into an existing build environment to apply, run and + report data on software tests. + + RapiTest makes testing easier by providing a user interface to manage it. The RVS + Project Manager included in RapiTest lets you create and configure test projects, + run them to produce results, and analyze the results. Alternatively, you can run + RapiTest through the command-line. + + By integrating with other tools in the RVS suite, RapiTest can collect coverage, + timing and scheduling information from software tests encompassing both high + and low-level requirements. + + This chapter describes the key features of the Rapita Verification Suite (RVS), the + suite of verification tools that RapiTest is a part of, before describing the key fea- + tures of RapiTest itself. RVS has core features that determine, in part, how to use + RapiTest. These features are described in the next section. + +2.1 Using RVS + To use RVS, it must be integrated into your existing target build system so you + can collect verification data when you run your code on target. Alternatively, you + can use RVS on host architectures or with simulators. For more information on + RVS integrations, see the RVS Integration Guide. After RVS has been installed and + integrated into your development environment, you can use RVS tools to produce, + analyze and export verification results. A high-level overview of the stages involved + in using RVS is shown in Figure 2.1. + + +RapiTest User Guide vWF20190404 9 +Using RVS What is RapiTest? + + + Figure 2.1: Overview of using RVS + + You can use RVS from both the RVS Project Manager user-interface and com- + mand-line scripts. The RVS User Guide describes how to use these tools in detail. + +2.1.1 Testing with RVS + RVS tools collect verification data during software tests including the following + types: + • System tests – tests of the entire system to ensure that its overall functional + behavior meets high-level requirements. + • Integration tests – tests of the integration between software components to + ensure that they interact properly. + • Unit tests – tests of individual software components designed to ensure that + they meet low-level requirements. + +2.1.2 RVS projects + RVS projects store data about your source code, RVS Integrations and Analyses + that you configure, and settings you provide RVS about your Target. This informa- + tion is all stored in a project file that has the .rvsprj extension. + + The structure of RVS project files is designed to reduce the effort needed for your + testing processes. Settings are grouped into Project, Integration, Analysis + + +10 RapiTest User Guide vWF20190404 +What is RapiTest? Using RVS + + + and Target settings. Each RVS project can have any number of Integrations, + Analyses and Targets. + + Each RVS Integration uses a single Analysis on a single Target. This hierarchical + structure lets you reuse Analyses and Targets between different Integrations, re- + ducing the number of options you must select when configuring new Integrations, + as shown in Figure 2.2. + + + Figure 2.2: RVS integration hierarchy + + As an example, you may want to run both coverage and timing analysis on your + source code, both on your target and host systems. Because timing metrics col- + lected on your host system would not be very useful, you decide not to run timing + integrations on your host system. In this example, you could create the following + integrations: + • Coverage-host + • Coverage-target + • Timing-target + + Because of the RVS project file structure, you need only configure settings for two + targets and two analyses in your project file, and enter an Integration Name for + each of your integrations. + +2.1.3 RVS integrations + In an RVS integration, a specific RVS Analysis is run on a specific Target. This is + done over several discrete stages, as shown in Figure 2.3. Understanding these + stages will help you get the most from RVS. + + +RapiTest User Guide vWF20190404 11 +Using RVS What is RapiTest? + + + Figure 2.3: The RVS workflow + + RVS projects have two distinct workflows, as shown in Figure 2.3. The dual-pass + integration mode is the default and recommended mode. In this mode, you can run + static and dynamic analyses at separate steps, so you need only run static analysis + once during your project rather than each time you run a new integration. This may + save you a lot of computational effort. In the single-pass integration mode, you + must carry out static and dynamic analyses at the same time. + + Figure 2.3 shows the stages of RVS integrations. Some or all of these stages are + carried out when you run RVS, depending on which options RVS is called with. + The actions carried out in each RVS stage are described below: + • Deploy – the folders and integration library needed to run an integration are + created. + • Clean – intermediate files are deleted from integration folders. + • Prepare – source code files are statically analyzed. + • Build – source code files are instrumented, and compiled and linked into ex- + ecutable files that will work on target. + + +12 RapiTest User Guide vWF20190404 +What is RapiTest? Using RapiTest + + + • Run – instrumented executable files from the build stage are run on target. + • Report – verification data obtained from running executable code on target is + written into a report file that can be viewed in the RVS Project Manager. + • Export – verification data obtained from running executable code on target is + written to an output file. + + You can invoke the stages above from both the RVS Project Manager and the + command-line. When you invoke a stage, a script customized to work with the + specific build and target system is run. Because this script is customized, the + workflow shown in Figure 2.3 is applicable to any development environment. + +2.2 Using RapiTest + This section describes key features of using RapiTest during testing processes. + +2.2.1 How does RapiTest work? + For RapiTest to work, you must supply it with tests and source code. It uses the + tests you supply to inject framework code into a copy of your source code. The + framework code applies test behavior specified in the input tests. Framework code + is compiled and linked into a test harness that is run on the target hardware, host + system or simulator. While the test harness is run, verification data is collected. + Finally, this is written to an output report. This process is summarized in Figure 2.4. + + + Figure 2.4: How RapiTest works + +2.2.2 Managing the testing process + RapiTest reduces the effort needed to verify embedded software by letting you + write test cases, apply these to embedded targets, analyze and export results. + + +RapiTest User Guide vWF20190404 13 +Using RapiTest What is RapiTest? + + + The example below shows how you might use RapiTest throughout your develop- + ment pipeline. + + In this example, you are running RapiTest to verify your test requirements, and as + an outcome should achieve 100% structural code coverage. This may be helpful + if, for example, you need to certify a product against DO-178B/C objectives or ISO + 26262 requirements. These examples work on host, but there is no reason why + they could not run on an embedded target. + + In the first stage, you use RapiTest to test high-level requirements. System tests + typically carry the most weight as they verify the actual use of your software. + RapiTest works with your build system to instrument and run your code. This gen- + erates a report indicating the level of code coverage your system tests achieved. + You use this report to write unit test cases to address your missing code coverage. + + In the second stage, you use RapiTest to run the unit tests of your code. These tests + typically exercise your low-level requirements. You supply unit tests to RapiTest in + a format of you choice, and the tool converts this into test scripts. It then works + with your build system to instrument and run your code. You split your testing + into multiple builds and merge coverage into a single report. You use RapiTest to + merge your system and unit test coverage, indicating that you have almost 100% + coverage. + + In the third and final stage, you use RapiTest to justify your missing code coverage. + This missing coverage is due to untestable, defensive code. You use RapiTest to + write justifications for your missing code coverage. Finally, you merge coverage + from system and unit tests and justifications using RapiTest to produce a final + report. You submit this report, which shows that you achieved 100% structural + coverage of your code, as evidence during certification of your product. + + This example demonstrates that RapiTest is designed for use throughout your de- + velopment life cycle. RapiTest knows which sections of code you have tested, even + when you move code segments during development. Because of this, RapiTest + can be used for iterative testing and test-driven development. + +2.2.3 Coverage, timing and scheduling analysis + You can use RapiTest to analyze coverage, timing and scheduling during tests. + To apply these analyses, RapiTest uses other tools in the RVS suite: RapiCover, + RapiTime and RapiTask. For more information on these tools, see the correspond- + ing User Guides, which are included in your installation of RapiTest. + + Some examples of how you might use RapiTest for coverage, timing and sched- + uling analysis during testing include the following: + • Testing for structural code coverage – you might test for structural code + coverage to address certification objectives or requirements. See the example + above in Section 2.2.2: Managing the testing process + • Optimizing worst-case execution time (WCET) – you might test your source + code for WCET throughout development. WCET analysis will identify the sec- + + +14 RapiTest User Guide vWF20190404 +What is RapiTest? Using RapiTest + + + tions of code that provide the greatest contribution to WCET. You can focus + optimization efforts on these sections to realize improvements to the timing + behavior of your code. Applying WCET analysis and optimization as an itera- + tive process throughout your development life cycle will reduce your overall + development time. + • Optimizing worst-case execution time (WCET) - you might use RapiTask + to visualize the scheduling behavior of your system and identify potential rare + timing events such as race conditions or priority inversions in your code. Hav- + ing identified these events, you could use the multi-threaded testing features + of RapiTest (see Section : Multi-threaded testing) to test affected tasks further, + and identify the source of the issue. + + +RapiTest User Guide vWF20190404 15 +This page intentionally left blank +3 Testing using RapiTest + RapiTest is designed to improve the efficiency of software testing processes. It + does this by by providing powerful means to write tests and automating the con- + version of these into test harnesses and running them on target hardware to pro- + duce results. + + This chapter describes how to write tests for use with RapiTest. This requires first + addressing some testing concepts. + +3.1 Introduction to managed testing + This section explains some of the concepts of managed testing using RapiTest. + +3.1.1 How does RapiTest manage tests? + RapiTest manages tests by injecting framework code into source code, building + executable code from this, running it on-target and collecting results. The target + can be an embedded target, host system or simulator. The tests RapiTest uses to + inject framework code can be written in a number of formats. + +3.1.2 What can RapiTest test? + You can test a set of functions of any size with RapiTest. This can be, for example, + a single function, a package or an entire system. Thus, RapiTest is capable of + managing unit, integration, module and system tests. We define a set of functions + of any size as a unit, but only use this term sparingly, to avoid confusion about + what types of test behavior RapiTest can manage. + + White box and black box testing + + RapiTest supports both white box and black box testing: + • In white box tests, RapiTest can modify the internals of tested functions, for + example by editing variables scoped within a tested function. + • In black box tests, RapiTest does not modify tested functions in any way. + + RapiTest generates tests as white box tests by default. To generate black box tests, + you must configure RapiTest to do so, for example by using the Blackbox con- + figuration option in Spreadsheet Test Format test sheets. + + Note + + To test a function as a black box, your source code must include an inter- + face to the function that is scoped outside of the function. + + +RapiTest User Guide vWF20190404 17 +Introduction to managed testing Testing using RapiTest + + + Multi-threaded testing + + RapiTest lets you test the behavior of multi-threaded software, letting you test non- + deterministic software and identify potential race conditions in your code. + + For more information, see the Spreadsheet Test Format User Guide. + +3.1.3 Test structure + RapiTest tests are structured in a hierarchy. When you view RapiTest results in + the RVS Project Manager, see Chapter 5: Analyzing test results, your results are + organized by this hierarchy. + + The smallest unit of each test that RapiTest reports is the assert. This is an action + such as checking that a parameter is equal to a specified value or that a function + is called. Each assert is assigned to either a test function or stub function. These + are described in Section 3.1.4: Test and stub functions. + + Above the level of the assert is the test. A test is defined by the operations assigned + for each of its test and stub functions, and by its scope. + + A scope is a list of functions that RapiTest reports data for after it runs a test. While + functions can be called by a test, data from their execution will only be reported + by RapiTest if they are defined inside a scope. + + The highest level of hierarchy is the test suite. This is just a container for tests, and + multiple tests can be included in a single test suite. + +3.1.4 Test and stub functions + Each function in a RapiTest test is either a test function or a stub function. A function + can be both a test function and a stub function in different tests, but not in the + same test. + + Test functions are modified as little as possible by RapiTest, and often not modified + at all. While additional code may be injected to redirect a test to call the function, + the original function is not changed. + + Stub functions are replaced or modified to change their behavior during tests. + While these terms may be used differently by various players in the critical software + industry, RapiTest supports the following types of behavior: + • Stub – the original function is replaced with a function that returns a fixed value. + The inputs of this function can be checked. + • Mock (or spy) – the original function is called, but its inputs and outputs are + checked. + • Fake – the original function is replaced with a complex function that imitates + the behavior of the replaced function. This can include complex logic. + + RapiTest refers to these collectively as stubs, and can implement each of them in + managed tests. + + +18 RapiTest User Guide vWF20190404 +Testing using RapiTest Writing tests for RapiTest + + +3.2 Writing tests for RapiTest + This section describes the formats you can use to write tests for RapiTest. + +3.2.1 The Spreadsheet Test Format + The Spreadsheet Test Format is a powerful spreadsheet format used to write tests + that can be imported directly into RapiTest. The format has been designed to allow + testers to write complex tests concisely while maintaining readability. + + The Spreadsheet Test Format User Guide describes the Spreadsheet Test Format, + contains easy-to-follow tutorials to learn how to write tests using it, and includes + a comprehensive reference of the format. + + While using the RVS Project Manager, you can generate template spreadsheets + to test the functions in your code, see Section 4.6: Adding tests. + +3.2.2 The RapiTest scripting language + The RapiTest scripting language (RTS) is a powerful scripting language used to + write tests that can be imported directly into RapiTest. Additionally, all tests used + with RapiTest are converted into RTS before they are run with the tool. RTS has + been designed to allow testers to generate complex tests unambiguously. + + For more information on the RapiTest scripting language, contact + support@rapitasystems.com. + +3.2.3 Other test formats + We recommend you use the RapiTest test format or RTS to write tests to use with + RapiTest. + + Nevertheless, if you have an existing test format that you want to use with RapiTest, + or want to convert existing tests into a format that RapiTest can use, we can de- + velop an importer or converter to meet your needs. For more information, contact + us at support@rapitasystems.com. + + +RapiTest User Guide vWF20190404 19 +This page intentionally left blank + Using RapiTest to +4 produce results + This chapter describes what you need to do to set up and run a test project using + RapiTest. It contains the following sections: + • Setting up RapiTest + • Creating a project + • Deploying an integration + • Preparing an integration + • Setting entry points + • Adding tests + • Running an integration + • Configuring a project + +4.1 Setting up RapiTest + To use RapiTest you need to have RVS installed and integrated into your develop- + ment environment. This is outside the scope of this guide; for more information + on installing and integrating RVS see the RVS Installation and Licensing Guide and + RVS Integration Guide respectively. + +4.2 Creating a project + Tutorial + + The RapiTest Creating a project tutorials walk you through creating a + RapiTest project suitable for analysis of both Ada and C code. + + To access these tutorials, open the tutorial menu by either clicking RVS + tutorials on the RVS Welcome page or selecting Tutorials from the Help + menu. For more information on accessing RVS tutorials, see Section 3.1.8: + The tutorial workspace in the RVS User Guide. + + + To create a RapiTest project, open the RVS Project Manager application. You can + do this on Windows systems from the Start menu (Start » RVS » RVS Project + Manager). + + When the RVS Project Manager opens for the first time, it opens on the Welcome + page, see Figure 4.1. From this page, create a new project by clicking Create + a new project in the Get started section. + + +RapiTest User Guide vWF20190404 21 +Creating a project Using RapiTest to produce results + + + Figure 4.1: RVS Project Manager Welcome page + + Tip + + If the Welcome page is not open, you can open it by opening the Help + menu and selecting Welcome Page. + + Alternatively, you can create a New RVS Project from the File menu. + + + The New RVS Project Wizard opens, which guides you through project creation. + For a description of each of the options available when you create a new project, + read the on-screen help text or see Section 4.2 in the RVS User Guide. When + prompted, select the Managed testing mode. This lets RapiTest run to produce a + test harness from input tests. + + Tip + + Mandatory settings in the New RVS Project Wizard are formatted in bold + text. You cannot continue to the next page in the New RVS Project Wizard + unless you have entered all mandatory settings on the current page. Set- + tings in default text formatting are optional. + + + When you finish creating your project, RapiTest creates a project folder and a + project file containing your settings on your file system. You can now run tests with + this project file using either the RVS Project Manager or the command-line. + + +22 RapiTest User Guide vWF20190404 +Using RapiTest to produce results Deploying an integration + + +4.3 Deploying an integration + Tutorial + + The RapiTest Deploying an integration tutorials walk you through deploying + a RapiTest integration for analysis of both Ada and C code. + + To access these tutorials, open the tutorial menu by either clicking RVS + tutorials on the RVS Welcome page or selecting Tutorials from the Help + menu. For more information on accessing RVS tutorials, see Section 3.1.8: + The tutorial workspace in the RVS User Guide. + + Before you can use RapiTest to analyze source code, you must deploy an RVS + integration library. Integration libraries contain definitions for RVS functions that tell + RapiTest how to instrument code and collect data from an executable when it runs. + + To deploy an integration using the RVS Project Manager, do the following: + 1. Open the project and select the Integration you want to deploy in the RVS + Project Manager. To change the active integration, use the Active integra- + tion drop-down menu on the project overview page. + 2. Click Deploy in the Actions section of the project overview page. + 3. Confirm by clicking OK. + + Note + + If your project has already been deployed, you must manually delete the in- + tegration library it is using before you can deploy it again. + + Integration libraries are deployed from a template depending on the settings in + the RVS project file. Templates are suitable for most on-host integrations out of + the box. If you want to use RapiTest to analyze software executed on embedded + hardware, however, you may need to edit your deployed integration library. This + should be carried out during the integration process – for more information, see + the RVS Integration Guide and RVS Integration Library Implementation Guide. + +4.4 Preparing an integration + Tutorial + + The RapiTest Preparing an integration tutorials walk you through preparing a + RapiTest integration for analysis of both Ada and C code. + + To access these tutorials, open the tutorial menu by either clicking RVS + tutorials on the RVS Welcome page or selecting Tutorials from the Help + menu. For more information on accessing RVS tutorials, see Section 3.1.8: + The tutorial workspace in the RVS User Guide. + + +RapiTest User Guide vWF20190404 23 +Setting entry points Using RapiTest to produce results + + + In the Prepare stage of dual-pass integrations, RapiTest statically analyzes source + code. For more information on the RVS workflow, see Section 2.1.3: RVS integra- + tions. + + You only need to Prepare each project once throughout your testing process, + assuming your code does not change. + + To prepare an integration using the RVS Project Manager, do the following: + 1. Open the project and select the Integration you want to prepare in the + RVS Project Manager. To change the active integration, use the Active in- + tegration drop-down menu on the project overview page. + 2. Click Prepare in the Actions section of the project overview page. Alterna- + tively, click the Prepare button on the toolbar. + 3. On the dialog window that opens, select whether or not to Clean your inte- + gration and Enable console debug. We recommend that you clean your + integration, to ensure that all the files your integration requires are present. + 4. Confirm by clicking OK. + + + Figure 4.2: Preparing an integration + + When RapiTest prepares an integration, it collects static information about your + source code and writes this to a report. At this stage, you must set the entry point(s) + to your source code and can refine the analysis you want to apply before running + the integration to produce results. + +4.5 Setting entry points + Before RapiTest can apply a test harness from your source code and input tests, + you must set the entry point(s) to your source code. + + +24 RapiTest User Guide vWF20190404 +Using RapiTest to produce results Setting entry points + + + Tutorial + + The RapiTest Running an integration tutorials describe how to set entry + point(s) to your source code, and are available for both Ada and C projects. + + To access these tutorials, open the tutorial menu by either clicking RVS + tutorials on the RVS Welcome page or selecting Tutorials from the Help + menu. For more information on accessing RVS tutorials, see Section 3.1.8: + The tutorial workspace in the RVS User Guide. + + + To set entry point(s) to your source code, do the following: + 1. Open the project and select the Integration you want to set entry point(s) + for in the RVS Project Manager. To change the active integration, use the + Active integration drop-down menu on the project overview page. + 2. Select the Analysis tab at the bottom of the project overview page. + 3. Your source code is displayed in the Source code section on the left of the + window. You may not be able to see some nested entries. To expand an entry, + click the icon to the left of it. Select the function(s) you want to set as entry + points, right-click and select Add entry point(s). + 4. The functions are now displayed in the Analysis settings section on the right + of the window. To return to the project overview page, click the Overview tab + at the bottom of the window. + + + Figure 4.3: Setting an entry point + + +RapiTest User Guide vWF20190404 25 +Adding tests Using RapiTest to produce results + + +4.6 Adding tests + Tutorial + + The RapiTest Adding test files tutorials describe how to add tests for use + with RapiTest and are available for both Ada and C projects. + + To access these tutorials, open the tutorial menu by either clicking RVS + tutorials on the RVS Welcome page or selecting Tutorials from the Help + menu. For more information on accessing RVS tutorials, see Section 3.1.8: + The tutorial workspace in the RVS User Guide. + + + RapiTest takes input tests and uses them to apply a harness to test source code. + You can write input tests in a variety of formats, as described in Section 3.2: Writing + tests for RapiTest. + + The simplest and easiest option for writing tests is to use the Spreadsheet Test + Format, which is described in detail in the Spreadsheet Test Format User Guide. + If you are going to use the Spreadsheet Test Format to write tests, RapiTest can + generate template spreadsheets that you can use to get started at any time after + the Prepare stage of an integration has been run. + + To generate a template spreadsheet using RapiTest, do the following: + 1. Open the project in the RVS Project Manager. + 2. Click Generate Spreadsheet Template in the Files section of the project + overview page to open the template test generation wizard, see Figure 4.4. + 3. On the first screen, select the elements (folders, files and/or functions) you + want to generate a template for using the checkboxes. + 4. If you want, change the name and/or location of the Output File that will be + produced. + 5. Click Next. + 6. On the Test configuration options screen, you can choose to add configura- + tion options to every generated test. Select any options that you want to add, + then click Next. + 7. On the Summary worksheet screen, you can add a Test Description file to + every generated test sheet – when you do this, the Suite sheet from this file, + which includes project metadata, is used as a template, and is copied to all + generated test worksheets. To add a Test Description file, click Browse and + select the file you want to use from your system's file explorer. then click Next. + 8. Click Finish. + 9. The template is automatically added to the project in a tests folder, + which is displayed in the Files section of the project overview page and the + Project Navigator on the left of the screen. + + +26 RapiTest User Guide vWF20190404 +Using RapiTest to produce results Adding tests + + + Figure 4.4: Generating spreadsheet templates + + For RapiTest to apply tests to source code, they must be added to the project. If + you have used RapiTest to generate test templates, these will already have been + added to your project. If not, you can import tests by doing the following: + 1. Open the project in the RVS Project Manager. + 2. Click Import File in the Files section of the project overview page. + 3. Select the test(s) you want to add to the project from your file system and + click OK. + 4. The test(s) you added is now displayed in the Files section of the project + overview page and the Project Navigator on the left of the screen. + + +RapiTest User Guide vWF20190404 27 +Running an integration Using RapiTest to produce results + + + Figure 4.5: Importing tests + +4.7 Running an integration + Tutorial + + The RapiTest Running an integration tutorials walk you through running a + RapiTest integration, and are available for both Ada and C projects. + + To access these tutorials, open the tutorial menu by either clicking RVS + tutorials on the RVS Welcome page or selecting Tutorials from the Help + menu. For more information on accessing RVS tutorials, see Section 3.1.8: + The tutorial workspace in the RVS User Guide. + + When running an integration, RapiTest uses input tests to build a test harness + executable and runs this on target to produce verification results, which it then + writes to a report file. + + It does this by executing multiple integration stages: Build, Run and Report. You + can run all of these stages together in the RVS Project Manager. For more infor- + mation on the RVS workflow, see Section 2.1.3: RVS integrations. + + To run an integration using the RVS Project Manager, do the following: + 1. Open the project and select the Integration you want to run in the RVS + Project Manager. To change the active integration, use the Active integra- + tion drop-down menu on the project overview page. + 2. Click Build & Run in the Actions section of the project overview page. Alter- + natively, click the Build & Run button on the toolbar. + 3. On the dialog window that opens, select settings for the run. Instrumenta- + tion is only applied to your source code if the Include instrumentation option + + +28 RapiTest User Guide vWF20190404 +Using RapiTest to produce results Configuring a project + + + is checked. The Keep results from previous run option instructs RapiTest to + merge data from previous runs into a combined report file. + 4. Confirm by clicking OK. + + Your results open automatically at the end of the run if Open report automatically + was checked. If not, open them by clicking the Results button on the toolbar. + For more information on viewing your results, see Chapter 5: Analyzing test results. + + Note + + In some cases, you may want to generate executable code using RapiTest + but not run it. If this is the case, you can execute the RVS Build stage with- + out executing the Run stage. To do this, select Build from the Project + menu or click the More actions button beside the Build & Run action + and select Build. + + After this, you will need to invoke the RVS Report stage to generate a re- + port. To do this, select Report from the Project menu or click the + More actions button beside the Build & Run action and select Re- + port. + + +4.8 Configuring a project + Some advanced configuration options are not available in the New RVS Project + Wizard. You may want to change these options for your project. + + To configure options for your project, click on the Configure button on the + project overview page. This opens the RVS Config Editor, see Figure 4.6. For more + information on configuration settings, see Section 4.11 in the RVS User Guide. + + + Figure 4.6: The RVS Config Editor + + +RapiTest User Guide vWF20190404 29 +Configuring a project Using RapiTest to produce results + + + When you Save your configuration, your new settings are saved to your project + file. To return to the RVS Project Manager, click Close. + + +30 RapiTest User Guide vWF20190404 +5 Analyzing test results + Tutorial + + The RapiTest Viewing test results tutorials walk you through viewing test re- + sults, and are available for both Ada and C projects. + + To access these tutorials, open the tutorial menu by either clicking RVS + tutorials on the RVS Welcome page or selecting Tutorials from the Help + menu. For more information on accessing RVS tutorials, see Section 3.1.8: + The tutorial workspace in the RVS User Guide. + + + Note + + This chapter provides a short introduction to viewing and analyzing RapiTest + results. For a comprehensive reference of features related to viewing and + analyzing results, see Chapter 6 in the RVS User Guide. + + + Note + + RVS reports include data that is displayed in various colors to emphasize + results from RVS analysis. + + You can edit the colors used to display RVS results to meet your prefer- + ences. To learn how to do so, see Section 3.2.9 in the RVS User Guide. + + + Note + + RVS includes prebuilt example reports that you can view and use to explore + the concepts in this chapter. To access these, open the Help menu » Exam- + ple Reports. + + When RapiTest collects data from tests it outputs it into a report file with the .rvd + extension. You can view and analyze this data in the RVS Project Manager. + + To view RapiTest reports, first open the RVS Project Manager. You can do this on + Windows systems by using the Windows Start menu (Start » RVS » RVS Project + Manager). + + You can open a report file in the RVS Project Manager in multiple ways: + • If you have previously prepared or run a RapiTest integration, click the Re- + sults button on the toolbar. This opens the last report generated by RapiTest + for the selected integration. + + +RapiTest User Guide vWF20190404 31 + Analyzing test results + + + • To open any report in your file system, open the File menu and select Open + Report, then select the report you want to open. + • To open a report you have viewed recently, open the File menu and the Recent + Reports submenu, then select the report you want to open. + + When you open your report, a report details window opens with the Overview tab + selected. This tab contains general information about your integration including + when it was run and which device it was run on. We recommend that you check + the Overview tab to ensure you are viewing the correct report. + + If you ran tests during your integration, your report includes a Unit tests tab. Click + on this tab to view your unit test data. When you open the Unit tests tab you see + a chart showing a summary of your test data like the one shown in Figure 5.1. + This chart shows the percentage of your tests and assertions that passed (green) + and failed (red). + + + Figure 5.1: Unit test chart + + Below the chart, your test data is also presented in a table like the one shown in + Figure 5.2. When you first open your report, your tests are displayed in a Tree + format that shows each of the test suites RapiTest applied to your source code. + You can expand each suite to show data for the tests inside it, and expand + each test to show data for the asserts inside it. Click the Flat button near the + top of the report details window. This shows you a flat list of all the tests RapiTest + ran to produce the report file. + + +32 RapiTest User Guide vWF20190404 +Analyzing test results + + + Figure 5.2: Unit test table + + To filter your results to show only those from a particular suite, you can double-click + the suite's name. If you are interested in results from a particular scope, you can + double-click its name to show more detail for it. This opens a page showing the + results of all tests applied to that scope, like the one shown in Figure 5.3. For more + information on RapiTest scopes, see Section 3.1.3: Test structure. To return to the + previous page, click the Back button above the report details window or use + the keyboard shortcut Alt+Left. + + + Figure 5.3: Scope detail + + +RapiTest User Guide vWF20190404 33 + Analyzing test results + + + You may want to review tests that failed. Return to the Tree view by clicking + the button near the top of the report details window. Filter the table by clicking the + filter drop-down menu above it and selecting Failed. The table now shows only + tests that failed. + + Click the icon next to Test Results to expand the table to show more detailed + information. Expand a suite and a test inside that suite to show the asserts that + failed for it. When an assert fails, the Message column in the table gives an indi- + cation why. You may find this information helpful for editing your test so it passes. + + If you wrote your tests in the RapiTest test format (see Section 3.2.1: The Spread- + sheet Test Format), a link to your spreadsheet appears in the test table. Dou- + ble-click this link to open the spreadsheet on the page of the selected tests. + + When you import a spreadsheet defining tests into the RVS Project Manager, it + saves a link to the original spreadsheet. This means you do not need to import + your test spreadsheet into the RVS Project Manager again after editing a test, + and you can simply Run your integration again. + + You can also view the RTS script RapiTest used to run your tests. RapiTest always + runs tests from scripts. If you defined your tests in another format, such as the + Spreadsheet Test Format, RapiTest creates an RTS script at run-time, and uses + this to run your tests. + + To view the script associated with an assert, test or suite, right-click on its name + and select View test script. For more information on RapiTest scripts, see Sec- + tion 3.2.2: The RapiTest scripting language. + + Click the Treemap button on the toolbar above your report to open a treemap + view of your source code, see Figure 5.4. + + + Figure 5.4: Treemap window + + +34 RapiTest User Guide vWF20190404 +Analyzing test results + + + This view displays colored rectangles showing the unit test coverage for each file + and function in your source code. The size of each rectangle is based on the num- + ber of statements the element it represents contains. Close the treemap window + by clicking the Treemap button again. For more information on treemaps, see + Chapter 6 in the RVS User Guide. + + Tutorial + + The RapiTest Using treemaps tutorials walk you through using treemaps to + view your results, and are available for both Ada and C projects. + + To access these tutorials, open the tutorial menu by either clicking RVS + tutorials on the RVS Welcome page or selecting Tutorials from the Help + menu. For more information on accessing RVS tutorials, see Section 3.1.8: + The tutorial workspace in the RVS User Guide. + + If you ran coverage or timing analysis during your integration, you may want to + analyze these results. Coverage and timing results are shown in other tabs in your + report. This is not discussed in this guide; for more information on analyzing cov- + erage and timing results, see Section 6.3 in the RVS User Guide or the RapiCover + and RapiTime User Guides. + + This chapter provided a short introduction to viewing RapiTask results. For a com- + prehensive reference of features related to viewing and analyzing results, see + Chapter 6 in the RVS User Guide. + + +RapiTest User Guide vWF20190404 35 +This page intentionally left blank +6 Exporting results + You can export results from RapiTest reports into a variety of file formats. Export + files are suitable for the use of RapiTest in a qualified testing process. + + You can export RapiTest results in the following formats: + • text – plain text format. Individual data items are separated with one or more + spaces. Data section headings are enclosed within one or more = characters. + • csv – comma separated value format. Data exported in this format can eas- + ily be imported into a spreadsheet application for further formatting and pro- + cessing. + • scsv – semicolon separated value format. Data exported in this format can + easily be imported into a spreadsheet application for further formatting and + processing. + • xml – XML format. The schema for the generated XML is included in the ex- + ported file. This data can be used for more sophisticated post-processing of + the results data. + + To learn how to export results from RapiTest projects, see Chapter 7 in the RVS + User Guide. + + +RapiTest User Guide vWF20190404 37 +This page intentionally left blank +7 Using the command-line + Tutorial + + The Automating RapiTest tutorials walk you through how to generate custom + RVS commands, which you can run from the command-line and are suit- + able for both Ada and C RapiTest projects. + + To access these tutorials, open the tutorial menu by either clicking RVS + tutorials on the RVS Welcome page or selecting Tutorials from the Help + menu. For more information on accessing RVS tutorials, see Section 3.1.8: + The tutorial workspace in the RVS User Guide. + + Whenever RapiTest is run, whether through the RVS Project Manager or the com- + mand-line, it is run using rvsdriver, which manages all of the back-end tools in- + volved in RVS integrations, see Section 2.1: Using RVS. + + The RVS Project Manager includes a Custom Command utility that makes it easy + to configure rvsdriver runs. You can use this utility to run custom commands from + within the RVS Project Manager or to generate scripts to use RVS outside the + RVS Project Manager. + + For more information on using the Custom Command utility, see Chapter 8 in the + RVS User Guide. + + +RapiTest User Guide vWF20190404 39 +This page intentionally left blank +8 Troubleshooting + This chapter describes what to do if you encounter any problems while using + RapiTest. + + Many problems that occur when using RapiTest are related to its integration with a + development and target environment. For information on the integration process, + see the RVS Integration Guide. + + If you receive a warning or error message while using RapiTest, you can look up + the cause of the error and learn how to resolve it in the RVS Troubleshooting Guide. + This document also describes known issues in RapiTest and other RVS tools. + + If you encounter a problem while using RapiTest, feel free to contact us at + support@rapitasystems.com or +44 (0) 1904 413 945. Please supply as + much information as possible about your problem, so we can resolve it promptly. + + For more information on the RVS troubleshooting process, see the RVS User + Guide. + + +RapiTest User Guide vWF20190404 41 +This page intentionally left blank + diff --git a/docs-extracted/src/scov/RVS/doc/RapiTest/Spreadsheet_Test_Format_Cheat_Sheet.md b/docs-extracted/src/scov/RVS/doc/RapiTest/Spreadsheet_Test_Format_Cheat_Sheet.md new file mode 100644 index 000000000..e83185c64 --- /dev/null +++ b/docs-extracted/src/scov/RVS/doc/RapiTest/Spreadsheet_Test_Format_Cheat_Sheet.md @@ -0,0 +1,108 @@ +--- +title: "Spreadsheet Test Format Cheat Sheet" +source: "./src/scov/RVS/doc/RapiTest/Spreadsheet_Test_Format_Cheat_Sheet.pdf" +category: "src/scov/RVS/doc/RapiTest" +pages: 2 +extracted: "2026-07-06T23:15:57.305769" +--- + +# Spreadsheet Test Format Cheat Sheet + +> Extracted from `./src/scov/RVS/doc/RapiTest/Spreadsheet_Test_Format_Cheat_Sheet.pdf` (2 pages). +> Figures, diagrams, and tables may not render accurately in plain text. + +Spreadsheet Test Format Cheat Sheet (Page 1 of 2) + Sections Function signatures Shorthands +Configuration Contains configuration options Parameter Specifies each parameter for the function Shorthand (Column) Specifies shorthand for element + +Contexts Specifies contexts to search for functions @N Refers to the Nth Parameter of a function :shorthand Refers to shorthand element + specified in its declaration +Scope Specifies which results should be reported :global.obj Refers to global object obj + Type Specifies type for each parameter +Stubs Specifies signatures for stubs in test sheet (see Types and modifiers) :local.obj Refers to a Test Local object obj + +Test Locals Specifies local objects for test sheet ? Match a non-overloaded function without :original Refers to the original version of a stubbed + specifying both Type and Parameters function +Tests Defines test sequences for test sheet + Function has no Parameter or Type :uut Refers to most recent invocation of a unit + under test + Configuration options + :stub Refers to most recent invocation of a + Test tables stubbed function +Blackbox Tests in current sheet will be applied as + black box tests + New test Specifies the beginning of a new set of +Control flow Expects all stub operations written to tests + respect control flow Types and modifiers + End tests Specifies the end of a test table +Disabled Tests in current sheet will not be run A type-signature is defined as + Test details + meaning + modifier* named_type + Applies metadata such as test name to all +Explicit stubs tests in table Possible modifiers are: + Expects that the number of times each + Test details + Value array[len] An array of length len + stubbed function is called is specified + Applies metadata such as test name to + pointer A dereferencable pointer to the type +Remove original stubs only test in current column + Removes original versions of stubbed reference A C++ type reference + Object Specifies a C++ class object + functions from test harness + volatile An object that must be read from memory + Call or stub Unit under test or stub function to apply and cannot be cached in a register + Special syntax operation on + const An object that cannot be modified through +# Comment entire row (should only be Variable Variable to apply operation on assignments + placed in column B) Types must be specified in modification order + Operation Operation to apply to call or stub +: Ignore the operation in this row Example: a constant pointer to an array containing 5 int + Value Value to apply operation with + elements must be specified as + const pointer array[5] int + For an electronic copy see RVS/doc/RapiTest +Spreadsheet Test Format Cheat Sheet (Page 2 of 2) + Basic operations Numerical operations Auxiliary test functions +call Used to call a function, often the check.ne Checks Variable is not equal to Value get.bitsz(obj) + :original version of a stubbed function Returns the size of obj in bits + check.lt Checks Variable is less than Value +called Checks stub is called Value times (unless get.bytesz(obj) + using Control flow) check.le Checks Variable is less than or equal to Returns the size of obj in bytes + Value +catch Checks exception (Value) is raised get.first(obj) + check.gt Checks Variable is greater than Value + Returns the lowest possible value for obj +check Checks value of Variable is Value + check.ge Checks Variable is greater than or equal to given its type +fail Reports test as failed when reached Value + get.invalid(obj) +pass Reports test as passed when reached Returns an invalid value for obj + check.eq(num) +run Invokes a unit under test Checks floating point Variable is within get.last(obj) + num of Value +set Sets value of Variable to Value Returns the highest possible value for obj + check.eq(num%) given its type +stubbed Specifies that a function in the stubs table Checks floating point Variable is within + is stubbed during a test num% percent of Value return References the return value of a unit under + test or stubbed function + check.string Checks value of Variable is equal to a + Arrays “” or another variable in Value + column + Test Locals +{X, Y, Z} (Test Locals) Initializes an array with + elements X, Y, Z Element Specifies sub-elements of structure type +get.length(array) Initializer Specifies values to initialize for local + Returns the length of array Pointers/accesses + init (operation) +array[x] References x’th element in array get.pointer(obj) (Operation) Initializes the initializer +array[x..y] Iterates between the x’th to y’th Returns the pointer/access to obj specified in Value field + elements in array (C/C++ only) + get.address(obj) + Returns the address of obj Raw code + Control flow get.deref(obj) raw: Inserts following code into test as written +called | Dereferences obj one level raw(type): Specifies type of the following raw code + Specifies that stub is called once + get.object(obj) rts: Inserts following code into test as RTS + Fully dereferences obj script + For an electronic copy see RVS/doc/RapiTest + diff --git a/docs-extracted/src/scov/RVS/doc/RapiTest/Spreadsheet_Test_Format_User_Guide.md b/docs-extracted/src/scov/RVS/doc/RapiTest/Spreadsheet_Test_Format_User_Guide.md new file mode 100644 index 000000000..0d98e5e20 --- /dev/null +++ b/docs-extracted/src/scov/RVS/doc/RapiTest/Spreadsheet_Test_Format_User_Guide.md @@ -0,0 +1,3029 @@ +--- +title: "Spreadsheet Test Format User Guide" +source: "./src/scov/RVS/doc/RapiTest/Spreadsheet_Test_Format_User_Guide.pdf" +category: "src/scov/RVS/doc/RapiTest" +pages: 90 +extracted: "2026-07-06T23:15:57.385210" +--- + +# Spreadsheet Test Format User Guide + +> Extracted from `./src/scov/RVS/doc/RapiTest/Spreadsheet_Test_Format_User_Guide.pdf` (90 pages). +> Figures, diagrams, and tables may not render accurately in plain text. + + Spreadsheet Test +Format User Guide + Version WF20190404 +Disclaimer +The information, text, and graphics contained within this document are +provided for information purposes only by Rapita Systems Ltd. Rapita +Systems Ltd. does not warrant the accuracy or completeness of the +information, text, and other items contained in this document. + + +Copyright and Trademarks +All rights reserved. Information and images contained within this doc- +ument are copyright and the property of Rapita Systems Ltd. All trade- +marks are hereby acknowledged to be the properties of their respective +owners. + + +Acknowledgments +Rapita Systems' tools are built using AdaCore's GNAT Pro compiler. + + +Rapita Systems Ltd. +Registered in the UK, number 5011090. +Registered address: +Atlas House +Link Business Park +Osbaldwick Link Road +York +YO10 3JB +UK +Phone: +44 (0) 1904 413 945 +http://www.rapitasystems.com/ +This document copyright © 2017-2019, Rapita Systems Ltd. + +Document build 118520 + +ID: DOC/17003 + Table of Contents + + 1. About this guide ............................................................... 5 + 1.1. Who should read this guide? ................................................... 5 + + 1.2. Structure of this guide ........................................................... 5 + + 1.3. Notation ............................................................................ 7 + + 1.4. RVS documentation map ........................................................ 7 + + 1.5. Support ............................................................................. 9 + + + 2. What is the Spreadsheet Test Format? ............................ 11 + 2.1. Spreadsheet Test Format syntax .............................................. 11 + + + 3. Spreadsheet Test Format workbooks .............................. 13 + + 4. Writing a suite sheet ....................................................... 15 + + 5. Writing test sheets: Ada .................................................. 17 + 5.1. Setting and checking global variables ....................................... 17 + + 5.2. Testing simple functions ........................................................ 19 + + 5.3. Stubbing functions .............................................................. 21 + + 5.4. Handling overloaded functions ................................................ 25 + + 5.5. Using local variables ............................................................ 28 + + 5.6. Testing multi-threaded software ............................................... 31 + + 5.7. Working with arrays ............................................................. 34 + + 5.8. Using accesses ................................................................. 35 + + 5.9. Setting configuration options .................................................. 36 + + 5.10. Advanced checking ........................................................... 37 + + 5.11. Advanced stubbing ............................................................ 39 + + +Spreadsheet Test Format User Guide vWF20190404 3 + Table of Contents + + + 5.12. Advanced multi-threaded testing ............................................ 42 + + 5.13. Using raw code ................................................................ 44 + + 5.14. Black box testing .............................................................. 45 + + + 6. Writing test sheets: C and C++ ...................................... 47 + 6.1. Setting and checking global variables ....................................... 47 + + 6.2. Setting and checking static class variables (C++) ........................ 49 + + 6.3. Testing simple functions ........................................................ 49 + + 6.4. Stubbing functions .............................................................. 51 + + 6.5. Testing overloaded functions (C++) ......................................... 55 + + 6.6. Using local variables ............................................................ 58 + + 6.7. Setting and checking object members (C++) ............................. 60 + + 6.8. Testing functions in inherited classes (C++) ............................... 61 + + 6.9. Testing multi-threaded software ............................................... 63 + + 6.10. Working with arrays ............................................................ 66 + + 6.11. Using pointers .................................................................. 67 + + 6.12. Setting configuration options ................................................. 69 + + 6.13. Advanced checking ........................................................... 70 + + 6.14. Advanced stubbing ............................................................ 72 + + 6.15. Advanced multi-threaded testing ............................................ 75 + + 6.16. Using raw code ................................................................ 76 + + 6.17. Black box testing .............................................................. 77 + + + 7. Test sheet examples ....................................................... 79 + 7.1. Simulating hardware addresses .............................................. 79 + + 7.2. Implicit dereferencing of pointers ............................................. 80 + + 7.3. Intercepting return values from stubbed functions ......................... 81 + + 7.4. Unnamed C++ function parameters ........................................ 82 + + + 8. Glossary ......................................................................... 85 + +4 Spreadsheet Test Format User Guide vWF20190404 +1 About this guide + The Spreadsheet Test Format User Guide explains how to write and interpret tests + using the Spreadsheet Test Format. + +1.1 Who should read this guide? + This document is intended for users who want to use the Spreadsheet Test Format + to write tests for use with RapiTest, and is intended to supplement other documen- + tation in the RVS suite, particularly the RapiTest User Guide. + +1.2 Structure of this guide + This document includes the following chapters: + + Chapter 1: About this guide + Describes the purpose and layout of the Spreadsheet Test Format User Guide and + the notation used throughout the document. + + Chapter 2: What is the Spreadsheet Test Format? + Describes the high-level features of the Spreadsheet Test Format, and the benefits + of using this format to write unit tests. + + Chapter 3: Spreadsheet Test Format workbooks + Describes the general layout of the Spreadsheet Test Format. + + Chapter 4: Writing a suite sheet + Describes how to write Suite sheets in the Spreadsheet Test Format, which you + can use to store project and version-control information. + + Chapter 5: Writing test sheets: Ada + Describes how to write Test sheets for Ada code in the Spreadsheet Test Format. + These sheets contain the information needed to run tests with RapiTest. This chap- + ter guides you through how to write tests using Ada examples. + + Chapter 6: Writing test sheets: C and C++ + Describes how to write Test sheets for C and C++ code in the Spreadsheet Test + Format. These sheets contain the information needed to run tests with RapiTest. + This chapter guides you through how to write tests using C and C++ examples. + + Chapter 7: Test sheet examples + Contains examples showing how to work around issues you may encounter during + testing, and clarifies the behavior of the Spreadsheet Test Format in some test + scenarios. + + +Spreadsheet Test Format User Guide vWF20190404 5 +Structure of this guide About this guide + + + Chapter 8: Glossary + Describes the meaning of important terms used in this document. + + +6 Spreadsheet Test Format User Guide vWF20190404 +About this guide Notation + + +1.3 Notation + This document uses the following notation: + • References to other documents and to other chapters or sections in this doc- + ument are written in italics, for example Chapter 1: About this guide. When + reading an electronic copy of this document, you can click on a reference to + navigate to the location of the referenced element. + • Names of RVS applications are formatted in bold italics, for example RVS + Project Manager. + • References to areas or elements in user interfaces are formatted in italics, for + example the Report Navigator. + • Menus, menu choices and button labels are formatted in bold, for example + File » Print or OK. Where buttons have icons, these are shown before their + Label in in-line text, for example Save. + • Names of RVS tools are formatted in bold, for example rvsdriver. + • References to HTML links appear as underlined text, for example + www.rapitasystems.com. + • Folder and file names are formatted in a monospaced font. + • Command-line tools and their commands, annotations and examples are for- + matted in a monospaced font. These are either written in-line with text + or as separate text blocks. When written in-line with text, they are formatted + like the following: rvsdriver, default_instrument, rvs_instr.h. + When written as a separate text block, they are formatted like the examples + below: + rvsdriver --project rvs.rvsprj --all + + #pragma RVS instrument( "function_name", "FALSE" ) + + • When referencing Ada code, the term functions refers to both functions and + procedures. + +1.4 RVS documentation map + This document is part of the Rapita Verification Suite (RVS) document set, which + contains the following documents: + + RVS Installation and Licensing Guide + Describes how to install RVS tools, and licensing options for them. + + RVS Integration Guide + Describes how to integrate RVS tools into build and target environments. + + RVS User Guide + Describes how to set up and run RVS projects, analyze data and export verification + results. + + +Spreadsheet Test Format User Guide vWF20190404 7 +RVS documentation map About this guide + + + RapiTest User Guide + Describes how to use RapiTest to manage test projects. + + Spreadsheet Test Format User Guide + Describes how to write tests for RapiTest in the Spreadsheet Test Format. + + RapiCover User Guide + Describes how to use RapiCover to measure code coverage and address cover- + age holes. + + RapiTime User Guide + Describes how to use RapiTime to measure timing metrics including worst-case + execution time, and how to use these metrics to identify the best optimization + candidates. + + RapiTask User Guide + Describes how to use RapiTask to measure system level task timing information, + visualize traces and gain insight into runtime behavior. + + RTBx 2xxx User Guide + Describes how to use the RTBx data logger. + + RVS Integration Library Implementation Guide + Describes how to implement RVS integration libraries. This document is for use by + readers with a thorough understanding of the implementation of RVS. + + RVS Files Reference Guide + Describes RVS-specific files including input, intermediate and output files. + + RVS Filters Guide + Describes RVS filters, which are used to convert raw trace data into a format that + RVS can analyze, and how to write them. + + RVS Command Line Tools Reference Guide + Describes the command-line tools used by RVS, including a list of available com- + mand options. + + RVS Annotations Reference Guide + Describes the annotations you can use to control instrumentation and analysis + with RVS. + + RVS Troubleshooting Guide + Describes the error and warning messages you may encounter when using RVS + tools, and how to address them. + + RVS Migration Guide + Describes how to migrate between using different versions of RVS. + + +8 Spreadsheet Test Format User Guide vWF20190404 +About this guide Support + + +1.5 Support + For support issues, please contact Rapita Systems Ltd. by any of the following + means: + + Email + support@rapitasystems.com + + Telephone + +44 (0) 1904 413 945 + + Website + www.rapitasystems.com + + To register for support, visit www.rapitasystems.com/register. More than one user + can register per license. + + +Spreadsheet Test Format User Guide vWF20190404 9 +This page intentionally left blank + What is the Spreadsheet +2 Test Format? + RapiTest's Spreadsheet Test Format is a spreadsheet format that can be used + to define tests for use with RapiTest. Before developing the format, we collated + the needs of a number of our customers. Taking these into account, RapiTest's + Spreadsheet Test Format reduces overall testing effort and has key features in- + cluding the following: + • Concise, high-level syntax – you can write complex test behavior in a concise + and simple way. Our conversion tools worry about low-level detail, so you don't + have to. Features such as context and shorthand notation reduce the effort + you need to write tests. + • Open format – you can write tests in any spreadsheet program. + • Customizable and extensible – our format has been designed to meet the + needs of our users. Because we understand these needs may be different, it + has been developed as a feature-rich base that we can extend. If there are any + extra features you want in your tests, we can work with you to add these. + +2.1 Spreadsheet Test Format syntax + The Spreadsheet Test Format has some syntax requirements that you must fol- + low when writing spreadsheets for use with RapiTest. Some requirements relate + to specific subsets of the Spreadsheet Test Format and are mentioned elsewhere + in this guide. Figure 2.1 shows an example worksheet written to meet the syntax + requirements of the Spreadsheet Test Format. + + + Figure 2.1: Spreadsheet Test Format syntax + + The general syntax requirements of the Spreadsheet Test Format are listed below: + • Column A is reserved for section headers – When RapiTest parses data in + a worksheet, it searches for text entered in column A before performing any + other operation, and uses this to determine how to process data. You should + type only section headers in column A of spreadsheets written for use with + RapiTest. + + +Spreadsheet Test Format User Guide vWF20190404 11 +Spreadsheet Test Format syntax What is the Spreadsheet Test Format? + + + • Column B marks the start of data in a section – After RapiTest reads a sec- + tion header, it parses data in that section by first searching for suitable text in + column B. You should only include suitable text, or comments, see below, in + column B of a worksheet. + • Blank rows are ignored – Blank rows are ignored by RapiTest when it parses + data. + • Comments should be entered in column B – If you want to insert a comment + into a worksheet, type this into column B. You can begin a comment by typing + # or [comment] into column B of a worksheet. Doing this instructs RapiTest + to ignore information on the entire row. We recommend that you do not insert + a comment into the same row as a section header. + • Colors are stylistic only – The color of cells in the Spreadsheet Test Format + does not affect how they are parsed by RapiTest. + + +12 Spreadsheet Test Format User Guide vWF20190404 + Spreadsheet Test Format +3 workbooks + This chapter describes the structure of Spreadsheet Test Format workbooks and + the data formats that can be used in it. + + You can include three different types of worksheet in workbooks you write in the + Spreadsheet Test Format. Figure 3.1 shows the worksheets in a simple workbook, + and includes at least one of each type of worksheet. + + + Figure 3.1: Test format layout + + Each type of worksheet has a specific purpose, which is described below: + • Suite sheets – these let you record information about your project and test + suite. When you use RapiTest to generate tests from a spreadsheet including + a Suite sheet, the information in this sheet is stored in your output RVD file. + For RapiTest to be able to identify your Suite sheet, it must be called Suite, + and be the first sheet in your workbook. For more information on writing Suite + sheets, see Chapter 4: Writing a suite sheet. + • Test sheets – these let you define and configure the behavior of tests in your + project. When you use RapiTest to generate tests from a spreadsheet, the tool + uses information in Test sheets to write your test code. You can include any + number of Test sheets in a workbook. For RapiTest to be able to parse your Test + sheets, they must have names beginning with Test. For more information on + writing Test sheets, see Chapter 5: Writing test sheets: Ada. + • User sheets – these let you record any additional information you want to. + You can include any number of User sheets in your Spreadsheet Test Format + projects. To include a User sheet, name your sheet anything other than Suite + or a name beginning with Test. RapiTest does not write data in User sheets + sheets into your output RVD file. + + Data you type in each sheet is parsed in sections, such as the Summary and Detail + sections in Figure 2.1 in the previous chapter. Each section begins with a valid + section header in column A, see Section 2.1: Spreadsheet Test Format syntax, and + ends at the next section header. + + You can include a single cell or table of data in each section. The Spreadsheet + Test Format includes four types of data format, and you must use a specific format + + +Spreadsheet Test Format User Guide vWF20190404 13 + Spreadsheet Test Format workbooks + + + for each section. The types of data format in the Spreadsheet Test Format are + described and shown below. + + Free text – these contain any data. They can be a single cell or multiple merged + cells in column B of a worksheet. + + + Figure 3.2: Free text + + Lists – these contain a set of fields and values. When RapiTest parses data, it + matches each value to its corresponding field and writes this to your report. In this + data type, each field is entered in column B, and each value in the corresponding + cell in column C. + + + Figure 3.3: Lists + + Tables – these also contain a set of fields and values. In this data type, fields are + written on a single row of the worksheet, and their corresponding values are written + on other rows. Only a single Table can be included in a section, and the first table + header must be in column B of the worksheet. + + + Figure 3.4: Tables + + Test tables – these are tables specifically formatted to define tests. For more in- + formation on this data format, see Chapter 5: Writing test sheets: Ada or Chapter 6: + Writing test sheets: C and C++. + + + Figure 3.5: Test tables + + +14 Spreadsheet Test Format User Guide vWF20190404 +4 Writing a suite sheet + You can use a Suite sheet (see Figure 4.1) to record information about your test + suite. When you run your test suite using RapiTest, the tool exports information + in this worksheet to your output report. This can help you map your tests to their + requirements and track the history of your project over time. While this is helpful, + Suite sheets are optional and you do not need to include them in your Spreadsheet + Test Format workbooks. + + + Figure 4.1: The Suite sheet + + You can record information in the Suite sheet in the Summary, Detail, History and + Comments sections. For RapiTest to be able to export data from the sheet, you + must use the correct data format for each section. For more information on data + formats, see Chapter 3: Spreadsheet Test Format workbooks. + + You can use the Summary section to record basic information about your test + project using the List format. The information in the example above is only a sug- + gestion, and you can add any number of field-value pairs to this section. + + The Detail section lets you record lower-level detail describing what the tests in + the spreadsheet were designed to test. You must use the Free text format to type + information in this section. You can include any number of Detail sections in the + RapiTest format. + + +Spreadsheet Test Format User Guide vWF20190404 15 + Writing a suite sheet + + + In the History section, you can record information to track changes you make to + your tests over time and record the outcome of test runs, using the Table format. + You can enter any number of rows in this section, and the table ends on the first + empty row. + + Finally, you can use the Comments section to record comments about the tests + in your spreadsheet, using the Free text format. Text in the Comments section is + written to your output RVD file, but not visible in the RVS Project Manager when + you open a report. For this reason, this is a separate section from the Detail section. + + +16 Spreadsheet Test Format User Guide vWF20190404 +5 Writing test sheets: Ada + Test sheets contain information defining the tests you want RapiTest to generate. + This chapter describes how to define tests for Ada code in test sheets by working + from a simple example test and adding complexity to this gradually. Many terms + used in the Spreadsheet Test Format are described in this chapter. Chapter 8: + Glossary contains a list of these, along with other important terms. + + The examples presented are shown below: + • Setting and checking global variables + • Testing simple functions + • Stubbing functions + • Handling overloaded functions + • Using local variables + • Testing multi-threaded software + • Working with arrays + • Using accesses + • Setting configuration options + • Advanced checking + • Advanced stubbing + • Advanced multi-threaded testing + • Using raw code + • Black box testing + +5.1 Setting and checking global variables + Consider the following Ada code: + + package MyPackage is + GlobalVariable : Natural := 0; + end MyPackage; + + + GlobalVariable is a global variable that is defined in the MyPackage pack- + age. + + The example below shows a test that sets and checks the value of GlobalVari- + able, Figure 5.1. + + +Spreadsheet Test Format User Guide vWF20190404 17 +Setting and checking global variables Writing test sheets: Ada + + + Figure 5.1: Setting and checking a global variable + + The table in Figure 5.1 defines a single test. This type of table is referred to hereafter + as a test table. Each test table can define one or more tests. Inside this table, we + defined our test in a test definition. This includes everything we need to identify + the test and tell it how to behave: its Name, Requirements, and everything in the + Variable, Operation and Value columns. Ignore the Call or stub column for now, we + will discuss it later. + + The test defined in Figure 5.1 sets GlobalVariable to 12345, and then + checks that the variable has this value. We have also named the test Global- + Variable and specified that it tests requirement 1. + + RapiTest is instructed to parse the test table by the presence of the Tests sec- + tion header. Like all section headers, this is written in column A of the worksheet + (see Chapter 3: Spreadsheet Test Format workbooks). The Tests section header + instructs RapiTest to recognize that the section contains test definitions. + + The test definition for this test comprises all the fields in the test table. Row 7 + instructs RapiTest to set the variable GlobalVariable to 12345, and row 8 + instructs it to check this value. Set and check are test operations, which instruct + RapiTest what to do with a passed Variable and Value. + + You must write test definitions in the order you want RapiTest to carry out test + operations. Typically, this means you must write them to reflect the control flow + of your program. The order in which you write stubs, however, does not generally + matter – you can write these to represent control flow or not, unless you have + the Control Flow configuration option set, see Section 5.9: Setting configuration + options. Coming back to the test, if we had written the operations in Figure 5.1 + in the reverse order, RapiTest would attempt to check GlobalVariable before + setting its value. + + In the example above, we referred to the variable GlobalVariable by specify- + ing that it is part of the MyPackage package, MyPackage.GlobalVariable. + You must specify package names to instruct RapiTest which variable or function + you want to test or stub without ambiguity. + + You can avoid having to specify package names multiple times in the Spreadsheet + Test Format by setting a Context. Figure 5.2 shows how to do this. + + +18 Spreadsheet Test Format User Guide vWF20190404 +Writing test sheets: Ada Testing simple functions + + + Figure 5.2: Setting a context + + The test sheet in Figure 5.2 includes a Contexts table, which is marked by the + Contexts section header. As described above for the Tests section header, this + tells RapiTest to parse the data in the section as being data of a specific type – in + this case, a context table. The Contexts table includes the MyPackage context, + in the Context name column. Ignore the other columns in the table for now, + we will discuss them later. + + When RapiTest generates your tests, it searches for functions or variables in a test + definition in a specific order. First, it checks each context in the Contexts table, + beginning at the bottom of the table and moving towards the top. Then, it checks + the root context, which is the global scope of the source code. If it finds a non- + ambiguous function or variable in a context, it stops searching. If it finds more than + one function or variable in a context, it reports an error and stops running. We will + discuss how to handle ambiguous functions and variables later. + +5.2 Testing simple functions + We will now build on the previous example to test the return value from a simple + function. Consider the code below: + + package MyPackage is + function Update(Value : Natural) return Natural; + end MyPackage; + + package body MyPackage is + GlobalVariable : Natural := 0; + + function Update(Value : Natural) return Natural is + begin + GlobalVariable := Value; + return GlobalVariable; + end Update; + end MyPackage; + + + The Update function assigns the input value it is passed to GlobalVariable, + and then returns this. Figure 5.3 shows an example of how to test this function. + + +Spreadsheet Test Format User Guide vWF20190404 19 +Testing simple functions Writing test sheets: Ada + + + Figure 5.3: Testing a simple function + + We are testing the Update function. Because we are testing this function, we refer + to it as the unit under test. Each test can include any number of units under test. + + The test shown in Figure 5.3 has some new features compared to the previous + one. These are explained below. + + The test includes a Scope table. A scope is a list of one or more units under test. + The main use of a scope is to instruct RapiTest how to report your test data. The + text Update in the table instructs RapiTest to report data for the Update function. + + The first operation in the test is to run the unit under test, Update. This specifies + that Update should be called at this point in the test. While you do not always + need to provide a run operation to specify where a unit under test is called, it is + strongly recommended as it improves the readability of tests. + + Note that different terminology is used to describe the behavior of this test com- + pared to the one in Section 5.1. In the Variable column, Value is the input para- + meter of Update, and return is the Ada keyword that specifies the return value + of this function. The values you enter in the Variable column are case-insensitive + for Ada, and should reflect the parameter names in your code. + + The test defined in this example includes text in the Call or stub column of the + test table. In this column, you must specify the function you want to test or stub + for each test operation. In the previous example, we did not need to specify this, + because GlobalVariable is a global variable, and not part of a function. + + There is a reason that Update only appears once in the test definition. RapiTest + parses each new function name in the Call or stub column as a new invocation of + the called function or stub. When a Call or stub cell is blank, RapiTest assigns the + test operation to the previous function entered in the Call or stub column. Thus, by + leaving cells D18-19 blank, we specify that the operations in these fields apply + to the same instance of Update as that specified in cell D17. + + +20 Spreadsheet Test Format User Guide vWF20190404 +Writing test sheets: Ada Stubbing functions + + +5.3 Stubbing functions + You can define functions to stub (replace or modify) in the Spreadsheet Test For- + mat. RapiTest can generate test code to replace or modify functions, check against + inputs and outputs and rewrite functions with complex logic. This means that it can + create behavior described by the terms stubs, mocks, fakes and spies – it uses + the term stubs to refer to these behaviors collectively. For more information, see + Section 3.1.4 in the RapiTest User Guide. + + In the code below, we have added two new functions to the MyPackage package + we used in Section 5.2: + + package MyPackage is + function Update(Value : Natural) return Natural; + procedure Set(Value : Natural); + function Get return Natural; + end MyPackage; + + package body MyPackage is + GlobalVariable : Natural := 0; + + function Get return Natural is + begin + return GlobalVariable; + end Update; + + procedure Set(Value : Natural) is + begin + GlobalVariable := Value; + end Update; + + function Update(Value : Natural) return Natural is + begin + Set(Value); + return Get; + end Update; + end MyPackage; + + + The Set function assigns its input to GlobalVariable. The Get function re- + turns the value of GlobalVariable. Update now calls both Set and Get + during its execution. + + We can stub the Set function to ensure that Update calls it when it executes. + Figure 5.4 shows how to do this. + + +Spreadsheet Test Format User Guide vWF20190404 21 +Stubbing functions Writing test sheets: Ada + + + Figure 5.4: Stubbing a function + + Figure 5.4 includes a Stubs table. RapiTest stubs the functions listed in this table + when it generates test code. We have left the Default field blank – this is only + needed when the stubbed function is called unexpectedly and the original version + of the stubbed function should not be called. + + Note + + You cannot assign the same function as both a unit under test and a stub. + Thus, you cannot write the same function in both the Scope and Stubs ta- + bles in a single test sheet. + + Note that we wrote the test with the unit under test (Update) before the stub (Set) + that Update calls during its execution. As mentioned in Section 5.1, you must + write tests to represent the control flow of your program. + + We added a Description entry in the Test details column of the test table. You can + add any number of fields in this column, which must be column B of the worksheet. + We typed the value that corresponds to this field in the Text column, which must + be column C of the worksheet. RapiTest outputs the fields and values in these + columns to your report when it converts and runs your tests. + + The test in Figure 5.4 is insufficient for the test specification in the Description. If + we cannot see the code in question, we do not know whether or not Set is written + + +22 Spreadsheet Test Format User Guide vWF20190404 +Writing test sheets: Ada Stubbing functions + + + to return 67890 regardless of its input. We can add another test to address this + by adding a new test to our test table, as shown in Figure 5.5. + + + Figure 5.5: Adding a new test + + In the example in Figure 5.5 we have specified a new test definition by adding a + new Value column to the test table. Each test definition comprises the information + in a single Value column as well as all other information in the test table. We have + not changed the rest of the test sheet. + + Note that we moved the value for the Name of our tests from the Text column to the + Value column. When you specify a value for a field in the Text column, it applies to + all tests in the test table. When you specify a value in the Value column, however, + it only applies to the test described in that column of the test table. Because the + specification for both tests is the same, we have chosen to leave the Description + in the Text column, so it applies to both tests. To make it easier to read your tests, + we recommend that you give each test a unique Name. + + We may also want to stub the Get function to ensure that our package behaves + as expected. The following example shows the test sheet after adding a test to + stub the Get function, Figure 5.6. + + +Spreadsheet Test Format User Guide vWF20190404 23 +Stubbing functions Writing test sheets: Ada + + + Figure 5.6: Stubbing multiple functions + + We have added an entry for Get in our Stubs table, defining it as a stubbed func- + tion. + + We wrote a new test by adding a new section to our test table. This is necessary + because the series of test operations we defined for the tests to stub Set and + Get are different. We call this series of test operations a test sequence. The test + sequence for the Stub Set tests, for example, defines two operations: set the + Value variable of Update, and check the Value variable of Update. Each + time you want to define a new test sequence, you must either add a new section + to your test table or use a new test sheet. + + In this example, we added a new section to our test table by typing New test in + column B. When RapiTest encounters this text, it starts a new section. + + The test sequence of the Stub Get test includes a new notation, :uut. This + is a shorthand notation, as are all elements in the Spreadsheet Test Format that + begin with :. This notation specifies that a test operation should be carried out + on the most recently invoked unit under test, which is the one that was invoked + closest above the current row in the test table. As we discussed previously, you + + +24 Spreadsheet Test Format User Guide vWF20190404 +Writing test sheets: Ada Handling overloaded functions + + + should not specify the name of a function more than once when referring to the + same invocation of it. + + In this case, we have used :uut to specify that the check operation should be + carried out on the Update function and not the Get function. + + The most common reason to use the :uut notation is to specify checking the + return of a function. To specify that an operation applies to a stub (such as Get), + you can use the :stub notation. + +5.4 Handling overloaded functions + The Spreadsheet Test Format includes a number of features that let you handle + overloaded functions and other forms of ambiguity to ensure your tests are ex- + plicit. In the code below, we have expanded our previous package to include two + functions with the same name but different signatures. + + package body MyPackage is + GlobalVariable : Natural := 0; + GlobalFloat : Float := 0.0; + + function Get return Natural is + begin + return GlobalVariable; + end Get; + + procedure Set(Value : Natural) is + begin + GlobalVariable := Value; + end Set; + + function Update(Value : Natural) return Natural is + begin + Set(Value); + return Get; + end Update; + + function Get return Float is + begin + return GlobalFloat; + end Get; + + procedure Set(Value : Float) is + begin + GlobalFloat := Value; + end Set; + + function Update(Value : Float) return Float is + begin + Set(Value); + return Get; + end Update; + end MyPackage; + + +Spreadsheet Test Format User Guide vWF20190404 25 +Handling overloaded functions Writing test sheets: Ada + + + There are now two versions of the Update, Set and Get functions, one that + handles natural numbers and one that handles floating point numbers. If we tried + to use the example worksheet in Figure 5.6, RapiTest would be unable to disam- + biguate between the two possible functions in each case, and would not convert + the test worksheet. Figure 5.7 shows how you can resolve this ambiguity using + the Spreadsheet Test Format. + + + Figure 5.7: Resolving function ambiguities + + In Figure 5.7, we have specified the signature for each of the Update, Set and + Get functions in the Scope and Stubs tables: Update and Set have a Value of + the Natural type, and Get has a return of the Natural type. By specifying + these signatures, we have instructed RapiTest that our test definitions refer to the + functions that handle natural numbers and not the ones that handle floating point + numbers. + + You only need to specify the signature of functions that are overloaded in a given + context. If you specify any of the parameters or types for a function in the Spread- + sheet Test Format, you must specify all of the parameters and their types for that + function. In the previous examples in this chapter, we typed ? in the Parameter + + +26 Spreadsheet Test Format User Guide vWF20190404 +Writing test sheets: Ada Handling overloaded functions + + + and Type fields. When you type a ? in the Parameter and Type fields for a function, + RapiTest will accept a function with any number of parameters of any type, so long + as the name of the function is unique in its context. If you leave the Parameter and + Type columns blank, RapiTest expects that a function has no parameters, and will + fail to convert your test sheet if it does have parameters. + + Figure 5.7 contains comments in cells B11 and B18. You can include a comment + in column B of any worksheet, as described in Section 2.1: Spreadsheet Test For- + mat syntax. + + Beside the third test in the sheet, we typed : in all of the Value columns. This spec- + ifies that these operations should not be carried out. Because there are no oper- + ations in H34:H37, RapiTest does not create a test for this part of the table. You + must use : to specify that an operation should not be carried out for a given test. + Blank fields in test definitions indicate that an empty value is necessary for an op- + eration. This can be used, for example, to run a function with no input parameters. + + Looking again at function ambiguity, imagine that you wanted to test both Update + functions in the code above during a single test. This presents another challenge + because of ambiguity: how can RapiTest disambiguate between the two functions? + + You can overcome this challenge by using shorthand notation to explicitly refer to + a function with a specific signature. Figure 5.8 shows how to do this. + + + Figure 5.8: Using shorthand notation + + +Spreadsheet Test Format User Guide vWF20190404 27 +Using local variables Writing test sheets: Ada + + + In Figure 5.8, we have specified shorthand notations for each of the Update func- + tions in the Scope table by typing upint and upfloat in the Shorthand column. + + Note + + You cannot specify the same shorthand notation more than once in a test + sheet. + + + In our test definition, we have used our upint and upfloat notations to specify + that the first set of test operations refers to the Update function that has parame- + ters with natural types and the second refers to the function that has parameters + with floating point types. We specified this by typing :upint and :upfloat in + the Call or stub column. Notice the additional : – you must include a : before you + use a shorthand notation. We used a shorthand previously in this chapter, when + we used the notation :uut, Section 5.3. + + You can use shorthand notation for other reasons than to disambiguate between + overloaded functions, particularly to reduce the amount you need to type to define + your tests. + +5.5 Using local variables + You can create variables in the Spreadsheet Test Format that are local to a test. + These let you, for example, define compound data types or data that can be deref- + erenced when supplying parameters to calls. + + Consider the code below: + + package MyPackage is + procedure AddOne(Value : access Integer); + end MyPackage; + + package body MyPackage is + procedure AddOne(Value : access Integer) is + begin + Value.all := Value.all + 1; + end AddOne; + end MyPackage; + + + To test the AddOne function, we must use a local variable. Figure 5.9 shows how + to do this. + + +28 Spreadsheet Test Format User Guide vWF20190404 +Writing test sheets: Ada Using local variables + + + Figure 5.9: Using local variables + + In the Test locals table, we have specified a local variable called MyInt, which + has the Integer type. The Test locals table lets you specify local variables for + the current test sheet. + + In the test table, we have referenced MyInt to produce a pointer and passed this + to AddOne. AddOne dereferences the pointer and adds one to MyInt, which + we check the value of. Without using a local variable, we would not be able to test + AddOne. + + Let's look at a more complicated example of using local variables. Consider the + code below: + + package MyPackage is + type MyStruct is record + MyInt : Integer := 0; + MyFloat : Float := 0.0; + end record; + + procedure AddOne(Value : access MyStruct); + end MyPackage; + + package body MyPackage is + procedure AddOne(Value : access MyStruct) is + begin + Value.MyInt := Value.MyInt + 1; + Value.MyFloat := Value.MyFloat + 1.0; + end AddOne; + end MyPackage; + + + In this code, MyStruct is a structure with two variables, MyInt and MyFloat. + Using local variables, we can declare input values for each of these variables in + the Test locals table and use them in our tests (see Figure 5.10). + + +Spreadsheet Test Format User Guide vWF20190404 29 +Using local variables Writing test sheets: Ada + + + Figure 5.10: Advanced local variables + + In the Test locals table, we have specified the variables MyInt and MyFloat in + the Element column. Each of these variables belongs to the MyStruct type and + is part of the MyLocal variable. + + We have also specified two initializers for MyLocal, Positive and Negative. + Initializers group together assignments for multiple variables, so you can assign + these using a single test operation. You can add as many initializers as you want + by adding a new column to the end of the Test locals table for each. + + In the test table, we assigned the Positive and Negative initializers to tests + using the init operation. To check the value in each variable, we specified both + the local variable and its sub-variable, such as in the example MyLocal.MyInt. + + +30 Spreadsheet Test Format User Guide vWF20190404 +Writing test sheets: Ada Testing multi-threaded software + + +5.6 Testing multi-threaded software + So far, we've considered how to test software that runs on a single thread, and is + thus deterministic in its behavior. RapiTest also supports testing the behavior of + multi-threaded software, which may be non-deterministic as it depends on a task + scheduling system. + + Consider the code below: + + procedure Read is + begin + loop + CurValue := ReadSensor; + end loop; + end Read; + + procedure Process is + begin + loop + ProcessValue(CurValue); + end loop; + end Process; + + + Read and Process are threads in a system, and their invocation is handled + by an overlying context switch routine. The ReadSensor and ProcessValue + subprograms they call are lower level functions that read and process inputs from + the system, respectively. + + The example below shows a multi-threaded test for these tasks, Figure 5.11. + + + Figure 5.11: Testing multi-threaded software + + +Spreadsheet Test Format User Guide vWF20190404 31 +Testing multi-threaded software Writing test sheets: Ada + + + A schematic representing the overall test behavior is shown in Figure 5.12. We'll + examine this behavior in detail below. + + + Figure 5.12: Multithreaded test behavior schematic + + Multithreaded tests include some test operations and features not present in sin- + gle-threaded tests. + + The test specifies in Figure 5.11 Read and Process as units under test (in the + Scope table), and ReadSensor and ProcessValue as stubs (in the Stubs + table). + + The structure of the Test table is different to that for single-threaded tests, and + includes operations unique to multi-threaded testing. While single-threaded tests + include a unique Value column for each test to run, multi-threaded tests must in- + clude a single Main column, and at least two columns that are named beginning + with Thread. Test operations included in the Main column define behavior for the + threads run in the test, such as running them, forcing them to wait or sleep, or halt- + ing them. Test operations included in columns corresponding to a specific Thread, + meanwhile, define what to do within that thread. + + Our test includes two threads, Thread 1 and Thread 2, and the test is written + in three sections (demarcated by bold lines in the Test table): + 1. The first section invokes and defines test behavior to apply in Thread 1. + 2. The second section invokes and defines test behavior to apply in Thread 2. + + +32 Spreadsheet Test Format User Guide vWF20190404 +Writing test sheets: Ada Testing multi-threaded software + + + 3. The final section defines behavior for the main test driver. + + Let's interpret the test, starting with the first section. The run operation in row 18 + invokes Thread 1. The duration operation specifies a maximum duration of + 1000 for the thread, instructing RapiTest to halt it non-fatally (without causing a + test failure) this duration after it invokes the thread. By default, durations are in + milliseconds. The test and stub operations for Read and ReadSensor in rows + 20-21 behave in the same way they would in single-threaded tests. + + In the next section, the run operation in row 22 invokes Thread 2. Rows 24-25 + define test and stub operations for Process and ProcessValue. As Thread 1 + is invoked earlier in the overall test sequence than Thread 2, we'll definitely invoke + Read before Process (as shown in Figure 5.12). After their invocation, however, + the threads could run in any order as the software is non-deterministic. + + In the final section, the wait operation in row 25 forces RapiTest to wait until + Thread 1 finishes running (in this case, until its duration expires). The kill + operation in row 26 then forces Thread 2 to halt non-fatally, ending the test. + + Note that, throughout, operations that define behavior for when a thread runs are + defined in the Main column, while those defining what a thread does are defined in + the Thread column. While, in this example, we've only assigned a single subpro- + gram to each thread, you can assign any number. + + +Spreadsheet Test Format User Guide vWF20190404 33 +Working with arrays Writing test sheets: Ada + + +5.7 Working with arrays + This section demonstrates how to work with arrays in the Spreadsheet Test Format. + + Consider the code below: + + package ArrayFunctions is + type ArrayType is Array (Positive range <>) of Integer; + procedure Reset(Array : in out ArrayType ; Size : in Integer); + end ArrayFunctions; + + package body ArrayFunctions is + procedure Reset(Array : in out ArrayType ; Size : in Integer) is + begin + for i in 1..Size loop + Array(i) := 1; + end loop; + end Reset; + end ArrayFunctions; + + + The Reset function resets the value in every index of an array it is passed to 1. + Figure 5.13 shows how to use a local variable to test this function. + + + Figure 5.13: Working with arrays + + In this test, we created a local variable, LocalArray, to pass to Reset. We then + set input parameters for Reset and checked that it reset the values at each index + in the array as expected. + + The LocalArray variable that we added to the Test Locals table set up an ar- + ray of three elements with values 3, 4 and 5. This example shows how to spec- + ify arrays and input values for them in the Spreadsheet Test Format – here, we + specified the type of the array by using the ArrayType type defined in the code, + and input values as comma separated values enclosed in a pair of curly braces, + {3, 4, 5}. + +34 Spreadsheet Test Format User Guide vWF20190404 +Writing test sheets: Ada Using accesses + + + To run the test, we set values for both input parameters of LocalArray. We + set the Array parameter by using the local variable we set up, LocalAr- + ray, and the Size parameter by using get.length(LocalArray). The + get.length() function, as we would expect, returns the length of an array. + + To check that Reset works correctly, we used three check operations using a + new notation, LocalArray[X]. The operations in rows 20 to 22 of the test + instruct RapiTest to check that the values in LocalArray at indexes 0, 1 and + 2 all equal 1. + + The syntax for specifying an array type, specifying input values to an array, refer- + encing the length of an array and indexing values in it is identical regardless of + whether the array is in a unit under test, stubbed function or local variable. + +5.8 Using accesses + This section describes how to use accesses in the Spreadsheet Test Format. This + builds on the example code used in Section 5.5: Using local variables. + + To define an access as a parameter in the Scope table, enter the parameter it + points to in the Parameter column. In the Type column, type pointer and the + type referenced by the access, for example pointer MyStruct, as shown in + Figure 5.14. + + + Figure 5.14: Using accesses + + There are three ways of referencing or dereferencing accesses in the Spreadsheet + Test Format, as shown in Figure 5.15: + • get.pointer(x) – this returns the access to x. + • get.address(x) – this returns the address of x. + • get.deref(x) – this dereferences pointer x one level. + • get.object(x) – this fully dereferences x. The operation dereferences all + pointers until it reaches data that is not a pointer. + + +Spreadsheet Test Format User Guide vWF20190404 35 +Setting configuration options Writing test sheets: Ada + + + Figure 5.15: Referencing and dereferencing pointers + + You can check that two pointers are equal, see Figure 5.16. + + + Figure 5.16: Comparing pointers + +5.9 Setting configuration options + You can set configuration options to test sheets that define how the tests in the + sheet behave. You do not need to include any of these options in your test sheets. + + The options available are described below: + • Blackbox – this tells RapiTest to generate all tests in the sheet as black box + tests. + • Control flow – this specifies that all stubs in the sheet must be written to + represent the order they are called during each test. If they are not, RapiTest + reports an error when converting the sheet. Section 5.11.1: Working with con- + trol flow describes how to use the Control flow setting. + • Disabled – this tells RapiTest to ignore the test sheet when preparing a test + suite. You may want to use this option, for example, while you are developing + tests and are not yet ready to execute them. + • Explicit stubs – this specifies that the number of times a stub is + called must be specified. You can specify these calls using operations set or + called, see Section 5.11: Advanced stubbing. + • Remove original stubs – this tells RapiTest to remove the original ver- + sion of stubbed functions from tests. If you use this option, you need to ensure + + +36 Spreadsheet Test Format User Guide vWF20190404 +Writing test sheets: Ada Advanced checking + + + that behavior has been specified for the stub if it is called during a test. If the + test tries to call a stubbed function and no behavior has been specified for it, + RapiTest reports an error. + + Configuration options are specified in a Configuration section and are assigned a + value of either Yes or No, see Figure 5.17. The default value for all configuration + options is No, and this value is used if the option is not included in a test sheet. + You can write configuration options in any order. + + + Figure 5.17: Setting configuration options + +5.10 Advanced checking + This section describes advanced checking features of the Spreadsheet Test For- + mat. + +5.10.1 Advanced numerical check operations + The default check operation checks that a Variable is equal to the specified + Value. You can define other types of numerical checks in the Variable column + as shown below (see Figure 5.18): + • check.ne – checks the Variable is not equal to the specified Value. + • check.lt – checks the Variable is less than the specified Value. + • check.le – checks the Variable is less than or equal to the specified + Value. + • check.gt – checks the Variable is greater than the specified Value. + • check.ge – checks the Variable is greater than or equal to the specified + Value. + • check.eq – checks the Variable is equal to the specified Value (the + same as check). You can add a tolerance to the equality to compare floating + point numbers by adding a number or percentage tolerance in parentheses + immediately after check.eq: (num) or (num%)). + + The test table in Figure 5.18 shows how some of these operations can be used to + test the code in Section 5.4: Handling overloaded functions. + + +Spreadsheet Test Format User Guide vWF20190404 37 +Advanced checking Writing test sheets: Ada + + + Figure 5.18: Advanced numerical check operations + + In these tests, we assigned a value to GlobalFloat, which is returned by Get, + the unit under test. We checked this value using each of the check operators listed + above. + +5.10.2 Checking strings + You can check that strings match a specific value by using the check.string + operation. + + Consider the code below: + + package MyPackage is + GlobalString : String := "hello world"; + GlobalString2 : String := GlobalString; + end MyPackage; + + + You can check the value of a string in a variable by specifying its name in the + Variable column and the string that you want to check (including enclosing "" + characters) in the Value column. + + You can also check the value of a string in one variable against the value in another + by including the name of one variable in the Variable column and the other in + the Value column. + + Note + + When specifying a variable in the Value column in this way, you must in- + struct RapiTest which package it is in – RapiTest does not search through + applied Contexts in this column. + + + Figure 5.19 shows a test table that can be used to test the example code above. + + +38 Spreadsheet Test Format User Guide vWF20190404 +Writing test sheets: Ada Advanced stubbing + + + Figure 5.19: Checking strings + +5.10.3 Grouping checks + You can group multiple checks together into a cluster by applying check crite- + ria, see Figure 5.20. + + + Figure 5.20: Check criteria + + The test in Figure 5.20 includes two sets of check criteria, each of which includes + a single check. All checks within a single criteria must all pass for that criteria to + pass. If you apply multiple criteria, at least one of them must pass for your test + to pass as a whole. + + As such, the test in Figure 5.20 will pass if the return value from ReadSensor is + either greater than 5 or less than 2. + + Note + + Applying check criteria changes the syntax requirements of the Spread- + sheet Test Format. + + The only valid operations after a check criteria are any type of check oper- + ation, or another check criteria. + + +5.11 Advanced stubbing + This section describes advanced stub operations and notations you can define + using the Spreadsheet Test Format. These are described below: + • stubbed – this operation specifies that a function should be stubbed during + a test without applying any other behavior to the stubbed function. It can be + used to stub a function during a test without applying specific behavior to it, + essentially creating an empty stub. + + +Spreadsheet Test Format User Guide vWF20190404 39 +Advanced stubbing Writing test sheets: Ada + + + • called – this operation checks that a stub is called the specified number of + times during a test. + • pass – this operation causes a test to pass immediately when the operation + executes. + • fail – this operation causes a test to report that it failed if the stubbed func- + tion is called. + • set – this operation can be used not only to set parameters inside the stub + when it is called, but also to set global variables during the call. + • call – this operation specifies calling any function. It is most often used with + the :original notation to specify calling the original version of a stubbed + function. + • :original – this notation references the original version of a stubbed func- + tion rather than the stubbed version of it. + + The test table in Figure 5.21 shows how these operations can be used to test the + code in Section 5.4: Handling overloaded functions. + + + Figure 5.21: Advanced stub operations + + In this example, upint and upfloat are the units under test (shown in red), + and setint and setfloat are stub functions (shown in green). Color-coding + your tests may make it easier to read them. + + The first set of tests checks that after calling Update, Set is called only once. + + The second set of tests checks that each Update function does not call the Set + function that handles different types to it. + + +40 Spreadsheet Test Format User Guide vWF20190404 +Writing test sheets: Ada Advanced stubbing + + + The final test modifies the stub setint so that it sets the value of GlobalVari- + able when it is called. Note the notation used to reference GlobalVariable + (:global.). This prefix specifies that this is a global variable. We must use this + notation to reference a global variable from inside a stub. + +5.11.1 Working with control flow + The Control flow configuration option lets you be explicit about stub ordering in + your tests, see Section 5.9: Setting configuration options. While you must always + write test operations that apply to your unit under test in the order you want them + to execute, this option instructs RapiTest to expect the same behavior from stubs. + + You can use the Control flow option together with the called operation to check + that each of your stubs is executed during a test, like in the example shown in + Figure 5.22. + + + Figure 5.22: Control flow example + + The code being tested takes an input value and does the following: + 1. If the input is even, it executes the function ProcessEven. Otherwise, it + executes the function ProcessOdd. + 2. If the input is positive, it executes the function ProcessPositive. Other- + wise, it executes the function ProcessNegative. + + +Spreadsheet Test Format User Guide vWF20190404 41 +Advanced multi-threaded testing Writing test sheets: Ada + + + The even positive test checks that the ProcessEven and ProcessPos- + itive functions are each called once (in that order) when 68790 is passed as + an input parameter to the unit under test, ProcessValue. Field G26 is ignored + because of the : character, see Section 5.4: Handling overloaded functions. Be- + cause of this, the execution of ProcessNegative is not checked. If field G26 + contained a numeric value, the test would fail, because the ProcessNegative + function is never called when ProcessValue processes a positive number. + + Likewise, the even negative test checks that the ProcessEven and + ProcessNegative functions are each called once (in that order) when + -45722 is passed as an input parameter to ProcessValue. The execution of + ProcessPositive is not checked in this test. + +5.11.2 Calling the original function + Normally, the original version of a stubbed function is never called during a test, + and only the stubbed version is. You may want to call the original version, however, + particularly if the function has complex logic and functionality that you do not want + to or cannot replicate using the Spreadsheet Test Format. + + The original version will be called during a test if you use the :original nota- + tion along with either the call or set operations. Figure 5.23 shows how to do + this, using the code described in Section 5.11.1: Working with control flow as an + example. + + + Figure 5.23: Calling the original function + + In the example, the row that contains the text :even executes the original version + of ProcessEven. Everything that occurs during its normal execution occurs, for + example setting global variables. In the next row, the set operation is used to + set the return of ProcessPositive (in the call even positive test) by + calling the original version of the stubbed function. + +5.12 Advanced multi-threaded testing + Section 5.6: Testing multi-threaded software introduced multi-threaded testing. + This section provides a reference of the multi-threaded test operations available in + + +42 Spreadsheet Test Format User Guide vWF20190404 +Writing test sheets: Ada Advanced multi-threaded testing + + + RapiTest. Some multithreaded testing operations apply to the Main test sequence, + while others apply to an individual Thread; this is clearly identified in the list of + operations below: + • duration (Thread) – this assigns a maximum duration for a test to run based + on the invocation time for the thread named in the Call or stub column to run. + After this duration has passed from the first time that the named thread was + invoked, the test will halt non-fatally (not causing a test failure). By default, + the specified duration is in units of milliseconds, but this depends on your + integration. + • kill (Main) – this halts the thread named in the Call or stub column non-fatally + (RapiTest will not report test failures as a result of invoking the operation). + • priority (Main) – this sets the priority for the thread named in the Call or + stub column. When running a test harness, threads with a lower numbered pri- + ority can pre-empt those with a higher numbered priority, for example, Thread + 1 which has a priority of 1 can pre-empt Thread 2, which has a priority of 2. + • run (Main or Thread) – while not unique to multi-threaded testing, this de- + serves special mention. Within the Main test sequence, run invokes the thread + named in the Call or stub column. Within the test sequence for a specific + Thread, run behaves as it would within a single threaded test. + • timeout (Thread) – this applies a watchdog timer to a thread. If the thread + is still executing at any point after the specified duration has passed since the + thread started executing, the test will halt and fail. + • wait (Main) – this causes the test to wait until the thread named in the Call + or stub column finishes executing before applying the next operation in the + test sequence. + + The test table in Figure 5.24 shows a valid test including these operations. + + +Spreadsheet Test Format User Guide vWF20190404 43 +Using raw code Writing test sheets: Ada + + + Figure 5.24: Advanced multithreaded testing operations + +5.13 Using raw code + You can use raw code in your test sheets. Raw code is inserted directly at an + appropriate place in a test harness without being altered. + + While using raw code is not recommended generally because of the power of the + Spreadsheet Test Format, it is useful in the following situations: + • When it may be more efficient and lead to more readable tests to use raw + code rather than the features provided by the Spreadsheet Test Format to write + certain parts of your tests. This could be due to the presence of complicated + data structures in your source code, for example. + • When it is not possible to write tests using features currently avail- + able in the Spreadsheet Test Format. In this case, please contact us at + support@rapitasystems.com to discuss whether we could add new features + to RapiTest to better support your needs. + + You can use raw code in test sheets in every field where an operation, variable or + value is expected. Figure 5.25 shows an example of the use of raw code to set + and check the values of an array using a complex expression. + + +44 Spreadsheet Test Format User Guide vWF20190404 +Writing test sheets: Ada Black box testing + + + Figure 5.25: Using raw code + + The AddOne function takes an input value and returns that value plus one. While + it is possible to create the same logic in the test without using raw code, the test + sheet would be less readable than the example shown below. + +5.14 Black box testing + RapiTest supports black box testing – testing the interface to functions in your + source code without making any modifications to the functions themselves. + + Note + + To be able to test a function through black box testing, your code must in- + clude an interface to the function that is scoped outside of the function it- + self. + + + To assign tests in a test sheet as black box tests, apply the Blackbox configuration + option to the test sheet, see Figure 5.26. + + +Spreadsheet Test Format User Guide vWF20190404 45 +Black box testing Writing test sheets: Ada + + + Figure 5.26: Black box testing + + +46 Spreadsheet Test Format User Guide vWF20190404 + Writing test sheets: C and +6 C++ + Test sheets contain information defining the tests you want RapiTest to generate. + This chapter describes how to define tests for C and C++ code in test sheets + by working from a simple example test and adding complexity to this gradually. + Many terms used in the Spreadsheet Test Format are described in this chapter. + Chapter 8: Glossary contains a list of these, along with other important terms. + + The examples presented are shown below: + • Setting and checking global variables + • Setting and checking static class variables (C++) + • Testing simple functions + • Stubbing functions + • Testing overloaded functions (C++) + • Using local variables + • Setting and checking object members (C++) + • Testing functions in inherited classes (C++) + • Testing multi-threaded software + • Working with arrays + • Using pointers + • Setting configuration options + • Advanced checking + • Advanced stubbing + • Advanced multi-threaded testing + • Using raw code + • Black box testing + +6.1 Setting and checking global variables + Consider the following C code: + + int globalVar = 0; + + void testFunction() { + globalVar++; + } + + + Note that globalVar is an integer variable with global scope. + + +Spreadsheet Test Format User Guide vWF20190404 47 +Setting and checking global variables Writing test sheets: C and C++ + + + Figure 6.1 shows a test that sets and checks the value of globalVar. + + + Figure 6.1: Setting and checking a global variable + + The table in Figure 6.1 defines a single test. This type of table is referred to hereafter + as a test table. Each test table can define one or more tests. Inside this table, we + defined our test in a test definition. This includes everything we need to identify + the test and tell it how to behave: its Name, Requirements, and everything in the + Variable, Operation and Value columns. Ignore the Call or stub column for now, we + will discuss it later. + + The test defined in Figure 6.1 sets globalVar to 12345, and then checks that + the variable has this value. We have also named the test Global Variable + and specified that it tests requirement 1. + + RapiTest is instructed to parse the test table by the presence of the Tests sec- + tion header. Like all section headers, this is written in column A of the worksheet + (see Chapter 3: Spreadsheet Test Format workbooks). The Tests section header + instructs RapiTest to recognize that the section contains test definitions. + + The test definition for this test comprises all the fields in the test table. Row 35 + instructs RapiTest to set the variable globalVar to 12345, and row 36 instructs + it to check this value. Set and check are test operations, which instruct RapiTest + what to do with a passed Variable and Value. + + You must write test definitions in the order you want RapiTest to carry out test + operations. Typically, this means you must write them to reflect the control flow + of your program. The order in which you write stubs, however, does not generally + matter – you can write these to represent control flow or not, unless you have + the Control Flow configuration option set, see Section 6.12: Setting configuration + options. Coming back to the test, if we had written the operations in Figure 6.1 in + the reverse order, RapiTest would attempt to check globalVar before setting + its value. + + When RapiTest generates your tests, it searches for functions or variables in a test + definition in a specific order. First, it checks each context in the Contexts table, + beginning at the bottom of the table and moving towards the top. Then, it checks + the root context, which is the global scope of the source code. If it finds a non- + ambiguous function or variable in a context, it stops searching. If it finds more than + one function or variable in a context, it reports an error and stops running. We will + discuss how to handle ambiguous functions and variables later. + + +48 Spreadsheet Test Format User Guide vWF20190404 + Setting and checking static class variables (C+ +Writing test sheets: C and C++ + +) + +6.2 Setting and checking static class variables (C++) + Consider the following C++ class with static class variables: + + class SimpleClass { + public: + static int publicVar; + private: + static int privateVar; + }; + + void testFunction() { + SimpleClass classObj; + } + + + Using a similar method to the previous example, we can set and check these + variables, as shown in Figure 6.2. + + + Figure 6.2: Setting and checking C++ static class variables + +6.3 Testing simple functions + We will now build on the example from Section 6.1 to test the return value from a + simple function. Consider the code below: + + int globalVar = 0; + + int update(int value) { + globalVar = value; + return globalVar; + } + + + The update() function assigns the input value it is passed to globalVar, and + then returns this. Figure 6.3 shows an example of how to test this function. + + +Spreadsheet Test Format User Guide vWF20190404 49 +Testing simple functions Writing test sheets: C and C++ + + + Figure 6.3: Testing a simple function + + We are testing the update() function. Because we are testing this function, we + refer to it as the unit under test. Each test can include any number of units under + test. + + The test shown in Figure 6.3 has some new features compared to the previous + one. These are explained below. + + The test includes a Scope table. A scope is a list of one or more units under test. + The main use of a scope is to instruct RapiTest how to report your test data. The text + update in the table instructs RapiTest to report data for the update() function. + The first operation in the test is to run the unit under test, Update. This specifies + that Update should be called at this point in the test. While you do not always + need to provide a run operation to specify where a unit under test is called, it is + strongly recommended as it improves the readability of tests. + + Note that different terminology is used to describe the behavior of this test com- + pared to the one in Section 6.1. In the Variable column, value is the input para- + meter of update(), and return is the keyword that specifies the return value + of this function. The values you enter in the Variable column are case-sensitive for + C and C++, and should reflect the parameter names in your code. + + The test defined in this example includes text in the Call or stub column of the + test table. In this column, you must specify the function you want to test or stub + for each test operation. (In Section 6.1 we did not need to specify this because + globalVar is a global variable and not part of a function.) + There is a reason that update only appears once in the test definition. RapiTest + parses each new function name in the Call or stub column as a new invocation of + the called function or stub. When a Call or stub cell is blank, RapiTest assigns the + test operation to the previous function entered in the Call or stub column. Thus, by + leaving cells D13-14 blank, we specify that the operations in these fields apply + to the same instance of update() as that specified in cell D12. + + +50 Spreadsheet Test Format User Guide vWF20190404 +Writing test sheets: C and C++ Stubbing functions + + +6.4 Stubbing functions + You can define functions to stub (replace or modify) in the Spreadsheet Test For- + mat. RapiTest can generate test code to replace or modify functions, check against + inputs and outputs and rewrite functions with complex logic. This means that it can + create behavior described by the terms stubs, mocks, fakes and spies – it uses + the term stubs to refer to these behaviors collectively. For more information, see + Section 3.1.4 in the RapiTest User Guide. + + In the code below, we have added two new functions to the previous example: + + int globalVar = 0; + + int get() { + return globalVar; + } + + void set(int value) { + globalVar = value; + } + + int update(int value) { + set(value); + return get(); + } + + + The set() function assigns its input to globalVar. The get() function returns + the value of globalVar. update() now calls both set() and get() during + its execution. + + We can stub the set() function to ensure that update() calls it when it exe- + cutes. Figure 6.4 shows how to do this. + + +Spreadsheet Test Format User Guide vWF20190404 51 +Stubbing functions Writing test sheets: C and C++ + + + Figure 6.4: Stubbing a function + + Figure 6.4 includes a Stubs table. RapiTest stubs the functions listed in this table + when it generates test code. We have left the Default field blank – this is only + needed when the stubbed function is called unexpectedly and the original version + of the stubbed function should not be called. + + Note + + You cannot assign the same function as both a unit under test and a stub. + Thus, you cannot write the same function in both the Scope and Stubs ta- + bles in a single test sheet. + + + Note that we wrote the test with the unit under test (update()) before the + stub (set()), which update() calls during its execution. As mentioned in Sec- + tion 6.1, you must write tests to represent the control flow of your program. + + We added a Description entry in the Test details column of the test table. You can + add any number of fields in this column, which must be column B of the worksheet. + We typed the value that corresponds to this field in the Text column, which must + be column C of the worksheet. RapiTest outputs the fields and values in these + columns to your report when it converts and runs your tests. + + The test in Figure 6.4 is insufficient for the test specification in the Description. If we + cannot see the code in question, we do not know whether or not set() is written + to return 67890 regardless of its input. We can add another test to address this + by adding a new test to our test table, as shown in Figure 6.5. + + +52 Spreadsheet Test Format User Guide vWF20190404 +Writing test sheets: C and C++ Stubbing functions + + + Figure 6.5: Adding a new test + + In the example in Figure 6.5 we have specified a new test definition by adding a + new Value column to the test table. Each test definition comprises the information + in a single Value column as well as all other information in the test table. We have + not changed the rest of the test sheet. + + Note that we moved the value for the Name of our tests from the Text column to the + Value column. When you specify a value for a field in the Text column, it applies to + all tests in the test table. When you specify a value in the Value column, however, + it only applies to the test described in that column of the test table. Because the + specification for both tests is the same, we have chosen to leave the Description + in the Text column, so it applies to both tests. To make it easier to read your tests, + we recommend that you give each test a unique Name. + + We may also want to stub the get() function to ensure that our package behaves + as expected. The following example shows the test sheet after adding a test to + stub the get() function, Figure 6.6. + + +Spreadsheet Test Format User Guide vWF20190404 53 +Stubbing functions Writing test sheets: C and C++ + + + Figure 6.6: Stubbing multiple functions + + We have added an entry for get() in our Stubs table, defining it as a stubbed + function. + + We wrote a new test by adding a new section to our test table. This is necessary + because the series of test operations we defined for the tests to stub set() and + get() are different. We call this series of test operations a test sequence. The test + sequence for the Stub Set tests, for example, defines two operations: set the + Value variable of update(), and check the Value variable of update(). + Each time you want to define a new test sequence, you must either add a new + section to your test table or use a new test sheet. + + In this example, we added a new section to our test table by typing New test in + column B. When RapiTest encounters this text, it starts a new section. + + The test sequence of the Stub get() test includes a new notation, :uut. This + is a shorthand notation, as are all elements in the Spreadsheet Test Format that + begin with :. This notation specifies that a test operation should be carried out + on the most recently invoked unit under test, which is the one that was invoked + closest above the current row in the test table. As we discussed previously, you + should not specify the name of a function more than once when referring to the + same invocation of it. + + In this case, we have used :uut to specify that the check operation should be + carried out on the update function and not the get function. + + +54 Spreadsheet Test Format User Guide vWF20190404 +Writing test sheets: C and C++ Testing overloaded functions (C++) + + + The most common reason to use the :uut notation is to specify checking the + return of a function. To specify that an operation applies to a stub (such as get), + you can use the :stub notation. + +6.5 Testing overloaded functions (C++) + The Spreadsheet Test Format includes a number of features that let you handle + overloaded functions and other forms of ambiguity to ensure your tests are explicit. + In the code below, we have expanded the example from Section 6.2 to include + overloaded versions of set() and update(). + + int globalInt = 0; + int globalFloat = 0.0f; + + int getInt() { + return globalInt; + } + + void set(int value) { + globalInt = value; + } + + int update(int value) { + set(value); + return getInt(); + } + + float getFloat() { + return globalFloat; + } + + void set(float value) { + globalFloat = value; + } + + float update(float value) { + set(value); + return getFloat(); + } + + + There are now two versions of the update() and set(), one that handles inte- + gers and one that handles floating point numbers. (It is not possible to overload + get(), which differs in return type only.) If we tried to use the example worksheet + in Figure 6.6, RapiTest would be unable to disambiguate between the two possible + functions of each overloaded function, and would fail to convert the test sheet. + Figure 6.7 shows how you can resolve this ambiguity using the Spreadsheet Test + Format. + + +Spreadsheet Test Format User Guide vWF20190404 55 +Testing overloaded functions (C++) Writing test sheets: C and C++ + + + Figure 6.7: Resolving function ambiguities + + In Figure 6.7, we have specified the signature for the update() and set() + functions in the Scope and Stubs tables: update() and set() have a value + of type integer. By specifying these signatures, we have instructed RapiTest + that our test definitions refer to the functions that handle integer numbers and not + the ones that handle floating point numbers. Note that you only need to specify + the signature of functions that are overloaded in a given context. + + If you specify any of the parameters or types for a function in the Spreadsheet Test + Format, you must specify all of the parameters and their types for that function. + In the previous examples in this chapter, we typed ? in the Parameter and Type + fields. When you type a ? in the Parameter and Type fields for a function, RapiTest + will accept a function with any number of parameters of any type, so long as the + name of the function is unique in its context. If you leave the Parameter and Type + columns blank, RapiTest expects that a function has no parameters, and will fail + to convert your test sheet if it does have parameters. + + Figure 6.7 contains comments in cells B6 and B14. You can include a comment in + column B of any worksheet, as described in Section 2.1: Spreadsheet Test Format + syntax. + + +56 Spreadsheet Test Format User Guide vWF20190404 +Writing test sheets: C and C++ Testing overloaded functions (C++) + + + Beside the third test in the sheet, we typed : in all of the Value columns. This + specifies that these operations should not be carried out. Because there are no + operations in columns H42:H44, RapiTest does not create a test for this part + of the table. You must use : to specify that an operation should not be carried + out for a given test. Blank fields in test definitions indicate that an empty value is + necessary for an operation. This can be used, for example, to run a function with + no input parameters. + + Looking again at function ambiguity, imagine that you wanted to test both up- + date() functions in the code above during a single test. This presents another + challenge because of ambiguity: how can RapiTest disambiguate between the two + functions? + + You can overcome this challenge by using shorthand notation to explicitly refer to + a function with a specific signature. Figure 6.8 shows how to do this. + + + Figure 6.8: Using shorthand notation + + In Figure 6.8, we have specified shorthand notations for each of the update() + functions in the Scope table by typing upint and upfloat in the Shorthand + column. + + Note + + You cannot specify the same shorthand notation more than once in a test + sheet. + + In our test definition, we have used our upint and upfloat notations to specify + that the first set of test operations refers to the update() function that has para- + + +Spreadsheet Test Format User Guide vWF20190404 57 +Using local variables Writing test sheets: C and C++ + + + meters with natural types and the second refers to the function that has parame- + ters with floating point types. We specified this by typing :upint and :upfloat + in the Call or stub column. Notice the additional : – you must include a : before + you use a shorthand notation. We used a shorthand previously in this chapter, + when we used the notation :uut, Section 6.4. + + You can use shorthand notation for other reasons than to disambiguate between + overloaded functions, particularly to reduce the amount you need to type to define + your tests. + +6.6 Using local variables + You can create variables in the Spreadsheet Test Format that are local to a test. + These let you, for example, define compound data types or data that can be deref- + erenced when supplying parameters to calls. They are also required for testing C + ++ class objects, as shown in Section 6.7. + + Consider the code below: + + void addOne(int* value) { + *value = *value + 1; + } + + int main() { + int x = 1; + addOne(&x); + return 0; + } + + To test the addOne() function, we must use a local variable. Figure 6.9 shows + how to do this. + + + Figure 6.9: Using local variables + + +58 Spreadsheet Test Format User Guide vWF20190404 +Writing test sheets: C and C++ Using local variables + + + In the Test locals table, we have specified a local variable called myInt of type + int. The Test locals table lets you specify local variables for the current test sheet. + + In the test table, we have referenced myInt to produce a pointer and passed + this to addOne(). addOne() dereferences the pointer and adds one to myInt, + which we check the value of. Without using a local variable, we would not be able + to test addOne(). + + Let's look at a more complicated example of using local variables. Consider the + code below: + + struct myStruct { + int myInt; + float myFloat; + }; + + void addOne(myStruct* value) { + value->myInt++; + value->myFloat++; + } + + + In this code, myStruct is a structure with two variables, myInt and myFloat. + Using local variables, we can declare input values for each of these variables in + the Test locals table and use them in our tests (see Figure 6.10). + + + Figure 6.10: Advanced local variables + + In the Test locals table, we have specified the variables myInt and myFloat in + the Element column. Each of these variables belongs to the myStruct type and + is part of the myLocal variable. + + We have also specified two initializers for myLocal, Positive and Negative. + Initializers group together assignments for multiple variables, so you can assign + these using a single test operation. You can add as many initializers as you want + by adding a new column to the end of the Test locals table for each. + + +Spreadsheet Test Format User Guide vWF20190404 59 +Setting and checking object members (C++) Writing test sheets: C and C++ + + + In the test table, we assigned the Positive and Negative initializers to tests + using the init operation. To check the value in each variable, we specified both + the local variable and its sub-variable, such as in the example myLocal.myInt. + +6.7 Setting and checking object members (C++) + Checking variable members belonging to class objects is similar to checking static + class members (see Section 6.2: Setting and checking static class variables (C+ + +)), but requires an object of the class to test. We can use the Test Locals table to + declare an object of a class, followed by the init operation in the test to create + the object using the class constructor. The following class has private data, and + a public setter function: + + class SimpleClass { + public: + void setVars(int a, int b); + + private: + int publicVarA; + int privateVarB; + }; + + + We can test setVars() by instantiating an object of SimpleClass and calling + the function, as shown in Figure 6.11. + + + Figure 6.11: Setting and checking C++ object members + + +60 Spreadsheet Test Format User Guide vWF20190404 +Writing test sheets: C and C++ Testing functions in inherited classes (C++) + + +6.8 Testing functions in inherited classes (C++) + You can use RapiTest to test inherited classes in C++. The example code below + contains two classes and two functions. Class Two is inherited from class One + and overloads getType(). setGlobal() is declared in One and inherited by + Two. + + int globalInt = 0; + + class One { + public: + int getType(); + void setGlobal(int value); + }; + + int One::getType() { + return 1; + } + + void One::setGlobal(int value) { + globalInt = value; + } + + class Two:One { + public: + int getType(); + }; + + int Two::getType() { + return 2; + } + + + To test these functions, we must first reference them using their respective classes, + and then declare a local object of the class to call the function. Figure 6.12 and + Figure 6.13 show how to do this. + + +Spreadsheet Test Format User Guide vWF20190404 61 +Testing functions in inherited classes (C++) Writing test sheets: C and C++ + + + Figure 6.12: Testing One::getType() + + + Figure 6.13: Testing Two::getType() + + In each example we: + • Referenced getType() with the name of the class we are testing in the + Scope table (Cell B4) + • Declared and initialized a local object of the same class in the Test locals table + (Cell B10) + • Referenced this object in the Object column of the test table when calling its + functions (Cells D17-20) + + Because getType() is overloaded, we use One.getType() and + Two.getType() to refer to the functions from One and Two. setGlobal() + +62 Spreadsheet Test Format User Guide vWF20190404 +Writing test sheets: C and C++ Testing multi-threaded software + + + is only defined in One, so we refer to it as One.setGlobal() in both tests. We + can call this from the object twoObj because of class inheritance. + +6.9 Testing multi-threaded software + So far, we've considered how to test software that runs on a single thread, and is + thus deterministic in its behavior. RapiTest also supports testing the behavior of + multi-threaded software, which may be non-deterministic as it depends on a task + scheduling system. + + Consider the code below: + + void read() { + while(1){ + curValue = readSensor(); + } + } + + void process() { + while(1){ + processValue(curValue); + } + } + + + read and process are threads in a system, and their invocation is handled + by an overlying context switch routine. The readSensor and processValue + subprograms they call are lower level functions that read and process inputs from + the system, respectively. + + The example below shows a multi-threaded test for these tasks, Figure 6.14. + + +Spreadsheet Test Format User Guide vWF20190404 63 +Testing multi-threaded software Writing test sheets: C and C++ + + + Figure 6.14: Testing multi-threaded software + + A schematic representing the overall test behavior is shown in Figure 6.15. We'll + examine this behavior in detail below. + + +64 Spreadsheet Test Format User Guide vWF20190404 +Writing test sheets: C and C++ Testing multi-threaded software + + + Figure 6.15: Multithreaded test behavior schematic + + Multithreaded tests include some test operations and features not present in sin- + gle-threaded tests. + + The test in Figure 6.14 specifies read and process as units under test (in the + Scope table), and readSensor and processValue as stubs (in the Stubs + table). + + The structure of the Test table is different to that for single-threaded tests, and the + test includes operations unique to multi-threaded testing. While single-threaded + tests include a unique Value column for each test to run, multi-threaded tests must + include a single Main column, and at least two columns that are named begin- + ning with Thread. Test operations included in the Main column define behavior for + the threads run in the test, such as running them, forcing them to wait or sleep, + or halting them. Test operations included in columns corresponding to a specific + Thread, meanwhile, define what to do within that thread. + + Our test includes two threads, Thread 1 and Thread 2, and the test is written + in three sections (demarcated by bold lines in the Test table): + 1. The first section invokes and defines test behavior to apply in Thread 1. + 2. The second section invokes and defines test behavior to apply in Thread 2. + 3. The final section defines behavior for the main test driver. + + +Spreadsheet Test Format User Guide vWF20190404 65 +Working with arrays Writing test sheets: C and C++ + + + Let's interpret the test, starting with the first section. The run operation in row 18 + invokes Thread 1. The duration operation specifies a maximum duration of + 1000 for the thread, instructing RapiTest to halt it non-fatally (without causing a + test failure) this duration after it invokes the thread. By default, durations are in + milliseconds. The test and stub operations for read and readSensor in rows + 20-21 behave in the same way they would in single-threaded tests. + + In the next section, the run operation in row 22 invokes Thread 2. Rows 24-25 + define test and stub operations for process and processValue. As Thread 1 + is invoked earlier in the overall test sequence than Thread 2, we'll definitely invoke + Read before Process (as shown in Figure 6.15). After their invocation, however, + the threads could run in any order as the software is non-deterministic. + + In the final section, the wait operation in row 25 forces RapiTest to wait until + Thread 1 finishes running (in this case, until its duration expires). The kill + operation in row 26 then forces Thread 2 to halt non-fatally, ending the test. + + Note that, throughout, operations that define behavior for when a thread runs are + defined in the Main column, while those defining what a thread does are defined in + the Thread column. While, in this example, we've only assigned a single subpro- + gram to each thread, you can assign any number. + +6.10 Working with arrays + This section demonstrates how to work with arrays in the Spreadsheet Test Format. + + Consider the code below: + + void resetArray(int A[],int size) { + int i=0; + for(i=0;ielt_a = a; + struct_ptr->elt_b = b; + struct_ptr->elt_c = c; + + return struct_ptr; + } + + + Example test: + + +80 Spreadsheet Test Format User Guide vWF20190404 +Test sheet examples Intercepting return values from stubbed functions + + +7.3 Intercepting return values from stubbed functions + For most tasks, you can simply assert input values for stubbed function calls and + either set a stubbed return value or call through to the original stubbed function. + In some cases, you may want to call through to the original function and check + the value that it returns. + + Example code: + + int saved_data; + + void set_data(int data) + { + saved_data = data; + } + + int get_data() + { + return saved_data; + } + + void increment_data() + { + int old_data = get_data(); + //... + + set_data(old_data + 1); + //... + } + + + Example test: + + +Spreadsheet Test Format User Guide vWF20190404 81 +Unnamed C++ function parameters Test sheet examples + + +7.4 Unnamed C++ function parameters + In C++, you can define functions with unnamed parameters. These parameters + are not usable within the body of the function, and are therefore often inaccessible + for testing. You can work around this by specifying the parameter types to differ- + entiate between overloaded functions. + + Example code: + + void fn_with_unnamed_parameters_A(unsigned int) + { + //... + } + + void fn_with_unnamed_parameters_B(unsigned long, char) + { + //... + } + + void fn(int call_count) + { + for (int counter = 0; counter < call_count; call_count++) + { + fn_with_unnamed_parameters_A(UINT_MAX); + } + + fn_with_unnamed_parameters_B(ULONG_MAX, 'a'); + + //... + } + + +82 Spreadsheet Test Format User Guide vWF20190404 +Test sheet examples Unnamed C++ function parameters + + + In the following example test, we check that + fn_with_unnamed_parameters_A is called called_count times from fn, + while fn_with_unnamed_parameters_B is only called once: + + +Spreadsheet Test Format User Guide vWF20190404 83 +This page intentionally left blank +8 Glossary + This chapter contains a list of the important terms, test operations and functions + used in the Spreadsheet Test Format. + • call – a test operation used to call a function. Most often used with the :orig- + inal notation to specify calling the original version of a stubbed function dur- + ing a test. + • called – a test operation used to assert that a stub is called the specified num- + ber of times when the test executes. + • Call or stub – a column in a test table of a test sheet that instructs RapiTest + which unit under test or stub a test operation applies to. + • cast type (expression) – an operator used to cast values in the Value column + of a test table. Casts the given expression to the specified type, for ex- + ample cast long (GlobalInt). + • catch – a test operation used to assert that an exception (or no exception) is + raised when the test executes. + • check – a test operation used to assert that the contents of a Variable match + a specified Value. + • check.eq(tol) – a test operation used to assert that the contents of a Variable + match a specified Value within a certain tolerance, where tol is a tolerance + specified as either a floating point number (e.g. check.eq(0.2)) or per- + centage (e.g. check.eq(5%)). + • check.ge – a test operation used to assert that a numerical Variable is greater + than or equal to a specified Value. + • check.gt – a test operation used to assert that a numerical Variable is greater + than a specified Value. + • check.le – a test operation used to assert that a numerical Variable is less than + or equal to a specified Value. + • check.lt – a test operation used to assert that a numerical Variable is less than + a specified Value. + • Comment – a row of free text beginning with # or [comment] in column B + of any type of worksheet. + • Configuration (option) – a setting in a configuration table that instructs + RapiTest how to handle tests in a test sheet. The available configuration op- + tions are Control flow, Disabled, Remove original stubs and Explicit stubs. + • Configuration (table) – a table in a test sheet that typically includes one or + more configuration options. + + +Spreadsheet Test Format User Guide vWF20190404 85 + Glossary + + + • Context – the location of a function within the parent function structure and + file system. + • Contexts (table) – a table in a test sheet containing information about the con- + texts RapiTest should use to search for functions declared in test definitions. + • Control flow – a Configuration option. When set to Yes, this instructs RapiTest + to expect that all stub operations in a test sheet are written in the order they are + called during each test in the sheet. If they are not, RapiTest throws an error. + • criteria – a test operation used to initialize a group of checks, where all checks + within the group must pass for the criteria to pass. + • Disabled – a Configuration option. When set to Yes, this instructs RapiTest to + ignore a test sheet when preparing a test suite. + • Default – the value RapiTest writes for the return value of a stub when the + stub is called unexpectedly and the original version of the stubbed function + should not be called (for example because the Control flow or Explicit stubs + configuration options have been applied). + • duration – a multithreaded test operation used to set an execution duration + after which to halt a thread non-fatally. + • Element – a column in a Test locals table that lets you specify multiple individ- + ual elements to set up for a test local. + • End tests – A delineation marker in a test table used to end a series of test + sequences. + • Explicit stubs – a Configuration option. When set to Yes, instructs RapiTest + to expect that the number of times each stubbed function is executed during + a test equals the number of times it is observed in a test sequence. If it does + not, RapiTest throws an error. + • fail – a test operation used to specify that a test should fail as soon as the + operation is executed during a test. + • fake – a type of stub. For faked functions, the original function is replaced with + a complex function that imitates the behavior of the replaced function. This + can include complex logic. + • Float – one of the possible Types for a Parameter, used to indicate that it is + a floating point number. + • get.address(obj) – a function used to return the address of an object, where + obj is the object. Can be used in the Variable or Value column of a test sheet. + • get.bytesz(obj) – a function used to return the size of an object in bytes, where + obj is the object. Can be used in the Variable or Value column of a test sheet. + • get.bitsz(obj) – a function used to return the size of an object in bits, where + obj is the object. Can be used in the Variable or Value column of a test sheet. + • get.deref(obj) – a function used to deference an access or pointer to an object + by one level, where obj is the object. Can be used in the Variable or Value + column of a test sheet. + + +86 Spreadsheet Test Format User Guide vWF20190404 +Glossary + + + • get.first(obj) – a function used to return the lowest possible value for an object + given its type, where obj is the object. Can be used in the Variable or Value + column of a test sheet. If this is used with: + • A numeric object, it returns the lowest possible numeric value of its type. + • An array object, it returns the index of the first value in the array. + • An Enum object, it returns the first Enum in the Enum definition. + • get.invalid(obj) – a function used to return an invalid value for an object given + its type, where obj is the object. Can be used in the Variable or Value column + of a test sheet. + • get.last(obj) – a function used to return the highest possible value for an object + given its type, where obj is the object. Can be used in the Variable or Value + column of a test sheet. + • A numeric object, it returns the highest possible numeric value of its type. + • An array object, it returns the index of the last value in the array. + • An Enum object, it returns the last Enum in the Enum definition. + • get.length(array) – a function used to return the length of an array. Can be + used in the Variable or Value column of a test sheet. + • get.object(obj) – a function used to deference an access or pointer to an + object fully to return the object itself, where obj is the object. Can be used in + the Variable or Value column of a test sheet. + • get.pointer(obj) – a function used to return an access or pointer to an object, + where obj is the object. Can be used in the Variable or Value column of a + test sheet. + • init – a test operation used to initialize values for a test local. + • kill – a multithreaded test operation used to halt a thread non-fatally. + • Main – A column in a multithreaded test table that includes a test sequence + for the main thread. + • mock – a type of stub. For mocked functions, the original function is called, + but its inputs and outputs are checked. + • Natural – one of the possible Types for a Parameter, used to indicate that it + is a natural number. + • New test – A delineation marker in a test table used to start a new test se- + quence. + • Object – A column in a test table that, when used with a properly constructs + test local, can be used to instantiate a local object of a C++ class. + • Parameter – the name of a valid parameter in source code, written to take + into account the case sensitivity of the source language. All parameters for a + function along with their types must be specified when that function is over- + loaded in its context. + + +Spreadsheet Test Format User Guide vWF20190404 87 + Glossary + + + • pass – a test operation used to specify that a test should pass as soon as the + operation is executed during a test. + • priority – a multithreaded test operation used to set a priority for a thread. + • raw: – a notation used to specify that the following code is raw code and + should be inserted directly into the test harness. + • raw(type): – a notation used to specify that the following code is raw code + and should be inserted directly into the test harness. This also specifies the + type of the expression, which is useful for reporting purposes. This cannot + be determined automatically by RapiTest. + • rts: – a notation used to specify that the following code is an RTS script and + should be inserted directly into the test harness. + • run – a test operation used to invoke a function. This can be used to invoke + functions with no parameters. + • Remove original stubs – a Configuration option. When set to Yes, this in- + structs RapiTest to remove original versions of stubbed functions when it con- + verts tests into a test harness. + • Scope (table) – a table in a test sheet declaring the units under test in that + sheet. + • set – a test operation used to assign a Value to its corresponding Variable. + • Shorthand – a column in a test sheet that can be used to define a shorthand + notation. + • shorthand notation – text defined in a Shorthand column that can be used + to refer to a function elsewhere in a test sheet, by typing the value defined in + the Shorthand column, immediately preceded by a :. RapiTest also includes + inbuilt shorthand notations. + • spy – a type of stub. For spied functions, the original function is called, but its + inputs and outputs are checked. + • stubbed – a test operation used to specify that a function declared in the Stubs + table is stubbed during the test. This can be used to stub a function during a + test without applying specific behavior to it, essentially creating an empty stub. + • stub (general) – a function that has its behavior modified by RapiTest. RapiTest + uses the term stub to refer to stubs, mocks, fakes and spies. + • Stubs (table) – a table in a test sheet containing information about the func- + tions RapiTest will stub during tests. + • Suite sheet – a type of worksheet that contains general information about a + test project and suite. For more information, see Chapter 4: Writing a suite + sheet. + • test definition – a series of values in a test table that define a test. This in- + cludes a test sequence as well as any user-entered data such as test name + and reference to requirements. + + +88 Spreadsheet Test Format User Guide vWF20190404 +Glossary + + + • test local – a variable or data structure that is local to a test and can be ac- + cessed from any scope within a test. + • Test locals (table) – a table in a test sheet used to specify one or more test + locals. + • test operation – a stage procedure that is part of both a test sequence and a + test definition. Basic operations include called, catch, check, run and set. + • test sequence – a series of test operations that act as part of a test definition. + • Test sheet – a type of worksheet that contains information describing tests + written in the Spreadsheet Test Format. + • Test table – a table in a test sheet containing one or more test definitions. + • Thread – A column in a multithreaded test table that includes a test + sequence for a thread. + • throw – a test operation used to cause an exception to be thrown when it + executes. + • timeout – a multithreaded test operation used to set a timeout for a thread + which, if hit, will halt and fail the test. + • Type – the type of a parameter in terms of typed programming languages. + When a function is overloaded in its context, all parameters and their types + must be specified for it. + • unit under test – any function that has been specified in a Scope table. + • User sheet – a type of worksheet that is used to store information that is ig- + nored by RapiTest. + • Value – a column in a test table providing the data to be used for a test op- + eration. + • Variable – the name of a column in a test sheet, used to record the variables + each test operation operates on. + • wait – a multithreaded test operation used to cause a test to wait until a thread + finishes executing before applying the next operation in the test sequence. + • : – specifies that no test operation should be carried out for the current field + in a test table. + • :global – specifies that a test operation acts on a variable in the global scope. + • :local – specifies that a test operation acts on an element in a test local. + • :original – specifies that the original version of a stubbed function should be + called, rather than a stubbed version of it. + • :stub – specifies that a test operation acts on the most recent stub encountered + in a test sequence. + • :uut – specifies that a test operation acts on the most recent unit under test + encountered in a test sequence. + + +Spreadsheet Test Format User Guide vWF20190404 89 + Glossary + + + • @N – a notation used in the Parameter field of a function definition to specify + the Nth parameter in a function’s declaration. This is most often used to un- + ambiguously refer to functions with unnamed parameters. + + +90 Spreadsheet Test Format User Guide vWF20190404 + diff --git a/docs-extracted/src/scov/RVS/doc/Reference/Integration_Library_Implementation.md b/docs-extracted/src/scov/RVS/doc/Reference/Integration_Library_Implementation.md new file mode 100644 index 000000000..cb4525a56 --- /dev/null +++ b/docs-extracted/src/scov/RVS/doc/Reference/Integration_Library_Implementation.md @@ -0,0 +1,1036 @@ +--- +title: "Integration Library Implementation" +source: "./src/scov/RVS/doc/Reference/Integration_Library_Implementation.pdf" +category: "src/scov/RVS/doc/Reference" +pages: 30 +extracted: "2026-07-06T23:15:57.425780" +--- + +# Integration Library Implementation + +> Extracted from `./src/scov/RVS/doc/Reference/Integration_Library_Implementation.pdf` (30 pages). +> Figures, diagrams, and tables may not render accurately in plain text. + + Integration Library +Implementation Guide + Version WF20190404 +Disclaimer +The information, text, and graphics contained within this document are +provided for information purposes only by Rapita Systems Ltd. Rapita +Systems Ltd. does not warrant the accuracy or completeness of the +information, text, and other items contained in this document. + + +Copyright and Trademarks +All rights reserved. Information and images contained within this doc- +ument are copyright and the property of Rapita Systems Ltd. All trade- +marks are hereby acknowledged to be the properties of their respective +owners. + + +Acknowledgments +Rapita Systems' tools are built using AdaCore's GNAT Pro compiler. + + +Rapita Systems Ltd. +Registered in the UK, number 5011090. +Registered address: +Atlas House +Link Business Park +Osbaldwick Link Road +York +YO10 3JB +UK +Phone: +44 (0) 1904 413 945 +http://www.rapitasystems.com/ +This document copyright © 2017-2019, Rapita Systems Ltd. + +Document build 118520 + +ID: DOC/17082 + Table of Contents + + 1. About this guide ............................................................... 5 + 1.1. Who should read this guide? ................................................... 5 + + 1.2. Structure of this guide ........................................................... 5 + + 1.3. Notation ............................................................................ 6 + + 1.4. RVS documentation map ........................................................ 6 + + 1.5. Support ............................................................................. 8 + + + 2. What are RVS integration libraries? ................................... 9 + 2.1. Contents of RVS integration libraries ......................................... 10 + + 2.2. Analysis types and data collection ........................................... 11 + + + 3. Integrations using maps .................................................. 13 + 3.1. Map location and size .......................................................... 13 + + 3.2. Map header structure ........................................................... 14 + + 3.3. Section lists ...................................................................... 15 + + 3.4. Static data ........................................................................ 15 + + 3.5. Dynamic data .................................................................... 16 + + 3.6. Maps and timing analysis ...................................................... 17 + + 3.7. Integrating for data collection via maps ..................................... 17 + + + 4. Integrations using direct or buffered write ....................... 19 + 4.1. Data output mechanisms ...................................................... 19 + + 4.2. Integrating for data collection via direct write ............................... 19 + + 4.3. Integrating for data collection via buffered write ............................ 21 + + + 5. Unit test integrations ....................................................... 25 + +RVS Integration Library Implementation Guide 3 + Table of Contents + + + 6. Control utilities ................................................................ 27 + 6.1. RVS_CRC32 ...................................................................... 27 + + 6.2. RVS_Calibration_Sleep ......................................................... 27 + + + A. List of integration library routines ................................... 29 + A.1. RVS_I .............................................................................. 29 + + A.2. RVS_C ............................................................................ 29 + + A.3. RVS_E ............................................................................ 29 + + A.4. RVS_T ............................................................................. 29 + + A.5. RVS_F ............................................................................. 29 + + A.6. RVS_V ............................................................................. 29 + + A.7. RVS_D ............................................................................ 29 + + A.8. RVS_CM .......................................................................... 29 + + A.9. RVS_DM .......................................................................... 30 + + A.10. RVS_DML ....................................................................... 30 + + +4 RVS Integration Library Implementation Guide +1 About this guide + The RVS Integration Library Implementation Guide describes the different types of + RVS integration libraries, requirements for them, and how to implement them. It + specifies constraints for how each integration interacts with standard parts of the + integration library and the instrumentation code that is injected into the software + under test (SUT). + +1.1 Who should read this guide? + This guide is designed for Rapita Field Application Engineers, and for customer + personnel who are thoroughly familiar with the RVS toolset. + + This guide assumes that you have already created an RVS project suitable for + working with your code base and have a deployed integration library template. For + more information, see Section 5.2 in the RVS Integration Guide. + +1.2 Structure of this guide + This document includes the following chapters: + + Chapter 1: About this guide + Describes the purpose and layout of this guide and the notation used throughout it. + + Chapter 2: What are RVS integration libraries? + Describes what RVS integration libraries are and their contents, including defini- + tions for the various types of RVS integration and data collection strategy. + + Chapter 3: Integrations using maps + Describes requirements for RVS map-based integration libraries for coverage + analysis. + + Chapter 4: Integrations using direct or buffered write + Describes requirements for RVS integration libraries that use a direct write or + buffered write data collection strategy, for coverage, schedule and timing integra- + tions. + + Chapter 5: Unit test integrations + Describes requirements for RVS integration libraries for managed integrations, + providing unit test facilities. + + Chapter 6: Control utilities + Describes control utilities that can be used in RVS integration libraries to provide + additional functionality. + + +RVS Integration Library Implementation Guide 5 +Notation About this guide + + + Appendix A: List of integration library routines + Provides a reference for some RVS API routines. + +1.3 Notation + This document uses the following notation: + • References to other documents and to other chapters or sections in this doc- + ument are written in italics, for example Chapter 1: About this guide. When + reading an electronic copy of this document, you can click on a reference to + navigate to the location of the referenced element. + • Names of RVS applications are formatted in bold italics, for example RVS + Project Manager. + • References to areas or elements in user interfaces are formatted in italics, for + example the Report Navigator. + • Menus, menu choices and button labels are formatted in bold, for example + File » Print or OK. Where buttons have icons, these are shown before their + Label in in-line text, for example Save. + • Names of RVS tools are formatted in bold, for example rvsdriver. + • References to HTML links appear as underlined text, for example + www.rapitasystems.com. + • Folder and file names are formatted in a monospaced font. + • Command-line tools and their commands, annotations and examples are for- + matted in a monospaced font. These are either written in-line with text + or as separate text blocks. When written in-line with text, they are formatted + like the following: rvsdriver, default_instrument, rvs_instr.h. + When written as a separate text block, they are formatted like the examples + below: + rvsdriver --project rvs.rvsprj --all + + #pragma RVS instrument( "function_name", "FALSE" ) + + • When referencing Ada code, the term functions refers to both functions and + procedures. + +1.4 RVS documentation map + This document is part of the Rapita Verification Suite (RVS) document set, which + contains the following documents: + + RVS Installation and Licensing Guide + Describes how to install RVS tools, and licensing options for them. + + RVS Integration Guide + Describes how to integrate RVS tools into build and target environments. + + +6 RVS Integration Library Implementation Guide +About this guide RVS documentation map + + + RVS User Guide + Describes how to set up and run RVS projects, analyze data and export verification + results. + + RapiTest User Guide + Describes how to use RapiTest to manage test projects. + + Spreadsheet Test Format User Guide + Describes how to write tests for RapiTest in the Spreadsheet Test Format. + + RapiCover User Guide + Describes how to use RapiCover to measure code coverage and address cover- + age holes. + + RapiTime User Guide + Describes how to use RapiTime to measure timing metrics including worst-case + execution time, and how to use these metrics to identify the best optimization + candidates. + + RapiTask User Guide + Describes how to use RapiTask to measure system level task timing information, + visualize traces and gain insight into runtime behavior. + + RTBx 2xxx User Guide + Describes how to use the RTBx data logger. + + RVS Integration Library Implementation Guide + Describes how to implement RVS integration libraries. This document is for use by + readers with a thorough understanding of the implementation of RVS. + + RVS Files Reference Guide + Describes RVS-specific files including input, intermediate and output files. + + RVS Filters Guide + Describes RVS filters, which are used to convert raw trace data into a format that + RVS can analyze, and how to write them. + + RVS Command Line Tools Reference Guide + Describes the command-line tools used by RVS, including a list of available com- + mand options. + + RVS Annotations Reference Guide + Describes the annotations you can use to control instrumentation and analysis + with RVS. + + RVS Troubleshooting Guide + Describes the error and warning messages you may encounter when using RVS + tools, and how to address them. + + +RVS Integration Library Implementation Guide 7 +Support About this guide + + + RVS Migration Guide + Describes how to migrate between using different versions of RVS. + +1.5 Support + For support issues, please contact Rapita Systems Ltd. by any of the following + means: + + Email + support@rapitasystems.com + + Telephone + +44 (0) 1904 413 945 + + Website + www.rapitasystems.com + + To register for support, visit www.rapitasystems.com/register. More than one user + can register per license. + + +8 RVS Integration Library Implementation Guide + What are RVS integration +2 libraries? + RVS integration libraries specify the functionality needed to use RVS to instrument + source code in order to collect verification data. Library implementation controls + the data collection mechanism for the specific target hardware used in an integra- + tion. + + RVS deploys a standard integration library template when you create a new project + in the RVS Project Manager. This comprises a standard collection of routines (the + RVS API) that interact with the instrumentation added to the software under test + (SUT) to record required data. + + Standard integration library templates are usable directly in some scenarios. In + others, however, some RVS API routines may need to be customized to reflect the + particular constraints of your target. This customization can be done in-house, or + with the help of a Rapita Field Applications Engineer. Figure 2.1 shows the rela- + tionship between the RVS tools, RVS instrumentation and the integration library. + + +RVS Integration Library Implementation Guide 9 +Contents of RVS integration libraries What are RVS integration libraries? + + + Figure 2.1: RVS Integration Library Context + + Note + + If you are qualifying RVS, you will need to qualify your integration. As part of + that process, you should review your implementation of the RVS API against + the specifications given in this document. + + +2.1 Contents of RVS integration libraries + RVS integration libraries include the following: + • Base ipoint definitions – the library defines low-level routines that implement + the basic requirements of an RVS instrumentation point (which allows mea- + surement of progress through the SUT). These routines provide functionality + for ipoint calls injected into source code by RVS instrumenter tools. + • MC/DC ipoint definitions – these implement coverage recording for MC/DC + analysis (RapiCover). These routines provide functionality for ipoint calls in + MC/DC expressions injected into source code by RVS instrumenter tools. + • Test start/end routines – these provide functions to initialize tests, output re- + sults and perform other book-keeping functions. + + +10 RVS Integration Library Implementation Guide +What are RVS integration libraries? Analysis types and data collection + + + • Control utilities – these additional routines are used to verify data integrity + and support tool qualification. + + Warning + + Except from RVS_Output(), routines that interact with on-target maps + and traces should not be amended. + + + Note + + Where standard library routines must be changed to work with the target + architecture, there are a number of constraints and behavior requirements + that these routines must conform to. Where appropriate, these are de- + scribed in this document. + + +2.2 Analysis types and data collection + An integration combines the SUT with parts of the RVS toolset so that the user can + analyze the behavior of the SUT. Each integration may support one or more of the + following types of analysis: + • During timing analysis and schedule analysis, RVS obtains data about the + execution time of the SUT. + • During coverage analysis, RVS obtains data about the coverage obtained by + tests exercising the SUT. + • During unit test analysis, RVS specifies and injects unit test code into the SUT, + and obtains results from unit tests. + + RVS integration libraries must be capable of collecting verification data during test- + ing of the SUT. The data collection methods available are as follows: + • Direct write – the integration writes data to an output device as soon as the + data is available, streaming the data to some external method of collection + such as an RTBx data logger or a logic analyzer. + • Buffered write – the integration writes streamed data (as for direct write), but + the data is buffered in some way on the target. The integration must arrange + for the buffer to be transferred from the target. + • Data map write – the integration records data to a map data structure on the + target. The integration must arrange for the map to be written to an external + collection method when appropriate. + + The analysis type constrains the data collection methods that can be used in an + integration, and determines which functions in the RVS API may need to be cus- + tomized to implement the integration, see Table 2.1. + + +RVS Integration Library Implementation Guide 11 +Analysis types and data collection What are RVS integration libraries? + + + Table 2.1 Integration strategies and RVS + API functions you may need to customize + Analyses Data collection method + Direct write Buffered write Data map write + Unit test Not available Not available RVS_Output() + + Timing RVS_Init() RVS_Init() Not available + RVS_Ipoint() RVS_Ipoint() + RVS_Output() + + Coverage RVS_Init() RVS_Init() RVS_Output() + RVS_Ipoint()/ RVS_Ipoint()/ + RVS_I() RVS_I() + RVS_Output() + + + Important + + If unit test analysis is performed during an integration, unit test data must be + collected using a data map write (map). If you are also performing coverage + analysis, you can store coverage data in the map, or stream it with direct + or buffered writes and process it separately to the map. If you are also per- + forming timing or schedule analysis, you must output that data with direct or + buffered writes and process it separately to the map. + + + Important + + If you need to add new integration library routines, we recommend that you + define them within files in the template integration library. You should avoid + writing custom routines beginning with the word RVS to ensure they do not + conflict with standard RVS routines. + + +12 RVS Integration Library Implementation Guide +3 Integrations using maps + Map integrations record data to a data structure in on-board memory. The map + structure is a block of memory that comprises the following sections: + • A map header that contains information concerning the integration and the + overall status of the map. + • A section list that describes the kind(s) of data stored in the map. + • A static data area that contains information derived from running the tests. + • A dynamic data area that the integration library can use for extra storage. + + Each of these areas is defined as a data structure in the format of the primary + language of the project. Integrations only need to interact with a small number of + elements in these structures as described below. + + During a test run, an RVS map is initialized and data is added to the map. The + data in the map may be output at the end of the process, or at several specific + times during the test run. + + RVS maps contain both static and dynamic elements: + • Static elements of maps comprise data that, once set, should not be changed + between different test runs. + • Dynamic elements of maps comprise data that belongs to a particular test + iteration. Note that these elements may appear in any part of the map, not just + the dynamic data area. + + Note + + In the following sections, all data sizes and offsets are measured as 8-bit + bytes unless otherwise specified. + + +3.1 Map location and size + Data in RVS maps is stored in memory allocated within the RVS package (for Ada) + or local to the RVS map file (for C/C++). We provide pointers to access the mem- + ory either as an 8-bit element or 32-bit element. Maps can be stored in either of + the following arrays: + • rvs_all_data8 (C/C++), all_data8 (Ada) – access the map byte-by- + byte. + • rvs_all_data32 (C/C++), all_data32 (Ada) – access the map word- + by-word. + + +RVS Integration Library Implementation Guide 13 +Map header structure Integrations using maps + + + The total available storage space in an RVS map is stored in + rvs_header->total_max_size8. The current used storage space is stored + in rvs_header->total_used_size8. + + As you allocate more memory (e.g. for MC/DC vectors or managed + test results), rvs_header->total_used_size8 grows. When it reaches + rvs_header->total_max_size8, further allocations are unsuccessful and + return a pointer to the beginning of the map data area. + + The corresponding fields for Ada map implementation are + rvs_header.total_max_size8 and + rvs_header.total_used_size8, respectively. + +3.2 Map header structure + RVS map headers contain information concerning the integration and the overall + status of the map. + + The RVS map header structure is defined in Table 3.1. The entries highlighted in + bold are important when implementing map integration libraries. + + Table 3.1 Map header structure definition + + Element Bits Offset Description + (bytes) + endianness 32 0 The endianness of the target hardware + valid 32 4 Flags recording the validity of the data + in the table + crc32 32 8 An optional checksum of the table, cal- + culated on demand + magic 32 12 Magic number + version 32 16 Internal version number for this struc- + ture + rvs_header_size8 32 20 The size of this structure + dynamic_overflow 32 24 A flag set if the dynamic data storage + has overflowed + dynamic_offset8 32 28 The offset of the dynamic data area for + the start of the header + dynamic_used_size8 32 32 The amount of dynamic storage used + dynamic_max_size8 32 36 The maximum dynamic storage avail- + able + total_used_size8 32 40 The total amount of storage used + total_max_size8 32 44 The size of the map as a whole + mem_dump_size8 32 48 0, or value passed to --mem-dump- + size if used + + +14 RVS Integration Library Implementation Guide +Integrations using maps Section lists + + + Element Bits Offset Description + (bytes) + segment_size8 32 52 0, or value passed to --segment if used + – note that this feature is not currently + supported + segment_count 32 56 If --segment is used, the number of + segments required to hold all the map + data + rvd_pathname 32 60 A reference to dynamic data containing + the name of the RVD file + rvd_last_modif_date 32 64 The creation time (as epoch) of the + MD5 (see below) of the RVD + rvd_md5 128 68 An MD5 of the RVD used to create the + map + map_creation_date 32 84 The creation time (as epoch) of the + map + username 32 88 A reference to dynamic data contain- + ing the name of the usr who created the + map + build_id 32 92 A reference to dynamic data containing + the build ID (if set) + nb_sections 32 96 The number of distinct sections in the + section list + + +3.3 Section lists + RVS map section lists describe the kind(s) of data stored in an RVS map. + + Section lists contain between 1 and 5 section entries. The section entry structure + is defined in Table 3.2. + + Table 3.2 Section entry structure definition + + Element Bits Offset Description + (bytes) + section_type 32 0 The type of the section: coverage data + or unit test data + section_offset8 32 4 The offset of the section + section_header_size 32 8 + section_data_size 32 12 The size of the data for this section + + +3.4 Static data + Static data areas in RVS maps contain information derived from running tests. + + +RVS Integration Library Implementation Guide 15 +Dynamic data Integrations using maps + + + Static data areas contain between 1 and 5 sections as defined in the section head- + ers. A section can be a coverage map or an assertion map. + + A coverage map consists of a header structure as defined in Table 3.3, plus one + 8-bit storage element for each ipoint inserted into the code. + + Table 3.3 Coverage map header structure definition + + Element Bits Offset Description + (bytes) + test_id 64 0 The ID of the test + test_name 32 8 A reference to dynamic data containing + the name of the test (if set) + bits_per_ID 32 12 The number of bits per ipoint + test_source 32 16 + + An assertion map consists of a header structure as defined in Table 3.4, plus one + 32-bit storage element for each assertion in the unit test. + + Table 3.4 Assertion map header structure definition + + Element Bits Offset Description + (bytes) + bits_per_assertion 32 0 The number of bits per assertion + test_id 032 4 The ID of the test + padding0 32 8 Padding bits to make the header the + same size as a coverage map header. + padding1 32 12 Padding bits to make the header the + same size as a coverage map header. + padding2 32 16 Padding bits to make the header the + same size as a coverage map header. + + +3.5 Dynamic data + Dynamic data areas in RVS maps provide extra storage for an RVS integration + library. + + Dynamic data is controlled by standard parts of the integration library (and/or in- + jected code). Dynamic data elements include: + • Stored strings pointed to by a header element + • Nodes in an MC/DC dynamic data structure + • Assertion header records + • Assertion failure records + • Data associated with assertion failures + + +16 RVS Integration Library Implementation Guide +Integrations using maps Maps and timing analysis + + + Note + + There is no need to modify the API routines that control the data structures + in dynamic areas of an RVS map. + + +3.6 Maps and timing analysis + The only circumstance in which a map may be used as part of a timing analysis + is if you are performing unit testing at the same time as timing tests. In this case, + your integration must conform to the following requirements: + • RVS_Init() must set up any initialization necessary for writing timing data + and must also retain the map initialization call from the standard map integra- + tion. + • RVS_Ipoint() must conform to the requirements for the method being + used to collect timing data, see Section 4.2: Integrating for data collection via + direct write and Section 4.3: Integrating for data collection via buffered write. + • RVS_Output() must include any teardown necessary for the timing writes + and must conform to the requirements of the map integration described in + Section : Requirements. + • You must arrange for the host side of your integration to separate the map + data from the trace data and process each individually. If the two parts are not + correctly separated, you will encounter parsing errors when trying to process + the data. We usually recommend that you place map data at the end of the + download, after any trace data could possibly be produced, and use map + header structures to separate them from the trace data. + +3.7 Integrating for data collection via maps + The standard integration template for map integrations contains implementations + of the standard functions that interact with maps. The only function that may re- + quire changing is RVS_Output(). + +3.7.1 RVS_Output + Synopsis + + This function is inserted into the SUT as part of the integration. When the function + is executed, it outputs map data in an integration-specific manner. + + API + + void RVS_Output(void); + + + Integration notes + + You must decide, as part of the integration, the actions to add to RVS_Output + so that the data in the map can be extracted. + + +RVS Integration Library Implementation Guide 17 +Integrating for data collection via maps Integrations using maps + + + We recommend that you first use the RVS_CRC32 given in the RVS integration + library templates to check the integrity of your data, and write the crc32 value + to the map header; see Table 3.1. For more information on using this routine, see + Section 6.1: RVS_CRC32. + + Some typical methods of data extraction are described below: + • Write to file – the implementation writes the map contents to a file. The stan- + dard name used for this file is rvs_map.bin. + • Debugger breakpoint – the implementation includes a breakpoint for use by + an external debugging tool that can read data from the map. While this could + be in any function, we recommend placing this breakpoint in RVS_Output() + for maintainability. You may need to declare a dummy volatile static variable + and write to it from RVS_Output() to prevent your compiler from optimizing + the RVS_Output() routine out of the executable. + • Write to external device – the implementation writes data to a hardware de- + vice that monitors the data and stores it. This could be via: + • A general I/O port + • A monitored variable + • A monitored address block + + Requirements + + The integration must ensure that all dynamic data in the map is cleared after + successfully exporting the data. The standard call to reset the map structure is + rvs_map_reset(). + + +18 RVS Integration Library Implementation Guide + Integrations using direct +4 or buffered write + Integrations using a direct or buffered write use the trace data format. A trace is a + list of pairs of numbers – the first is a number up to 32-bits in size, and the second + is up to 64-bits in size. + + The contents of each number depends on the type of analysis being performed: + • For timing analysis, the first number is an ipoint ID, and the second is a time- + stamp. + • For coverage analysis, the first number is either an ipoint ID or coverage data, + and the second is not used. If you are not automatically timestamping the data, + use a value of 1 instead of a timestamp. + +4.1 Data output mechanisms + You must select a data output mechanism when implementing a data collection + strategy using either direct or buffered write: + • In a direct write, information is sent to its ultimate location as soon as it gen- + erated. + • In a buffered write, information is stored temporarily in a local buffer before + it is sent to its ultimate location. + +4.2 Integrating for data collection via direct write + The standard integration template for integrations using direct write contains im- + plementations of the standard routines that stream data. + + The routines that you may need to change to implement a direct write integration + depend on the analysis performed: + • For timing analysis, you may need to change the implementation of + RVS_Init() and RVS_Ipoint(). + • For coverage analysis, you may need to change the implementation of + RVS_Init(). + +4.2.1 RVS_Init + Synopsis + + This function is called before testing starts. + + API + + +RVS Integration Library Implementation Guide 19 +Integrating for data collection via direct write Integrations using direct or buffered write + + void RVS_Init(void); + + + Integration notes + + This function contains any initialization code needed to set up the facility to write + data. + +4.2.2 RVS_Ipoint + Synopsis + + This function is the base implementation used by ipoints that the instrumenters add + to your code. The function must write ipoint numbers to the appropriate place. If + you do not have an external timestamping facility, this function must also calculate + and record a timestamp. + + API + + void RVS_Ipoint(unsigned int); + + + Integration notes + + The implementation writes data to a hardware device that monitors the data and + stores it. This could be via: + • A general I/O port + • A monitored variable + • A monitored address block + + For timing analysis, the integration as a whole must obtain a timestamp for the + ipoint. This may be obtained from an internal or external source. If an internal time- + stamp is used, the function must get the timestamp and output it at the same time + as the ipoint number. Alternatively, the integration may use an external source to + timestamp ipoints, typically an RTBx or a logic analyzer. + + For coverage analysis, the ipoint must implement a LiveMap strategy to collect + data, wherein: + • The RVS_Ipoint function writes data out as normal. + • The MC/DC routines RVS_DM and RVS_DML have the same implementation, + calling RVS_I to write the ipoint ID and RVS_Ipoint to write out MC/DC + key data. + • The RVS_I function outputs its parameter with the top bit set to distinguish + ordinary ID values from MC/DC values. This lets the LiveMap reader perform + basic demultiplexing while avoiding the possibility of corrupt values. + + If the integration uses an I/O port or monitored variable, RVS_Ipoint must write + the ipoint number (and timestamp if any) to the port or variable. The ipoint and + + +20 RVS Integration Library Implementation Guide +Integrations using direct or buffered write Integrating for data collection via buffered write + + + timestamp are typically encoded together so this operation can be performed in + a single write operation. + + If the integration uses a monitored address block, RVS_Ipoint must calculate + a suitable offset into the address block and write a dummy value at that offset, + typically using the most efficient means that the hardware instruction set allows. + The calculated offset encodes the ipoint number and the timestamp if necessary. + +4.3 Integrating for data collection via buffered write + When using buffered write, the following strategies are available: + • On-demand data output – for this strategy, the integration detects when the + buffer is full and calls RVS_Output() to empty the buffer so that execution + can proceed. Typically, the implementation of RVS_Ipoint() would check + the status of the buffer and call RVS_Output as necessary. + • Scheduled data output – for this strategy, a call to RVS_Output() is placed + somewhere in the application, ideally outside of the analysis root. This may + be at the end of the main application loop or in a background or idle thread, + or in a different thread or process, such that the output routine is called often + enough that the buffer never fills. The output routine sends the data out from + the buffer and then empties it. + + The standard integration template for integrations using buffered write contains + implementations of the standard routines that stream data. + + The routines that you may need to change to implement a buffered write integration + depend on the analysis performed: + • For timing analysis, you may need to change the implementation of the + RVS_Init() and RVS_Ipoint(). + • For coverage analysis, you may need to change the implementation of the + RVS_Init() routine. + + Important + + The integration must supply suitable storage to contain the buffered data, + typically in the form of a linear buffer of sufficient size. + + +4.3.1 RVS_Init + Synopsis + + This function is called before testing starts. + + API + + void RVS_Init(void); + + +RVS Integration Library Implementation Guide 21 +Integrating for data collection via buffered write Integrations using direct or buffered write + + + Integration notes + + This function contains any initialization code needed to set up the facility to write + data. For instance, it may allocate the memory required for the write buffer. + +4.3.2 RVS_Ipoint + Synopsis + + This function is the base implementation used by all ipoints that the instrumenters + add to your code. The function gets an internal timestamp and writes the ipoint + number and timestamp to the buffer. + + API + + void RVS_Ipoint(unsigned int); + + + Integration notes + + You must use an internal timestamp. Your implementation of RVS_Ipoint() + must acquire the current timestamp. + + You must ensure that, when called, RVS_Ipoint() writes the ipoint number + (and timestamp if necessary) to the next available location(s) in the buffer. + + Requirements + + The integration must ensure that no data is lost as a result of buffer overrun. + + If the integration is using scheduled data output, it must ensure that the parts + of RVS_Output() and RVS_Ipoint() that read and write buffered data are + protected by critical sections to avoid concurrency problems. + +4.3.3 RVS_Output + Synopsis + + This function extracts buffered data. This may be done on-demand, where the + buffer is emptied when it becomes full; or in a scheduled way, where a a process + external to the SUT empties the buffer at regular intervals. + + We recommend that you use the RVS_CRC32 routine generated in RVS integra- + tion library templates to check the integrity of your data when you extract it. For + more information on using this routine, see Section 6.1: RVS_CRC32. + + API + + void RVS_Output(void); + + +22 RVS Integration Library Implementation Guide +Integrations using direct or buffered write Integrating for data collection via buffered write + + + Requirements + + The integration must ensure no data is lost as a result of buffer overrun. + + The integration must ensure that the data in the buffer is cleared after successfully + extracting the data. + + If the integration is using scheduled data output, it must ensure that the parts + of RVS_Output() and RVS_Ipoint() that read and write buffered data are + protected by critical sections to avoid concurrency problems. + + +RVS Integration Library Implementation Guide 23 +This page intentionally left blank +5 Unit test integrations + A unit test integration must use a map, so the notes and constraints on map in- + tegration described in Section 3.7: Integrating for data collection via maps apply, + even if the integration is also using direct or buffered write for coverage or timing + analysis data collection. + + You should not change any of the code in the standard template that supports + unit test analysis. + + +RVS Integration Library Implementation Guide 25 +This page intentionally left blank +6 Control utilities + RVS control utilities let you perform additional functionality in your integrations. + These utilities are optional. + +6.1 RVS_CRC32 + RVS_CRC32 is a standard RVS routine used to check that data collected on + buffers during RVS integrations is not corrupted during post-processing. + + We recommend that you implement the RVS_Output routine to call RVS_CRC32 + before it extracts data from the target. + + If you do, your data is validated in the following way: + • RVS_Output generates a checksum from the data before it extracts it. + • RVS calls a copy of RVS_CRC32 to generate a checksum when it performs + post-processing of the data. + • If the two checksums match, post-processing continues. If they don't, RVS + reports an error and stops post-processing the data. + + Important + + You should not change the implementation of RVS_CRC32 such that it re- + turns a different checksum. If you do, your integration will fail as RVS uses a + copy of the RVS_CRC32 function when it post-processes data. + + +6.2 RVS_Calibration_Sleep + When qualifying an integration library for RapiTime, the confirmation test must be + able to delay for a fixed length of time without using the same mechanism that + RapiTime uses for timestamps. For example, if the timestamps come from a CPU + counter, you cannot check the calibration of the integration by counting on the + same CPU counter. + + The generated on-site confirmation test calls RVS_Calibration_Sleep to de- + lay for a fixed length of time. You only need to implement this for RapiTime inte- + grations that are qualified through a Rapita Systems QTIK. + +6.2.1 Requirements + RVS_Calibration_Sleep delays for the given number of nanoseconds, to + the resolution possible on the target hardware. + + +RVS Integration Library Implementation Guide 27 +RVS_Calibration_Sleep Control utilities + + + RVS_Calibration_Sleep uses a delay mechanism that is independent from + the timestamping that is added to instrumentation points. If no such mechanism + is available, we recommend using a busy-wait loop and an external monitoring + device to calibrate the loop. + + +28 RVS Integration Library Implementation Guide + List of integration library +A routines +A.1 RVS_I + RVS_C(unsigned int ipoint_id, ) + + +A.2 RVS_C + RVS_C(unsigned int ipoint_id, ) + + +A.3 RVS_E + RVS_E(unsigned int ipoint_id, ) + + +A.4 RVS_T + unsigned int RVS_E(unsigned int ipoint_id); + + +A.5 RVS_F + unsigned int RVS_E(unsigned int ipoint_id); + + +A.6 RVS_V + unsigned int RVS_V(unsigned int ipoint_id, unsigned int bool) + + +A.7 RVS_D + unsigned int RVS_D(unsigned int ipoint_id, unsigned int bool) + + +A.8 RVS_CM + unsigned int RVS_CM(unsigned int* key, unsigned int index, unsigned int + bool); + + +RVS Integration Library Implementation Guide 29 +RVS_DM List of integration library routines + + +A.9 RVS_DM + unsigned int RVS_DM(unsigned int ipoint_id, unsigned int* key, unsigned + int bool); + + +A.10 RVS_DML + unsigned int RVS_DML(unsigned int ipoint_id, unsigned int* key, unsigned + int bool); + + +30 RVS Integration Library Implementation Guide + diff --git a/docs-extracted/src/scov/RVS/doc/Reference/RVS_Annotations.md b/docs-extracted/src/scov/RVS/doc/Reference/RVS_Annotations.md new file mode 100644 index 000000000..da6381d40 --- /dev/null +++ b/docs-extracted/src/scov/RVS/doc/Reference/RVS_Annotations.md @@ -0,0 +1,4670 @@ +--- +title: "Rvs Annotations" +source: "./src/scov/RVS/doc/Reference/RVS_Annotations.pdf" +category: "src/scov/RVS/doc/Reference" +pages: 114 +extracted: "2026-07-06T23:15:57.531546" +--- + +# Rvs Annotations + +> Extracted from `./src/scov/RVS/doc/Reference/RVS_Annotations.pdf` (114 pages). +> Figures, diagrams, and tables may not render accurately in plain text. + + Annotations +Reference Guide + Version WF20190404 +Disclaimer +The information, text, and graphics contained within this document are +provided for information purposes only by Rapita Systems Ltd. Rapita +Systems Ltd. does not warrant the accuracy or completeness of the +information, text, and other items contained in this document. + + +Copyright and Trademarks +All rights reserved. Information and images contained within this doc- +ument are copyright and the property of Rapita Systems Ltd. All trade- +marks are hereby acknowledged to be the properties of their respective +owners. + + +Acknowledgments +Rapita Systems' tools are built using AdaCore's GNAT Pro compiler. + + +Rapita Systems Ltd. +Registered in the UK, number 5011090. +Registered address: +Atlas House +Link Business Park +Osbaldwick Link Road +York +YO10 3JB +UK +Phone: +44 (0) 1904 413 945 +http://www.rapitasystems.com/ +This document copyright © 2006-2019, Rapita Systems Ltd. + +Document build 118520 + +ID: DOC/16001 + Table of Contents + + 1. About this guide ............................................................... 7 + 1.1. Who should read this guide? ................................................... 7 + + 1.2. Structure of this guide ........................................................... 7 + + 1.3. Notation ............................................................................ 8 + + 1.4. RVS documentation map ........................................................ 9 + + 1.5. Support ........................................................................... 10 + + + 2. What are RVS annotations? ............................................. 11 + + 3. Syntax and placement .................................................... 13 + 3.1. Placing annotations ............................................................. 13 + + + 4. Annotation parameters .................................................... 17 + 4.1. bool ................................................................................ 17 + + 4.2. code/statement .................................................................. 17 + + 4.3. condition .......................................................................... 17 + + 4.4. coverage_type ................................................................... 17 + + 4.5. expr ................................................................................ 17 + + 4.6. file .................................................................................. 18 + + 4.7. fpexpr ............................................................................. 18 + + 4.8. func ................................................................................ 18 + + 4.9. id_set .............................................................................. 19 + + 4.10. path .............................................................................. 20 + + 4.11. pathname ....................................................................... 20 + + 4.12. profile ............................................................................ 20 + + 4.13. tag ................................................................................ 21 + + +Annotations Reference Guide vWF20190404 3 + Table of Contents + + + 4.14. tagname ......................................................................... 21 + + + 5. Tags ................................................................................ 23 + 5.1. Named tags ...................................................................... 23 + + 5.2. File position tags ................................................................ 23 + + 5.3. ASL tags .......................................................................... 24 + + + 6. Profiles ............................................................................ 27 + 6.1. Profile modifiers ................................................................. 30 + + 6.2. Combining profiles .............................................................. 32 + + + 7. Instrumentation annotations ............................................ 35 + 7.1. add_statement/add_code ...................................................... 37 + + 7.2. black_box and black_box_inline .............................................. 39 + + 7.3. build_id ........................................................................... 42 + + 7.4. default_instrument ............................................................... 43 + + 7.5. exclude_ipoint_IDs .............................................................. 45 + + 7.6. enable/disable_function_wrap ................................................. 46 + + 7.7. enable/disable_instrumentation ............................................... 48 + + 7.8. exit_point/exit_function .......................................................... 50 + + 7.9. ignore_subprogram ............................................................. 52 + + 7.10. instrument ....................................................................... 53 + + 7.11. instrument_inline ............................................................... 56 + + 7.12. instrumentation_point ......................................................... 58 + + 7.13. start_root/end_root ............................................................. 61 + + 7.14. uncertain_return ................................................................ 63 + + + 8. Analysis annotations ....................................................... 65 + 8.1. call_to and default_call_to ..................................................... 68 + + 8.2. call_through_to .................................................................. 73 + + +4 Annotations Reference Guide vWF20190404 +Table of Contents + + + 8.3. cor_include_calls, default_cor_include_calls, cor_include_this_call ...... 75 + + 8.4. disable_inherited_justifications ................................................ 79 + + 8.5. expand_calls, default_expand_calls, expand_this_call .................... 80 + + 8.6. ignore_path ....................................................................... 84 + + 8.7. justification ....................................................................... 87 + + 8.8. loop_max_iter .................................................................... 91 + + 8.9. max_wpaths ...................................................................... 93 + + 8.10. no_fold .......................................................................... 94 + + 8.11. overall_wcet_calls, overall_wcet_this_call .................................. 96 + + 8.12. path_id .......................................................................... 99 + + 8.13. recursive ....................................................................... 101 + + 8.14. tag .............................................................................. 102 + + 8.15. unroll_this_loop, default_unroll_loops ..................................... 104 + + 8.16. wfreq ........................................................................... 106 + + 8.17. wp_*, lwp_* ................................................................... 109 + + 8.18. wpath, lwpath ................................................................. 112 + + +Annotations Reference Guide vWF20190404 5 +This page intentionally left blank +1 About this guide + This guide describes how RVS annotations can be used to determine how RVS + analyzes source code. + +1.1 Who should read this guide? + This guide is intended for RVS users who need to apply annotations to change + the analysis applied during RVS analysis, or who want to learn how RVS uses + annotations to analyze source code. + +1.2 Structure of this guide + This document includes the following chapters: + + Chapter 1: About this guide + Describes the purpose and layout of this guide and the notation used throughout it. + + Chapter 2: What are RVS annotations? + Describes what RVS annotations are and how they can be used to control RVS + analysis. + + Chapter 3: Syntax and placement + Describes syntax and placement restrictions for RVS annotations. + + Chapter 4: Annotation parameters + Describes the parameters that can be supplied for RVS annotations. + + Chapter 5: Tags + Describes the types of tag that can be used with annotations, which specify loca- + tions in source code without being added to it. + + Chapter 6: Profiles + Describes the instrumentation profiles that can be used with RVS and modifiers + that can be applied to these profiles. + + Chapter 7: Instrumentation annotations + Describes annotations that can be used to modify the instrumentation applied by + RVS. + + Chapter 8: Analysis annotations + Describes annotations that can be used to modify RVS analysis. + + +Annotations Reference Guide vWF20190404 7 +Notation About this guide + + +1.3 Notation + This document uses the following notation: + • References to other documents are formatted in italics. + • References to other chapters or sections in this document are written in either + italics or default text formatting. When reading an electronic copy of this doc- + ument, you can click on a reference to navigate to that chapter or section. + • Names of RVS applications are formatted in bold italics, for example RVS + Project Manager. + • References to areas or elements in graphical user interfaces such as the RVS + Project Manager are formatted in italics, for example the Report Navigator. + • Menus, menu choices and button labels are formatted in bold, for example + File » Print or OK. Where buttons have icons, these are shown before their + Label in in-line text, for example Save. + • Names of RVS tools are formatted in bold, for example rvsdriver. + • References to HTML links appear as underlined text, for example + www.rapitasystems.com. + • Command-line tools and their commands, annotations, file names and ex- + amples are formatted in a monospaced font. These are either written + in-line with text or as separate text blocks. When written in-line with text, + they are formatted like the following: rvsdriver, default_instrument, + rvs_instr.h. When written as a separate text block, they are formatted like + the examples below: + rvsdriver --project rvs.rvsprj --all + + #pragma RVS instrument( "function_name", "FALSE" ) + + • For the purposes of Ada, the term functions refers to both functions and pro- + cedures. + • Parameters to RVS annotations appear in angle brackets, for example , , or , and must be replaced by an appropriate function, + variable or file name respectively. Boolean parameters are marked as + and may have values TRUE or FALSE. Parameters appearing in square brack- + ets are optional, such as + [ , ] + . In some situations, parameters are enclosed in square brackets, + which are represented in boldface to distinguish them from optional parame- + ters. Thus: + [ [] ] + + + Indicates that the token tagref is optional, but if it appears, it must be enclosed + in square brackets. + + +8 Annotations Reference Guide vWF20190404 +About this guide RVS documentation map + + +1.4 RVS documentation map + This document is part of the Rapita Verification Suite (RVS) document set, which + contains the following documents: + + RVS Installation and Licensing Guide + Describes how to install RVS tools, and licensing options for them. + + RVS Integration Guide + Describes how to integrate RVS tools into build and target environments. + + RVS User Guide + Describes how to set up and run RVS projects, analyze data and export verification + results. + + RapiTest User Guide + Describes how to use RapiTest to manage test projects. + + Spreadsheet Test Format User Guide + Describes how to write tests for RapiTest in the Spreadsheet Test Format. + + RapiCover User Guide + Describes how to use RapiCover to measure code coverage and address cover- + age holes. + + RapiTime User Guide + Describes how to use RapiTime to measure timing metrics including worst-case + execution time, and how to use these metrics to identify the best optimization + candidates. + + RapiTask User Guide + Describes how to use RapiTask to measure system level task timing information, + visualize traces and gain insight into runtime behavior. + + RTBx 2xxx User Guide + Describes how to use the RTBx data logger. + + RVS Integration Library Implementation Guide + Describes how to implement RVS integration libraries. This document is for use by + readers with a thorough understanding of the implementation of RVS. + + RVS Files Reference Guide + Describes RVS-specific files including input, intermediate and output files. + + RVS Filters Guide + Describes RVS filters, which are used to convert raw trace data into a format that + RVS can analyze, and how to write them. + + +Annotations Reference Guide vWF20190404 9 +Support About this guide + + + RVS Command Line Tools Reference Guide + Describes the command-line tools used by RVS, including a list of available com- + mand options. + + RVS Annotations Reference Guide + Describes the annotations you can use to control instrumentation and analysis + with RVS. + + RVS Troubleshooting Guide + Describes the error and warning messages you may encounter when using RVS + tools, and how to address them. + + RVS Migration Guide + Describes how to migrate between using different versions of RVS. + +1.5 Support + For support issues, please contact Rapita Systems Ltd. by any of the following + means: + + Email + support@rapitasystems.com + + Telephone + +44 (0) 1904 413 945 + + Website + www.rapitasystems.com + + To register for support, visit www.rapitasystems.com/register. More than one user + can register per license. + + +10 Annotations Reference Guide vWF20190404 + What are RVS +2 annotations? + RVS annotations let you control the way your source code is instrumented by RVS. + These annotations let you customize an instrumentation strategy by specifying + which types of analysis RVS runs when it analyzes your code. You can use anno- + tations to specify your analysis down to the level of individual lines of code. + + Annotations can be supplied inline within program source code or in an external + configuration file. There are two types of annotations: global and local. Global + annotations apply everywhere, whereas local annotations have a limited scope— + for example, one loop within one function. For more information on the placement + and effect of annotations, see Section 3.1. + + Annotations can be used for two purposes: instrumentation and analysis. Instru- + mentation annotations control how your source code is instrumented automatically + by RVS, see Chapter 7. Analysis annotations control how output data is processed + after being received from the target hardware, see Chapter 8. + + +Annotations Reference Guide vWF20190404 11 +This page intentionally left blank +3 Syntax and placement + The syntax of annotations is as follows: + + Language Example Syntax + C, C++ #pragma RVS exit_function("quit") + + C, C++ /*##RVS exit_function("quit")*/ + + C99 onward, ven- //##RVS exit_function("quit") + dor-specific C, C++ + Ada pragma RVS (exit_function("quit")); + + + Warning + + When using a stylized comment to represent an annotation, make sure that + your preprocessor does not strip the comments from the preprocessed + source. If comments are stripped, the annotations will disappear before + they can be processed by the instrumenter. + + + Note + + The CodeWarrior IDE only accepts specific pragmas. It will not compile + code that uses RVS pragmas. If you are using CodeWarrior, we recommend + that you add annotations using the comment style instead. + + +3.1 Placing annotations +3.1.1 Annotation lines + In terms of line-by-line placement of annotations, there are some further restric- + tions and considerations: + • C/C++ pragma format: each annotation must be on a separate line, on its + own with no comments, with the # character in the first column. + • C/C++ comment format: you can only use comments in conjunction with an + option to your C pre-processor to preserve comments in the preprocessed + source, otherwise your pre-processor will remove annotations before they can + reach cins or cppins. You cannot place comments inside expressions. + • C++ style comments: you can only use C++ style comments if the compiler + tool chain supports them. As with C-style comments, you can only use this + +Annotations Reference Guide vWF20190404 13 +Placing annotations Syntax and placement + + + annotation style in conjunction with an option to your C pre-processor to pre- + serve comments in the preprocessed source, otherwise your pre-processor + will remove annotations before they can reach cins or cppins. + • Expressions: you cannot place annotations inside expressions. For example, + the following code gives an error because the annotation on line 7 is embed- + ded within an expression. You can work around this limitation by using a local + variable. + + Example 3.1: Illegal placement of annotations in expressions + + 1: ... + 2: /* This source code can not be parsed by the + instrumenter */ + 3: void + 4: my_function(void) + 5: { + 6: z = calc(x) + 7: #pragma RVS expand_this_call ( "calc","TRUE") + 8: + calc(y); + 9: #pragma RVS expand_this_call ( "calc","TRUE") + 10: } + 11: ... + + + • Annotations may be placed in both source code and in additional files passed + to the instrumenter with the -c option. Annotations in the C/C++ comment + and pragma styles are supported in C and C++ source code. Annotations in + the Ada pragma style are supported in Ada source code. Annotations in the C/ + C++ comment style and all pragma styles (C/C++ and Ada) are supported + for C, C++ and Ada code when using the -c option. + + Example 3.2: Ada Annotation formats + + ... + pragma RVS(ignore_path); + ... + + +3.1.2 Program structure + The placement of an annotation within the program structure controls which parts + of the program are affected by the annotation. The exact relationship depends on + what the annotation does: + • Analysis annotations control the way results are processed. They may be + placed arbitrarily in the source code files or in external files, but the file must + be processed by xstutils to create an analysis .xsc file. + • Some instrumentation annotations such as disable_instrumentation, + instrumentation_point or cpp_add must be placed at the exact + line where the action should take place. In some cases the action al- + ters the instrumented code output on that line; in other cases (e.g. for +14 Annotations Reference Guide vWF20190404 +Syntax and placement Placing annotations + + + disable_instrumentation) the action affects subsequent source- + code modifications. + • Some analysis annotations such as call_to are placed directly after the call + that they affect. + • The remaining instrumentation annotations take effect from the point at which + they occur in the preprocessed source file. For example, instrumentation an- + notations that are intended to control the instrumentation applied for a partic- + ular function must appear before the start of that function to have any effect + on it. + + The recommended placement of annotations for a standard integration is as fol- + lows: + • Put instrumentation annotations into a file rvs_instr.h. This should be + used with the -c option of the instrumenter. This provides the same annota- + tions to multiple files, reducing the risk of inconsistent instrumentation. Note + that the file can use C or C++ syntax with any instrumenter, including adains, + and that adains also accepts the Ada syntax for annotations. When instru- + menting C and C++ code, note that the file will be prepended to the instru- + mented output, so its contents must be syntactically valid for your C or C+ + + compiler. + • Put analysis annotations into a file rvs_annot.c. This should be processed + with cins as though it were a normal C source file, but with the --no-instr + option. This produces an XSC file that provides the analysis control information + for xstutils, covparser and timeparser. + • Put indirect call annotations into a file rvs_fptr.h. This is supplied in the + same way as rvs_instr.h, to optimize the placement of instrumentation + points, and also in the same way as rvs_annot.h, so that information about + indirect calls may be used for analysis. + + +Annotations Reference Guide vWF20190404 15 +This page intentionally left blank +4 Annotation parameters + This section provides more detail on the parameters that can be supplied to an- + notations. All annotation parameters must be enclosed in double quotes. + +4.1 bool + The parameter type is a Boolean. Specify Booleans as either "TRUE", + or "FALSE". + +4.2 code/statement + The parameter type is a string containing source code, which can be + any valid source code fragment. Parameter type can only contain + valid statements, and should not include the statement terminator (semi-colon in + C, C++ and Ada). + +4.3 condition + The parameter is a string representing an expression used as a + MC/DC condition in the source code and it's 'index' in the decision and is used by + the justification annotation (see Section 8.7 for more detailed information). + +4.4 coverage_type + The parameter type is a string describing a type of cov- + erage metric and is used by the justification annotation (see Section 8.7). + It can be: + COV_FUNCTIONS + COV_BRANCHES (or COV_DECISIONS) + COV_CALLS + COV_STATEMENTS + COV_MCDC + + +4.5 expr + The parameter type is a numerical expression. Construct expressions + from integers using the following arithmetic operators: + • + - * / mod + • parentheses () + • ceil(x,y) + • floor(x,y) + • abs(x) + + +Annotations Reference Guide vWF20190404 17 +file Annotation parameters + + + • sgn(x) + • max(x,y) + • min(x,y) + + The / operator rounds towards zero, i.e. any fractional part of the result of x/y + is discarded. + + The ceil(x,y) function computes x/y and then rounds towards positive infin- + ity, giving the smallest integer that is greater than or equal to x/y. + + The floor(x,y) function computes x/y and then rounds towards negative + infinity, giving the largest integer that is less than or equal to x/y. + + The sgn(x) function is 1 if x is positive, -1 if x is negative, and 0 if x is zero. + + Example 4.1: Numeric expression used as an annotation parameter + + ... + #pragma RVS wfreq("min(floor(15*64,19),50)") + ... + + +4.6 file + The parameter type is a file name. For example "ETP123.txt". + +4.7 fpexpr + The parameter type is a function pointer expression. + +4.8 func + The parameter type is a function name, for example main. + + Function, namespace and package names can be specified using wildcards or + regular expressions, to match multiple function names corresponding to a given + pattern. + + The following notation is supported: + • *: any string of 0 or more characters + • ?: any one character + • [a,x,z]: any one character a or x or z + • [a-z]: any one character in range a to z + • {xxx,yyy,zzz}: string xxx or yyy or zzz + + An example of matching multiple functions during instrumentation: + instrument ("pkg*.funX[a-z]", "TRUE") + + +18 Annotations Reference Guide vWF20190404 +Annotation parameters id_set + + +4.8.1 Static C/C++ functions + For static C/C++ functions, which may use the same name in different files, you + must supply an unambiguous partial or full path name prefix to identify the (static) + function to which the annotation applies. For example "dir1\myfile:bfun" + + Note + + You may represent the directory separator as either '\' or '/' + + +4.8.2 C++ namespaces/class methods + For functions and methods within namespaces, the name is made up of the name- + space followed by the '::' separator followed by the function name. If several name- + spaces are nested, all namespaces are part of the name (separated by '::'). For + example instrument ("N::M::foo", "TRUE"). + + For methods within classes, the same format is used. For example: + instrument("N::Obj::bar"). + +4.8.3 Ada packages + To identify subprograms within Ada packages, types or subprograms, use the ful- + ly-qualified Ada name. For example, the function count_entries within the + procedure manage_entries within the child package ff_db in the package + db is identified as db.ff_db.manage_entries.count_entries. To refer + to the entry point of an Ada program, use the procedure name as though it were a + package name. For example, the top-level procedure main_program is identi- + fied as main_program.main_program. + + Note + + Wildcards can be used to match some or all subprograms contained within + a package, for example: + instrument("my_package.*", "TRUE") + will cause all subprograms within the package my_package to be instru- + mented. + + +4.8.4 C++ templates/Ada generics + When referring to C++ templates or Ada generics, refer to the name of the tem- + plate or generic itself rather than the names under which it is instantiated. + +4.9 id_set + The parameter type allows you to specify a set of ipoint identifiers. + Each identifier is a decimal integer. The set of integers can be described using: a + + +Annotations Reference Guide vWF20190404 19 +path Annotation parameters + + + single value; a comma separated list of values; or a range of values. Complicated + sets can be described by combining the above operations. + + For example, the following are all valid s. + + 13 + 13, 17, 23 + 13..35 + 11, 13..35, 20009, 37 + +4.10 path + The parameter type is a reference to a path ID (as defined by a path_id + annotation). + +4.11 pathname + The parameter type is used by the path_id annotation + to define a path ID. Path names must be valid C-style identifiers, for example + "path_name". + +4.12 profile + The parameter type is an instrumentation profile, specifying the level + of instrumentation added to code (which in turn controls the level of detail that + reports can achieve). For reference, the list of possible profiles is as follows: + + NONE + MANUAL + TIME_FULL + TIME_FUNCTIONS + TIME_START_OF_SCOPES + COV_178_DAL_A + COV_178_DAL_B + COV_178_DAL_C + COV_26262_HR_ASIL_A + COV_26262_HR_ASIL_B + COV_26262_HR_ASIL_C + COV_26262_HR_ASIL_D + COV_BRANCHES + COV_CALLS + COV_DECISIONS + COV_FUNCTIONS + COV_FUNCTION_EXITS + COV_MCDC + COV_STATEMENTS + + See Chapter 6: Profiles for details about each instrumentation profile. + + +20 Annotations Reference Guide vWF20190404 +Annotation parameters tag + + +4.13 tag + The parameter type is either a reference to a named tag (as defined by a + tag annotation) or an ASL tag. + + In C and C++ both types of tag reference must be enclosed within square brack- + ets, for example: + #pragma RVS ["tag_name"] annotation(annotation_param) + /*##RVS ["func@P2"] annotation(annotation_param) */ + + In Ada, both types of tag reference are given as the first parameter to the RVS + pragma, for example: + pragma RVS ("tag_name", annotation(annotation_param)); + pragma RVS ("pkg.read_data@L1", annotation(annotation_param)); + + +4.14 tagname + The parameter type is used by the tag annotation to define a named + tag. Tag names must be valid C-style identifiers, for example "tag_name". + + +Annotations Reference Guide vWF20190404 21 +This page intentionally left blank +5 Tags + Annotation tags allow annotations to apply to specific sections of source code + without the need to place annotations in the code. RVS uses these tags to modify + the analysis applied during an integration, and you can also use them for this + purpose. + + Three types of tags are available, which identify locations in source code in differ- + ent ways: + • Named tags – these identify a location and reference it by using a user-defined + name. + • File position tags – these identify a location in a file by using a line position. + • Abstract Source Location (ASL) tags – these identify a location by describing + it in terms of the structure of the source code. + +5.1 Named tags + Named tags are defined using the tag annotation (see Section 8.14). + + Example 5.1: Defining and using tag names + + 1: ... + 2: if (x > 0) + 3: { + 4: process(x); + 5: #pragma RVS tag ("block123") + 6: } + 7: ... + 8: #pragma RVS ["block123"] ignore_path + 9: ... + + + In Example 5.1, there is a named tag on line 5, within the body of the if statement. + This enables a 'global' annotation (line 8) to refer to that location. In this case the + ignore_path annotation configures the analysis to ignore the path taken for + positive values of x. + +5.2 File position tags + The format of a file position tagged annotation is as follows: + + #pragma RVS [":"] + + +Annotations Reference Guide vWF20190404 23 +ASL tags Tags + + + Where is the name of a source file and is the + line position within that file where the element to annotate can be found. + +5.3 ASL tags + The format of an ASL tagged annotation is as follows for C and C++ code: + + #pragma RVS [@] + + + And as follows for Ada code: + + pragma RVS( "@", ); + + + Where is a function name, is L for loop, C for call + or P for conditional path, and is an integer starting from 1 (1 being the + first in the function). + + Note + + As an exception, @P0 represents the body of the function (non-conditional + path). + + +24 Annotations Reference Guide vWF20190404 +Tags ASL tags + + + Example 5.2: ASL Tags + + 1: ... + 2: void + 3: initialize_array(t_data tab, int x, int y) + 4: { + 5: /* this is ASL location @P0 */ + 6: int i,j; // + 7: + 8: if (x != 0) { + 9: /* this is @P1 */ + 10: } else { + 11: /* this is @P2 */ + 12: } + 13: + 14: if (tab == NULL) { + 15: /* this is @P3 */ + 16: fatal_error (); + 17: } + 18: + 19: for (i=0 ; i < x ; i++) + 20: { /* this is loop ASL @L1 */ + 21: for (j=0 ; j < y ; j++ ) { + 22: /* and this is @L2 */ + 23: reset (tab,i,j); + 24: } + 25: } + 26: } + 27: + 28: #pragma RVS [initialize_array@L2] loop_max_iter (10) + 29: #pragma RVS [initialize_array@C2] expand_this_call + ("reset", "TRUE") + 30: #pragma RVS [initialize_array@P3] ignore_path + 31: + 32: ... + + + In Example 5.2, the annotation with an ASL tag on line 28 specifies a maximum + number of iterations for the second loop in function initialize_array (at + line 21). + + The annotation with an ASL tag on line 29 indicates that the second function call + in initialize_array (at line 23) should be expanded. + + Finally, the annotation with an ASL tag on line 30 indicates that the first conditional + path in initialize_array (at line 16) should be ignored (i.e. the error case). + + The ASL tags enable these annotations to refer to locations inside + initialize_array without modifying its source code. + + +Annotations Reference Guide vWF20190404 25 +ASL tags Tags + + + Note + + There is a strict left to right ordering on function calls, loops and conditional + paths. The order for loops and conditionals is defined by the position of the + "if", "while" or "do" keywords. The order for calls is defined by their positions + marked by the character of the opening parenthesis of its argument list. In + the example g((*f())()), the calls are 1:g(), 2:f(), 3:the function pointed + to by f's return value. + + + Warning + + ASL tags are resolved against preprocessed code, i.e. after the expansion + of macros and the resolution of conditional compilation sections. + + If preprocessor macros are expanded to contain loops or conditionals, the + expanded versions of the numbering used by ASL tags must take these ex- + pansions into account. If the implementation of macros is altered to add + or remove loops or conditionals, the numbering used by ASL tags will also + need to be altered accordingly. + + + Warning + + The C construct + do { ...} while(0); + is syntactically a loop, but executes exactly once. It is commonly used to + ensure that a macro replacement with several statements is handled cor- + rectly. This idiom is therefore not considered as a loop for the ASL notation. + + +26 Annotations Reference Guide vWF20190404 +6 Profiles + RVS instrumentation profiles are the primary mechanism for controlling the instru- + mentation that is added to the source code. + + Profiles are grouped according to the purpose of the instrumentation points that + they add; timing profiles add instrumentation points for timing analysis and cov- + erage profiles do the same for measurement of structural coverage. + + The profiles that can be used by RVS tools are listed in Table 6.1: + + Table 6.1 RVS instrumentation profiles + Profile Description Product + NONE Do not add instrumentation. all + MANUAL Adds instrumentation points where all + they are explicitly requested by the + use of instrumentation_point, + exit_point, or + start_root/end_root annota- + tions. + TIME_FULL Add instrumentation points at the be- RapiTime, + ginning and end of all blocks of code. RapiTask + TIME_FUNCTIONS Add instrumentation at the entry and RapiTime, + exit points of functions. RapiTask + TIME_START_OF_SCOPES Add instrumentation points at the be- RapiTime, + ginning of blocks of code. RapiTask + COV_178_DAL_A This is an alias for a collection of cov- RapiCover + erage profiles suitable for performing + structural coverage analysis of soft- + ware to level A for DO-178B/C. It is + equivalent to (COV_FUNCTIONS+ + COV_STATEMENTS+ + COV_DECISIONS+ COV_MCDC). + COV_178_DAL_B This is an alias for a collection of cov- RapiCover + erage profiles suitable for performing + structural coverage analysis of soft- + ware to level B for DO-178B/C. It is + equivalent to (COV_FUNCTIONS+ + COV_STATEMENTS+ + COV_DECISIONS). + COV_178_DAL_C This is an alias for a collection of cov- RapiCover + erage profiles suitable for performing + structural coverage analysis of soft- + ware to level C for DO-178B/C. It is + + +Annotations Reference Guide vWF20190404 27 + Profiles + + + Profile Description Product + equivalent to (COV_FUNCTIONS+ + COV_STATEMENTS). + COV_26262_HR_ASIL_A This is an alias for a collection of cov- RapiCover + erage profiles suitable for perform- + ing structural coverage analysis of + software to ASIL A for ISO 26262. It is + equivalent to (COV_FUNCTIONS+ + COV_STATEMENTS). + COV_26262_HR_ASIL_B This is an alias for a collection of cov- RapiCover + erage profiles suitable for perform- + ing structural coverage analysis of + software to ASIL B for ISO 26262. It is + equivalent to (COV_FUNCTIONS+ + COV_STATEMENTS+ + COV_BRANCHES). + COV_26262_HR_ASIL_C This is an alias for a collection of cov- RapiCover + erage profiles suitable for performing + structural coverage analysis of soft- + ware to ASIL C for ISO 26262. It is + equivalent to (COV_FUNCTIONS+ + COV_STATEMENTS+ + COV_BRANCHES+ COV_CALLS). + COV_26262_HR_ASIL_D This is an alias for a collection of cov- RapiCover + erage profiles suitable for performing + structural coverage analysis of soft- + ware to ASIL D for ISO 26262. It is + equivalent to (COV_FUNCTIONS+ + COV_STATEMENTS+ + COV_BRANCHES+ COV_CALLS+ + COV_MCDC). + COV_BRANCHES Add instrumentation to measure branch RapiCover + coverage. Instrumentation points are + added at the entry and exit points of + functions and at the beginning of all + branches. + COV_CALLS Add instrumentation to measure call RapiCover + coverage. Instrumentation points are + added at the entry and exit points of + functions and before function calls. + COV_DECISIONS Add instrumentation to measure deci- RapiCover + sion coverage. Instrumentation points + are added at the entry and exit points + of functions and at the beginning of all + branches. + COV_FUNCTIONS Add instrumentation to measure func- RapiCover + tion entry coverage. Instrumentation + points are added at the entry points of + + +28 Annotations Reference Guide vWF20190404 +Profiles + + + Profile Description Product + functions as well as before some func- + tion calls. + COV_FUNCTION_EXITS Add instrumentation to measure func- RapiCover + tion exit coverage. Instrumentation + points are added at exit points of func- + tions. + COV_MCDC Add instrumentation points to measure RapiCover + MC/DC. + COV_STATEMENTS Add instrumentation to measure state- RapiCover + ment coverage. Instrumentation points + are added at the entry and exit points of + functions and after all blocks of state- + ments. + + + Note + + The instrumenter will place instrumentation points as per the specified pro- + file. Additionally, the instrumenter will detect any calls to the instrumentation + point functions (RVS_I and RVS_Ipoint) that are already present in the + source code, and will treat these as instrumentation points in the report. + + This behavior occurs in all profiles (including NONE) and also when instru- + mentation is disabled by using a disable_instrumentation annota- + tion, the --no-instr instrumenter option, or by setting the instrumenta- + tion to FALSE using an instrument or default_instrument anno- + tation. + + +Annotations Reference Guide vWF20190404 29 +Profile modifiers Profiles + + + Important + + The choice of instrumentation profile (including any modifiers) controls the + placement of instrumentation points in the application code by the instru- + menter. By selecting a particular profile, the instrumenter will ensure that + sufficient instrumentation points are present to permit measurement of tim- + ing or coverage at the requested level. + + The instrumentation process is deterministic, so instrumenting the same + source code twice with the same RVS version, profile, options and input file + order will produce identical instrumented output. The instrumented output + will not be identical if different tool options or profiles are used. + + As part of Rapita Systems's policy of continuous improvement, or to ad- + dress any defects that are identified, it may be necessary to make changes + to the instrumentation policy in any major, minor or incremental RVS ver- + sion. These changes may cause the instrumenter to insert more or fewer in- + strumentation points than in previous versions, or to insert instrumentation + points at locations that are different from previous versions. + + It is therefore not possible to guarantee that the instrumented output pro- + duced by one version of RVS will be identical to that produced by any other + RVS version, however the inserted instrumentation will be sufficient to per- + form timing or coverage analysis at the requested level. + + +6.1 Profile modifiers + The behavior of the profiles can be modified by adding modifiers prefixed with "-" + or "+", for example "TIME_FUNCTIONS-m". The profile modifiers are typically + used to reduce ("-") or increase ("+") the number of instrumentation points that + are generated. + + Profile modifiers and the profiles that they work with are as follows: + + Profile modifier + Profile -b +c [+-]e -l [+-]m -q -t [+-]x +u + NONE - - o - - - - - o + MANUAL - - - - - - - - - + TIME_FULL - - o ● - ● ● o o + TIME_FUNCTIONS - - o - ● - - o ● + TIME_START_OF_SCOPES - - o ● - ● ● o o + COV_BRANCHES - - ● - ● - - ● - + COV_CALLS - - ● - ● - - ● - + COV_DECISIONS - - ● - ● - - ● - + COV_FUNCTIONS - - ● - ● - - ● - + + +30 Annotations Reference Guide vWF20190404 +Profiles Profile modifiers + + Profile modifier + Profile -b +c [+-]e -l [+-]m -q -t [+-]x +u + COV_FUNCTION_EXITS - - - - ● - - ● - + COV_MCDC ● - - - - - - - - + COV_STATEMENTS - ● ● - - - - ● - + + ● - the profile modifier is supported by the profile. + o - the profile modifier is available, but not usually used because it may add in- + strumentation points that are not required (+) or remove useful instrumentation + points (-). + + The profile modifiers are as follows: + + • -b + + Do not instrument branches. This applies to MC/DC coverage profiles. Deci- + sions and conditions are still instrumented. + • +c + + Always insert an ipoint before each function call when instrumenting for state- + ment coverage. Ipoints are never inserted by default when using map instru- + mentation. Specifying +c overrides this default. If the ipoint is not present, + covered statements before a call to a non-returning function may be marked + as uncovered. Adding ipoints incurs an additional instrumentation overhead + for each call. + + If you are using map instrumentation, and your code contains calls to non-re- + turning functions, you can use COV_STATEMENTS+c to insert the additional + ipoints. + • -e and +e + + Never (-e) or always (+e) instrument the entry point of a function. The ipoint + is inserted by default for trace instrumentation, and omitted by default for map + instrumentation. + • -l + + Do not instrument loops. Note that this may cause the maximum number of + iterations of loops to be measured incorrectly by timeparser in some cases. + • -m + + Some ipoints are inserted solely to disambiguate a trace (e.g. to distinguish + between calls to the same function in a conditional that is otherwise not in- + strumented). The -m modifier prevents these ipoints from being inserted. This + can render the generated trace non-deterministic and therefore unsuitable for + RapiTime analysis. + • +m + +Annotations Reference Guide vWF20190404 31 +Combining profiles Profiles + + Force the insertion of more disambiguation ipoints by not relying on ipoints to + be present in other functions. + • -q + + Do not instrument the 'C' ternary operator (the ?: operator, e.g. + (a > b) ? a : b). + • -t + + Do not instrument tight loops. A tight loop is defined as a loop that does not + contain any conditional statements, any inner loops or any function calls and + spans less than or equal to 15 lines of (preprocessed) source code. + + In the case of tight loops (for example copying data from one buffer to another) + placing instrumentation points within the loop may result in a large overhead as + well as the generation of very large amounts of trace data. If you are confident + that the test data results in the maximum number of loop iterations in each + calling context, you can omit instrumentation. + • -x and +x + + Never (-x) or always (+x) instrument the exit points of a function. The ipoints + are inserted by default for trace instrumentation, and omitted by default for + map instrumentation. + • +u + + Adds required instrumentation points in loops to ensure that the generated + trace is deterministic even if loop unrolling is specified during the analysis + phase (see Section 8.15). + +6.2 Combining profiles + RVS supports multiple simultaneous profiles. For example, combining + TIME_FUNCTIONS with COV_STATEMENTS provides both timing and code cov- + erage information. Similarly, combining COV_STATEMENTS with COV_MCDC pro- + vides multiple simultaneous coverage analyses. + + To specify a combined profile, list the individual profiles together with "+" signs + and enclose the list in parentheses. For example: + + Example 6.1: Combining profiles + + #pragma RVS instrument("str_c_int", "TRUE", "(TIME_FUNCTIONS + +COV_STATEMENTS)") + #pragma RVS default_instrument("TRUE", "(COV_STATEMENTS+COV_MCDC)") + + + To apply a modifier to a combined profile, add the modifier tag to the end of the + combination: + + +32 Annotations Reference Guide vWF20190404 +Profiles Combining profiles + + Example 6.2: Combining profiles with a modifier + + #pragma RVS instrument("x_tri", "TRUE", "(TIME_FUNCTIONS + +COV_DECISIONS)-x") + + + Multiple profile modifiers may also be combined: + + Example 6.3: Combining profiles + + #pragma RVS instrument("ctrl_night", "TRUE", "(COV_DECISIONS + +COV_STATEMENTS)-ex") + #pragma RVS instrument("ctrl_day", "TRUE", "TIME_START_OF_SCOPES- + qt"); + + + When multiple profiles are combined, the source code is instrumented with all of + the instrumentation points necessary for each profile, and the report is prepared + so that it is able to receive the corresponding target data. + + +Annotations Reference Guide vWF20190404 33 +This page intentionally left blank + Instrumentation +7 annotations + This section describes annotations that control the quantity and location of instru- + mentation points that are added to your application. The instrumentation anno- + tations use profiles to define which instrumentation strategy is being applied at + which point in your code. Valid profiles are defined in Chapter 6: Profiles. + + Important + + Instrumentation annotations must be placed before the definition of the ref- + erenced function otherwise they will have no effect. + + + Note + + If no annotation is supplied for a given file (either within the file or with the + -c option), then the instrumenter will not instrument anything + in that file, with the exception of C++ constructors and destructors which + must be instrumented to resolve their potential implicit invocation. + + RVS includes the following instrumentation annotations: + Annotation Description Scope + add_statement Inserts a statement in the instru- Local + mented code. + add_code Inserts arbitrary text (source code) in Local + the instrumented code. + black_box Instrument before and after calls to Global + a specific function that can't be di- + rectly instrumented. + black_box_inline Treat a function and its call tree as a Global + block of code with a single path. + black_box_inline_ Treat a specified call to a function Local + this_call and its call tree as a block of code + with a single path. + build_id Tag the generated XSC file with a Global + build id. + default_instrument Set the default instrumentation pro- Global + file to use for all functions. + exclude_ipoint_IDs Prevent a set of values to be used Global + as ipoint IDs. + disable_instrumentation Stop the addition of instrumentation Local + points to the source code. + + +Annotations Reference Guide vWF20190404 35 + Instrumentation annotations + + + Annotation Description Scope + enable_instrumentation Restart the addition of instrumenta- Local + tion points to the source code. + exit_point Consider a particular source code Local + location as an exit from a function. + exit_function Consider all calls to a particular Global + function as calls that exit the pro- + gram. + ignore_subprogram Completely remove a function from Global + the analysis, preventing it from be- + ing instrumented or shown in re- + ports. + instrument Set a specific instrumentation profile Global + for one or more functions. + instrument_inline Set an instrumentation profile for a Global / + function and consider the function Local + as being inlined by the compiler. + instrumentation_point Insert an additional instrumentation Local + point at the location of the annota- + tion. + start_root/end_root Inserts instrumentation points with Local + unique IDs that can then be used to + define the root of the analysis with + the @R notation. + uncertain_return For coverage, this indicates that a Global + call to a function may not return. + This annotation causes an extra + ipoint to be injected before the call. + + +36 Annotations Reference Guide vWF20190404 +Instrumentation annotations add_statement/add_code + + +7.1 add_statement/add_code +7.1.1 Applies to + RVS + +7.1.2 Synopsis + C/C++ + #pragma RVS add_statement("") + #pragma RVS add_code("") + /*##RVS add_statement("") */ + /*##RVS add_code("") */ + C++ + //##RVS add_statement("") + //##RVS add_code("") + Ada + pragma RVS (add_statement("")); + pragma RVS (add_code("")); + + +7.1.3 Description + The add_statement and add_code annotations can be manually added to + the source code as follows: + ... + #pragma RVS add_statement ("RVS_Init()") + ... + #pragma RVS add_code ("if (init_done) {RVS_Output();}") + ... + + + Note + + Double quotes in the inserted source code must be escaped. In C and C+ + +, use \, for example: + ... + #pragma RVS add_code("#include \"rvs.h\"") + ... + In Ada, use "", for example: + ... + pragma RVS( add_statement( "RVS.Begin_Test( 2, ""Output + Test"" )" ) ); + ... + + + Note + + It is recommended that you do not place comments inside add_code + or add_statement annotations. C-style comments will not + work inside C-style comment-based annotations, for example: + /*##RVS add_code ("/* comment */")*/ is not valid. + + +Annotations Reference Guide vWF20190404 37 +add_statement/add_code Instrumentation annotations + + These are local annotations that cause the instrumenter (cins, cppins or adains) + to add either a single code statement (add_statement) or an arbitrary section + of code (add_code) at that location in the instrumented source code. + + The add_statement and add_code annotations can be used in situations + where it is necessary for code to be present in the instrumented source code that + is not required when the source code is built without instrumentation, such as any + calls to the RVS API. + + Important + + The RVS tools do not consider the additional code when performing instru- + mentation or structural analysis. This gives rise to a number of considera- + tions that should be examined before using these annotations: + • The code added must be syntactically valid when combined with the in- + strumented code. If for example the code added is to handle a default + case, the instrumenter may also add its own code to measure the de- + fault case. The resulting code is unlikely to be valid. + • If the added code modifies the execution behavior of the code, any + WCET value calculated by RapiTime may be optimistic. + • RapiCover does not consider the additional code as that which needs + to be covered. All uses of add_code and add_statement should + be reviewed when examining coverage results. + • If the additional code contains calls to any instrumented functions, the + execution data may contain sequences of instrumentation point identi- + fiers corresponding to unknown execution paths, causing timeparser or + covparser to fail due to unexpected ipoints. + + + Note + + With the exception of adding a ';' to the end of the statement, + add_statement and add_code offer the same functionality. + + add_statement is provided primarily for the situation where you are us- + ing annotations within comments, and your coding standard does not per- + mit whole statements within comments. In this case, add_statement can + be used. + + +38 Annotations Reference Guide vWF20190404 +Instrumentation annotations black_box and black_box_inline + + +7.2 black_box and black_box_inline +7.2.1 Applies to + RVS (except RapiCover) + +7.2.2 Synopsis + C/C++ + #pragma RVS black_box("") + #pragma RVS black_box_inline(""[,""]) + #pragma RVS[ [""] ] black_box_inline_this_call("") + /*##RVS black_box("") */ + /*##RVS black_box_inline(""[,""]) */ + /*##RVS[ [""] ] black_box_inline_this_call("") */ + C++ + //##RVS black_box("") + //##RVS black_box_inline(""[,""]) + //##RVS[ [""] ] black_box_inline_this_call("") + Ada + pragma RVS (black_box("")); + pragma RVS (black_box_inline(""[,""])); + pragma RVS ([ "", ] black_box_inline_this_call("")); + + +7.2.3 Description + The black_box annotation tells adains, cins or cppins to consider the function + as a "black box". + + Sometimes you may not be able to instrument a function. For example, functions + supplied as part of a 3rd party object code library, hidden function calls (such as + memcpy), and functions incorporating unsupported language constructs, cannot + be instrumented. To deal with these situations, you can mark a function as black + box. We recommend that the black_box annotation is only used in these cases. + + If it is possible to instrument a function but detailed instrumentation is not required, + then you should use the TIME_FUNCTIONS (for RapiTime) or COV_FUNCTIONS + (for RapiCover) instrumentation profile rather than black boxing. See Chapter 6: + Profiles for more details on these instrumentation profiles. + + There are two types of black box annotations, which work as follows: + 1. To make the instrumenter place ipoints before and after all calls to the func- + tion during instrumentation, use the following global annotation: + black_box("library_with_callback"); + + Any ipoints which are encountered in the call tree of + library_with_callback() will be ignored during analysis. + + This is useful for ignoring ipoints generated by part of the application for + which the source code is not supplied. For example, library code may make + calls to instrumented callback functions or invoke instrumented methods on + objects passed to the library code. + + +Annotations Reference Guide vWF20190404 39 +black_box and black_box_inline Instrumentation annotations + + + 2. To treat the function, and its call tree, as if it were a block of code with a single + path through it, use one of the following annotations: + • black_box_inline("func"); + This global annotation black-boxes all calls to function func. + • black_box_inline("funcA","funcB"); + This global annotation black-boxes only calls to function funcA made + from funcB. + • black_box_inline_this_call("func"); + This local annotation black-boxes only the call to function func, which + is located immediately before the annotation. + • ["my_func@C3"] black_box_inline_this_call("func"); + This local annotation black-boxes only the third call to function func + from my_func. + + The time spent in the black-boxed function/sub-functions is allocated to a copy + of the black-boxed function. The report differentiates a black-boxed function from + the original function by prefixing [BB] to the function name. + + Note + + For the black_box_inline annotation, if you use a tag reference, it + must be a reference to a call as opposed to a loop or a path. + + + Important + + You must take care to ensure that the function being black-boxed by + one of the black_box_inline annotations is instrumented (the + "TIME_FUNCTIONS" or "COV_FUNCTIONS" instrumentation profile is + sufficient here). + + + Note + + Using the black_box annotations can generate some errors during in- + strumentation if a statement contains multiple calls to black boxed func- + tions. This is because adains, cins or cppins must put instrumentation + points after each call to a black boxed function. This can be solved in two + ways: + 1. Use a temporary variable to allow the statement to be split into a num- + ber of smaller statements, each of which contains at most one call to a + black boxed function. + 2. Wrap a new function inside the original (black boxed) function and + modify the black_box annotation so that the new function is black + boxed instead of the original function. + + +40 Annotations Reference Guide vWF20190404 +Instrumentation annotations black_box and black_box_inline + + + Note + + Ipoints around calls to the black-boxed functions are always added by the + black_box annotation (but not by the black_box_inline annota- + tions), irrespective of the instrumentation profile or instrumentation policy + employed. + + + Important + + Marking a function as "black box" increases the burden on testing. The tests + must exercise every possible path through the function and any sub-func- + tions in its call tree for the computed WCET to be measured correctly. (The + computed WCET is equal to the longest measured execution time for a + black box function). + + +Annotations Reference Guide vWF20190404 41 +build_id Instrumentation annotations + + +7.3 build_id +7.3.1 Applies to + RVS + +7.3.2 Synopsis + C/C++ + #pragma RVS build_id("") + /*##RVS build_id("") */ + C++ + //##RVS build_id("") + Ada + pragma RVS (build_id("")); + + +7.3.3 Description + The build_id annotation can be manually added to the source code. + + This annotation tags the generated XSC file(s) with a build ID. When the RVD file + is generated by xstutils, the build IDs from all XSC files (if set) and the build ID + specified on the command line (if any) are checked for consistency. + + For example, #pragma RVS build_id("Build_42") will tag the XSC file + with the string "Build_42". + + +42 Annotations Reference Guide vWF20190404 +Instrumentation annotations default_instrument + + +7.4 default_instrument +7.4.1 Applies to + RVS + +7.4.2 Synopsis + C/C++ + #pragma RVS default_instrument("", "") + /*##RVS default_instrument("", "")*/ + C++ + //##RVS default_instrument("", "") + Ada + pragma RVS (default_instrument("", "")); + + +7.4.3 Description + The default_instrument annotation controls whether or not code is in- + strumented by default. You must provide a value for this annotation, otherwise it + will fail with an error (see below). This is a global annotation, which means that it + affects all subsequent lines of code in files in which it appears. You must place this + annotation before objects to which it applies. This annotation also sets the default + instrumentation profile for all functions. + + is the profile to use. Valid profiles are defined in Chapter 6: Profiles. + + If is "FALSE", the default is for no instrumentation to be generated. If + TRUE, the instrumentation is generated as per the profile. + + Important + + If no profile is specified or if a default_instrument annotation is not + provided, then an error is generated. + + Previous versions of RVS did not require this annotation to be specified. For + backward compatibility, the deprecated behavior can be restored by defin- + ing + #pragma RVS default_instrument ("FALSE", "TIME_FULL"); + before other annotations. + + + Note + + As well as placing instrumentation points as per the specified profile, the + instrumenter will detect any calls to the instrumentation point functions + (RVS_I and RVS_Ipoint) that are already present in the source code, + and will treat these as instrumentation points in the report. + + +Annotations Reference Guide vWF20190404 43 +default_instrument Instrumentation annotations + + +7.4.4 Examples + Example 7.1: Default instrumentation set to TIME_FULL-qt profile + + ... + #pragma RVS default_instrument("TRUE", "TIME_FULL-qt") + ... + + + This annotation enables instrumentation, and sets the default instrumentation pro- + file to TIME_FULL with the q and t modifiers enabled. + + Example 7.2: Default instrumentation set to MANUAL profile + + ... + #pragma RVS default_instrument("TRUE", "MANUAL") + ... + + + This will not introduce any Ipoints, except for the ones directly introduced by the + user using the instrumentation_point (Section 7.12), exit_point (Sec- + tion 7.8) or start/end_root (Section 7.13) annotations. + +7.4.5 Errors + The following errors may be raised by the instrumenter (cins, cppins or adains) if + the default_instrument annotation is not supplied or it is malformed: + + E06036: No default_instrument annotation has been provided for this source + file. + The instrumenter could not find a default_instrument annotation. Check + that the file containing instrumentation annotations is being passed to the instru- + menter correctly (using the -c option), and that the file being passed contains a + correctly-formed default_instrument annotation. + + E06037: The default_instrument annotation does not specify an instrumenta- + tion profile. + The default_instrument annotation is malformed and does not specify an + instrumentation profile. Correct the annotation to specify a valid profile. + + +44 Annotations Reference Guide vWF20190404 +Instrumentation annotations exclude_ipoint_IDs + + +7.5 exclude_ipoint_IDs +7.5.1 Applies to + RVS + +7.5.2 Synopsis + C/C++ + #pragma RVS exclude_ipoint_IDs ("") + /*##RVS exclude_ipoint_IDs ("") */ + C++ + //##RVS exclude_ipoint_IDs ("") + Ada + pragma RVS (exclude_ipoint_IDs ("")); + pragma RVS (exclude_ipoint_IDs ("")); + + +7.5.3 Description + #pragma RVS exclude_ipoint_IDs + + Prevents a set of values from being used as IDs for instrumentation points. + + When using options --nbits or --maxid you can specify the maximum value + to be used for ipoints IDs. The range of value used is then 10..maximum_ID (values + 0 to 9 are reserved for special uses). + + The exclude_ipoint_IDs annotation makes it possible to specify a list of + values, or ranges of values that should not be used as ipoint IDs within that + 10..maximum_ID range. + + Note + + When using the Ada annotation format, the ID values must form legal Ada + syntax. You can specify either a list of at least one ID or a single range of + IDs. To exclude multiple ranges, you will need to use multiple annotations. + + +7.5.4 Examples + ... + #pragma RVS exclude_ipoint_IDs(13, 17, 20..22, 35, 39..42) + ... + This annotation prevents the instrumenter from allocating instrumentation points + with any of the following identifiers: 13, 17, 20, 21, 22, 35, 39, 40, 41, 42. + + +Annotations Reference Guide vWF20190404 45 +enable/disable_function_wrap Instrumentation annotations + + +7.6 enable/disable_function_wrap +7.6.1 Applies to + RVS (Ada) + +7.6.2 Synopsis + Ada + pragma RVS (disable_function_wrap ("")); + pragma RVS (enable_function_wrap ("")); + + +7.6.3 Description + pragma RVS (disable_function_wrap ("")); + Prevents the instrumenter inserting function call wrappers for any function calls + matching within the remainder of the current scope. Function call wrap- + ping may be re-enabled using: + pragma RVS (enable_function_wrap ("")); + + Where possible, adains will instrument function calls by placing ipoints before or + after each call. However, this is not possible in all cases, e.g. if the call is part of + a larger expression involving other calls. + + For example, the expression f(a(1), a(2)) contains two calls to function a. + To analyze this expression, it is necessary to disambiguate the two calls. To do + that, adains will create a new function named rvs_wrapN as a wrapper for a. + The expression is rewritten as follows: f(a(1), rvs_wrapN(2)). The new + function named rvs_wrapN contains one or two ipoints and the call to a. + + Function wrapping can increase code size, may affect compiler optimizations and + may increase the execution time of a program. Therefore, it may be useful to dis- + able function wrapping, either for the whole of a project, or for certain parts of it. + disable_function_wrap and enable_function_wrap provide a way + to do this for specific scopes; another method is to use the --no-fwrap com- + mand-line option, which disables wrapping throughout a project (see Chapter 3 + in the RVS Command Line Tools Reference Guide). + + The disable_function_wrap and enable_function_wrap annota- + tions specify a pattern which matches the name of a called function. The pattern + may include *. Some typical usage scenarios include: + pragma RVS (disable_function_wrap ("pkg.f")); + (calls to pkg.f will not be wrapped) + pragma RVS (disable_function_wrap ("pkg.*")); + (calls to any function in pkg will not be wrapped) + pragma RVS (disable_function_wrap ("*.get")); + (calls to any function named get will not be wrapped) + pragma RVS (enable_function_wrap ("pkg.a")); + + +46 Annotations Reference Guide vWF20190404 +Instrumentation annotations enable/disable_function_wrap + + + (calls to pkg.a can be wrapped) + + The pragma applies to all function calls following the pragma within the current + scope. Multiple instances of the pragma can be used to re-enable and re-disable + function wrapping as required. + +7.6.4 Examples + Example 7.3: Disabling function wrapping + + pragma RVS (disable_function_wrap ("*.a")); + procedure ex1 is + begin + x := f (a (1), a (2)); + end ex1; + + + In Example 7.3, the annotation instructs adains not to wrap any call to function a. + + Example 7.4: Re-enabling function wrapping + + + procedure ex2 is + begin + pragma RVS (disable_function_wrap ("*")); + x := f (a (1), a (2)); + pragma RVS (enable_function_wrap ("*.a")); + y := f (a (3), a (4)); + z := f (b (5), b (6)); + end ex2; + + + In Example 7.4, the first annotation disables all function wrapping, but the second + annotation re-enables function wrapping for calls to function a only. The call to + a(4) can be wrapped. The calls to function b are not wrapped. + + +Annotations Reference Guide vWF20190404 47 +enable/disable_instrumentation Instrumentation annotations + + +7.7 enable/disable_instrumentation +7.7.1 Applies to + RVS + +7.7.2 Synopsis + C/C++ + #pragma RVS disable_instrumentation + #pragma RVS enable_instrumentation + /*##RVS disable_instrumentation */ + /*##RVS enable_instrumentation */ + C++ + //##RVS disable_instrumentation + //##RVS enable_instrumentation + Ada + pragma RVS (disable_instrumentation); + pragma RVS (enable_instrumentation); + + +7.7.3 Description + #pragma RVS disable_instrumentation + + Marks the beginning of a region where instrumentation should not be applied. The + region ends at the corresponding enable_instrumentation annotation: + #pragma RVS enable_instrumentation + + Instrumentation is not, in general, required in sections of code that have a single + execution path. This includes sections of code containing loops and conditional + statements that include only a single execution path. Typical examples include + loops that iterate a fixed number of times, with no data-dependent paths inside + the loop. + + In each case, the section of source code may be enclosed in the + disable_instrumentation and enable_instrumentation annota- + tions. + + Note + + The disable_instrumentation and enable_instrumentation + annotations are static directives that control the instrumenter and are there- + fore not executed dynamically during program execution. + + + Note + + These annotations only suppress instrumentation within the designated re- + gion. If used within a single function, particularly for measuring structural + code coverage, the instrumenter may simply move the ipoints that it would + place so that they occur just before or just after that region. In some cases + this leads to more instrumentation than would normally be added. + + +48 Annotations Reference Guide vWF20190404 +Instrumentation annotations enable/disable_instrumentation + + + In Example 7.5, the annotations instruct cins, cppins or adains not to instrument + the enclosed code: + +7.7.4 Examples + Example 7.5: Stopping and starting instrumentation + + ... + #pragma RVS disable_instrumentation + + for (i=0; i<100; i++) + { + /* copy data */ + buf[i] = message[i]; + } + #pragma RVS enable_instrumentation + ... + + + In Example 7.5, although there is a loop construct with a condition i<100 there is + exactly one path through the code. Instrumentation is therefore not required. Note + that instrumentation would normally be necessary to achieve full coverage. + + The disable_instrumentation and enable_instrumentation an- + notation blocks may not be directly nested however calling sub-routines con- + taining disable_instrumentation and enable_instrumentation + blocks is permissible within a disable_instrumentation and + enable_instrumentation block. + + Warning + + Placing disable_instrumentation and + enable_instrumentation annotations around a return statement + prevents the insertion of an instrumentation point for the function exit. This is + not recommended, as it may prevent RVS from parsing data collected from + program execution in some cases. + + +Annotations Reference Guide vWF20190404 49 +exit_point/exit_function Instrumentation annotations + + +7.8 exit_point/exit_function +7.8.1 Applies to + RVS (except RapiCover map) + +7.8.2 Synopsis + C/C++ + #pragma RVS exit_function("") + #pragma RVS exit_point + /*##RVS exit_function("") */ + /*##RVS exit_point */ + C++ + //##RVS exit_function("") + //##RVS exit_point + Ada + pragma RVS (exit_function("")); + pragma RVS (exit_point); + + +7.8.3 Description + This annotation indicates where exit points can occur in the code. + + When processing data files, timeparser and covparser expect the program to be + executed from the first ipoint of the root function to the last. In some cases, the + execution of the program can be terminated before it reaches the last ipoint of the + root function - for example, if the C exit function or an RTOS terminate_task + function are used. If this is the case, you must specify the different places where + an immediate exit of the root function can be encountered. + + If the early end of execution is caused by a particular function, use the + exit_function ("") annotation. + +7.8.4 Examples + For example, the annotation exit_function ("fatal_error") indicates + that all calls to function fatal_error should be considered as valid exits of the + root function. + + +50 Annotations Reference Guide vWF20190404 +Instrumentation annotations exit_point/exit_function + + + Example 7.6: Exit caused by the fatal_error( ) function + + ... + #pragma RVS exit_function ("fatal_error") + + int + my_fun( int x ) + { + if( x < 100 ) + { + /* fatal error, stop immediately */ + fatal_error( ); + return 0; + } + else + { + return( x % 2 ); + } + } + ... + + + If the early end of execution happens at a particular point in the program, use the + exit_point annotation. + + The exit_point annotation adds an ipoint to the instrumented code and indi- + cates that this point in the code is a valid exit for the program (and the root func- + tion). + + Warning + + This annotation must be placed before the statement that will cause the + program to exit prematurely. + + Example 7.7: Defining an exit point + + ... + int + my_fun( int x, int y ) + { + if( y == 0 ) + { + /* fatal error */ + #pragma RVS exit_point + trap_div_by_zero ( ); + } + + return( x / y ); + } + ... + + +Annotations Reference Guide vWF20190404 51 +ignore_subprogram Instrumentation annotations + + +7.9 ignore_subprogram +7.9.1 Applies to + RapiTime + +7.9.2 Synopsis + C/C++ + #pragma RVS ignore_subprogram("") + /*##RVS ignore_subprogram("") */ + C++ + //##RVS ignore_subprogram("") + Ada + pragma RVS (ignore_subprogram("")); + + +7.9.3 Description + This annotation tells RVS to ignore the specified function during the analysis. + + Some systems make extensive use of small utility functions that are called fre- + quently throughout the execution. Examples of these include watchdog check- + point functions, internal runtime monitor code, critical section entry/exit functions + and status check functions. Often, it is desirable to not instrument these functions + because the overhead of the instrumentation outweighs the time spent in the func- + tion. Additionally, when these functions are called throughout the call tree, their + presence can result in additional functions being instrumented to maintain the + consistency of the instrumentation. + + The use of the ignore_subprogram annotation has the following effects: + • The ignored function is not instrumented. + • The function is not included in the RVS report file, and all calls made to that + function are removed. + • When instrumentation annotations are generated using the xstutils command, + the ignored function is not considered to be part of the call tree. + + +52 Annotations Reference Guide vWF20190404 +Instrumentation annotations instrument + + +7.10 instrument +7.10.1 Applies to + RVS + +7.10.2 Synopsis + C/C++ + #pragma RVS instrument("", ""[, ""]) + /*##RVS instrument("", ""[, ""])*/ + C++ + //##RVS instrument("", ""[, ""]) + Ada + pragma RVS (instrument("", ""[, ""])); + + +7.10.3 Description + The instrument annotation overrides the default instrumentation policy, and + sets the instrumentation profile for individual functions. + + is the profile to use. Profiles are defined in Chapter 6: Profiles. + + Important + + If no profile is specified, the default profile (set by the + default_instrument annotation) is used. + + + Note + + As well as placing instrumentation points as per the specified profile, the + instrumenter will detect any calls to the instrumentation point functions + (RVS_I and RVS_Ipoint) that are already present in the source code, + and will treat these as instrumentation points in the report. + + +Annotations Reference Guide vWF20190404 53 +instrument Instrumentation annotations + + +7.10.4 Examples + Example 7.8: Instrumentation example + + 1: + ... + + 2: + #pragma RVS default_instrument("TRUE", "TIME_FULL") + + 3: + #pragma RVS + instrument("message_handler","TRUE","TIME_FULL-qt") + + 4: + #pragma RVS instrument("crc", "TRUE", + "TIME_FUNCTIONS") + + 5: + ... + + + In the above example, the default_instrument annotation on line 2 en- + sures that full instrumentation is applied by default. The instrument annota- + tion on line 3 specifies that full instrumentation should be applied to the function + message_handler, with the exception of the C ternary conditional operator + '?:' (the q profile modifier) and tight loops (the t profile modifier) which are not + instrumented. The instrument annotation on line 4 specifies that instrumenta- + tion should be added only at the entry and exit of the function crc. + +7.10.5 Instrumenting overloaded C++ methods + If you have overloaded methods in C++ code, the notation shown in Sec- + tion 7.10.2 will cause all overloaded methods to be instrumented. + + To instrument specific methods, you can refer to the line number each method + occurs on, using ones of the following notations: + #pragma RVS instrument(":", ""[, ""]) + /*##RVS instrument(":", ""[, ""])*/ + //##RVS instrument(":", ""[, ""]) + + + Where is the line number on which the method you want to instrument is + declared. + + If multiple instances of the same C++ method are declared on the same line, you + can instrument a specific one by using one of the following notations: + #pragma RVS instrument("::char", ""[, ""]) + /*##RVS instrument("::char", ""[, ""])*/ + + +54 Annotations Reference Guide vWF20190404 +Instrumentation annotations instrument + + //##RVS instrument("::char", ""[, ""]) + + + Where is the starting character number of the declaration for the method + you want to instrument. + +7.10.6 Instrumenting overloaded Ada subprograms + If you have overloaded subprograms in Ada code, the notation shown in Sec- + tion 7.10.2 will cause all overloaded subprograms to be instrumented. + + To instrument specific subprograms, you can refer to the line number each sub- + program occurs on, using the following notation: + pragma RVS (instrument(":", ""[, ""])); + + + Where is the line number on which the subprogram you want to instrument + is declared, or the line number of the subprogram definition if the subprogram + does not have an explicit declaration. + + If multiple instances of the same Ada subprogram are declared on the same line, + you can instrument specific subprograms by using the following notation: + pragma RVS (instrument("::", ""[, + ""])); + + + Where is the starting character number where the subprogram you want + to instrument is declared, or where it is defined, if it does not have an explicit + declaration. + + +Annotations Reference Guide vWF20190404 55 +instrument_inline Instrumentation annotations + + +7.11 instrument_inline +7.11.1 Applies to + RVS (C/C++ only) + +7.11.2 Synopsis + C/C++ + #pragma RVS[ [""] ] instrument_inline("", ""[, + ""]) + /*##RVS[ [""] ] instrument_inline("", ""[, + ""])*/ + C++ + //##RVS[ [""] ] instrument_inline("", ""[, + ""]) + + +7.11.3 Description + The instrument_inline annotation provides support for instrumentation of + inline functions. C and C++ compilers sometimes inline functions that are not + marked for inlining with the inline directive, and may ignore some requests for + inlining. RVS ignores all source-code inlining hints, and instead allows the user + to specify to RVS independently what the compiler will do with the code. The + instrument_inline annotation performs the following: + • The function is considered by RVS to be inlined by the compiler. + • The function is treated as a block within each calling function rather + than as a separate function. The effect of its different execution paths will still + be taken into account, but it will not be reported as a separate function. + • The function is instrumented according to and the provided + . + + Note + + When specifying a function name for this annotation both static and global + names can be used. A global function name will cause all inline functions + corresponding to that name (whether they are declared static or not) to be + instrumented whereas a static function name will only instrument the static + inline functions corresponding exactly to that name (i.e. in only one file). For + more information on naming of static functions in the RVS analysis process, + refer to Section 4.4.1 in the RVS Command Line Tools Reference Guide. + + +56 Annotations Reference Guide vWF20190404 +Instrumentation annotations instrument_inline + + +7.11.4 Examples + Example 7.9: Enabling instrumentation + + ... + #pragma RVS default_instrument ("TRUE", "TIME_FULL") + #pragma RVS instrument("one", "FALSE") + #pragma RVS instrument ("two","TRUE", "TIME_FUNCTIONS") + #pragma RVS instrument_inline ("three","TRUE") + #pragma RVS instrument_inline + ("fileone:three","TRUE","TIME_FUNCTIONS") + #pragma RVS [five@P3] instrument_inline ("four","TRUE", + "TIME_START_OF_SCOPES") + ... + + + The annotations in Example 7.9 instruct cins or cppins to: + • Instrument all functions with the default profile, except for functions one and + two. In this case, do not instrument function one at all, and only instrument + function two at its beginning and end. + • Instrument and inline function three in all files (including functions belonging + to header files) except in file fileone where the static inline function three + will only be instrumented at its beginning and end. + • Instrument and inline function four only at the third conditional path of func- + tion five. + + Note + + Normally, instrumentation does not take place inside .h files unless cins + or cppins is called with the --instrument-h option. However, inline + functions are often defined in header files, so instrument_inline will + cause the instrumentation of a function even if that function is in a .h file. + + +Annotations Reference Guide vWF20190404 57 +instrumentation_point Instrumentation annotations + + +7.12 instrumentation_point +7.12.1 Applies to + RVS + +7.12.2 Synopsis + C/C++ + #pragma RVS instrumentation_point + /*##RVS instrumentation_point */ + C++ + //##RVS instrumentation_point + Ada + pragma RVS (instrumentation_point); + + +7.12.3 Description + The instrumentation_point annotation can be manually added to the + source code as follows: + ... + #pragma RVS instrumentation_point + ... + + + This is a local annotation that acts as a request to cins, cppins or adains + to add an instrumentation point at that location. If instrumentation is dis- + abled at that point, due to a default_instrument, instrument or + disable_instrumentation annotation, then the instrumenter will not add + an instrumentation point; the request will be ignored. This makes it possible to turn + instrumentation on and off without the need to modify any source code containing + manually placed instrumentation_point annotations. + + Together with the instrumentation profiles, instrumentation_point annota- + tions can be used to obtain a fine degree of control over instrumentation. + + Note + + When the instrumenter is configured to use non-unique ipoint IDs, instru- + mentation points inserted as a result of instrumentation_point an- + notations will always be assigned IDs in the master ipoint ID range, i.e. each + ipoint will always have a unique ID. In situations where the ID range is con- + strained, the use of instrumentation_point annotations may cause + the ipoint ID range to overflow. + + +58 Annotations Reference Guide vWF20190404 +Instrumentation annotations instrumentation_point + + + Note + + The instrumentation_point annotation causes the instrumenter to insert an + instrumentation point into the source code. Additionally, the instrumenter + will detect any calls to the instrumentation point functions (RVS_I and + RVS_Ipoint) that are already present in the source code, and will treat + these as instrumentation points in the report. + + + Important + + The instrumentation_point annotation must be considered as a + statement and so can only be placed in the code where a statement is per- + mitted. This means that it cannot be placed outside of function definitions or + within declarations. + + +7.12.4 Examples + + Example 7.10: Manual instrumentation example + + ... + #pragma RVS default_instrument("TRUE", "TIME_FULL") + #pragma RVS instrument("funA", "TRUE", "TIME_FUNCTIONS") + #pragma RVS instrument("funB", "TRUE", "MANUAL") + #pragma RVS instrument("funC", "FALSE") + ... + int funA( void ) + { + int x; + #pragma RVS instrumentation_point /* added */ + x = get_1(); + x += get_2(); + return x; + } + int funB( void ) + { + int y = funA(); + #pragma RVS instrumentation_point /* added */ + y += get_3(); + return y; + } + int funC( int k ) + { + int c = funB(); + #pragma RVS instrumentation_point /* not added */ + c *= k; + return c; + } + ... + + + In Example 7.10, instrumentation_point annotations placed in functions + funA and funB will result in instrumentation points being added to the code by + cins, cppins or adains, while those in funC will not. The MANUAL instrumenta- + + +Annotations Reference Guide vWF20190404 59 +instrumentation_point Instrumentation annotations + + tion profile allows manual instrumentation points to be added to the code while + avoiding any automatic instrumentation. + + The second line of the example illustrates a common combination of manual + and automatic instrumentation. Here, automatic instrumentation is used to place + instrumentation points at the beginning and end of the function funA while + instrumentation_point annotations can be used to mark key mutually ex- + clusive paths through the function. + + +60 Annotations Reference Guide vWF20190404 +Instrumentation annotations start_root/end_root + + +7.13 start_root/end_root +7.13.1 Applies to + RVS (except RapiCover map) + +7.13.2 Synopsis + C/C++ + #pragma RVS start_root + #pragma RVS end_root + /*##RVS start_root */ + /*##RVS end_root */ + C++ + //##RVS start_root + //##RVS end_root + Ada + pragma RVS (start_root); + pragma RVS (end_root); + + +7.13.3 Description + The start_root and end_root annotations can be manually added to the + source code. + + This is a local annotation that acts as a request to cins, cppins or adains to + add an instrumentation point with a unique id at that location. If instrumentation + is disabled at that point, due to a default_instrument, instrument or + disable_instrumentation annotation, then the instrumenter will not add + an instrumentation point; the request will be ignored. This makes it possible to turn + instrumentation on and off without the need to modify any source code containing + manually placed start_root/end_root annotations. + + Important + + The start_root and end_root annotations must be used in pairs to + define a potential root for the analysis. The pair must be placed in a se- + quence and be located in the same function. + + + Once added to the code, the root of the analysis can be defined to be the se- + quence of code between the start_root and end_root annotations by using + the @R notation for specifying the root (see Section 21.3.40 in the RVS Command + Line Tools Reference Guide). + + +Annotations Reference Guide vWF20190404 61 +start_root/end_root Instrumentation annotations + + +7.13.4 Example + Example 7.11: Start_root/end_root annotations + + ... + + int + my_task( int normal_mode ) + { + if( normal_mode ) { + while (do_continue) { + get_data (); + #pragma RVS start_root + filter_data (); + process_data_normal (); + merge_data (); + #pragma RVS end_root + write_data (); + } + } else { + while (do_continue) { + get_data (); + #pragma RVS start_root + filter_data_fast (); + process_data_fast (); + replace_data (); + #pragma RVS end_root + write_data (); + } + } + } + ... + + + The example Example 7.11 defines two potential roots for the analysis within the + function my_task: my_task@R1 and my_task@R2. + + Important + + These annotations can only be placed in the code where a statement is per- + mitted. It must be considered as a statement. This means that it cannot be + placed outside of function definitions or within declarations. + + +62 Annotations Reference Guide vWF20190404 +Instrumentation annotations uncertain_return + + +7.14 uncertain_return +7.14.1 Applies to + RapiCover + +7.14.2 Synopsis + C/C++ + #pragma RVS uncertain_return ("") + /*##RVS uncertain_return ("") */ + C++ + //##RVS uncertain_return ("") + Ada + pragma RVS (uncertain_return ("")); + + +7.14.3 Description + The uncertain_return is an instrumentation annotation that acts as a request + to cins, cppins or adains to add an instrumentation point before each call to a + particular function. + + If instrumentation is disabled at that point, due to a default_instrument, + instrument or disable_instrumentation annotation, then the instru- + menter will not add an instrumentation point. + + This is required when performing statement coverage on source code that con- + tains calls to a function that may or may not return. If a call to a function does not + return, an ipoint before that call is required to ensure that statement coverage is + recorded correctly up to the non-returning call. + +7.14.4 Example + + Example 7.12: uncertain_return annotation + + ... + + #pragma RVS uncertain_return ("task_end"); + + int + my_task( int normal_mode ) + { + while (do_continue) { + get_data (); + filter_data (); + process_data_normal (); + merge_data (); + } + write_data (); + task_end(); + } + ... + + +Annotations Reference Guide vWF20190404 63 +uncertain_return Instrumentation annotations + + The example Example 7.12 shows a call to task_end that will not return. The + uncertain_return annotation indicates that, in order to obtain coverage of + the statements preceding the call, an extra ipoint is required before the call. + + +64 Annotations Reference Guide vWF20190404 +8 Analysis annotations + The annotations provided in this section work with RapiTime to increase the ac- + curacy of the WCET estimate that RapiTime reports and with RapiCover to allow + the coverage analysis of complex software. The purpose of the annotations is to + inform the analysis about constraints on the code that cannot be inferred simply + by inspecting the code (for example, this function pointer can point to these func- + tions). + + The following table gives an overview of the available analysis annotations: + + Annotation Description Product Scope + call_to Specify the destination of a RVS Local + particular call through a func- + tion pointer, member func- + tion pointer or function access + type. + default_call_to Specify the destination of sub- RVS Global + sequent calls through a func- + tion pointer, member func- + tion pointer or function access + type. + call_through_to Specify the destination for a RVS Local + call through a dispatching + function with a single call site. + cor_include_calls Set whether calls to a specific RapiTime Global + analyzed function from outside + the analysis root should be in- + cluded in execution-time analy- + sis. + default_cor_ Set whether calls to analyzed RapiTime Global + include_calls functions from outside the + analysis root should be includ- + ed in execution-time analysis. + cor_include_this_call Set whether the preceding RapiTime Local + call to an analyzed function + from outside the analysis root + should be included in execu- + tion-time analysis. + disable_inherited_ Prevent justifications for an ele- RapiCover Global + justifications ment from applying to its sub- + elements. + default_expand_calls Control whether calls to func- RapiTime Global + tions from different places in + + +Annotations Reference Guide vWF20190404 65 + Analysis annotations + + + Annotation Description Product Scope + the call tree (contexts) are con- + sidered together or separately. + expand_calls Control whether calls to a spe- RapiTime Global + cific function from different + places in the call tree (con- + texts) are considered together + or separately. + expand_this_call Control whether to consider RapiTime Local + the preceding call to a particu- + lar function separately. + ignore_path Exclude a path from WCET RapiTime Local + analysis. + justification Specify justification for non- RapiCover Local + covered items. + loop_max_iter Provide a maximum bound on RapiTime Local + the number of executions of a + loop for WCET analysis. + max_wpaths Specify a upper limit on the RapiTime Global + number of execution paths to + be considered simultaneously + during analysis. + no_fold path_id annotations within RapiTime Global + the specified function are prop- + agated to the caller. + overall_wcet_calls Provide precomputed WCET RapiTime Global + values for specific functions. + overall_wcet_this_ Provide precomputed WCET RapiTime Local + call values for a call to a specific + function (a specific context). + path_id Label a specific program path RapiTime Global + for reference by other annota- + tions. + recursive Indicate that a function directly RVS Global + calls itself. + tag Label a specific source code RVS Local + location for reference by other + annotations. + default_unroll_loops Specify how many different it- RapiTime Global + erations of loops to analyze + separately. + unroll_this_loop Specify how many different it- RapiTime Local + erations of a particular loop to + analyze separately. + + +66 Annotations Reference Guide vWF20190404 +Analysis annotations + + + Annotation Description Product Scope + wfreq Set a specific local worst-case RapiTime Local + frequency for a conditional + block in an enclosing loop. + wp_*, lwp_* Specify infeasible execution RapiTime Global + paths. (wp_ + form), + Local + (lwp_ + form) + wpath, lwpath Specify infeasible execution RapiTime Global + paths. (wpath + form), + Local + (lw- + path + form) + + +Annotations Reference Guide vWF20190404 67 +call_to and default_call_to Analysis annotations + + +8.1 call_to and default_call_to +8.1.1 Applies to + RVS (except RapiCover map) + +8.1.2 Synopsis + C/C++ + #pragma RVS default_call_to("", "" [,""]+) + #pragma RVS [ [""] ] call_to("", "" [,""]+) + /*##RVS default_call_to("", "" [,""]+) */ + /*##RVS [ [""] ] call_to("", "") */ + C++ + //##RVS default_call_to("", "" [,""]+) + //##RVS [ [""] ] call_to("", "" [,""]+) + Ada + pragma RVS (default_call_to("", "" [,""]+)); + pragma RVS ([ "", ] call_to("", "" [,""]+)); + + +8.1.3 Description + This analysis annotation specifies the destination(s) of calls made through function + pointers and dynamic calls (indirect calls). + + call_to annotations augment the call tree structure, which guides the parsing + of data collected from program execution. The file containing the annotations must + be processed with cins to create an xsc file. This xsc file is then supplied to + xstutils along with the other xsc files during report generation. + + The default_call_to form (referred to as the global annotation) defines the + destination for any calls made through the specified function pointer in + any subsequent lines of code. + + The call_to form (referred to as the local annotation) specifies only the call + made through the variable immediately preceding the annotation (or + tag). This means you must either place this annotation on the line immediately after + the call through the function pointer, or you must refer to a tag which references + the line after the call. must be the string representing the expression + used as the function name in the call. In Ada, this includes any use of .all in + the expression, but does not need any additional qualification beyond the actual + expression in the source code. For example, note that the expression in the code + sample below is p.all and not calls.p.all: + ... + pragma RVS( default_call_to( "p.all", "calls.example" ) ); + procedure calls is + type ap is access procedure; + procedure example is + begin + ... + end example; + + +68 Annotations Reference Guide vWF20190404 +Analysis annotations call_to and default_call_to + + p: ap := example'Access; + begin + p.all; + end calls; + ... + + + Note + + The instrumenter (cins, cppins or adains) outputs a warning if you omit a + call_to or default_call_to annotation. For example: + Warning: Call through function pointer found. + You should use annotation 'call_to' or 'default_call_to' such as the + following: + RVS default_call_to ("(*fptr)", "destination"); /* 0 */ + Indirect call locations: + call_to_warning.c:18 ( 0 ) + + + You can annotate a function pointer that has multiple targets using a comma-sep- + arated list of function names. For example, to indicate that a call through afp[i] + may result in a call to afun, bfun, or cfun: + + #pragma RVS call_to ("afp[i]", "afun" ,"bfun", "cfun"); + + The use of "*" in a call_to annotation indicates that the set of supplied des- + tinations is incomplete and that there may be other destination functions that will + be identified when data collected from program execution is parsed. + + #pragma RVS call_to ("afp[i]", "afun" ,"bfun", "*"); + + If the "*" parameter is given, any other destinations not listed will be resolved + automatically when data collected from program execution is parsed. Without "*" + the list of supplied destinations is considered to be complete and an error will be + raised if the indirect call reaches a non-listed destination. + + With multiple function pointers which are referenced on the same line, supply mul- + tiple annotations for that line. In the following example, both f and g are resolved + correctly: + ... + f = aFunction; + g = anotherFunction; + x = f( x ) - g( x ); + #pragma RVS call_to( "f", "aFunction") + #pragma RVS call_to( "g", "anotherFunction") + ... + + + Multiple annotations for each function pointer on a line are always required, even + if they point to the same function. For example: + ... + f = aFunction; + x = f( x ) - f( x ); + #pragma RVS call_to( "f", "aFunction") + + +Annotations Reference Guide vWF20190404 69 +call_to and default_call_to Analysis annotations + + #pragma RVS call_to( "f", "aFunction") + ... + + + Note + + If you supply too few call_to annotations, this will be reported as an un- + resolved function pointer, even if the same function pointer is involved each + time. + + + Important + + Take care when you provide annotations for calls through function pointers + made in different ways, since these will be treated separately. + + For example: given an array of function pointers fp[3]; calls to fp[i], + and fp[j] are treated as distinct (where i and j are indices into the ar- + ray). + + In this case you need both of the following: + ... + #pragma RVS default_call_to ("fp[i]","afun","bfun","cfun") + #pragma RVS default_call_to ("fp[j]","afun","bfun","cfun") + ... + + + Important + + You can combine local annotations that are applied to functions (such as + expand_this_call) with function pointer annotations. For example: + ... + f = aFunction; + y = f( x ); + #pragma RVS call_to( "f", "aFunction") + #pragma RVS expand_this_call( "aFunction", "TRUE" ) + ... + + + tells RVS to expand the call made to aFunction through the function + pointer f. + + +70 Annotations Reference Guide vWF20190404 +Analysis annotations call_to and default_call_to + + +8.1.4 Examples + + Example 8.1: call_to annotation + + 1: ... + 2: int afun (int); + 3: int bfun (int); + 4: void + 5: test(void) + 6: { + 7: int (* funp)(int); + 8: funp = afun; + 9: + 10: funp(7); + 11: #pragma RVS call_to ("funp","afun") + 12: + 13: grp->afp[3] = bfun; + 14: grp->afp[3](0); + 15: #pragma RVS call_to ("grp->afp[3]","bfun") + 16: } + 17: ... + + + In the above example, funp is a pointer to a function that takes an int as a + parameter and returns an int. On line 8, funp is set to point to the function + afun. On line 10, a call to afun is made through the function pointer funp.The + annotation on line 11 tells RVS to treat the call through funp on the previous line + as a call to the function afun. + + RVS can handle complex expressions that evaluate to function pointers. For ex- + ample, on line 14, grp->afp[3] is a pointer to the function bfun. This is spec- + ified in the annotation on line 15. + + Example 8.2: default_call_to annotation + + 1: ... + 2: #pragma RVS default_call_to ("funp","fun") + 3: + 4: void (*funp)(void); /* define the function pointer */ + 5: void fun(void); /* externally defined function */ + 6: + 7: int + 8: main(void) + 9: { + 10: funp = &fun; + 11: funp(); + 12: return 0; + 13: } + 14: ... + + +Annotations Reference Guide vWF20190404 71 +call_to and default_call_to Analysis annotations + + In Example 8.2, funp is a function pointer which points to the function fun. The + annotation on line 2 states that a call through funp results in a call to fun. The + call itself (in main) does not require any further annotation. + +8.1.5 Automatic discovery of indirect call destinations + If timeparser or covparser encounters an indirect call for which there is no an- + notation (or where the annotation contains the special destination "*") but there + is sufficient instrumentation to discover the destination of the call automatically, + it will then resolve the call automatically. This creates an annotation in the file + rvs_autores_fptr.txt which should be reviewed and transferred to the + analysis annotation file. If there is not enough instrumentation to be able to resolve + the call automatically, an error is reported instead. + + The --discover-fptr option to the instrumenter ensures that there is suffi- + cient instrumentation in the source code to be able to perform automatic resolution + on RVS traces (providing that all possible destinations are instrumented). It is not + possible to resolve indirect calls automatically when a coverage map or LiveMap + is used. + + Important + + For indirect calls to be resolved correctly, it is necessary for all possible in- + direct call destinations to be instrumented. If an indirect call destination is + uninstrumented, it will not appear in data collected from program execution + and it will not be possible to identify that destination correctly. + + If the call tree of an uninstrumented destination contains instrumented code, + the first instrumented function seen in the data collected from program exe- + cution will be identified as the destination of the indirect call. + + The incorrect identification of indirect call destinations is a common cause + of "unexpected ipoint" errors during processing of data collected from pro- + gram execution. You should manually review all automatically-resolved indi- + rect call destinations to ensure that the destinations are correct. + + + Note + + It is not possible to use automatic discovery of indirect calls in conjunction + with the IdPack feature, as unique instrumentation is required on all indirect + call destinations in order to identify the destination. + + Debugging unresolved indirect call destinations is significantly more difficult + when an integration uses IdPack. It is strongly recommended that you re- + solve all indirect call destinations and provide appropriate annotations be- + fore enabling IdPack. + + +72 Annotations Reference Guide vWF20190404 +Analysis annotations call_through_to + + +8.2 call_through_to +8.2.1 Applies to + RVS (except RapiCover map) + +8.2.2 Synopsis + C/C++ + #pragma RVS [ [""] ] call_through_to("", "") + /*##RVS [ [""] ] call_through_to("", "") */ + C++ + //##RVS [ [""] ] call_through_to("", "") + Ada + pragma RVS ([ "", ] call_through_to("", "")); + + +8.2.3 Description + call_through_to may be used whenever a function is called via another func- + tion. For analysis purposes, the effect of the annotation is the replacement of the + first call () with the second (). + + This analysis annotation may be used if a dispatching function invokes functions + indirectly. Dispatching functions link different modules together in a dynamic or + semi-dynamic fashion, calling a destination function on behalf of the caller. + + Function may or may not be instrumented. If it is not instrumented, it is + treated as a black box. + +8.2.4 Examples + A well-known example of a dispatching function is a "system call". + + Consider an embedded system containing an operating system kernel, an appli- + cation, and one or more device drivers. As part of normal operation, the applica- + tion will access hardware devices via the drivers. In some cases, it may be possi- + ble to use a direct function call: + video_driver_write ("Hello"); + + However, this approach forces a very tight binding between video_driver + and the application; neither component can be updated independently. This is + a problem if the kernel may have more than one application or more than one + video_driver, alternatively if different development teams are working on the + two components. Even in an embedded environment, with only one application + and only one video_driver, the direct approach does not scale well. + + Therefore, a dispatching table is used to separate the components. The applica- + tion performs a "system call" via the kernel: + void output (void * value) { + syscall (WRITE_TO_SCREEN, value); + + +Annotations Reference Guide vWF20190404 73 +call_through_to Analysis annotations + + } + + WRITE_TO_SCREEN is a constant value, defined as part of the API for the kernel. + The kernel implements syscall using a dispatch table: + void syscall (unsigned index, void * arg) { + _syscalls[index](arg); + } + + In this example, _syscalls[WRITE_TO_SCREEN] is equal to + video_driver_write. + + RVS tools support indirect function calls using call_to (see Section 8.1). This + is not suitable for a dispatching function because all of the calls are dispatched + through a single place, i.e.: + _syscalls[index](arg); + + A single call_to annotation for this location would not be useful because it + would list all possible destinations, not just video_driver_write. + + Dispatching functions should be handled by using the call_through_to an- + notation to specify a link between the system call (syscall) and the destination + (video_driver_write). In this example, the annotation is used as follows: + #pragma RVS [output@C1] call_through_to ("syscall", + "video_driver_write"); + void output (void * value) { + syscall (WRITE_TO_SCREEN, value); + } + + During analysis, RVS treats the call to syscall as a call to + video_driver_write. This allows the application and video_driver to + be analyzed at the same time by RVS. + + Note + + call_through_to annotations may be generated automatically by the + rvdutils tool: see Section 11.3.3 in the RVS Command Line Tools Reference + Guide. For this example, the command + rvdutils --call-through-to-out a.txt --call-through-to-func syscall + --call-through-to-arg 1 + + will produce an annotations file named a.txt containing + #pragma RVS [output@C1] call_through_to ("syscall", + "WRITE_TO_SCREEN"); + + This file would be manually edited to replace "WRITE_TO_SCREEN" with + the true name of the destination function, i.e. "video_driver_write". + + +74 Annotations Reference Guide vWF20190404 + cor_include_calls, default_cor_include_calls, +Analysis annotations + cor_include_this_call + +8.3 cor_include_calls, default_cor_include_calls, + cor_include_this_call +8.3.1 Applies to + RapiTime + +8.3.2 Synopsis + C/C++ + #pragma RVS default_cor_include_calls("") + #pragma RVS cor_include_calls("", "") + #pragma RVS [ [""] ] cor_include_this_call("", "") + /*##RVS default_cor_include_calls("") */ + /*##RVS cor_include_calls("", "") */ + /*##RVS [ [""] ] cor_include_this_call("", "") */ + C++ + //##RVS default_cor_include_calls("")) + //##RVS cor_include_calls("", "") + //##RVS [ [""] ] cor_include_this_call("", "") + Ada + pragma RVS (default_cor_include_calls("")); + pragma RVS (cor_include_calls("", "")); + pragma RVS ([ "", ] cor_include_this_call("", "")); + + +8.3.3 Description + This annotation is used for controlling "calls outside root" (abbreviated to cor). It is + useful in cases where the analysis scope (see Section 21.3.4 in the RVS Command + Line Tools Reference Guide) is different to the root function. + + The default behavior of RapiTime is to set the analysis scope to be the same as + the root function. You can change the analysis scope to be a different function to + the root function by using the --analysis-scope option to xstutils. + + The root function should be a function that is called from somewhere within the call- + tree of the analysis scope function. Setting the analysis scope to be different to the + root function allows RapiTime to use timing information measured from invocations + of functions made from outside of the root function call tree. + + By default, the analysis determines the WCET of a function by combining the data + collected during program execution from all calls to a function made within the + analysis scope. This calculation includes calls to the function that are made both + from inside and outside the call tree of the root function under analysis. + + However, sometimes function calls outside of the root function call tree may lead + to WCETs that are not possible when the same function is called from within the + call tree of the root function. In this case, you can use cor_include_calls + annotations to exclude calls outside of the root function from the analysis, so that + they do not contribute to the WCET calculations. + + In the example below, the analysis scope has been set to main, and the root + function has been set to root. The call to afun on line 5 is outside of the call + + +Annotations Reference Guide vWF20190404 75 +cor_include_calls, default_cor_include_calls, + Analysis annotations +cor_include_this_call + tree of the root function and could be excluded from the WCET analysis, while the + call to the same function on line 14 should be included. + + + Example 8.3: Calls outside root + + 1: ... + 2: int + 3: main(void) + 4: { + 5: afun(0); /* context 1 */ + 6: root(); + 7: + 8: return 0; + 9: } + 10: + 11: void + 12: root(void) + 13: { + 14: afun(1); /* context 2 */ + 15: bfun(); + 16: } + 17: ... + + + RapiTime provides three annotations that specify whether sub-function calls made + outside of the root function call tree are included or excluded from the analysis: + • default_cor_include_calls(""); + Set this global annotation to TRUE to instruct RapiTime to use trace data from + all the functions called from within the root function call tree, including calls to + those same functions made from outside of the root function call tree. Set the + annotation to FALSE to instruct RapiTime to include only trace data belonging + to function calls made from within the root function call tree and within the + analysis scope. + • cor_include_calls("", ""); + Set this global annotation to TRUE to instruct RapiTime to include all calls to + the specified function from within the analysis scope. This annotation overrides + any more general inclusion. + • cor_include_this_call("", ""); + Set this local annotation to TRUE to instruct RapiTime to include the specific + call to a function preceding the annotation. + + Note + + RapiTime gives a warning if a call outside root annotation is applied to a + specific function call that is made within the call tree of the root function. + + +76 Annotations Reference Guide vWF20190404 + cor_include_calls, default_cor_include_calls, +Analysis annotations + cor_include_this_call + Note + + If you use a tag reference for a cor_include_this_call annotation, it + must be a reference to a call as opposed to a loop or a path. + + +8.3.4 Examples + Example 8.4: Calls outside root annotations + + 1: ... + 2: #pragma RVS default_cor_include_calls("FALSE") + 3: #pragma RVS cor_include_calls("afun","TRUE") + 4: int + 5: main(void) + 6: { + 7: afun(); /* excluded */ + 8: #pragma RVS cor_include_this_call("afun","FALSE") + 9: afun(); /* included */ + 10: bfun(); /* excluded */ + 11: bfun(); /* included */ + 12: #pragma RVS cor_include_this_call("bfun","TRUE") + 13: root(); + 14: + 15: return 0; + 16: } + 17: + 18: void + 19: root(void) + 20: { + 21: afun(); /* included */ + 22: bfun(); /* included */ + 23: } + 24: ... + + + The example above illustrates how you can use the call outside root annotations. + The root function under analysis is root. The annotations control which calls to + the functions afun and bfun contribute timing information that is included in the + analysis. + + The annotation on line 2 effectively changes the overall default so that only function + calls made from the call tree of root are included in the analysis. This default + is then overridden by the annotation on line 3, which specifies that all calls to + afun should be included in the analysis. This second global annotation is itself + overridden by the local annotation on line 8, which excludes the preceding call to + afun on line 7 from the analysis. + + The call to bfun on line 10 is excluded from analysis but the subsequent call on + line 11 is included due to the local annotation on line 12. + + +Annotations Reference Guide vWF20190404 77 +cor_include_calls, default_cor_include_calls, + Analysis annotations +cor_include_this_call + Important + + If you exclude calls outside of the call tree of the root function from the + analysis you may place a heavier burden on testing. Your test strategy must + ensure that all feasible sub-paths in the function are exercised by calls + from within the root function. Often, it is easier to use a simple test harness + to exercise a given sub-function and to include the trace data generated + from the calls within the test harness (but outside of the root function) in the + analysis. + + + Note + + RapiTime generates an error message if there are conflicts in the set + of Call Outside Root annotations used, for example if you use two + default_cor_include_calls annotations with the parameters TRUE + and FALSE. + + +78 Annotations Reference Guide vWF20190404 +Analysis annotations disable_inherited_justifications + + +8.4 disable_inherited_justifications +8.4.1 Applies to + RapiCover + +8.4.2 Synopsis + C/C++ + #pragma RVS disable_inherited_justifications + /*##RVS disable_inherited_justifications */ + C++ + //##RVS disable_inherited_justifications + Ada + pragma RVS (disable_inherited_justifications); + + +8.4.3 Description + This annotation controls whether justifications from parent elements should be + inherited by the child elements. + + For example, by default when a branch is justified via a justification annotation all + the statements, calls, branches, etc. within this branch are also justified by the + same justification annotation. + + This annotation disable this default behavior so that each element must be justified + individually. + + +Annotations Reference Guide vWF20190404 79 +expand_calls, default_expand_calls, + Analysis annotations +expand_this_call + +8.5 expand_calls, default_expand_calls, + expand_this_call +8.5.1 Applies to + RapiTime + +8.5.2 Synopsis + C/C++ + #pragma RVS default_expand_calls("") + #pragma RVS expand_calls("", "") + #pragma RVS [ [""] ] expand_this_call("", "") + /*##RVS default_expand_calls("") */ + /*##RVS expand_calls("", "") */ + /*##RVS [ [""] ] expand_this_call("", "") */ + C++ + //##RVS default_expand_calls("")) + //##RVS expand_calls("", "") + //##RVS [ [""] ] expand_this_call("", "") + Ada + pragma RVS (default_expand_calls("")); + pragma RVS (expand_calls("", "")); + pragma RVS ([ "", ] expand_this_call("", "")); + + +8.5.3 Description + This annotation controls whether the different contexts (places within the call tree + that a function is called from) of a sub-function are considered separately or + merged with other contexts when performing the timing analysis. Consider the fol- + lowing example: + + +80 Annotations Reference Guide vWF20190404 + expand_calls, default_expand_calls, +Analysis annotations + expand_this_call + Example 8.5: Context dependent execution times (1) + + ... + void + three_paths(int x) + { + switch (x) + { + case 0: + /* code for case 0 */ + break; + case 1: + /* code for case 1 */ + break; + default: + /* code for default */ + break; + } + } + + void + test(void) + { + three_paths(0); + three_paths(1); + three_paths(2); + } + ... + + + In this example the function three_paths has three distinct execution + paths. When the function test calls three_paths, the execution time of + three_paths depends upon the value of the parameter it is passed. Each call- + ing context passes a different parameter value to three_paths, resulting in con- + text dependent WCETs. By default, these three contexts are unified. This means + that RapiTime will consider that they have the same execution time. However, only + one of the three paths takes the overall WCET. The calculated WCET for test will + be pessimistic if it includes the overall WCET of three_paths three times. + + RapiTime provides three annotations to improve the analysis with respect to calling + context dependencies: + • default_expand_calls(""); + Set this global annotation to TRUE to instruct RapiTime to consider the context + in which every function is called separately. Set the parameter to FALSE to + instruct RapiTime to combine the timing information for each function from all + the contexts in which it is called. Hence each function analyzed has a single + computed ETP and WCET. The default is FALSE. + • expand_calls("", ""); + Set this global annotation to TRUE to instruct RapiTime to consider the context + in which a specific function is called separately. The default is FALSE. + • expand_this_call("", ""); + Set this local annotation to TRUE to instruct RapiTime to consider the context + of a specific call to a function separately. The context is identified by the call + to the specified function preceding the annotation. Also note that this anno- + + +Annotations Reference Guide vWF20190404 81 +expand_calls, default_expand_calls, + Analysis annotations +expand_this_call + tation overrides any more general annotation specifying function expansion. + The default is FALSE. + + Note + + For the expand_this_call annotation, if you use a tag reference, it + must be a reference to a call as opposed to a loop or a path. + + +8.5.4 Examples + Example 8.6: Context dependent execution times (2) + + 1: ... + 2: #pragma RVS default_expand_calls("FALSE") + 3: #pragma RVS expand_calls("afun","TRUE") + 4: + 5: void + 6: root(int x, int y) + 7: { + 8: afun(1); /* context dependent wcet*/ + 9: afun(2); /* context dependent wcet */ + 10: bfun(x); /* unified wcet */ + 11: bfun(y); /* unified wcet */ + 12: bfun(0); /* context dependent wcet */ + 13: #pragma RVS expand_this_call("bfun","TRUE") + 14: } + 15: ... + + + Example 8.6 illustrates the expansion of calling contexts. The annotation on line 2 + configures the analysis to unify the calling contexts of all functions. Note that this + is the default and could be omitted. The annotation on line 3 overrides the default + for the function afun. + + The analysis of each context in which this function is called is treated separately, + resulting in execution time profiles and WCET information for the function when it + is called from lines 8 and 9. Calls to the function bfun are unified by the analysis, + with the exception of the call on line 12, which is treated separately due to the + specific annotation on line 13. + + This means that timing information from calls to bfun with parameters x and y are + combined into a single ETP and WCET. A further ETP and WCET is provided for + the "context dependent" call to bfun made on line 12. + + +82 Annotations Reference Guide vWF20190404 + expand_calls, default_expand_calls, +Analysis annotations + expand_this_call + Important + + Expanding the analysis of a function into separate calling contexts may + place an additional burden on testing. To avoid optimistic WCET calcula- + tions when using expanded calls, you should ensure that the testing strat- + egy exercises every feasible sub-path through the function in each of its + calling contexts. Typically this means that more test cases are needed than + when analysis of the function is unified. + + +Annotations Reference Guide vWF20190404 83 +ignore_path Analysis annotations + + +8.6 ignore_path +8.6.1 Applies to + RapiTime + +8.6.2 Synopsis + C/C++ + #pragma RVS ignore_path; + #pragma RVS ignore_path ("path_id"); + /*##RVS ignore_path */ + C++ + //##RVS ignore_path + //##RVS ignore_path ("path_id") + Ada + pragma RVS (ignore_path); + pragma RVS (ignore_path ("path_id")); + + +8.6.3 Description + Use the local annotation ignore_path to instruct the RVS tools to ignore specif- + ic paths through the code when processing execution time data. Situations where + this is useful include: + 1. Code that forms part of a special mode of operation that does not need to + execute within a defined execution time budget, for example a programming + or diagnostic mode. + 2. Code that is present to reset the system in exceptional circumstances. If ex- + ecuted, this code will reset the processor, restarting the system. Its execution + time is not relevant to normal operation. + 3. Code that supports functionality that is not required in the deployed system. + For example code to support long message identifiers in a system that only + uses short identifiers. + + Note + + Without any parameters, ignore_path ignores at the location of the an- + notation. With a ("path_id") parameter, the given path ID is ignored in- + stead. See Section 8.12 for the annotation to declare a path ID for a particu- + lar location in the source code. + + + You can also use the ignore_path annotation to mark a point in the code that + cannot be on the worst-case path. RapiTime's analysis of the code structure rec- + ognizes that all the other lines of code in the same block as the ignore_path + annotation cannot be on the worst-case path either. Hence the ignore_path + annotation effectively spreads out to define a block of code that you want to ignore + during timing analysis. + + +84 Annotations Reference Guide vWF20190404 +Analysis annotations ignore_path + + It is essential that you correctly place ignore_path annotations so that you + only exclude regions of code that can be safely ignored. Otherwise the WCETs + computed by RapiTime may be optimistic and therefore potentially incorrect. + + Note + + When you use the ignore_path annotation, you prevent RapiTime from + processing any timing data for the associated block. This includes min, + max, average, high-water mark, WCET and end-to-end runs. The fact that + the block has been exercised and the number of tests for the block will still + be recorded. + + + Important + + You must be careful when using the ignore_path annotation. We recom- + mended that you carefully examine the source code browser in the RVS re- + port viewer with WCET and HWM highlighted so that you can see exactly + which lines of code are being ignored. Placing the ignore_path anno- + tation outside of an if or other decision statement (such as while, for, + switch, etc.) can have unexpected consequences because the ignored + region extends back up the call hierarchy until a decision point is found. + This can mean that the ignored region extends into a number of higher-level + functions. + + +8.6.4 Examples + Example 8.7: ignore_path annotation + + ... + void + set_XY(int x, int y) + { + if(x > 100) + { + /* This is ASL @P1 */ + value = x + y - 1; + } + + if (x != 0) + { + bits_set += x & 0x01; + x >>= 1; + #pragma RVS path_id ("if01") + } + done = true; + } + ... + #pragma RVS ignore_path ("if01"); + #pragma RVS [set_XY@P1] path_id ("pathX"); + #pragma RVS ignore_path ("pathX"); + ... + + +Annotations Reference Guide vWF20190404 85 +ignore_path Analysis annotations + + The above example illustrates placement of the ignore_path annotation in an + if statement. Note that the analysis includes the condition in the if statements, + but not the code that is conditionally executed. + + +86 Annotations Reference Guide vWF20190404 +Analysis annotations justification + + +8.7 justification +8.7.1 Applies to + RapiCover + +8.7.2 Synopsis + C/C++ + #pragma RVS justification( "" [, ""] , + "") + /*##RVS justification( "" [, ""] , + "") */ + C++ + //##RVS justification( "" [, ""] , + "") + Ada + pragma RVS ( justification( "" [, ""] , "")); + + + Where is one of: + COV_FUNCTIONS + COV_BRANCHES (or COV_DECISIONS) + COV_CALLS + COV_STATEMENTS + COV_MCDC + COV_FUNCTION_EXITS + + + When is COV_MCDC, a must be specified as de- + scribed in Section 8.7.5. + +8.7.3 Description + In some cases it is not feasible to achieve 100% coverage for a particular class of + coverage on the analyzed source code. + + To help explain why coverage for a particular location hasn't been observed, you + can add justifications to your code. Justifications are viewable in the RVS Project + Manager and appear in coverage exports generated by covexport. + + +Annotations Reference Guide vWF20190404 87 +justification Analysis annotations + + + Note + + The easiest way to add justifications to your code is by using the RVS + Project Manager. This lets you add and edit justifications directly without + adding annotations to your source code, and provides additional features + such as letting you add descriptions and custom fields to your justifications, + link attachments to them, and migrate them more easily when your source + code changes. For more information, see Chapter 9 in the RapiCover User + Guide. + + The primary method of adding justifications is by using the RVS Project + Manager. Justification annotations are supported in situations where it is + necessary or desirable to place the justification directly into the application + source code. When justifications are added using annotations it is not pos- + sible to edit or remove them through the RVS Project Manager, and en- + hanced justification features are not available. + + + The justification annotations should be placed as follows: + 1. COV_FUNCTIONS justifications can be placed anywhere in the body of the + function. + 2. COV_CALLS, COV_STATEMENTS or COV_FUNCTION_EXITS justifications + must be placed on the line immediately after the call, statement or function + exit that they apply to. + + Where there are multiple calls, statements or function exits on that line, you + must specify an index to indicate which element the justification applies to. + The first element of a class (e.g. statement) on a line is index 1, following + elements of the same class have increasing index numbers left to right. + 3. COV_BRANCHES (or COV_DECISIONS) justifications must be placed at the + top of the branch to be justified for that decision. + 4. COV_MCDC justifications can be placed at the top of any of the branches of + the decision. Additionally, COV_MCDC justifications must indicate the con- + dition they apply to by specifying the condition index and text as part of the + annotation (see example below). + + Sometimes, MC/DC decisions do not have a branch (e.g. assignments to + the result of a Boolean expression, or Boolean expressions in call parame- + ters). In these cases, COV_MCDC justifications must be placed after the line + containing the MC/DC decision. + + +88 Annotations Reference Guide vWF20190404 +Analysis annotations justification + + +8.7.4 Examples of justification annotations + + Example 8.8: Justification annotations for functions and decisions + + ... + void fatal_error (void) + { + #pragma RVS justification( "COV_FUNCTIONS", "The fatal_error + function cannot be executed during normal execution") + /* some code */ + } + ... + void check_status (int status) + { + if ( (check_enabled) && (FATAL_ERROR == status) ) { + #pragma RVS justification( "COV_DECISIONS", "Variable 'status' + cannot take value FATAL_ERROR during normal execution") + + fatal_error(); + } + } + ... + + + Example 8.9: Justification annotations for calls and MC/DC + + ... + procedure check_status (status: StatusType) is + begin + if ( (check_enabled) and then + (FATAL_ERROR_STATUS = status) ) then + pragma RVS (justification( + "COV_MCDC", "2:(FATAL_ERROR_STATUS=status)", + "Variable 'status' cannot take value FATAL_ERROR_STATUS during + normal execution")); + + fatal_error; + pragma RVS (justification( + "COV_CALLS", + "The fatal_error function cannot be called during normal + execution")); + return; + pragma RVS (justification( + "COV_FUNCTION_EXITS", + "This function exit cannot be reached during normal + execution")); + end if; + + more_code; + + end check_status; + ... + + +8.7.5 MC/DC justifications + MC/DC justifications are more complicated than non-MC/DC justifications: + + +Annotations Reference Guide vWF20190404 89 +justification Analysis annotations + + + 1. MC/DC justifications apply to one condition of a decision, rather than the + whole decision. + 2. MC/DC justifications take an extra parameter, specifying the con- + dition that the justification refers to. In the example above, + the MC/DC justification justifies the second condition in the + decision, which is (FATAL_ERROR_STATUS=status). Therefore, + the justification annotation must be passed the parameter: + "2:(FATAL_ERROR_STATUS=status)". + + Warning + + Take care with brackets surrounding MC/DC conditions. RapiCover consid- + ers the condition (FATAL_ERROR_STATUS=status) to be different to + the condition FATAL_ERROR_STATUS=status. The justification parser + is not sensitive to whitespace in the condition, but it is sensitive to brackets. + + +90 Annotations Reference Guide vWF20190404 +Analysis annotations loop_max_iter + + +8.8 loop_max_iter +8.8.1 Applies to + RapiTime + +8.8.2 Synopsis + C/C++ + #pragma RVS [ [""] ] loop_max_iter("") + /*##RVS [ [""] ] loop_max_iter("") */ + C++ + //##RVS [ [""] ] loop_max_iter("") + Ada + pragma RVS ([ "", ] loop_max_iter("")); + + +8.8.3 Description + loop_max_iter specifies the maximum number of iterations to use for com- + puting the WCET of this loop. + + is a mathematical expression defining the maximum number of iterations. + See Section 4.5 for a definition of permitted operations. + + Normally RapiTime uses the information from the trace data to determine the max- + imum number of times each loop iterates on any single invocation of that loop. + This information is then used in the WCET calculation. + + Sometimes it is useful to specify the maximum number of loop iterations manually. + This might be necessary in the following circumstances: + 1. Your testing strategy is not guaranteed to ensure that the maximum possi- + ble number of loop iterations is observed. Use annotations to ensure that + appropriate values are used in the analysis. + 2. Your testing strategy makes use of some unrealistic data that results in a + larger number of loop iterations than can possibly occur during normal sys- + tem operation. Use annotations to reduce the maximum iterations value used + in the analysis. + + Use the loop_max_iter annotation to define the maximum number of itera- + tions of a loop. The annotation refers to the first enclosing loop found, working + outwards from the location of the annotation. The value you provide in this anno- + tation specifies the maximum number of times that the body of the loop executes + on any one invocation. (In the case of for and while loops, this number is one + less than the number of times the loop test executes). + + Note + + We recommend that you avoid using the loop_max_iter annotation. In- + stead modify your test strategy to include data that drives the worst-case + number of iterations of each loop. + + +Annotations Reference Guide vWF20190404 91 +loop_max_iter Analysis annotations + + +8.8.4 Examples + Example 8.10: loop_max_iter annotation + + ... + void + my_fun (int range_min, int range_max) + { + int j; + + /* Maximum range width is 10 */ + for(j = range_min; j<=range_max; j++) + { + check (j); + } + } + ... + #pragma RVS [my_fun@L1] loop_max_iter (10) + ... + + + In the above example, the annotation specifies the maximum number of iterations + of the loop as 10. This means that the loop body is considered to execute 10 times + and the loop test (j <= range_max), 11 times. + + Note + + If you do specify a value for loop_max_iter that is lower than an ob- + served number of iterations for that loop, a warning message is generated + by timeparser and the corresponding table entries in the RVS Project Man- + ager are highlighted in red. + + +92 Annotations Reference Guide vWF20190404 +Analysis annotations max_wpaths + + +8.9 max_wpaths +8.9.1 Applies to + RapiTime + +8.9.2 Synopsis + C/C++ + #pragma RVS max_wpaths("") + /*##RVS max_wpaths("") */ + C++ + //##RVS max_wpaths("") + Ada + pragma RVS (max_wpaths("")); + + +8.9.3 Description + max_wpaths specifies the maximum number of execution paths to be consid- + ered simultaneously during analysis. + + By default, RapiTime considers only the worst-case path through each procedure + or function. However, if infeasible paths are identified using path_id (see Sec- + tion 8.12), then more than one possible path may be considered. Generally speak- + ing, every unique path_id label within a function doubles the number of paths + considered. For example, if path_id is used twice within one function, then four + paths are considered. If it is used three times, then eight paths are considered. In + other words, the correspondence between the number of unique path_id labels + and the number of paths is exponential. + + max_wpaths can be used to limit this expansion by forcing RapiTime to exit with + an error if the specified number of execution paths is exceeded. This helps to + ensure that the CPU time and memory required for analysis remain within expected + bounds. + + max_wpaths is particularly important in conjunction with no_fold. Any function + call annotated as no_fold will cause the path_id labels in the called function + to be analyzed as if they appear in the caller, with a corresponding exponential + increase in the number of worst-case paths to be considered within the caller. + + +Annotations Reference Guide vWF20190404 93 +no_fold Analysis annotations + + +8.10 no_fold +8.10.1 Applies to + RapiTime + +8.10.2 Synopsis + C/C++ + #pragma RVS no_fold("", "") + /*##RVS no_fold("", "") */ + C++ + //##RVS no_fold("", "") + Ada + pragma RVS (no_fold("", "")); + + +8.10.3 Description + If the no_fold annotation is used, all path_id annotations within be- + come accessible from any function calling . + + Without no_fold, wpath annotations can only specify relationships between + paths within a single function. This is because multiple worst-case paths are nor- + mally folded into a single worst-case path at every function boundary. no_fold + creates an exception to this rule. + + Any non-root function can be no_fold. + + no_fold has the additional effect that all calls to are automatically ex- + panded as if expand_calls is used. (The expand_calls annotation is im- + plicit and does not also need to be specified.) + + +94 Annotations Reference Guide vWF20190404 +Analysis annotations no_fold + + +8.10.4 Example + Example 8.11: no_fold annotation + + ... + extern void big_computation(); + extern int timer; + + void step() + { + if (timer == 1) { + #pragma RVS path_id("big") + big_computation(); + timer = 0; + } else { + timer++; + } + } + + #pragma RVS wp_one_or_none_of("U@C1.big","U@C2.big") + void U() + { + step(); + step(); + } + ... + + + In the above example, the no_fold annotation allows the use of inter-procedural + wpath annotations, which are used to specify that big_computation is exe- + cuted at most once per call to U. + + The path expressions given to wp_one_or_none_of identify each call site us- + ing the standard Abstract Source Location (ASL) syntax (see Section 5.3). Paths + identified in this way must be placed inside double quotes. + + The form of these annotations is "@C." where + is the name of the calling function, is the number of the call + site, and is a path name given to a path_id annotation within the + called function. + + Call sites are places in the code where a function is called. Call site numbers are + assigned in order of appearance within the function source code, starting from 1. + + For example, the annotation "U@C1.big" refers to the first call site within the func- + tion U. The called function contains a path_id named "big". + + Note + + Consider using max_wpaths to limit the maximum number of paths + processed within each function (see Section 8.9). + + +Annotations Reference Guide vWF20190404 95 +overall_wcet_calls, overall_wcet_this_call Analysis annotations + + +8.11 overall_wcet_calls, overall_wcet_this_call +8.11.1 Applies to + RapiTime + +8.11.2 Synopsis + C/C++ + #pragma RVS overall_wcet_calls("", "") + #pragma RVS [ [""] ] overall_wcet_this_call("", "") + /*##RVS overall_wcet_calls("", "") */ + /*##RVS [ [""] ] overall_wcet_this_call("", "") */ + C++ + //##RVS overall_wcet_calls("", "") + //##RVS [ [""] ] overall_wcet_this_call("", "") + Ada + pragma RVS overall_wcet_calls("", ""); + pragma RVS ([ "", ] overall_wcet_this_call("", + "")); + + +8.11.3 Description + This annotation allows you to replace the computed WCET of specific functions + (in cycles) with a value that you supply. + + The annotations specifying worst-case execution times are particularly useful un- + der the following circumstances: + • Contracted out subsystem + + You have a supplier who provides the code for a given subsystem (function). + The supplier performs testing and WCET analysis of their code and supplies + its timing information. You can then include the timing in your analysis of the + complete subsystem. + + You use the black_box annotation to instruct cins, cppins or adains to + place ipoints either side of calls into the supplied system. Then use the + overall_wcet_this_call annotation with the supplied WCET for each + sub-system function. + + The supplier, who needs to provide overall WCET values for the subsystem, + should contact Rapita Systems Ltd. for advice on how to ensure that the values + collected using RapiTime are appropriate for use in this respect. + • Preliminary analysis of an incomplete system + + Include the unimplemented functions as simple stubs and use their execution + time budgets as initial worst-case execution time estimates. + • Incremental approach to generating timing information. + + You may find it useful to take an incremental approach to generating timing + information For example, you could run a set of tests that exercise all the sub- + + +96 Annotations Reference Guide vWF20190404 +Analysis annotations overall_wcet_calls, overall_wcet_this_call + + paths through a particularly complex function. Later test sets could then omit + testing and instrumentation of that function and focus on other parts of the + software, using the overall_wcet annotation to include the previous re- + sults in the overall WCET calculation. + + Two variants of the overall_wcet exist: + • overall_wcet_calls("", ""); + + Use this global annotation to instruct the analysis to use the number or numer- + ical value as the WCET of the function . This time includes all + sub-function calls in the function's call tree. + • overall_wcet_this_call("", ""); + + Use this local annotation to specify the WCET of a call to a function in a specific + calling context. This annotation applies to the call of the function immediately + preceding the annotation or tag. + + Note + + These annotations only affect WCET data in the RVS report. Other ob- + served timing data (minimum, maximum, high-water mark and aver- + age-case execution times) are still collected by timeparser. + + + Note + + When the WCET of a function call is unified, all calls to the function + will be treated as having the maximum WCET specified by any of the + overall_wcet_this_call annotations that apply to the function. + + +Annotations Reference Guide vWF20190404 97 +overall_wcet_calls, overall_wcet_this_call Analysis annotations + + +8.11.4 Examples + Example 8.12: Predefined WCETs + + ... + #pragma RVS overall_wcet_calls("afun",325) + + void + afun(void) + { + /* not implemented yet */ + /* wcet budget 325 cycles */ + } + + void + root(void) + { + afun(); + bfun(); + } + ... + #pragma RVS [root@C2] overall_wcet_this_call("bfun",753) + ... + + + In the above example, the value supplied by the overall_wcet_calls anno- + tation is regarded as the contribution to the worst-case execution time due to a + single call to the specified function (including execution of any sub-functions in + its call tree). + + +98 Annotations Reference Guide vWF20190404 +Analysis annotations path_id + + +8.12 path_id +8.12.1 Applies to + RapiTime + +8.12.2 Synopsis + C/C++ + #pragma RVS [ [""] ] path_id("") + /*##RVS [ [""] ] path_id("") */ + C++ + //##RVS [ [""] ] path_id("") + Ada + pragma RVS ([ "", ] path_id("")); + + +8.12.3 Description + path_id is used to name a path in the source code, which is used by the wp_ + annotations (see Section 8.18) in order to define infeasible paths (which helps to + improve RapiTime's WCET estimate). + + Each path_id annotation marks a particular block of code. You can establish an + implicit dependency between blocks of code in the same function by re-using + the same path_id name. In these cases, RapiTime considers either all or none + of the implicitly related blocks of code of a function in the WCET computation. + +8.12.4 Examples + Example 8.13 shows an example in which the dependency relation between blocks + of code is implicitly defined by re-using the same path_id name, path_A. This + indicates that any path considered for the purpose of WCET computation should + contain either both marked blocks of code or none of them. Note that this assumes + that the variable a is not modified between the two conditionals. + + Example 8.13: Implicit dependency between blocks of code + + ... + void my_fun( int a, int b ) + { + if(a != 0){ + #pragma RVS path_id("path_A") /* 1 */ + ... + } + ... + if (a !=0 ){ + #pragma RVS path_id("path_A") /* 2 */ + ... + } + } + ... + + +Annotations Reference Guide vWF20190404 99 +path_id Analysis annotations + + + Note + + The path_id annotation is only used for marking paths that are refer- + enced in wp_ or wpath annotations. To mark a source code location so + that it can be used as a named tag in an annotation, use the tag annota- + tion. See Section 8.14 for a description of the tag annotation. + + +100 Annotations Reference Guide vWF20190404 +Analysis annotations recursive + + +8.13 recursive +8.13.1 Applies to + RVS (except RapiCover map) + +8.13.2 Synopsis + C/C++ + #pragma RVS recursive("","") + /*##RVS recursive("",""*/ + C++ + //##RVS recursive("","") + Ada + pragma RVS (recursive("",""); + + +8.13.3 Description + The recursive annotation lets you indicate that a function calls itself directly + (is directly recursive). + + Note + + The recursive annotation only supports direct recursive calls, where + a function calls itself. It cannot handle indirectly-recursive functions, e.g. + where funcA calls funcB and funcB also calls funcA. Indirectly-recur- + sive calls are automatically black-box inlined. + + The parameter indicates which function is recursive, and the pa- + rameter indicates the maximum recursion depth. + + The annotation places a bound on the recursive depth, effectively unrolling the + recursive function into different instances. This enables + RVS to analyze directly-recursive functions. + + The report differentiates between function calls at different depths by prepending + [Rn] to the function name (where n is the depth of the call). + + RVS unifies the recursive function's instances that are called from multiple places + unless you also expand contexts (see Section 8.5). + + Warning + + If the function actually recurses to a greater depth than , timepars- + er will fail to parse the trace data. + + +Annotations Reference Guide vWF20190404 101 +tag Analysis annotations + + +8.14 tag +8.14.1 Applies to + RVS + +8.14.2 Synopsis + C/C++ + #pragma RVS tag("") + /*##RVS tag("")*/ + C++ + //##RVS tag("") + Ada + pragma RVS (tag("")); + + +8.14.3 Description + RapiTime can use named tags (or tagnames) to refer to locations in the code. + Using tags allows you to maintain local annotations in a configuration file (of global + annotations) rather than locally in the code. + + is any valid C identifier enclosed in double quotes. + +8.14.4 Examples + Example 8.14: Defining and using tag names in C/C++ + + 1: ... + 2: if (x > 0) + 3: { + 4: process(x); + 5: #pragma RVS tag ("block123") + 6: } + 7: ... + 8: #pragma RVS ["block123"] ignore_path + 9: ... + + + Example 8.15: Defining and using tag names in Ada + + 1: ... + 2: if x > 0 then + 3: process(x); + 4: pragma RVS (tag ("block123")); + 5: end if; + 6: pragma RVS ("block123", ignore_path); + 7: ... + + + Line 5 defines a tag that is then used by the ignore_path annotation on line 8. + + +102 Annotations Reference Guide vWF20190404 +Analysis annotations tag + + + Note + + The tag annotation is only used for marking a source code location so that + it can be used as a named tag in an annotation. To mark paths that are ref- + erenced in wp_ or wpath annotations, use the path_id annotation.See + Section 8.12 for a description of the path_id annotation. + + +Annotations Reference Guide vWF20190404 103 +unroll_this_loop, default_unroll_loops Analysis annotations + + +8.15 unroll_this_loop, default_unroll_loops +8.15.1 Applies to + RapiTime + +8.15.2 Synopsis + C/C++ + #pragma RVS default_unroll_loops("") + #pragma RVS [ [""] ] unroll_this_loop("") + /*##RVS default_unroll_loops("") */ + /*##RVS [ [""] ] unroll_this_loop("") */ + C++ + //##RVS default_unroll_loops("") + //##RVS [ [""] ] unroll_this_loop("") + Ada + pragma RVS (default_unroll_loops("")); + pragma RVS ([ "", ] unroll_this_loop("")); + + +8.15.3 Description + The unroll_loops annotation allows RapiTime to treat the execution time of + different loop iterations separately. This supports the analysis of processors with + instruction cache, where the first iteration of a loop typically takes far longer than + the same code executed on subsequent iterations. This is due to the delays in + loading the instructions into cache. The second and third iterations of loops may + also take different execution times on some processors. + + RapiTime obtains tight WCET bounds by recognizing this behavior and computing + worst-case execution times for loops based on separate execution time profiles + for the observed execution times of different iterations of the loop: 1st, 2nd, 3rd + etc. and subsequent iterations. + + The number of times a loop is unrolled for analysis purposes is specified using + the following annotations: + • default_unroll_loops(""); + Use this global annotation to specify the default number of times that each + loop should be unrolled. + • unroll_this_loop(""); + Use this local annotation to specify the level of loop unrolling for the loop en- + closing the annotation or tag. + + You can use the loop unrolling annotation to provide more accurate analysis for + systems with instruction and/or data caches. However the annotation also affects + the amount of computation required as part of the analysis. It is recommended that + you limit your use of the loop unrolling annotation to those loops that contribute + the most to the worst-case execution time. + + The level of loop unrolling necessary to obtain the most accurate analysis depends + on the characteristics of the hardware. For simple microprocessors with no cache, + + +104 Annotations Reference Guide vWF20190404 +Analysis annotations unroll_this_loop, default_unroll_loops + + use the default of zero. For more advanced processors you can obtain improve- + ments by using one or two levels of loop unrolling. The analysis does not need + to differentiate further than between (1) the first, (2) the second and (3) all subse- + quent iterations of a loop. + + Note + + You are recommended not to use levels of loop unrolling greater than 3, as + this results in the analysis becoming overly complex. In addition, unrolling + loops can place an additional burden on testing because it is necessary to + ensure that the paths through each unrolled iteration have been adequately + tested. + + + Note + + Function calls in an unrolled loop also need to be expanded in order to cap- + ture timing variability due to cache effects. + + +8.15.4 Examples + Example 8.16: Loop unrolling + + 1: ... + 2: #pragma RVS default_unroll_loops(0) + 3: + 4: for(j=0; j"] ] wfreq("") + /*##RVS [ [""] ] wfreq("") */ + C++ + //##RVS [ [""] ] wfreq("") + Ada + pragma RVS ([ "", ] wfreq("")); + + +8.16.3 Description + Use the wfreq annotation to specify a local worst-case frequency, that is the + maximum number of times that a conditional block of code can be executed in + its enclosing loop. + + Important + + You can only place the wfreq annotation in a conditional block of code + that is itself contained inside a loop (see Example 8.18). A conditional block + of code is anything that can selectively execute - a selection structure (e.g. + if, switch) or a loop structure (e.g. while, for). + + + Warning + + For conditionals that contain more than one conditional block (e.g. if-then- + else statements), if you add a wfreq annotation to one of the blocks, then + you must also add matching wfreq annotations to the other blocks (see + Example 8.19). If you fail to add the matching annotations, the resulting + WCET analysis will be pessimistic. + + + Warning + + When you use a wfreq annotation for conditional blocks in switch state- + ments, you must not omit the break statement (i.e. do not use 'fall- + throughs'), as shown in Example 8.17. + + + Warning + + When you use a wfreq annotation on a nested loop, you specify the maxi- + mum number of iterations for that loop independently of the number of iter- + ations of the enclosing loop (see Example 8.20). + + +106 Annotations Reference Guide vWF20190404 +Analysis annotations wfreq + + +8.16.4 Examples + + Example 8.17: wfreq for switch statements + + ... + for(i=0; i < limit; i++) + { + #pragma RVS loop_max_iter (100) + switch (i) + { + case 1: + #pragma RVS wfreq (1) + first(); + break; /* The wfreq annotation requires this break */ + case 2: + #pragma RVS wfreq (1) + second(); + break; /* The wfreq annotation requires this break */ + default: + others(); + #pragma RVS wfreq (98) + } + } + ... + + + Example 8.18: wfreq annotation + + ... + void + process_data(int limit) + { + int i, star_count, save_count; + + star_count = 0; + for(i=0; i < limit; i++) + { + if(buf[i] == '*') + { + star_count++; + if(star_count >= 50) + { + save_count = star_count; + break; + } + } + } + } + ... + #pragma RVS [process_data@L1] loop_max_iter (1000) + #pragma RVS [process_data@P1] wfreq (50) + #pragma RVS [process_data@P2] wfreq (1) + ... + + + In the above example, the loop_max_iter annotation specifies that the body + of the loop is executed at most 1000 times. + + +Annotations Reference Guide vWF20190404 107 +wfreq Analysis annotations + + The first wfreq annotation specifies that the condition buf[i]=='*' is true in + at most 50 of the 1000 iterations. + + Finally, the last wfreq annotation specifies that the condition star_count>=50 + can only be true once for each execution of the loop. + + Example 8.19: wfreq for multiple conditional blocks + + ... + for(i=0; i < limit; i++) + { + if(i%2 == 0) + { + even++; + } else { + odd++; + } + } + ... + #pragma RVS [foo@L1] loop_max_iter (100) + #pragma RVS [foo@P1] wfreq (50) + #pragma RVS [foo@P2] wfreq (50) + ... + + + In the above example, the loop_max_iter annotation specifies that the body + of the loop is executed at most 100 times and that the two conditional paths within + the loop are executed half of the time each (i.e. 50). + + Example 8.20: wfreq for nested loops + + ... + if ( x > 200 ) + { + x = 200; + } + + for (i=0; i < x; i++) + { + for (j = i%2 + 1; j < i%3 + 1; j++) + { + c++; + } + } + ... + #pragma RVS [calculate@L1] loop_max_iter (200) + #pragma RVS [calculate@L2] wfreq (132) + ... + + + In the above example, the loop_max_iter annotation specifies that the body + of the loop is executed at most 200 times. The wfreq annotation specifies that + during those 200 executions, the inner loop will execute at most 132 times total (in + this example, this means that the value of c never exceeds 132). + + +108 Annotations Reference Guide vWF20190404 +Analysis annotations wp_*, lwp_* + + +8.17 wp_*, lwp_* +8.17.1 Applies to + RapiTime + +8.17.2 Synopsis + C/C++ + #pragma RVS [ [""] ] ("" [, ""]*) + /*##RVS [ [""] ] ("" [, ""]*) */ + C++ + //##RVS [ [""] ] ("" [, ""]*) + Ada + pragma RVS ( [ "", ] ("" [, ""]*)); + + Where is one of: + lwp_one_or_none_of + lwp_at_least_one_of + lwp_exactly_one_of + wp_one_or_none_of + wp_at_least_one_of + wp_exactly_one_of + + +8.17.3 Description + In some cases you can improve the WCET estimate computed by RapiTime by + adding information about which paths are infeasible execution paths. wp_* and + lwp_* annotations provide a simple interface to some of the most commonly + used path constraints. + + Note + + wp_* annotations can be global or local. Local annotations start with the + prefix l. They must be placed inside the function body and only apply to + tags in that particular function. Global annotations do not start with the pre- + fix l. They must be placed outside any function body and apply to all the + functions at once. + + + There are three types of wp_* annotations to cater for the following types of con- + straint: + 1. Consider at most one of the marked blocks of code in the WCET computa- + tion. RapiTime will select the block of code with the largest WCET when there + are several to choose from. + + The global annotation to apply this constraint is: + wp_one_or_none_of("", ... ); + + The local annotation to apply this constraint is: + + +Annotations Reference Guide vWF20190404 109 +wp_*, lwp_* Analysis annotations + + lwp_one_or_none_of("", ... ); + + 2. Consider at least one of the marked blocks of code in the WCET computa- + tion. + + The global annotation to apply this constraint is: + wp_at_least_one_of ("", ... ); + + + The local annotation to apply this constraint is: + lwp_at_least_one_of ("", ... ); + + 3. Consider exactly one of the marked blocks of code in the WCET computation. + + The global annotation to apply this constraint is: + wp_exactly_one_of ("", ... ); + + + The local annotation to apply this constraint is: + lwp_exactly_one_of ("", ... ); + + + Note + + More advanced path constraints can be defined using a path expression + in a wpath or lwpath annotation. See Section 8.18 for further details of + these annotations. + + +8.17.4 Example of mode analysis + Example 8.21 shows a program where the path taken depends upon the mode of + operation: weight_on_wheels mode uses the tagged block of code WOW, but + in_flight mode uses the tagged block of code IF. To ensure that RapiTime + computes the WCET for the weight_on_wheels mode, the code includes two + annotations: + 1. The global wp_exactly_one_of annotation states that the modes are + mutually exclusive. + 2. The global wp_at_least_one_of annotation states that the mode to in- + clude in WCET calculations is weight_on_wheels. + + +110 Annotations Reference Guide vWF20190404 +Analysis annotations wp_*, lwp_* + + Example 8.21: Mode-specific path + + ... + #pragma RVS wp_exactly_one_of ("WOW", "IF") + #pragma RVS wp_at_least_one_of ("WOW") + + int get_speed( void ) + { + int speed; + + if(mode == weight_on_wheels) { + #pragma RVS path_id("WOW") + speed = get_wheel_speed (); + } + + if (mode == in_flight){ + #pragma RVS path_id("IF") + speed = get_air_speed (); + } + return speed; + } + ... + + + Note + + Unless no_fold is used, references to path tags are restricted by the + function boundary. In other words, path tags defined in two different func- + tions cannot be referenced in a single annotation either local or global. + no_fold relaxes this restriction by allowing path tags to be referenced by + the caller (see Section 8.10). + + +Annotations Reference Guide vWF20190404 111 +wpath, lwpath Analysis annotations + + +8.18 wpath, lwpath +8.18.1 Applies to + RapiTime + +8.18.2 Synopsis + C/C++ + #pragma RVS wpath ( "" ) + #pragma RVS lwpath ( "" ) + /*##RVS wpath ( "" ) */ + /*##RVS lwpath ( "" ) */ + C++ + //##RVS wpath ( "" ) + //##RVS lwpath ( "" ) + Ada + pragma RVS wpath ( "" ); + pragma RVS lwpath ( "" ); + + Where is one of: + and + nand + or + xor + not + and (, ... ,) + nand (, ... ,) + or (, ... ,) + xor (, ... ,) + + And is either or () . + +8.18.3 Description + In some cases you can improve the WCET estimate computed by RapiTime by + adding information about which paths are infeasible execution paths. Using a + wpath annotation, infeasible paths can be expressed as a path expression con- + sisting of named path sections and Boolean operators. + + Note + + wpath annotations can be global or local. Local wpath annotations start + with the prefix l. They must be placed inside the function body and only ap- + ply to tags in that particular function. Global wpath annotations do not start + with the prefix l. They must be placed outside any function body and apply + to all the functions at once. + + For example, you might use the following path expression to cause any path which + includes idle_mode_path or diag_mode_path to be excluded from the + analysis: + #pragma RVS wpath("not(idle_mode_path) or not(diag_mode_path)") + + +112 Annotations Reference Guide vWF20190404 +Analysis annotations wpath, lwpath + + +8.18.4 Example of mutually exclusive paths + Example 8.22 demonstrates mutual exclusion between tagged blocks of + code path_A and path_B. In this case, the local annotation lw- + path ("path_A xor path_B") prevents RapiTime from including both in + the WCET computation. + + Example 8.22: Mutual exclusion + + ... + void my_fun( int a, int b ) + { + #pragma RVS lwpath ("path_A xor path_B") + if(a == 0){ + #pragma RVS path_id("path_A") + ... + } + + if (a !=0){ + #pragma RVS path_id("path_B") + ... + } + } + + void other_fun( int c ) + { + #pragma RVS path_id("path_C") + ... + } + + ... + + + Warning + + Generally, references to path tags are restricted to the function boundary + only. In other words, path tags defined in two different functions cannot be + referenced in a single annotation either local or global. For example, path_A + and path_C cannot be used in the same annotation. + + However, if the functions involved call each other, the no_fold annotation + allows the use of inter-procedural wpath constraints (see Section 8.10). + + +Annotations Reference Guide vWF20190404 113 +This page intentionally left blank + diff --git a/docs-extracted/src/scov/RVS/doc/Reference/RVS_Files.md b/docs-extracted/src/scov/RVS/doc/Reference/RVS_Files.md new file mode 100644 index 000000000..e930cd2d5 --- /dev/null +++ b/docs-extracted/src/scov/RVS/doc/Reference/RVS_Files.md @@ -0,0 +1,1833 @@ +--- +title: "Rvs Files" +source: "./src/scov/RVS/doc/Reference/RVS_Files.pdf" +category: "src/scov/RVS/doc/Reference" +pages: 56 +extracted: "2026-07-06T23:15:57.586533" +--- + +# Rvs Files + +> Extracted from `./src/scov/RVS/doc/Reference/RVS_Files.pdf` (56 pages). +> Figures, diagrams, and tables may not render accurately in plain text. + +Files Reference Guide + Version WF20190404 +Disclaimer +The information, text, and graphics contained within this document are +provided for information purposes only by Rapita Systems Ltd. Rapita +Systems Ltd. does not warrant the accuracy or completeness of the +information, text, and other items contained in this document. + + +Copyright and Trademarks +All rights reserved. Information and images contained within this doc- +ument are copyright and the property of Rapita Systems Ltd. All trade- +marks are hereby acknowledged to be the properties of their respective +owners. + + +Acknowledgments +Rapita Systems' tools are built using AdaCore's GNAT Pro compiler. + + +Rapita Systems Ltd. +Registered in the UK, number 5011090. +Registered address: +Atlas House +Link Business Park +Osbaldwick Link Road +York +YO10 3JB +UK +Phone: +44 (0) 1904 413 945 +http://www.rapitasystems.com/ +This document copyright © 2017-2019, Rapita Systems Ltd. + +Document build 118520 + +ID: DOC/17053 + Table of Contents + + 1. About this guide ............................................................... 5 + 1.1. Who should read this guide? ................................................... 5 + + 1.2. Structure of this guide ........................................................... 5 + + 1.3. Notation ............................................................................ 5 + + 1.4. RVS documentation map ........................................................ 6 + + 1.5. Support ............................................................................. 7 + + + 2. What are RVS files? .......................................................... 9 + + 3. RVS configuration files .................................................... 11 + 3.1. Summary ......................................................................... 11 + + 3.2. Project configuration file (*.rvsprj, *.rvscfg) ................................. 12 + + 3.3. Integration file (various extensions) ........................................... 13 + + 3.4. Spreadsheet Test Format file (*.xlsx, *.xlsm, RapiTest only) ............... 14 + + 3.5. RTS file (*.rts, RapiTest only) .................................................. 15 + + 3.6. Annotation file (various extensions) ........................................... 16 + + 3.7. Justification file (*.xml, RapiCover only) ..................................... 17 + + 3.8. Command file .................................................................... 18 + + 3.9. File list ............................................................................ 19 + + 3.10. IdPack configuration file ...................................................... 20 + + 3.11. Warning list ..................................................................... 23 + + 3.12. RVS global configuration file (rvsconfig.ini) ................................ 24 + + + 4. RVS output files .............................................................. 25 + 4.1. Summary ......................................................................... 25 + + 4.2. RVS report database file (*.rvd) ............................................... 26 + + +RVS Files Reference Guide vWF20190404 3 + Table of Contents + + + 4.3. RapiTest export file .............................................................. 27 + + 4.4. RapiCover export file (*.txt) .................................................... 30 + + 4.5. RapiCover export file (*.html) .................................................. 34 + + 4.6. RapiTime export file (*.txt) ..................................................... 40 + + + 5. RVS intermediate files ..................................................... 45 + 5.1. Summary ......................................................................... 45 + + 5.2. Call tree annotation file (*.ctree) .............................................. 46 + + 5.3. Exchange file (*.exf) ............................................................ 47 + + 5.4. Function pointer resolution file (rvs_autores_fptr.txt) ....................... 48 + + 5.5. Map file (various extensions) .................................................. 49 + + 5.6. Recursion resolution file (rvs_autores_bbox.txt) ............................ 50 + + 5.7. Trace file (various extensions) ................................................. 51 + + 5.8. Temporary cache file (various extensions) ................................... 54 + + 5.9. Source code structure file (*.xsc) ............................................. 55 + + +4 RVS Files Reference Guide vWF20190404 +1 About this guide + This guide describes the purpose of RVS-specific files. This includes input files + used to control how RVS works, intermediate files generating while running it, and + output files generated as a result of using RVS. + +1.1 Who should read this guide? + The primary intention of this document is to provide guidance on the input and + export requirements and specifications for various types of RVS files. By reading + it, users should be able to determine whether RVS input files are in the correct + format, and understand the purpose of various types of RVS output files. They + should also be able to understand in which situations each file type is used. This + information is intended to support the qualification of RVS for use in critical systems + development. + +1.2 Structure of this guide + This document includes the following chapters: + + Chapter 1: About this guide + Describes the purpose and layout of this guide and the notation used throughout it. + + Chapter 2: What are RVS files? + Describes RVS files and when they are generated during the RVS workflow. + + Chapter 3: RVS configuration files + Describes input files that are used with RVS. This includes files that form an RVS + integration library. + + Chapter 4: RVS output files + Describes output RVS files that are produced during RVS integrations. + + Chapter 5: RVS intermediate files + Describes intermediate RVS files that are generated when RVS runs and used for + producing output files, but should not be viewed or edited by the user. + +1.3 Notation + This document uses the following notation: + • References to other documents and to other chapters or sections in this doc- + ument are written in italics, for example Chapter 1: About this guide. When + reading an electronic copy of this document, you can click on a reference to + navigate to the location of the referenced element. + + +RVS Files Reference Guide vWF20190404 5 +RVS documentation map About this guide + + + • Names of RVS applications are formatted in bold italics, for example RVS + Project Manager. + • References to areas or elements in user interfaces are formatted in italics, for + example the Report Navigator. + • Menus, menu choices and button labels are formatted in bold, for example + File » Print or OK. Where buttons have icons, these are shown before their + Label in in-line text, for example Save. + • Names of RVS tools are formatted in bold, for example rvsdriver. + • References to HTML links appear as underlined text, for example + www.rapitasystems.com. + • Folder and file names are formatted in a monospaced font. + • Command-line tools and their commands, annotations and examples are for- + matted in a monospaced font. These are either written in-line with text + or as separate text blocks. When written in-line with text, they are formatted + like the following: rvsdriver, default_instrument, rvs_instr.h. + When written as a separate text block, they are formatted like the examples + below: + rvsdriver --project rvs.rvsprj --all + + #pragma RVS instrument( "function_name", "FALSE" ) + + • When referencing Ada code, the term functions refers to both functions and + procedures. + +1.4 RVS documentation map + This document is part of the Rapita Verification Suite (RVS) document set, which + contains the following documents: + + RVS Installation and Licensing Guide + Describes how to install RVS tools, and licensing options for them. + + RVS Integration Guide + Describes how to integrate RVS tools into build and target environments. + + RVS User Guide + Describes how to set up and run RVS projects, analyze data and export verification + results. + + RapiTest User Guide + Describes how to use RapiTest to manage test projects. + + Spreadsheet Test Format User Guide + Describes how to write tests for RapiTest in the Spreadsheet Test Format. + + +6 RVS Files Reference Guide vWF20190404 +About this guide Support + + + RapiCover User Guide + Describes how to use RapiCover to measure code coverage and address cover- + age holes. + + RapiTime User Guide + Describes how to use RapiTime to measure timing metrics including worst-case + execution time, and how to use these metrics to identify the best optimization + candidates. + + RapiTask User Guide + Describes how to use RapiTask to measure system level task timing information, + visualize traces and gain insight into runtime behavior. + + RTBx 2xxx User Guide + Describes how to use the RTBx data logger. + + RVS Integration Library Implementation Guide + Describes how to implement RVS integration libraries. This document is for use by + readers with a thorough understanding of the implementation of RVS. + + RVS Files Reference Guide + Describes RVS-specific files including input, intermediate and output files. + + RVS Filters Guide + Describes RVS filters, which are used to convert raw trace data into a format that + RVS can analyze, and how to write them. + + RVS Command Line Tools Reference Guide + Describes the command-line tools used by RVS, including a list of available com- + mand options. + + RVS Annotations Reference Guide + Describes the annotations you can use to control instrumentation and analysis + with RVS. + + RVS Troubleshooting Guide + Describes the error and warning messages you may encounter when using RVS + tools, and how to address them. + + RVS Migration Guide + Describes how to migrate between using different versions of RVS. + +1.5 Support + For support issues, please contact Rapita Systems Ltd. by any of the following + means: + + +RVS Files Reference Guide vWF20190404 7 +Support About this guide + + + Email + support@rapitasystems.com + + Telephone + +44 (0) 1904 413 945 + + Website + www.rapitasystems.com + + To register for support, visit www.rapitasystems.com/register. More than one user + can register per license. + + +8 RVS Files Reference Guide vWF20190404 +2 What are RVS files? + RVS files are files used to configure how RVS runs, to implement RVS analysis, + and to report results from RVS analysis. + + RVS files are categorized into the following types: + • Configuration files – these files describe how to run RVS. Some of these files + are optional. + • Output files – these files are the main product of running RVS. They contain + results from RVS analysis, such as source code structural coverage or end- + to-end execution times. + • Intermediate files – these files are generated automatically by RVS when it + runs, are not normally viewed and should not be edited. + + The files in each of these categories are discussed in the subsequent chapters + of this document. + + +RVS Files Reference Guide vWF20190404 9 +This page intentionally left blank +3 RVS configuration files + This chapter describes the configuration files used by RVS. These files are created + using the RVS Project Manager or RVS command-line tools. In order to run RVS + to collect verification data, some of these files must be present. + +3.1 Summary + RVS includes the configuration files shown in Table 3.1. Each of these is described + in detail later in this chapter. + + Table 3.1 Configuration file types + File type Usage + Project configuration file The main RVS configuration file. Stores RVS + project, integration, analysis and target settings + among others. + Integration file Contains definitions for RVS functions needed to + use RVS in a specific development environment. + Spreadsheet Test Format Defines tests for use with RapiTest. + spreadsheet + RTS file Defines tests for use with RapiTest. + Annotation file Controls RVS instrumentation. + Justification file Defines code constructs as covered by analysis. + Command file Stores options for RVS command-line tools. + File list Lists files for processing by RVS tools. + IdPack configuration file Stores settings for use with the IdPack feature. + Warning list Specifies warning messages to ignore when run- + ning RVS. + RVS global configuration file Stores licensing and advanced tool settings for + RVS. + + +RVS Files Reference Guide vWF20190404 11 +Project configuration file (*.rvsprj, *.rvscfg) RVS configuration files + + +3.2 Project configuration file (*.rvsprj, *.rvscfg) +3.2.1 Usage + RVS project files (*.rvsprj) are the main configuration file used to define settings + for RVS projects. These define RVS integrations including where to locate source + code, commands to build and run source code, and analysis settings. + + RVS project files are created and edited using the RVS Project Manager, the + RVS Config Editor or the command-line tool configutils. They can include RVS + configuration files. + + RVS configuration files (*.rvscfg) can be included in RVS project files to define + additional settings for an RVS project. They can be created and edited using the + RVS Config Editor or the command-line tool configutils. + + For more information on creating and editing project configuration files, see the + RVS User Guide. + +3.2.2 Format/encoding + XML, UTF-8. + +3.2.3 Syntax + Project configuration files have a standard XML structure where project settings + are stored within an root element. + + A full list of valid settings for project configuration files is given in + riclib_doc.html, which is included in RVS installations in the folder + RVS\integration_resources\reference. + + Valid project configuration files must include at least the following: + • A single project section that contains at least a project-name and a + languages setting. + • A single integrations section that contains at least one named inte- + gration with a single analysis-ref and target-ref setting. This + integration should also include a data-files section with suitable + settings to collect data with RVS. + • A single analyses section that contains at least one named analysis with + a single analysis-tasks and instr-profile setting. + • A single targets section that contains at least one named target with + a working-folder setting. This target should contain commandline + settings suitable to build the project's source code. + + +12 RVS Files Reference Guide vWF20190404 +RVS configuration files Integration file (various extensions) + + +3.3 Integration file (various extensions) +3.3.1 Usage + RVS integration files form an integration library of that configures RVS how to + collect verification data from a particular target architecture. These files must be + present before RVS can be run. Template integration libraries that are suitable + for a range of languages, analyses and target architectures are stored in the + rvs/integration_resources/templates. + + For more information on configuring RVS integration libraries, see Chapter 5 in the + RVS Integration Guide. + +3.3.2 Format/encoding + Custom source code to add to your project. + +3.3.3 Syntax + The files must build successfully with your compiler and run with your runtime, if + any. + + +RVS Files Reference Guide vWF20190404 13 +Spreadsheet Test Format file (*.xlsx, *.xlsm, + RVS configuration files +RapiTest only) + +3.4 Spreadsheet Test Format file (*.xlsx, *.xlsm, + RapiTest only) +3.4.1 Usage + Spreadsheet Test Format files are an input file format used to define tests for use + with RapiTest. + +3.4.2 Format/encoding + XLSX or XLSM worksheet, Microsoft Office 2010 and onwards. + +3.4.3 Syntax + The syntax for Spreadsheet Test Format files is described in detail in the Spread- + sheet Test Format User Guide. + + +14 RVS Files Reference Guide vWF20190404 +RVS configuration files RTS file (*.rts, RapiTest only) + + +3.5 RTS file (*.rts, RapiTest only) +3.5.1 Usage + RTS files are an input file format used to define tests for use with RapiTest. + + Note + + RTS files are also an intermediate file format – when tests are provided to + RapiTest in other formats, RapiTest converts input tests into RTS files before + subsequent processing. + + +3.5.2 Format/encoding + Text, ASCII. + + +RVS Files Reference Guide vWF20190404 15 +Annotation file (various extensions) RVS configuration files + + +3.6 Annotation file (various extensions) +3.6.1 Usage + RVS annotation files define how source code is instrumented for collection of ver- + ification data such as coverage, timing and task analysis data. These files are + generated using the RVS Project Manager and can be copied between different + integrations. + +3.6.2 Format/encoding + Ada, C or C++ source files with RVS annotations. + +3.6.3 Syntax + For information on the syntax of annotation files, see the RVS Annotations Refer- + ence Guide. + + +16 RVS Files Reference Guide vWF20190404 +RVS configuration files Justification file (*.xml, RapiCover only) + + +3.7 Justification file (*.xml, RapiCover only) +3.7.1 Usage + Justification files store RapiCover justifications, which mark code as covered, and + are created using the RVS Project Manager. For more information on justifica- + tions, see the Chapter 9 in the RapiCover User Guide or the RapiCover tutorials. + +3.7.2 Format/encoding + XML. + +3.7.3 Syntax + The justification system uses file signatures to validate the contents. As such, you + should only create and edit justifications using the RVS Project Manager or RVS + Report Viewer. + + +RVS Files Reference Guide vWF20190404 17 +Command file RVS configuration files + + +3.8 Command file +3.8.1 Usage + All RVS tools have a --cmd-file option that lets the user provide options from + a text file. + + Command files are text files containing tool parameters, which may be written on + a single line or split across multiple lines. + +3.8.2 Format/encoding + Text, ASCII. + +3.8.3 Syntax + No specific file naming convention or file extension exists for command files. We + recommend that you do not use the .cmd extension, as this is recognized by + Windows as a command script file. + + No text is expanded through a shell environment. For example, $HOME is passed + to the tool as $HOME. + + Text within single quotes is taken literally and no escaping is possible. For example, + 'C:\home' is passed to the tool as C:\home. + + Text within double quotes is taken literally except that the escape sequence \" + evaluates to the character ". For example, "C:\"home" is passed to the tool + as C:"home. + + Text elsewhere is taken literally except that the escape sequences \" + and \' evaluate, respectively, to the characters " and '. For example, + --code \"int i;\" is passed to the tool as --code "int i;". + + Warning + + A command file cannot be empty (zero bytes or whitespace only). + + + Note + + A line is ignored if the first non-whitespace character is #. + + +18 RVS Files Reference Guide vWF20190404 +RVS configuration files File list + + +3.9 File list +3.9.1 Usage + Some tool options (-l for cins, cppins and adains; --ipoint-rewrite for + xstutils) specify a file list, which is a list of files to operate on. + +3.9.2 Format/encoding + Text, ASCII. + +3.9.3 Syntax + File lists are text files where file names are listed one per line. Absolute paths + should be used for file names in file lists. Files in a file list may be located in the + current directory or in sub-directories of the current directory. If they are located in + sub-directories, the path name should be specified: + + absolute\path\to\file1.c + absolute\path\to\another\file1.c + + When using with cins or cppins, each input file path can take, as an optional + parameter, an additional path to the source file from which the preprocessed code + was generated, in the following format: + [,] + This can be used to disambiguate where multiple source files in different subdi- + rectories share the same file name. + + +RVS Files Reference Guide vWF20190404 19 +IdPack configuration file RVS configuration files + + +3.10 IdPack configuration file +3.10.1 Usage + IdPack configuration files contain configuration settings that let you use the IdPack + feature of RVS. This feature lets you configure instrumentation. + + Sometimes the number of bits available to write ipoint IDs is insufficient to instru- + ment the entire source code. In these cases, the --idpack-cfg option to xstu- + tils can be used to insert calls to a tailored ipoint routine depending on the number + of bits required to output the ipoint ID. + + The --idpack-cfg option lets you to control the IdPack feature via an IdPack + configuration file, which instructs xstutils to produce several types of ipoint and + use them in a priority ordering (i.e. try to use the short ones most often). + +3.10.2 Format/encoding + Text, ASCII. + +3.10.3 Syntax + In the IdPack configuration file, you specify groups of ipoints, and you associate + with each group a range of permissible ipoint IDs together with a name that is + appended to the ipoint routine in the source code (to distinguish this group from + the others). + + IdPack configuration files must comply with the following grammar: + FILE: UNCHANGED? GROUP+ + UNCHANGED: '[' 'unchanged' ']' RANGEID NAME? + GROUP: '[' 'group' ID ']' RANGEID NAME? UNIQIDS? + RANGEID: 'range' '=' RANGEDEF + NAME: 'name' '=' STRING + UNIQIDS: 'uniq_ids' '=' BOOL + BOOL: 'TRUE' + | 'FALSE' + STRING: '"' [a-zA-Z_]+ '"' + ID: [a-zA-Z_][a-zA-Z_0-9]* + RANGEDEF: SET + | RANGE + | '(' RANGEDEF ')' + | RANGEDEF '-' RANGEDEF + | RANGEDEF '+' RANGEDEF + SET: '{' NUM {',' NUM}* '}' + RANGE: '[' NUM '..' NUM ']' + NUM: DIGIT DIGIT* + DIGIT: '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' + where: + • Each non-terminal symbol appears in upper case. For example, FILE and SET + are both non-terminals. Repetitive non-terminal symbols are enclosed in brace + brackets {}. + + +20 RVS Files Reference Guide vWF20190404 +RVS configuration files IdPack configuration file + + + • Each terminal symbol is enclosed between single quotes. For example, '+' + represents the character literal +. + • * matches the preceding element zero or more times. + matches the preced- + ing element one or more times. ? matches the preceding element zero or one + time. + • Character classes are enclosed between square brackets []. For example, [a- + z] specifies a range which matches any lower-case character from 'a' to 'z'. + + The grammar permits an optional group of ipoints to be specified as unchanged, + indicating that xstutils will not remap any ipoint IDs in the specified range. Typically, + this is needed when particular ipoints are used to instrument interrupts or the OS. + + Warning + + Unchanged ipoints must be placed manually in the source code before + cins runs. + + xstutils uses the order that the (other) groups appear in the IdPack configuration + file as the priority it should employ when searching for a remapped ipoint ID. For + example, if it cannot find a suitable remapped ipoint ID from the range specified + by the first group then it continues onto the second group, and so on. + + The grammar also permits a group of ipoints to have unique remapped IDs (indi- + cated by uniq_ids = TRUE), which is needed for black-boxed functions and + master ipoints of root functions.At least one group must be selected for unique IDs + (it is possible to select several groups). As the number of unique IDs required is + usually low, the group selected for unique IDs is usually the most expensive one. + + Note that the ipoint IDs of all groups should be disjointed. If an ID is present in + multiple groups, a warning will be issued and the ID will be assigned to the first + group in the file in which it appears. + +3.10.4 Example + Assume that you have the following requirements on remapped ipoint IDs: + • Ipoint IDs between 500 and 510, except 505 and 506, are reserved for instru- + mentation of interrupts and the OS. This is the first group of ipoint IDs. + • Availability of a 3-bit output port to which ipoint IDs are written. Therefore, val- + ues in the range 1 to 7 can be written in a single write (0 is a reserved ipoint + ID and cannot be used) and should be used as often as possible. This is the + second group of ipoint IDs. + • When ipoint IDs from the second group are not sufficient for the remapping, + two writes can be used (a 0 followed by a value from 1 to 7), allowing values + between 8 and 14. This is the third group of ipoint IDs. + • When ipoint IDs from any other group are not sufficient for the remapping, use + values between 1 and 511, except for those used by the other groups. This + + +RVS Files Reference Guide vWF20190404 21 +IdPack configuration file RVS configuration files + + + requires 5 writes (two 0s and then three values from 1 to 7). This is the fourth + group of ipoint IDs. + + Also use values from this group whenever a unique ipoint ID is needed (this is + indicated by the line uniq_ids = TRUE). + + These requirements are met using the following IdPack configuration file: + # 1/ Unchanged ipoints + [unchanged] + range = [500..510] - {505, 506} + name = "OS" + + # 2/ Short ipoints (One 3-bit write) + [group short] + range = [1..7] + name = "Short" + + # 3/ Long ipoints (Two 3-bit writes) + [group long] + range = [8..14] + name="Long" + + # 4/ Very_Long ipoints (Five 3-bit writes) + [group very_long] + range = (([1..511] - [1..14]) - [500..510]) + {505, 506} + name="Very_Long" + uniq_ids = TRUE + Note that, during the remapping performed by xstutils, the ipoint routine in the + source code is appended with the name specified by the group. For example, + if the remapped ID of an ipoint is taken from the fourth group, then the ipoint + routine appears as RVS_I_Very_Long in the source code once xstutils has + completed. + + Important + + You must ensure that there is an implementation of every wrapper in the in- + strumentation library (e.g. RVS_E, RVS_C...) for each group. + + +22 RVS Files Reference Guide vWF20190404 +RVS configuration files Warning list + + +3.11 Warning list +3.11.1 Usage + Warning lists specify RVS warnings to ignore when running RVS. + +3.11.2 Format/encoding + Text, ASCII. + +3.11.3 Syntax + In warning files, each warning identifier is listed on a separate line, and comments + can be included using #, as shown in the example below: + + W64003 # ignore function pointer warnings + + +RVS Files Reference Guide vWF20190404 23 +RVS global configuration file (rvsconfig.ini) RVS configuration files + + +3.12 RVS global configuration file (rvsconfig.ini) +3.12.1 Usage + An RVS global configuration file contains licensing and advanced tool settings for + all installations of RVS on the system. For information on configuring these files, + see the RVS Installation and Licensing Guide. + +3.12.2 Format/encoding + Text, ASCII. + +3.12.3 Syntax + rvsconfig.ini contains settings as key-value pairs in an INI file format, as in + the following example: + + [server] + server_addr=123.123.123.123 + server_port=12345 + + +24 RVS Files Reference Guide vWF20190404 +4 RVS output files + RVS output files are generated from running RVS, either through the RVS Project + Manager or rvsdriver. These files are the main products from RVS and are used + to view and report on results. + +4.1 Summary + RVS includes the intermediate files shown in Table 4.1. Each of these is described + in detail later in this chapter. + + Table 4.1 Output file types + File type Usage + RVS report database file Stores results from RVS analysis + RapiTest export file Stores results from RapiTest analysis for use in fi- + nal reports and certification + RapiCover txt export file Stores results from RapiCover analysis for use in + final reports and certification (plain text format). + RapiCover srchtml export file Stores results from RapiCover analysis for use in + final reports and certification (HTML format). + RapiTime export file Stores results from RapiTime analysis for use in + final reports and certification + + +RVS Files Reference Guide vWF20190404 25 +RVS report database file (*.rvd) RVS output files + + +4.2 RVS report database file (*.rvd) +4.2.1 Usage + RVD files are the main product of RVS integrations. These files may contain struc- + tural information about the source code and verification metrics collected from + running code instrumented for coverage, timing and scheduling analysis. + +4.2.2 Format/encoding + Custom. + +4.2.3 Syntax + Report files should not be edited directly. The contents of report files can be viewed + (and in some cases edited) using the RVS Project Manager. + + Some integrations may include custom components that interact with report files. + These are only valid for a specific release of RVS. + + To provide results from RVS analysis to external sources, exporters should be used + to generate export files. + + +26 RVS Files Reference Guide vWF20190404 +RVS output files RapiTest export file + + +4.3 RapiTest export file +4.3.1 Usage + RapiTest export files are produced by exporting test results from an RVD file using + the --export command of rvsdriver or through the RVS Project Manager. The + format of these files is suitable for the use of RapiTest in a qualified testing process. + +4.3.2 Format/encoding + Text, ASCII. + +4.3.3 Syntax + RapiTest export files are organized into hierarchical sections containing data lists + and data tables. + + Some tables use specific terminology for data columns as follows: + • File – this shows the spreadsheet or RTS file for suites and tests, or the + source file for subprograms tested. For tests written in the Spreadsheet Test + Format, both the workbook and worksheet are shown, separated by a colon, + for example tests.xlsx:Test Absolute. + • Location – this shows the location of a test, assert or subprogram in a + source file, spreadsheet or RTS file. For subprograms in a source file, this is + shown as the lines of the source file where the subprogram is defined. For + tests and asserts in a spreadsheet, this is shown as a column and row value, + for example G16 For tests and asserts in an RTS file, this is shown as the lines + of the RTS file where the test or assert is defined, for example 42. + • Passed – this shows the number of tests or asserts that passed. + • Failed – this shows the number of tests or asserts that failed. + • Unreached – this shows the number of tests or asserts that could not be + reached (for example due to a test aborting after previous asserts failed). + • Check – this shows asserts specified during a test. For asserts that failed, + additional information is given that describes it may have failed, for example + FAIL: Value observed for return = -9. + Suite summary + + This section contains a summary of how many tests passed, failed and were not + reached in each suite tested in the exported RVD. + + For information on the data reported, see Section 4.3.3: Syntax. + Example 4.1: Suite summary + = Suite_summary = + + File Location Suite name Passed Failed Unreached + tests.xlsx Rapita 57 3 6 + + +RVS Files Reference Guide vWF20190404 27 +RapiTest export file RVS output files + + + Subprogram summary + + This section contains a summary of how many test passed, failed and were not + reached in each subprogram tested in the exported RVD. + + For information on the data reported, see Section 4.3.3: Syntax. + + Example 4.2: Subprogram summary + + = Subprogram_summary = + + File Location Subprogram Name Passed Failed ... + mathematics.adb 21-50 mathematics.add_one 10 1 ... + mathematics.adb 53-84 mathematics.subtract_one 8 1 ... + mathematics.adb 87-90 mathematics.negate 6 0 ... + + + Test summary + + This section lists each test in the exported RVD, and how many asserts passed, + failed and were unreached in each. + + For information on the data reported, see Section 4.3.3: Syntax. + + Example 4.3: Test summary + + = Test_summary = + + File Location Test Name Passed Failed Unreached + tests.xlsx:Test Absolute G16 Zero 2 0 0 + tests.xlsx:Test Absolute H16 Positive 2 0 0 + tests.xlsx:Test Absolute I16 Negative 2 0 0 + + + Check summary + + This section lists each assert in the exported RVD, and whether it passed, failed + or was unreached. + + For information on the data reported, see Section 4.3.3: Syntax. + + Example 4.4: Check summary + + = Check_summary = + + File Location Check Passed Failed ... + tests.xlsx:Test Absolute G16 Zero finishes 1 0 ... + tests.xlsx:Test Absolute G19 return == 0 1 0 ... + tests.xlsx:Test Absolute H16 Positive finishes 1 0 ... + + + RVD information + + This section contains data about the RVD data was extracted from. + + +28 RVS Files Reference Guide vWF20190404 +RVS output files RapiTest export file + + + Example 4.5: RVD information + + = RVD_Information = + + RVD filename: unittest.rvd + Tool version v3.7 build 1092651 + Created: 2018-01-08 15:47:20 + Last modified: 2018-01-08 15:47:20 + By user: rapita@rapita-PC + + +RVS Files Reference Guide vWF20190404 29 +RapiCover export file (*.txt) RVS output files + + +4.4 RapiCover export file (*.txt) +4.4.1 Usage + RapiCover TXT export files are produced by exporting coverage results from an + RVD file using the --export command of rvsdriver or through the RVS Project + Manager, when the export is configured in the txt format. The format of these + files is suitable for the use of RapiCover in a qualified testing process. + +4.4.2 Format/encoding + Text, ASCII. + +4.4.3 Syntax + RapiCover txt export files are organized into hierarchical sections containing da- + ta lists, data tables and in some cases relevant source code. + + Some tables use specific terminology for data columns as follows: + • Req – shows how many individual elements are required for 100% coverage + of a coverage type in a specific file, function, or overall throughout the report. + This is listed as a numerical value. + • Unk – shows how many elements are not instrumented or otherwise ad- + dressed for the given coverage type in a specific file, function, or overall + throughout the report. This is listed as a numerical value. + • Adr – shows how many elements are addressed (covered by RapiCover jus- + tifications) for the given coverage type in a specific file, function, or overall + throughout the report. This is listed as a numerical value and a percentage. + • Cov – shows how many elements are covered by tests for the given coverage + type in a specific file, function, or overall throughout the report. This is listed + as a numerical value and a percentage. + • Total – shows how many elements are either covered by tests or addressed + by RapiCover justifications for the given coverage type in a specific file, func- + tion, or overall throughout the report. This is listed as a numerical value and + a percentage. + + Percentage values are rounded according to the rounding rationale specified in + the export settings. + + The remainder of this section explains the contents of various sections of the text + export. + + RVD information + + This section contains data about the RVD data was extracted from. + + +30 RVS Files Reference Guide vWF20190404 +RVS output files RapiCover export file (*.txt) + + + Example 4.6: RVD information + + = RVD_Information = + + RVD filename: coverage.rvd + Tool version v3.7 build 1092651 + Created: 2018-01-08 15:47:20 + Last modified: 2018-01-08 15:47:20 + By user: rapita@rapita-PC + + + Overall coverage + + This section contains an overall summary of the coverage required and achieved + for each coverage element analyzed (e.g. COV_FUNCTIONS, see Chapter 6 in + the RVS Annotations Reference Guide), throughout all source files (*). + + The coverage for each element is shown as a table showing coverage achieved + throughout all tests in the RVD used to generate the export file. + + For information on the column headers used for coverage reporting, see Sec- + tion 4.4.3: Syntax. + + + Example 4.7: Overall coverage + + = Overall_Coverage = + + == Table COV_FUNCTIONS == + + File All Tests + Req Unk Adr Cov Total + * 3 3 0 1 1 + 0% 33% 33% + + + File coverage + + This section contains a summary of the coverage required and achieved for each + coverage element analyzed (e.g. COV_FUNCTIONS, see Chapter 6 in the RVS + Annotations Reference Guide) for each source file, and overall. + + The coverage for each element is shown as a table showing coverage achieved + through tests for each source file (e.g. coverage.c) and all source files (*). The + table lists file coverage results throughout all tests, and per individual test included + in the RVD used to generate the export file. + + For information on the column headers used for coverage reporting, see Sec- + tion 4.4.3: Syntax. + + +RVS Files Reference Guide vWF20190404 31 +RapiCover export file (*.txt) RVS output files + + + Example 4.8: File coverage + + = File_Coverage = + + == Table COV_FUNCTIONS == + + File All Tests Test 1 + Req Unk Adr Cov Total Cov + coverage.c 3 3 0 1 1 1 + * 3 3 0 1 1 + 0% 33% 33% + + + Detailed coverage + + This section contains details of the coverage required and achieved for each cov- + erage element analyzed (e.g. COV_FUNCTIONS, see Chapter 6 in the RVS Anno- + tations Reference Guide), throughout all source files (*). + + The coverage for each element is shown as a table showing coverage achieved + in each file (e.g. coverage.c) through tests for each individual element (e.g. + fun0), and summed across the source file (*). The table lists detailed coverage + results throughout all tests, and per individual test included in the RVD used to + generate the export file. + + For information on the column headers used for coverage reporting, see Sec- + tion 4.4.3: Syntax. + + Example 4.9: File coverage + + = File_Coverage = + + == Table COV_FUNCTIONS == + + File Subprogram All Tests Test 1 + Req Unk Adr Cov Total Cov + coverage.c S34 fun0 1 1 0 0 0 0 + coverage.c S1 fun1 1 1 0 1 1 1 + coverage.c S37 fun2 1 1 0 0 0 0 + coverage.c * 3 3 0 1 1 1 + 0% 33% 33% + + + Remaining items + + This contains a list of each item that is not covered by tests, grouped by by + coverage type, for example decision coverage. For each such item, the File, + Subprogram, Lines of source code and missing element (Required) are + listed, along with any Justifications that apply to the item, and a copy of + the source code. + + Items that are missing as a consequence of a parent element being missing are + shown in a Consequent missing coverage subsection. For example, if a branch + was not tested, elements that are missing because of this are shown, see the + example below. + + +32 RVS Files Reference Guide vWF20190404 +RVS output files RapiCover export file (*.txt) + + + Example 4.10: Remaining items + + = Remaining_items = + + == Missing decision coverage == + + ID File Subprogram Lines Required Justification + + 6 coverage.c fun1 30-33 BranchF Cannot be tested + + Source code: + 30 if (x) + 31 {RVS_I(16);} + 32 else + 33 {/* Unknown Call + Statement */ fun0();} + + == Consequent missing coverage == + + Lines ID Missing Values Justification + 33-33 15 statement coverage Statement + 33-33 33 call coverage Call + + +RVS Files Reference Guide vWF20190404 33 +RapiCover export file (*.html) RVS output files + + +4.5 RapiCover export file (*.html) +4.5.1 Usage + RapiCover srchtml export files are produced by exporting coverage results from + an RVD file using the --export command of rvsdriver or through the RVS Project + Manager, when the export is configured in the srchtml format. The format of + these files is suitable for the use of RapiCover in a qualified testing process. + +4.5.2 Format/encoding + Text, HTML. + +4.5.3 Syntax + RapiCover srchtml export files are organized into sections showing: + • RVD information + • Configuration settings + • Coverage summary + • Coverage report + • Justifications + • Justified element statistics + + Percentage values are rounded according to the rounding rationale specified in + the export settings. + + RVD information + + This section contains data about the RVD that data was extracted from. + + + Figure 4.1: RapiCover srchtml export – RVD information + + Configuration settings + + This section displays configuration settings applied to the RVS integration used to + produce the export, see Figure 4.2. + + This section is not displayed by default. To display it, click Configuration. + + +34 RVS Files Reference Guide vWF20190404 +RVS output files RapiCover export file (*.html) + + + Figure 4.2: RapiCover srchtml export – configuration settings + + Coverage summary + + This section contains a summary of the coverage data collected for each source + file analyzed and displays the coverage profile that was used to collect data. This + summary includes data on each type of coverage that was analyzed, per the in- + strumentation assigned to the source code. Elements shown in green are fully + covered, while those shown in red are not. + + + Figure 4.3: RapiCover srchtml export – coverage summary + + Hovering over a column header in the table shows a tooltip describing the data + shown in that column. + + By default, this section shows coverage data per source file. To view information + for each subprogram analyzed, click Show/Hide subprogram coverage. + + + Figure 4.4: RapiCover srchtml export – + coverage summary including subprograms + + +RVS Files Reference Guide vWF20190404 35 +RapiCover export file (*.html) RVS output files + + + Coverage report + + This section shows detailed information on the coverage data collected for a file + in the source code analyzed. RapiCover srchtml exports include a single cov- + erage report section per source file analyzed. + + This section is not shown by default. To show it, click on the name of a source file + from the export's home page. If the home page is not displayed, first return to it + by clicking the up button. + + The coverage report includes two sections; Subprogram Coverage and Source + Coverage. + + Subprogram Coverage + This section shows a summary of the coverage data collected for the source file + being viewed, including data for each function analyzed. This summary includes + data on each type of coverage that was analyzed, per the instrumentation as- + signed to the source code. Elements shown in green are fully covered, while those + shown in red are not. + + + Figure 4.5: RapiCover srchtml export – subprogram coverage + + Clicking on one of the subprograms listed in the Subprogram Coverage section + of the coverage report jumps to that section in the Source Coverage section of + the coverage report. + + Source Coverage + This section shows code from the source file analyzed by RVS, along with inline + elements showing the coverage achieved for each line in the file. The table at the + top of the section shows a legend describing the meaning of each of the inline + elements. + + In the margin, elements shown in green are fully covered, while those shown in red + are not. If the source line was not fully covered per the applied instrumentation, + it is highlighted in red. + + +36 RVS Files Reference Guide vWF20190404 +RVS output files RapiCover export file (*.html) + + + Figure 4.6: RapiCover srchtml export – source coverage + + If RapiCover justifications have been used to manually mark code as covered by + analysis, the justification file and description is shown after the line(s) of code that + were justified. These are highlighted in blue, see Figure 4.7. + + + Figure 4.7: RapiCover srchtml export – justification in source coverage + + If MC/DC analysis was applied, the Source Coverage section of coverage reports + shows MC/DC tables after each line of code containing an MC/DC decision that + was not fully covered, see Figure 4.8. + + + Figure 4.8: RapiCover srchtml export – + MC/DC vectors table (uncovered decision) + + +RVS Files Reference Guide vWF20190404 37 +RapiCover export file (*.html) RVS output files + + + The decision for which MC/DC coverage is missing is highlighted in red. The table + lists observed and missing vectors for each condition (e.g. C1, C2) in the decision, + as well as the result. In the table, T represents true, F represents false, and + ? represents unknown. + + Justifications + + This section lists any RapiCover justifications that have been applied to the ana- + lyzed source code. For each justification applied, the source location justified is + listed, as well as the justification file, title, description, and the coverage element(s) + justified, see Figure 4.9 + + + Figure 4.9: RapiCover srchtml export – justifications + + This section is not displayed by default. To display it, click View Justifications + from the export's home page. If the home page is not displayed, first return to it + by clicking the up button. + + Justified element statistics + + This section shows a summary of the RapiCover justifications applied to the source + code, categorized by type of coverage element justified. Each section includes a + table showing the number of justifications applied in each subprogram of each + file analyzed, see Figure 4.10. + + +38 RVS Files Reference Guide vWF20190404 +RVS output files RapiCover export file (*.html) + + + Figure 4.10: RapiCover srchtml export – justified elements + + This section is not displayed by default. To display it, click View Justified element + statistics from the export's home page. If the home page is not displayed, first + return to it by clicking the up button. + + +RVS Files Reference Guide vWF20190404 39 +RapiTime export file (*.txt) RVS output files + + +4.6 RapiTime export file (*.txt) +4.6.1 Usage + RapiTime export files are produced by exporting timing results from an RVD file + using the --export command of rvsdriver or through the RVS Project Manager. + The format of these files is suitable for the use of RapiTime in a qualified testing + process. + +4.6.2 Format/encoding + Text, ASCII. + +4.6.3 Syntax + RapiTime export files are organized into hierarchical sections containing data lists + and data tables. + + Some tables use specific terminology for data columns or rows. Tables that report + timing data show the following: + • Min – shows minimum execution time values for a context itself, for just the + subprograms called by the context, or overall (the sum of self and sub + values). These are listed as numerical values. + • Avg – shows average (mean) execution time values for a context itself, for + just the subprograms called by the context, or overall (the sum of self and + sub values). These are listed as numerical values. + • Max – shows maximum execution time values for a context itself, for just + the subprograms called by the context, or overall (the sum of self and sub + values). These are listed as numerical values. + • HWM – shows high-water mark execution time values for a context itself, for + just the subprograms called by the context, overall (the sum of self and + sub values), and how many times the context was executed on the high-water + mark path (freq). These are listed as numerical values. + • HWMC – shows high-water mark contribution time values for a context itself, + for just the subprograms called by the context, or overall (the sum of self + and sub values). These are listed as percentage values. + • WCET – shows worst-case execution time values for a context itself, for just + the subprograms called by the context, overall (the sum of self and sub + values), and how many times the context was executed on the worst-case path + (freq). These are listed as numerical values. + • WCC – shows worst-case contribution time for a context itself, for just the + subprograms called by the context, or overall (the sum of self and sub + values). These are listed as percentage values. + • Tests – shows how many times a context was executed during tests. This + is listed as a numerical value. + + +40 RVS Files Reference Guide vWF20190404 +RVS output files RapiTime export file (*.txt) + + + Tables that report data on tested blocks show the following: + • Blocks – shows how many blocks are in the specified context. This is listed + as a numerical value. + • T-Blocks – shows how many of the blocks in the specified context were + tested. This is listed as a numerical value. + • T-Blocks% – shows what percentage of the blocks in the specified context + were tested. This is listed as a percentage value. + + Tables that report structural data show the following: + • #LOC – shows how many lines of code are in a subprogram. This is listed as + a numerical value. + • #stmt – shows how statements are in a subprogram. This is listed as a nu- + merical value. + • #loops – shows how many loops are in a subprogram. This is listed as a + numerical value. + • #conditionals – shows how many conditions are in a subprogram. This + is listed as a numerical value. + • #calls – shows how many calls are in a subprogram. This is listed as a + numerical value. + + Percentage values are rounded according to the rounding rationale specified in + the export settings. + + Throughout RapiTime export files, subprograms and contexts that were black- + boxed to avoid recursion are listed with a prefix of BB before the subprogram or + context name. + + The remainder of this section explains the contents of various sections of the text + export. + + Root summary + + This section contains a summary of the timing data collected for each call tree + root analyzed. + + For information on the data reported, see Section 4.6.3: Syntax. + + Example 4.11: Root summary + + = Root_summary = + + Min Min + Min ... + File Lines Context self sub + overall ... + mathematics.c 9-24 mathematics.self_test-U*-* 3 5 + 8 ... + + +RVS Files Reference Guide vWF20190404 41 +RapiTime export file (*.txt) RVS output files + + + Tested blocks summary + + This section contains a summary of the number of blocks throughout all context + (*-*) in all source files analyzed (*), and how many of these were tested. + + For information on the data reported, see Section 4.6.3: Syntax. + + Example 4.12: Tested blocks summary + + = Tested_blocks_summary = + + File Lines Context Blocks T-Blocks T-Blocks% + * 0-0 *-* 41 38 93% + + + Timing data + + This section contains detailed timing data on each context in each source file. + + For information on the data reported, see Section 4.6.3: Syntax. + + Example 4.13: Timing data + + = Timing_data = + + Min Min Min ... + File Lines Context self sub overall ... + mathematics.adb 99-105 mathematics.absolute-U 3 0 3 ... + mathematics.adb 27-56 mathematics.add_one-U 4 0 5 ... + mathematics.adb 93-96 mathematics.negate-U 0 0 0 ... + + + Tested blocks + + This section contains data on the number of blocks in each context and how many + of these were tested. + + For information on the data reported, see Section 4.6.3: Syntax. + + Example 4.14: Tested blocks + + = Tested_blocks = + + File Lines Context Blocks T-Blocks ... + mathematics.adb 99-105 mathematics.absolute-U 5 4 ... + mathematics.adb 27-56 mathematics.add_one-U 15 14 ... + mathematics.adb 93-96 mathematics.negate-U 1 1 ... + + + Structural data + + This section contains structural data about the source code that was analyzed. + + Structural data is listed for each subprogram in each file that was analyzed. + + For information on the data reported, see Section 4.6.3: Syntax. + + +42 RVS Files Reference Guide vWF20190404 +RVS output files RapiTime export file (*.txt) + + + Example 4.15: Structural data + + = Structural_data = + + File Lines Subprogram #LOC #stmt #loops ... + mathematics.adb 99-105 mathematics.absolute 4 0 0 ... + mathematics.adb 27-56 mathematics.add_one 6 3 0 ... + mathematics.adb 93-96 mathematics.negate 3 1 0 ... + + + RVD information + + This section contains data about the RVD data was extracted from. + + For information on the data reported, see Section 4.6.3: Syntax. + + Example 4.16: RVD information + + = RVD_Information = + + RVD filename: timing.rvd + Tool version v3.7 build 1092651 + Created: 2018-01-08 15:47:20 + Last modified: 2018-01-08 15:47:20 + By user: rapita@rapita-PC + + +RVS Files Reference Guide vWF20190404 43 +This page intentionally left blank +5 RVS intermediate files + This chapter describes the intermediate file formats generated by RVS. These files + are created during RVS integrations and should not be edited. + +5.1 Summary + RVS includes the intermediate files shown in Table 5.1. Each of these is described + in detail later in this chapter. + + Table 5.1 Intermediate file types + File type Usage + Call tree annotation file Controls RVS instrumentation + Exchange file Exchanges ipoint information between multiple ex- + ecutions of RVS instrumenters. + Function pointer resolution file Lists function pointers that were automatically re- + solved. + Map file Stores coverage or unit test data. + Recursion resolution file Lists functions that were automatically black + boxed to handle recursion. + Trace file Stores execution time data. + Temporary cache file Stores intermediate outputs to increase perfor- + mance. + Source code structure file Stores the structural hierarchy of source files. + + +RVS Files Reference Guide vWF20190404 45 +Call tree annotation file (*.ctree) RVS intermediate files + + +5.2 Call tree annotation file (*.ctree) +5.2.1 Usage + + Note + + Call tree annotation files let you produce instrumentation annotations for a + specific call tree, but other, easier methods are available to do this. + + The recommended way to do so is to refine your analysis using the Analysis + tab, as described in the RVS User Guide. + + Call tree annotation files contain instrumentation annotations for a specific call + tree. They can be generated by calling xstutils manually, see Chapter 21 in the + RVS Command Line Tools Reference Guide. + + After generating a call tree annotation file, the file must be included in the source + code before calling the RVS instrumenters through the command-line or via the + RVS Project Manager. For more information on RVS annotations, see the RVS + Annotations Reference Guide. + +5.2.2 Format/encoding + Ada, C or C++ source files with RVS annotations. + +5.2.3 Syntax + Call tree annotation files are written in the RVS annotation file format. For informa- + tion on the syntax of annotation files, see the RVS Annotations Reference Guide. + + +46 RVS Files Reference Guide vWF20190404 +RVS intermediate files Exchange file (*.exf) + + +5.3 Exchange file (*.exf) +5.3.1 Usage + Exchange files are used to exchange information between several executions of + an RVS instrumenter. They record the ipoint numbers allocated during instrumen- + tation, allowing the instrumenter to ensure unique ipoint numbering across multi- + ple builds. + +5.3.2 Format/encoding + Binary, internal format. + +5.3.3 Syntax + You should not need to read or edit exchange files. If you need to do so, contact + support@rapitasystems.com. + + +RVS Files Reference Guide vWF20190404 47 +Function pointer resolution file + RVS intermediate files +(rvs_autores_fptr.txt) + +5.4 Function pointer resolution file + (rvs_autores_fptr.txt) +5.4.1 Usage + When you use covparser or timeparser with a trace generated by a program + that uses indirect calls (e.g. function pointers, subprogram accesses or dynamic + dispatch), the file rvs_autores_fptr.txt is automatically generated. + + This file contains call_to annotations reflecting indirect calls that have been de- + tected from the trace. It only records indirect calls that were not already accounted + for in existing call_to annotations, and it only creates the file when there is at + least one new call_to annotation. + + Note + + Function pointer resolution files are temporary files. When they are generat- + ed, you should review their content and copy any appropriate annotations + to annotation files used in your project. + + +5.4.2 Format/encoding + Text, ASCII. + +5.4.3 Syntax + Function pointer resolution files contain two sections. + + The first section, at the top of the file, contains a list of RVS annotations suitable + to resolve function pointers in the source code. For each function pointer that was + observed, the trace file and source location is first specified, then the annotation + is specified on the next line as in the following example: + /* Trace .\rvs_trace.txt element 6 - src\mathematics.c:94 */ + #pragma RVS default_call_to ("*pointer","negate","*"); + + The second section, at the bottom of the file, contains information about the op- + eration that produced the function pointer resolution file. + + +48 RVS Files Reference Guide vWF20190404 +RVS intermediate files Map file (various extensions) + + +5.5 Map file (various extensions) +5.5.1 Usage + Map files store coverage or unit test data collected by RVS in a format suitable + for processing by RVS tools. Sometimes, map data must be filtered before being + processed by RVS tools. + + Data collection in the map file format is implemented by an RVS integration library. + This is described in the RVS Integration Library Implementation Guide. + + The following map file formats can be operated on by RVS: + .txt + .dt1 + .dt2 + .rpz + .bin + .srec + .tla + .tld + .t32 + .aar + + +5.5.2 Format/encoding + Binary. + +5.5.3 Syntax + You should not need to read or edit map files directly. The map file format is de- + scribed in the RVS Integration Library Implementation Guide. + + +RVS Files Reference Guide vWF20190404 49 +Recursion resolution file (rvs_autores_bbox.txt) RVS intermediate files + + +5.6 Recursion resolution file (rvs_autores_bbox.txt) +5.6.1 Usage + When RVS identifies simple recursion in the source code structure, it automatically + produces a recursion resolution file. This file cuts the call tree at the point where + the recursive function calls itself so that the calling hierarchy can be processed. + + Note + + rvs_autores_bbox.txt is a temporary file. When it is generated, you + should review its content and copy annotations you need from it to your + project's annotation file. + + +5.6.2 Format/encoding + Text, ASCII. + +5.6.3 Syntax + Recursion resolution files contain two sections. + + The first section, at the top of the file, contains a list of RVS annotations suitable to + resolve recursion in the source code. One annotation is displayed per line in the + file as in the following example: + #pragma RVS black_box_inline ("fun1","fun2"); + + The second section, at the bottom of the file, contains information about the op- + eration that produced the recursion resolution file. + + +50 RVS Files Reference Guide vWF20190404 +RVS intermediate files Trace file (various extensions) + + +5.7 Trace file (various extensions) +5.7.1 Usage + Trace files store execution time data collected by RVS in a format suitable for + processing by RVS tools. Sometimes, trace data must be filtered before being + processed by RVS tools. + + Data collection in the trace file format is implemented by an RVS integration library. + This is described in the RVS Integration Library Implementation Guide. + +5.7.2 Format/encoding + Text, ASCII. + +5.7.3 Syntax + You should not need to read or edit trace files directly. The trace file format is + described in the RVS Integration Library Implementation Guide. + +5.7.4 Trace file formats + The following trace file formats can be operated on by RVS: + + .txt + .dt1 + .dt2 + .rpz + .bin + .srec + .tla + .tld + .t32 + .aar + + + These formats are described below. + + .txt + + Displays the ipoint number and timestamp in text form. + + The following example shows how data for three ipoints is displayed in this format: + ipoint 1 at time 871, ipoint 2 at time 872 and ipoint 3 at time 874: + 1 871 + 2 872 + 3 874 + + + Output may be in either decimal or hexadecimal values depending on the filtering + options used, see the RVS Filters Guide. .txt files may include comments at the + end of each line, preceded by a #. + + +RVS Files Reference Guide vWF20190404 51 +Trace file (various extensions) RVS intermediate files + + + .dt1 + + Displays the ipoint number and time delta from the previous ipoint with an optional + first line specifying the timestamp for the first ipoint in the trace. If no first line is + present, the start time is assumed to be zero. + + The following example shows how data for three ipoints is displayed in this format: + ipoint 1 at time 871, ipoint 2 at time 872 and ipoint 3 at time 874: + [871] + 1 ( 0 ) + 2 ( 1 ) + 3 ( 2 ) + + Output may be in either decimal or hexadecimal values depending on the filtering + options used, see the RVS Filters Guide. .dt1 files may include comments at the + end of each line, preceded by a #. + + .dt2 + + Displays the ipoint number and time delta to the next ipoint with an optional first + line specifying the timestamp for the first ipoint in the trace. If no first line is present, + the start time is assumed to be zero. + + The following example shows how data for three ipoints is displayed in this format: + ipoint 1 at time 871, ipoint 2 at time 872 and ipoint 3 at time 874: + [871] + 1 ( 1 ) + 2 ( 2 ) + 3 ( 0 ) + + Output may be in either decimal or hexadecimal values depending on the filtering + options used, see the RVS Filters Guide. .dt2 files may include comments at the + end of each line, preceded by a #. + + .rpz + + RVS compressed trace format. This format is a lossless, compressed encoding + and is considered the native format of RVS because of its efficiency. + + .bin + + Raw, uncompressed binary format. + + This format can only be interpreted as RVS trace data if a byte_reader filter is + used; for more information, see Section 3.3.1 in the RVS Filters Guide. + + .srec + + Raw binary format, encoded as Motorola S-Records. + + +52 RVS Files Reference Guide vWF20190404 +RVS intermediate files Trace file (various extensions) + + + This format can only be interpreted as RVS trace data if a byte_reader filter is + used; for more information, see Section 3.3.1 in the RVS Filters Guide. + + .tla .tld .t32 .aar + + Text format output files created by third-party data capture tools. + + These are legacy file formats for backward compatibility. + + +RVS Files Reference Guide vWF20190404 53 +Temporary cache file (various extensions) RVS intermediate files + + +5.8 Temporary cache file (various extensions) +5.8.1 Usage + To increase performance, RVS caches some intermediate outputs. These cached + files are stored in the RVS_TEMP directory. + + Periodically when an RVS tool is run, cached files older than a certain period are + deleted. Intermediate representations of project code structures are deleted if they + are older than 72 hours. All other cached files are deleted if they are older than + 12 hours. + + The table below shows where RVS_TEMP can be found on different operating + systems. In each case the user has their own unique directory. + + Operating System Directory Path + Windows XP %USERPROFILE%\Local Settings\Temp\RVS_TEMP + Windows Vista, 7 & 8 %USERPROFILE%\AppData\Local\Temp\RVS_TEMP + Linux $TMP/RVS_TEMP/ + + +5.8.2 Format/encoding + Various, depending on the file. + +5.8.3 Syntax + You should not need to read or edit temporary cache files. If you need to do so, + contact support@rapitasystems.com. + + +54 RVS Files Reference Guide vWF20190404 +RVS intermediate files Source code structure file (*.xsc) + + +5.9 Source code structure file (*.xsc) +5.9.1 Usage + XSC files contain information about the structure of the source code in a project + and the instrumentation applied to it. These are produced by a command-line tool + that instruments the source code. When all XSC files have been generated, these + are linked together to produce an RVS database (RVD file). Typically, one XSC file + is produced per source file. + +5.9.2 Format/encoding + Binary, internal format. + +5.9.3 Syntax + You should not need to read or edit XSC files. If you need to do so, contact + support@rapitasystems.com. + + +RVS Files Reference Guide vWF20190404 55 +This page intentionally left blank + diff --git a/docs-extracted/src/scov/RVS/doc/Reference/RVS_Filters.md b/docs-extracted/src/scov/RVS/doc/Reference/RVS_Filters.md new file mode 100644 index 000000000..3e5c6eff7 --- /dev/null +++ b/docs-extracted/src/scov/RVS/doc/Reference/RVS_Filters.md @@ -0,0 +1,3000 @@ +--- +title: "Rvs Filters" +source: "./src/scov/RVS/doc/Reference/RVS_Filters.pdf" +category: "src/scov/RVS/doc/Reference" +pages: 62 +extracted: "2026-07-06T23:15:57.654461" +--- + +# Rvs Filters + +> Extracted from `./src/scov/RVS/doc/Reference/RVS_Filters.pdf` (62 pages). +> Figures, diagrams, and tables may not render accurately in plain text. + +Filters Guide + Version WF20190404 +Disclaimer +The information, text, and graphics contained within this document are +provided for information purposes only by Rapita Systems Ltd. Rapita +Systems Ltd. does not warrant the accuracy or completeness of the +information, text, and other items contained in this document. + + +Copyright and Trademarks +All rights reserved. Information and images contained within this doc- +ument are copyright and the property of Rapita Systems Ltd. All trade- +marks are hereby acknowledged to be the properties of their respective +owners. + + +Acknowledgments +Rapita Systems' tools are built using AdaCore's GNAT Pro compiler. + + +Rapita Systems Ltd. +Registered in the UK, number 5011090. +Registered address: +Atlas House +Link Business Park +Osbaldwick Link Road +York +YO10 3JB +UK +Phone: +44 (0) 1904 413 945 +http://www.rapitasystems.com/ +This document copyright © 2017-2019, Rapita Systems Ltd. + +Document build 118520 + +ID: DOC/17029 + Table of Contents + + 1. About this guide ............................................................... 5 + 1.1. Structure of this guide ........................................................... 5 + + 1.2. Notation ............................................................................ 5 + + 1.3. RVS documentation map ........................................................ 6 + + 1.4. Support ............................................................................. 7 + + + 2. What are RVS filters? ........................................................ 9 + 2.1. How RVS filters work ........................................................... 10 + + 2.2. How traceutils works ........................................................... 10 + + 2.3. Trace file formats ................................................................ 10 + + + 3. Writing RVS filters ........................................................... 11 + 3.1. Filter names and configuration options ...................................... 11 + + 3.2. RVS filter commands ........................................................... 13 + + 3.3. Read filter configuration options .............................................. 37 + + 3.4. Pattern replacement ............................................................ 50 + + 3.5. Writing Python filters ............................................................ 57 + + 3.6. Writing C filters .................................................................. 60 + + +RVS Filters Guide vWF20190404 3 +This page intentionally left blank +1 About this guide + This guide explains what RVS filters are and how to write them. It is intended for + users who want to write filters that can be used to convert raw trace data into a + format that RVS can analyze. + +1.1 Structure of this guide + This document includes the following chapters: + + Chapter 1: About this guide + Describes the purpose and layout of the RVS Filters Guide and the notation used + throughout the document. + + Chapter 2: What are RVS filters? + Describes what RVS filters are and how they are used. + + Chapter 3: Writing RVS filters + Describes how to write RVS filters in the RVS filter language, python and C. + +1.2 Notation + This document uses the following notation: + • References to other documents and to other chapters or sections in this doc- + ument are written in italics, for example Chapter 1: About this guide. When + reading an electronic copy of this document, you can click on a reference to + navigate to the location of the referenced element. + • Names of RVS applications are formatted in bold italics, for example RVS + Project Manager. + • References to areas or elements in user interfaces are formatted in italics, for + example the Report Navigator. + • Menus, menu choices and button labels are formatted in bold, for example + File » Print or OK. Where buttons have icons, these are shown before their + Label in in-line text, for example Save. + • Names of RVS tools are formatted in bold, for example rvsdriver. + • References to HTML links appear as underlined text, for example + www.rapitasystems.com. + • Folder and file names are formatted in a monospaced font. + • Command-line tools and their commands, annotations and examples are for- + matted in a monospaced font. These are either written in-line with text + or as separate text blocks. When written in-line with text, they are formatted + + +RVS Filters Guide vWF20190404 5 +RVS documentation map About this guide + + + like the following: rvsdriver, default_instrument, rvs_instr.h. + When written as a separate text block, they are formatted like the examples + below: + rvsdriver --project rvs.rvsprj --all + + #pragma RVS instrument( "function_name", "FALSE" ) + + • When referencing Ada code, the term functions refers to both functions and + procedures. + +1.3 RVS documentation map + This document is part of the Rapita Verification Suite (RVS) document set, which + contains the following documents: + + RVS Installation and Licensing Guide + Describes how to install RVS tools, and licensing options for them. + + RVS Integration Guide + Describes how to integrate RVS tools into build and target environments. + + RVS User Guide + Describes how to set up and run RVS projects, analyze data and export verification + results. + + RapiTest User Guide + Describes how to use RapiTest to manage test projects. + + Spreadsheet Test Format User Guide + Describes how to write tests for RapiTest in the Spreadsheet Test Format. + + RapiCover User Guide + Describes how to use RapiCover to measure code coverage and address cover- + age holes. + + RapiTime User Guide + Describes how to use RapiTime to measure timing metrics including worst-case + execution time, and how to use these metrics to identify the best optimization + candidates. + + RapiTask User Guide + Describes how to use RapiTask to measure system level task timing information, + visualize traces and gain insight into runtime behavior. + + RTBx 2xxx User Guide + Describes how to use the RTBx data logger. + + RVS Integration Library Implementation Guide + Describes how to implement RVS integration libraries. This document is for use by + readers with a thorough understanding of the implementation of RVS. + + +6 RVS Filters Guide vWF20190404 +About this guide Support + + + RVS Files Reference Guide + Describes RVS-specific files including input, intermediate and output files. + + RVS Filters Guide + Describes RVS filters, which are used to convert raw trace data into a format that + RVS can analyze, and how to write them. + + RVS Command Line Tools Reference Guide + Describes the command-line tools used by RVS, including a list of available com- + mand options. + + RVS Annotations Reference Guide + Describes the annotations you can use to control instrumentation and analysis + with RVS. + + RVS Troubleshooting Guide + Describes the error and warning messages you may encounter when using RVS + tools, and how to address them. + + RVS Migration Guide + Describes how to migrate between using different versions of RVS. + +1.4 Support + For support issues, please contact Rapita Systems Ltd. by any of the following + means: + + Email + support@rapitasystems.com + + Telephone + +44 (0) 1904 413 945 + + Website + www.rapitasystems.com + + To register for support, visit www.rapitasystems.com/register. More than one user + can register per license. + + +RVS Filters Guide vWF20190404 7 +This page intentionally left blank +2 What are RVS filters? + RVS filters are small software applications that are used to convert raw data col- + lected from embedded targets into data that RVS can analyze. These filter raw + data to do things such as: + • Extract and convert data fields from each line of data + • Remove data lines + • Add and manipulate error markers + • Manage wall-clock time adjustments + • Demultiplex trace data from multiple concurrent tasks or processes + + Figure 2.1 shows a simple strategy whereby an RVS filter is used to convert raw + data from a memory dump into a format that RVS can analyze. + + + Figure 2.1: Example conversion using an RVS filter + + +RVS Filters Guide vWF20190404 9 +How RVS filters work What are RVS filters? + + +2.1 How RVS filters work + When RVS filters are available, they can be configured as part of converters in + the RVS Project Manager. After doing so, the converter automatically runs the + filter during the Report stage of an RVS integration. To learn more about data + conversion and how to configure filters during an RVS integration, see Chapter 6 + in the RVS Integration Guide. + + RVS filters are executed by an RVS utility called traceutils. It is helpful to know how + this utility works before learning how to write RVS filter files. + +2.2 How traceutils works + traceutils operates on input trace files by executing an RVS filter file. RVS filter files + can include one or more RVS filters written in the RVS filter language, Python, or + C. The utility operates in three distinct stages: + • First, it runs a read filter (see Section 3.2.8) to collect data from input trace + files. This is not explicitly declared in the RVS filter file, it is defined automatically + by traceutils. + • Next, it runs each of the RVS filters specified in the RVS filter file. These are + executed in the order that they appear in the file. + • Finally, it runs the write filter (see Section 3.2.12) to write trace data to the + output file(s). Like the read filter, write is not explicitly declared in the RVS + filter file, it is defined automatically by traceutils. + + For more information on traceutils, see Chapter 20 in the RVS Command Line + Tools Reference Guide. + +2.3 Trace file formats + traceutils operates on input trace files and produces output trace files in a number + of formats. These are described in detail in Section 5.7 in the RVS Files Reference + Guide. + + +10 RVS Filters Guide vWF20190404 +3 Writing RVS filters + Basic RVS filters can be written in the RVS filter language. More complex filtering + operations require the use of Python or C filters. This chapter describes how to + write RVS filters using each of these languages. + + Numeric literals in RVS filter files can be any of: + 1. Zero; + 2. Decimal (not allowed to start with a zero); + 3. C hexadecimal format: preceded by either 0x or 0X and case insensitive; + 4. Ada hexadecimal format: 16## and case insensitive; + In all three cases, Ada-style underscore separators are permitted. For example: + 1_000 + 0x10_0000 + 16#1234_ABCD# + + +3.1 Filter names and configuration options + Some filters used by traceutils have optional and configurable features. These + can be controlled using filter configuration options specified in RVS filter files. + + A filter is normally declared by a single statement, such as: + replace( (10, t), (20, t) ); + To access the configuration options for the filter, it should be assigned to a filter + name as follows: + NN := replace( (10, t), (20, t) ); + The filter name NN is used to refer to this filter at any subsequent location in the + filter file. + + Options for the filter are set as follows: + NN.recursive; + NN.adjust_times; + These configuration options apply only to the named filter. + + A filter name can be any string of letters (a-z), with the exception of words that + are already used as filter commands or keywords. Numbers, symbols and spaces + cannot be used. Names are not case sensitive, so name, Name and NAME are + all equivalent. + + The special filter names read and write can be used to access the configura- + tion options for the read and write filters to be set as follows: + read.reset_start_time; + + +RVS Filters Guide vWF20190404 11 +Filter names and configuration options Writing RVS filters + + read.escape(99); + write.discard_wt; + The options for the write filter are given in Section 3.2.12. The options for the + read filter are listed in Section 3.3. + + Note + + The filter names read and write are not defined in the filter file but are + instead defined automatically by traceutils. read and write cannot be + used as names for user-defined filters. + + +12 RVS Filters Guide vWF20190404 +Writing RVS filters RVS filter commands + + +3.2 RVS filter commands + The filter commands that can be used in RVS filters are shown in the table below. + Each command is described in more detail later in this section. + + Filter Description + bit_pos Indicates that the ipoint ID has been encoded as a bit po- + sition and now needs to be decoded. See Section 3.2.1 + for more information. + concat Indicates that ipoint IDs have been split across multiple + ipoints and now need to be concatenated together again. + See Section 3.2.2 for more information. + demux De-multiplexes trace data into a number of separate files. + See Section 3.2.3 and Section 3.2.4 for more information. + demux_rr De-multiplexes trace data into a number of separate files + in a round robin manner. See Section 3.2.5 for more infor- + mation. + gray Indicates that ipoint IDs are Gray coded, changing exactly + one bit at a time. See Section 3.2.6 for more information. + keep_sequence Preserves an ipoint sub-sequence. See Section 3.2.7 for + more information. + remove Removes specified ipoints from the trace. See Sec- + tion 3.2.9 for more information. + replace Replaces a particular pattern of ipoints with an alternative + pattern. See Section 3.2.10 for more information. + save_metadata, Save and delete all metadata embedded within the trace + restore_metadata (such as build identifiers and test identifiers). The corre- + sponding restore operation undoes this operation, re-in- + serting the saved metadata. See Section 3.2.11 for more + information. + + +3.2.1 bit_pos + Use a bit_pos filter to translate a bit position in a Gray coded trace to the original + ID that was used in the instrumented code. + + A typical on-target implementation of an instrumentation point when using Gray + coding is to encode the original ipoint ID value as a bit position, for example by + shifting a 1 left by ID bits. To translate a trace generated from this implementation + back to the original value, use the bit_pos filter, which replaces ID 1 with ID 1, + 2 with 2, 4 with 3, 8 with 4, 16 with 5 and so on up to bit index 32. + + If more than one bit is set in the input ID, an escape ipoint is generated with the + following fields: the ID is 99, the input timestamp is unchanged, the third data + item is the input ID and the fourth data item is a copy of the input timestamp. This + ensures that no information is lost and allows such ipoints to be easily discarded + using remove( 99 ); if they are not required. + + +RVS Filters Guide vWF20190404 13 +RVS filter commands Writing RVS filters + + + Filter Configuration Options + + The bit_pos filter has no options. + + Example + Example 3.1: Decoding bit position ipoint IDs + + bit_pos; + replace( (i1, t1, i2, t2), (i1, t1) (i2, t2) ); + + + Note + + The replace command in Example 3.1 replaces the escape ipoints (gen- + erated by bit_pos) with a sequence of normal ipoints. For details of the + replace command, see Section 3.2.10. + + Example 3.2: Trace + + before: + 1 1 # bit 1 + 8 2 # bit 4 + 8192 3 # bit 14 + 3 4 # two bits: 1 and 2 + 2 5 # bit 2 + + after: + 1 1 + 4 2 + 14 3 + 99 4 + 3 4 + 2 5 + + +3.2.2 concat(, , , ) + Use concat to concatenate any number of successive ipoint IDs. This is required + when a limited range of output values has forced the RVS_I routine to split an + ID across several ipoints. + + If is set to a numeric value, concatenation is only performed on se- + quences of ipoints starting with that value. Alternatively, can be set to + ".", to concatenate every ipoints. + + The length of the sequence of ipoints to concatenate is given by . On + every new ipoint in the sequence, including any trigger value, the new ipoint ID is + decremented by one and then added to the currently concatenated ipoint multi- + plied by . At the end of the sequence, a new ipoint is synthesized where + the ID is the concatenated value modulo , then incremented by one, and + the timestamp is that of the first ipoint in the concatenated sequence. + + +14 RVS Filters Guide vWF20190404 +Writing RVS filters RVS filter commands + + + Filter Configuration Options + + The following filter configuration options are available for concat: + + keep_finish_time + If this option is set, the synthesized ipoint is extended to make an escape ipoint + where the escaped ID is zero and the escaped timestamp is the timestamp of the + ipoint that finishes the sequence. This can be used to remove the concatenated + ipoint sequence elapsed time from the trace, using the replace filter with the + adjust_times option. + Example + + In Example 3.3, ipoint IDs have been processed by a bit_pos filter and are + restricted to the range 1 to 6. In this example ipoint ID 6 is used to indicate the + start of a sequence of ipoints to be concatenated to form a new ipoint value in + the range 181 to 216. + + The concat filter: concat(6, 3, 6, 216); will match the ipoint 6 and con- + catenate the next two ipoints using the formula: + + New ipoint = 1 + ((([ipoint 6] - 1) * 6 + ([ipoint after 6] - 1)) * 6 + ([2nd ipoint + after 6] - 1)) mod 216. + + The modulo at the end ensures that the ipoint value is less than 216. The config- + uration option keep_finish_time propagates the time associated with ipoint + 6 to the new ipoint while the write.discard_wt option removes the time ad- + justment from the output trace. + Example 3.3: Concatenating ipoint IDs + C := concat( 6, 3, 6, 216 ); + C.keep_finish_time; + replace( (i1, t1, i2, t2), (i1, t1) (i2, t2) ); + write.discard_wt; + + + Example 3.4: Trace + + before: + 1 1 + 2 2 + 6 3 # start of sequence representing 182 + 1 4 # 182 = 1 + ((((6-1) * 6 + (1-1)) * 6 + (2-1)) + 2 5 # % 216) + 3 6 + + after: + 1 1 + 2 2 + 182 3 + 0 5 + 3 6 + + +RVS Filters Guide vWF20190404 15 +RVS filter commands Writing RVS filters + + + Note + + The use of keep_finish_time in Example 3.3 records the end time of + the concatenated sequence as an escaped ipoint with ID 0. The replace + command transforms this into a sequence of two normal ipoints (182 3 + and 0 5 in Example 3.4). + + +3.2.3 demux([,, ]) + Use demux to split a trace into multiple traces. The filter will switch the output of + traceutils to different output files based on a field in an escape ipoint. For more + information on escape ipoints see Section 3.3.3. + + Specify the output filenames using the traceutils command-line option + --outname-template . Each output filename is based on + the filename argument following --outname-template with a number corre- + sponding to inserted between the filename and extension. + + The valid values for are I0, I1, and T1. These correspond to the fields + in an escape ipoint (I0, timestamp, I1, T1). You cannot demultiplex on + the timestamp of the escape ipoint). + + The principle can be illustrated by some examples; each of the following demux + examples use the same input file: + + Example 3.5: demux example input file + + 1 100 + 2 110 + 3 120 + 75 121 + 6 130 + 3 135 + 54 137 + 7 140 + 23 142 + 8 150 + 4 160 + 32 162 + + + The first example simply switches output files based on the escape ipoint ID itself. + + Example 3.6: demux on escape ipoint ID + + read.escape( 3 ); + read.escape( 7 ); + demux( I0 ); + replace( (i1, t1, i2, t2), (i1, t1) (i2, t2) ); + + + Used in conjunction with an outname-template of file.txt, the filter gen- + erates the following output: + + +16 RVS Filters Guide vWF20190404 +Writing RVS filters RVS filter commands + + + Example 3.7: Output + + # in file 'file_3.txt' + 3 120 + 75 121 + 6 130 + 3 135 + 54 137 + + # in file 'file_7.txt' + 7 140 + 23 142 + 8 150 + 4 160 + 32 162 + + + Note that the trace data associated with ipoints 1 and 2 are discarded since they + appear before any of the escape ipoints. + + Using the same input file as before, the second example switches output files + based on the I1 value: + + Example 3.8: demux on I1 field + + read.escape( 3 ); + read.escape( 7 ); + demux( I1 ); + replace( (i1, t1, i2, t2), (i1, t1) (i2, t2) ); + + + Example 3.9: Output + + # in file 'file_75.txt' + 3 120 + 75 121 + 6 130 + + # in file 'file_54.txt' + 3 135 + 54 137 + + # in file 'file_23.txt' + 7 140 + 23 142 + 8 150 + 4 160 + 32 162 + + + Using T1 instead of I1 has a similar effect, but is only useful when T1 has been + used as an additional data item rather than a timestamp. + + If it is necessary to limit the ipoints used as demultiplexer triggers, the and arguments can be used to qualify the demultiplexer operation: + demux(I1,I0,value) translates to ' demultiplex based on I1 when I0 is + equal to value'. + + +RVS Filters Guide vWF20190404 17 +RVS filter commands Writing RVS filters + + + Example 3.10: Limiting demux scope + + read.escape( 3 ); + read.escape( 7 ); + demux( I1, I0, 3 ); + replace( (i1, t1, i2, t2), (i1, t1) (i2, t2) ); + + + The above filter definition produces the following output: + + Example 3.11: Output + + # in file 'file_75.txt' + 3 120 + 75 121 + 6 130 + + # in file 'file_54.txt' + 3 135 + 54 137 + 7 140 + 23 142 + 8 150 + 4 160 + 32 162 + + + It is also possible to use bit ranges from each of the fields by using the square- + bracket notation seen in the byte_reader command (Section 3.3.1): + + Example 3.12: Use of bit fields + + read.escape( 3 ); + read.escape( 7 ); + read.escape( 4 ); + # demultiplex based on odd-numbered I1 field + demux( I0, I1[0:0], 1 ); + replace( (i1, t1, i2, t2), (i1, t1) (i2, t2) ); + + + Example 3.13: Output + + # in file 'file_3.txt' + 3 120 + 75 121 + 6 130 + 3 135 + 54 137 + + # in file 'file_7.txt' + 7 140 + 23 142 + 8 150 + 4 160 + 32 162 + + +18 RVS Filters Guide vWF20190404 +Writing RVS filters RVS filter commands + + + Note + + The demux filter is designed to work in situations where context switches + occur relatively infrequently, and by default uses a large internal buffer to + store trace elements. If you use a demux filter on a trace with frequent con- + text switches, the overhead associated with switching the buffer can have a + significant impact on performance. + + To improve the performance in these situations, you can reduce the buffer + size, as shown in the following example: + d := demux(); + d.buffer_size(); + + + The default buffer size is 50,000 elements. In cases where the trace switch- + es output every few elements, you will see improved performance using a + much smaller buffer (e.g. 16). + + +3.2.4 demux() + The demux filter splits system-level traces into task-level traces. A system-level + trace includes trace data from the operating system, the scheduler, interrupt han- + dlers and all application tasks. The demux filter reduces this to a single trace for + each task. + + The demux filter will switch the output of traceutils to different output files by rec- + ognizing certain special events in the trace, such as: + • Task startup and task completion; + • Context switches (task activation and suspension events); + • Interrupt service routine entry and exit. + The ipoint numbers identifying these events are given to the demux filter using + filter configuration options. + + The output file names are specified using the + --outname-template command-line option (or + -o ). Each output file name is based on this command-line op- + tion, with the task name inserted between the file name and extension. + + The demux filter requires the user to specify the target system's scheduling policy. + The scheduling policy determines how tasks preempt each other. Two policies are + supported: + + priority_based + A priority-based scheduler only permits tasks to preempt each other in a strictly + nested priority order. A task can only be pre-empted by a higher-priority task. A + pre-empted task is only resumed if the pre-empting task returns. + + +RVS Filters Guide vWF20190404 19 +RVS filter commands Writing RVS filters + + + full_preemptive + A full pre-emptive scheduler allows any task to pre-empt any other task, regardless + of priority. In a system with this scheduling policy, tasks are identified by process + IDs (PIDs) and can be suspended and resumed by the scheduler. The system will + include a "context-switch" routine in the operating system. + + Priority-based Scheduling Policy + + The priority_based scheduling policy requires no operating system instru- + mentation. The demux filter is declared as follows: + pb := demux(priority_based); + This should be followed by a list of tasks that are present in the system. + + Tasks can be automatically identified from an RVS database (RVD) file, or they + may be explicitly defined. In both cases, the demux filter looks for three pieces + of information: + • The name of the task; + • The entry ipoint for the task root function; + • The exit ipoint for the task root function. + + All three pieces of information can be defined manually using the add_task con- + figuration option: + pb.add_task(, , ); + + However, the recommended way to determine task information is as follows. Task + information should be determined automatically from an RVS database (RVD) file + containing the task root function: + pb.add_rvd(<.rvd file name>); + + A list of RVD files can also be given to traceutils on the command line: + traceutils filter.flt -o output.txt input.txt task1.rvd task2.rvd + + In priority_based mode, the demux filter allows an "unknown" task to be + specified. This task is assumed to be running at all times, and can represent a + system idle task, non-real-time background tasks, or real-time tasks that were al- + ready executing at the point when the trace began. The unknown task is named + as follows: + pb.add_unknown_task(); + As this acts as a "catch all" for all execution activity outside of a known task, it is + not possible to state any entry/exit ipoints. + + Full Pre-emptive Scheduling Policy + + For a full pre-emptive system, the demux filter is declared as follows: + fp := demux(full_preemptive, + + +20 RVS Filters Guide vWF20190404 +Writing RVS filters RVS filter commands + + , ); + and are special ipoint values that identify task + activation and task suspension. These ipoints are produced by the context-switch + routine within the operating system, which is instrumented to provide this infor- + mation. The ipoint numbers are entirely user-defined, but cannot be used in any + application task. + + Each task activation ipoint is followed by the process ID (PID) of the new task. The + PID is the task identifier used by the operating system. + + The add_rvd and add_task filter configuration options are used to define the + tasks that are executed by the system. These options are the same for both the + priority-based and full pre-emptive scheduling policies. + + However, the full_preemptive mode also supports "interrupt tasks". These + tasks do not have process IDs, because they are invoked in response to interrupt + events rather than the scheduler. This means that they require special treatment. + Interrupt tasks are identified using a filter configuration option: + fp.set_interrupt_task ( [, ]); + The named task must already have been defined by add_rvd or add_task. The + optional parameter specifies that an interrupt task will + not call the scheduler immediately on exit. You should provide this parameter for + each interrupt task that does not do so. + + The full_preemptive mode does not support "unknown" tasks. However, + the time cost of OS overheads such as scheduling and context-switching can be + brought into a special "overhead" task which is identified as follows: + fp.add_overhead_task(, + , ); + A trace will be generated for the overhead task in which represents + entry to some OS function and represents exit from that function. + This allows OS overheads to be shown in the RapiTask Viewer. + + In the full_preemptive mode, each task activation ipoint is followed by the + PID of the new task. The PID may be encoded using one, two, four or eight ipoints. + The encoding format can be chosen to match the available trace capabilities for + the target system. It is specified as follows: + fp.set_pid_size(2, 256); + The first parameter (2) is the number of ipoints used to encode the PID. The second + parameter (256) is the modulus that should be multiplied with each part of the PID + in order to reconstruct the whole PID. In this case, the value of 256 is used, which + means that the sequence (197 16) is reconstructed into a PID as (197*256) + 16 + = 50448. The same PID could also be encoded as four ipoints, e.g. (12 5 1 0). + In this case, + fp.set_pid_size(4, 16); + would specify decoding as follows: (12*16*16*16) + (5*16*16) + (1*16) + 0 + = 50448. There is an implicit assumption of big-endian number encoding, but + + +RVS Filters Guide vWF20190404 21 +RVS filter commands Writing RVS filters + + + the only requirement is that PIDs identify tasks uniquely, so it is not necessary to + reverse the ipoint output order on a little-endian system. + + Context Switch Calibration + + In either full_preemptive or priority_based mode, tasks are pre-empt- + ed. When a task is pre-empted, in an ideal situation the start and end of the pre- + empting task are denoted exactly by the execution of corresponding ipoints (Fig- + ure 3.1a). However, in a typical situation, the first ipoint in the higher-priority task is + executed some time after the interrupted task stops executing and the ipoint at the + end of the higher-priority task is executed some time before the pre-empted task + resumes execution. If only the time spanned by these ipoints is deducted from + the pre-empted task, the execution time of the pre-empted task is overestimated. + Similarly, if only the time spanned by these ipoints is accounted to the pre-empting + task, the execution time of the pre-empting task is underestimated (Figure 3.1b). + + The adjust_cx option configures the demux filter to allow a constant overhead + to be added to the pre-empting task and deducted from the pre-empted task + (Figure 3.1c). This is achieved by changing the timestamps on the two ipoints + representing entry and exit from the pre-empting task. The entry ipoint is moved + earlier, the exit ipoint is moved later. For example, using: + d.adjust_cx(40, 50); + The entry ipoint is moved earlier by 40 time units, and the exit ipoint is moved later + by 50 time units. This happens for every entry/exit pair. No other timestamps are + altered. + + The adjust_cx feature will generate an error message if the requested adjust- + ment would cause ipoint timestamps to become out of order. This will happen if + the specified overheads are larger than the actual overheads on the target system. + + +22 RVS Filters Guide vWF20190404 +Writing RVS filters RVS filter commands + + + in p u t d a t a d e m u lt ip le xe d d a t a + t hread 2 + ipoint ipoint ipoint + + + t hread 1 t hread 2 + ipoint ipoint ipoint ipoint + ipoint + 91 4 5 90 + 91 4 5 90 + + ipoint ipoint ipoint ipoint + 1 2 3 92 t hread 1 ipoint ipoint ipoint ipoint + t im e 1 2 3 92 + + (a) Ideal sit uat ion - Ipoint s 91 and 90 ident ify t hread 2 execut ion t im e + + + in p u t d a t a d e m u lt ip le xe d d a t a + t hread 2 + ipoint ipoint ipoint + + + t hread 1 t hread 2 + ipoint ipoint ipoint ipoint + ipoint + 91 4 5 90 + 91 4 5 90 + + ipoint ipoint ipoint ipoint + 1 2 3 92 t hread 1 ipoint ipoint ipoint ipoint + t im e 1 2 3 92 + + (b) Typical sit uat ion - Ipoint s 91 and 90 do not delineat e t he whole of t hread 2; + t im e bet ween Ipoint 2 and Ipoint 3 is overest im at ed + + in p u t d a t a d e m u lt ip le xe d d a t a + t hread 2 + ipoint ipoint ipoint + + + t hread 1 t hread 2 + ipoint + ipoint ipoint ipoint ipoint 91 4 5 90 + 91 4 5 90 + + ipoint ipoint ipoint ipoint + 1 2 3 92 t hread 1 ipoint ipoint ipoint ipoint + t im e 1 2 3 92 + + (c) adjust _cx allocat es t im e from preem pt ed t ask t o preem pt ing t ask + t o correct t im ing inform at ion + + + Figure 3.1: Timing of task pre-emption using adjust_cx. + + Filter Configuration Options + + The following filter configuration options are available for demux: + + add_rvd (<.rvd file name>) + The task in the specified RVD file will be demultiplexed from the input trace. + + add_task (, , ) + A task with the specified entry and exit ipoints will be demultiplexed from the input + trace. + + +RVS Filters Guide vWF20190404 23 +RVS filter commands Writing RVS filters + + + add_overhead_task (, , ) + Add a task to represent the time cost of OS overheads such as scheduling and + context-switching. This option is only valid in the full_preemptive mode. + + add_unknown_task () + Add a task to contain all trace events that cannot be matched to any other task. + This option is only valid in the priority_based mode. + + add_virtual_task (,) + Associates a virtual task with the given . Virtual tasks are used to + represents tasks that exists outside of an instrumented project, however still can + be seen via instrumented context switches and process IDs. They only display + in the RapiTask viewer as they are not linked to any instrumented code. Virtual + tasks do not support fragmentation and suspension, when a virtual task is context + switched out, it is assumed to have ended. When a normal task start ipoint occurs + after a virtual task a trace warning is given, the normal task takes + ownership of the process ID and the virtual task activity is assumed to have ended. + This option is only valid in the full_preemptive mode. + + detect_virtual_tasks () + Use this function to enable the detection of virtual tasks. A new vir- + tual task will be added for each process ID seen in the trace that + does not have a normal task associated with it. Detected virtual tasks + will be given names in the form "". See + add_virtual_task (,) for more informa- + tion on virtual tasks. This option is only valid in the full_preemptive mode. + + adjust_cx (, ) + Adjust the timestamps of entry/exit ipoints to account for the overhead of con- + text-switching. + + debug () + Causes the demux filter to print debugging output as it reads the input trace. This + output is useful in cases where the demux filter's interpretation of trace events is + incorrect, as it reveals the internal state of the demux filter and the interpretation + that it assigns to particular ipoints. The may range from 0 to 3, with + 3 being most verbose. + + set_interrupt_task ( [,]) + Label the named task as an "interrupt task", meaning that it is invoked in response + to an interrupt and has no PID. The task must already have been defined by + add_rvd or add_task. The optional no_interrupt_task_switch para- + meter specifies that the task does not call the scheduler immediately on exit. This + option is only valid in the full_preemptive mode. + + +24 RVS Filters Guide vWF20190404 +Writing RVS filters RVS filter commands + + + set_pid_size (, ) + Set the encoding format for task PIDs in the trace. This option is only valid in the + full_preemptive mode. + + Examples + + In Example 3.14, a system with priority-based scheduling executes the following + two tasks: + void t1( void ) { + RVS_I( 100 ); + RVS_I( 101 ); + } + + void t2( void ) { + RVS_I( 200 ); + RVS_I( 201 ); + } + t2's priority is greater than t1's. + + + Example 3.14: Demultiplexing a Trace from a Priority-Based System + + + If t2 pre-empts t1 at time 2, the system trace is as follows: + 100 1 # t1 starts + 200 2 # t2 preempts t1 + 201 3 # t2 finishes; t1 resumes + 101 4 # t1 finishes + This system trace may be demultiplexed using the filter file: + pb := demux(priority_based); + pb.add_task("t1", 100, 101); + pb.add_task("t2", 200, 201); + to produce output files for t1: + 100 1 + 4294967295 2 + 4294967294 3 + 101 4 + and for t2: + 200 2 + 201 3 + + + In Example 3.15, a system with full pre-emptive scheduling also executes t1 and + t2. The operating system's context switch routine generates ipoint 5 to indicate + task suspension, and ipoint 6 (followed by a PID) to indicate the activation of a + new task. + + +RVS Filters Guide vWF20190404 25 +RVS filter commands Writing RVS filters + + + Example 3.15: Demultiplexing a Trace from a Full Pre-emptive System + + + The system trace is as follows: + 6 1 # context switch... + 301 2 # ...to PID 301 + 100 3 # t1 starts + 5 4 # t1 suspended + 6 5 # context switch... + 302 6 # ...to PID 302 + 200 7 # t2 starts + 201 8 # t2 finishes + 6 9 # context switch... + 301 10 # ...to PID 301 (t1 resumes) + 101 11 # t1 finishes + This system trace reveals that the operating system has assigned PID 301 to + t1 and PID 302 to t2. The trace may be demultiplexed using the filter file: + fp := demux(full_preemptive, 6, 5); + fp.add_task("t1", 100, 101); + fp.add_task("t2", 200, 201); + to produce output files for t1: + 100 3 + 4294967295 4 + 4294967294 10 + 101 11 + and for t2: + 200 7 + 201 8 + + + If desired, the operating system overheads can be captured using a filter config- + uration option similar to the following: + fp.add_overhead_task("overheads", 400, 401); + The trace for the overheads task is shown in Example 3.16. It captures all of the + time spent in the scheduler and context-switch routine. + + Example 3.16: Overheads Task - Example Trace + + 400 4 + 401 7 + 400 8 + 401 10 + 400 11 + + + The task-level traces can be used for WCET analysis and coverage analysis, and + may also be displayed by RapiTask Viewer. + + Within the t1 output traces, special ipoint ID markers denote time when t1 was + not executing. These are 0xFFFFFFFF (=4294967295) to start removing time and + + +26 RVS Filters Guide vWF20190404 +Writing RVS filters RVS filter commands + + + 0xFFFFFFFE (=4294967294) to stop removing time. This time is ignored for the + purposes of WCET analysis. It can also be removed entirely from the trace using + the write.discard_wt option (see Section 3.2.12). + +3.2.5 demux_rr( [,, ]) + Use demux_rr to split the trace into separate files on a round robin + basis. Each time the specified escape ipoint is encountered, output is re-directed + to the next file in sequence. The stem of the output file name is specified by the + command-line option --outname-template or -o to traceutils. The values 1 + to are appended to this stem to form the full file name. + + Filter Configuration Options + + The demux_rr filter has no options. + + Examples + + The following trace input: + + + Example 3.17: demux_rr example input file + + 1 100 + 2 110 + 3 120 + 75 121 + 6 130 + 3 135 + 54 137 + 7 140 + 23 142 + 8 150 + 4 160 + 32 162 + + + is given to the following demux_rr filter file: + + + Example 3.18: demux_rr filter + + read.escape( 3 ); + read.escape( 7 ); + demux_rr( 2 ); + replace( (i1, t1, i2, t2), (i1, t1) (i2, t2) ); + + + In conjunction with the traceutils option -o or --outname-template + file.txt, the demux_rr filter will produce the following output: + + +RVS Filters Guide vWF20190404 27 +RVS filter commands Writing RVS filters + + + Example 3.19: Round-robin demultiplex output + + in file_1.txt: + 3 120 + 75 121 + 6 130 + 7 140 + 23 142 + 8 150 + 4 160 + 32 162 + + in file_2.txt: + 3 135 + 54 137 + + + The additional and parameters allow the escape ipoints used + for demultiplexing to be selected. The parameter is one of I0, I1, or T1, + and the output file is switched when the specified field is equal to value. + Example 3.20: demux_rr filter (2) + + read.escape( 3 ); + read.escape( 7 ); + demux_rr( 2, I0, 3 ); + replace( (i1, t1, i2, t2), (i1, t1) (i2, t2) ); + + + will, in conjunction with the traceutils option -o or --outname-template + file.txt, produce the following output: + Example 3.21: Round-robin demultiplex output + + in file_1.txt: + 3 120 + 75 121 + 6 130 + + in file_2.txt: + 3 135 + 54 137 + 7 140 + 23 142 + 8 150 + 4 160 + 32 162 + + +3.2.6 gray + Use a gray filter to convert a trace that has been generated using Gray coding + on-target. Gray coding is a technique used to avoid "glitches" in the trace due to + different rise and fall times of I/O pins by only changing one bit at once. + + +28 RVS Filters Guide vWF20190404 +Writing RVS filters RVS filter commands + + + Use the read.min_delta filter configuration option to remove transient, glitch + ipoints from a trace provided that all valid values persist for long enough to distin- + guish valid from glitch values reliably. When that is not achievable, one solution is + to use Gray coding in the target instrumentation code, where a value is signaled + by changing exactly one bit in the ipoint ID. + + A typical RVS_I routine for Gray coded ipoints uses an exclusive OR instruction + to change the required bit and may well be extremely efficient. The gray filter + allows the resulting trace to be interpreted by applying an exclusive OR operation + to every pair of ipoint IDs. + + If more than one bit is changed in a single transition, the gray filter interprets this + as a non-Gray coded value, still applying the exclusive OR operation but deleting + any single-tick transition value immediately before or after that value. This allows + the RVS_I routine to change multiple bits, as long as it guarantees that there is + no valid transition immediately before or after the non-Gray coded value. + + Note + + If an 8-bit IO port is being used to emit ipoint IDs, Gray coding allows only + 8 different values rather than the 256 that could be achieved using ordinary + binary encoding. To permit a larger range of ipoint IDs, it may be necessary + to send a succession of Gray coded values to express a single ipoint ID + and then recombine them in the trace using the concat filter. + + Filter Configuration Options + + The gray filter has no options. + + Example + + In Example 3.22, a sample trace is shown before it is passed through the gray + filter. Note that each consecutive ipoint differs in only one bit. For instance, between + the second and third ipoint only bit-1 has changed from 0 to 1. The gray filter + converts this sequence of encoded ipoints into the actual ipoint numbers shown + in the "after:" section below. + Example 3.22: Trace + + before: + 0 0 # initial port value + 1 1 # (1) bit 0 toggled on the port + 3 2 # (2) bit 1 toggled + 6 3 # Glitch. Two bits changed. + 1 5 # (2) bit 1 toggled again + 5 6 # (4) bit 2 toggled + + after: + 1 1 + 7 2 + 3 5 + + +RVS Filters Guide vWF20190404 29 +RVS filter commands Writing RVS filters + + +3.2.7 keep_sequence(,) + Use keep_sequence to preserve only those ipoint sequences between IDs + and . It is typically used to preserve ipoint sequences that are + within the call tree of the root function, discarding any ipoints that are not brack- + eted by the ipoints at the start and end of the root function. + + keep_sequence always matches the longest sequence(s) found. + + Filter Configuration Options + + The keep_sequence filter has no options. + + Example + + The filter: + Example 3.23: keep_sequence example + keep_sequence(1,7); + + + will have the following effect: + Example 3.24: keep_sequence action + + before: + 1 100 + 37 150 + 2 300 + 3 400 + 1 500 + 7 523 + 35 699 + 5 700 + + after: + 1 100 + 37 150 + 2 300 + 3 400 + 1 500 + 7 523 + + + Note + + If multiple keep_sequence commands are specified then they will isolate + smaller and smaller sub-sequences, so: + keep_sequence(10,20); + keep_sequence(5,8); + + will keep sequences of ipoints beginning with ID 5 and ending with ID 8, + found within sequences beginning with ID 10 and ending with ID 20. + + +30 RVS Filters Guide vWF20190404 +Writing RVS filters RVS filter commands + + + Note + + To keep ipoints with selected IDs and remove all others, use the remove fil- + ter. For example: + remove(0:0xFFFFFFFF, !5, !8); + will remove all ipoints apart from those with ID 5 or ID 8. + + +3.2.8 read + The read filter reads input traces provided to traceutils on the command line. + See Section 5.7 in the RVS Files Reference Guide for details of the supported input + formats. + + Important + + The read filter is never declared within an RVS filter file. It is defined implic- + itly by traceutils. + + + The read filter passes trace data to the first filter declared in the RVS filter file. If no + filter file is provided, data is passed directly to the write filter (see Section 3.2.12). + + Filter Configuration Options and Examples + + The filter configuration options for read are described (with examples) in Sec- + tion 3.3. + +3.2.9 remove( [, ]+) + Use remove to remove ipoints with the specified IDs from the trace. For example, + you can use remove to remove certain ipoints that have been generated on- + target, but which you do not need for analysis. + + Use each argument to specify an ipoint or a range of ipoints to remove. Ranges + of ipoints are specified using ':' (colon) and are inclusive. + + Specify ipoints that you do not want to remove using the '!' operator. The arguments + have left to right precedence, with later arguments potentially overriding earlier + ones. + + Filter Configuration Options + + The remove filter has no options. + + +RVS Filters Guide vWF20190404 31 +RVS filter commands Writing RVS filters + + + Example + + + Example 3.25: Removing ipoints + + # remove ipoints with IDs 1, 3 and 5 + remove(1,3,5); + + # remove ipoints in the ranges 0 to 10 and 20 to 255 + remove(0:10, 20:255); + + # remove all the ipoints in the range 0 to 255 + # but not those in the range 10 to 20 + # but do remove ipoints with ID 15 + remove(0:255, !10:20, 15); + + # keep only ipoints that come after ipoints with ID 3 + # assuming a 16 bit ipoint so all ipoint numbers are + # in range 0 to 0xFFFF + read.escape( 3 ); + remove(0:0xFFFF, !3); + replace( ( 3, ., x, t ), ( x, t ) ); + + + Note + + The remove command is useful in removing specific ipoints. replace + (below) is more powerful and flexible and allows arbitrary patterns of ipoints + to be removed or replaced. + + +3.2.10 replace(, ) + Use replace to replace occurrences of in the trace data with + . This filter is widely used for manipulation of trace data coming + from a target that contains context-switches and interrupts to prepare it for analysis + by RVS. + + Filter Configuration Options + + The following filter configuration options are available for replace: + + recursive + The recursive option causes repeated passes to be made over the data until + the resultant trace no longer changes. Without the recursive option, replace- + ment occurs on only one pass through the trace data. + + Important + + The recursive option must be used with care; for example, if is a sub-sequence of , an infinite sequence will + result, and replace will not terminate. + + +32 RVS Filters Guide vWF20190404 +Writing RVS filters RVS filter commands + + + adjust_times + The adjust_times option discards sections of time associated with a se- + quence of removed ipoints. The duration of time removed is the timestamp of the + last ipoint in the sequence minus the timestamp of the first ipoint in the sequence. + + Important + + The adjust_times option is only valid when the replace filter is used + to remove ipoints rather than replace them. It will only work correctly when + is left blank. + + when () + The when option allows pattern replacement to be conditional. + + Examples + + See Section 3.4 for a description of patterns and examples of their use. + +3.2.11 save_metadata and restore_metadata + Use these filters to save and restore metadata embedded within a trace. + + Build identifiers and test identifiers are examples of embedded metadata. They + are written to a trace using the build_id annotation (see Section 7.3 in the RVS + Annotations Reference Guide) and the RVS_Begin_Test API call, see the RVS + Integration Library Implementation Guide. Embedded metadata begins with a spe- + cific sequence of ipoint IDs, usually starting with 7. The read.event_id() + configuration option may be used to change the ipoint ID signifying a metadata + sequence. + + In general, RVS filters are unaware of embedded metadata, and it is possible to + write filter rules that destroy the structure of build and test identifiers. Furthermore, + rules that distribute data to more than one output (such as demux) will not handle + metadata correctly. It will either be discarded, or routed to one output only. + + To avoid these issues, save_metadata is used at the beginning of an RVS filter + file to preserve any metadata in the trace. The metadata is removed from the trace + and stored separately in memory. + + Then, restore_metadata is used at the end of the same RVS filter file to re- + store any metadata removed from the trace. + + Filter Configuration Options + + The save_metadata and restore_metadata filters have no options. + + Example + + save/restore_metadata should be used whenever a trace contains meta- + data which needs to be preserved across the use of filters such as demux, re- + move and replace. For example: + + +RVS Filters Guide vWF20190404 33 +RVS filter commands Writing RVS filters + + + Example 3.26: save/restore_metadata filter example + + save_metadata; + remove(0); + restore_metadata; + + + This filter will have the following effect: + + Example 3.27: Trace containing metadata + + before: + 0 1 + 100 2 + 7 3 + 5 3 + 65 3 + 66 3 + 0 3 + 101 3 + + after: + 100 2 + 7 3 + 255 3 + 58 3 + 66 3 + 117 3 + 105 3 + 108 3 + 100 3 + 32 3 + 73 3 + 100 3 + 2 3 + 9 3 + 171 3 + 65 3 + 66 3 + 101 3 + + + In this example, the remove rule is used to delete zero ipoint IDs from the trace. + This correctly removes the initial ipoint ID, but it would also change the build + identifier metadata (7 5 65 66 0) unless the metadata is preserved using save/ + restore_metadata. + + Note + + Embedded metadata is distinct from trace-processing metadata (see Sec- + tion 3.2.12). Embedded metadata is part of the trace data itself and repre- + sents events that occur during a test, whereas trace-processing metadata + is part of the trace file and represents actions that have been applied to that + trace file, e.g. by traceutils. + + +34 RVS Filters Guide vWF20190404 +Writing RVS filters RVS filter commands + + + Important + + A filter file can contain only one save_metadata command. + + +3.2.12 write + The write filter creates trace files during the final processing step of traceutils. + + Important + + The write filter is never declared in an RVS filter file. It is defined implicitly + by traceutils. + + + Filter Configuration Options + + The following filter configuration options are available for write: + + discard_metablock + The write.discard_metablock prevents traceutils writing any trace-pro- + cessing metadata to the output trace. Metadata records are visible within .txt, + .dt1 and .dt2 format traces, where they are encoded as comments. Metadata + records are also stored in a compressed form in RPZ files. + + Note + + Trace-processing metadata is distinct from embedded metadata (see Sec- + tion 3.2.11). Trace-processing metadata is part of the trace file and repre- + sents actions that have been applied to that trace file, whereas embedded + metadata is part of the trace data itself and represents events that occur + during a test. + + + discard_wt + The write.discard_wt option will cause timestamps to be changed instead + of adding time manipulation markers to the trace. Special ipoint ID markers are + added to the trace to denote time that was removed (e.g. by the adjust_times + option with the replace filter, see Section 3.4.2) or time when a task was not + executing (e.g. by the demux filter, see Section 3.2.4). + + The markers are 0xFFFFFFFF (=4294967295) to start removing time + and 0xFFFFFFFE (=4294967294) to stop removing time. When the + write.discard_wt option is used, the markers and the time interval are re- + moved from the trace output. + + hex + Outputs ipoints in hexadecimal format, when using text-based trace file formats + such as .txt, .dt1 and .dt2. + + +RVS Filters Guide vWF20190404 35 +RVS filter commands Writing RVS filters + + + output_format() + Override the output trace file format. Normally, the output file format is de- + rived from the extension of the file name given on the command-line to -o or + --outname-template. The write.output_format option sets the for- + mat explicitly, allowing any extension to be used. For example: + write.output_format("rpz"); + forces output in RPZ format. See Section 5.7 in the RVS Files Reference Guide for + details of the supported output formats. + + +36 RVS Filters Guide vWF20190404 +Writing RVS filters Read filter configuration options + + +3.3 Read filter configuration options + The read filter is responsible for reading input traces provided to traceutils on + the command line. + + The trace file reader is the most complex feature of traceutils because of the large + number of options for processing incoming trace data before it is passed to other + filters. + + The following sections document the configuration options for the read filter. If + multiple options are specified, then their effects are always applied to the trace + data in a specific order, regardless of their order in the RVS filter file. The immutable + order is: + 1. byte_reader (see Section 3.3.1), + 2. line_reader (see Section 3.3.4), + 3. escape (see Section 3.3.3), + 4. reverse_timestamps (see Section 3.3.7), + 5. wrap (see Section 3.3.9), + 6. reset_start_time (see Section 3.3.6), + 7. min_delta (see Section 3.3.5), + 8. scale (see Section 3.3.8), + 9. deinstrument (see Section 3.3.2). + +3.3.1 read.byte_reader(,[, + Use read.byte_reader to specify how to transform a stream of bytes (as a + raw binary input file) into ipoint ID and timestamp pairs. The byte stream is defined + in terms of bytes, for example B0 is the first byte in the stream and B0[3:0] + represents the 4 least significant bits in that byte. + + Note + + The read.byte_reader configuration option requires the trace data file + to have the .bin extension, which indicates that the trace data is in raw, + uncompressed format. See Section 5.7 in the RVS Files Reference Guide for + more details on trace data formats and file extensions. + + The following example shows how to decode a Big-Endian stream of 32-bit values, + where the most significant 12 bits contain the ipoint ID and the least significant 20 + bits contain the ipoint timestamp. + + Example 3.28: Byte reader (big endian) + + read.byte_reader("B0[7:0] B1[7:4]", "B1[3:0] B2 B3"); + read.wrap(20); + + +RVS Filters Guide vWF20190404 37 +Read filter configuration options Writing RVS filters + + + This is illustrated below: + + 7 07 07 07 0 + + B0 B1 B2 B3 + + 12 0 20 0 + + ID Tim est am p + + Figure 3.2: Byte reader + + We can see that the ID field has been constructed by concatenating the 8 bits + of B0 with the upper 4 bits of B1, so that B1[7:4] form the lower 4 bits of ID. + Similarly, the timestamp field has been constructed by concatenating the lower 4 + bits of B1 with B2 and B3, so that B1[3:0] form the most significant 4 bits of + the resulting 20 bit number. + + Note + + The bit field B0[7:0] specified above is equivalent to B0. + + + Note + + The read.wrap option should always be used alongside the + read.byte_reader option to ensure that wraps of the timestamp field + are treated correctly. + + If the same stream of 32-bit values were written in a Little-Endian format, it would + be decoded as follows: + + Example 3.29: Byte reader (little endian) + + read.byte_reader("B3[7:0] B2[3:0]", "B2[7:4] B1 B0"); + read.wrap(20); + + + If there are some bytes that must be skipped after reading each record, the + parameter of read.byte_reader can be used to specify how + many extra bytes should be read but not processed after reading each ipoint ID + and timestamp. + + If there is header information that must be skipped to reach the ipoint data, you + can discard a specified number of bytes from the start of the trace data using the + option: + read.skip_bytes(); + + +3.3.2 read.deinstrument () + Use read.deinstrument to subtract the specified instrumentation overhead + from the interval between adjacent timestamps. + + +38 RVS Filters Guide vWF20190404 +Writing RVS filters Read filter configuration options + + + Note + + The additional (i.e. third and fourth) fields in escape ipoints are unaffected + by the time adjustment. + + The following example deducts 10 cycles from each ipoint. Notice that the + read.escape option will prevent the read.deinstrument option from de- + ducting the time from any ipoint following an ipoint with ID 7. + + Example 3.30: De-instrumentation + + read.escape( 7 ); + read.deinstrument( 10 ); + replace( (i1, t1, i2, t2), (i1, t1) (i2, t2) ); + + + Example 3.31: De-instrumented trace + + before: + 1 100 + 37 150 + 2 300 + 3 400 + 1 500 + 7 523 + 35 999 + 5 700 + + after: + 1 100 + 37 140 + 2 280 + 3 370 + 1 460 + 7 473 + 35 999 + 5 640 + + +3.3.3 read.escape ( [, ]+) + Use the escape option to treat ipoint identifiers as escape ipoints. An ipoint that is + designated as an escape ipoint is joined with the next ipoint in the stream to form + a single item containing all the information from the two ipoints together. + + Use each argument to specify an ipoint or a range of ipoints to treat as escape + ipoints. Ranges of ipoints are specified using ':' (colon) and are inclusive. + + You can use the read.escape option when instrumenting an operating system's + context-switch mechanism to record the new process identifier in the trace. + + A number of the filter commands use the escape ipoint concept. An escape ipoint + is a mechanism by which extra data can be attached to an ipoint rather than treated + + +RVS Filters Guide vWF20190404 39 +Read filter configuration options Writing RVS filters + + + as a normal ipoint. In this way, the extra information will not be modified by other + filters. The escape keyword joins instances of the specified ipoint with the ipoint + data that is immediately following it, effectively turning two ipoints (each containing + an identifier and timestamp) into one ipoint containing an identifier, timestamp and + two extra data items. + + In the following example, we consider an instrumented context-switch routine, + where just prior to the context-switch, a known ipoint identifier is explicitly added, + immediately followed by an ipoint that identifies the context being switched to. + + Example 3.32: Context-switch instrumentation + + ... + if (context_switch_required(p)) + { + /* about to switch to process 'p' */ + + RVS_I(3); /* our escape ipoint */ + RVS_I(p); /* log the process ID */ + + dispatch(p); /* dispatch the process */ + } + ... + + + For this particular test run, where process 75 is dispatched, a trace including the + following fragment might be produced from the target: + + Example 3.33: Context-switch trace fragment (before) + + 13 500 + 23 520 + 29 530 + 3 565 + 75 567 + 32 573 + 41 590 + 75 620 + + + Here we see that the ipoint with ID 3 is immediately followed by an ipoint with ID + 75. The ipoint with ID 75 is not a typical ipoint, because the ID depends on the + run-time behavior of the system. It is helpful to treat ipoint 75 as extra data that + is really associated with the ipoint 3, otherwise other filters that you apply to the + trace might change the data in the ipoint. + + Using the read.escape option with ID 3 will join the (75 567) pair to the (3 565) + pair, so any subsequent ipoint manipulation will not modify the (75 567) pair. For + example: + + Example 3.34: Context-switch filter + + read.escape( 3 ); + remove( 75 ); + replace( (i1, t1, i2, t2), (i1, t1) (i2, t2) ); + + +40 RVS Filters Guide vWF20190404 +Writing RVS filters Read filter configuration options + + + will not remove the (75 567) pair, but will remove the (75 620) pair. Note that the final + replace filter is a method to remove any escaped ipoint data from the final trace + (if any remains). Trace data files cannot contain escape ipoints, so any remaining + escape ipoints must be unescaped. + Example 3.35: Context-switch trace fragment (after remove) + + 13 500 + 23 520 + 29 530 + 3 565 + 75 567 + 32 573 + 41 590 + + + Important + + For this to work correctly, there must be no chance of ipoints being inserted + between the escape-ipoint and the data-ipoint - i.e. interrupts must not oc- + cur between them. + + +3.3.4 read.line_reader( ) + Use read.line_reader to specify how to decode a text format trace file into + ipoint and timestamp pairs. The read filter reads one line at a time and extracts + fields based on a line specification. + + If you provide more than one read.line_reader clause (you can have + up to 100), traceutils tries the clauses in turn until it reads successfully. If no + read.line_reader clauses match, then the input line is ignored. If traceutils + cannot parse a particular read.line_reader clause in the filter file, it skips + that clause. + + To improve efficiency, you can discard a specified number of characters from the + start of each line (note that tab is counted as a single character) using the option: + read.skip_columns(); + + The line specification is defined as one or more character-field specifications con- + tained within quotation marks. + + A character-field specification can be one of: + + ipoint identifier + Specify ipoint identifiers in either decimal or hexadecimal formats: + • IH : ipoint ID as hex number; + • ID : ipoint ID as an unsigned decimal number; + • ID : ipoint ID as a signed decimal number with width bits. Negative + numbers are converted to unsigned form (e.g. with ID8 -1 is read as 255). + ID8, ID16 and ID32 are supported. + + +RVS Filters Guide vWF20190404 41 +Read filter configuration options Writing RVS filters + + + Timestamp value + Timestamp values can be in decimal, hexadecimal or floating point, and are spec- + ified as either an absolute time, a time-to-next delta time, or a time-from-previous + delta time. + + The form of a timestamp specifier is where t can be one of: + • T : absolute timestamp; + • P : delta-from-previous timestamp; + • N : delta-to-next timestamp; + + and f can be one of: + + • H : Hexadecimal format; + • D : Decimal format; + • T : floating-point format with time units specified after each value in the trace + file. The allowed units are s, ms, us, ns and ps, each of which can be preceded + by spaces or tab characters. + • T : floating-point format with time units . The allowed units are s, + ms, us, ns and ps. + + The combinations are therefore as follows: + + • TH : absolute time as hex; + • TD : absolute time as decimal; + • TT : absolute time as floating point with units in the trace file; + • TT : absolute time as floating point with units ; + • PH : time from previous as hex; + • PD : time from previous as decimal; + • PT : time from previous as floating point with units in the trace file; + • PT : time from previous as floating point with units ; + • NH : time to next as hex; + • ND : time to next as decimal; + • NT : time to next as floating point with units in the trace file, + • NT : time to next as floating point with units . + + Whitespace + traceutils ignores whitespace, except for newlines. Whitespace merely serves as + a separator for other fields. + + Literal string + To match a precise string in an input line, enclose a literal string in single quotes + ('). + + +42 RVS Filters Guide vWF20190404 +Writing RVS filters Read filter configuration options + + + Discard specifier + You can discard non-constant fields using the following field specifiers: + • DH : Discard a hexadecimal integer value (optionally preceded by 0x); + • DD : Discard a decimal integer value (not including a decimal point); + • DW : Discard a non-blank string + + read.line_reader examples + + read.line_reader is very powerful and complex. This section describes + some examples of its use. + + Example 3.36 shows an example of input containing decimal ipoint and ab- + solute-timestamp data. No other text is expected on a trace line. Example 3.37 is + the corresponding read.line_reader specification. + + Example 3.36: read.line_reader simple example input file + + 1 100 + 2 150 + 3 203 + + + Example 3.37: Simple read.line_reader clause (1) + + read.line_reader("ID TD"); + + + Now consider the trace-file in Example 3.38 whereby each line contains the string + "data" followed by a single whitespace before the ipoint identifier: + + Example 3.38: read.line_reader example input file + + data 1 100 + data 2 200 + data 3 300 + + + A read configuration for this trace-file is: + + Example 3.39: Simple read.line_reader clause (2) + + read.line_reader("'data' ID TD"); + + + This generates the trace-file shown in Example 3.40: + + Example 3.40: read.line_reader example output file + + 1 100 + 2 200 + 3 300 + + +RVS Filters Guide vWF20190404 43 +Read filter configuration options Writing RVS filters + + + As every line in this file begins with "data", the same output file can be generated + using the read.skip_columns option to indicate that the first four characters + be skipped: + + Example 3.41: read.line_reader example filter file + + read.line_reader("ID TD"); + read.skip_columns("4"); + + + Observe that the read.line_reader specification in Example 3.41 does + not require the "data" string as in Example 3.39 due to the use of + read.skip_columns. Also note that read.skip_columns has a speed + advantage, although the exact match of "data" will not be verified. + + The read.line_reader defined in Example 3.42 reads a line which has an + unknown hexadecimal number at the beginning of each line, followed by a hexa- + decimal ipoint ID and delta-timestamp (where the delta-time is since the previous + ipoint). + + Example 3.42: Simple read.line_reader clause (3) + + read.line_reader("DH IH PH"); + + + The trace data read by this example corresponds to a hexdump of a memory buffer + captured by a debugger. + +3.3.5 read.min_delta() + Use read.min_delta to remove short ipoint records that are closer together + than clock ticks. + + You would typically use read.min_delta where your external trace capture + device has also captured intermediate stages in an IO port transition (perhaps due + to mismatched rise/fall times on the port). If you are using the RTBx data logger, + it can automatically remove short times for you using its oversampling feature, so + you do not need to use the read.min_delta option. + + When the read filter detects two ipoints closer together than the window, then a + single ipoint is constructed using the timestamp of the first ipoint, and the ID of + the second. + + Example 3.43: Removing short ipoints + + read.min_delta(2); + + +44 RVS Filters Guide vWF20190404 +Writing RVS filters Read filter configuration options + + + Example 3.44: Trace + + before: + 1 100 + 2 200 + 3 300 + 7 400 + 4 401 + 5 500 + + + after: + 1 100 + 2 200 + 3 300 + 4 400 + 5 500 + + +3.3.6 read.reset_start_time + Use read.reset_start_time to force the timestamps in the output trace to + start at 0. + + By default, timestamps in the input trace will be transferred directly into the output + trace. If reset_start_time is used, the timestamps in the output trace file will + be corrected so that the first timestamp in the trace is 0 and all other timestamps + are relative to this. + + Note + + The read.reset_start_time sub-filter will generate an error if time + appears to run backwards within the trace, e.g. if timestamp 200 is followed + by timestamp 199. If this phenomenon is due to timer wrap-around, then + read.reset_start_time must be combined with read.wrap (see + Section 3.3.9). + + Example 3.45: read.reset_start_time example + + read.reset_start_time; + + + Example 3.46: read.reset_start_time input + + 1 100 + 2 105 + 3 106 + 4 111 + 5 118 + 6 122 + 7 124 + + +RVS Filters Guide vWF20190404 45 +Read filter configuration options Writing RVS filters + + + Example 3.47: read.reset_start_time output + + 1 0 + 2 5 + 3 6 + 4 11 + 5 18 + 6 22 + 7 24 + + +3.3.7 read.reverse_timestamps + Use read.reverse_timestamps to convert between traces that are cre- + ated using a timestamp that counts downwards and traces that have increas- + ing timestamps. Some targets have built-in timers that count downwards; when + you use a decrementing counter for timestamping ipoints you can then use the + read.reverse_timestamps option to convert the timestamps to increment- + ing timestamps, which is the normal format for RapiTime traces. + + Example 3.48: read.reverse_timestamps example + + read.reset_start_time; + read.reverse_timestamps; + + + Note + + The filter example above includes the read.reset_start_time op- + tion in order to ensure that the output file timestamps start from zero. This is + purely for the readability of this example. + + Example 3.49: reverse_timestamps input + + 1 25 + 2 20 + 3 19 + 4 14 + 5 7 + 6 3 + 7 1 + + + Example 3.50: reverse_timestamps output + + 1 0 + 2 5 + 3 6 + 4 11 + 5 18 + 6 22 + 7 24 + + +46 RVS Filters Guide vWF20190404 +Writing RVS filters Read filter configuration options + + +3.3.8 read.scale(,) + Use read.scale to scale the intervals between timestamps by multiplying them + by and then dividing by . + + If the result of the calculation is a non-integer, the result is rounded to the nearest + integer. Moreover, the start time of a trace is reset to zero. + + When the read.scale option is used, the read.reset_start_time option + is implied. The intervals between timestamps must be greater than or equal to zero. + + As an example, consider that the trace obtained was at clock 1THz. In order to + scale it to 400MHz, the following filter options are used: + + Example 3.51: read.scale example + + read.scale(400, 1_000_000); + + + This will have the following effect: + + Example 3.52: Scaled trace + + + before: + 1 1000000 + 2 2603450 + 3 3234300 + 4 4500234 + + + after: + 1 0 + 2 641 + 3 893 + 4 1399 + + + Thus, the timestamp 1,000,000 for ipoint 1 will be scaled to 400 (1,000,000 x 400 / + 1,000,000). Similarly, the timestamp of ipoint 2 is scaled to 1,041 (2,603,450 x + 400 / 1,000,000). Further, the timestamp of first ipoint (ipoint 1) is reset to zero thus + subtracting 400 from all the ipoints. + + The read.scale option also supports scaling to fractions such as 33.333MHz. + Using the above trace of 1THz, the following option will scale it to 33.333MHz. + + Example 3.53: read.scale example + + read.scale(100, 3_000_000); + + +RVS Filters Guide vWF20190404 47 +Read filter configuration options Writing RVS filters + + + A simple way to derive the above option setting is to formulate 1THz to 33.33MHz + conversion using 33.33 = (1,000,000 * m)/d. In this case, the values for m and d + are 100 and 3,000,000 respectively. This will have the following effect: + + Example 3.54: Scaled trace + + before: + 1 1000000 + 2 2603450 + 3 3234300 + 4 4500234 + + after: + 1 0 + 2 53 + 3 74 + 4 116 + + + Important + + If the scaling values passed to read.scale are too large, the calculation + may overflow, in which case traceutils will report an error. + + Where the overflow is caused by a multiplier value that is too large, it may + be possible to divide both scaling values by a common divisor to remove + the error. For example the option: + read.scale( 4_000_000_000, 2_000_000_000 ); + may give an error, but by dividing both values by 2,000,000,000 the result- + ing option: + read.scale( 2, 1 ); + may prevent the error from occurring. + + +3.3.9 read.wrap() + Use read.wrap to adjust for a timer wrap-around. Unless a timer has a large + number of bits, then it may overflow by wrapping round. This option causes the + read filter to detect wraparounds and creates a trace that uses a larger number + of bits for the timestamps to avoid wraparound. + + The argument is the number of bits used for the timer in the input trace file: + n + the timer counts from zero to 2 -1. The default is 64-bits. + + As an example, the option: + + Example 3.55: read.wrap filter example + + read.wrap(8); + + +48 RVS Filters Guide vWF20190404 +Writing RVS filters Read filter configuration options + + + will have the following effect: + + Example 3.56: Example trace with timer wrap-around + + before: + 1 10 + 2 120 + 3 243 + 4 16 + + after: + 1 10 + 2 120 + 3 243 + 4 272 + + + Observe in the original trace that, between ipoints 3 and 4, the timer has wrapped + around. After the wrap option has been applied, the timestamp associated with + ipoint 4 is corrected to 256 + 16 = 272. + + Important + + traceutils can only infer that a timer wraparound has occurred from the da- + ta contained within the trace. To ensure that timing measurements are cor- + rect, the timer must not wrap more than once between consecutive ipoints. + + +RVS Filters Guide vWF20190404 49 +Pattern replacement Writing RVS filters + + +3.4 Pattern replacement + Pattern replacement is a powerful and flexible facility that lets you manipulate pat- + terns of ipoints in a general way. + + A pattern is a list of elements where each element is an ipoint ID and timestamp + pair. Ipoint IDs and timestamps may be specified as literals, variables or 'don't + care'. Literals are numbers (e.g. 2, 3, 436589), while variables are any valid C vari- + able name (e.g. a, var, dummy, t1 etc.), and 'don't care' is specified by '.' (dot). + + In addition, '*' (star) is used to specify zero or more elements. '*' (star) may only be + used to specify multiple arbitrary elements, indicated by '.' (dot). It cannot be used + to specify multiple defined elements. '^' (hat) can be used to specify "start of file", + effectively an imaginary ipoint before the first ipoint in the file. Similarly, '$' (dollar) + can be used to specify "end of file", effectively an imaginary ipoint after the last + ipoint in the file. + + '*' (star), '.' (dot), '^' (hat) and '$' (dollar) cannot be used in the definition of the + output pattern. + + replace can be used to remove sequences of ipoints as illustrated in the fol- + lowing examples. + + Example 3.57: First example of removing sequences of ipoints using pattern + replacement + + # remove all ipoints from the start to the first + # ipoint with ID = 1 inclusive + replace(^ .* (1,.), ); + + + In Example 3.57, the command removes all ipoints from the start, up to and in- + cluding the first ipoint with ID=1, by replacing them with an empty pattern. Note, + we use '.' (dot) for the timestamp value here; it is not used in the output pattern, + so we don't need to reference it. + + Example 3.58: Second example of removing sequences of ipoints using pattern + replacement + + # remove all ipoints after the last ipoint with ID = 2 + # to the end + replace((2,t1) .* $, (2,t1)); + + + In Example 3.58, the command effectively removes all the ipoints after the last + ipoint with ID=2 up to the end of the file. It does this by replacing the sequence + from the last ipoint with ID=2 to the end by just the last ipoint with ID=2. Here, + the variable t1 is used to store the timestamp of the ipoint with ID=2 as this is + required to create the output pattern. + + +50 RVS Filters Guide vWF20190404 +Writing RVS filters Pattern replacement + + + Example 3.59: Third example of removing sequences of ipoints using pattern + replacement + + # remove the ipoint preceding each ipoint with ID = 3 + replace((.,.) (3,t2), (3,t2)); + + + In Example 3.59, the command removes a single arbitrary ipoint preceding each + ipoint with ID=3. Here, the variable t2 is used to store the timestamp of the ipoint + with ID=3, as this is required to create the output pattern. + + Example 3.60: Fourth example of removing sequences of ipoints using pattern + replacement + + # remove the ipoint following each ipoint with ID = 4 + replace((4,time) (.,.), (4,time)); + + + In Example 3.60, the command removes a single arbitrary ipoint following any + ipoint with ID=4. + + Example 3.61: Pattern replacement + + replace( (1, t1) .* (2, t2), (1, t1) (0, t1) (1, t2) ); + + + In the final example above, the first command looks for a pattern that starts with an + ipoint with ID=1 (with any timestamp), followed by an arbitrary number of ipoints + with any ID and timestamp, followed by an ipoint with ID=2 and any arbitrary time- + stamp. This pattern is then replaced by a pattern containing just three ipoints with + IDs of 1, 0 and 1, respectively. The variables t1 and t2 are used to capture the + timestamp values and place them in the output pattern. + + The result of the filter in Example 3.61 can be seen in Example 3.62. + +3.4.1 Matching rules + replace works by searching forwards through the list of ipoints looking for + matches to the specified pattern. Once a match is found for the final ipoint spec- + ified, then replace works backwards through the file until it finds a match to the + entire pattern. The sub-sequence identified is then replaced by the output pattern. + + This is very similar to a conventional regular expression, except that minimal + matching is always performed, and the smallest possible pattern is matched (Most + regular expressions try to match the largest possible pattern). + + The behavior of matching rules is best understood via an example. + + Consider the replace command given in Example 3.61, applied to the following + file of ipoints: + + +RVS Filters Guide vWF20190404 51 +Pattern replacement Writing RVS filters + + + Example 3.62: Pattern replacement + + + before: + 1 100 + 1 200 + 1 300 + 3 400 + 4 500 + 2 600 + 5 700 + 2 800 + + + after: + 1 100 + 1 200 + 1 300 + 0 300 + 1 600 + 5 700 + 2 800 + + + replace searches through the file, from its starting point, until the entire pat- + tern has been matched. This occurs for the ipoint (2,600). It then searches back + through the file, again matching the pattern, until it first finds a complete match. + This occurs at the ipoint (1,300). The selected sub-sequence from (1,300) to + (2,600) is then replaced by the output pattern. replace then continues from a + new starting point at the next ipoint, until it finds a further match or reaches the + end of the file. + + Sometimes it is useful to apply pattern replacement repeatedly until the resulting + trace no longer changes. This can be done using the recursive option: + + + Example 3.63: Recursive pattern replacement + + r := replace((i1, t) (i2, .), (i1, t) (i2, t+1)); + r.recursive; + + + In the above example, the replace command rewrites time-stamps so that they + increase by one tick each ipoint. This can be used to obtain a report that only + counts ipoints, rather than measuring time. + + +52 RVS Filters Guide vWF20190404 +Writing RVS filters Pattern replacement + + + Example 3.64: Recursive pattern replacement + + before: + 1 100 + 1 200 + 1 300 + 3 400 + 4 500 + 2 600 + 5 700 + 2 800 + + after: + 1 100 + 1 101 + 1 102 + 3 103 + 4 104 + 2 105 + 5 106 + 2 107 + + + If we had not used the recursive option, only alternate time-stamps would have + been rewritten. + +3.4.2 Adjusting timestamps + Specifying the adjust_times option with the replace filter allows sections of + time to be removed from traces. + + The output pattern of the replace command should always be left blank when + using the adjust_times option. + + When a sequence of ipoints matching the input pattern is found, they will be re- + moved and the duration of time equal to the timestamp of the final ipoint in the + sequence minus the first ipoint in the sequence is removed from the trace. + + By default, when the write.discard_wt option is not used, time is re- + moved by adding special ipoint ID markers to the trace. These are 0xFFFFFFFF + (=4294967295) to start removing time and 0xFFFFFFFE (=4294967294) to stop + removing time. When timeparser sees these markers, it will remove this sec- + tion of time from the trace. + + The filter shown in Example 3.65 will remove all sequences of ipoints starting with + ipoint ID 130 and ending with ipoint ID 129. The time used by these ipoints will be + removed from the trace, except from from the time used by the final ipoint, which + is assigned to the ipoint preceding the removed sequence. + Example 3.65: Using replace filter with adjust_times option + r := replace ( ( 130, . ) .* ( 129, . ), ); + r.adjust_times; + + +RVS Filters Guide vWF20190404 53 +Pattern replacement Writing RVS filters + + + Example 3.66 shows the special trace markers that are inserted by the + adjust_times option. + + Example 3.66: Time manipulation with trace markers + + before: + 16 110 + 17 120 + 130 124 + 35 126 + 36 127 + 129 130 + 18 140 + 130 144 + 36 150 + 129 160 + 19 162 + + + after: + 16 110 + 17 120 + 4294967295 134 + 4294967294 140 + 18 140 + 4294967295 146 + 4294967294 162 + 19 162 + + + If the write.discard_wt option is used then the times in the output trace are + changed as shown in Example 3.67 instead of adding the trace markers. + + Example 3.67: Time manipulation with write.discard_wt option + + before: + 16 110 + 17 120 + 130 124 + 35 126 + 36 127 + 129 130 + 18 140 + 130 144 + 36 150 + 129 160 + 19 162 + + + after: + 16 110 + 17 120 + 18 134 + 19 140 + + +54 RVS Filters Guide vWF20190404 +Writing RVS filters Pattern replacement + + + Time adjustment markers can also be inserted into the trace using the replace + filter if you need to remove sections of times in a different way than can be achieved + with the adjust_times option. + + Example 3.68 shows a filter which will remove all time used by ipoints with ID 999 + from the trace. + + Example 3.68: Filter to remove time used by ipoints with ID 999 + + replace ( ( 999, t1 ) ( x, t2 ) , ( 0xFFFF_FFFF, t1 ) ( 0xFFFF_FFFE, + t2 ) ( x, t2 ) ); + + + Example 3.69: Removing time used by ipoints with ID 999 + + before: + 16 110 + 17 120 + 999 124 + 18 140 + 19 142 + + after: + 16 110 + 17 120 + 4294967295 124 + 4294967294 140 + 18 140 + 19 142 + + +3.4.3 Conditional replacement + You can perform pattern replacement on a conditional basis, using the when op- + tion to the replace filter. + + In Example 3.70, the replace operation is only carried out when the interval + between ipoints with IDs 1 and 2 is less than 100 ticks: + + Example 3.70: Trivial example of conditional pattern replacement + + r := replace((1,t1) .* (2,t2), ); + r.adjust_times; + r.when("(t2 - t1) < 100"); + + + Note + + The above example is not safe in the presence of timer-wraps. Timer-wraps + must be fixed first. + + The supported operators for the when option are as follows: + + +RVS Filters Guide vWF20190404 55 +Pattern replacement Writing RVS filters + + + Comparison operators (between two arithmetic expressions) + Equality: == + + Inequality: != or /= + + Greater-than: > + + Less-than: < + + Greater-than-or-equal-to: >= + + Less-than-or-equal-to: <= + + Boolean operators (case insensitive): + not + + and + + or + + Boolean expressions: + true + + false + + Arithmetic operators: + Addition: + + + Subtraction: - + + Division: / + + Multiplication: * + + Exponentiation: ^ or ** + + Modulus: mod + + Negation: - + + Arithmetic expressions: + Literal number + + A variable from the left hand pattern of the replace expression + + +56 RVS Filters Guide vWF20190404 +Writing RVS filters Writing Python filters + + +3.5 Writing Python filters + This section describes how to write RVS filters in Python. It assumes that you are + already familiar with the Python language. + + Python code can be included in an RVS filter file as a filter or as a script. + + Note + + Python code must be compatible with Python 3.6. Python 2 is no longer + supported. + + +3.5.1 Python filters + RVS filter files can include any number of Python filters. These can be + written inline in tags, or included from an exter- + nal file with a call to python_filter naming the external file, e.g. + python_filter("expand_gray.py");. + + A Python filter is written as a single function called filter with the following + signature: + def filter(i, t, i2, t2): + ... + return (f, oi, ot, oi2, ot2) + + + Parameters i and t are the ID and time (for time measurement) or the ID and flag + vector (for coverage measurement). + + If the ipoint is an escape ipoint, then values i2 and t2 are set to the associated + values from the second part of the ipoint. If the ipoint is not an escape ipoint, then + these values are set to a constant non_escape. + + Return value f is a Boolean value and should be set to True to insert the element + into the filtered trace or False to remove the element. + + Return values oi, ot, oi2 and ot2 hold the new ipoint data to be added to the + result. To return a non-escape ipoint, set values oi2 and ot2 to non_escape. + + The following example shows a simple filter that remaps two stray ipoint IDs and + eliminates two others: + + +RVS Filters Guide vWF20190404 57 +Writing Python filters Writing RVS filters + + + Example 3.71: Simple Python filter + + + def filter(i, t, i2, t2): + if i in (2, 4): + return ( False, 0, 0, 0, 0 ) + elif i == 3: + return ( True, 5, t, i2, t2 ) + elif i == 5: + return ( True, 3, t, i2, t2 ) + else: + return ( True, i, t, i2, t2 ) + + + +3.5.2 Python scripts + RVS filter filers can include any number of Python scripts. These can + be written inline in tags, or included from an ex- + ternal file with a call to python_script naming the external file, e.g. + python_script("remap_12ms.py");. + + In contrast to a traceutils Python filter, which is called once per ipoint, a traceutils + Python script has programmatic access to the stream of ipoints. It is written as a + simple script of Python code that reads and writes ipoint data. + + The traceutils script has access to the following functions: + + (eot, i, t, wt) = get () + Get the next trace element. eot is true if the end of the input was reached. i and + t are the ipoint values, and wt is the associated wall-clock time. Note that if you + modify the value of t for timing data, you should also consider whether to modify + wt. Discrepancies between t and wt are reported in the traceutils output using + special time adjustment markers so that the subsequent analysis can take this + into account. + + Use this function when you know that there are no escape ipoints in the input data. + + (eot, i, t, i2, t2, wt, wt2) = getFull () + Get the next trace element. eot is true if the end of the input was reached. For an + escape ipoint, i, t, i2 and t2 are the escape ipoint values. For a normal ipoint, + i2 and t2 are set to non_escape. wt and wt2 are the corresponding wall- + clock times. + + Use this function when there might be escape ipoints in the input data. + + put (i, t, wt) + Write out a non-escape trace element. Values i and t are the element content, + and wt is the corresponding wall-clock time. + + +58 RVS Filters Guide vWF20190404 +Writing RVS filters Writing Python filters + + + putFull (i, t, i2, t2, wt, wt2) + Write out an escape trace element. Values i, t, i2 and t2 are the element con- + tent, and wt and wt2 are the corresponding wall-clock times. + + The following example illustrates the general structure of a traceutils Python script. + + Example 3.72: Simple Python script + + + while True: + (eot, i, t, wt) = get() + if eot: + break + if i not in ( 2, 4 ): + if i == 3: + put ( 5, t, wt ) + elif i == 5: + put ( 3, t, wt ) + else: + put ( i, t, wt ) + + + +3.5.3 Reserved words + Some words are reserved in the processing of the Python scripts. If these words + are used in Python scripts, the RVS filter will fail: + + sys, time, trace, get, put, getFull, put- + Full, non_escape, __P + + +RVS Filters Guide vWF20190404 59 +Writing C filters Writing RVS filters + + +3.6 Writing C filters + This section describes how to write RVS filters in C. It assumes that you are already + familiar with the C language. + + C code can be included in RVS filter files as a script. RVS filter files can include + any number of C scripts. C scripts are written inline in tags, or + included from an external file with a call to c_script naming the external file, + e.g. c_script("remap_12ms.c");. + + A traceutils C script has access to blocks of trace data. Each script must de- + fine a C function named filter_block. This function is called repeatedly by + traceutils on successive blocks from the trace input. The function may modify + ipoint values and timestamps and remove elements from the block. Elements may + be appended to the end of the output trace using a second C function named + filter_flush. This second function is optional. + + The C functions run within a C environment provided by the Tiny C Compiler (TCC), + which is embedded within traceutils. No external C compiler is required. + + In addition to the standard C types, the following special types are defined in the + C script environment: + typedef struct t_trace_elt { + unsigned int i; /* ipoint value */ + unsigned int i2; /* (used for escape ipoints) */ + unsigned long long t; /* Timestamp */ + unsigned long long t2; /* (used for escape ipoints) */ + unsigned long long wt; /* wall-clock timestamp */ + unsigned long long wt2; /* (used for escape ipoints) */ + } t_trace_elt; + + typedef t_trace_elt * t_trace_elts; + + + The filter_block function must be defined as follows: + + void filter_block (t_trace_elts trace, unsigned int * last) + { + /* user-defined C code */ + } + + + + trace is a pointer to an array of zero or more t_trace_elt records, each + representing a single trace element. The total number of t_trace_elt records + is given by *last. User-defined C code should avoid any assumptions about the + value of *last. + + The filter_block function should iterate through the elements in trace. If + elements are removed, the value of *last can be set to a smaller number. How- + ever, the value of *last cannot be increased. User-defined C code must not ac- + cess any trace array index greater than or equal to *last. + + +60 RVS Filters Guide vWF20190404 +Writing RVS filters Writing C filters + + + filter_block is typically invoked many times during trace processing. It may + make use of global and static variables to store information between invocations. + + filter_block cannot increase the number of elements in a block. However, + you can define a second C function named filter_flush which appends el- + ements to the end of a trace. If filter_flush is defined, it is called when every + input trace element has been processed. + + The filter_flush function must be defined as follows: + + void filter_flush (t_trace_elts trace, unsigned int * valid) + { + /* user-defined C code */ + } + + + + The filter_flush function is called with *valid = 0. However, there is + space for exactly one element in the trace array. If the user-defined C code wish- + es to write an additional element to the trace output, it should set *valid = 1 and + copy the element into trace. The function is called again if it sets *valid = 1. + + The following example illustrates the general structure of a traceutils C script. The + script applies an arithmetic operation to each ipoint value. + + + Example 3.73: Trace elements modified using a C script + + + void filter_block (t_trace_elts trace, unsigned int * last) + { + unsigned int j; + + for (j = 0; j < *last; j++) { + trace[j].i = trace[j].i % 100; + } + } + + + + The following example shows how a C script may be used to remove elements + from a trace. Elements with an ipoint value less than 10 are removed. The total + number of elements in the trace block is reduced, so *last is updated before + leaving the filter_block function. + + +RVS Filters Guide vWF20190404 61 +Writing C filters Writing RVS filters + + + Example 3.74: Trace elements removed using a C script + + + void filter_block (t_trace_elts trace, unsigned int * last) + { + unsigned int j, k; + + for (j = k = 0; j < *last; j++) { + if (trace[j].i > 9) { + trace[k] = trace[j]; + k++; + } + } + *last = k; + } + + + + The following example shows how a C script may be used to combine elements + within a trace. Each pair of consecutive elements are merged into one. As an + odd number of elements may be given to filter_block, the filter_flush + function is needed to write the final element. Global variables are used to store + the filter state. + + Example 3.75: Trace elements combined using a C script + + + t_trace_elt last_element; + unsigned int first = 1; + + void filter_block (t_trace_elts trace, unsigned int * last) + { + unsigned int j, k; + + for (j = k = 0; j < *last; j++) { + if (first) { + last_element = trace[j]; + first = 0; + } else { + trace[k] = trace[j]; + trace[k].i += last_element.i * 256; + k++; + first = 1; + } + } + *last = k; + } + + void filter_flush (t_trace_elts trace, unsigned int * valid) + { + if (!first) { + *valid = 1; + trace[0] = last_element; + first = 1; + } + } + + + +62 RVS Filters Guide vWF20190404 + diff --git a/docs-extracted/src/scov/RVS/doc/Troubleshooting_Guide.md b/docs-extracted/src/scov/RVS/doc/Troubleshooting_Guide.md new file mode 100644 index 000000000..e951176c3 --- /dev/null +++ b/docs-extracted/src/scov/RVS/doc/Troubleshooting_Guide.md @@ -0,0 +1,9891 @@ +--- +title: "Troubleshooting Guide" +source: "./src/scov/RVS/doc/Troubleshooting_Guide.pdf" +category: "src/scov/RVS/doc" +pages: 176 +extracted: "2026-07-06T23:15:57.771668" +--- + +# Troubleshooting Guide + +> Extracted from `./src/scov/RVS/doc/Troubleshooting_Guide.pdf` (176 pages). +> Figures, diagrams, and tables may not render accurately in plain text. + +Troubleshooting Guide + Version WF20190404 +Disclaimer +The information, text, and graphics contained within this document are +provided for information purposes only by Rapita Systems Ltd. Rapita +Systems Ltd. does not warrant the accuracy or completeness of the +information, text, and other items contained in this document. + + +Copyright and Trademarks +All rights reserved. Information and images contained within this doc- +ument are copyright and the property of Rapita Systems Ltd. All trade- +marks are hereby acknowledged to be the properties of their respective +owners. + + +Acknowledgments +Rapita Systems' tools are built using AdaCore's GNAT Pro compiler. + + +Rapita Systems Ltd. +Registered in the UK, number 5011090. +Registered address: +Atlas House +Link Business Park +Osbaldwick Link Road +York +YO10 3JB +UK +Phone: +44 (0) 1904 413 945 +http://www.rapitasystems.com/ +This document copyright © 2016-2019, Rapita Systems Ltd. + +Document build 118520 + +ID: DOC/16004 + Table of Contents + + 1. About this guide ............................................................... 5 + 1.1. Who should read this guide? ................................................... 5 + + 1.2. Structure of this guide ........................................................... 5 + + 1.3. Notation ............................................................................ 5 + + 1.4. RVS documentation map ........................................................ 6 + + 1.5. Support ............................................................................. 7 + + + 2. Known Issues ................................................................... 9 + 2.1. (nnnn) Template known issue ................................................... 9 + + 2.2. (608) Recognizing compiler intrinsics .......................................... 9 + + 2.3. (1113) RVS pragmas cause CodeWarrior errors ............................ 10 + + 2.4. (1308) Failure to read TLA narrow columns ................................. 11 + + 2.5. (1791) replace filter with wildcard ......................................... 11 + + 2.6. (2303) Aggregation of Min- or Max-Freq is unsafe ......................... 12 + + 2.7. (2439) C++: cppins does not support some Microsoft Visual C++ ex- + tensions ................................................................................ 12 + + 2.8. (2530) C++: cppins has limited support for choosing instrumentation + profile of overloaded functions ..................................................... 12 + + 2.9. (3058) RapiCover : Using annotation 'recursive' causes an internal error + with covparser ......................................................................... 13 + + 2.10. (3211) RapiCover : Misleading presentation of dead code in C loops + ............................................................................................ 13 + + 2.11. (3215) Report viewer: #Loc-Over% column shows "Out of range" error + for some functions .................................................................... 13 + + 2.12. (3749) Searching Eclipse RVS docs uses underscore as a wildcard + ............................................................................................ 14 + + 2.13. (4346) Ada : Overriding attributes with subprograms is not supported + ............................................................................................ 14 + + +RVS Troubleshooting Guide vWF20190404 3 + Table of Contents + + + 2.14. (4440) Report Viewer: Pinning a running instance of Report Viewer to + the taskbar in Windows 7 pins Eclipse instead .................................. 14 + + 2.15. (5031) Windows: get_hostid program does not work on Windows XP + ............................................................................................ 15 + + 2.16. (5043) Windows: RVS Shell and MSys exclusive filepaths cause file not + found errors within list-files. ......................................................... 15 + + 2.17. (5415) Ada : Instrumented 'select' statement fails on trace parsing..... 15 + + 2.18. (5588) Use of C pre-processor definitions on the command line ....... 16 + + 2.19. (5891) adains ignores annotations placed after the final 'end' keyword of + a top level package or procedure ................................................. 17 + + 2.20. (6138) Ipoints with IDs lower than 10 are not considered for coverage + when using covparser --livemap option ........................................... 17 + + 2.21. (6594) Potential false positive on MC/DC coverage when jumping in the + middle of a decision ................................................................. 18 + + 2.22. (6782) It is not possible to apply inline justification to branches that only + exist on one line ...................................................................... 18 + + 2.23. (6791) It is not possible to apply inline justification annotations to calls + that span multiple lines .............................................................. 19 + + 2.24. (6825) It is not possible to apply inline justification annotations to some + "if-then-else if" type constructs ...................................................... 20 + + 2.25. (10973) Can't use environment variables within parentheses "()" in RI- + CLib ..................................................................................... 22 + + + 3. RVS User Messages ....................................................... 25 + 3.1. Errors .............................................................................. 25 + + 3.2. Warnings ........................................................................ 130 + + +4 RVS Troubleshooting Guide vWF20190404 +1 About this guide + This guide provides information on how to handle problems that you may en- + counter while using RVS. + +1.1 Who should read this guide? + This guide is intended for advanced RVS users who are encounter- + ing a problem while using RVS and want to resolve it. by contacting + support@rapitasystems.com. + +1.2 Structure of this guide + This document includes the following chapters: + + Chapter 1: About this guide + Describes the purpose and layout of this guide and the notation used throughout it. + + Chapter 2: Known Issues + Describes known issues in RVS and workarounds for them. + + Chapter 3: RVS User Messages + Lists the error and warning messages that can be provided by RVS, how to solve + problems that cause errors or warnings, and situations in which warnings can be + ignored. + +1.3 Notation + This document uses the following notation: + • References to other documents and to other chapters or sections in this doc- + ument are written in italics, for example Chapter 1: About this guide. When + reading an electronic copy of this document, you can click on a reference to + navigate to the location of the referenced element. + • Names of RVS applications are formatted in bold italics, for example RVS + Project Manager. + • References to areas or elements in user interfaces are formatted in italics, for + example the Report Navigator. + • Menus, menu choices and button labels are formatted in bold, for example + File » Print or OK. Where buttons have icons, these are shown before their + Label in in-line text, for example Save. + • Names of RVS tools are formatted in bold, for example rvsdriver. + + +RVS Troubleshooting Guide vWF20190404 5 +RVS documentation map About this guide + + + • References to HTML links appear as underlined text, for example + www.rapitasystems.com. + • Folder and file names are formatted in a monospaced font. + • Command-line tools and their commands, annotations and examples are for- + matted in a monospaced font. These are either written in-line with text + or as separate text blocks. When written in-line with text, they are formatted + like the following: rvsdriver, default_instrument, rvs_instr.h. + When written as a separate text block, they are formatted like the examples + below: + rvsdriver --project rvs.rvsprj --all + + #pragma RVS instrument( "function_name", "FALSE" ) + + • When referencing Ada code, the term functions refers to both functions and + procedures. + +1.4 RVS documentation map + This document is part of the Rapita Verification Suite (RVS) document set, which + contains the following documents: + + RVS Installation and Licensing Guide + Describes how to install RVS tools, and licensing options for them. + + RVS Integration Guide + Describes how to integrate RVS tools into build and target environments. + + RVS User Guide + Describes how to set up and run RVS projects, analyze data and export verification + results. + + RapiTest User Guide + Describes how to use RapiTest to manage test projects. + + Spreadsheet Test Format User Guide + Describes how to write tests for RapiTest in the Spreadsheet Test Format. + + RapiCover User Guide + Describes how to use RapiCover to measure code coverage and address cover- + age holes. + + RapiTime User Guide + Describes how to use RapiTime to measure timing metrics including worst-case + execution time, and how to use these metrics to identify the best optimization + candidates. + + +6 RVS Troubleshooting Guide vWF20190404 +About this guide Support + + + RapiTask User Guide + Describes how to use RapiTask to measure system level task timing information, + visualize traces and gain insight into runtime behavior. + + RTBx 2xxx User Guide + Describes how to use the RTBx data logger. + + RVS Integration Library Implementation Guide + Describes how to implement RVS integration libraries. This document is for use by + readers with a thorough understanding of the implementation of RVS. + + RVS Files Reference Guide + Describes RVS-specific files including input, intermediate and output files. + + RVS Filters Guide + Describes RVS filters, which are used to convert raw trace data into a format that + RVS can analyze, and how to write them. + + RVS Command Line Tools Reference Guide + Describes the command-line tools used by RVS, including a list of available com- + mand options. + + RVS Annotations Reference Guide + Describes the annotations you can use to control instrumentation and analysis + with RVS. + + RVS Troubleshooting Guide + Describes the error and warning messages you may encounter when using RVS + tools, and how to address them. + + RVS Migration Guide + Describes how to migrate between using different versions of RVS. + +1.5 Support + For support issues, please contact Rapita Systems Ltd. by any of the following + means: + + Email + support@rapitasystems.com + + Telephone + +44 (0) 1904 413 945 + + Website + www.rapitasystems.com + + To register for support, visit www.rapitasystems.com/register. More than one user + can register per license. + + +RVS Troubleshooting Guide vWF20190404 7 +This page intentionally left blank +2 Known Issues +2.1 (nnnn) Template known issue + Description + A known issue is a behavior of RVS that deviates from its documented features. + + Each known issue is identified by a 3 or 4 digit number in parentheses and a short + title. Using the known issue number allows you to precisely identify a particular + known issue, for example when discussing it with Rapita Systems Ltd. support. + + A known issue has a Description and one or more Work-arounds. The description + indicates the effects of the issue and the conditions under which it occurs. + + Work-arounds + The work-arounds indicate how you can avoid the issue or correct for the de- + scribed behavior. + +2.2 (608) Recognizing compiler intrinsics + Description + The RVS tools cannot recognize when a compiler intrinsics that appears to be a + function call is not, in fact, compiled to an object code function call. This causes + a problem when RVS is configured not to instrument "tight" loops. Any loop con- + taining a function call is not treated as a tight loop, so the tools fail to recognize + as a tight loop any loop containing a compiler intrinsic. + + In Example 2.1, we suppose that the compiler provides a fast way to double a + signed integer via the intrinsic call, compiler_intrinsic_double. + + + Example 2.1: A tight loop using a compiler intrinsic + + ... + for( i = 0; i < 100; ++i ) + { + result += compiler_intrinsic_double( i ); + } + ... + + + Work-around + Instrumentation of tight loops containing compiler intrinsics can be sup- + pressed by instructing the tool to ignore the call to the intrinsic with the + ignore_subprogram annotation. + +RVS Troubleshooting Guide vWF20190404 9 +(1113) RVS pragmas cause CodeWarrior errors Known Issues + + + Example 2.2: Explicit suppression of instrumentation + + ... + #pragma RVS ignore_subprogram( "compiler_intrinsic_double" ); + for( i = 0; i < 100; ++i ) + { + result += compiler_intrinsic_double( i ); + } + ... + + + For extended support for a particular compiler's extensions to the C language, + please contact Rapita Systems Ltd. + +2.3 (1113) RVS pragmas cause CodeWarrior errors + Description + Some pragma directives used by RVS to configure instrumentation and analysis + are not tolerated by the CodeWarrior compiler front-end. The result is that, rather + than just warning about an unrecognized pragma, the compiler raises an error + and fails. + + Work-arounds + 1. If the pre-processor is re-run after instrumentation, as is normally the case, a + work around for pragmas in files included by cins with -c, is to use the pre- + processor to prevent the pragmas reaching the compiler. The pre-processor + directives are ignored by the RVS tools, allowing the pragma to have the + desired effect. + + + Example 2.3: Pre-processor used to protect unacceptable pragma + + ... + #if 0 + #pragma RVS instrument( "a_function", "TRUE", "FULL-t" ); + #endif + ... + + + 2. If the pre-processor is not re-run after instrumentation, or the pragmas must + pass through the pre-processor before instrumentation (for example, be- + cause they are in-lined), stylized comments rather than pragmas can be + used. See the RVS Reference Guide for details. + + Note that when using stylized comments, care must be taken to ensure they + are not deleted in pre-processing before being passed to RVS. For exam- + ple, the GNU C pre-processor requires the -C option if it is to preserve com- + ments. + + +10 RVS Troubleshooting Guide vWF20190404 +Known Issues (1308) Failure to read TLA narrow columns + + +2.4 (1308) Failure to read TLA narrow columns + Description + RapiTime can read text files exported by a Tektronix TLA logic analyser using the + line_reader filter of traceutils. However, the exported text file is exactly the + text that appears on the screen and, if columns have been sized too narrow for the + data, there is truncation of wide values and corruption of the resulting RapiTime + trace. + + Example 2.4: Data truncation in narrow column + + ... + 15 <0.000,650 us + ... + + + Work-around + Ensure that the columns have plenty of width for the ipoint values and times listed + in them. + +2.5 (1791) replace filter with wildcard + Description + When traceutils processes a trace with a replace filter, it may fail to detect + matches for the first argument pattern if there is more than one Ipoint to match + after a .* wildcard. + + If traceutils is using the filter in Example 2.5 and encounters a sequence of Ipoint + IDs 1, 2, 4, 2, 3 then it fails to detect a match and does not perform the required + replacement. + + Example 2.5: Unsafe filter + + replace( (1, t1) .* (2, t2) (3, .), (1, t1) (2, t2) ); + + + Work-around + This problem can be avoided by ensuring that there is exactly one Ipoint to match + after each .* wildcard. To do this, first replace the sequence you wished to match + after .* with a single, synthetic Ipoint and then use that single, synthetic Ipoint + after the .* in original replace filter. Immediately after this, unmatched synthetic + Ipoints need to be reverted to their original form. The unsafe filter above has been + converted to a safe version in Example 2.6. + + Example 2.6: Safe equivalent filter + + replace( (2, t2) (3, t3), (0x8000_0023, t2, 0, t3) ); + replace( (1, t1) .* (0x8000_0023, t2, 0, .), (1, t1) (2, t2) ); + replace( (0x8000_0023, t2, 0, t3), (2, t2) (3, t3) ); + + +RVS Troubleshooting Guide vWF20190404 11 +(2303) Aggregation of Min- or Max-Freq is unsafe Known Issues + + 31 + When choosing an ID for the synthetic Ipoint, we used a value greater than 2 to + avoid any possible clash with Ipoint IDs inserted by cins. By making it an escape + Ipoint, we are able to encode the times both for Ipoint 2 and Ipoint 3 in that single + Ipoint. + +2.6 (2303) Aggregation of Min- or Max-Freq is unsafe + Description + When aggregating Min- or Max-Freq from the expanded contexts to the subpro- + gram level, the rvsviewer does not have the data required to correctly display the + aggregated values. + + Work-around + If you require correctly aggregated Min- and Max-Freq values at the subprogram + level, do not expand contexts. + +2.7 (2439) C++: cppins does not support some + Microsoft Visual C++ extensions + Description + Some compilers extension for Microsoft Visual C++ are not supported. The key- + words 'safe_cast', 'interface', 'super', 'for each', 'array', 'generic', 'interior_ptr', 'nullptr' + and 'property' are not supported. + +2.8 (2530) C++: cppins has limited support for + choosing instrumentation profile of overloaded + functions + Description + In the following code, the instrumentation pragma applies to both 'test' functions. + It is not possible to be more specific and only instrument one of the two functions + with one annotation. + #pragma RVS instrument ("test", "TRUE"); + void test (int x) { + } + + void test(char y) { + } + + + Work-around + There is no work-around for this. Redefining the instrumentation profile for a func- + tion mid-way through instrumentation is no longer supported. If you encounter this + problem, please contact Rapita Systems support. + + +12 RVS Troubleshooting Guide vWF20190404 + (3058) RapiCover : Using annotation 'recursive' +Known Issues + causes an internal error with covparser + +2.9 (3058) RapiCover : Using annotation 'recursive' + causes an internal error with covparser + Description + When the 'recursive' annotation is used the resulting RVD file can not be used by + covparser for processing a coverage map. + + Work-around + Do not use the 'recursive' annotation for using RapiCover with a map. + +2.10 (3211) RapiCover : Misleading presentation of + dead code in C loops + Description + When you have a loop in C or C++ with an unconditional break, the condition + expression (the update of a for-loop or the while-expression of a do-while) is ef- + fectively dead code. RapiCover reports that there is insufficient instrumentation + for statement coverage of this statement, rather than associating it with an instru- + mentation point, which is potentially misleading when reviewing code coverage. + The other type of C loop, the while-loop, allows the execution of the statement, but + in either case it will not be possible to get 100% MC/DC of the decision. + + Work-around + Do not use unconditional breaks in loops. + +2.11 (3215) Report viewer: #Loc-Over% column shows + "Out of range" error for some functions + Description + When viewing reports generated with earlier versions of RVS or RapiTime, the + #Loc-Over% column in the functions table (Static tab) may show an "Out of range" + error as the calculated percentage is greater than 100%. An internal change has + been made to the way that this statistic is calculated in more recent versions of the + report viewer which results in inaccurate values when older reports are opened. + + Work-around + Regenerate the structural report using the most recent version of the RVS tools to + resolve the inconsistency. This will require re-instrumentation and regeneration of + the report. If possible, please send examples of any occurrences of this problem + to Rapita Systems using the feedback tool in the report viewer. + + +RVS Troubleshooting Guide vWF20190404 13 +(3749) Searching Eclipse RVS docs uses under- + Known Issues +score as a wildcard + +2.12 (3749) Searching Eclipse RVS docs uses + underscore as a wildcard + Description + An unquoted underscore in a search term in the Eclipse help system acts as a + wildcard. This means that, for example, searching for a term such as RVS_C will + also find instances of rvs.c. + + Work-around + If searching for a term that includes an underscore, quote the search term with + double-quote characters. This will avoid the false positive matches from the wild- + card. For example, searching for "RVS_C" will only find that exact string. + +2.13 (4346) Ada : Overriding attributes with + subprograms is not supported + Description + In Ada it is possible to override attributes, such as Read, Write, Input, Output, + with user defined subprograms. RVS currently does not support analysis of this + language feature. For example, attempting to parse a trace containing data from + Ipoints within an overridden attribute subprogram will produce an unexpected + Ipoint error. + + Work-around + Implement such overridden attribute subprograms as normal subprograms in- + stead. + +2.14 (4440) Report Viewer: Pinning a running instance + of Report Viewer to the taskbar in Windows 7 pins + Eclipse instead + Description + In Windows 7, if you right-click a running instance of Report Viewer from the taskbar + and select "Pin this program to taskbar", Eclipse will be pinned instead of Report + Viewer. Using the pinned Eclipse shortcut opens Eclipse in an incorrect state and + it is not possible to view reports. + + Work-around + To pin Report Viewer to the taskbar, instead right-click on the Report Viewer short- + cut in the Start menu and select "Pin to Taskbar". + + +14 RVS Troubleshooting Guide vWF20190404 + (5031) Windows: get_hostid program does not +Known Issues + work on Windows XP + +2.15 (5031) Windows: get_hostid program does not + work on Windows XP + Description + It is not possible to obtain a valid host ID from a system running Windows XP. This + means that the RVS license server cannot be used with a license file on Windows + XP. + + Work-arounds + Run the RVS license server using a USB License Key, or install the RVS license + server on a different computer with a more recent operating system. + +2.16 (5043) Windows: RVS Shell and MSys exclusive + filepaths cause file not found errors within list- + files. + Description + Filepaths that are not valid Windows filepaths, but are understood by RVS Shell or + MSys, can cause file not found exceptions when used within list-files. + + For example when using adains with -l list.txt, where + list.txt contains the text /c/directory/main.adt. Even if + c:/directory/main.adt exists on the Windows file-system, Error E07010 + will still occur as the drive path /c/ is not recognized when used within list-files. + + Work-around + When generating list-files from MSys or RVS Shell, ensure that they are generated + with Windows compatible filepaths. + + For example if an adains list-file is generated with the command + find ./ -type f -name '*.adt' > list.txt, + the issue can be resolved if the drive path is correct- + ed through the use of the regex tool sed, as shown, + find ./ -type f -name '*.adt' | sed -e 's|^/C|c:|' > list.txt. + +2.17 (5415) Ada : Instrumented 'select' statement fails + on trace parsing + Description + The Ada 95 language contains four different form of select statement, see http:// + www.adahome.com/rm95//rm9x-09-07.html. These constructs are not supported + by RVS integrations that collect data via a trace. + + Attempting to parse a trace containing data from ipoints within select state- + ments will produce an unexpected ipoint error. + + +RVS Troubleshooting Guide vWF20190404 15 +(5588) Use of C pre-processor definitions on the + Known Issues +command line + + + Work-around + If using a trace-based integration, disable instrumentation around Ada se- + lect statements. This can be achieved by changing the instrumentation pro- + file for the enclosing subprogram (e.g. set it to TIME_FUNCTIONS) or by using + enable/disable_instrumentation annotations. + +2.18 (5588) Use of C pre-processor definitions on the + command line + Description + C code must be pre-processed before the C instrumenter can work on it, in order + to eliminate any possible confusion about function calls/macros, for instance. Af- + ter instrumentation, the instrumented code must be pre-processed again to en- + sure that the inserted instrumentation points are compiled correctly. This double + invocation of the pre-processor could lead to undesirable outcomes if the com- + mand-line instructions used contain pre-processor directives. + + Consider the code shown below. + + Example 2.7: Example code requiring command-line pre-processor directives + + ... + #if defined(Output) + #undef Output + const char *Output = "Hello World"; + #endif + + int main() + { + int Valid = 0; + printf("Message: %s\n", Output); + ... + + + The string “Output” must be defined for this to compile successfully. This can be + done by defining it on the command line, so that the initial call to the pre-processor + might be gcc -DOutput=Valid -E file.c. The code that then goes to + be instrumented has one level of preprocessor directives stripped out, and looks + like this: + + Example 2.8: Example code after pre-processing + + ... + const char *Output = "Hello World"; + + int main() + { + int Valid = 0; + printf("Message: %s\n", Output); + ... + + +16 RVS Troubleshooting Guide vWF20190404 + (5891) adains ignores annotations placed after +Known Issues the final 'end' keyword of a top level package or + procedure + This is still valid code, but if the final compilation command retains the redefinition + of the string “Output” to be “Valid”, the call to printf will try to use the local int + definition of Valid instead of the external char * one, and fail with some sort + of null pointer exception. + + This is obviously a somewhat contrived example, designed for brevity rather than + to represent production code. However, it does show that this has the potential to + cause problems, especially in code that makes heavy use of the pre-processor. + + Work-around + The process of instrumentation requires this double use of the pre-processor, so + users must be aware of it, and use command-line parameters with care. + +2.19 (5891) adains ignores annotations placed after + the final 'end' keyword of a top level package or + procedure + Description + RVS annotations inserted as Ada pragmas after the last 'end' keyword of a file are + not considered by the Ada instrumenter and thus will have no effect. + + Consider the code shown below. + Example 2.9: Example code with annotation after 'end' keyword + ... + procedure MyProcedure is + begin + pragma RVS (disable_instrumentation); + Put_Line ("Hello"); + end MyProcedure; + + pragma RVS (enable_instrumentation); + ... + + + This is valid code, but the final pragma will be ignored. This will result in an error + as the earlier annotation (disable_instrumentation) will not be matched + by a enable_instrumentation annotation. + + Work-around + Move the annotation before the last 'end' keyword of the file. + +2.20 (6138) Ipoints with IDs lower than 10 are not + considered for coverage when using covparser -- + livemap option + Description + Ipoints added manually in the source code are ignored by covpars- + er --livemap if their ID is lower than 10. + +RVS Troubleshooting Guide vWF20190404 17 +(6594) Potential false positive on MC/DC cover- + Known Issues +age when jumping in the middle of a decision + + + Work-around + In order to use manual Ipoints for livemap coverage their ID should be chosen to + be 10 or greater. + + Note + + The exclude_ipoint_IDs annotation must then be used to prevent the + chosen ID(s) from being re-used by the instrumenter. + + +2.21 (6594) Potential false positive on MC/DC coverage + when jumping in the middle of a decision + Description + If the execution path can 'jump' in the middle of a decision (i.e. somehow skipping + the evaluation of some conditions that should be evaluated) the resulting coverage + may show the skipped condition(s) as covered for MC/DC when they are not. + + Consider the code shown below. + + Example 2.10: Example of jumping in the middle of a decision + + ... + if (c) {longjmp(env,0);} + + if ( + a + && + ({setjmp(env); b;}) + + ) { + ... + + + When the longjmp is executed, the control is transferred directly to setjmp + meaning that condition a is not evaluated. + + Work-arounds + There is not work-around for this situation. Do not use setjmp/longjmp to jump + in the middle of a decision. + +2.22 (6782) It is not possible to apply inline justification + to branches that only exist on one line + Description + When writing a conditional (e.g. if statement) on a single line, it is not possible to + use inline justification annotation (i.e. justification annotations added directly in the + code) to justify the branches of the conditional construct. + + +18 RVS Troubleshooting Guide vWF20190404 + (6791) It is not possible to apply inline justification +Known Issues + annotations to calls that span multiple lines + + Consider the code shown below. + + Example 2.11: Example conditional on one line + + ... + if (Valid) {error=0;} else {error=42;} + ... + + + The justification annotation must be added within the branches but also have to + be on a separate line if in pragma form. + + Work-around + One option is to split the construct so that branches are on several lines. + + Example 2.12: Example conditional on several line + + ... + if (Valid) { + error=0; + } else { + error=42; + #pragma RVS justification ("COV_BRANCHES", "not_testable") + } + ... + + + Work-around + Another option is to use comment based justifications. + + Example 2.13: Example conditional on one line with comment justification + + ... + if (Valid) {error=0;} else {error=42;/*##RVS justification + ("COV_BRANCHES", "not_testable")*/} + ... + + + Work-around + Finally, justifications can be added at a later stage (using a justification store) via + the report viewer. + +2.23 (6791) It is not possible to apply inline justification + annotations to calls that span multiple lines + Description + When a nested function call spans multiple lines it is not possible to use inline + justification annotations (i.e. justification annotations added directly in the code) + to justify any of the calls except for the last one. + + Consider the code shown below. + + +RVS Troubleshooting Guide vWF20190404 19 +(6825) It is not possible to apply inline justifica- +tion annotations to some "if-then-else if" type con- Known Issues +structs + Example 2.14: Example multi-line nested call + + ... + big_func(new_func(x), + new_func(5), + new_func(10)); + ... + + + It is not possible to place an annotation inside the parameter list so it is not possible + to justify the first or second call to new_func. + + Work-arounds + One option is to create XML justifications through the report viewer. For more in- + formation on how to do this see the RapiCover User Guide. + + Another option is to modify the code to put the whole call on one line and then + refer to each of the calls by their position index: + + Example 2.15: Example using compound statements (GCC only) + + ... + big_func(new_func(x), new_func(5), new_func(10)); + #pragma RVS justification("COV_CALLS", "1", "reason...") + ... + + + A third option is to use the GCC compound statement extension: + + Example 2.16: Example using compound statements (GCC only) + + ... + big_func( ({ + new_func(x); + #pragma RVS justification ("COV_CALLS","reason...") + }), + ({ + new_func(5); + #pragma RVS justification ("COV_CALLS","reason...") + }), + new_func(10)); + ... + + +2.24 (6825) It is not possible to apply inline justification + annotations to some "if-then-else if" type + constructs + Description + For a typical "if-then-else if" C or C++ construct (with no curly braces for the 'else' + branch) it is not possible to use inline justifications to get 100% decision coverage + of the top-level decision. + + +20 RVS Troubleshooting Guide vWF20190404 + (6825) It is not possible to apply inline justifica- +Known Issues tion annotations to some "if-then-else if" type con- + structs + Consider the code shown below. + + + Example 2.17: Example "if-then-else if" + + ... + if (x) // << Impossible to justify when x is false + { + #pragma RVS justification("COV_DECISIONS","JUST_X_TRUE") + func(x); + } + else if (y) + { + #pragma RVS justification("COV_DECISIONS","JUST_Y_TRUE") + func(y); + } + else + { + #pragma RVS justification("COV_DECISIONS","JUST_Y_FALSE") + func(z); + } + ... + + + It is not possible to place an annotation inside the else branch of the top decision. + + Work-arounds + Add curly braces to the else branch in order to add the annotation inside the scope + of the branch. + + + Example 2.18: Example "if-then-else if" with annotation + + ... + if (x) + { + #pragma RVS justification("COV_DECISIONS","JUST_X_TRUE") + func(x); + } + else + { + #pragma RVS justification("COV_DECISIONS","JUST_X_FALSE") + if (y) + { + #pragma RVS justification("COV_DECISIONS","JUST_Y_TRUE") + func(y); + } + else + { + #pragma RVS justification("COV_DECISIONS","JUST__Y_FALSE") + func(z); + } + } + ... + + +RVS Troubleshooting Guide vWF20190404 21 +(10973) Can't use environment variables within + Known Issues +parentheses "()" in RICLib + +2.25 (10973) Can't use environment variables within + parentheses "()" in RICLib + Description + RICLib is an internal library used by RVS. One of its uses is managing data need- + ed to run RVS, which may include using system environment variables. In RICLib, + environment variables are written as $((ENVVAR)). While the value of an envi- + ronment variable can include parentheses, e.g. ProgramFiles(x86), it is not + possible to use an environment variable directly within parentheses. + + Consider the environment variable shown in Figure 2.1, which has been added to + the RVS Config Editor in the RVS Project Manager. + + + Figure 2.1: Specifying environment variables in RVS + + ($((ENVVAR))) is parsed incorrectly by RICLib, as a variable named + ENVVAR). This will likely cause an issue when trying to run RVS. + + Work-arounds + To use an environment variable within parentheses, you can first assign it to a RI- + CLib variable, then use the RICLib variable in the place of the environment vari- + able. In the example below, the custom variable X is set to the environment vari- + able ENVVAR, and Y is set to (${{variable[@variable-name='X']}}). + ENVVAR is set to the string 'var', so the resulting output of Y is the string '(var)'. + + +22 RVS Troubleshooting Guide vWF20190404 + (10973) Can't use environment variables within +Known Issues + parentheses "()" in RICLib + + + Figure 2.2: Specifying environment variables in RVS + + +RVS Troubleshooting Guide vWF20190404 23 +This page intentionally left blank +3 RVS User Messages + This document lists the error and warning messages that can be issued by RVS. + + These messages are uniquely identified by a code with format + where is the letter 'E' for errors and 'W' for warnings and is a five + digit identifier where the first two digits represent the message class and the last + three digits are the identifier within that class. + + Note that messages starting with letter 'I' are for internal errors and are not docu- + mented here. Internal errors should be reported to support@rapitasystems.com + for investigation. + +3.1 Errors + This section lists the error messages that can be issued by RVS. + + Error messages are grouped by classes in the following sections. + + For each error message the following are given: + • The error number. + • A description of the error messages. + • What action should be performed to avoid the error (elimination). + • An example of the message as it would be issued by RVS. + +3.1.1 E01xxx - Ada/Gnat + E01001 + + There was an error while executing the external tool '%s'. + + Elimination: Exclude the affected .adt file from the analysis. Contact + support@rapitasystems.com and supply the debug report data if possible. + : file.ext: Error E01001: An error has occurred while executing + external tool 'adt2ast' on this file. + + + E01003 + + The version of GNAT corresponding to an .adt file could not be identified. + + Elimination: Regenerate the .adt file using a version of the GNAT compiler sup- + ported by RVS. + : file.ext: Error E01003: Could not detect the version of the .adt + file. + + +RVS Troubleshooting Guide vWF20190404 25 +Errors RVS User Messages + + + E01004 + + The version of GNAT corresponding to a .adt file is not supported. + + Elimination: Regenerate the .adt file using a version of the GNAT compiler sup- + ported by RVS. + : file.ext: Error E01004: GNAT version 'gpl2012' is not supported. + + + E01005 + + The converter for this version of ADT files could not be found. + + Elimination: Regenerate the .adt file using a different version of the GNAT compiler + supported by RVS, or contact Support for information about support for this ver- + sion of the compiler. + : file.ext: Error E01005: Could not find the converter for GNAT + version 'pro 6.3': 'pro6.3/adt2ast.exe'. + + + E01006 + + The list of ADT files supplied contained files with different versions. + + Elimination: Regenerate the .adt files using a the same version of the GNAT com- + piler or modify the integration to deal with different compiler outputs separately. + : Error E01006: ADT files with different versions supplied + 'pro6.4' and 'gpl2014'. + + +3.1.2 E02xxx - Command line + E02001 + + An error was encountered while parsing command line arguments. + + Elimination: Follow the syntax specified in the help message and documentation + for the command line of the tool. + : Error E02001: -xyz + Use -h option for help. + + + E02002 + + An error was encountered while parsing command line arguments. Only one report + file is allowed. + + Elimination: Remove the extra report file from the input. + : Error E02002: Only one report file is allowed on the command + line, but 3 were given:report1.rvd, report2.rvd, report3.rvd + + +26 RVS Troubleshooting Guide vWF20190404 +RVS User Messages Errors + + + E02003 + + An error was encountered while parsing command line arguments. Only one trace + file is allowed. + + Elimination: Remove the extra trace file name from command line. + : Error E02003: Only one trace file is allowed on the command line + (trace1.rpz, trace2.rpz, trace3.rpz). + + + E02004 + + An error was encountered while parsing command line arguments. An RVD file + must be specified on the command line. + + Elimination: Add the missing RVD file name to the command line. + : Error E02004: No RVD file was specified on the command line. + + + E02005 + + An error was encountered while parsing command line arguments. A trace file + must be specified on the command line. + + Elimination: Add the missing trace file name to the command line. + : Error E02005: No trace file was specified on the command line. + + + E02006 + + The value specified for the --cext option is invalid or not supported. Use one of + the valid options provided. + + Elimination: Use one of the valid options listed in the error message. + : Error E02006: Invalid value 'tasm' for the --cext option. Valid + values are GREENHILLS, TASKING, ... + + + E02007 + + An error was encountered while parsing command line arguments. The number + of input, original and output files differ. + + Elimination: Use the same number of file names for the list of input, original and + output file names. + : Error E02007: A different number of input files (10), original + files (5) and output files (12) were specified. + + + E02008 + + There was no input file found on the command line. + + +RVS Troubleshooting Guide vWF20190404 27 +Errors RVS User Messages + + + Elimination: Add the missing input file name to the command line. + : Error E02008: Input file not found on the command line. + + + E02009 + + Error encountered while processing -o option. Cannot provide multiple input files + with -o option. Please use -d option for this purpose. + + Elimination: Use only one input file for option -o or use option -d to specifying an + output directory. + : Error E02009: Option -o cannot be used with multiple input + files. Use option -d instead. + + + E02010 + + There will be more than one instrumented file generated from this input. Please + use -d option for this purpose. + + Elimination: Use option -d rather than option -o for specifying the output. + : Error E02010: Multiple instrumented files will be generated from + this input. Use option -d. + + + E02011 + + Incorrect input file extension for the specified file. + + Elimination: Use a different file or change the extension of the file before using + the tool. + : Error E02011: Incorrect input file extension (file.xyz). + + + E02012 + + Number of bits for Ipoint numbering must be in the range 4..31. + + Elimination: Change the value for the --nbits option. + : Error E02012: Number of bits for Ipoint numbering must be in the + range 4..31. + Use -h option for help. + + + E02013 + + Number of concurrent threads for cppins must be in the range 1..16. + + Elimination: Change the value for the -j option. + : Error E02013: Number of concurrent threads for cppins must be in + the range 1..16. + Use -h option for help. + + +28 RVS Troubleshooting Guide vWF20190404 +RVS User Messages Errors + + + E02014 + + Duplicated root functions are not allowed. Please specify the root function only + once. + + Elimination: Remove the duplicate -r option(s) from the command line. + : Error E02014: The root function 'foo' has been specified on the + command line more than once using option -r. + + + E02015 + + Option -x/--move-exit-ipoints has been deprecated. + + Elimination: Remove this option from the command line. + : Error E02015: Option -x/--move-exit-ipoints has been deprecated. + + + E02016 + + An appropriate call tree root must be specified to produce an RVD file. + + Elimination: Add the missing option (either -r or --no-root) to the command line. + : Error E02016: Option -r or --no-root is required to produce an + RVD file. + + + E02017 + + Option -r is required to produce this type of output file. + + Elimination: Add the missing -r option to the command line. + : Error E02017: Option -r is required to produce this type of + output file. + + + E02018 + + The file was specified more than once on the command line. + + Elimination: Remove the duplicate file name from the command line. + : Error E02018: File 'file' was found more than once on the + command line. + + + E02019 + + The file extension used for the input file is reserved for output files. + + Elimination: Do not use this file as input or use an alternative file format/extension. + : Error E02019: Destination format is not allowed for an input + file. + + +RVS Troubleshooting Guide vWF20190404 29 +Errors RVS User Messages + + + E02020 + + The configuration for IdPack does not allow to allocate enough Ipoint Ids. + + Elimination: Modify the IdPack configuration to allow for more Id values to be used. + : Error E02020: Incorrect IdPack configuration. + Not enough Ids are available for IdPack in this configuration. + + + E02021 + + No solution was found for IdPack using the specified number of bits. + + Elimination: Modify the IdPack configuration to allow for more Id values to be used. + : Error E02021: No solution was found for the IdPack number of + bits. + + + E02022 + + All values for IdPack configuration must be in the range 1 .. 65535. + + Elimination: Modify the IdPack configuration to use only values in the range 1 .. + 65535. + : Error E02022: All values for IdPack configuration must be in the + range 1 .. 65535 + + + E02023 + + Syntax error while parsing idpack file. 'uniq_ids=TRUE' should be defined for at + least one group. + + Elimination: Add the missing 'uniq_ids=TRUE' line to the IdPack configuration file. + : file.ext: Error E02023: Syntax error 'uniq_ids=TRUE' should be + defined for at least one group. + + + E02024 + + Syntax error in IdPack configuration file. + + Elimination: Edit the IdPack configuration file to fix the syntax. + : file.ext: Error E02024: Syntax error. + + + E02025 + + The --ipoint-rewrite list must not be empty. + + Elimination: Make sure the file list provided to option --ipoint-rewrite is not empty. + : file.ext: Error E02025: No files found in the --ipoint-rewrite + list + + +30 RVS Troubleshooting Guide vWF20190404 +RVS User Messages Errors + + + E02027 + + Number of concurrent threads for adains must be in the range 1..16. + + Elimination: Change the value for the -j option. + : Error E02027: Number of concurrent threads for adains must be in + the range 1..16. + + + E02028 + + The value of -w must be in the range 1..62. + + Elimination: Change the value for the -w option. + : Error E02028: The value for option -w should be in the range + 1..62. + + + E02029 + + Only one trace/map file is allowed on the command line. + + Elimination: Remove the extra trace or map file(s) from the command line. + : Error E02029: Only one trace/map file is allowed on the command + line 'trace.rpz'. + + + E02030 + + The root function specified could not be found. A close match is suggested. + + Elimination: Change the value for the -r option. + : Error E02030: The root function 'foot' could not be found. Did + you mean 'root'? + + + E02031 + + The root function could not be found. + + Elimination: Change the value for the -r option. + : Error E02031: The root function 'function' could not be found. + + + E02032 + + A trace file must be specified on the command line. + + Elimination: Add the missing trace file to the command line. + : Error E02032: Trace file (.rpz) is required. + + + E02033 + + An XSC file must be specified on the command line. + + +RVS Troubleshooting Guide vWF20190404 31 +Errors RVS User Messages + + + Elimination: Add the missing XSC file(s) to the command line. + : Error E02033: At least one XSC file is required. + + + E02034 + + The input file must have the specified extension. + + Elimination: Use a different file as input or change the extension of this file. + : Error E02034: The input file must have extension '.rvd'. + + + E02035 + + The specified RVD or trace file is missing on the command line. + + Elimination: Add the missing file on the command line. + : Error E02035: Missing a RVD/trace file on the command line. + + + E02036 + + The instrumentation profile selected requires that option -u is used. + + Elimination: Add the missing option to the command line. + : Error E02036: Option -u is required when instrumenting for + coverage map. + + + E02037 + + When using the --base-dir option there is a duplicate entry in the file list (-l option). + + Elimination: Modify the file list to remove the duplicate source file. + : Error E02037: File 'file1' representing the source file 'file2' + is already listed. + + + E02038 + + Several outputs are to be written to the same file name. + + Elimination: Change the command line to ensure all output files have different file + names. + : Error E02038: File 'file.c' was found more than once as output. + + + E02039 + + A file name has been used more than once as input on the command line. + + Elimination: Change the command line to avoid using a file name more than once + as input. + : Error E02039: The input file 'file' has been used more than once + on the command line. + + +32 RVS Troubleshooting Guide vWF20190404 +RVS User Messages Errors + + + E02040 + + A file name has been used for both an input file and a configuration file. + + Elimination: Change the command line to avoid using the same file name for input + and configuration. + : Error E02040: The file 'file' can not be used as both + configuration and input. + + + E02041 + + A file name has been used for both an input and an output file. + + Elimination: Change the command line to avoid using the same file name for input + and output. + : Error E02041: The file 'file' can not be used as both input and + output. + + + E02042 + + The input file does not contain the #line information required to detect the path + from which it was produced by preprocessing. + + Elimination: Make sure preprocessor 'line' information are present in the input files, + or add the missing information to the file list (-l option). Alternatively if short line + directives are being used, that is line numbers only prefixed by a '#', then use the + --force-hline option. + : file.ext: Error E02042: The preprocessing path could not be + defined as no '#line' information was found in the input file. + + + E02043 + + The information found in the preprocessed file did not allow the path to be found + from which it was produced by preprocessing. + + Elimination: Add the missing information to the file list (-l option). + : Error E02043: The path from which test.c was preprocessed to + produce test.pre can not be determined. + + + E02044 + + Conflicting preprocessing directories found: A number of files have been found + with the same name in the listed preprocessing directories. It cannot be deter- + mined which of these files was the file used for preprocessing. + + Elimination: Use the file list (-l) option to add more specific detail regarding the cor- + rect file location. The file list format allows specification of a more precise source + name for each line, following a comma (e.g. src/myfile.c,lib3/src/myfile.c). + + +RVS Troubleshooting Guide vWF20190404 33 +Errors RVS User Messages + + : Error E02044: The path from which 'test.c' was preprocessed to + produce 'test.pre' can not be decided from the following list: dir1, + dir2 + + + E02045 + + The maximum Ipoint Id must be in the range 15..(2^31-1). + + Elimination: Change the value for the --maxid option. + : Error E02045: The maximum Id for Ipoint numbering must be in the + range 15..(2^31-1). + + + E02046 + + An error was encountered while parsing command line arguments. The number + of trace files does not match the number of RVD files. + + Elimination: Make sure the number of trace files given matches the number of rvd + files given. + : Error E02046: The number of trace files does not match the + number of RVD files. + + + E02047 + + An error was encountered while parsing command line arguments. Option --map- + size is required for generating this coverage map. + + Elimination: Use option --map-size on the command line. + : Error E02047: Option --map-size is required. A minimum of 8096 + bytes is recommended for generating this coverage map. + + + E02048 + + An error was encountered while parsing command line arguments. The value + specified by option --map-size is too small to generate the coverage map. + + Elimination: Specify a larger amount of available memory or reduce the scope + (instrumentation) of the analysis. + : Error E02048: The value specified by option --map-size is too + small. A minimum of 8096 bytes is recommended for generating this + coverage map. + + + E02049 + + An error was encountered while parsing command line arguments. The output + format specified by option --fmt is not valid. + + Elimination: The supported output formats are 'text', 'xml', 'csv' and 'src'. The default + is 'csv'. + : Error E02049: The output format 'text' is unknown. + + +34 RVS Troubleshooting Guide vWF20190404 +RVS User Messages Errors + + + E02050 + + An error was encountered while parsing command line arguments. The output + order specified by option --order is not valid. + + Elimination: The supported output orders are 'function_first', 'coverage_needed' + and 'file_first'. The default is 'file_first'. + : Error E02050: The output order 'function_incorrect' is not + supported. + + + E02051 + + An error was encountered while parsing command line arguments. The precision + setting specified by option --precision is not supported. + + Elimination: The supported precision settings are 0, 1 and 2. The default is 0, + meaning that percentages are rounded to the nearest decimal value. + : Error E02051: The precision setting '3' is not supported. + + + E02052 + + An error was encountered while parsing command line arguments. The specified + --consequent-missing setting is not supported. + + Elimination: The supported formats for 'consequent missing' information are 'de- + fault', 'full' and 'summary'. The default setting uses 'summary' for non-covered func- + tions, otherwise 'full'. + : Error E02052: The 'consequent missing' format 'incorrect_format' + is not supported. + + + E02053 + + taskparser requires at least one match to be found between an input RVD file and + an input trace file. No matches were found, so there is no valid input data, and + no work could be done. + + Elimination: Resolve any warnings of type W61001, and ensure that the correct + RVD files and trace files are provided to taskparser. Warning types of W61001 are + raised when given report/trace files do not corresponding to any trace/report files. + : Error E02053: Taskparser has no valid input data to process. + + + E02055 + + taskparser was given two or more --overhead trace files for a single CPU. This is + not permitted; there can be at most one overhead file per CPU. + + Elimination: Ensure that one --overhead parameter appears within each --cpu de- + finition. + + +RVS Troubleshooting Guide vWF20190404 35 +Errors RVS User Messages + + : Error E02055: Two --overhead trace were defined for CPU 1. + + + E02056 + + When used in a multicore configuration, taskparser requires at least one input RVD + file for each CPU. No RVD file was found for one of the CPUs. + + Elimination: Resolve any warnings of type W61001, and ensure that the correct + RVD files and trace files are provided to taskparser within the correct --cpu defi- + nitions. + : Error E02056: Taskparser has no valid input data to process for + CPU 1. + + + E02057 + + When used in a multicore configuration, taskparser can only produce output as + an XML trace file. (Either separately or as part of a .rvd package) + + Elimination: Specify an output XML trace file name on the command line, e.g. '- + o trace.xmltrc'. + : Error E02057: Taskparser is being used in a multicore + configuration, so the output file type must be '.xmltrc' or '.rvd'. + + + E02058 + + RVS could not read this collection of reports. + + Elimination: Ensure that the input file is a valid report collection. + : file.ext: Error E02058: Input rvd collection is invalid. + + + E02059 + + RVS requires a named output file. + + Elimination: Specify an output file using the -o option. + : Error E02059: Please use the -o option to specify an output + file. + + + E02061 + + The value for -Xmx(N)m must be a positive integer. + + Elimination: Specify a positive integer for the maximum JVM memory allocation. + : Error E02061: '-2048' is not valid for the -Xmx(N)m option. + + + E02062 + + The build ID given to the tool was an empty string. + + Elimination: Amend the build ID to be a non-empty string. + + +36 RVS Troubleshooting Guide vWF20190404 +RVS User Messages Errors + + : Error E02062: The supplied build ID, using --build-id, was an + empty string. + + + E02063 + + The VCS ID regular expression supplied using --VCS-regexp was not valid and + could not be parsed by xstutils. + + Elimination: The RVS Reference Guide has some examples of regular expressions + that can be used with --VCS-regexp. + : Error E02063: The VCS ID regular expression 'badregex' is not + valid: reason. + + + E02064 + + This tool requires RVD files as input. + + Elimination: Specify either a directory or a list of RVD files. + : Error E02064: No RVD files specified. + + + E02065 + + This tool is missing a required option. + + Elimination: Specify one of the required options. + : Error E02065: One of the following options is required: -a, -b, + --option-c. + + + E02066 + + The tool cannot find any test data for these reports. + + Elimination: Ensure that all tests have been included, and/or mark the master re- + port explicitly with --master report.rvd + : Error E02066: There are no tests for the following reports: + report1.rvd report2.rvd. + + + E02068 + + An error was encountered while parsing command line arguments. Globbing is + not allowed for use with the option. + + Elimination: Specify option parameters without globbing. + : Error E02068: Option --create-map does not accept globbing in + parameter(s). Invalid parameter *.adb was used. + + + E02069 + + An invalid file extension was used. + + +RVS Troubleshooting Guide vWF20190404 37 +Errors RVS User Messages + + + Elimination: Make sure that the input file name has the correct file extension. + : Error E02069: Unexpected file extension '*.txt' for input on + file 'file.c'. Expected file extension(s): '.rvd or .xsc'. + + + E02070 + + An invalid time unit was specified. + + Elimination: Use a valid time unit. + : Error E02070: Invalid parameter 'years' for --time-units. Valid + values are: cycles, seconds, milliseconds, microseconds, nanoseconds, + picoseconds or femtoseconds. + + + E02071 + + When specifying alternative output file(s), the number of output files must match + the number of input reports. + + Elimination: Either specify an output file for each input report, or else omit the -o + option to modidy the reports in place. + : Error E02071: The number of output reports requested with -o (1) + does not match the number of input reports given (2). + + + E02072 + + An error was encountered while parsing command line arguments. The output + format specified by option --fmt is not valid. + + Elimination: The supported output formats are 'text', 'xml' and 'csv'. The default is + 'csv'. + : Error E02072: The output format 'text' is unknown. + + + E02073 + + The value specified was not a valid minor feature. + + Elimination: Ensure that the feature specified is a valid minor feature. + : Error E02073: Invalid minor feature name 'RPT_RAPITIMW', must be + one of 'RPT_RAPITIME RPT_C RPT_ADA...'. + + + E02074 + + The value specified for the segment size was not valid. + + Elimination: Specify a segment size within the supported range or contact cus- + tomer support. + : Error E02074: The minimum segment size is 256 Bytes. + + +38 RVS Troubleshooting Guide vWF20190404 +RVS User Messages Errors + + + E02075 + + An invalid numerical value was specified for the option. + + Elimination: Use a value from the indicated range. + : Error E02075: The numerical value '-89' for option '--test-id' + is not in the allowed range (0..65535). + + + E02076 + + Sizes (in number of bytes) specified for parameters of the map generation must + be multiple of 16. + + Elimination: Round the value up or down to be a multiple of 16. + : Error E02076: The size specified for option --map-size (254 + bytes) must be a multiple of 16 (e.g. 256). + + + E02079 + + The RVD was generated with a specific clock frequency and therefore --clock-hz + should either match this frequency or --clock-hz option should not be used. + + Elimination: Remove the --clock-hz option or set --clock-hz to match the generated + RVD or when timeparser is run, change the --clock-hz option to match the value + passed to timexport. + : Error E02079: Cannot change clock frequency of RVD 'report.rvd' + to '100hz'. The report already has a set clock frequency of '200hz'. + + + E02080 + + No clock frequency could be found in the RVD therefore --clock-hz is required + when --time-units is being used. + + Elimination: Use option --clock-hz when running timeparser or timexport. + : Error E02080: Option --time-units requires option --clock-hz as + a clock frequency was not found in RVD 'report.rvd'. + + + E02081 + + A root function of an RVD cannot be stubbed. + + Elimination: Specify a different root function using the -r option or a different func- + tion to be set as stubbed using the --stubbed option. + : Error E02081: Cannot apply option '--stubbed' to root function + 'func0'. Option '--stubbed' can only be applied to non-root functions. + + + E02082 + + The input file name was invalid. + + +RVS Troubleshooting Guide vWF20190404 39 +Errors RVS User Messages + + + Elimination: Make sure that the input file name is a non-empty string with one of + the given extensions. + : Error E02082: Invalid file name '.abc' for input. File name must + be a non-empty string with extension(s): .rvd or .xsc. + + + E02083 + + The input file name is a file extension with no name. + + Elimination: Make sure the provided file name is more than a file extension. + : Error E02083: The file '.c' has no name (only an extension). + + + E02084 + + The root function specified could not be found. Close matches are suggested. + + Elimination: Change the value for the -r option. + : Error E02084: The root function 'foot' could not be found. Did + you mean one of the following?\n 'root1'\n 'root2' + + + E02085 + + No action was specified for the tool + + Elimination: Choose an action to call on the command line for this tool. + : Error E02085: No action specified on the command line + + + E02086 + + The wildcard root regular expression supplied using -r was not valid and could not + be parsed by xstutils. + + Elimination: Correct the error(s) in the regular expression. + : Error E02086: The wildcard root regular expression 'badregex' is + not valid: reason. + + + E02087 + + One of the regular expressions in the --static-merge list was not valid and could + not be parsed by the instrumenter. + + Elimination: Correct the error(s) in the regular expression. + : Error E02087: The --static-merge regular expression 'badregex' + is not valid: reason. + + + E02088 + + An error was encountered while parsing command line arguments. The value + specified by option --memdump-size is too small to dump the generated map. + + +40 RVS Troubleshooting Guide vWF20190404 +RVS User Messages Errors + + + Elimination: Specify a larger amount of memory to dump or reduce the scope + (instrumentation) of the analysis. + : Error E02088: The value '1024' specified by option --memdump- + size is too small. A minimum of 2048 bytes is required for dumping this + map. + + + E02089 + + The --mode option must be either 'aero' or 'auto'. + + Elimination: + : Error E02089: The --mode option must be either 'aero' or 'auto'. + + + E02090 + + The --update parameter must be followed by an .rvd file (not a collection of reports, + or any other kind of file). + + Elimination: + : Error E02090: The --update parameter must be followed by an .rvd + file (not a collection of reports, or any other kind of file). + + + E02091 + + Segmented maps are only supported for the Ada language. Therefore, the --seg- + ment option requires an Ada output file for --create-map. + + Elimination: Specify an Ada output file for --create-map. + : Error E02091: The --segment option can only be used with Ada + maps. + + + E02092 + + The specified set of command-line options require a map template that is not + available. The choice of template is affected by --map-template, --segment, --ad- + dress-16 and the file extension used with --create-map. Some combinations are + not available. For example, the --segment option can only be used with Ada out- + put, while the XC2000 template can only be used with C output. + + Elimination: Contact customer support for assistance with the options used to + generate coverage maps. + : Error E02092: No map template is available for the specified set + of options: options. + + + E02093 + + Statically initialized maps (--static-init) can only have a specified base address + (--map-base) in certain circumstances. They are only supported for the Ada lan- + guage, and then only when the deprecated --coverage-map option is used. + + +RVS Troubleshooting Guide vWF20190404 41 +Errors RVS User Messages + + + Elimination: Contact customer support for assistance with the options used to + generate maps. + : Error E02093: The --static-init and --map-base options cannot be + used together for universal maps. + + + E02094 + + The requested feature or tool is not available in this Express version of RVS. + + Elimination: Contact customer support for assistance. + : Error E02094: Option --xyz is not available in RVS Express for + ABC + + + E02095 + + clone_helper has been given a language which is unknown. + + Elimination: Pass a file with a known source extension (.adb, .c, .cpp) or specify + the language as one of "ada", "c", or "cpp". + : file.ext: Error E02095: Invalid language specified. Use one of + 'ada', 'c' or 'cpp' + + + E02096 + + clone_helper has been given an instrumenter which is unknown. + + Elimination: Pass a file with a known source extension (.adb, .c, .cpp) or specify + the instrumenter as one of "adains", "cins", or "cppins". + : file.ext: Error E02096: Invalid instrumenter specified. Use one + of 'adains', 'cins' or 'cppins' + + + E02097 + + The environment variables RVS_PROJECT and RVS_INTEGRATION must be set + in order for clonehelper to function correctly. + + Elimination: Run clonehelper from within rvsdriver. + : Error E02097: Integration helper tools must be run from + rvsdriver + + + E02098 + + The --dry-run flag has been provided to rvsdriver with a command line which does + not result in either the prepare, commit or build stages being run. + + Elimination: Either remove the --dry-run flag or ensure the supplied arguments + result in prepare, commit or build being run. + : Error E02098: --dry-run may only be used when either committing, + building or preparing the codebase. + + +42 RVS Troubleshooting Guide vWF20190404 +RVS User Messages Errors + + + E02099 + + An error was encountered while parsing command line arguments. A coverage + map or livemap file must be specified on the command line. + + Elimination: Add the missing trace file name to the command line. + : Error E02099: No coverage map file was specified on the command + line. + + + E02100 + + When used to only process virtual tasks, taskparser does not use RVD data. + + Elimination: Remove any RVD files and non-virtual task traces from the command + line. + : Error E02100: Taskparser is being used for virtual tasks only, + so an RVD file must not be specified. + + + E02101 + + When used to only process virtual tasks, taskparser can only produce output as + an XML trace file. + + Elimination: Specify an output XML trace file name on the command line, e.g. '- + o trace.xmltrc'. + : Error E02101: Taskparser is being used for virtual tasks only, + so the output file type must be '.xmltrc'. + + + E02102 + + Checkparser must be called with a .tfa or a .check file as one of its arguments. + + Elimination: Pass a .tfa or .check file when calling checkparser. + : Error E02102: Missing .tfa or .check file on the command line. + + + E02103 + + The value specified for the --cext option is invalid or not supported. Use one of + the valid options provided. + + Elimination: Use one of the valid options listed in the error message. + : Error E02103: Tasm + + + E02104 + + One test ID cannot be given two links. + + Elimination: Remove the additional --test-link argument. + + +RVS Troubleshooting Guide vWF20190404 43 +Errors RVS User Messages + + : Error E02104: Multiple --test-link options (link1 and link2) + applied to single test ID (1) + + + E02105 + + One test ID cannot be given two names. + + Elimination: Remove the additional --test-name argument. + : Error E02105: Multiple --test-name options (name1 and name2) + applied to single test ID (1) + + +3.1.3 E03xxx - EXF files + E03001 + + The EXF file is not compatible with this version of RVS and must be re-generated. + + Elimination: Delete the EXF file and repeat instrumentation. + : file.ext: Error E03001: The EXF file is not compatible with this + version of RVS. + + + E03004 + + The EXF file seems to be corrupted. + + Elimination: Delete the EXF file and repeat instrumentation. + : file.ext: Error E03004: EXF file seems to be corrupted. + + + E03005 + + Could not write to the EXF file. + + Elimination: Check that the EXF file can be created, and that it is not read-only, + and repeat instrumentation. + : Error E03005: Could not write to the EXF file 'file.exf' + + + E03007 + + Could not read the EXF file. + + Elimination: Delete the EXF file and repeat instrumentation. + : Error E03007: Could not read the EXF file 'file.exf'. + + + E03008 + + The EXF file is not valid. + + Elimination: Delete EXF file and repeat instrumentation. + : Error E03008: The file 'file.exf' is not a valid EXF file. Use a + different file or delete it and start again. + + +44 RVS Troubleshooting Guide vWF20190404 +RVS User Messages Errors + + + E03009 + + Failed to rename an EXF file. + + Elimination: Check that the source and target files are writable. + : Error E03009: Failed to rename the EXF file 'file1' to 'file2' + + + E03010 + + The EXF file name is not valid. + + Elimination: Use a valid file name for the --exf parameter. + : Error E03010: The file name 'aux' is not a valid EXF file name. + Use a different file name. + + + E03011 + + The path given to the --exf option is a directory. EXF data cannot be stored here; + a file name is required. + + Elimination: Specify a different path for the --exf option. + : Error E03011: The path given to the --exf option ('dir.exf') is + a directory. + + + E03012 + + The EXF backup file name is not valid and cannot be used. The EXF backup file + name is derived from the --exf option. The backup file name must be readable, + writable and not a directory. + + Elimination: Specify a different path for the --exf option. + : Error E03012: The EXF backup file 'backup.exf' is not valid and + cannot be used. It is a directory. + + + E03013 + + The EXF file contains unique Ipoint Ids. It cannot be used without the -u option or + a profile that automatically applies the -u option. + + Elimination: Delete the EXF file. + : Error E03013: The EXF file 'file.exf' contains unique Ids and + cannot be used without the -u option. + + + E03014 + + The EXF file contains non-unique Ipoint Ids. It cannot be used with the -u option + or a profile that automatically applies the -u option. + + Elimination: Delete the EXF file. + + +RVS Troubleshooting Guide vWF20190404 45 +Errors RVS User Messages + + : Error E03014: The EXF file 'file.exf' contains non-unique Ids + and cannot be used with the -u option. + + +3.1.4 E04xxx - Trace/Map filters + E04001 + + There was an error while generating the demux filter. + + Elimination: Make sure the entry and exit Ipoint Ids of all the root subprograms + are unique. + : Error E04001: Unable to generate demux filter. + Ipoint 12334 is not unique. It is an entry for the root function 'foo'. + + + E04002 + + Patterns cannot be used in a demux_filter. + + Elimination: Modify the parameter(s) for the demux filter in the filter file. + : file.ext: Error E04002: Patterns cannot be used in a demux + filter + + + E04003 + + Bit ranges must be [MSB:LSB] numbering with the lowest bit as 0 + + Elimination: Modify the parameter(s) for the 'read.byte_reader' configuration option + in the filter file. + : file.ext: Error E04003: Bit ranges must be [MSB:LSB] numbering + with the lowest bit as 0. + + + E04004 + + The specified filter configuration option cannot be applied to this filter. + + Elimination: Modify the parameter(s) for the filter in the filter file. + : file.ext: Error E04004: 'when' cannot be applied to this filter. + + + E04005 + + Could not add pattern constraint to this filter. + + Elimination: Modify the parameter(s) for the filter in the filter file. + : file.ext: Error E04005: Could not add pattern constraint to this + filter. + + + E04006 + + Could not add Ipoint pattern to this filter. + + Elimination: Modify the parameter(s) for the filter in the filter file. + + +46 RVS Troubleshooting Guide vWF20190404 +RVS User Messages Errors + + : file.ext: Error E04006: Could not add Ipoint pattern to this + filter. + + + E04007 + + Adjustments must be applied only to the replacement part of a 'pattern'. + + Elimination: Modify the parameter(s) for the filter in the filter file. + : file.ext: Error E04007: Adjustments must be applied only to the + replacement part of a 'pattern'. + + + E04008 + + There is a syntax error in the filter file. + + Elimination: Modify the filter file to resolve the error. + : file.ext: Error E04008: Syntax error: details + + + E04009 + + Syntax error in 'read.byte_reader' format. + + Elimination: Modify the parameter(s) for the 'read.byte_reader' configuration option + in the filter file. + : file.ext: Error E04009: Syntax error in 'read.byte_reader' + format: expected 'B' + + + E04010 + + Escape and min_delta are incompatible. Escape Ipoints must be created after + min_delta using replace. + + Elimination: Modify the filter file. + : Error E04010: Escape and min_delta are incompatible. Escape + Ipoints have to be created after min_delta using replace. + + + E04011 + + Multiplying or dividing by zero is not permitted in a scaling filter. + + Elimination: Modify the parameter(s) for the filter in the filter file. + : Error E04011: Multiply or divide by zero is not permitted in a + scaling filter. + + + E04012 + + Trace time exceeds wrap nbits modulus. + + Elimination: Use the correct value for the wrap filter or option. Check that there + are no wrap filters being applied to already-wrapped values. If you have specified + the number of bits correctly, there may have been corruption of the timestamps in + + +RVS Troubleshooting Guide vWF20190404 47 +Errors RVS User Messages + + + the trace data. Check that the data is transferred correctly from the target, via the + capture device, to the trace data file on the host. + : Error E04012: Trace time exceeds wrap nbits modulus. + + + E04013 + + Scale filter overflow during multiplication operation. + + Elimination: Scale the time by a smaller factor. If the factor is correct but the error + still persists, there may have been corruption of the timestamps in the trace data. + Check that the data is transferred correctly from the target, via the capture device, + to the trace data file on the host. + : Error E04013: Scale filter overflow on multiply. + + + E04014 + + The specified deinstrumentation value is too large. + + Elimination: Perform calibration to find the correct deinstrumentation value. + : Error E04014: Deinstrumentation value '12:12:12' is too large. + + + E04015 + + Lexical error in filter file. + + Elimination: Modify the filter file. + : Error E04015: Lexical error detected in the filter file + + + E04016 + + Syntax error in filter file. + + Elimination: Modify the filter file. + : Error E04016: Syntax error in filter file. + + + E04017 + + Error in the replace pattern in filter the file. + + Elimination: Modify the parameter(s) for the filter in the filter file. + : Error E04017: Replace pattern error. + + + E04018 + + A replace filter has tried to create an Ipoint with a value that is out of range. The ID + and timestamp are limited to 32 and 64 bits respectively. A common error is that + the filter tried to put a timestamp bigger than 32 bits into the ID field. + + Elimination: Modify the parameter(s) for the filter in the filter file. + + +48 RVS Troubleshooting Guide vWF20190404 +RVS User Messages Errors + + : Error E04018: Values are out of range in the pattern output. + Check if timestamp has been used as an Ipoint Id. + + + E04019 + + Start of trace pattern '^' is only permitted at start of match pattern. + + Elimination: Modify the parameter(s) for the filter in the filter file. + : Error E04019: Start of trace pattern '^' is only permitted at + start of match pattern + + + E04020 + + Pattern filter(s) must be configured with at least one Ipoint pattern. + + Elimination: Modify the parameter(s) for the filter in the filter file. + : Error E04020: Pattern filter(s) must be configured with at least + one Ipoint pattern. + + + E04021 + + Aborted filter(s) because recursive pattern match may be looping. + + Elimination: Modify the parameter(s) for the filter in the filter file. + : Error E04021: Aborted filter(s) because recursive pattern match + may be looping. + + + E04022 + + Attempted to write escape Ipoint to trace. Escape Ipoints must be filtered before + writing. + + Elimination: Add another filter to remove or transform escape Ipoint before the end + of the filter file. For example,: replace( (i1, t1, i2, t2), (i1, t1) (i2, t2) ); + : Error E04022: Attempted to write escape Ipoint to trace. + + + E04023 + + Could not read Python file. + + Elimination: Make sure that the path to the Python file specified in the filter is correct + and that the file is readable. + : Error E04023: Could not read Python file 'file.py'. + + + E04024 + + There was no 'filter' function defined in the Python code file. + + Elimination: Make sure the the Python code used as filter contains a function name + 'filter'. + + +RVS Troubleshooting Guide vWF20190404 49 +Errors RVS User Messages + + : file.ext: Error E04024: No 'filter' function defined in the + Python code. + + + E04025 + + There was no 'filter' function defined in the inlined Python code. + + Elimination: Make sure the the Python code used as filter contains a function name + 'filter'. + : Error E04025: No 'filter' function defined in the inline Python + code. + + + E04026 + + The value of the parameter for option -w should be in the range 1..62. + + Elimination: Use a value in the range 1..62 for the -w option or wrap filter. + : Error E04026: Parameter for option -w should be in range 1..62 + + + E04027 + + Deinstrumentation constant cannot be negative. + + Elimination: Use a positive value for deinstrumentation. + : Error E04027: Deinstrumentation constant cannot be negative. + + + E04028 + + No data with which to create output file. + + Elimination: Make sure that not all Ipoints are filtered out of the input trace by the + filter. + : Error E04028: No data with which to create output file + 'file.out'. + + + E04029 + + There was no 'get' or 'getFull' function called in the Python script file. + + Elimination: Make sure the Python code used as script contains a call to the 'get' + or 'getFull' function. + : file.ext: Error E04029: No 'get' or 'getFull' function called in + the Python code. + + + E04030 + + There was no 'get' or 'getFull' function called in the inline Python script. + + Elimination: Make sure the Python code used as script contains a call to the 'get' + or 'getFull' function. + + +50 RVS Troubleshooting Guide vWF20190404 +RVS User Messages Errors + + : Error E04030: No 'get' or 'getFull' function called in the + inline Python code. + + + E04031 + + Unexpected value found in the coverage map data. + + Elimination: Make sure the coverage map data was collected/extracted correctly. + : Error E04031: At line 42, found id 5 but expected 0 or 7. + + + E04032 + + The DML Ipoint routine ran out of memory for the variable size part of the coverage + map. + + Elimination: Increase the amount of memory for the coverage map (option --map- + size of rvdutils) or reduce the amount of instrumentation. + : file.ext: Error E04032: Out of memory detected for DML + instrumentation. Increase the map size. + + + E04033 + + A special event Ipoint sequence within the trace could not be interpreted by traceu- + tils. These sequences are used to store metadata such as build IDs and test IDs + within traces, but in this case, the sequence appears to be invalid, as one of the + Ipoints within it is invalid. + + Elimination: By default, event sequences begin with Ipoint number 7. In some cir- + cumstances, this number may be reused by other data within the trace, e.g. if the + range of available Ipoint numbers is restricted. You can use the --event-id option + to change the default from 7. + : Error E04033: Error detected while processing a special event in + the trace at trace element 125: Ipoint Id 256 follows special Ipoint Id + 99. + + + E04034 + + The trace contains more than one different build ID. + + Elimination: The trace has been generated incorrectly, e.g. from more than one + different build. + : Error E04034: The trace contains more than one different build + ID. + + + E04035 + + The trace filter file contains more than one instance of save_metadata. + + Elimination: save_metadata should appear at most once within the filter file. + : Error E04035: The trace filter file contains more than one + instance of save_metadata. + + +RVS Troubleshooting Guide vWF20190404 51 +Errors RVS User Messages + + + E04036 + + The same filter name is assigned to more than one filter. Names cannot be rede- + fined. + + Elimination: Choose a different name for each filter. + : file.ext: Error E04036: Filter name 'f1' redefined. + + + E04037 + + A filter name is being used before it is defined. (Filter names are case-sensitive.) + + Elimination: Ensure that the filter name is defined before it is used. + : file.ext: Error E04037: Filter name 'f1' is undefined. + + + E04038 + + The specified trace file format is not known. Run 'traceutils -h' for a list of supported + formats. + + Elimination: Use the correct extension for the trace file. + : file.ext: Error E04038: Unknown format '.xxx' given to + 'write.output_format'. + + + E04039 + + A filter configuration option contains a number that is outside of a permitted range. + + Elimination: Specify a number within the permitted range. + : file.ext: Error E04039: Invalid number '0': must be in range + 1..5. + + + E04040 + + The demux filter configuration is invalid because at least one of the Ipoints that + control the filter is defined in more than one place. + + Elimination: Make sure the entry and exit Ipoint Ids of all the root subprograms are + unique, and that there is no clash between these Ipoint ids and those used by the + operating system (e.g. activate/suspend). + : file.ext: Error E04040: Ipoint 100, defined as 'entry for + root1', has already been defined as 'exit for root2'. + + + E04041 + + The demux filter does not support special tasks of the given type. For example, + the priority-based demux filter does not support operating system overhead tasks, + while the fully-preemptive demux filter does not support unknown or idle tasks. + + +52 RVS Troubleshooting Guide vWF20190404 +RVS User Messages Errors + + + Elimination: The invalid task definition should be removed from the filter file. + : Error E04041: Special tasks of type 'overhead' are not allowed + with a priority_based demux filter. + + + E04042 + + The filter configuration specifies more than one task of the given type. + + Elimination: The invalid task definition should be removed from the filter file. + : Error E04042: A task of special type 'overhead' is already + defined. + + + E04043 + + Two tasks with the same name have been provided to the demux filter. Tasks must + have unique names so that trace data from each task can be separated into dif- + ferent output files by the demux filter. Note that tasks may be defined explicitly in + the filter file, or defined implicitly within RVD files read by traceutils. + + Elimination: Remove the incorrect task definition. + : file.ext: Error E04043: A task with name 'root1' is already + defined. + + + E04044 + + The specified task name is not known. The RVD file containing this task may not + have been loaded correctly, or an 'add_task' directive may be missing. + + Elimination: Ensure that the task name is correct and check the files being read + by traceutils. + : file.ext: Error E04044: Task with name 'root1' is not defined. + + + E04045 + + The requested configuration option can only be applied to regular tasks, as op- + posed to special tasks (idle, overhead) or interrupt tasks. + + Elimination: The configuration option must be removed. + : file.ext: Error E04045: Task with name 'root1' is not a regular + task. + + + E04046 + + One of the RVD files read by the traceutils tool did not contain a recognizable + root function. In order to be recognized by traceutils, root functions should contain + exactly one entry Ipoint and exactly one exit Ipoint. The two Ipoints must be unique. + If a root function does not match this specification, it must be manually defined + within the filter file using the 'add_task' demux option. + + +RVS Troubleshooting Guide vWF20190404 53 +Errors RVS User Messages + + + Elimination: Check that the root function is defined correctly when generating the + RVD file. + : file.ext: Error E04046: The RVD file does not contain a + recognizable root function. [Additional information] + + + E04047 + + One of the numbers specified within the filter configuration file is larger than the + maximum permitted number (2^63-1). + + Elimination: Specify a number within the permitted range. + : file.ext: Error E04047: Invalid number '0'. + + + E04048 + + A configuration option for a filter was used more than once within the filter file(s). + The option may only be used once. + + Elimination: Make sure that this option only appears once within the filter file. + : file.ext: Error E04048: The 'demux' filter configuration option + 'invalidate_cx' is used more than once. + + + E04049 + + No tasks are defined, so the demux filter has no effect, and no output will be + generated. + + Elimination: Define tasks by adding .rvd files on the command line or in the filter + file, or by using the 'add_task' option of the demux filter. + : Error E04049: No tasks: the demux filter has nothing to do. + + + E04050 + + A Python script, used from within a filter file, terminated unexpectedly due to an + error. + + Elimination: See the 'standard error' output of 'traceutils' for details of error(s) found + within Python. + : Error E04050: A Python script terminated unexpectedly. + + + E04051 + + The 'read.byte_reader' configuration option is required to read input trace files in + raw binary format (.bin) and its equivalents. + + Elimination: Add 'read.byte_reader' to the trace filter file to specify how the binary + trace data should be interpreted. + + +54 RVS Troubleshooting Guide vWF20190404 +RVS User Messages Errors + + : Error E04051: The 'read.byte_reader' configuration option is + required to read trace file 'trace.bin'. + + + E04052 + + The Ipoint assignments within the instrumented code do not match the coverage + map filter. This issue occurs if the instrumented program is changed in some way + that adds or removes Ipoints, but the program is not completely reinstrumented, + or not completely recompiled, or the RVD file is not regenerated by xstutils, or the + coverage map filter is not regenerated by rvdutils. + + Elimination: Ensure that your project is completely rebuilt from a clean state, + checking that the RVD and coverage map filter file are both regenerated. + : Error E04052: Coverage map mismatch detected. The Ipoint + assignments within the instrumented code do not match the coverage map + filter. + + + E04053 + + The C script of filter function could not be found in the filter. + + Elimination: Check that either 'filter' (for c_filter) or 'filter_block' (for c_script) is de- + fined. + : file.ext: Error E04053: Could not find function 'filter_block'. + + + E04054 + + The C script or C filter function could not be compiled successfully. + + Elimination: Fix the error(s) mentioned in the error message. + : file.ext: Error E04054: Compilation of the C code failed. + error + + + E04055 + + The C script is setting an incorrect value for parameter 'last'. + + Elimination: Check that the C script is updating parameter 'last' correctly. + : Error E04055: C script: An error occurred when updating + parameter 'last'. + + + E04056 + + The dynamic data area within the map is too small for your test cases. Various + events within tests consume dynamic data, for example failed assertions and DML + Ipoints. Your test cases have exhausted the available space for these events. + + Elimination: Increase the amount of memory for the map, simplify the test cases + which are executed together, reduce the amount of instrumentation, or remove + assertions. + + +RVS Troubleshooting Guide vWF20190404 55 +Errors RVS User Messages + + : file.ext: Error E04056: The dynamic data area within the map is + too small for your test cases. Currently the map stores 123 bytes of + dynamic data, with total size 456 bytes. Increase the map size. + + +3.1.5 E05xxx - SubTools + E05001 + + Error while executing xstutils. + + Elimination: None. See previous error message. + : Error E05001: Error while executing xstutils (pass1). + + + E05003 + + The version of c2ast and cins do not match. + + Elimination: Ensure that the version of c2ast and cins match. Ensure that your + installation of RVS is correct. + : Error E05003: Mismatch between c2ast and cins versions, c2ast: + 'v3.1', cins: 'v3.2'. + + + E05004 + + An error was encountered while parsing command line arguments. + + Elimination: Follow the syntax specified in the help message and documentation + for the command line of the tool. + : Error E05004: Input file not found on the command line. + Use +RVS_HELP option for help. + + + E05005 + + An error was encountered while parsing an XML document. + + Elimination: Follow the syntax specified in the help message and documentation + for the command line of the tool. + : Error E05005: XML parsing error. Node is not closed + + +3.1.6 E06xxx - Annotations + E06001 + + A duplicate target has been found in a call_to annotation. + + Elimination: Remove the duplicated function name from the list of targets. + : Error E06001: Duplicated target 'func' in a call_to annotation. + + +56 RVS Troubleshooting Guide vWF20190404 +RVS User Messages Errors + + + E06002 + + The value used for this profile is invalid. Please refer to the RVS Reference Guide + for information on instrumentation profiles. + + Elimination: Change the instrumentation profile to use one listed in the documen- + tation. + : file.ext: Error E06002: Unknown profile 'FUNTION-m', did you + mean 'FUNCTIONS'? + + + E06003 + + The value used for this profile is invalid. Please refer to the RVS Reference Guide + for information on instrumentation profiles. + + Elimination: Change the instrumentation profile to use one listed in the documen- + tation. + : file.ext: Error E06003: Unknown profile 'FUNTION-m'. + + + E06004 + + There were error(s) encountered in annotations. + + Elimination: Fix all the errors listed in the previous message(s). + : Error E06004: Error(s) in annotations. + [Annotation error list] + + + E06005 + + There were conflicting instrumentation profiles found for this function. + + Elimination: Use only one instrumentation profile for this function. + : file.ext: Error E06005: Conflicting instrumentation profiles + found for function 'foo'. + + + E06006 + + The profile modifier is not allowed for this instrumentation profile. + + Elimination: Do not use this profile modifier with this profile. See Reference guide + for valid combinations. + : file.ext: Error E06006: The profile modifier '-f' is not allowed + with the instrumentation profile 'FUNCTIONS'. + + + E06007 + + Invalid C++ parser patch. + + +RVS Troubleshooting Guide vWF20190404 57 +Errors RVS User Messages + + + Elimination: Fix the syntax of the C++ parser patch annotation. + : Error E06007: Invalid C++ parser patch: '12'. + + + E06008 + + Could not find matching 'cpp_ignore_end'. + + Elimination: Add a missing cpp_ignore_end annotation or remove the extra + cpp_ignore_begin annotation. + : Error E06008: Could not find matching 'cpp_ignore_end'. + + + E06009 + + Bad syntax for pragma RVS cpp_ignore_region. + + Elimination: Fix the syntax of the cpp_ignore_region annotation. + : Error E06009: Bad syntax for pragma RVS cpp_ignore_region. + + + E06010 + + Error in cpp_insert annotation syntax. + + Elimination: Fix the syntax of the cpp_insert annotation. + : Error E06010: Error in cpp_insert annotation syntax. + + + E06011 + + The annotation style specified is invalid. + + Elimination: A valid list of annotation styles is displayed. Use the annotation style + from the list specified. + : Error E06011: Invalid annotation style 'X'. Valid options are: + Y, Z, ... + + + E06012 + + Multiple wfreq annotations found in the same conditional. + + Elimination: Only one wfreq annotation should be place in each conditional + branch. + : Error E06012: Multiple wfreq annotations found in the same + conditional at foo.c:34 and foo.c:67 + + + E06013 + + The ASL subroot name must begin with 'L' (for loops) or 'R' (for manual sub-roots). + + Elimination: Change the ASL subroot name so that it begins with 'L' or 'R'. + + +58 RVS Troubleshooting Guide vWF20190404 +RVS User Messages Errors + + : Error E06013: Invalid ASL subroot specifier: '@B9'. + + + E06014 + + Could not find the loop specified in the function. + + Elimination: Use the correct loop name for the loop in that function. + : Error E06014: Could not find loop 'L99' in 'foo' + + + E06015 + + The root function specified should be set as unified (not expanded). + + Elimination: Add the annotation 'expand_calls (function,"FALSE")' or remove any + 'expand_this_call (function,"TRUE")' annotation affecting the root function. + : Error E06015: The root function 'root' should be set as unified + (not expanded). + + + E06016 + + Errors were detected while processing annotations. + + Elimination: Fix the errors listed in the error message. + : Error E06016: Errors were detected while processing annotations. + \nError in instrument annotation.\n + + + E06017 + + No suitable Ipoints found for the entry and exit of the function specified, while at- + tempting to automatically apply 'black_box_inline'. This function should be instru- + mented or an explicit black box annotation should be used to hide it. + + Elimination: Change the instrumentation profile for this function so that its entry + and exits are instrumented, or use a 'black_box' annotation to hide it. + : file.ext: Error E06017: No suitable Ipoints found for the entry + and exit of 'foo' while attempting to automatically black box it. + + + E06018 + + No suitable Ipoints were found for the entry and exit of the function specified. You + can only apply a black_box_inline annotation on subprograms which are instru- + mented. + + Elimination: Change the instrumentation profile for this function so that its entry + and exits are instrumented. + : file.ext: Error E06018: No suitable Ipoints found for the + entry and exit of 'function'. You can only apply a black_box_inline + annotation on subprograms which are instrumented. + + +RVS Troubleshooting Guide vWF20190404 59 +Errors RVS User Messages + + + E06019 + + Annotation 'black_box_inline' cannot be applied to this function. + + Elimination: Remove this annotation. + : file.ext: Error E06019: Annotation 'black_box_inline' cannot be + applied to the root function of the analysis 'foo'. + + + E06020 + + The wfreq annotation must be enclosed in a conditional block or a loop within a + loop. No suitable loop/conditional block could be found for this annotation. + + Elimination: Remove or change the location of this annotation. + : file.ext: Error E06020: The wfreq annotation must be enclosed in + a conditional block or a loop within a loop. No suitable loop could be + found for this annotation. + + + E06021 + + Syntax error in wfreq annotation. + + Elimination: Fix the syntax of the wfreq annotation. + : file.ext: Error E06021: Syntax error in wfreq annotation. + + + E06022 + + Syntax error in wfreq annotation. Variables are not allowed in parameter. The pa- + rameter must be a constant integer value. + + Elimination: Fix the syntax of the wfreq annotation. The parameter must be a con- + stant integer value. + : file.ext: Error E06022: Syntax error in wfreq annotation. + Variable not allowed. + + + E06023 + + Syntax error in wfreq annotation. Missing parameter. No expression provided. + + Elimination: Fix the syntax of the wfreq annotation. The annotation is expecting + one constant integer parameter. + : file.ext: Error E06023: Syntax error in wfreq annotation. No + expression provided. + + + E06024 + + Division by zero in annotation. + + Elimination: Fix the division by zero error in the annotation expression. + + +60 RVS Troubleshooting Guide vWF20190404 +RVS User Messages Errors + + : file.ext: Error E06024: Division by zero in annotation. + + + E06025 + + Syntax error parsing loop_max_iter annotation. + + Elimination: Fix the syntax of the loop_max_iter annotation. + : file.ext: Error E06025: Syntax error parsing loop_max_iter + annotation. + + + E06026 + + Syntax error parsing loop_max_iter annotation. Variables are not allowed in para- + meter. + + Elimination: Fix the syntax of the loop_max_iter annotation. The parameter must + be a constant integer value. + : file.ext: Error E06026: Syntax error parsing loop_max_iter + annotation. Variable not allowed. + + + E06027 + + Syntax error in loop_max_iter annotation. Missing parameter. + + Elimination: Fix the syntax of the loop_max_iter annotation. The annotation is ex- + pecting one constant integer parameter. + : file.ext: Error E06027: No expression provided in user + loop_max_iter. + + + E06028 + + Division by zero in annotation. + + Elimination: Fix the division by zero error in the annotation expression. + : file.ext: Error E06028: Division by zero in loop_max_iter + annotation. + + + E06029 + + The specified expression can never be true in the scope. + + Elimination: Make sure that the 'wp_' annotation used allows at least one value to + be selected. + : file.ext: Error E06029: This 'wp' annotation does not allow any + valid value. + + + E06030 + + A disable_instrumentation annotation was found inside an existing + disable_instrumentation block. + + +RVS Troubleshooting Guide vWF20190404 61 +Errors RVS User Messages + + + Elimination: Do not use a disable_instrumentation annotation in a section of code + where instrumentation is already disabled. + : file.ext: Error E06030: Nested disable_instrumentation + annotations are not allowed. + + + E06031 + + An enable_instrumentation annotation was found without first seeing a corre- + sponding disable_instrumentation annotation. + + Elimination: Add the missing disable_instrumentation annotation or remove the + extra enable_instrumentation annotation. + : file.ext: Error E06031: Could not find the corresponding + disable_instrumentation annotation. + + + E06032 + + Tags of the specified type can not be used for tagging annotations. + + Elimination: Use a different type of tag for tagging this annotation. + : Error E06032: Wrong type of tag (source_file) for a tagged + annotation. + + + E06033 + + Could not find the subroot specified in the function. + + Elimination: Use the correct subroot name for the subroot in that function. + : Error E06033: Could not find subroot 'R99' in 'foo' + + + E06034 + + A function is marked as no_fold, but it contains only one execution path. The pur- + pose of no_fold is to propagate multiple execution paths from a called function to + the caller, but in this case, the called function contains only one path, so no_fold + has no effect. + + Elimination: Check that path_ID is used properly within the called function. + : Error E06034: The no_fold function 'foo' contains only one + execution path + + + E06035 + + The number of execution paths has exceeded the limit set using max_wpaths. + + Elimination: Check that the number of execution paths meets expectations; each + path_ID annotation may double the number of paths. Increase max_wpaths or + modify the use of path_ID accordingly. + : Error E06035: The max_wpaths limit of 16 was exceeded in + function 'foo' where there are at least 32 execution paths. + + +62 RVS Troubleshooting Guide vWF20190404 +RVS User Messages Errors + + + E06036 + + No default_instrument annotation has been provided for the specified source + file, in which there is at least one function requiring instrumentation. The + default_instrument annotation must be given if any function will be instrumented. + Please refer to the RVS Reference Guide for information on the default_instrument + annotation. + + Elimination: Specify a default_instrument annotation such as #pragma RVS + default_instrument ("FALSE", "NONE"); + : file.ext: Error E06036: No default_instrument annotation has + been provided for this source file. + + + E06037 + + This default_instrument annotation must specify an instrumentation profile as it is + the first default_instrument annotation to be examined by the instrumenter. Please + refer to the RVS Reference Guide for information on the default_instrument anno- + tation. + + Elimination: Specify a default_instrument profile such as #pragma RVS + default_instrument ("TRUE", "TIME_FULL"); + : file.ext: Error E06037: The default_instrument annotation does + not specify an instrumentation profile. + + + E06038 + + It is probable that these profiles were intended to be combined, but this requires + parentheses around the expression. Please refer to the RVS Reference Guide for + information on combining annotation profiles. + + Elimination: Surround the expression with parentheses. + : Error E06038: '+COV_STATEMENTS' is not a valid modifier for + the COV_DECISIONS profile. To combine these profiles, add parentheses + around the expression: '(COV_STATEMENTS+COV_DECISIONS)' + + + E06039 + + Please refer to the RVS Reference Guide for information on annotation profile mod- + ifiers. + + Elimination: + : Error E06039: '+afp' is not a valid modifier for the + COV_DECISIONS profile. + + + E06040 + + A conflicting duplicate default_call_to annotation has been defined for an indirect + subprogram call. + + +RVS Troubleshooting Guide vWF20190404 63 +Errors RVS User Messages + + + Elimination: + : file.ext: Error E06040: Duplicate default_call_to annotation + 'default_call_to(funcPtr, func3, func4)' for indirect call + 'funcPtr'. The call to targets were already set by annotation + 'default_call_to(funcPtr, func1, func2)' at 'file1.c:32' . + + + E06041 + + The --add-annotations option cannot yet be used to insert this type of annotations + into an RVD. Only 'justification' annotations can be added in this version of the tool. + + Elimination: + : file.ext: Error E06041: The --add-annotations option cannot + yet be used to insert this type of annotations into an RVD. Only + 'justification' annotations can be added in this version of the tool. + + + E06042 + + An annotation cannot be placed at a particular location in a source file, because + that location is not a valid place for annotations. For example, annotations are not + permitted between the beginning of a 'switch' statement and the first 'case' label. + + Elimination: Move this annotation to another location, e.g. immediately before (or + after) a neighboring statement. + : file.ext: Error E06042: Annotations cannot be placed at this + source location. + + + E06043 + + Two justifications were found for the same element. + + Elimination: Remove one of the justifications. + : file.ext: Error E06043: There is already a justification for + this statement (file1.c:32). + + + E06044 + + A justification annotation has been specified with an ASL tag. This is not supported. + + Elimination: Use extended justifications via the GUI, or place the annotation in the + code. + : file.ext: Error E06044: Justification annotations cannot be used + with ASL tags. + + + E06045 + + The regular expression supplied to the annotation was not valid and could not be + parsed by the instrumenter. + + Elimination: Correct the error(s) in the regular expression. + + +64 RVS Troubleshooting Guide vWF20190404 +RVS User Messages Errors + + : Error E06045: The annotation regular expression 'badregex' is + not valid: reason. + + + E06046 + + An option required by an instrumentation profile was not used. + + Elimination: Use the required option when calling the instrumenter. + : Error E06046: The instrumentation profile 'COV_STATEMENTS' + requires that either --coverage-map or --coverage-livemap is used. + + + E06047 + + An option not allowed by the instrumentation profile was used. + + Elimination: Remove the disallowed option when calling the instrumenter. + : Error E06047: The instrumentation profile 'TIME_FULL' does not + allow either --coverage-map or --coverage-livemap to be used. + + +3.1.7 E07xxx - Files + E07001 + + A temporary copy of an RVD file could not be created in the directory for temporary + files. + + Elimination: Make sure the file can be created in the directory for temporary files. + : Error E07001: The temporary RVD file '/tmp/report.rvd' cannot be + created. + + + E07002 + + An RVD file could not be overwritten with new data. + + Elimination: Make sure the RVD file is writable and not locked. + : Error E07002: The RVD file 'report.rvd' cannot be updated. + + + E07003 + + The RVD file has been locked by another application. + + Elimination: Close the application that has a lock on the RVD file. + : Error E07003: The RVD file 'report.rvd' is locked. Make sure it + is not being used by another application. + + + E07004 + + Use of invalid file name. + + Elimination: Correct the file name. + + +RVS Troubleshooting Guide vWF20190404 65 +Errors RVS User Messages + + : Error E07004: The file name ':_122.rvd' is not valid. + + + E07005 + + The file extension of the input file has not been recognized or is not supported. + + Elimination: Use a supported extension for that file. + : Error E07005: Unknown file extension 'asd' for file 'test.asd'. + + + E07006 + + A file name has been used both as an input and as an output file. + + Elimination: Change the command line to avoid using the same file name as both + input and output. + : Error E07006: The file 'test.c' cannot be used as both an input + file and an output file. + + + E07007 + + There was an error writing to the file. + + Elimination: Check that the file path is valid and that you have write permissions + on the file. + : Error E07007: Cannot write to file 'report.rvd'. + + + E07008 + + There was an error reading from the file. + + Elimination: Check that the file path is valid and that you have read permissions + on the file. + : Error E07008: Cannot read from file 'report.rvd'. + + + E07010 + + The file cannot be found. + + Elimination: Make sure the file exists before using the tool. + : Error E07010: Cannot find file 'test.c'. + + + E07011 + + The file cannot be opened. + + Elimination: Make sure the file is readable before using the tool. + : Error E07011: The file 'file' cannot be opened. + + +66 RVS Troubleshooting Guide vWF20190404 +RVS User Messages Errors + + + E07012 + + This file has been locked by another application. + + Elimination: Close the application that has a lock on the file. + : Error E07012: The file 'file.rvd' is locked. Make sure it is not + being used by another application. + + + E07013 + + Could not create the specified log file. + + Elimination: Make sure the file path is valid and the file can be created. + : Error E07013: Could not create log file 'file.log'. + + + E07014 + + Cannot create the specified annotation calltree file. + + Elimination: Make sure the file path is valid and the file can be created. + : Error E07014: Cannot create file 'file.ctree'. + + + E07015 + + Could not find the extension of the file. + + Elimination: Use a file name with an extension. + : Error E07015: Unable to find the extension of file 'file'. + + + E07016 + + The file extension for the input file is wrong. + + Elimination: Use a file name with the expected extension. + : Error E07016: Unknown file extension for input file 'file.c'. + + + E07017 + + Incorrect output file extension. + + Elimination: Use a correct file extension for this output file. + : Error E07017: The extension (ext) of the output file is + incorrect. + + + E07018 + + Cannot read the specified file. + + +RVS Troubleshooting Guide vWF20190404 67 +Errors RVS User Messages + + + Elimination: Check that the file path is valid and that you have read permissions + on the file. + : Error E07018: Cannot read file 'file'. + + + E07019 + + Input files are empty. No subprogram was found. + + Elimination: Check that the instrumented source code contains some subpro- + grams. + : Error E07019: No subprogram was found in the input files. + + + E07020 + + Error writing data to disk. Device not available. This is generally caused by running + out of disk space or by losing the connection to a mounted device. Intermediate + results are not valid. + + Elimination: Make sure the disk is available and is not full. + : Error E07020: Error writing data to disk. Device not available. + + + E07021 + + Unable to open trace file for reading. + + Elimination: Check that the file path is valid and that you have read permission + on the trace file. + : Error E07021: Unable to open trace file 'trace.rpz' for reading. + + + E07022 + + Unable to open trace file for writing. + + Elimination: Check that the file path is valid and that you have write permission + on the trace file. + : Error E07022: Unable to open trace file 'trace.rpz' for writing. + + + E07023 + + Error while reading file from the --ipoint-rewrite list. + + Elimination: Check that the file path is valid and that you have read permission + on the file. + : Error E07023: Error while reading file 'file.c' from the -- + ipoint-rewrite list. + + + E07024 + + Could not read a list file. + + +68 RVS Troubleshooting Guide vWF20190404 +RVS User Messages Errors + + + Elimination: Check that the file path is valid and that you have read permission + on the list file. + : Error E07024: Could not read list file 'list'. + + + E07025 + + The specified file must be an XSC file. + + Elimination: Make sure the file is a valid XSC file (i.e. was produced by the instru- + menter). + : Error E07025: The file 'file.xsb' is not an XSC file. + + + E07026 + + Could not write to the specified file. Access denied. + + Elimination: Check you have write permission on the file. + : Error E07026: Could not write file 'file.c'. Access denied. + + + E07027 + + Input RVD file is not valid. + + Elimination: Make sure the file is a valid RVD file (i.e. was produced by xstutils). + : Error E07027: Input RVD file is not valid. + Did you generate it using 'xstutils' ? + + + E07028 + + The input RVD file appears to be empty. + + Elimination: Make sure the file is a valid RVD file (i.e. was produced by xstutils). + : Error E07028: Input RVD file appears to be empty. + + + E07029 + + RVD does not have a valid trace parsing engine. + + Elimination: Make sure the RVD file was generated by xstutils using the -r option. + : Error E07029: RVD does not have a valid trace parsing engine. + + + E07030 + + The specified directory cannot be found. + + Elimination: Make sure the directory name is valid and the directory exists. + : Error E07030: Cannot find directory 'dir'. + + +RVS Troubleshooting Guide vWF20190404 69 +Errors RVS User Messages + + + E07031 + + A syntax error was found while covexport was parsing the exclusion file. + + Elimination: Check the formatting of the specified line within the exclusion file. + : file.ext: Error E07031: Syntax error in exclusion file: details. + + + E07032 + + A syntax error was found while covexport was parsing the justification file. + + Elimination: Check the formatting of the specified line within the justification file. + : file.ext: Error E07032: Syntax error in justification file: + [Additional information]. + + + E07033 + + An exclusion could not be applied because the specified file was not found. + + Elimination: Check the file names specified in the exclusions file. + : Error E07033: No matching file was found for exclusion on + 'file'. + + + E07034 + + An exclusion could not be applied because more than one file name matched the + specification. + + Elimination: Use a more specific file name. + : Error E07034: More than one matching file was found for + exclusion on 'file'. + + + E07035 + + Unable to open a trace file as an input because the same file is being used as + an output. + + Elimination: Ensure that the output trace file name is different to every input trace + file name. Note: if the --chain-traces parameter is in use, traceutils will automati- + cally increment the first number in the input trace file name when searching for + further input. + : Error E07035: Unable to open trace file 'trace.rpz' for reading + because the file is also being used for output. + + + E07036 + + The named file was found more than once in the list of source directories. + + +70 RVS Troubleshooting Guide vWF20190404 +RVS User Messages Errors + + + Elimination: Ensure that files have unique file names. + : Error E07036: Multiple locations were found for 'file.c': dir1/ + file.c + + + E07037 + + Could not read the given XST files. + + Elimination: + : Error E07037: Could not read XST files 'test1.xsc','test2.xsc'. + + + E07038 + + When processing multiple input files, the -o option is required. + + Elimination: + : Error E07038: Please use the -o option to specify an output file + when processing multiple input files. + + + E07039 + + This option can only merge coverage to a single root report. + + Elimination: Create this report using xstutils with a single root (or --no-root) + : Error E07039: Cannot merge coverage: 'report.rvd' must contain + zero or one root(s). + + + E07040 + + Could not create the specified output file. + + Elimination: Make sure the file path is valid and the file can be created. + : Error E07040: Could not create output file 'file.out'. + + + E07041 + + The source code for these files has been modified and should be preprocessed + again. + + Elimination: Use a preprocessor to generate the input for cins/cppins. + : Error E07041: The input file source.p (last modified on YYYY- + MM-DD HH:MM:SS) includes content from the modified file source.c (last + modified on YYYY-MM-DD HH:MM:SS) + + + E07042 + + The input file is empty. + + Elimination: Make sure the provided file contains the expected data. + + +RVS Troubleshooting Guide vWF20190404 71 +Errors RVS User Messages + + : Error E07042: The file 'file.c' is empty. + + + E07043 + + The source file is not part of the base directory or any included directories. + + Elimination: Make sure all source files listed are located within the --base-dir di- + rectory tree or included with -I. + : Error E07043: The source file 'file.c' is not part of the base + directory 'source' or any included directories. + + + E07044 + + The specified test could not be found in the RVD. + + Elimination: Make sure that the correct RVD has been specified and that the test + exists in the RVD. + : Error E07044: Test ID '4' could not be found in 'file.rvd'. + + + E07045 + + No files were found in the directory. Directory may be unreadable or empty + + Elimination: Make sure the directory name is valid, contains files and is readable. + : Error E07045: No files were found in directory 'dir'. Directory + may be unreadable or empty. + + + E07046 + + Could not create the specified backup file. + + Elimination: Make sure that the directory is writable, and that there is not already + a write-protected file with this name. + : Error E07046: Could not create backup file 'file.out'. + + + E07047 + + The requested output file format requires a certain number of input files. + + Elimination: Supply the correct number of files for the requested output format. + : Error E07047: Expected 1 input file(s) for output file + type .txt. + + + E07048 + + The trace list file could not be parsed. + + Elimination: Make sure that the trace list file is syntactically correct. + + +72 RVS Troubleshooting Guide vWF20190404 +RVS User Messages Errors + + : file.ext: Error E07048: Syntax error in trace list. + + + E07049 + + The coverage element is too large to fit within for the segment size limit. + + Elimination: Increase the segment size or reduce the size of the coverage element. + : file.ext: Error E07049: Coverage element is too large for + segment size. Coverage element requires 1024 bytes. Segment size is 512 + bytes. + + + E07050 + + This instrumentation would overwrite an original source file. + + Elimination: Rename the instrumented file using -o, or place in a different directory + using --output-dir. + : Error E07050: Instrumentation would overwrite the input source + file file.c. Rename the instrumented file using -o, or place in a + different directory using --output-dir. + + + E07051 + + Data for the specified core could not be found in the RVD. + + Elimination: Make sure that the correct RVD has been specified and that data + exists for that core in the RVD. + : Error E07051: Core with ID '4' could not be found in 'file.rvd'. + + + E07052 + + One or more justification file is locked by another user or process and thus cannot + be used. + + Elimination: Wait until the user has unlocked the justification or until the lock time- + out expires + : Error E07052: The following justifications are locked:The + justification J0001 is locked by acolin since 2015-03-25 14:15:04 + + + E07053 + + The RVD already contains a file with this name. + + Elimination: Do not attempt to insert duplicate files into an RVD. + : Error E07053: Report.rvd already contains a file called file.x. + + + E07054 + + This justification directory already exists. + + +RVS Troubleshooting Guide vWF20190404 73 +Errors RVS User Messages + + + Elimination: Initialize the justification directory in a new location. + : Error E07054: The justification directory 'justpath' already + exists. + + + E07055 + + The --cmd-file passed to the tool contains invalid data. A --cmd-file can only con- + sist of printable ASCII characters, separated by newline characters. + + Elimination: Check how the --cmd-file has been generated. + : file.ext: Error E07055: The --cmd-file contains invalid data. + + + E07056 + + The given input path was a file not a directory. + + Elimination: Check that the input path is correct and that the file exists. + : Error E07056: 'file.x' is a directory not a file. + + + E07057 + + In order to support justifications, a report must contain information which cannot + be determined during an upgrade. Therefore, the report must be re-generated. + + Elimination: Regenerate this report. + : Error E07057: This rvd cannot be upgraded to support + justifications + + + E07058 + + An input file contained too many lines. + + Elimination: Reduce the number of lines in the file. Check the correct file is being + input. + : Error E07058: File 'file.x' contains too many lines. File may + only contain a maximum of '990' lines. + + + E07059 + + The specified file's content is not valid. + + Elimination: Check that the specified file is not corrupt. + : Error E07059: The content of file 'file' is not valid. + + + E07060 + + The GUID of the justification file does not match the file name. + + +74 RVS Troubleshooting Guide vWF20190404 +RVS User Messages Errors + + + Elimination: Check that the specified file is not corrupt. + : Error E07060: The GUID '54321' of the justification file + '12345.xml' does not match the file name. + + + E07061 + + The specified file's content is not valid. + + Elimination: Check that the specified file is not corrupt. + : Error E07061: The content of the justification file 'file' is + not valid. + + + E07062 + + The justification xml file is missing a required element. + + Elimination: Fix the justifications for this report. + : Error E07062: 12345.xml: No value found for 'field' + + + E07063 + + There was an issue with the "rvsconfig.ini" file. + + Elimination: Refer to the RVS Installation and Licensing Guide for information about + the correct usage of "rvsconfig.ini". + : Error E07063: Placeholder error for configlib, do not remove. + + + E07064 + + Inherited justifications were disabled for some (but not all) of the XSCs used to + generate a report. + + Elimination: Either disable justification inheritance for all sources, or none of them. + : Error E07064: Inherited justifications are disabled for + file.xsc, but not for the previous XSCs read by xstutils. + + + E07065 + + Inherited justifications were disabled for some (but not all) of the XSCs used to + generate a report. + + Elimination: Either disable justification inheritance for all sources, or none of them. + : Error E07065: Inherited justifications are enabled for file.xsc, + but not for the previous XSCs read by xstutils. + + + E07066 + + The specified directory cannot be written to. + + +RVS Troubleshooting Guide vWF20190404 75 +Errors RVS User Messages + + + Elimination: Make sure the directory name is valid and the directory is not read only. + : Error E07066: Cannot write to directory 'dir'. + + + E07067 + + covparser (or testparser) has been given an RVD file (call it 'B') and a map file, but + the map file was generated from a different RVD file (call it 'A'). The parser cannot + reliably obtain test data from the map file, because the RVD files A and B were + generated from different source code. + + Elimination: This error normally points to a problem with the integration, where a + stale file is not being updated correctly by some processing stage. Check the time + stamps for the map file and and the RVD to determine if an older version of the + RVD, map file or map template is in use. If you are completely certain that the error + can be ignored, it may be downgraded to a warning using the --no-check-build- + id option. + : file.ext: Error E07067: Detail + + + E07068 + + clone_helper has been given language which is unknown, without the --pproc-ext + flag being used. + + Elimination: Pass a file with a known source extension (.adb, .c, .cpp) or specify + the extension of the pre-processed file manually using the --pproc-ext flag. + : file.ext: Error E07068: Can not determine the pre-processed file + extension for the file sample.txt. Use --pproc-ext to specify manually. + + + E07069 + + clone_helper has either been given a preprocessed file which does not exist, or + has been unable to correctly derive the location of the pre-processed file. + + Elimination: Ensure the pre-processed file at the specified location exists, or man- + ually specify the location of the preprocessed file using the --pproc-file flag. + : file.ext: Error E07069: Can not locate the pre-processed file + at sample.txt. Ensure the file exists, or use --pproc-file to specify + manually. + + + E07070 + + clone_helper has been passed a file with an unknown extension, and cannot de- + termine the correct instrumenter to use. + + Elimination: Pass a file with a known source extension (.adb, .c, .cpp) or specify + the instrumenter manually using the --instrumenter flag. + : file.ext: Error E07070: Can not determine which instrumenter to + use for file at sample.txt. Use --instrumenter to specify manually. + + +76 RVS Troubleshooting Guide vWF20190404 +RVS User Messages Errors + + + E07071 + + clone_helper has been passed a file with an unknown extension, and cannot de- + termine the correct language of the file. + + Elimination: Pass a file with a known source extension (.adb, .c, .cpp) or specify + the language manually using the --language flag. + : file.ext: Error E07071: Can not determine the language of the + file sample.txt. Use --language to specify manually. + + + E07072 + + The specified subprogram could not be found in the RVD. + + Elimination: Make sure that the correct RVD has been specified and that the sub- + program exists in the RVD. + : Error E07072: Subprogram ID '4' could not be found in + 'file.rvd'. + + + E07073 + + A double quote character appears in an unexpected place within a field. + + Elimination: Ensure that double-quotes within fields are correctly escaped (with + an additional double-quote character), that the field itself is enclosed in dou- + ble-quotes, and that only whitespace characters or the comma separator occur + after the closing double-quote. + : Error E07073: Parse error in costs.csv, unexpected double-quote + in '"test"name"' at position 6. + + +3.1.8 E08xxx - Instrumentation + E08001 + + An error was encountered while parsing. + + Elimination: Check the source code syntax at the given location. Option --cext can + be used to add support for C/C++ extensions. + : Error E08001: Could not parse the expression around the token + 'mult'. + + + E08002 + + There was an error while parsing the input file. An unmatched comment ('/*') was + found. + + Elimination: Make sure all comments are closed in input files. + : file.ext: Error E08002: Unmatched '/*' detected in the input + file. + + +RVS Troubleshooting Guide vWF20190404 77 +Errors RVS User Messages + + + E08003 + + There was a syntax error while parsing the input file. + + Elimination: Check the source code syntax at the given location. Option --cext can + be used to add support for C/C++ extensions. + : file.ext: Error E08003: Syntax error parsing input file. + + + E08004 + + There was an error instrumenting a file when using option -j. + + Elimination: None. See previous error message. + : Error E08004: Error: Instrumentation 123 failed. + + + E08005 + + Encountered a syntax error while working on a file. + + Elimination: Check the source code syntax at the given location. Option --cext can + be used to add support for C/C++ extensions. + : Error E08005: Syntax error: Permission denied + + + E08006 + + There is no support for ASM for the given compiler extension. + + Elimination: Do not use inline assembly in the source to instrument. + : file.ext: Error E08006: This compiler extension does not support + ASM. + + + E08007 + + An unexpected end of file marker was encountered while parsing the ASM function. + + Elimination: Check the source code for inline assembly sections not properly + closed. + : file.ext: Error E08007: Unexpected end of file found while + parsing ASM function + + + E08008 + + The function has been declared as a non-static function but defined as a static + function. + + Elimination: Make sure the declaration and definition of the function are either both + static or both non-static. + + +78 RVS Troubleshooting Guide vWF20190404 +RVS User Messages Errors + + : file.ext: Error E08008: Function 'foo' declared as non-static + and defined as static. + + + E08009 + + There was an error while parsing the argument given for an Ipoint. + + Elimination: Make sure Ipoints have one constant integer parameter. + : file.ext: Error E08009: Error parsing arguments of Ipoint. + + + E08010 + + There was an error while parsing the argument given to Ipoint. The expression in + the argument does not evaluate to a constant. + + Elimination: Make sure Ipoints have one constant integer parameter. + : file.ext: Error E08010: Syntax error parsing argument to Ipoint. + The expression may not evaluate to a constant: (a + 8) + + + E08011 + + There was error evaluating the argument given to Ipoint. Found a division by zero + in the argument. + + Elimination: Fix the division by zero in the Ipoint parameter. + : file.ext: Error E08011: Division by zero in argument to Ipoint: + (a/0) + + + E08012 + + The number of bits used to generate the Ipoint Ids is not enough to instrument all + the functions in the given source files. + + Elimination: Use option --nbits with a higher number of bits, or reduce the amount + of instrumentation used. + : Error E08012: Only 5 bits for generating the Ipoint Ids is not + enough to instrument all functions. + + + E08013 + + There is a missing enable_instrumentation annotation at the end of the file. + + Elimination: Make sure all 'disable_instrumentation' annotations are followed by a + 'enable_instrumentation' annotation. + : Error E08013: Missing enable_instrumentation annotation at the + end of file 'test.c'. + + + E08014 + + The specified extension keyword is not supported. + + +RVS Troubleshooting Guide vWF20190404 79 +Errors RVS User Messages + + + Elimination: Modify the source code to avoid this unsupported keyword or exclude + this file from the analysis. + : Error E08014: The extension keyword 'asm' is not supported. + + + E08015 + + Microsoft '#include ' is not supported by RVS. + + Elimination: Use '#include ' instead. + : Error E08015: Microsoft '#include ' is not supported + by RVS. + + + E08016 + + Parse error detected in the specified file. + + Elimination: Check the source code syntax at the given location. Option --cext can + be used to add support for C/C++ extensions. + : Error E08016: Parse error detected in 'file.c': + message + + + E08017 + + There was an preprocessor error while executing the given command. + + Elimination: Check the preprocessing command separately. + : Error E08017: Preprocessor error while executing 'command' + + + E08018 + + The maximum Id for Ipoints is not enough to instrument all the functions in the + given source files. + + Elimination: Use option --maxid with a higher number of bits. + : Error E08018: The maximum Id for Ipoints (515) is not enough to + instrument all functions. + + + E08019 + + Parse error detected in one of the files specified by option -c. + + Elimination: Check the source code syntax at the given location. Option --cext can + be used to add support for C/C++ extensions. + : Error E08019: Parse error detected in an external annotation + file. + + + E08020 + + These instrumentation profiles cannot be combined together. + + +80 RVS Troubleshooting Guide vWF20190404 +RVS User Messages Errors + + + Elimination: Change the instrumentation profile. + : file.ext: Error E08020: Instrumentation profiles 'Profile A' and + 'Profile B' cannot be combined. + + + E08021 + + The --expand-multiple-case-labels option was given to the 'adains' tool, and as a + result, 'adains' detected a 'case' statement where a single 'when' statement con- + tains more than one label (e.g. 'when X | Y => ST;'). 'adains' tried to expand this + 'when' statement into separate labels (e.g. 'when X => ST;', 'when Y => ST;') so + that coverage can be obtained for each label in isolation. However, this operation + requires that the labels are enumerated type values, which they are not. + + Elimination: Manually expand the 'case' statement so that each 'when' statement + contains only one label. + : file.ext: Error E08021: This 'case' statement contains multiple + case labels, but the labels cannot be expanded into separate conditions + because they are not enumerated type values. + + + E08023 + + A mixture of coverage and timing instrumentation profiles has been used to gen- + erate the XSC files. When using either coverage or timing profiles, all of the ana- + lyzed files must be instrumented with either coverage or timing analysis. + + Elimination: Use either coverage or timing instrumentation profiles throughout your + analysis. + : Error E08023: A mix of XSC files generated using coverage and + timing instrumentation profiles was found. + + + E08024 + + 'instrumentation_point' annotations should only be placed inside a function body. + + Elimination: Remove the annotation. + : file.ext: Error E08024: An instrumentation_point annotation + found outside of a function body was ignored. + + + E08025 + + Instrumenting and already instrumented file is a sign of a problem in your build + process. + + Elimination: Make sure you are instrumenting the right files. + : file.ext: Error E08025: This input file is already instrumented. + + + E08026 + + There is more than one definition of a subprogram within the XSC files. As option + --dedupl-func was used, the tool attempted to match calls to definitions using a + + +RVS Troubleshooting Guide vWF20190404 81 +Errors RVS User Messages + + + heuristic. However, the attempt failed, because the heuristic could not distinguish + between two (or more) possibilities. + + Elimination: Do not use option --dedupl-func and make sure the called function + does not appear more than once in your XSC files. + : file.ext: Error E08026: The call to subprogram 'foo' could + not be resolved to a single subprogram, as there is more than one + possibility: file.c:53 + + + E08028 + + An instrumentation profile for timing has been used to instrument the source code + however a map instrumentation profile was expected. + + Elimination: Instrument source code with a timing instrumentation profile. + : Error E08028: The input XSC file contained timing + instrumentation profiles however a map instrumentation profile was + expected. + + + E08029 + + An instrumentation profile for coverage maps has been used to instrument the + source code however a timing instrumentation profile was expected. + + Elimination: Instrument source code with a coverage map instrumentation profile. + : Error E08029: The input XSC file contained map instrumentation + profiles however a timing instrumentation profile was expected. + + + E08030 + + When producing an RVD file, XSC files should have all been produced with unique + IDs or all without. + + Elimination: Make sure all your XSC files are produced with the same option -u + or (--coverage-map). + : Error E08030: Unique IDs XSC mismatch. The XSC file 'file.xsc' + contains unique IDs whereas previously loaded XSC files do not have + unique IDs. + + + E08031 + + When producing an RVD file, XSC files should have all been produced with unique + IDs or all without. + + Elimination: Make sure all your XSC files are produced with the same option -u + or (--coverage-map). + : Error E08031: Unique IDs XSC mismatch. The XSC file 'file.xsc' + contains non-unique IDs whereas previously loaded XSC files do have + unique IDs. + + +82 RVS Troubleshooting Guide vWF20190404 +RVS User Messages Errors + + + E08032 + + Even though all the input XSC files were produced with either the -u or --cover- + age-map option, repeated Ipoint IDs were found. The most likely cause is that the + EXF file used to instrument the source code wasn't the same for all instrumented + files or was deleted during instrumentation. + + Elimination: Make sure all your XSC files are produced using the same EXF file + during instrumentation. + : Error E08032: The set of input XSC files should only contain + unique Ipoint IDs but ID 15 was found more than once ('file1.c' and + 'file2.c'). + + + E08033 + + The inputted .adt files are different versions and therefore can not be parsed. + + Elimination: Ensure that the input adt files produced are of the same version. + : Error E08033: Mixed ADT version detected '6.2.0' and '6.4.2'. + + + E08035 + + A lazy insertion file must have a unique file target. Two or more lazy insertion file + target the same source file. + + Elimination: Use only one of the lazy insertion files, or merge the files together. + Check that the integration is correctly cleaning old injection files. + : Error E08035: Duplicate lazy insertion file. Both 'dir1/ + file.cic' and 'dir2/file.cic' target source file 'file.adb'. Only one + lazy insertion file is allowed per source file. + + + E08036 + + The annotations 'start_root' and 'end_root' cannot be nested. + + Elimination: Move the 'start_root' annotation outside of the enclosing 'start_root/ + end_root' section. + : file.ext: Error E08036: Annotation 'start_root' found inside + another root block. + + + E08037 + + The annotation 'end_root' must be preceded by a 'start_root' in the same scope. + + Elimination: Add the missing 'start_root' annotation. + : file.ext: Error E08037: Annotation 'end_root' found with no + matching 'start_root'. + + +RVS Troubleshooting Guide vWF20190404 83 +Errors RVS User Messages + + + E08038 + + The annotations 'start_root' and matching 'end_root' must be placed in the same + scope. + + Elimination: Move annotations as required so that they are in the same scope. + : file.ext: Error E08038: Annotations 'start_root' and + 'end_root' (file.c:35) must be in the same scope. + + + E08039 + + The annotation 'start_root' must be followed by a 'end_root' in the same scope. + + Elimination: Add the missing 'end_root' annotation. + : file.ext: Error E08039: Annotation 'start_root' found with no + matching 'end_root'. + + + E08041 + + A source file has not been fully instrumented, i.e. some of the ipoints could not be + added in the expected places. If the source file contains Ada code, this may hap- + pen if the file has changed on disk since it was analyzed by GNAT, or if the GNAT + preprocessor was activated using -gnatep or -gnateD. If the source file contains + C or C++ code, this may happen if the preprocessed source file does not match + the original source file. + + Elimination: Ensure that the source file and any files derived from it are up to date + (e.g. ADT file for Ada, or .i file for C/C++). For Ada, avoid the use of the GNAT + preprocessor for the affected file. + : Error E08041: The source file 'file.adb' has not been fully + instrumented. This may be because the file has changed on disk since it + was analyzed or preprocessed, or it may be due to an internal error in + the instrumenter. + + + E08042 + + An object with the same name was found in two different Ada source files. The + contents of these two files cannot coexist in the source code database created by + 'adains'. The source files cannot be instrumented. + + Elimination: If this conflict is intentional, then it will be necessary to instrument these + files separately, i.e. run 'adains' more than once. If the conflict is unintentional, + ensure that the inputs to 'adains' are consistent: none of the source files are out + of date, or in incorrect places. If a source code database existed before 'adains' + was executed, try removing it. + : Error E08042: An object named 'pkg' has been found in two + different Ada source files: 'path1/pkg.adb' and 'path2/pkg.adb'. + + +84 RVS Troubleshooting Guide vWF20190404 +RVS User Messages Errors + + + E08043 + + Encountered a very long line while working on a file. + + Elimination: Check the source code at the given location. Option --cext can be + used to transform input. + : Error E08043: Line too long: File source.c line 12345 exceeds + 1000000 characters + + + E08044 + + The annotations 'start_root' and matching 'end_root' can only appear in a body of + code: within a subprogram, package, task or protected body. + + Elimination: Move annotations as required so that they are inside a suitable body. + : file.ext: Error E08044: Annotations 'start_root' and 'end_root' + can only appear in a body of code. + + + E08045 + + The instrumenter was unable to reinstrument a source file when using the incre- + mental coverage option (--incr-coverage) to omit ipoints that are already covered + in an RVD file. In --incr-coverage mode, ipoint numbers are assigned using the + list of ipoints in the RVD. However, at least one ipoint is now at a different loca- + tion within the source code, indicating that the source code or other settings have + changed. Incremental coverage instrumentation is not possible. + + Elimination: Ensure that all settings and source code remain unchanged when + using --incr-coverage mode. If you need to update settings or source code, all + source code must be reinstrumented and the RVD file must be recreated. + : file.ext: Error E08045: Unable to reinstrument 'source.c' + using incremental coverage from 'file.rvd'. The source code or + instrumentation settings appear to have changed: the set of ipoints is + not identical. + + + E08046 + + RVD file contains coverage trace data. Support for this has been removed. + + Elimination: Regenerate RVD file using map coverage. + : Error E08046: RVD file contains coverage trace data. + + +3.1.9 E09xxx - Licensing + E09001 + + The IP Address specified by server_bind_addr is not a valid IP Address. + + Elimination: Modify the rvsconfig.ini file to provide a valid server_bind_addr value. + + +RVS Troubleshooting Guide vWF20190404 85 +Errors RVS User Messages + + : Error E09001: The IP Address specified by server_bind_addr + (1.2.3) is not a valid IP Address. + + + E09002 + + Could not bind the license server to the specified IP address. + + Elimination: Modify the rvsconfig.ini file to provide a correct server_bind_addr val- + ue. + : Error E09002: Could not bind to address (bind to address + failed). + + + E09003 + + Could not bind the license server to the given port. + + Elimination: Modify the rvsconfig.ini file to provide a different port number. + : Error E09003: Could not bind socket to port 8080. + + + E09004 + + License file not found. + + Elimination: Place the license file in the expected location. + : Error E09004: Could not find 'file'. + + + E09005 + + The port number was not set in the license key. + + Elimination: Use 'licserv --usb-license-key-port' or 'licserv --file-port' to set the li- + cense server port number. + : Error E09005: The port number was not set in the license key. + Use 'licserv --usb-license-key-port' or 'licserv --file-port' to set + the license server port number. + + + E09006 + + The report was not generated by a trial version of RVS. + + Elimination: Use the full version or RVS or re-generate the report using the trial + version of the command line tools. + : Error E09006: Cannot verify database signature. This version of + RVS will only open reports created by the trial version of the command + line tools. + + + E09007 + + There was an issue with software licensing. + + +86 RVS Troubleshooting Guide vWF20190404 +RVS User Messages Errors + + + Elimination: Contact support@rapitasystems.com for assistance with licensing is- + sues. + : Error E09007: Placeholder error for licencelib, do not remove. + + + E09008 + + The license scan failed to contact any license servers. All of the servers may be + unavailable, or their addresses may be specified incorrectly. + + Elimination: License servers may be down for maintenance, or they may have been + moved to new network addresses, or additional proxy details may be required. + Contact your IT support administrator to obtain the correct settings for license + servers. + : Error E09008: License scan failed to contact any license + servers. + + + E09009 + + The --uninstall-file command was unable to delete the license file installed on your + computer. This could be an issue with file system permissions, or because the file + is in use. + + Elimination: Delete the named license file manually. + : Error E09009: The --uninstall-file command was unable to delete + 'file'. Please delete this file manually. + + + E09010 + + The --install-file command was unable to install a new license file at the named + location on your computer. This could be an issue with file system permissions. + As the installation failed, 'licserv' now has no license. + + Elimination: Ensure that 'licserv' has access to the specified location. Note that + 'licserv' may run using a different user account. For example, it may be running in + the background as a service or as a daemon, using a limited user account which + does not have access to certain files on your computer. + : Error E09010: The --install-file command was unable to install + 'file'. Please ensure that the 'licserv' process or service has access + to that location. + + + E09011 + + The provided license file is not valid and cannot be installed. The error message + states the nature of the problem, e.g. the file has expired, the file has a different + host ID, or the file is corrupted. + + Elimination: Contact support@rapitasystems.com for assistance with this issue, + and provide the content of this error message. + : Error E09011: The license file is not valid: msg + + +RVS Troubleshooting Guide vWF20190404 87 +Errors RVS User Messages + + + E09012 + + The provided license file is not accessible from the 'licserv' process or service. + + Elimination: Move the file to a location which is accessible to all users, check the + file permissions (readable by all users) and try again. Note that 'licserv' may run + using a different user account. For example, it may be running in the background + as a service or as a daemon, using a limited user account which does not have + access to certain files on your computer. + : Error E09012: The license file 'file' is inaccessible. + + + E09013 + + After starting up, 'licserv' connects to itself in order to ensure that it is accessible + on the network. This test failed: the license server started, but was not accessible + via the loopback network device. + + Elimination: Check local firewall rules to ensure that the ports used by the license + server are accessible. + : Error E09013: The license server loopback test failed. + + + E09014 + + The --usb-license-key-port command failed due to some error related to the USB + License Key or its drivers. For example, the USB License Key drivers may not be + installed, the USB License Key may not be present, the USB License Key may + have expired or may not be intended for use with 'licserv'. + + Elimination: Contact support@rapitasystems.com for assistance if the error mes- + sage is unclear. + : Error E09014: The --usb-license-key-port command failed with the + following error: msg + + + E09015 + + The command failed because 'licserv' is in the 'stopped' state. 'licserv' must be in + the 'running' or or 'suspended' state in order to use this command. + + Elimination: The server must be started (e.g. 'licserv --start') before this command + may be used. + : Error E09015: The command failed because 'licserv' is in the + 'stopped' state. The server must be started (e.g. 'licserv --start') + before this command may be used. + + + E09016 + + The command failed because 'licserv' is in the 'suspended' state. This command + requires the server to be in the 'running' state. + + +88 RVS Troubleshooting Guide vWF20190404 +RVS User Messages Errors + + + Elimination: Try to force the server to enter the 'running' state with 'licserv --resume'. + : Error E09016: The command failed because 'licserv' is in the + 'suspended' state. The server must be in the 'running' state for this + command. Try 'licserv --resume'. + + + E09017 + + The --file-port command failed due to some error related to the installed license + file. For example, the installed license file may not be valid, or the license file may + not be installed. + + Elimination: Ensure that a license file has been installed using 'licserv --install-file'. + Contact support@rapitasystems.com for assistance if the error message is un- + clear. + : Error E09017: The --file-port command failed with the following + error: msg + + +3.1.10 E10xxx - RVD data + E10001 + + The file is not a valid RVD file. + + Elimination: Regenerate the RVD file using xstutils. + : Error E10001: The file 'file.rvd' is not a valid RVD file. + + + E10002 + + XSC and RTD files generated by RapiTime prior to version 2.4 are not supported + by this version of RVS. + + Elimination: Regenerate the XSC file using the instrumenter. + : Error E10002: RapiTime XSC file version 2.1 detected. This + format is not supported by RVS 3.0. + + + E10003 + + There is a mismatch between the old and the new value used for option --clock- + hz while executing timeparser. + + Elimination: Use the same value for the --clock-hz option as the previous run of + timeparser for that RVD file. + : Error E10003: The value recorded for option --clock-hz (100) in + a previous execution of timeparser is different from the current one + (1000). + + + E10004 + + There is no build Id in the given RVD/trace/map file. + + +RVS Troubleshooting Guide vWF20190404 89 +Errors RVS User Messages + + + Elimination: When using a build Id make sure it is set on both the RVD file and + the trace or map data. + : Error E10004: No build Id was found in the RVD file 'report.rvd' + so it cannot be matched against the trace file 'trace.rpz' with build + Id '1234'. + + + E10005 + + The build Id in the RVD and the trace/map files must match. + + Elimination: When using a build Id make sure it is set to the same value on both + the RVD file and the trace or map data. + : Error E10005: The build Id given to the RVD file + 'report.rvd' (1234) does not match the build Id for the trace file + 'trace.rpz' (134). + + + E10006 + + This tool does not support the specified RVD file. + + Elimination: Regenerate the RVD file with option -r of xstutils. + : Error E10006: This type of RVD file is not suitable for this + tool because it does not have a root function. Use option -r of + xstutils. + + + E10007 + + A duplicate transition from one Ipoint to another has been detected. + + Elimination: Increase the level of instrumentation or do not use option --check- + uniq-transition of xstutils. + : Error E10007: Duplicated transition found from scope 'foo' + Ipoint 12234 to Ipoint 12232. + + + E10008 + + The specified RVD file was not generated with the -u option. This is required in + order to use the --map option of the covparser. + + Elimination: Use option -u when instrumenting to make sure all Ipoint Ids are + unique. + : Error E10008: This RVD file cannot be used with the --map + option as it contains non-unique ipoint IDs. This may happen if the -- + coverage-map option was not used during the instrumentation stage, or if + the report contains source files from different instrumentation runs. + Same ipoint Id 12334 was found at locations foo.c:233 ('func1') and + foo.c:123 ('func2'). + + + E10009 + + This RVD file was generated without using -u option. + + +90 RVS Troubleshooting Guide vWF20190404 +RVS User Messages Errors + + + Elimination: Use option -u when instrumenting to make sure all Ipoint Ids are + unique in order to use covparser --map. + : Error E10009: This RVD file cannot be used with option --map of + covparser. + Covparser --map requires that option -u is used when instrumenting. + + + E10010 + + One or more function call(s) cannot be black boxed. Refer to the reference guide + for further details on black-boxing function calls. + + Elimination: Modify the source code at the indicated location(s) to allow Ipoints to + be placed before and after the call(s). + : Error E10010: 1 function call(s) cannot be black boxed:x.c:1:2: + Call to 'func'. + + + E10011 + + Error reading XST from database. + + Elimination: Regenerate the RVD file. + : Error E10011: Error reading XST from database. + + + E10012 + + Unable to upgrade database - it was created with a newer version of RVS. + + Elimination: Regenerate the RVD file. + : Error E10012: Unable to upgrade database - it was created with a + newer version of RVS. + + + E10013 + + Unable to upgrade database - it was created with a version of RVS that is too old. + + Elimination: Regenerate the RVD file. + : Error E10013: Unable to upgrade database - it was created with a + version of RVS that is too old. + + + E10014 + + Failed to upgrade database. + + Elimination: Regenerate the RVD file. + : Error E10014: Failed to upgrade database. + + + E10015 + + The Ipoint Ids in this RVD file are not unique. Please make sure you used option + -u when instrumenting your source code. + + +RVS Troubleshooting Guide vWF20190404 91 +Errors RVS User Messages + + + Elimination: Use option -u when instrumenting to make sure all Ipoint Ids are + unique. + : Error E10015: The Ipoint Ids in the RVD file(s) are not unique. + Please reinstrument with -u option. Ipoint 23 was found in both 'x' and + 'y'. + + + E10016 + + The data in the map for the MCDC decision at the specified Ipoint has been cor- + rupted. + + Elimination: Check the map capture mechanism and filters used to post-process + the map data. + : Error E10016: The data in the map for the MCDC decision at + Ipoint 23 is corrupt (invalid decision outcome). Bit 8 is set but does + not represent a valid vector. + + + E10017 + + The data in the map for the MCDC decision at the specified Ipoint is incomplete. + + Elimination: Check the map capture mechanism and filters used to post-process + the map data. + : Error E10017: The data in the map for the MCDC decision at + Ipoint 23 is incomplete. Expecting 4 bytes, but received 3 bytes. + + + E10018 + + The IdPack option does not allow a root function to be called within another root + function. + + Elimination: When using several root functions, select roots so that no root function + is part of the call-tree of another root function. + : Error E10018: Root function 'function1' is called within another + root function 'function2'. This is not allowed with the IdPack option. + + + E10019 + + A transition between two Ipoints with the same Id has been found. + + Elimination: Use the --no-ident-transition option during instrumentation. + : Error E10019: A transition between two Ipoints with the same Id + has been found + message + + + E10020 + + Non deterministic transitions detected inside a single function. In the specified + function, an Ipoint Id was found more than once. This error should only happen + with manually instrumented code. + + +92 RVS Troubleshooting Guide vWF20190404 +RVS User Messages Errors + + + Elimination: Modify the manual instrumentation of the function so that Ipoint Ids are + unique within the function. If an unroll_loops annotations is used with the FUNC- + TIONS instrumentation profile, the profile modifier '+u' should be added (profile is + then FUNCTIONS+u) to avoid the issue caused by unrolling loops. + : Error E10020: Non deterministic automata transitions detected + inside a single function. In function 'func', the Ipoint Id 23 was + found more than once. + + + E10021 + + Non deterministic transition(s) detected. + + Elimination: If the RVD file being generated is to be used by timeparser, then the + instrumentation profile(s) of the function listed must be increased as requested. If + an unroll_loops annotations is used with the FUNCTIONS instrumentation profile, + the profile modifier '+u' should be added (profile is then FUNCTIONS+u) to avoid + the issue caused by unrolling loops. + : Error E10021: Non deterministic transition(s) detected. + Not enough instrumentation points to construct a parser. + Summary: + The following functions must be instrumented:... + The following functions must be instrumented with a more detailed + instrumentation profile:.... + + + E10022 + + Non deterministic transition(s) detected. + + Elimination: If the RVD file being generated is to be used by timeparser, then the + instrumentation profile(s) of the function listed must be increased as requested. If + an unroll_loops annotations is used with the FUNCTIONS instrumentation profile, + the profile modifier '+u' should be added (profile is then FUNCTIONS+u) to avoid + the issue caused by unrolling loops. If the RVD file being generated is to be used + by covparser this error can be ignored by using option --no-parse-check of xstutils. + : Error E10022: Non deterministic transition(s) detected. + Not enough instrumentation points to construct a parser. + + + E10023 + + This RVD was not generated to parse a trace file. + + Elimination: Use option -r and do not use option --no-parse-check of xstutils. + : Error E10023: RVD cannot be used for parsing a trace. + + + E10024 + + Root function specified is not in the call tree of the analysis scope function. + + Elimination: Select a root function that is part of the call tree of the analysis scope + function. + + +RVS Troubleshooting Guide vWF20190404 93 +Errors RVS User Messages + + : Error E10024: Root function 'root' is not in the call tree of + the analysis scope function 'main'. + + + E10025 + + Wrong exit Ipoint for the analysis scope function of the analysis. + + Elimination: Make sure that the last Ipoint of the analysis scope function cannot be + immediately followed in the trace by an Ipoint located in the calltree of the analysis + scope function (excepted the analysis scope entry Ipoint(s)). + : Error E10025: Wrong exit Ipoint for the analysis scope function + of the analysis (func): + Ipoint source (file.c source) is followed by other Ipoints. + + + E10026 + + The same function has been found in two input XSC files and the number of Ipoints + added to this function is different between the two files specified. It should be + identical. + + Elimination: Make sure the duplicated function is intended. Make sure the function + name actually represents the same source code. Make sure the function is always + instrumented with the same profile. + : Error E10026: The number of Ipoints in function + 'function1' (xref) is different between file 'file1' and file + 'file2' (it should be identical). + + + E10027 + + The same function has been found in two input XSC files and its structure is dif- + ferent between the two files specified . It should be identical. + + Elimination: Make sure the duplicated function is intended. Make sure the function + name actually represents the same source code. + : Error E10027: The function 'function1' (file1.c:42) is different + between file 'file1.c' and file 'file2.c' (it should be identical). + + + E10028 + + The same function has been found in two input XSC files and its Ipoint Ids are + different between two specified files. They must be identical. + + Elimination: Make sure the duplicated function is intended. Make sure the function + name actually represents the same source code. Make sure the function is always + instrumented with the same profile. Make sure the EXF file is not being deleted + between instrumentation of these two source files. + : Error E10028: The Ipoint Ids for function + 'function1' (file1.c:42) are different between file 'file1.c' and file + 'file2.c' (they should be identical). + + +94 RVS Troubleshooting Guide vWF20190404 +RVS User Messages Errors + + + E10029 + + The same function has been found in two input XSC files. + + Elimination: Make sure the duplicated function is intended. Use option --allow-du- + pl-func of xstutils. + : Error E10029: The function 'function1' has been found more than + once. + In 'file1.c' (file1.c:42) and + in 'file2.c' (file2.c:36). + + + E10030 + + The instrumentation of the source file caused parser generation to fail. + + Elimination: Use option --no-root to skip the parser generation or improve the in- + strumentation by using a more detailed instrumentation profile. + : Error E10030: Parsing engine not created. + + + E10031 + + The function specified has been removed from the analysis. + + Elimination: Do not use xstutils option --keep for this function. + : Error E10031: The function 'foo' has been removed from the + analysis. + + + E10032 + + The given function could not be found. + + Elimination: Use the correct function name. + : Error E10032: The function 'function1' could not be found. Did + you mean 'function2'? + + + E10033 + + The given function could not be found. + + Elimination: Use the correct function name. + : Error E10033: The function 'foo' could not be found. + + + E10034 + + This type of file is not suitable for WCET computation. + + Elimination: Use option -r of xstutils. + : Error E10034: This type of RVD file is not suitable for WCET + computation. Use option -r of xstutils. + + +RVS Troubleshooting Guide vWF20190404 95 +Errors RVS User Messages + + + E10035 + + Could not find a suitable first Ipoint for some of the root functions. + + Elimination: Make sure all root functions are instrumented. + : Error E10035: Could not find a suitable first Ipoint for some of + the root functions 'foo'. + + + E10036 + + The entry Ipoint for the analysis scope function is not unique. + + Elimination: Make sure the root function is instrumented and that its entry Ipoint + has a unique Id. + : file.ext: Error E10036: The entry Ipoint Id 1023 of the analysis + scope function is not unique. + + + E10037 + + The only allowed transitions from an exit Ipoint are to entry Ipoints. Could not find + a suitable exit Ipoint for the analysis scope function. + + Elimination: Make sure the analysis scope function is instrumented such as to + have an Ipoint at the beginning, as well as on function exit. + : Error E10037: Could not find a suitable exit Ipoint for the + analysis scope function (foo). + + + E10038 + + Ipoint specified is not a suitable exit Ipoint for the analysis scope function. It can + also be found in the calltree of the analysis scope function. + + Elimination: Make sure that the last Ipoint of the analysis scope function cannot be + immediately followed in the trace by an Ipoint located in the calltree of the analysis + scope function (excepted the analysis scope entry Ipoint(s)). + : file.ext: Error E10038: Ipoint 453345 is not a suitable exit + Ipoint for the analysis scope function. It can also be found in the + calltree of the analysis scope function. + + + E10039 + + Ipoint specified cannot be both entry and exit Ipoint for the analysis scope function. + + Elimination: Make sure the entry and exit Ipoints of the analysis scope function are + different. This may require modifying the source code to add more Ipoints. + : Error E10039: Ipoint 453343 cannot be both an entry and exit + Ipoint for the analysis scope function of the analysis 'function': + Ipoint 453342 (x) + + +96 RVS Troubleshooting Guide vWF20190404 +RVS User Messages Errors + + + E10040 + + The Id for an entry Ipoint is not unique. It is found in two different locations. + + Elimination: Make sure the EXF file is not being deleted during instrumentation. + : Error E10040: The entry Ipoint 453343 is not unique. It was + found in report.rvd and file1.rvd. + + + E10041 + + An abnormally large number of iterations (greater than 2^47) has been detected + for a loop. ETP Computation is unable to cope with loops of this magnitude. + + Elimination: Check that the loop iteration count is correct. Do not instrument this + loop. + : file.ext: Error E10041: An abnormally large number of iterations + has been detected for a loop in function 'foo'. ETP Computation can not + be performed. + + + E10042 + + There is a mismatch between the build ID supplied on the command line and the + one found in an XSC file. + + Elimination: Use the same value for the build ID in the annotations and the xstutils + command line. + : Error E10042: The build ID recorded in the XSC at + 'file.c:150' (muID1) does not match the build ID specified for option + --build-id (muID2). + + + E10043 + + There is a mismatch between the build IDs found in XSC files. + + Elimination: Use the same value for all the build IDs in the annotations. + : Error E10043: The build ID recorded in the XSC at + 'file1.c:150' (muID1) does not match the build ID specified in another + XSC file at 'file2.c:100' (muID2). + + + E10044 + + When processing a coverage map, the Ipoint Ids must uniquely identify a piece of + code. This is not the case with this RVD file. + + Elimination: Do not use annotation 'recursive' (see known issue KI3058). + : file.ext: Error E10044: The Ipoint Id 42 is not unique. + + + E10045 + + This RVD file was generated without using -u option. + + +RVS Troubleshooting Guide vWF20190404 97 +Errors RVS User Messages + + + Elimination: Use option -u when instrumenting to make sure all Ipoint Ids are + unique in order to use rvdutils --create-map. + : Error E10045: This RVD file cannot be used with option --create- + map of rvdutils. + rvdutils --create-map requires that option -u is used when + instrumenting. + + + E10046 + + This RVD file was not processed by covparser. It does not contain any coverage + information. + + Elimination: Use covparser to add coverage information to the RVD file. + : Error E10046: 'file.rvd' was not processed by covparser. + + + E10047 + + The input RVD file does not contain any build IDs, but a build ID is specified in + the justification file. + + Elimination: The instrumented program should write the build ID to the execution + trace or coverage map, e.g. using the RVS_Build_ID function. + : file.ext: Error E10047: The input RVD file does not have a build + ID to match the build ID 'b123' from the justification file. + + + E10048 + + The input RVD file and justification file contain build IDs, but the build IDs do not + match. + + Elimination: Ensure that the correct RVD file and justification file are in use. Re- + generate the trace and RVD file if necessary. + : file.ext: Error E10048: The input RVD file build ID ('b123') + does not match the build ID from the justification file ('b124'). + + + E10049 + + A coverage justification, given in the justification file, matched too many covered + elements. + + Elimination: Amend the incorrect coverage justification. + : file.ext: Error E10049: Several (9) MCDC items could be found to + associate to justification '[Additional information]'. + + + E10050 + + A coverage justification, given in the justification file, did not match the expected + number of covered elements. + + Elimination: Amend the incorrect coverage justification. + + +98 RVS Troubleshooting Guide vWF20190404 +RVS User Messages Errors + + : file.ext: Error E10050: Not enough (3) MCDC item(s) could be + found to associate to justification 'justification'. Expecting at least + 4. + + + E10051 + + An unexpected number of covered elements was found on one line in the source + code. The justification data states that a particular number of elements are expect- + ed on this line, but the actual number differs from this. + + Elimination: Amend the incorrect coverage justification. + : file.ext: Error E10051: 3 MCDC item(s) could be found on this + line. Expecting 4. + + + E10052 + + The RVD file must be processed by timeparser before WCET computation can be + done. + + Elimination: Process an execution trace with timeparser first. + : Error E10052: 'timeparser' must be run before running wcalc. + + + E10053 + + The last attempt at processing an execution trace with timeparser failed. + + Elimination: Fix the issue with timeparser before attempting WCET computation. + : Error E10053: Previous run of 'timeparser' failed. Cannot run + wcalc. + + + E10054 + + There are no subprograms which match the wildcard expression. + + Elimination: Run xstutils with a valid argument to the -r option (or -use --no-root). + : Error E10054: No root functions matching root_name_* were found. + + + E10055 + + These subprograms have been modified in the tests, and therefore cannot be + merged into the master report. + + Elimination: Specify --merge-or-replace or --replace-only to allow subprogram re- + placement. + : Error E10055: The following subprograms need replacing rather + than merging: - subprogram_f + + + E10056 + + These subprograms does not match between tests, and therefore cannot be + merged or replace into the master report. + + +RVS Troubleshooting Guide vWF20190404 99 +Errors RVS User Messages + + + Elimination: Ensure that the code and instrumentation for this subprogram has not + been modified in only some of the tests. + : Error E10056: The following subprograms differ between tests:f + (test_1.rvd, test_2.rvd) + + + E10057 + + The same file has been used to generate two different reports, but the content of + the file has changed. + + Elimination: + : Error E10057: The source file 'file.c' has been changed between + reports 'report1.rvd' and 'report2.rvd'. + + + E10058 + + When merging coverage data from two RVD files, the source code has changed + between generation of the RVD files. The locations of certain elements of the + source code no longer match. + + Elimination: When merging coverage report from one RVD into another, make sure + both RVDs were built from the same source code (same contents and same file + location). + : Error E10058: Cannot merge: source code location appears to have + changed from 'init.adb:3-11' to 'init.adb:9-19'. + + + E10059 + + The coverage data could not be merged in to this report, as the report is a multicore + report but no core information was provided for the additional coverage data. + + Elimination: Add the '--core' option to the command line to specify which core the + coverage data is from. + : Error E10059: Core information must be provided using the + '--core' option when merging data in to a multicore report. Report + 'report.rvd' is a multicore report as the '--core' option was + previously specified when adding coverage data. + + + E10060 + + The coverage data could not be merged in to this report as the report is not mul- + ticore report. No core information was provided when data was first added to this + report. + + Elimination: Add the '--core' option to the command line when first adding cover- + age data to the report. + : Error E10060: Report 'report.rvd' is not a multicore report. + The '--core' option was not used when first adding coverage data to + + +100 RVS Troubleshooting Guide vWF20190404 +RVS User Messages Errors + + this report. Therefore the '--core' option cannot be used when merging + coverage data in to this report + + + E10061 + + The input rvd was a multicore report. The --remove-test option can not be used + on a multicore report. + + Elimination: To remove core data from a report, use the --remove-core-test option. + : Error E10061: The '--remove-test option can not be used on a + multicore report. File 'report.rvd' is a multicore report. + + + E10062 + + The input rvd was not a multicore report. The --remove-core-data option can only + be used on a multicore report. + + Elimination: To remove test data from a report, use the --remove-test option. + : Error E10062: The '--remove-core-data' option can only be used + on a multicore report. File 'report.rvd' is not a multicore report. + + + E10063 + + The input rvd was a multicore report. The --replace-test option can not be used + on a multicore report. + + Elimination: To replace core data in a report, use the --remove-core-data option. + : Error E10063: The '--replace-test' option can not be used on a + multicore report. + + + E10064 + + The input rvd was not a multicore report. The --replace-core-data option can only + be used on a multicore report. + + Elimination: To replace test data in a report, use the --replace-test option. + : Error E10064: The '--replace-core-data' option can only be used + on a multicore report. + + + E10065 + + A configuration mismatch was detected by xstutils. The input XSC files were gen- + erated with coverage map options, but an analysis scope function has been spec- + ified for xstutils (using -r or --analysis-scope). The analysis scope function does + not contain enough unique Ipoints to build a trace parser, as a result of coverage + map optimizations applied during instrumentation. + + Elimination: Use the --no-root option for xstutils, or add more instrumentation + points. + + +RVS Troubleshooting Guide vWF20190404 101 +Errors RVS User Messages + + : Error E10065: Function foo has has as a result of coverage map + optimizations, so it cannot be used as an analysis scope function. + Coverage map projects should use the --no-root option of xstutils. + + + E10066 + + The file name specified for this justification does not uniquely identify a file (the file + path name is not detailed enough) for placing a justification. + + Elimination: Amend the coverage justification location by extending the path for + the file name. + : file.ext: Error E10066: A matching COV_MCDC item could be found + in files: + a/file.c + b/file.c + + + E10067 + + There is no build Id in the given RVD file. + + Elimination: Set the build Id when creating the RVD file. + : Error E10067: No build Id was found in the RVD file 'report.rvd' + so it cannot be used with justifications in 'justpath'. + + + E10068 + + The data in the livemap for the MCDC decision of the specified Ipoint has been + corrupted. + + Elimination: Check the livemap capture mechanism and filters used to post- + process the livemap data. + : Error E10068: The data in the map for the MCDC decision at + Ipoint 23 (trace element 230) is corrupt (invalid decision outcome). + Value 8 does not represent a valid vector. + + + E10069 + + The instrumenters used in the generation of this RVD were too old. + + Elimination: Regenerate the XSC files using the instrumenter and regenerate the + RVD file using xstutils. + : Error E10069: The RVD 'report.rvd' was generated using an old + version of the instrumenter. Please reinstrument and regenerate the RVD + file. + + + E10070 + + This RVD file was not processed by timeparser. It does not contain any timing + information. + + Elimination: Use timeparser to add timing information to the RVD file. + + +102 RVS Troubleshooting Guide vWF20190404 +RVS User Messages Errors + + : Error E10070: 'file.rvd' was not processed by timeparser. + + + E10071 + + This RVD file cannot be further processed by one of the tool. + + Elimination: The reason for the incompatibility must be fixed in the integration. + : Error E10071: The RVD file 'file.rvd' cannot be processed by + covparser because it was generated with option --no-coverage. + + + E10072 + + In order to merge two coverage RVD files they must have the same justification + inheritance settings. + + Elimination: The reason for the incompatibility must be fixed in the integration. + : Error E10072: The source RVD file 'file1.rvd' and the target RVD + file 'file2.rvd' cannot be merged because they have different settings + for justification inheritance. + + + E10073 + + In order to merge two coverage RVD files they must have the same justification + store. + + Elimination: The reason for the incompatibility must be fixed in the integration. + : Error E10073: The source RVD file 'file1.rvd' and the target + RVD file 'file2.rvd' cannot be merged because they have different + justification stores ('jstore1' and 'jstore2'). + + + E10074 + + In order to merge two coverage RVD files with justifications their justification store + must be available. + + Elimination: The justification store must be restored to proceed with merging. + : Error E10074: The source RVD file 'file1.rvd' and the target RVD + file 'file2.rvd' cannot be merged because their justification store + 'jstore' cannot be found. + + + E10076 + + When justification inheritance is disabled by annotation it is an error to try to enable + it via the command line. + + Elimination: If justification inheritance is required, the annotation that disables it + must be removed. + : Error E10076: Justification inheritance has been disabled + by annotation for 'file1.rvd'. It cannot be enabled using option -- + inherit-justifications. + + +RVS Troubleshooting Guide vWF20190404 103 +Errors RVS User Messages + + + E10077 + + The expanded status of calls must match across reports. + + Elimination: Use 'pragma expand_calls' consistently. + : Error E10077: The subprogram 'f' was expanded in 1.rvd, but not + in 2.rvd. + + + E10078 + + There is a mismatch between reports which prevents merging. + + Elimination: Re-generate the specified reports to address the mismatch. + : Error E10078: Name mismatch between 1.rvd and 2.rvd + + + E10079 + + The RVD report was created with one --mode setting, and then covparser was + invoked with a different --mode setting. + + Elimination: Identical --mode options should be given to the instrumenter and to + covparser. + : Error E10079: The --mode option setting (aero) does not match + the mode set within the RVD file (auto). + + + E10080 + + The project contains a mixture of Aero and Auto instrumentation profiles. Some + instrumentation profiles imply an aerospace project (e.g. COV_DECISIONS, + COV_178_DAL_C) while other profiles imply an automotive project (e.g. + COV_BRANCHES). As there is a mixture, the RVS tools are unable to determine + whether coverage reports should be optimized for aerospace or automotive use. + + Elimination: The instrumenter command line should include an explicit '--mode' + setting to specify whether the project is an aerospace project ('--mode aero'), an + automotive project ('--mode auto'), or neither ('--mode core'). This setting must be + the same for every instrumented source file. + : Error E10080: The project contains a mixture of Aero and Auto + instrumentation profiles. + + + E10082 + + The specified cost file did not contain any cost values that could be recognized. + + Elimination: The cost file should be in CSV (comma separated variable) format, + with a header as 'id,duration,cost'. The first column should contain test name. Du- + rations must be in time format (e.g. 12:04:59) and costs must be in integer format + (with no decimal point or digit grouping character). + + +104 RVS Troubleshooting Guide vWF20190404 +RVS User Messages Errors + + : Error E10082: No valid cost values were found in file + 'file.csv'. + + + E10083 + + A cost file was specified but did not contain a valid cost value for one or more tests. + + Elimination: Check the cost file contains an exact match for all test names, and + that the cost value is in the correct format. Cost values may be in any column but + must be in integer format (with no decimal point or digit grouping character) or + time format, e.g. 123 or 12:04:59 + : Error E10083: No cost value found for test 'testname'. + + + E10084 + + The RVD file passed to "xstutils --update" has already been processed by "xstutils". + This is not currently supported. An RVD file can only be processed once by xstutils. + + Elimination: Use "xstutils --replace" instead, or make a backup of the RVD file be- + fore passing it to xstutils. + : Error E10084: Xstutils has already processed 'filename.rvd'. An + RVD file can only be processed once by xstutils. + + + E10085 + + The data in the map for the specified Ipoint has been corrupted. The value does + not match earlier ipoint values. Every non-zero ipoint must have the same value + in the map. + + Elimination: Check the map capture mechanism and filters used to post-process + the map data. + : Error E10085: The data in the map for ipoint 23 is corrupt. + Earlier non-zero ipoints had value 1 in the map, but this ipoint has + value 2. + + + E10086 + + No data of the expected type could be found in the RVD. + + Elimination: Check that the operation on the RVD is correct. Check how and what + type of data is added to the RVD. + : Error E10086: The RVD 'file.rvd' does not contain any coverage + data. + + + E10087 + + The RVD is not suitable for use with --import-rvd because it was not created using + --preparation. + + Elimination: Use option --preparation of xstutils to create RVD files that are suitable + for importing with --import-rvd. + + +RVS Troubleshooting Guide vWF20190404 105 +Errors RVS User Messages + + : Error E10087: The RVD 'file.rvd' is not suitable for use with -- + import-rvd because it was not created using --preparation. Use option + --preparation of xstutils to create RVD files that are suitable for + importing with --import-rvd. + + + E10088 + + The analysis scope or root must contain Ipoints. + + Elimination: Check that instrumentation is switched on for the analysis scope or + root. Failing that, insert start_root/end_root annotations or Ipoint annotations to + delimit the start and end of the analysis scope or root. + : Error E10088: There are no Ipoints in the analysis scope + or root 'foo'. If the analysis scope or root is a loop, add manual + instrumentation point annotations to mark every entry and every exit of + the loop body. + + + E10089 + + The analysis scope or root must contain entry Ipoints. + + Elimination: Place Ipoints so that they appear before code under analysis starts + executing. + : Error E10089: No suitable entry Ipoints found in the analysis + scope or root 'foo'. + + + E10090 + + The analysis scope or root must contain exit Ipoints. + + Elimination: Place Ipoints so that they appear after code under analysis finishes + executing. + : Error E10090: No suitable exit Ipoints found in the analysis + scope or root 'foo'. + + + E10091 + + Calls are not delimited by entry Ipoints in the analysis scope or root. + + Elimination: Put Ipoints before every call in the analysis scope or the root. + : Error E10091: Execution of the analysis scope or a root must + include a set of Ipoints that appear before any call is made, even if + the callee (or any of its callees) is not instrumented. There is a path + from the start of 'foo' to a call (x) that includes no Ipoint. + + + E10092 + + Calls are not delimited by exit Ipoints in the analysis scope or root. + + Elimination: Put Ipoints after every call in the analysis scope or the root. + : Error E10092: Execution of the analysis scope or a root must + include a set of Ipoints that appear after any call is made, even if + + +106 RVS Troubleshooting Guide vWF20190404 +RVS User Messages Errors + + the callee (or any of its callees) is not instrumented. There is a path + from a call (x) to the end of 'foo' that includes no Ipoint. + + + E10093 + + An Ipoint is both an entry and exit Ipoint for the analysis scope or a root. + + Elimination: Make sure the entry and exit Ipoints of the analysis scope or root are + different. + : Error E10093: Ipoint 453343 (x) is both an entry and exit + Ipoint. + + + E10094 + + An Ipoint marked as an entry does not have a unique ID. + + Elimination: Reassign Ipoint IDs so that entry Ipoints do not share IDs with other + Ipoints. + : Error E10094: Entry Ipoint 453343 (x) shares its ID with other + Ipoints. + + + E10095 + + An Ipoint marked as an exit does not have a unique ID. + + Elimination: Reassign Ipoint IDs so that exit Ipoints do not share IDs with other + Ipoints. + : Error E10095: Exit Ipoint 453343 (x) shares its ID with other + Ipoints. + + + E10096 + + When using bit packing for coverage map option --map-bit-pack must be used + for all instrumented files. + + Elimination: Make sure option --map-bit-pack is either always or never used in your + integration. + : Error E10096: Coverage map bit packing was enabled on some but + not all XSC files. + + + E10097 + + The structural database was built using an older version of the tools. + + Elimination: If running rvsdriver, run the --clean and then --prepare stages. If run- + ning an instrumenter, use the --replace option instead of --update. + : Error E10097: The structural database's version does not match + the tool's version. If running rvsdriver, run the --clean and then -- + prepare stages. If running an instrumenter, use the --replace option + instead of --update. + + +RVS Troubleshooting Guide vWF20190404 107 +Errors RVS User Messages + + +3.1.11 E11xxx - Trace/Map files + E11001 + + An unexpected end of trace has been detected while parsing the trace file. + + Elimination: Use option --allow-incomplete or filter the trace using the filter gener- + ated by option --scope-filter of xstutils before parsing it. + : Error E11001: Unexpected end of trace detected while parsing the + trace file 'trace.rpz'. + Last Ipoint was: 23423 at 1231231 + + + E11002 + + There is no Ipoint in the trace file that corresponds to the root function in the spec- + ified RVD file. + + Elimination: Make sure the trace corresponds to a run of the root function (entry + and exit Ipoint Ids for the root function can be found by viewing the RVD in the GUI). + : Error E11002: No Ipoint corresponding to the root function + 'func_root' in the RVD file 'report.rvd' could be found in the trace + file 'trace.rpz'. + + + E11003 + + A function pointer was found while parsing the input file. + + Elimination: Rebuild the RVD file with more 'call_to' annotations to solve function + pointers. + : Error E11003: A function pointer has been detected in the trace. + Please use an appropriate annotation to resolve the function pointer. + + + E11004 + + A negative elapsed time between two Ipoint has been found. + + Elimination: If the negative time difference between the two Ipoints is due to a + counter wraparound, use the --wrap option of traceutils to filter the trace before + processing. + : Error E11004: Found a negative value for the elapsed time + between two Ipoints. + + + E11005 + + Timing of the trace appears to be going backwards at a given line. + + Elimination: If the negative time difference between the two Ipoints is due to a + counter wraparound, use the --wrap option of traceutils to filter the trace before + processing. + : Error E11005: Time is going backward at line 1223423 + + +108 RVS Troubleshooting Guide vWF20190404 +RVS User Messages Errors + + + E11006 + + There was an error encountered while executing parameter elements within a func- + tion call. One or more parameter elements were found to be executed more than + once. + + Elimination: Check the instrumented source code and the trace to understand how + the sequence of Ipoints reported was executed. + : file.ext: Error E11006: One of the elements of this list of + parameters has been executed more than once. + Trace element: + Trace line '123' + Ipoint Id '12234' + Timestamp '122321223' + Although the order in which the elements of a list of parameters of a + function call is not specified, each element must be executed exactly + once. + + + E11007 + + Time has been found to be going backward in the trace. + + Elimination: Check that traceutils is used correctly to import the trace data. By writ- + ing a .dt2 file with traceutils, you can obtain a human-readable text representation + of the trace data which shows elapsed time between successive Ipoints, or time + delta in (brackets). Wherever a "negative" value is present, the time delta will be a + very large number as it is represented modulo 2^64. By locating such values, you + can find clues to the cause of the trace data processing problem. If the negative + time difference between the two Ipoints is due to a counter wraparound, use the + --wrap option of traceutils to filter the trace before processing. + : Error E11007: Time is going backward in the trace at trace + element 123. + + + E11008 + + Time has been detected to be going backward in the trace file. + + Elimination: If the negative time difference between the two Ipoints is due to a + counter wraparound, use the --wrap option of traceutils to filter the trace before + processing. + : Error E11008: Time is going backward in the trace file + 'trace.rpz'. + at record number '101' at time '6654433' time 50 was encountered. + Previous Ipoint: 157 + + + E11009 + + The timeparser tool read a trace data file containing a sequence of Ipoints that is + not a valid trace of the software modeled in the .rvd file. This may occur because + there is a call through a function pointer and the .rvd file was built without the addi- + + +RVS Troubleshooting Guide vWF20190404 109 +Errors RVS User Messages + + + tional information required to know which functions are reached through the func- + tion pointer call. This error may also occur because the trace data corresponds to + one instrumentation of the source code but the .rvd file was built from a different + instrumentation of the source code. Another possible reason for an unexpected + Ipoint is that an interrupt has occurred. For guidance on the correct instrumenta- + tion and treatment of interrupts, see the Integration Guide. An unexpected Ipoint + can also be an indication of a corrupt trace. + + Elimination: Check that the report and the software build are up to date. Check + the instrumented source code and the trace to understand how the sequence of + Ipoints reported was executed. For function pointers, you may need to use the -- + discover-fptr option. + : Error E11009: Trace error detected. + In trace file 'trace.rpz'. + At trace record number 101. + At time 52322. + Unexpected Ipoint 122 was encountered. + Previous Ipoint: 254 + Expected Ipoint(s): + 12232, 12231, 10 + + + E11010 + + A line from the TLA trace file could not be parsed. + + Elimination: Make sure the trace file only contains lines in TLA format. + : Error E11010: Line '23' could not be parsed by the TLA trace + parser. + + + E11011 + + Error while reading a text trace (wrong format). + + Elimination: Make sure the text trace file contains data in the expected format. + : Error E11011: Error while reading a text trace (wrong format at + line 23). x + + + E11012 + + The trace write is not implemented. + + Elimination: Change the extension of the output trace to a different type. + : Error E11012: TLA trace write is not implemented. + + + E11013 + + Invalid line_reader string. + + Elimination: Use a valid format when configuring the line_reader in the filter file. + : Error E11013: Invalid line_reader string. + + +110 RVS Troubleshooting Guide vWF20190404 +RVS User Messages Errors + + + E11014 + + Error while reading a dt2 trace (wrong format). + + Elimination: Make sure the .dt2 trace file contains data in the expected format. + : Error E11014: Error while reading a dt2 trace (wrong format). + + + E11015 + + An error occurred when reading or writing an RPZ trace file. The RPZ trace file may + be corrupt. + + Elimination: Ensure that the RPZ file is in an accessible location. Regenerate the + RPZ file if necessary. + : Error E11015: RPZ trace file error: unable to open trace file. + + + E11016 + + File is not an RPZ file. + + Elimination: Regenerate the RPZ file. + : Error E11016: File 'trace.rpz' is not an RPZ file. + + + E11018 + + Error while reading a dt1 trace (wrong format). + + Elimination: Make sure the .dt1 trace file contains data in the expected format. + : Error E11018: Error while reading a dt1 trace (wrong format). + + + E11020 + + Error while reading a t32 trace (wrong format). + + Elimination: Make sure the t32 trace file contains data in the expected format. + : Error E11020: Error while reading a t32 trace (wrong format). + + + E11022 + + The text trace file contains an overly long line. + + Elimination: If the line is a comment remove the line before processing. + : file.ext: Error E11022: This line of the text trace file is too + long (more than 1024 characters). + + + E11023 + + The recorded decision value and taken branch do not match. + + +RVS Troubleshooting Guide vWF20190404 111 +Errors RVS User Messages + + + Elimination: Check the instrumented source code and the trace to understand how + the sequence of Ipoints reported was executed. + : file.ext: Error E11023: MCDC: For decision 'x' the branch taken + (True) after the decision does not match the decision value (False). + + + E11025 + + The demux filter encountered an unexpected special Ipoint while processing the + trace. Special Ipoints convey information about program execution, and they have + very specific meaning. For example, an 'activate' Ipoint should be followed by the + process ID (PID) of the new task. If the subsequent Ipoint cannot be interpreted, + error E11025 is generated. + + Elimination: Examine the trace to ensure that the sequence of Ipoints around the + given timestamp is valid. The trace may have been generated incorrectly, or the + demux filter configuration may be incorrect. + : Error E11025: Unexpected Ipoint 6 found at time 1200. + [Additional information] + + + E11026 + + The demux filter could not adjust the context switch time of a task, because this + would cause an Ipoint timestamp to be less than its predecessor. This has hap- + pened because the numbers given to the 'adjust_cx' option do not match the real + context switch overhead of the system. + + Elimination: Determine the real context switch overhead and change the parame- + ters of 'adjust_cx' accordingly. + : Error E11026: Unable to adjust the context switch time for task + 'task1' at time 1200. [Additional information] + + + E11027 + + An invalid event was found within one of the task traces given to taskparser. The + event is invalid because it occurred at a time when the task (or one of its func- + tions) was not executing. The input trace is corrupt and cannot be displayed by + the RapiTask viewer. + + Elimination: If using multiple CPUs, check that the task to CPU assignment given + to taskparser matches the task to CPU assignments in your system. Otherwise, + the traces may have become corrupted in an earlier processing stage. + : Error E11027: An invalid 'suspend' event was found at time 1200 + within the trace for task 'task1'. This is invalid because the task is + not running. + + + E11028 + + The provided trace contains an unresolved function pointer, and --merge-results + was specified on the command line. --merge-results can only be used when every + function pointer has already been resolved. + + +112 RVS Troubleshooting Guide vWF20190404 +RVS User Messages Errors + + + Elimination: The possible destinations of every indirect call using a function pointer + must be resolved before --merge-results is used. This may be achieved by adding + "#pragma RVS call_to" annotations to the program. The annotations can be dis- + covered automatically by timeparser or covparser. See the Reference Guide for + further information. + : Error E11028: Unresolved function pointers are present and + cannot be automatically resolved during --merge-results operation. + + + E11029 + + The provided file was not a filtered map. + + Elimination: Check that the correct file is being inputted. Apply a filter to map data + before passing it as an input. + : Error E11029: The file 'rvs_output_map.txt' is not a valid + filtered map. + + + E11030 + + Ipoint number does not identify a unique subprogram. It cannot be used to dis- + cover the target of a call through a function pointer. + + Elimination: Resolve indirect calls manually using call_to annotations. + : file.ext: Error E11030: Ipoint number 23 does not identify a + unique subprogram. It cannot be used to discover the target of a call + through a function pointer. + + + E11031 + + The trace file has already been parsed by timeparser for the rvd. + + Elimination: Ensure that timeparser has not parsed that trace already for the rvd. + : Error E11031: The trace 'trace.rpz' has already been parsed by + timeparser for the rvd 'report.rvd'. The parse result may not be added + twice for the rvd. + + + E11032 + + There were no RVD files found that had a matching trace. + + Elimination: Ensure that at least one of the traces generated correspond to an + inputted RVD. + : Error E11032: None of the traces matched against any of the RVD + files. + + + E11033 + + The tool was unable to close the Open Trace Format file. + + +RVS Troubleshooting Guide vWF20190404 113 +Errors RVS User Messages + + + Elimination: Ensure that the file is accessible and not in use by other processes. + : Error E11033: Could not close OTF file. + + + E11034 + + No suitable Ipoint was found for the artificial root specified by a pair of + start_task_code and end_task_code annotations. + + Elimination: Ensure that the subprogram containing the specified 'start_task_code' + and 'end_task_code' annotations is instrumented. + : file.ext: Error E11034: No Ipoint was found for the artificial + root 'my_task1', when using the 'start_task_code' and 'end_task_code' + annotations. + + + E11035 + + Multiple traces can not be given for a single RVD root or task if the --discover-fptr + is used. + + Elimination: Ensure that traces that map to the same root or task are parsed sep- + arately. + : Error E11035: The option '--discover-fptr' may not be used + when multiple traces are given for a single root or task. Traces + 'trace1.rpz, trace2.rpz, trace3.rpz' refer to 'main_task' in RVD + 'report.rvd' + + + E11036 + + Unexpected value found in the coverage map data. + + Elimination: Make sure the coverage map data was collected/extracted correctly. + : file.ext: Error E11036: Error in map data, expected '6bfa21cc' + but found '5a4a7f98' for the 'Magic number'. + + + E11037 + + The calculated CRC32 did not match the expected value. + + Elimination: Make sure the coverage map data was collected/extracted correctly. + : file.ext: Error E11037: CRC32 mismatch, expected '6bfa21cc' but + calculated '5a4a7f98'. + + + E11038 + + An unexpected amount of data was found. + + Elimination: Make sure the coverage map data was collected/extracted correctly. + : file.ext: Error E11038: Error in map data, expected either 936 + bytes (used size) or 1200 bytes (max size) but found 1016 bytes. + + +114 RVS Troubleshooting Guide vWF20190404 +RVS User Messages Errors + + + E11039 + + Less data than expected was found. + + Elimination: Make sure the coverage map data was collected/extracted correctly. + : file.ext: Error E11039: Error in map data, was expecting at + least 200 bytes but only found 68 bytes. + + + E11040 + + The sequence of accesses to the preemption stack is incorrect. + + Elimination: You may have to filter the data (demultiplexing) before processing it. + : Error E11040: Error (push) on livemap stack at trace line 68. + + + E11041 + + The value of the ID exceeded the maximum allowed value. + + Elimination: You may have to filter the data before processing it. + : Error E11041: Overflow detected decoding ID from '4294967296 + 10' (line 68) + + + E11042 + + The value of the timestamp exceeded the maximum allowed value. + + Elimination: You may have to filter the data before processing it. + : Error E11042: Overflow detected decoding timestamp from '10 + 0x10000000000000000' (line 68) + + + E11043 + + During operation of the demux filter, an unexpected sequence of events was ob- + served in the trace, such as reaching the exit Ipoint from a task that was never + entered. The demux filter is unable to attempt to recover from the situation auto- + matically. + + Elimination: This error normally means that the beginning of the trace is incom- + plete, missing the earliest events from system execution. However, it may also in- + dicate that the trace is corrupt, or has been generated incorrectly. + : Error E11043: Unexpected sequence of events at time 1200. + [Additional information] + + + E11044 + + The map file contains coverage data for a test case with ID = 0. This must be the + result of passing zero for the ID argument to RVS_Begin_Test. Test case ID zero is + reserved for test cases with no ID, thus you must not specify zero directly. + + +RVS Troubleshooting Guide vWF20190404 115 +Errors RVS User Messages + + + Elimination: Use a test case ID that is greater than or equal to one when calling + RVS_Begin_Test. + : Error E11044: Test case ID of zero was found in map file + + + E11045 + + The traces being parsed contained two named virtual tasks with the same Id. + + Elimination: Ensure that the demux filters used do not contain two virtual tasks that + are using the same virtual task Id but with different names. + : Error E11045: Two virtual tasks were found with with the same + task ID but different names. Both task 'myTask1' and task 'myTask2' are + assigned to task ID '1001'. + + + E11046 + + The taskparser tool read a trace data file containing a sequence of Ipoints that + may not be a valid trace of the software modeled in the .rvd file. Though this may + occur for all the reasons listed in the description for Error E11009, this may also + have occurred because the --faster option was used, and there is insufficient in- + strumentation in one or more subprograms for parsing using --faster. + + Elimination: Rerun the taskparser tool without the --faster option, or add more + Ipoints to the subprogram where the unexpected Ipoint was detected, e.g. by us- + ing the TIME_FULL profile. + : Error E11046: Trace error detected. + In trace file 'trace.rpz'. + At trace record number 101. + At time 52322. + Unexpected Ipoint 122 was encountered. + Previous Ipoint: 254 + Expected Ipoint(s): + 12232, 12231, 10 + + + E11047 + + The tool read a branch trace file containing a sequence of branches that did not + match the disassembled program. This occurs if the branch trace and disassem- + bly do not match, for example if (1) the disassembly is from a different version of + the program, or (2) the branch trace is corrupt or missing some data, or (3) the + disassembly contains an incorrect interpretation of the instructions. + + Elimination: Ensure that the branch trace and disassembly are consistent. Check + for errors in earlier trace processing stages (e.g. trace capture, trace conversion, + demultiplexing). Use 'tracedebug' to examine the trace around the time/position + stated in the error message to check for corruption. Check the disassembled code + for consistency with the trace, and check the SCFG file for consistency with the + disassembled code. + : Error E11047: Trace error detected. + + +116 RVS Troubleshooting Guide vWF20190404 +RVS User Messages Errors + + In trace file 'trace.rpz'. + At trace record number 101. + At time 52322. + Disassembly file 'x.dtxt'. + Standard control flow graph (SCFG) file 'x.scfg'. + More + + + E11048 + + The tool read a branch trace file which does not appear to match the standard + control flow graph. The branch trace and the disassembly don't have any address- + es in common. + + Elimination: Ensure that the branch trace and disassembly are consistent. Check + for errors in earlier trace processing stages (e.g. trace capture, trace conversion, + demultiplexing). + : Error E11048: Unable to find any address in trace file + 'trace.rpz' matching the standard control flow graph (SCFG) file + 'x.scfg'. + + + E11049 + + The tool failed to parse a standard control flow graph (SCFG) file. + + Elimination: Clean the project directory, forcing the tool to recreate the SCFG file. + : Error E11049: The standard control flow graph (SCFG) file + 'x.scfg' could not be parsed. + More + + + E11050 + + The tool was unable to copy data from one branch trace file to another because + the branch trace data was invalid in some way. This occurs if the PSP has not + filtered or demultiplexed the trace data correctly. + + Elimination: This error indicates a bug in the PSP. Check that the PSP is processing + traces correctly. + : Error E11050: Trace error detected. + Source trace file 'trace.rpz'. + Source trace record number 101. + Source time 52322. + Target file 'output.rpz'. + More + + + E11051 + + The symbol had no matching ipoint from any of the input trace files. Either the TFA + is incorrect, or the correct trace file was not supplied on the command line. + + Elimination: Correct the TFA if it is incorrect, or supply the correct trace file on the + command line. + + +RVS Troubleshooting Guide vWF20190404 117 +Errors RVS User Messages + + : Error E11051: No ipoint could be found for symbol FUNCSTART * + process_messages + + + E11052 + + The branch trace file for a thread does not appear to contain any entry to the root + function for the thread. Other addresses in the trace match the standard control + flow graph (SCFG) file, but the root function is never reached. + + Elimination: Ensure that the correct root function has been specified for the thread. + : Error E11052: Unable to find the entry to root function + 'root' (address 0x1234) in trace file 'trace.rpz'. + + +3.1.12 E14xxx - RTS files + E14001 + + An RTS script made use of a feature which is not yet implemented. + + Elimination: Contact support@rapitasystems.com for advice. + : file.ext: Error E14001: Unimplemented feature: . + + + E14002 + + A suitable operator function (e.g. +, -) is not available for this type. + + Elimination: Rewrite the expression containing this operator, cast the type, or + state explicitly which operator function should be used, e.g. replacing -a with + global.package_name."-"(a). + : file.ext: Error E14002: Operator '+' is not defined for type + 'integer'. + + + E14003 + + A suitable operator function (e.g. +, -, *) is not available for this pair of types. + + Elimination: Rewrite the expression containing this operator, cast the types, or + state explicitly which operator function should be used, e.g. replacing a + b with + global.package_name."+"(a, b). + : file.ext: Error E14003: Operator '+' is not defined for types + 'integer' and 'string'. + + + E14004 + + More than one possible implementation of this operator exists, and the RTS script + does not contain enough information to determine which one should be used. + + Elimination: Rewrite the expression containing this operator, or state explic- + itly which operator function should be used, e.g. replacing a + b with + global.package_name."+"(a, b). + + +118 RVS Troubleshooting Guide vWF20190404 +RVS User Messages Errors + + : file.ext: Error E14004: More than one possible implementation of + operator '+' was found. The operand types are: details + + + E14005 + + An illegal variable name was specified within an RTS script. + + Elimination: Rewrite the expression or assignment containing this variable. + : file.ext: Error E14005: + + + E14006 + + A statement or expression was placed incorrectly within the RTS script. + + Elimination: Move the statement or expression to an appropriate location. + : file.ext: Error E14006: + + + E14007 + + The RTS script contains an incorrectly formatted string. + + Elimination: Correct the use of quotation marks and/or escape sequences within + the string. + : file.ext: Error E14007: + + + E14008 + + An object named by the RTS script could not be found. + + Elimination: Correct the name and/or signature of the object. + : file.ext: Error E14008: + + + E14009 + + A subprogram named by the RTS script could not be found in the project, or within + a package within the project. + + Elimination: Correct the name of the object. + : file.ext: Error E14009: Subprogram '' not found in . + + + E14010 + + A subprogram named by the RTS script was found in the project, but the parameter + signature did not match. + + Elimination: Correct the name and/or signature of the object. + : file.ext: Error E14010: Subprogram '' was found in , but the + parameter signature does not match. The RTS script specifies signature + '' while the project specifies signature ''. + + +RVS Troubleshooting Guide vWF20190404 119 +Errors RVS User Messages + + + E14011 + + Subprograms nested in subprograms cannot be the target of tests. + + Elimination: Tests can only be based on subprograms nested inside packages. + Choose a different subprogram as the target of this test. + : file.ext: Error E14011: Subprograms nested in subprograms cannot + be the target of tests. + + + E14012 + + Subprograms within an instance of a generic object cannot be stubbed. + + Elimination: Tests cannot create stubs within an instance of a generic object. The + generic object should be stubbed instead. + : file.ext: Error E14012: Instance objects cannot be the target of + stubs, use the generic for this. + + + E14013 + + Subprograms within a generic object cannot be tested. + + Elimination: Tests cannot target generic objects. Test an instance of the generic + object instead. + : file.ext: Error E14013: Generic objects cannot be the target of + tests, use an instance of this generic. + + + E14014 + + The RTS statement requires some type conversion, but this conversion cannot be + carried out as there is no relationship between the types. + + Elimination: The type conversion must be stated explicitly, using a conversion func- + tion. + : file.ext: Error E14014: There is no known way to convert type + 'type1' to type 'type2'. + + + E14015 + + No implementation of an operator exists for these operand types. + + Elimination: Rewrite the expression containing this operator, stating explic- + itly which operator function should be used, e.g. replacing a + b with + global.package_name."+"(a, b). + : file.ext: Error E14015: No implementation of operator '+' was + found. The operand types are: details + + + E14016 + + There is no implementation of this subprogram. + + +120 RVS Troubleshooting Guide vWF20190404 +RVS User Messages Errors + + + Elimination: Look in the source code to determine why this function is missing. + : Error E14016: An implementation of subprogram 'f' was not found. + + +3.1.13 E17xxx - RTBx + E17001 + + A network error occurred which prevented the client from connecting to the RTBx. + + Elimination: Check your network connection status, then run again. + : Error E17001: Could not connect to RTBx '127.0.0.1' + + + E17002 + + The API of the RTBx is not supported by the current version of the RTBx Command + Line Interface, as it is older than the RTBx firmware. + + Elimination: Update the RTBx Command Line Interface to the most recent version. + : Error E17002: The RTBx Command Line Interface is at version '1', + but the RTBx firmware is at version '2'. Please update the RTBx Command + Line Interface to the latest version. + + + E17003 + + The RTBx Command Line Interface no longer supports the API version of the RTBx + firmware. + + Elimination: Update the RTBx firmware to the most recent version. + : Error E17003: The RTBx Command Line Interface is at version + '2', but the RTBx firmware is at version '1'. Please update the RTBx + firmware to the latest version. + + + E17004 + + The task could not be performed as there is no job currently running. + + Elimination: Start a job on the target RTBx before this action. + : Error E17004: There is no job currently running on the RTBx + '127.0.0.1'. + + + E17005 + + There is no job with the specified name or ID on the target RTBx. + + Elimination: Check that the job name/ID being requested is correct and there exists + a job with that name/ID on the RTBx. + : Error E17005: No such job '1234567890' on RTBx '127.0.0.1'. + + +RVS Troubleshooting Guide vWF20190404 121 +Errors RVS User Messages + + + E17006 + + The requested action could not be done because there is a job already running + on the specified RTBx. + + Elimination: Stop the currently running job first before performing this action. + : Error E17006: There is already a job running on the RTBx + '127.0.0.1'. + + + E17008 + + The specified job does not have any trace files associated with it. + + Elimination: Run the specified job first before downloading the trace data. + : Error E17008: No trace files available to download for job: + '1234567890', run: '0'. + + + E17009 + + The specified run tag does not exist for the specified job. + + Elimination: Check that the job has a run with that tag. + : Error E17009: No such run '0' for job '1234567890' on RTBx + '127.0.0.1'. + + + E17010 + + The specified action failed, with the supplied error message. + + Elimination: + : Error E17010: Failed action: 'start job', Error message: ''. + + + E17011 + + The specified action failed, with the supplied HTTP error code. + + Elimination: + : Error E17011: Failed action: 'start job', HTTP error code: + '502'. + + + E17012 + + The trace file downloaded does not match the file on the RTBx that was sent. + + Elimination: Download the trace file again. + : Error E17012: The trace file 'trace0.rpz', failed the download + integrity check. + + +122 RVS Troubleshooting Guide vWF20190404 +RVS User Messages Errors + + + E17013 + + The data received could not be parsed as valid JSON. + + Elimination: + : Error E17013: The JSON data received is invalid. Error message: + ''. + + +3.1.14 E18xxx - Spreadsheets + E18001 + + The spreadsheet doesn't contain any test sheets. + + Elimination: Please ensure all test sheets start with the word "Test". + : Error E18001: No tests found in file. Please ensure all test + sheets start with the word 'Test'. Tab names were: [Description,Test 1] + In file: 'test.xlsx' + + + E18002 + + The spreadsheet doesn't contain any enabled tests. + + Elimination: Please enable at least one test before running. + : Error E18002: All tests were disabled. Please enable at least + one test before running. In file: 'test.xlsx' + + + E18003 + + A converter for the test file has not been specified, and the file is not a recognized + format. + + Elimination: Please change the file extension or update your configuration to spec- + ify the appropriate converter. + : Error E18003: No converter specified and not a recognized file + extension for: 'test.ods' + Please change the file extension or update your configuration to specify + the appropriate converter + + + E18004 + + There is an error in the cell + + Elimination: Ensure the cell has a valid value. + : Error E18004: Check the input spreadsheet, cell error was found + '#NUM!' + In cell: 'test.xlsx:Test 1:25:10' + + +RVS Troubleshooting Guide vWF20190404 123 +Errors RVS User Messages + + + E18005 + + There is unsupported formatting in the cell + + Elimination: Ensure the cell has valid or no formatting. + : Error E18005: Check the input spreadsheet, cell format: + 'val:#,##0' is not supported. + In cell: 'test.xlsx:Test 1:25:10' + + + E18006 + + There is unsupported formatting in the cell + + Elimination: Ensure the cell has valid or no formatting. + : Error E18006: Check the input spreadsheet, date formats are not + supported. + In cell: 'test.xlsx:Test 1:25:10' + + + E18007 + + The expected table header is missing. + + Elimination: Ensure the table headers are valid. + : Error E18007: Table : Missing table header. Expected 'Header' + In cell: 'test.xlsx:Test 1:25:10' + + + E18008 + + The table header specified is incorrect. + + Elimination: Ensure the table header is valid. + : Error E18008: Table : Incorrect table header 'Header'. Expected + 'Header'. + Table headers are: 'Function name, Shorthand, Parameter, Type' + In cell: 'test.xlsx:Test 1:25:10' + + + E18009 + + No identifiers were found in the source that match the identifier name given in the + test. + + Elimination: Ensure the identifier name is a valid identifier. + : Error E18009: Found 0 function identifiers which match: 'ident' + In cell: 'test.xlsx:Test 1:25:10' + + + E18010 + + Multiple identifiers were found in the source that match the identifier name given + in the test. + + +124 RVS Troubleshooting Guide vWF20190404 +RVS User Messages Errors + + + Elimination: Ensure the identifier name is a valid identifier. + : Error E18010: Found 3 function identifiers which match: 'func' + Matched: func,pkg.funcIn cell: 'test.xlsx:Test 1:25:10' + + + E18011 + + The identifier name given has already been defined. + + Elimination: Ensure the identifiers are uniquely named. + : Error E18011: The function identifier 'func' has already been + defined. + In cell: 'test.xlsx:Test 1:25:10' + + + E18012 + + The identifier name given has not been defined. + + Elimination: Ensure the identifiers are defined before use. + : Error E18012: The function identifier 'func' has not been + defined. + In cell: 'test.xlsx:Test 1:25:10' + + + E18013 + + The identifier contains invalid characters. + + Elimination: Ensure the identifier has a valid name. Identifiers must be alphanu- + meric and start with a letter or _ + : Error E18013: The variable identifier 'variable_name' contains + invalid characters. Identifiers must be alphanumeric and start with a + letter or _ + In cell: 'test.xlsx:Test 1:25:10' + + + E18014 + + The operator used in the test is not a valid operator. + + Elimination: Ensure the operator given is a valid operator. + : Error E18014: Test Data : Operation 'operator' is not + recognized. + In cell: 'test.xlsx:Test 1:25:10' + + + E18015 + + The test detail attribute value given is not valid. + + Elimination: Use a valid attribute value, provided from the error message. + : Error E18015: Test detail 'disabled' has an invalid attribute + value 'false'. + no + + +RVS Troubleshooting Guide vWF20190404 125 +Errors RVS User Messages + + In cell: 'test.xlsx:Test 1:25:10' + + + E18016 + + The test detail has already been set. + + Elimination: Only set the test detail once. + : Error E18016: The test detail 'disabled' has already been set. + In cell: 'test.xlsx:Test 1:25:10' + + + E18017 + + The test detail given is not recognized. + + Elimination: Use recognized test details, provided in the error message. + : Error E18017: The test detail 'enabled' is not a recognized + attribute. + disabled + In cell: 'test.xlsx:Test 1:25:10' + + + E18018 + + The reference ':uut' has been used with no scope to refer to. + + Elimination: Specify a scope for the ':uut' reference. + : Error E18018: Call or Stub: ':uut' has been used with no scope + to refer to. + In cell: 'test.xlsx:Test 1:25:10' + + + E18019 + + Cannot return to :uut from inside a different context. + + Elimination: Provide an appropriate test order. + : Error E18019: Call or Stub: Cannot return to :uut from inside a + different context. + In cell: 'test.xlsx:Test 1:25:10' + + + E18020 + + The given operator can only be used in the specified context context. + + Elimination: Ensure there is an appropriate context when using this operator. + : Error E18020: The 'operator' operator can only be used in a stub + context. + In cell: 'test.xlsx:Test 1:25:10' + + + E18021 + + The specified operator cannot be used in the given context. + + +126 RVS Troubleshooting Guide vWF20190404 +RVS User Messages Errors + + + Elimination: Use a valid operator in the given context. + : Error E18021: The 'check' operator cannot be used in a script + context. + In cell: 'test.xlsx:Test 1:25:10' + + + E18022 + + The specified operation does not accept the item given. + + Elimination: Do not specify the item given for the specified operation. + : Error E18022: Test Data: Cannot specify a variable for the + 'operator' operation. + In cell: 'test.xlsx:Test 1:25:10' + + + E18023 + + The ':stub' reference has been used with no stub context to refer to. + + Elimination: Ensure there is a stub context when using ':stub'. + : Error E18023: Call or Stub: ':stub' has been used with no stub + context to refer to. + In cell: 'test.xlsx:Test 1:25:10' + + + E18024 + + A stub cannot only be specified in an object context. + + Elimination: Do not specify the stub in the object context. + : Error E18024: Stub: Object context cannot be used when + specifying a stub. + In cell: 'test.xlsx:Test 1:25:10' + + + E18025 + + When the 'Remove Original Stubs' configuration option is enabled, you cannot call + the original stub + + Elimination: If you require calls to the original stub then the 'Remove Original Stubs' + configuration option must not be enabled. + : Error E18025: Test Data: Cannot call the original stub, when + 'Remove Original Stubs' configuration option is enabled. + In cell: 'test.xlsx:Test 1:25:10' + + + E18026 + + The init operation may only be used with local variables. + + Elimination: + : Error E18026: Test Data : The init operation may only be used + with local variables. + + +RVS Troubleshooting Guide vWF20190404 127 +Errors RVS User Messages + + In cell: 'test.xlsx:Test 1:25:10' + + + E18027 + + The check approximation contains an incorrect value. + + Elimination: Use a numeric value with an optional %. + : Error E18027: Test Data : The check approximation contains an + incorrect value '10' enter a numeric value with an optional %. + In cell: 'test.xlsx:Test 1:25:10' + + + E18028 + + The function type contains an incorrect value. + + Elimination: Use a valid type for the function. + : Error E18028: Scripts : The function 'func' must have a type in + type1,type2. The type given was 'type3'. + In cell: 'test.xlsx:Test 1:25:10' + + + E18029 + + The function cannot be defined without a source file. + + Elimination: Specify a source file for the function. + : Error E18029: Scripts : The function 'func' cannot be defined + without a source file. + In cell: 'test.xlsx:Test 1:25:10' + + + E18030 + + The macro cannot be placed in multiple locations. + + Elimination: You must specify single location for placing a macro. + : Error E18030: Context : Can not define multiple locations to + place macro macro. + In cell: 'test.xlsx:Test 1:25:10' + + + E18031 + + The macro parameter cannot have multiple definitions. + + Elimination: Remove the additional parameter definitions, or rename them. + : Error E18031: Context : Multiple definitions of 'param' for + 'macro' + In cell: 'test.xlsx:Test 1:25:10' + + + E18032 + + Rows containing test details can not also contain test vectors + + +128 RVS Troubleshooting Guide vWF20190404 +RVS User Messages Errors + + + Elimination: Move the test vectors to rows that do not contain test details. + : Error E18032: Invalid field - rows containing test details can + not also contain test vectors. + In cell: 'test.xlsx:Test 1:25:10' + + + E18033 + + The operation requires a value to be used. + + Elimination: Provide a value, or explicitly ignore the cell by using ':'. + : Error E18033: Test Data: Must specify a value for the 'check' + operation or use ':' to ignore this cell. + In cell: 'test.xlsx:Test 1:25:10' + + + E18034 + + The operation requires a call or stub. + + Elimination: Provide a call or stub for the operation. + : Error E18034: Test Data: No 'Call or stub' specified for the + 'check' operation. + In cell: 'test.xlsx:Test 1:25:10' + + + E18035 + + Test vectors require at lease one operation. + + Elimination: Provide an operation for the test vector. + : Error E18035: Test Data: No operation specified for test vector. + In cell: 'test.xlsx:Test 1:25:10' + + + E18036 + + All init names must be specified prior to their use. + + Elimination: Specify an init name and value for the local given. + : Error E18036: Test Data : The init name 'value1' was not + specified for the local 'local'. + In cell: 'test.xlsx:Test 1:25:10' + + + E18037 + + The colon operator may not be used in this context. + + Elimination: Try using '?' instead. + : Error E18037: Locals : The colon operator may not be used in + this context. Try using '?' instead. + In cell: 'test.xlsx:Test 1:25:10' + + +RVS Troubleshooting Guide vWF20190404 129 +Warnings RVS User Messages + + + E18038 + + The check mode given is not valid. + + Elimination: Use a valid check, provided from the error message. + : Error E18038: Test Data : The check mode 'az' should be one of + 'eq, ne, gt'. + In cell: 'test.xlsx:Test 1:25:10' + + +3.2 Warnings + This section lists the warning messages that can be issued by RVS. + + Warning messages are grouped by classes in the following sections. + + For each warning message the following are given: + • The warning number. + • A description of the warning messages. + • What action should be performed to avoid the warning (elimination). + • A possible justification for not eliminating the warning. + • An example of the message as it would be issued by RVS. + +3.2.1 W60xxx - Files + W60001 + + The input file is empty. + + Elimination: Make sure the provided file contains the expected data. + + Justification: An empty file usually indicates that another process has failed to pro- + duce correct output. If the other process is still being developed or cannot gener- + ate some appropriate non-empty output (e.g. just a comment) then this warning + can be ignored. + Warning W60001: The file 'file.c' is empty. + + + W60002 + + The source file specified for an input file does not match the actual source file + name found in preprocessor directives. + + Elimination: Change the source file name specified in the --list parameter file to + match the one recorded by the preprocessor. + + Justification: This warning can be ignored if the mismatch between the names is + intentional. + Warning W60002: The source file specified for input file 'x.pre' does + not match the actual source file 'y.c'. + + +130 RVS Troubleshooting Guide vWF20190404 +RVS User Messages Warnings + + + W60003 + + The specified source file could not be found. Be sure to include the appropriate + directory using the '-I' option when running xstutils. + + Elimination: xstutils navigates from the .xsc files to the instrumented source, pre- + processed source and the original source code input to the preprocessor. If xstu- + tils is unable to find a corresponding */ source file, use the '-I' option to tell it where + to look, or adjust the build system so that xstutils can follow the #-directives to + find the original source file. + + Justification: If your build system creates files in folders with auto-generated + names, it may be impossible to name appropriate folders for the '-I' option. In this + case, the warning can be ignored. + Warning W60003: Cannot find file 'file'. + + + W60004 + + The specified source file could not be found at this location. However, another + version of the file was found and will be used instead. + + Elimination: Do not move files during the instrumentation process. + + Justification: This warning can be ignored if the found files are correct and it is not + possible to prevent the missing files from being moved. + Warning W60004: Cannot find file 'file.c' in directory '[...]/dir1'. + Using the copy in '[...]/dir2' instead. + + + W60005 + + The input file is not part of the base directory or any included directories. The file + will be instrumented, and the instrumented source code will be written to the root + of the destination directory. + + Elimination: Make sure all input files listed are located within the --base-dir direc- + tory tree or included with -I. + + Justification: This warning can be ignored if your code includes library source that + cannot be moved into your project. + Warning W60005: The input file 'file.c' is not part of the base + directory 'source' or any included directories. Instrumented source + code will be written to 'dest'. + + + W60006 + + There are no subprograms matching this expression. + + Elimination: Remove the non-matching expression or replace it with a matching + expression. + + +RVS Troubleshooting Guide vWF20190404 131 +Warnings RVS User Messages + + + Justification: If you are using a number of wildcard roots when only instrumenting + parts of the code at a time (e.g. for unit test scenarios or multiple-run instrumen- + tation) then some of the wildcards will only match in some cases. In this situation, + this warning can be ignored. + Warning W60006: No root function matching 'root_name_*' was found. + + + W60009 + + The checksum for this justification calculated by rvdutils does not match the one + calculated by the GUI. + + Elimination: Re-create the justification from the GUI, or review the changes in the + existing justification by hand. + + Justification: This warning can be ignored while processing a batch of justifica- + tions. + Warning W60009: The justification at file.c:1 has been modified, and + will require review. + + + W60010 + + The file could not be deleted. + + Elimination: Ensure that the tool has permission to delete the file. + + Justification: This warning may come up in highly-parallel processing, in which + case it can be ignored, although it is usually worth trying to structure the file pro- + cessing so that multiple stages of processing will not use the same folder. + Warning W60010: File 'trace.rpz' could not be deleted. + + + W60011 + + The file was found in the current directory which is a deprecated location because + it may not be found by some tools. + + Elimination: Move the file to a supported location, see the RVS Reference Guide + for details. + + Justification: If using more than one version of the tool, it may be most practical to + use the deprecated location so that older tools can find the same configuration. + Warning W60011: The file 'rvsconfig.ini' was found in the current + directory which is a deprecated location for storing configuration and + license files. + + + W60012 + + The input file name is a file extension with no name. + + Elimination: Make sure the provided file name is more than a file extension. + + +132 RVS Troubleshooting Guide vWF20190404 +RVS User Messages Warnings + + + Justification: This warning can be ignored if the build system uses such files and + they need to be processed by RVS tools. + Warning W60012: The file '.c' has no name (only an extension). + + + W60013 + + The instrumenter should be invoked with either the -d or the -o option in order to + specify where instrumented output files should be placed. This avoids any ambi- + guity about the desired location for output files, and prevents original source files + being compiled in place of instrumented code. If -d or -o is not specified, a default + location is used instead: instrumented files are placed in the same directory as + the input files, and the name of each instrumented file is identical to the source file + with '.i.' added to the extension, e.g. 'src.adb' becomes 'src.adb.i'. + + Elimination: Use the -d option to place instrumented files in a separate directory + (i.e. '-d instrumented_files') or use the -o option to specify the name of each instru- + mented file (i.e. '-o output.i.adb'). + + Justification: This warning can be ignored if the build system can only build the + instrumented code when placed within the same directory as the .adt files. + Warning W60013: The location for instrumented output files was not + specified using either -d or -o. Instrumented output will be written + to the directory containing the input files ('dir'). Each output file + will share the same name as the source file, with '.i' added to the + extension, e.g. 'src.adb' becomes 'src.i.adb'. + + + W60014 + + There was an issue with the "rvsconfig.ini" file. + + Elimination: Refer to the RVS Installation and Licensing Guide for information about + the correct usage of "rvsconfig.ini". + + Justification: + Warning W60014: Placeholder warning for configlib, do not remove. + + + W60015 + + Files from the RVS_TEMP folder are missing. + + Elimination: Re-instrument the source files, and do not delete the contents of + RVS_TEMP before creating the report. + + Justification: This warning can be ignored if your build system cleans up temp file + automatically. + Warning W60015: Cannot find RVS_TEMP files. Example message. + + + W60016 + + Another justification has been migrated to this target. + + +RVS Troubleshooting Guide vWF20190404 133 +Warnings RVS User Messages + + + Elimination: Remove one of the justifications. + + Justification: This warning can be ignored while processing a batch of justifica- + tions. + file.ext:42:Warning W60016: Another justification has been migrated to + this statement (file1.c:32). + + + W60017 + + The specified source file has been modified since it was instrumented. This means + that coverage and timing results cannot be shown alongside their source loca- + tions, as there is no valid copy of the source file. The source file will not appear + within the RVS Viewer. + + Elimination: Do not modify files during the instrumentation process. + + Justification: This warning can be ignored if your build system monitors and mod- + ifies source codes automatically. + Warning W60017: File 'file.c' has been modified after instrumentation. + This file will not be added to the RVD. + + + W60018 + + The specified XSC file was created by an older version of RVS, and should be re- + generated. + + Elimination: Re-run the source code instrumentation. + + Justification: + Warning W60018: The file 'file.xsc' is out of date. Please update your + instrumented build. + + + W60019 + + The file has a mixture of LF and CRLF line endings. + + Elimination: Standard line endings to Unix or DOS format. + + Justification: + Warning W60019: The file 'file.c' has mixed line endings. Source + locations may be reported incorrectly. + + + W60020 + + covparser (or testparser) has been given an RVD file (call it 'B') and a map file, but + the map file was generated from a different RVD file (call it 'A'). The parser cannot + reliably obtain test data from the map file, because the RVD files A and B were + generated from different source code. + + +134 RVS Troubleshooting Guide vWF20190404 +RVS User Messages Warnings + + + Elimination: This error normally points to a problem with the integration, where a + stale file is not being updated correctly by some processing stage. Check the time + stamps for the map file and and the RVD to determine if an older version of the + RVD, map file or map template is in use. + + Justification: + file.ext:42:Warning W60020: Detail + + + W60021 + + The command file recursively includes another command file. + + Elimination: Remove the --cmd-file option from the command file. + + Justification: + Warning W60021: Ignored --cmd-file option found inside the command file + 'cmd.txt'. + + + W60022 + + The file could not be accessed for a required operation. + + Elimination: Ensure that the tool has permission to perform actions on the file. + + Justification: + Warning W60022: File 'source.txt' could not be writing. + + +3.2.2 W61xxx - Command line + W61001 + + Some of the given report/trace files did not correspond to any trace/report file. This + happens when the tool (covparser or timeparser) tries to match trace root Ipoints + to report root Ipoints and either a report file had no data to populate it or some + data had no report file to populate. + + Elimination: This warning may be eliminated by customizing the integration so that + only relevant files are generated. + + Justification: This warning may be ignored if the set of generated report and trace + files varies depending on what was encountered during testing, and the set of files + to process has to be explicitly enumerated in the integration. + Warning W61001: Some report files did not correspond to any trace + file:test.rvd, test2.rvd, report.rvd + + + W61002 + + The Ipoint Id ranges in the IdPack configuration file are processed in the order + in which they appear, with the first matching entry being used. If multiple ranges + + +RVS Troubleshooting Guide vWF20190404 135 +Warnings RVS User Messages + + + match, a reader unaware of this disambiguation method could misinterpret the + specification. + + Elimination: This warning may be eliminated by rewriting the IdPack configuration + file to delineate each disjoint range explicitly rather than relying on implicit disam- + biguation. + + Justification: This warning may be ignored if the IdPack configuration file is inde- + pendently reviewed, and the IdPack configuration file is correct, and the IdPack + configuration file cannot justifiably be rewritten to exclude the overlap because of + the increase in effort. + file.ext:42:Warning W61002: The Ipoint Id ranges in the IdPack + configuration file 'file.cfg' are not disjoint. + + + W61003 + + Address must be specified for Ipoint in the specified file. The Ipoint is removed if + the address is not found. + + Elimination: Ensure that the address mapping is complete and correct. + + Justification: This warning may be ignored if the affected Ipoint is outside of the + analysis scope, and the address for that Ipoint cannot be determined in advance. + Warning W61003: No address was specified for Ipoint Id 23 in file + 'file.txt'. This Ipoint has been removed. + + + W61004 + + Ipoint number does not identify a unique subprogram. It cannot be used to dis- + cover the target of a call through a function pointer. + + Elimination: Resolved indirect calls manually using call_to annotations. + + Justification: This warning can only be eliminated. If not it will be followed by an + error. + Warning W61004: Ipoint number 23 does not identify a unique subprogram. + It cannot be used to discover the target of a call through a function + pointer. + + + W61005 + + There were no Ipoints found in the input file(s). + + Elimination: This warning may be eliminated by removing the file from the list of + trace files, or reworking the instrumentation options and the instrumentation library + to produce instrumentation in the file. + + Justification: This warning may be ignored if the integration sometimes produces + data in the file and sometimes not, depending on the conditions of the test. + Warning W61005: No Ipoints could be found in the input file(s). + + +136 RVS Troubleshooting Guide vWF20190404 +RVS User Messages Warnings + + + W61006 + + The option -m has been deprecated now. + + Elimination: Use option --analysis-scope instead of option -m + + Justification: This warning can be ignored if the command line is also used with + an old version of RapiTime that requires option -m. + Warning W61006: Option -m is deprecated. + + + W61007 + + The specified file could not be found and option -C, continue on error, was used. + + Elimination: Make sure the specified file exists or do not use it on the command + line. + + Justification: This warning can be ignored if specifying an non-existing file on the + command line is intentional. For example if the missing file was not needed to + analyze the root function. + Warning W61007: Cannot find file 'file'. + + + W61008 + + The specified file could not be read and option -C was used. + + Elimination: Make sure the specified file is readable or do not use it on the com- + mand line. + + Justification: This warning can be ignored if specifying an non-readable file on the + command line is intentional. + Warning W61008: Cannot read file 'file'. + + + W61009 + + taskparser produces XML trace files. The file extension should be '.xmltrc'. + + Elimination: Use file names similar to 'trace.xmltrc'. + + Justification: This warning can be ignored if the XML trace file will never be dis- + played by the RapiTask viewer. + Warning W61009: RapiTask file names should end in '.xmltrc'. + + + W61010 + + The tool was not able to access the license proxy, a background program which + provides license services to all RVS tools. As a result, the tool was forced to ac- + cess the license server, USB License Key or license file itself. This means that tool + startup is slower. + + +RVS Troubleshooting Guide vWF20190404 137 +Warnings RVS User Messages + + + Elimination: If this warning is seen frequently, please contact + support@rapitasystems.com for assistance. + + Justification: This warning can be safely ignored as both methods of licensing are + equivalent. + Warning W61010: Acquiring RVS license in direct mode. err + + + W61011 + + The VCS ID regular expression supplied using --VCS-regexp did not match any + VCS ID strings within a source file. This may indicate that the regular expression + is incorrect. + + Elimination: Amend the VCS ID regular expression to match the VCS ID scheme + used within the source file. The RVS Reference Guide has some examples of reg- + ular expressions that can be used with --VCS-regexp. + + Justification: This warning may be ignored if there are no VCS IDs within the source + file. + Warning W61011: The VCS ID regular expression 'regex' did not match any + strings within source file 'file'. + + + W61012 + + The included directory does not contain any source files with obvious extensions. + + Elimination: Only include directories which contain source files. + + Justification: This warning may be ignored if there are source files in this directory + with non-standard file extensions. + Warning W61012: The included source directory 'dir' contains no source + files. + + + W61013 + + The same file was given as input and output. + + Elimination: Only specify input files which will not be overwritten by the tool. + + Justification: This warning may be ignored if the overwrite is intentional. For exam- + ple, the memory space is not enough for two reports. + Warning W61013: The output file 'report.rvd' cannot also be used as + input. It will be overwritten. + + + W61014 + + When using the --merge-results option, a matching test-id was found in the rvd + file, however the specified test-name did not match the test-name associated with + that test-id in the rvd. + + +138 RVS Troubleshooting Guide vWF20190404 +RVS User Messages Warnings + + + Elimination: Change the value of the --test-name options to match. + + Justification: This warning may be ignored if the building system auto feed the test + name to the command line option --test-name. + Warning W61014: Matching test-ids with mismatching test-names. Test-id + '1' in 'report.rvd' has the name 'test001'. However the merged test + with the same test-id has the name 'test002'. The merged test name will + be used. + + + W61016 + + A command line option tried to reference a subprogram which doesn't exist. + + Elimination: Check that the subprogram name is correct, and case-sensitive (for + C functions). + + Justification: This warning may be ignored if the set of subprogram and input files + varies depending on what was encountered during testing, and the set of subpro- + grams to process has to be explicitly enumerated in the integration. + Warning W61016: No subprogram named 'func' was found in the input. + + + W61017 + + An instrumentation profile has been replaced by a tool option and is now depre- + cated. + + Elimination: Modify your integration to use the recommended option and instru- + mentation profile. + + Justification: This warning can be ignored if the command line is also used with + an old version of RVS that requires deprecated instrumentation profiles. + Warning W61017: The instrumentation profile 'COV_MCDC_MAP' is + deprecated. You should use profile 'COV_MCDC' with option '--coverage- + map' instead. + + + W61018 + + It is unlikely that the segment size is not a power of 2. + + Elimination: Change the segment size to be a power or 2. + + Justification: This warning may be ignored if you have limited storage resource for + collecting data. + Warning W61018: The value specified for option --segment (300) is not a + power of 2. + + + W61019 + + The same file has been listed multiple times as input. + + +RVS Troubleshooting Guide vWF20190404 139 +Warnings RVS User Messages + + + Elimination: Remove the duplicate(s) from the list of input files. + + Justification: When you specify input file with both list file and command line option, + and there are some overlap. This warning may be ignored. + Warning W61019: The file 'file.c' has been specified as input more than + once. + + + W61020 + + Flags -f and --no-instr may be used together, but it really does not make sense + to include them both. + + Elimination: Remove -f when adding --no-instr. + + Justification: This warning may be ignored if the option list varies depending on the + test condition. The building system auto-generate the option list which contains + both options. + Warning W61020: The flag -f forces overwrite of instrumented files but + --no-instr will not produce instrumented files. + + + W61021 + + Some options may be used together, but will have any effect. + + Elimination: Remove the ignored option. + + Justification: This warning may be ignored if the option list varies depending on the + test condition. The building system auto-generate the option list which contains + both options. + Warning W61021: --coverage-map has been ignored because of --no-instr. + + + W61022 + + No call_through_to annotations could be created using the command-line options + given to rvdutils, as the .rvd file does not contain any function calls using the func- + tion name given to the --call-through-to-func parameter. + + Elimination: Check the function name passed to --call-through-to-func. + + Justification: This warning may be ignored if the set of generated report and call + through to functions varies depending on what was encountered during testing, + and the set of call through to functions has to be explicitly enumerated in the in- + tegration. + Warning W61022: No calls to function name 'func' were found in the .rvd + file: no call_through_to annotations were created. + + + W61023 + + The option --exclusions is deprecated. + + +140 RVS Troubleshooting Guide vWF20190404 +RVS User Messages Warnings + + + Elimination: Use justifications for code that cannot be covered. + + Justification: This warning can be ignored if the command line is also used with + an old version of RapiCover that requires option --exclusions. + Warning W61023: Option --exclusions is deprecated. + + + W61024 + + The file extension .fctree is deprecated. + + Elimination: Do not use this file extension. + + Justification: This warning can be ignored if the command line is also used with + an old version of RapiCover that requires call tree file with .fctree extension. + Warning W61024: File extension .fctree is deprecated. + + + W61025 + + Several outputs are to be written to the same file name. This error has been down- + graded to a warning because --permissive is specified. + + Elimination: Change the command line to ensure all output files have different file + names. + + Justification: + Warning W61025: File 'file.c' was found more than once as output (and -- + permissive is specified). + + + W61026 + + One of the license servers appears more than once in the rvsconfig.ini file, or the + list passed to the "rvsinfo" -c parameter. Additional appearances are ignored. + + Elimination: Remove duplicates from the list of license servers. Note that a single + server may have multiple addresses. + + Justification: + Warning W61026: License server ip appears more than once in the server + list: additional appearances are ignored. + + + W61027 + + Connection to one of the license servers failed with an error while "rvsinfo" was + performing a license scan. The server was skipped. + + Elimination: The server may be down for maintenance, or it may have been moved + to a new network address, or additional proxy details may be required. Contact + your IT support administrator to obtain the correct settings for this license server. + + +RVS Troubleshooting Guide vWF20190404 141 +Warnings RVS User Messages + + + Justification: + Warning W61027: Connection to license server ip failed (err). + + + W61028 + + The license server does not support license scans, so "rvsinfo" was not able to + obtain any information about the licenses available on this server. The server was + skipped. + + Elimination: Contact support@rapitasystems.com for assistance with licensing is- + sues. + + Justification: + Warning W61028: License server ip does not support license scans. Please + upgrade the server to the most recent version. + + + W61029 + + A necessary environment variable is not set. + + Elimination: The environment variable should be defined. + + Justification: + Warning W61029: Environment variable DISPLAY is not set + + + W61030 + + The specified memory limit is higher than the memory available on the system + itself, or the system architecture. Available memory has been pinned to the amount + in the system instead. + + Elimination: Set the memory limit to less than or equal the amount of memory in + the system. + + Justification: + Warning W61030: Specified memory limit (100 MB) is higher than the + available system memory (4000 MB). Limiting to available system memory. + + + W61031 + + The command line %s is deprecated. + + Elimination: See the migration guide for details on what to use instead. + + Justification: + Warning W61031: The command line --deprecated-option is deprecated and + may be removed in a later version. Use option --new-option See the + migration guide for more details. + + +142 RVS Troubleshooting Guide vWF20190404 +RVS User Messages Warnings + + + W61032 + + Some of the given report files did not correspond to any trace files. This happens + when given a set of reports files and trace files, the tool(covparser or timeparser), is + unable to find ipoints in any of the trace files that match to a reports corresponding + root ipoint(s). + + Elimination: This warning may be eliminated by customizing the integration so that + only relevant files are generated. + + Justification: This warning may be ignored if the set of generated report and trace + files varies depending on what was encountered during testing, and the set of files + to process has to be explicitly enumerated in the integration. + Warning W61032: No ipoints in any of the input trace files correspond to + the following report files:test.rvd, test2.rvd, report.rvd + + +3.2.3 W62xxx - EXF files + W62001 + + A backup of the EXF file has been restored. + + Elimination: Do not use option -j of the instrumenter. + + Justification: This warning can be ignored if the correct numbering of Ipoints is + checked after instrumentation. + Warning W62001: Restored backup exf file 'file.exf.bak'. + + + W62002 + + An invalid EXF file was deleted. + + Elimination: Do not use option -j of the instrumenter. + + Justification: This warning can be ignored if the correct numbering of Ipoints is + checked after instrumentation. + Warning W62002: Deleted invalid backup exf file 'file.exf'. + + + W40001 + + A configuration option for a filter was used more than once within the filter file(s). + Only the final usage of the option has an effect. + + Elimination: Make sure that this option only appears once within the filter file. + + Justification: This warning can be ignored if you are intentionally overriding an + earlier configuration option. + + +RVS Troubleshooting Guide vWF20190404 143 +Warnings RVS User Messages + + file.ext:42:Warning W40001: The 'read' filter configuration option + 'skip_bytes' is used more than once. Only the final usage of this + option has an effect. + + + W40002 + + A filter configuration option was specified without giving the name of the filter to + be reconfigured. This is now deprecated. + + Elimination: Filter configuration options should be stated in the form .