E09 Adding struct signals

Struct signals can be used as logs, transaction, chart data, gant evetns, and ... .A struct event is a combination of key value pairs, with values of type string , integer, float and enum.


Struct Signals

Struct events can be grouped and layered. Grouping means that that all events of a group have the same group id and an order descriptor (first, intermediate {multiple, optional}, last). Layering means that each group (defined in the first event) has a layer id (0..255). This layer id is used to draw parallel transactions in raws.

Interface

This is the interface:

public interface IStructSamplesWriter extends ISamplesWriter{

    boolean write(long units, boolean conflict, int id, int order,int layer, StructMember[] value);
    boolean write(long units, boolean conflict,  StructMember[] value);

}	

The parameters have the following meaning:

units
No of domain units (e.g. ns)
conflict
Define this sample as a conflict one.
value
An array of StructMember
id
The group id. Must start at 0 (for the first group) to N (for the last group).
order
IStructSamplesWriter.GO_FIRST,IStructSamplesWriter.GO_INTER,IStructSamplesWriter.GO_LAST
layer
0 (first layer)..255.

Creating

Now take a look at some examples (out of de.toem.impulse.serializer.ExampleStructReaderReader):

        Scope signals = addScope(null, "Signals");
        Signal log1 = addSignal(signals, "Log", "A log signal", ProcessType.Discrete, 
                SignalType.Struct, SignalDescriptor.DEFAULT);
        Signal transaction1 = addSignal(signals, "Transaction", "A transaction signal", 
                ProcessType.Discrete, SignalType.Struct, new SignalDescriptor(
                SignalDescriptor.STRUCT_CONTENT_TRANSACTION,  ISample.FORMAT_DEFAULT));

To create a struct signal, you need to give the signal type SignalType.Struct and a signal descriptor with its content description (STRUCT_CONTENT_LOG,STRUCT_CONTENT_TRANSACTION,..).

Writing a simple struct signal (Logs)

Here an example how to write non-grouped struct samples.

        // log
        StructMember members[] = new StructMember[2];
        members[0] = new StructMember("Message", StructMember.STRUCT_TYPE_TEXT, 
                null, ISamples.FORMAT_DEFAULT);
        members[1] = new StructMember("Data", StructMember.STRUCT_TYPE_INTEGER, 
                null, ISamples.FORMAT_HEXADECIMAL);

        IStructSamplesWriter logWriter = (IStructSamplesWriter) getWriter(log1);

        members[0].setValue("Start");
        members[1].setValue(100);
        logWriter.write(100, false, members);

        members[0].setValue("Continue");
        members[1].setValue(500);
        logWriter.write(500, false, members);

Before using the writer interface, we must create the members.

    public StructMember(String name, int type, String content, int format);
name
Name of the member.
type
One of STRUCT_TYPE_TEXT,STRUCT_TYPE_ENUM,STRUCT_TYPE_LOCAL_ENUM,STRUCT_TYPE_INTEGER,STRUCT_TYPE_FLOAT,... (IStructSample).
STRUCT_TYPE_TEXT
Uses String values.
STRUCT_TYPE_ENUM
Global enums. Use String or Integer values.
STRUCT_TYPE_LOCAL_ENUM
Local enums (does not share with other members). Use String or Integer values.
STRUCT_TYPE_INTEGER
Use Long or Integer values.
STRUCT_TYPE_FLOAT
Use Float or Double values.
STRUCT_TYPE_BINARY
Use byte[] values.
content
Usually a diagram depended information, e.g. "STATE" and "EVENT" are used in Gant and Event diagrams, "LABEL" is used in charts.
format
One of FORMAT_NONE,FORMAT_BINARY,FORMAT_OCTAL,FORMAT_HEXADECIMAL,FORMAT_ASCII,FORMAT_DECIMAL,.. (ISample) ()

Writing a grouped struct signal (Transaction)

Here an example how to write grouped and layered struct samples.

        // transaction
        StructMember members0[] = new StructMember[2];
        members0[0] = new StructMember("Message", StructMember.STRUCT_TYPE_TEXT, 
                null, ISamples.FORMAT_DEFAULT);
        members0[1] = new StructMember("Data", StructMember.STRUCT_TYPE_INTEGER, 
                null, ISamples.FORMAT_HEXADECIMAL);
        StructMember members1[] = new StructMember[2];
        members1[0] = new StructMember("Message", StructMember.STRUCT_TYPE_TEXT, 
                null, ISamples.FORMAT_DEFAULT);
        members1[1] = new StructMember("Address", StructMember.STRUCT_TYPE_INTEGER, 
                null, ISamples.FORMAT_HEXADECIMAL);

        IStructSamplesWriter transWriter = (IStructSamplesWriter) getWriter(transaction1);

        members0[0].setValue("Do 1");
        members0[1].setValue(0);
        transWriter.write(100, false, /* id */0,/* order */IStructSamplesWriter.GO_FIRST,
                /* layer */0, members0);

        members1[0].setValue("Do 2");
        members1[1].setValue(0);
        transWriter.write(150, false, 1, IStructSamplesWriter.GO_FIRST, 1, members1);

        members0[1].setValue(90);
        transWriter.write(300, false, 0, IStructSamplesWriter.GO_LAST, 0, members0);

        members1[1].setValue(90);
        transWriter.write(350, false, 1, IStructSamplesWriter.GO_LAST, 1, members1);

        members0[0].setValue("Do 3");
        members0[1].setValue(0);
        transWriter.write(350, false, 2, IStructSamplesWriter.GO_FIRST, 0, members0);
        members0[1].setValue(90);
        transWriter.write(600, false, 2, IStructSamplesWriter.GO_LAST, 0, members0);