Fábio Coutada
ebcfde0f5e
- 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
73 KiB
| title | source | category | pages | extracted |
|---|---|---|---|---|
| Migration Guide | ./src/scov/RVS/doc/Migration_Guide.pdf | src/scov/RVS/doc | 38 | 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
-
RVS versions .................................................................... 5
-
General migration considerations ..................................... 6
-
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
-
Migrating from RapiTest v1.4a ......................................... 11 4.1. Changed features ............................................................... 11
-
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
- 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
-
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 (<n>.0 - for example 3.0). These releases contain significant
new functionality and may have considerable changes from previous versions.
• Minor release (<n>.<m> - for example 3.6). These releases contain new
tools and features but the behavior remains broadly the same as the previous
version.
• Incremental release (<n>.<m><x> - 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_<integration_name> 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:
<projectfolder>/RVS_<projectname>/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 <projectfolder>/rvs_<projectname>, 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:
<projectfolder>/rvs_<projectname>/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:
<projectfolder>/rvs_<projectname>/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
<project RVS folder>/config/<tool>.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