The FrameTag.Tx class describes the transmit configuration of a Tag in a Frame. More...

Methods
	Description.Get
	Returns a textual description of the object.

	Disable
	Method to disable the tag on the Frame. More...

	Enable
	Method to enable the tag on the Frame. More...

	Format.String.Get
	This returns the format string of this tag. More...

	IsEnabled
	Method which will return whether a tag is activated or not. More...

	Metrics.Get
	Returns the FrameTag.Metrics of this tag. More...

	Parent.Get
	Returns the parent object.

	Position.Automatic.Set
	This method will use the automatic position for the tag. More...

	Position.Get
	Returns the current configured location of the tag within the Frame. More...

	Position.Set position
	Sets the location of the tag in the Frame. More...

	Type.Get
	Returns the FrameTag type. More...

Class overview

The FrameTag.Tx class describes the transmit configuration of a Tag in a Frame.

ByteBlower supports optional tagging of frames. Such a tag can have different formats, locations, ... These parameters can be set and retrieved using this class.

Currently, two different types of FrameTags are supported:

SequenceTag: is used for out of sequence detection and contains a frame counter value. The server automatically increments it for each frame sent in the stream.
TimeTag: is used for latency measurements and contains a timestamp value. The server automatically determines it by looking at its clock for each frame sent in the stream.

Adding tags is a very powerful and flexible feature of ByteBlower. Please have a look at ByteBlower API Knowledgebase: Background: Adding FrameTags to your ByteBlower frame - structure and behaviour for a very detailed explanation.

To perform latency measurements or out of sequence detection, configuration needs to be done both at TX and RX side:

At the TX side: we need to add the FrameTag(s) to the Frame object.
At the RX side: we need to create the appropriate receiver(s) on the incoming packets. This causes the server to read a tag from the received frames and interpret them (e.g. by calculating latency based on the timestamps).

Definition at line 4922 of file api.tcl.

Method documentation

FrameTag.Tx::Disable

Method to disable the tag on the Frame.

This will deactivate the tag on the Frame. The original content of the frame will be restored.

Note the configuration of other enabled frames may change when this frame is disabled.

Default value: Disabled

Example

To disable the sequence tag on frame, one can do:

1 [$frame FrameTag.Sequence.Get] Disable

Definition at line 4943 of file api.tcl.

FrameTag.Tx::Enable

Method to enable the tag on the Frame.

This will activate the tag on the Frame, and apply its configuration. As long as this method is not called, the tag will not be active.

Note the configuration of other enabled frames may change when this frame is disabled.

Default value: Disabled

Example

To enable the sequence tag on frame, one can do:

1 [$frame FrameTag.Sequence.Get] Enable

Definition at line 4959 of file api.tcl.

FrameTag.Tx::Format.String.Get

This returns the format string of this tag.

The exact format of the different tags may vary between the different versions of the ByteBlower software. To match the receiving part of a flow with then transmitting part, it is necessary to configure the same format.

Each tag format has a unique format code. The following formats are currently defined:

Sequence Tag

For a Sequence Tag, the following formats exist:

SequenceNumber-0_CRC

this format defines a tag of 8 bytes:

 |--------|--------|--------|--------|--------|--------|--------|--------|
 |    1   |    2   |    3   |    4   |    5   |    6   |    7   |    8   |
 |--------|--------|--------|--------|--------|--------|--------|--------|
 |                   SEQUENCE NUMBER                   |       CRC       |
 |-----------------------------------------------------------------------|

The sequence number is incremented for each packet leaving the ByteBlower server. The CRC will invert the changes in value so the checksum over the full payload remains constant. This makes sure other checksums (e.g. UDP) remain valid.

Time Tag

For a Time Tag, two formats are currently defined:

TimeStamp-Microseconds_CRC

Please note that support for Microseconds resolution has been dropped since 2.9.0 This format is used on pre-1.10.16 software versions on the ByteBlower 1000 series. This Tag is 8 bytes long and looks like this:

 |--------|--------|--------|--------|--------|--------|--------|--------|
 |    1   |    2   |    3   |    4   |    5   |    6   |    7   |    8   |
 |--------|--------|--------|--------|--------|--------|--------|--------|
 |               TIMESTAMP MICROSECONDS                |       CRC       |
 |-----------------------------------------------------------------------|

This format carries the server timestamp when this frame was sent in units of microseconds. The CRC will invert the changes in value so the checksum over the full payload remains constant. This makes sure other checksums (e.g. UDP) remain valid.

TimeStamp-10Nanoseconds

This format is used by the ByteBlower 2000 series and by the 1000 series from version 1.10.18 onwards. This Tag is 8 bytes long, only containing the Timestamp in nanoseconds. It does not include a CRC compensation. This means that automatic checksum calculation must be enabled on the Frame or those CRC values will be incorrect.

Returns

One of

SequenceNumber-0_CRC
TimeStamp-Microseconds_CRC
TimeStamp-10Nanoseconds

Example

This example will return the type of a Sequence Tag:

1 [$frame FrameTag.Sequence.Get ] Format.String.Get

Returns:

SequenceNumber-0_CRC

Definition at line 4993 of file api.tcl.

FrameTag.Tx::IsEnabled

Method which will return whether a tag is activated or not.

This method is used to retrieve the current state of the tag. If this tag is activated/enabled, true is returned. Otherwise, this method will return false.

Default value: Disabled

Returns: True if enabled, false if disabled.

Example

To see if a timestamp tag is enabled on a frame, this code can be used:

1 [$frame FrameTag.Time.Get] IsEnabled

Returns:

false

Definition at line 5009 of file api.tcl.

FrameTag.Tx::Metrics.Get

Returns the FrameTag.Metrics of this tag.

The FrameTag.Metrics represent the configuration like the length and alignment of a tag. This method returns this information for this object.

Returns: <FrameTag.Metrics object>

Example

This example will return the FrameTag.Metrics object for a sequence tag:

1 [$frame FrameTag.Sequence.Get ] Metrics.Get

Returns:

<FrameTag.Metrics object>

Definition at line 5023 of file api.tcl.

FrameTag.Tx::Position.Automatic.Set

This method will use the automatic position for the tag.

ByteBlower is very flexible in positioning the tag, and the combination of different tags. If the position of the tag is not important, the automatic positioning of tags is the easiest way for the user.

Note that the automatic position is used by default. This method is only useful when you want to reset positions that were previously set by the user.

Automatic placement of FrameTags has multiple advantages:

it shields the API user from the complexity described above
it makes sure the requirements are respected: the position will always be larger than the tag length and multiple tags will never overlap
it places the tags as close towards the end as possible to allow tagging small frames without overwriting frame headers

Tags are automatically placed at the end of the frame. If both Tags are enabled and have an automatic position, the SequenceTag is placed in front of the TimeTag.

If a tag has an explicit position, this is always respected. The automatic position will adapt to it as follows:

If there is enough place after the fixed tag to fit the automatic tag, the automatic tag is placed behind it (at the end of the frame).
If there is not enough place after the fixed tag to fit the automatic tag, the automatic tag is placed right in front of the fixed tag.

Default value: Enabled

Example

In this example, we will reset the position of the sequence tag to automatic.

1 [$frame FrameTag.Sequence.Get] Postion.Automatic.Set

Definition at line 5050 of file api.tcl.

FrameTag.Tx::Position.Get

Returns the current configured location of the tag within the Frame.

A user can choose where in a the Frame a tag will be placed (TX) or looked for (RX).

This position is configured relative to the end of the frame in units of bytes. This eliminates the complexity caused by VLAN tagging or other protocols that may influence the header structure of a frame.

The meaning of the position value is shown like this:

 |                                                              Position
 |                                                     | <---------------------|
 |-----------------------------------------------------------------------------|
 |                                                     | TAG |                 |
 |-----------------------------------------------------------------------------|

If no position is specified by the user, the server sert (TX) or look for (RX) the tag at a default location.

This method returns the current configured value for this position.

Default value At the TX side, the default position places the tag at the end of the frame, without overlapping with other enabled tags. At the RX side, the default position is the length of the tag. This means the RX side guesses the location of the tag to be at the very end of the frame. Note that this guess is incorrect if multiple tags are enabled on a single frame!

Returns: Current configured position. If nothing was specified, the default position chosen by the server is returned.

Example

This example will return the position of a sequence tag:

1 [$frame FrameTag.Sequence.Get] Position.Get

Returns:

Definition at line 5079 of file api.tcl.

FrameTag.Tx::Position.Set			position

Sets the location of the tag in the Frame.

A user can choose where in a the Frame a tag will be placed (TX) or looked for (RX).

This position is configured relative to the end of the frame in units of bytes. This eliminates the complexity caused by VLAN tagging or other protocols that may influence the header structure of a frame.

The meaning of the position value is shown like this:

 |                                                              Position
 |                                                     | <---------------------|
 |-----------------------------------------------------------------------------|
 |                                                     | TAG |                 |
 |-----------------------------------------------------------------------------|

If no position is specified by the user, the server sert (TX) or look for (RX) the tag at a default location.

This method allows the user to configure this value.

Parameters

position The new value of the position. This value must be between <taglength> and <framelength>.

Example

This example will sets the position of a sequence tag:

1 [$frame FrameTag.Sequence.Get] Position.Set 32

Definition at line 5106 of file api.tcl.

FrameTag.Tx::Type.Get

Returns the FrameTag type.

Currently two FrameTags are in use:

The TimeTag is used for latency measurements and contains a timestamp value. The server automatically determines it by looking at its clock for each frame sent in the stream.
The SequenceTag is used for out of sequence detection and contains a frame counter value. The server automatically increments it for each frame sent in the stream.

Returns

The current type of the FrameTag:

SequenceNr: This is a FrameTag with a sequence number.
TimeStamp: This is a FrameTag with a timestamp.

Example

This example will return the type of a Sequence Tag:

1 [$frame FrameTag.Sequence.Get ] Type.Get

Returns:

SequenceNr

Definition at line 5122 of file api.tcl.

Methods

Class overview

Method documentation