1. GNATcoverage User’s Guide

• 1.1. Getting Started
  • 1.1.1. Framework concepts and process overview
  • 1.1.2. Selecting a trace mode; supported features and environments
  • 1.1.3. A brief introduction to the main process steps
    • 1.1.3.1. Example production of a binary trace for a bareboard environment
    • 1.1.3.2. Example production of a source trace for a native environment
    • 1.1.3.3. Example production of a coverage report
  • 1.1.4. Going Further
  • 1.1.5. Conventions used in the rest of this manual
• 1.2. Specifying Units Of Interest
  • 1.2.1. Providing coverage obligation files (--scos|--sid)
  • 1.2.2. Using project files (-P, --projects, --units)
    • 1.2.2.1. Conveying projects of interest
    • 1.2.2.2. Conveying units of interest within projects
    • 1.2.2.3. Other switches or attributes of importance
  • 1.2.3. Conveying source files to ignore / handling Ada subunits
  • 1.2.4. Compilation unit vs source file names
• 1.3. Producing binary traces with gnatcov run
  • 1.3.1. Compilation prerequisites
  • 1.3.2. gnatcov run command line
  • 1.3.3. Execution environment
  • 1.3.4. Program selection and Arguments passing
  • 1.3.5. Trace file contents
• 1.4. Producing source traces with gnatcov instrument
  • 1.4.1. Setting up the coverage runtime library
  • 1.4.2. Instrumenting programs
    • 1.4.2.1. gnatcov instrument command line
    • 1.4.2.2. Output strategies for main units
    • 1.4.2.3. Controlling trace file names
    • 1.4.2.4. gnatcov instrument limitations
  • 1.4.3. Building instrumented components
  • 1.4.4. Extracting a trace from standard output
  • 1.4.5. Composed instrumentation
  • 1.4.6. Instrumentation of a multi-languages project
  • 1.4.7. Instrumentation and coverage of SPARK code
    • 1.4.7.1. Inhibiting SPARK related pragmas
    • 1.4.7.2. Coverage obligations for SPARK code
  • 1.4.8. Example use cases
    • 1.4.8.1. Whole program instrumented at once, cross configuration, base64 output
    • 1.4.8.2. Library instrumented separately, native configuration, trace output
• 1.5. Source coverage analysis with gnatcov coverage
  • 1.5.1. gnatcov coverage command line
  • 1.5.2. Output report formats (--annotate)
    • 1.5.2.1. Annotated sources, text (=xcov[+])
    • 1.5.2.2. Annotated sources, html (=html[+])
    • 1.5.2.3. Annotated sources, dynamic html (=dhtml)
    • 1.5.2.4. Violations summary, text (=report)
  • 1.5.3. Statement Coverage analysis
    • 1.5.3.1. Core notions and Reporting (--level=stmt)
    • 1.5.3.2. Example program and assessments
  • 1.5.4. Decision Coverage analysis
    • 1.5.4.1. Core notions and Reporting (--level=stmt+decision)
    • 1.5.4.2. Example program and assessments
  • 1.5.5. Modified Condition/Decision Coverage analysis
    • 1.5.5.1. Core notions and Reporting (--level=stmt+mcdc)
    • 1.5.5.2. Example decisions and conditions
    • 1.5.5.3. Handling non short-circuit operators
    • 1.5.5.4. MCDC variants
    • 1.5.5.5. Example program and assessments
  • 1.5.6. Synthetic metrics
  • 1.5.7. Handling source relocation for annotated sources output formats
  • 1.5.8. Inlining & Ada generic units
    • 1.5.8.1. Combined coverage on generics (default behavior)
    • 1.5.8.2. Separated coverage on generics
  • 1.5.9. Handling Ada assertions and contracts
  • 1.5.10. Processing of C macros
  • 1.5.11. Optimization and non-coverable items
• 1.6. Object coverage analysis with gnatcov coverage
  • 1.6.1. gnatcov coverage command line
  • 1.6.2. Output report formats (--annotate)
    • 1.6.2.1. Machine level reports (=asm)
    • 1.6.2.2. Annotated sources, text (=xcov[+])
    • 1.6.2.3. Annotated sources, html (=html[+]) or dynamic html (=dhtml)
  • 1.6.3. Object Instruction Coverage analysis (--level=insn)
  • 1.6.4. Object Branch Coverage analysis (--level=branch)
  • 1.6.5. Focusing on subprograms of interest (--routines)
  • 1.6.6. Inlining & Ada Generic units
  • 1.6.7. Full object coverage considerations
• 1.7. Object/Source level metrics considerations
  • 1.7.1. Main differences examplified
  • 1.7.2. Full branch coverage vs MCDC
• 1.8. Coverage Consolidation
  • 1.8.1. Consolidation from trace files
    • 1.8.1.1. Single unit tested by different programs
    • 1.8.1.2. Disjoint units tested by different programs
    • 1.8.1.3. Multiple executions of a single program
    • 1.8.1.4. Special care needed with binary traces
  • 1.8.2. Consolidation from coverage checkpoints
    • 1.8.2.1. Efficient storage of test results
    • 1.8.2.2. Incremental coverage analysis
    • 1.8.2.3. Handle incidental coverage effects
    • 1.8.2.4. Compatibility considerations
• 1.9. Coverage Exemptions
  • 1.9.1. Defining Exemption Regions
  • 1.9.2. Reporting about coverage exemptions
  • 1.9.3. Object coverage exemptions
• 1.10. Using project files
  • 1.10.1. General considerations
  • 1.10.2. Specifying gnatcov command Switches
  • 1.10.3. Specifying the Target and language Runtime
• 1.11. Importing binary traces with gnatcov convert
  • 1.11.1. gnatcov convert command line
  • 1.11.2. Generating Coverage Information from Nexus Traces on MPC5634M
    • 1.11.2.1. Nexus Program Trace Data: the Hardware Perspective
    • 1.11.2.2. Configuring the winIDEA Analyzer
    • 1.11.2.3. Exporting the Trace Data
  • 1.11.3. Generating Coverage Information from Lauterbach Trace32
    • 1.11.3.1. Enabling Trace Data
    • 1.11.3.2. Running the executable
    • 1.11.3.3. Exporting the Trace Data
    • 1.11.3.4. Automation
• 1.12. Using GNATcoverage from GNAT Studio
  • 1.12.1. Basic usage
  • 1.12.2. Binary traces usage
  • 1.12.3. GNATtest scenario
• 1.13. Appendices
  • 1.13.1. Sample html index
  • 1.13.2. Sample html annotated source
  • 1.13.3. Target specific points of note with Binary traces
  • 1.13.4. Known Limitations with Binary traces
    • 1.13.4.1. Incomplete statement coverage on lines with multiple statements
    • 1.13.4.2. MCDC inaccuracies with interrupts and multi-threaded applications
• 1.14. Glossary of terms & concepts