1 Reading Samples

This guide provides a comprehensive overview of reading signal data within the impulse framework. The framework offers a rich hierarchy of interfaces designed for efficient and flexible data access, ranging from simple value retrieval to complex structural analysis.

Introduction to Signals in impulse

Signals are a core concept in the impulse framework, representing data streams that can be analyzed, visualized, and processed. In the context of the impulse Viewer, signals exist within records, which are hierarchical structures that organize related signals and provide context for their interpretation.

A record primarily consists of signals and scopes (containers that organize signals into a structured hierarchy), but can also include other elements like proxies (references to signals), relations (connections between elements), and active record elements such as includes, analysis components, and interfaces to external sources.

When working with signals, understanding their structure, metadata, and the methods for accessing their data is essential for effective analysis and processing. Whether you're examining waveform files, log files, trace files, or combined data sources, the interfaces described in this guide provide the foundation for extracting meaningful information from signal data.

Core Reading Interfaces

• IReadableSamples: The primary interface for accessing signal data, providing methods to retrieve samples, navigate through the signal, and access metadata.
• IReadableValue: Provides access to a single value with formatting and type conversion capabilities.
• IReadableSample: Represents a complete sample with both value and metadata.
• IReadableGroup: Represents a group of related samples as a single logical unit.
• IReadableMembers: Provides access to structured data with named or indexed members.

Sample Definition Interfaces

• ISample: Defines the fundamental constants, data types, and encoding formats for samples. This interface provides the core specifications for sample representation, including byte-level format details, data type definitions, and constants for flags and masks.
• ISamples: Serves as the foundation for all signal sample collections, integrating various aspects of sample management like characteristics, validation, and events. This interface acts as a common base that is extended by both reading and writing interfaces.

Characteristic Interfaces

• ISampleCharacteristic: Defines the essential properties of an individual sample, including its type, format, scale, and tags. This interface focuses on metadata that describes how sample data should be interpreted.
• ISamplesCharacteristic: Provides metadata for an entire collection of samples, including domain information, continuity, and release status. This interface is useful for understanding the nature of a signal without accessing individual values.

Understanding Signal and Sample Characteristics

Before diving into the details of accessing and manipulating samples, it's important to understand the fundamental characteristics of signals and samples in the impulse framework.

Signals are much more than simple data arrays—they are rich data structures with metadata, contextual information, and complex behaviors that enable sophisticated analysis and visualization. A signal in impulse represents a sequence of samples organized along a domain (typically time), with each sample containing a value of a specific type plus optional metadata such as tags and attachments.

Signal Structure

A signal in impulse can contain up to 2^31 samples, with the following key attributes:

• Name: A unique identifier for distinguishing the signal from others.
• Description: Detailed comments or notes that provide additional context about the signal.
• Process Type: Defines whether the signal is discrete or continuous.
• Signal Type: Categorizes the signal based on its data type.
• Tags: Provides metadata for context and categorization, such as "default", "state", "event", "transaction", "log", "chart", or "image".
• Scale: Represents the dimension of the signal (bit width, array size, etc.).
• Format Specifier: Defines how the signal's values are represented textually, such as binary, hexadecimal, or decimal.
• Domain Base: Defines the minimum distance between samples (e.g., nanoseconds, picoseconds).
• Start and End: Marks the beginning and end positions of the signal.
• Rate: Defines the sampling rate (for continuous signals).
• Attachments: Additional context like relations (links between samples in different signals) or labels (textual annotations).

Through the Signal dialog in the impulse Viewer, users can view and modify signal properties such as name, description, tags, and more, while also examining the signal's technical properties and raw sample data.

Process Types

The process type of a signal is a fundamental characteristic that determines how samples are distributed along the domain and how position information is stored and interpreted. The impulse framework supports two types of signals:

• Discrete Signals: Have samples at irregular, event-based intervals. Each sample contains its own position information as a delta from its predecessor. Samples can occur at any domain position, with the restriction that positions must be non-decreasing. This process type is particularly useful for event-driven data where samples occur at significant moments rather than at regular intervals.

// Check if a signal is discrete
boolean isDiscrete = !samples.isContinuous();

// For discrete signals, get the position of each sample individually
DomainLongValue pos = samples.positionAt(index);

• Continuous Signals: Have samples at regular intervals based on a fixed sampling rate. The position of each sample can be calculated from the start position and rate.

// Check if a signal is continuous
boolean isContinuous = samples.isContinuous();

// For continuous signals, get the sampling rate
DomainLongValue samplingRate = samples.getRate();

Method Descriptions:

Signal Types

The signal type is a critical characteristic that defines the nature of the data represented by the signal and determines how samples should be interpreted and processed. The impulse framework supports several signal types to represent different kinds of data:

• Logic: Digital signals with 1 to N bits, representing binary states (0, 1, Z, X, etc.). These can be stored as 2-state, 4-state, or 16-state data, making them suitable for representing binary states in digital circuits.
• Float: Floating-point values, typically used for analog measurements, sensor readings, or mathematical computations. These can be 32-bit or 64-bit precision values.
• Integer: Whole numbers of any length, used for counters, IDs, or any data requiring precise integer values without fractional components.
• Enumeration: Named values with associated numeric representations, ideal for states or categories (e.g., "ON", "OFF", "IDLE"). Enumerations provide human-readable labels for numeric values.
• Text: String data, useful for labels, descriptions, or any text-based information that needs to be recorded in the signal.
• Array: Collections of elements of a specific type, such as Text, Binary, Integer, Float, or Enumeration. Arrays are useful for structured data like matrices or lists.
• Structure: Complex data types with named members of various types. Each member can be of type Text, Binary, Integer, Float, Enumeration, or Arrays. Structures are particularly useful for logs, transactions, charts, Gantt events, and other complex data representations.
• Binary: Raw binary data like images, files, or other non-textual data. This type is useful for handling data that doesn't fit into the other categories.

// Get the signal type
int type = samples.getSampleType();

// Check for specific types
if (type == ISample.TYPE_LOGIC) {
    // Logic signal handling
} else if (type == ISample.TYPE_FLOAT) {
    // Float signal handling
} else if (type == ISample.TYPE_STRUCT) {
    // Structured data handling
}

Method Descriptions:

Signal Scale

The scale attribute has different meanings depending on the signal type:

• For Logic Signals: Represents the bit width (e.g., 1 for a single bit, 8 for a byte).
• For Numeric Signals: Can represent precision.
• For Arrays: Indicates dimensions.

// Get the scale of a signal
int scale = samples.getScale();

Method Descriptions:

Signal Domain

Every signal has a domain that defines the independent variable, typically time. The domain base establishes the unit of measurement and context for positions within the signal:

// Get the domain base
IDomainBase domain = samples.getDomainBase();

// Get domain range
DomainLongValue start = samples.getStart();
DomainLongValue end = samples.getEnd();

Method Descriptions:

Understanding getStart() vs getStartAsMultiple() (and the same for getEnd, getRate)

The impulse framework provides multiple methods for accessing domain positions:

// Get the start position as a DomainValue object
DomainLongValue start = samples.getStart();
System.out.println("Start position: " + start.toString());  // e.g., "10 ns"

// Get the start position as a raw numeric multiple
long startMultiple = samples.getStartAsMultiple();
System.out.println("Start position multiple: " + startMultiple);  // e.g., 10

// The difference:
// - getStart() returns a full DomainValue object with unit context
// - getStartAsMultiple() returns just the numeric value without unit context

Method Descriptions:

The getStart() method returns a complete DomainValue object that knows about its domain base and can perform unit conversions, while getStartAsMultiple() returns just the raw numeric value (the "multiple" of the base unit).

Working with DomainValue

The DomainValue class is crucial for handling positions and intervals in signal processing. It provides rich functionality for unit conversion, mathematical operations, and formatting:

// Creating domain values
DomainValue timeValue = DomainValue.parse("Time", "10ns");  // From domain class and string
DomainValue freqValue = DomainValue.parse("2.5MHz");        // From string with auto-detection
DomainValue customValue = DomainValue.valueOf(domain, 42);  // From domain base and multiple

// Converting between units
DomainValue microseconds = timeValue.convertTo(TimeBase.us);
System.out.println(timeValue + " = " + microseconds);  // "10 ns = 0.01 μs"

// Accessing the numeric value in different forms
long longVal = timeValue.longMultiple();       // As long
double doubleVal = timeValue.doubleMultiple(); // As double
BigDecimal bigVal = timeValue.bigMultiple();   // As BigDecimal

// Mathematical operations
DomainValue sum = timeValue.add(DomainValue.parse("5ns"));        // 15 ns
DomainValue diff = timeValue.sub(DomainValue.parse("2ns"));       // 8 ns
DomainValue doubled = timeValue.mul(2);                           // 20 ns
DomainValue scaled = timeValue.div(4);                            // 2.5 ns
Number ratio = timeValue.div(DomainValue.parse("2ns"), false);    // 5.0 (unitless)

// Comparing domain values
boolean isLess = timeValue.lt(DomainValue.parse("20ns"));         // true
boolean isGreater = timeValue.gt(DomainValue.parse("5ns"));       // true
boolean isEqual = timeValue.eq(DomainValue.parse("10ns"));        // true

// Formatting options
String defaultFormat = timeValue.toString();                     // "10 ns"
String withStyle = timeValue.toString(IDomainBase.STYLE_AUTO_UNIT);  // "10 ns"

Method Descriptions:

Unit Conversion with DomainValue

The DomainValue class provides several methods for unit conversion:

// Converting an entire DomainValue to another base
DomainValue nsValue = DomainValue.parse("1μs");
DomainValue psValue = nsValue.convertTo(TimeBase.ps);
System.out.println(nsValue + " = " + psValue);  // "1 μs = 1000000 ps"

// Converting just the numeric component between bases
Number psNumber = nsValue.convertMultipleTo(TimeBase.ps, IDomainBase.CONVERT_ANY);
System.out.println("In picoseconds: " + psNumber);  // 1000000

// Conversion with explicit result type
double psDouble = nsValue.convertMultipleToDouble(TimeBase.ps, IDomainBase.CONVERT_ANY, 0.0);
long psLong = nsValue.convertMultipleToLong(TimeBase.ps, IDomainBase.CONVERT_ANY, 0);

Method Descriptions:

By understanding these domain value operations, you can effectively work with signal positions, calculate intervals, and perform meaningful comparisons across different units and scales.

Sample Structure

Each sample in a signal has several key attributes:

• Value: The actual data of the sample, which can be of any supported signal type.
• Position: The location of the sample in the signal's domain.
• Tag: Optional metadata that can mark samples as special or provide additional context.

// Check if a sample is tagged
boolean isTagged = samples.isTaggedAt(index);

// Get the position of a sample
DomainLongValue position = samples.positionAt(index);

// Get the value of a sample (generic object)
Object value = samples.valueAt(index);

Method Descriptions:

Sample Groups and Layers

Samples can be organized into logical groups and layers, which is particularly useful for representing transactions or multi-stage processes:

// Check if a signal has groups
boolean hasGroups = samples.getGroups() > 0;

// Get the group a sample belongs to
int groupIndex = samples.groupAt(sampleIndex);

// Get the layer of a sample
int layer = samples.layerAt(sampleIndex);

// Get sample order within its group
int order = samples.orderAt(sampleIndex);
if (order == ISample.GO_INITIAL) {
    // First sample in a group
} else if (order == ISample.GO_FINAL) {
    // Last sample in a group
} else if (order == ISample.GO_INTER) {
    // Intermediate sample in a group
} else if (order == ISample.GO_SINGLE) {
    // Single-sample group
}

Method Descriptions:

Sample Attachments

Samples can have attachments that provide additional context:

• Relations: Create links between samples in different signals.
• Labels: Add textual or symbolic annotations to samples.

// Get attachments for a sample
List attachments = samples.attachmentsAt(sampleIndex);

// Get specific types of attachments
List relations = samples.attachmentsAt(sampleIndex, ISample.AT_RELATION);
List labels = samples.attachmentsAt(sampleIndex, ISample.AT_LABEL);

// Get attachments for a group
List groupAttachments = samples.attachmentsAtGroup(groupIdx);

Method Descriptions:

Accessing Signal Samples

The impulse framework provides a rich set of methods for accessing and navigating through signal data. Whether you need to retrieve individual samples, find samples at specific positions, or work with collections of related samples, the framework offers intuitive interfaces for these operations.

When working with signal data, you often need to:

• Navigate through samples sequentially
• Find samples at particular domain positions
• Extract values in appropriate types
• Handle different signal types consistently

The IReadableSamples interface serves as the foundation for these operations, providing methods that abstract away the complexity of the underlying data formats and access patterns. This makes it possible to write code that works seamlessly across different signal types and sources.

Reading Individual Samples

The IReadableSamples interface provides several methods to access individual samples:

// Get the number of samples in the signal
int count = samples.getCount();

// Access sample value at a specific index
Object value = samples.valueAt(10);

// Check if a sample is tagged
boolean isTagged = samples.isTaggedAt(5);

// Get a complete sample representation
IReadableSample sample = samples.compoundAt(3);

Method Descriptions:

Finding Samples by Position

To locate samples at specific domain positions:

// Find the sample index at a specific position (in multiple of the domain base)
int index = samples.indexAt(1000); 

// Get the position of a sample
DomainLongValue position = samples.positionAt(index);
String formatted = position.toString();  // e.g., "1.0 ms"

// Get the position as a raw multiple (without domain base information)
long positionMultiple = samples.multPosAt(index);

Method Descriptions:

Working with Sample Values

Signal values can represent a wide variety of data types, from simple binary states to complex structured data. The impulse framework provides type-specific methods that allow you to work with each data type in its natural form, without having to worry about the underlying representation or conversion details.

This approach simplifies application code by providing direct access to values in their appropriate data types. Whether you're working with digital waveforms, analog measurements, text logs, or complex data structures, you can use consistent patterns to access and manipulate the data.

The framework also provides comprehensive formatting capabilities that enable you to convert values into human-readable string representations suitable for UI display, logging, or analysis.

Type-Specific Value Access

The framework provides methods for accessing values in their appropriate types:

// For digital/logic signals
Logic logic = samples.logicValueAt(index);
boolean isHigh = samples.isHighAt(index);
boolean isLow = samples.isLowAt(index);

// For numeric signals
double doubleVal = samples.doubleValueAt(index);
long longVal = samples.longValueAt(index);
int intVal = samples.intValueAt(index);

// For text signals
String textVal = samples.stringValueAt(index);

// For enum signals
Enumeration enumVal = samples.enumValueAt(index);

// For binary data
byte[] binaryData = samples.bytesValueAt(index);

// For structured data
Struct structData = samples.structValueAt(index);

Method Descriptions:

Formatting Values

For formatted string representations of values:

// Format using a specific format
String hexString = samples.formatAt(index, "hex");
String binaryString = samples.formatAt(index, "bin");
String decimalString = samples.formatAt(index, "dec");

// Convenience formatting methods
String hex = samples.fhexAt(index);
String dec = samples.fdecAt(index);
String bin = samples.fbinAt(index);
String ascii = samples.fasciiAt(index);
String oct = samples.foctAt(index);

// Get the default format for a sample
String defaultFormat = samples.defaultFormatAt(index);

Method Descriptions:

Working with Logic States

For digital/logic signals, specialized methods are available:

// Check for edges (transitions)
boolean isRisingEdge = samples.isEdgeAt(index, 1);
boolean isFallingEdge = samples.isEdgeAt(index, -1);
boolean isAnyEdge = samples.isEdgeAt(index, 0);

// Get detailed logic state
int logicState = samples.logicStateAt(index);
switch (logicState) {
    case ISample.STATE_0_BITS:  // Logic 0
        // Handle logic 0
        break;
    case ISample.STATE_1_BITS:  // Logic 1
        // Handle logic 1
        break;
    case ISample.STATE_Z_BITS:  // High impedance
        // Handle high-Z state
        break;
    // Other states: X, L, H, U, W, etc.
}

Method Descriptions:

Working with Structured Data

Structured data represents complex information models with named fields or members, similar to structs in C/C++ or objects in higher-level languages. In the impulse framework, structured signals can represent logs, transactions, events, and other complex data types that go beyond simple scalar values.

The key advantage of structured data is the ability to maintain relationships between related pieces of information while preserving their individual semantics. For example, a transaction event might include fields for a transaction ID, timestamp, status code, and message text. With structured data, all these fields remain accessible individually while still being treated as a cohesive unit.

The framework provides interfaces like IReadableMembers that allow you to:

• Access individual members by name or index
• Retrieve type-appropriate values for each member
• Format members according to their specific requirements
• Explore the structure of complex data types
• Apply consistent operations across different structured data models

Working with structured data effectively is especially important for analyzing complex systems, where the relationships between different pieces of information are as important as the individual values themselves.

Accessing Struct Members

For structured data types, you can access individual members:

// Get a structured sample
IReadableSample sample = samples.compoundAt(index);

// Using IReadableMembers interface
double numericField = sample.doubleValueOf("fieldName");
String textField = sample.stringValueOf("anotherField");
boolean boolField = sample.booleanValueOf("flagField");

Method Descriptions:

Formatting Struct Members

Format individual members for display:

// Format a member using a specific format
String formattedValue = sample.formatOf("address", "hex");

// Convenience formatting methods for members
String hexField = sample.fhexOf("address");
String decField = sample.fdecOf("count");
String binField = sample.fbinOf("flags");

Method Descriptions:

Working with Member Descriptors

Explore the structure of complex data types:

// Get all member descriptors for a signal
List allMembers = samples.getMemberDescriptors();

// Get a specific member descriptor
IMemberDescriptor memberDesc = samples.getMemberDescriptor("fieldName");
// or by ID
IMemberDescriptor memberById = samples.getMemberDescriptor(42);

// Get information about the member
String name = memberDesc.getName();
String path = memberDesc.getPath();
int type = memberDesc.getType();
String format = memberDesc.getFormat();

// Find members with specific tags
List criticalMembers = samples.getMembersForTag("critical");

Method Descriptions:

Working with Attachments

Attachments in the impulse framework provide a powerful mechanism for adding context, metadata, and relationships to signal samples. Unlike the core sample data that represents the primary measurements or states, attachments represent secondary information that enhances the interpretation and analysis of the signal data.

There are two primary types of attachments supported by the framework:

Relations: Create links between samples in different signals, allowing you to establish cause-and-effect relationships, hierarchical connections, or any other association between signals. Relations are particularly valuable for:

• Tracing the flow of data through a system
• Connecting requests with their corresponding responses
• Establishing parent-child relationships between events
• Creating visual connections between related signals in the UI

Labels: Add textual or symbolic annotations to specific samples, providing additional descriptive information, commentary, or categorization. Labels are useful for:

• Marking significant events or anomalies
• Adding human-readable explanations to complex patterns
• Creating markers for navigation or reference
• Highlighting samples that meet specific criteria

Attachments can be associated with individual samples or with entire groups of samples, making them extremely flexible for different analysis scenarios. The ability to attach contextual information to signals without modifying the underlying data makes it possible to layer multiple interpretations onto the same signal data.

Retrieving Attachments

Attachments provide additional context for samples and groups:

// Get all attachments for a sample
List attachments = samples.attachmentsAt(sampleIndex);

// Get attachments of a specific type
List relations = samples.attachmentsAt(sampleIndex, ISample.AT_RELATION);
List labels = samples.attachmentsAt(sampleIndex, ISample.AT_LABEL);

// Get attachments for a group
List groupAttachments = samples.attachmentsAtGroup(groupIdx);

Method Descriptions:

Working with Specific Attachment Types

Different attachment types serve different purposes and provide different information:

// Process relations (links between samples/signals)
for (IAttachment attachment : relations) {
    if (attachment instanceof IAttachment.IAttachedRelation) {
        IAttachment.IAttachedRelation relation = (IAttachment.IAttachedRelation) attachment;
        
        // Access relationship information
        String targetId = relation.getTargetId();
        String style = relation.getStyle();
        
        // Get positions
        DomainValue sourcePos = relation.getSourcePosition();
        DomainValue targetPos = relation.getTargetPosition();
        DomainValue absoluteTargetPos = relation.getAbsoluteTargetPosition();
        
        // Check relationship properties
        boolean isReverse = relation.isReverse();
        boolean isDelta = relation.isDelta();
       
    }
}

// Process labels (textual annotations)
for (IAttachment attachment : labels) {
    if (attachment instanceof IAttachment.IAttachedLabel) {
        IAttachment.IAttachedLabel label = (IAttachment.IAttachedLabel) attachment;
        
        // Access label information
        String message = label.getMessage();
        String style = label.getStyle();
        
        // Get label position
        DomainValue position = label.getSourcePosition();       
    }
}

Method Descriptions:

Working with Enumerations

Enumerations are a powerful feature in the impulse framework that provide a mapping between numeric values and meaningful textual labels. This mapping creates a layer of abstraction that makes signals more intuitive to work with and analyze, especially when dealing with state-based or categorical data.

In many digital systems, states and modes are represented internally as numeric values (like 0, 1, 2, etc.), but these values have specific semantic meanings in the context of the system (like "IDLE", "RUNNING", "ERROR"). Enumerations bridge this gap by maintaining both the efficient numeric representation and the human-readable label.

The benefits of enumerations include:

1. Improved Readability: Instead of cryptic numeric codes, signals display meaningful state names.
2. Consistent Interpretation: Ensures that everyone analyzing the data uses the same terminology.
3. Simplified Filtering: Makes it easier to search for specific states or transitions.
4. Enhanced Visualization: Enables color-coding and styling based on state values.
5. Domain Context Preservation: Maintains the original design terminology from the system being analyzed.

Enumerations can be global (applicable to multiple signals) or local to specific struct members, providing flexibility in how they're applied across a record. They're particularly valuable when analyzing protocols, state machines, or any system with discrete operational modes.

// Get all enumerations of a specific type

// Get all enumerations of a specific type
List globalEnums = samples.getEnums(ISample.ENUM_GLOBAL);
List relationTargets = samples.getEnums(ISample.ENUM_RELATION_TARGET);
List relationStyles = samples.getEnums(ISample.ENUM_RELATION_STYLE);

// Get enumerations for a specific member
List memberEnums = samples.getMemberEnums("stateField");

// Look up an enumeration by label
Enumeration runningEnum = samples.getMemberEnum("stateField", "RUNNING");

// Look up an enumeration by value
Enumeration stateOne = samples.getMemberEnum("stateField", 1);

Method Descriptions:

Conclusion

The impulse framework provides a comprehensive set of interfaces and methods for working with signal data, enabling developers to efficiently extract, analyze, and visualize information from complex signals. By understanding the concepts and techniques covered in this guide, you can build powerful applications that leverage the full capabilities of the impulse signal processing ecosystem.

Key takeaways from this guide include:

1. Rich Data Representation: Signals in impulse are much more than simple arrays of values; they include metadata, domain context, and structural information that enables sophisticated analysis.
2. Type-Specific Access: The framework provides specialized methods for working with each signal type, making it easy to handle anything from simple binary logic to complex structured data.
3. Domain Context: All position and interval information maintains its connection to the underlying domain (like time or frequency), ensuring accurate calculations and meaningful comparisons.
4. Structural Analysis: For complex data types, the framework offers powerful interfaces for exploring and navigating structure layouts and accessing nested information.
5. Contextual Attachments: Relations and labels provide additional layers of meaning and connection that enhance the interpretability of signal data.
6. Flexible Formatting: Comprehensive formatting capabilities make it easy to convert raw values into human-readable representations suitable for different analysis contexts.

Whether you're building tools for semiconductor debugging, communications protocol analysis, sensor data processing, or any other signal-focused application, the impulse reading interfaces provide a solid foundation for your development efforts. By leveraging the appropriate interfaces and methods for your specific use case, you can create efficient, maintainable code that delivers powerful analysis capabilities.

For more information about working with samples, refer to:

• Reading: Iterating Samples
• Writing: Writing Samples and Building Records