next - previous - toc

2.3. Structure Definition

Concept

The structure definition is used to model the data structure you want to display in the editor.

A structure definition is a tree structure consisting of structure definition elements. There are two types of elements : statements and data field definitions. A statement may contain other elements whereas a data field definition is a leaf in the tree and may not contain other elements. If the structure definition contains no errors it is compiled into a view.

Statements

A root statement is compiled into one data frame, the root frame of the resulting view. A case statement is compiled into zero or one view elements. A repeat statement is compiled into 0-n data frames.

Data Field Definitions

A Data Encoding Field Definition is compiled into exactly one Data Encoding Field. A Map Field Definition is compiled into one Map Field

View Definition Editing

Dynamic data views are recompiled after each change to the data. The recompilation can be turned by disabling the "Compile View" checkbox.
Each data view has an offset where the structure definition starts. This offset is used as the bitoffset of the first structure node when the structure is rendered. The offset can be locked to the current selection offset by enabling the Lock checkbox. If the offset is locked the offset of the structure is always the current selection offset (If the offset change did not originate from this dataview). If it is unlocked you can manually change the structure offset.

Clicking on a structure definition element will display the corresponding configuration dialog on the right side. After changing the element click on the apply button to make the changes take effect or on the cancel button to undo the changes.
New Insert -> New Add Above -> New Add Below Cut Copy Paste (Insert) Paste (Add Above) Paste (Add Below) Delete

On the buttom you can see two tabs
Validation
Before the structure definition is compiled into a view it has to be valid. The validation tab displays a list of errors in the structure definition which have to be corrected before the view is compiled. By clicking on the error you can select the corresponding structure definition element in the structure tree.
Compiler Output
The compiler output tab provides detailed information about the compilation process. This can be useful if you want to debug complex structure definitions. By clicking on a compiler message you can select the corresponding structure definition element in the structure tree.

Element Configuration

Root Statement


Example:

Case Statement

The data offset has to be a structure definition element before this case statement.
The data size must be greater than 0 bits.
Example: The case statement evalutes the protocol field in an ip packet to chose correct view definition. The protocol field has a length of 1 byte, and the defined cases are UDP and TCP. If none of those two protocols are used the default branch is choosen.

Repeat Statement

This repeat statement is compiled into length data frames.
Example: The repeat statement is compiled into on data frame with the name "access-flags".

The pointer definition consists of a field before this repeat statement.
After the pointer has been evaluated the resulting number is modified by a multiplication and then an addition (subtraction).
The minimum number of repeats is zero.
Example: The number of repeats is stored in a field called constant-pool-count. This field is evaluated as an unsigned big endian number.

Repeat Until Offset Statement

This repeat statement is compiled into length data frames.
Example: The repeat statement is compiled into on data frame with the name "access-flags".

The pointer definition consists of a field before this repeat statement.
After the pointer has been evaluated the resulting number is modified by a multiplication and then an addition (subtraction).
The minimum number of repeats is zero.
Example: The number of repeats is stored in a field called constant-pool-count. This field is evaluated as an unsigned big endian number.

Repeat Until Delimiter Statement

Example:

Fields

Data Encoding Field Definition

Example:

The pointer definition consists of a field before this repeat statement.
After the pointer has been evaluated the resulting number is modified by a multiplication and then an addition (subtraction).
The minimum bitSize is zero.
Example: The data encoding field displays the data inside an udp packet. The length of the packet is stored int a field called length. The length is in bytes, so we have to multiply by 8 to get bits. Then we have to substract the headersize of the udp packet (8 bytes) to get the data size.

Repeat Until Offset Field Definition


Example:

Example:

Repeat Until Delimiter Field Definition

Example: This is the definition for a c-style string. The delimiter is 0x00 and we display the result in ascii. We want to include the delimiter in the displayed data so we modify the calculated bitsize by adding 1 byte.

Map Field Definition

Example: The Operating System byte in the gzip structure. It is 1 byte long and there are 8 possible mappings defined.


next - previous - toc