J001 Creating records

Content outdated

We are in the process of migrating all content to impulse version 2.0.

If you develop a reader, a recJs script or are simple Signal Script production, impulse provides you always the same interfaces to simply create records, scopes and signals.


Screen Cast: J01 Creating records


Independent from its source and type, impulse organizes all signal data by using these elements:

  • Record: The top-level element, usually the content of a file, or the resulting input of a port.  
  • Scope: An organization element (like a folder) to group signals.  
  • Signal: An indexed sequence of signal samples (containing values of different type), organized along a domain base (e.g. time).  
  • Proxy: A signal that contains the identical content of a another signal, and therefore contains only a link to that signal (wave file often contains identical signals).
See 02 Signal Basics for more about signals.


Record generator

The record generator help you to prepare a record with all its contents. If you create a reader, your class will be derived from IRecordGenerator, if you are working with recJs scripts or a scripted reader, a IRecordGenerator variable (generator) will be provided. The "Signal Script" production does not require to use a record generator, as the signal and reader setup is done internally.

To create a record , the following steps are required:

  • Initialize the record
  • Add the record content (scopes, signals and proxies)
  • Acquire writers for the signals you want to fill
    •     Open the writer
    •     Write samples
    •     Close the writer
The ISingleDomainRecordGenerator interface provides a more comfortable interface when using records with only 1 domain base. Open JavaDoc Reference

Experimenting with records

If you want to experiment with records and signals, just create a file/resource with file ending "recJs" (e.g. my_wave.recJs) and put the following text into the header of the file ("//-recjs" is important to get the file identified) :

//-recjs (keep this line)
// Vars:
// * generator of ISingleDomainRecordGenerator
//
void initRecord(String name);
....

Add your code below and open with impulse.


Record initialization

The initialization provides the record with a name and in case of ISingleDomainRecordGenerator also with a domain base:

  • name: to be used as record name.
  • domainBase: Domain base in case of multi domain record (e.g. TimeBase.ms).

Interface

void initRecord(String name);
    
// ISingleDomainRecordGenerator only
void initRecord(String name, IDomainBase domainBase); 

Examples

// Java (reader derived from IRecordGenerator, ISingleDomainRecordGenerator)
initRecord("Example Record");
initRecord("Example Record",TimeBase.ns);
// JavaScript (recJs, scripted reader,..)
generator.initRecord("Example Record");
generator.initRecord("Example Record",TimeBase.ns);

Adding scopes

Scopes let you organize your signals within a hierarchy. To add a scope you need a container (or null for the root), a name and optionally a description.

  • container: Parent of new scope, or null (for root).
  • name: Name of the new scope.
  • description: Scope description (just comments).

Interface

Scope addScope(ICell container, String name);
Scope addScope(ICell container, String name, String description);

Examples

// Java (reader derived from IRecordGenerator, ISingleDomainRecordGenerator)
addScope(null, "External Signals");
addScope(null, "External Signals","Just for this");
// JavaScript (recJs, scripted reader,..)
generator.addScope(null, "External Signals");
generator.addScope(null, "External Signals","Just for this");

Defining signals

After defining a signal, you can create a writer to add samples. To define a signal you need a signal and process type. The signal type defines the data type of a signal (text, integer, float, ...). The process type defines how the samples are organized on the domain (Discrete: at any position; Continuous: at fixed positions with equal distance).
impulse supports the following signal types:

  • Logic (1..N bits — the bits are stored as 2-state, 4-state or 16-state data (usually nine states are used).
  • Float (32-bit or 64-bit), Float arrays
  • Integer (any length), Integer arrays
  • Event (Enumeration), Event arrays
  • Text (any length), Text arrays
  • Structure (unlimited properties per structure: Text/Binary/Integer/Float/Enumeration)
  • Transaction Event (a group of structures — a transaction can consist of multiple events)
  • Binary (can contain images,… )

The signal descriptor contains additional information about the signal.
The domain of a signal may be Time,Frequency,Index,... . The domain base represents the the minimum distance between two samples (e.g. ns or ps).
If "createWriter" is set to true (the default value), a writer is generated in background.

  • container: Parent of new signal, or null (for root).
  • name: Name of the new signal.
  • description: Signal description (just comments).
  • processType: Discrete or Continuous process type (ProcessType. ...).
  • signalType: One of the defined signal types (SignalType. ...).
  • signalDescriptor: Extended definition of the signal type, usually set to SignalDescriptor.DEFAULT.
  • domainBase: Domain base in case of multi domain record, or null.
  • createWriter: Set to true to automatically create a writer

Interface

Signal addSignal(ICell container, String name, String description, 
    	ProcessType processType, SignalType signalType, 
    	SignalDescriptor signalDescriptor, IDomainBase domainBase);
Signal addSignal(ICell container, String name, String description, 
    	ProcessType processType, SignalType signalType, SignalDescriptor signalDescriptor, 
        IDomainBase domainBase, boolean createWriter));
    
// ISingleDomainRecordGenerator only
Signal addSignal(ICell container, String name, String description, 
    	ProcessType processType, SignalType signalType, 
        SignalDescriptor signalDescriptor);    

Examples

// Java (reader derived from IRecordGenerator, ISingleDomainRecordGenerator)
Scope signals = addScope(null, "External Signals");
Signal clk = addSignal(signals, "Clk", "", ProcessType.Discrete, 
    	SignalType.Logic, SignalDescriptor.DEFAULT);
// JavaScript (recJs, scripted reader,..)
var signals = generator.addScope(null, "External Signals");
var clk = generator.addSignal(signals, "Clk", "", 
    	ProcessType.Discrete, SignalType.Logic, SignalDescriptor.DEFAULT);

The signal descriptor

In above examples i used the default signal descriptor (SignalDescriptor.DEFAULT). You may use a dedicated signal descriptor:
  • to define the bits width of a logic signal.
  • to define the array size.
  • to set content information (e.g a binary content contains an image).
  • to define the accuracy of a signal (e.g. float 32/64)).
  • to set a format specifier (e.g. decimal, hex, ..)
public SignalDescriptor(String content, int scale0, int accuracy, int format);
Signal signal2 = addSignal(signals, "Integer3", "XY", 
	ProcessType.Discrete, SignalType.IntegerArray, 
    new SignalDescriptor(SignalDescriptor.CONTENT_DEFAULT,2,
    ISample.INTEGER_ACCURACY_DEFAULT,ISample.FORMAT_DEFAULT));
  • content: String describing the content (meaning/definition) of a signals (e.g. image (binary), transaction (struct),..).
  • scale0: Defines a type specific scale value (e.g. no of logic bits, dimension of float array).
  • accuracy: May define a type specific accuracy definition.
  • format: Defines the value rendering format (ISample.FORMAT_...).

Adding proxies

Proxies are signals that contains the identical content of a another signal. To create a proxy, you just need a container (or null for the root), a name, a descritpion (or null) and the referenced signal (must not be null).


Interface

	SignalProxy addSignalProxy(ICell container, String name, String description, Signal signal);

Examples

// Java (reader derived from IRecordGenerator, ISingleDomainRecordGenerator)
Signal clk = addSignal(signals, "Clk", "", 
    	ProcessType.Discrete, SignalType.Logic, SignalDescriptor.DEFAULT);
addSignalProxy(other, "External Signals","Just for this",clk);
// JavaScript (recJs, scripted reader,..)
var clk = generator.addSignal(signals, "Clk", "", 
    	ProcessType.Discrete, SignalType.Logic, SignalDescriptor.DEFAULT);
generator.addSignalProxy(other, "External Signals","Just for this",clk);
The next chapter ( J02 Using sample writers ) handles the writer creation and the steps of writing samples.


toem

technical software and tooling

Company

Contact Us

This email address is being protected from spambots. You need JavaScript enabled to view it.