CPPTracer - C++ Variable Tracer for VCD File Generation

cpptracer is a C++ library for tracing variable values and generating Value Change Dump (VCD) files. It allows you to track the changes of variables over time and output these changes in VCD format. The library supports hierarchical scoping of traces, compression of trace data, and fine-grained control over the sampling period and timescale.

Features

• Trace Variables: Trace changes to any variable in your program, including basic types, arrays, and more complex structures.
• Hierarchical Scoping: Organize traces in nested scopes, similar to how signals are grouped in VCD files.
• Compression: Enable optional compression for VCD files to save disk space.
• Custom Timescales and Sampling: Control the granularity of time and the sampling period of your traces.
• Automatic VCD Generation: Automatically output variable values in the VCD format, capturing their state at each timestep.

Installation

Clone the repository and include the necessary header files in your C++ project.

git clone https://github.com/Galfurian/cpptracer.git

You can then include the tracer.hpp header in your C++ project:

#include <cpptracer/tracer.hpp>

Example Usage

Here are some examples.

1. Minimal Example

Here’s a minimal example that demonstrates how to trace a simple variable and generate a VCD file.

#include <cpptracer/tracer.hpp>

int main()
{
    cpptracer::TimeScale timeStep(1, cpptracer::TimeUnit::SEC);
    int myVar = 42;

    cpptracer::Tracer tracer("minimal_trace.vcd", timeStep, "root");
    tracer.addTrace(myVar, "myVar");
    tracer.createTrace();

    for (double time = 0; time < 10; time += 1)
    {
        myVar = time * 2;
        tracer.updateTrace(time);
    }
    tracer.closeTrace();
    return 0;
}

2. Minimal Example with Compression

This example shows how to enable compression for the generated VCD trace.

#include <cpptracer/tracer.hpp>

int main()
{
    cpptracer::TimeScale timeStep(1, cpptracer::TimeUnit::SEC);
    int myVar = 42;

    cpptracer::Tracer tracer("compressed_trace.vcd", timeStep, "root");
    tracer.enableCompression();  // Enable compression
    tracer.addTrace(myVar, "myVar");
    tracer.createTrace();

    for (double time = 0; time < 10; time += 1)
    {
        myVar = time * 2;
        tracer.updateTrace(time);
    }
    tracer.closeTrace();
    return 0;
}

3. Minimal Example with Scopes

This example demonstrates how to organize traces using scopes.

#include <cpptracer/tracer.hpp>

int main()
{
    cpptracer::TimeScale timeStep(1, cpptracer::TimeUnit::SEC);
    int myVar1 = 42;
    int myVar2 = 84;
    int myVar3 = 12;

    cpptracer::Tracer tracer("scoped_trace.vcd", timeStep, "root");

    // Scope after: CPP/SCOPE1
    tracer.addScope("SCOPE1");
    tracer.addTrace(myVar1, "myVar1");

    // Scope after: CPP/SCOPE1/SUBSCOPE1
    tracer.addSubScope("SUBSCOPE1");
    tracer.addTrace(myVar2, "myVar2");
    tracer.closeScope(); // Closes CPP/SCOPE1/SUBSCOPE1.

    // Scope after: CPP/SCOPE2
    tracer.addScope("SCOPE2");
    tracer.addTrace(myVar3, "myVar3");

    // Scope after: CPP
    tracer.closeScope();

    tracer.createTrace();

    for (double time = 0; time < 10; time += 1)
    {
        myVar1 = time * 2;
        myVar2 = myVar1 * 2;
        tracer.updateTrace(time);
    }
    tracer.closeTrace();
    return 0;
}

Classes

Tracer

The main class used to manage traces and generate the VCD file.

• addTrace: Add a trace for a specific variable.
• addScope: Add a new scope to organize traces, it joints the other sibling scopes at the same level.
• addSubScope: Add a new sub-scope under the current scope.
• updateTrace: Update traces with the latest values at a specific time.
• closeTrace: Finalize the trace file and write to disk.
• enableCompression: Enable compression for the trace data.

Trace

The base class representing a traceable variable. This class is used to track changes in variable values.

• getVar: Get the $var representation for the trace.
• getValue: Get the current value of the trace.
• hasChanged: Check if the trace value has changed.
• updatePrevious: Update the previous value with the current value.

TraceWrapper

A template class that wraps a variable to be traced.

Contributing

Feel free to fork the repository, open issues, and submit pull requests. All contributions are welcome!

License

CPPTracer is released under MIT license.