Introduction

FrameTags are used to overwrite parts of a frame with dynamically generated data, such as a timestamp. This data is calculated for each individual frame in a frame blasting stream, just before it leaves the ByteBlower server.

Consider a ByteBlower Port on which a Tx.Stream is created. A Frame object is added to the stream. The content of a frame is static and can be set using the Bytes.Set function. The following code shows how to create this situation in the Tcl API:

Tcl

set flowObject [ $sourcePortObject Tx.Stream.Add ]
set frameObject [ $flowObject Frame.Add ]
$frameObject Bytes.Set $byteFrame

The static bytes of a frame can be changed by calling the Bytes.Set function again. This can be done at all times, even while the Tx.Stream is being transmitted!

However, changing the static bytes of a frame is a client-side action. FrameTags allow changing the frame content automatically and at the server side.

Adding a FrameTag to a Frame object causes the following things to happen for each individual frame in the traffic stream:

• The ByteBlower server determines the tag value, immediatly before a frame is to be transmitted.
• The ByteBlower server inserts the tag value into the frame, overwriting the static bytes located at the tag's location.
• The ByteBlower server sends the resulting frame.

This entry will show...

• how to add a frame tag to a frame object
• where those tags are placed by default and how to override this position
• how to tell the receiving side where in the received frame to look for a tag

Types of FrameTags

Currently two FrameTags exist:

• 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.

To perform latency measurements or out of sequence detection, the test scenario needs to be configured at two different places:

1. At the TX side, we need to add the FrameTag(s) to the Frame object.
2. 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).

Adding a FrameTag to a Frame

Adding a FrameTag to a Frame object is very simple. Just retrieve the relevant FrameTag object on the frame and enable it. 

Tcl

set timeTagObject [ $frameObject FrameTag.Time.Get ]
$timeTagObject Enable

Note that there are deprecated functions to enable a specific tag directly from the frame object. These are only preserved for backwards compatibility and their behaviour is identical to the two lines of code above.

Tcl

$frameObject TimeTag.Enable

Adding multiple FrameTags is also possible.

Tcl

[ $frameObject FrameTag.Time.Get ] Enable
[ $frameObject FrameTag.Sequence.Get ] Enable

FrameTag properties

Every FrameTag has a fixed set of properties:

• Metrics: Contains two values defining the external tag structure.
  • Alignment: Defines at which positions, relative to the start of the frame, the tag value can be inserted. A value of 1 means the tag value can inserted at any byte. A value of 4 means the tag can only be inserted at bytes 4, 8, 12, etc.
  • Length: Shows the number of bytes in the frame that will be overwritten by the tag. As shown in the tag insertion mechanism, this is not always a contiguous range!
• Position: Defines at which byte the tag starts, relative to the end of the frame. The position is defined from the back, because the frame headers may change during transmission (e.g. a VLAN tag might be added). This would change the tag position relative to the front of the frame.
• Format: This code defines the internal format of the tag (e.g. whether the timestamp is shown in nanoseconds or microseconds).

Apart from the position, which can be explicitly set, these properties properties have fixed values and defined by two things:

• the type of tag (e.g. a TimeTag)
• the transmitting server type (e.g. a 1x00 server)

The current tag metrics are:

The current TX tag formats are:

Note that in future multiple tags and even metrics may be supported by the various server types (either at the TX side, the RX side or both sides). This could allow some interoperability between server series.

FrameTag insertion mechanism

When the alignment value is 1, the tag can be inserted into the frame at every byte. The tag is inserted as follows:

1. Start at the back of the frame.
2. Go back position bytes.
3. The tag value starts at that location and continues for length bytes.

Requirement: The tag position should always be larger than its length. If a smaller position is set, an error will be thrown (even if that FrameTag is currently disabled).

Multiple tags

Multiple tags can be added into a single frame object. Each of them has its own position. When a tag is enabled, the necessary bytes in the frame are reserved for that tag. For an alignment value of 1, this means bytes [position, position-length[ will be reserved.

Requirement: The positions of all enabled tags must be chosen so that their reserved spaces do not overlap. Enabling a FrameTag whose reserved space would overlap with another enabled FrameTag's reserved space will throw an error.

Automatic position

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

Example 1: Full automatic behaviour

The tags are placed at the end of the frame.

If both are enabled, the SequenceTag is placed in front of the TimeTag:

Example 2: TimeTag has an explicit position

The explicit position is always respected.

If the TimeTag position is greater than or equal to 16, the SequenceTag can be placed behind it (at the end of the frame). If the position is less than 16, the SequenceTag is placed right in front of the TimeTag.

The same goes for a SequenceTag with an explicit position.

Minimally required frame sizes

Positioning FrameTags automatically places them as close to the end of the frame as possible.

Even so, tagging takes up space, so our frame should have at least a minimal payload so the frame headers are not overwritten.

The table below shows the minimal frame size for various frame header and tagging combinations:

(*) No valid Ethernet frame (smaller than 60 bytes)Frame smaller than 60 bytes, the minimum frame size required by the Ethernet specification.

Passing FrameTag settings to RX side(s)

Adding a TimeTag or SequenceTag to a Frame object is not enough to perform latency or out of sequence detection tests.

At the receiving ByteBlower port, a corresponding receiver must be created. Adding receivers for both can be done as follows:

Tcl

set latencyObject [ $destinationPortObject Rx.Latency.Add ]
set outofsequenceObject [ $destinationPortObject Rx.OutOfSequence.Add ]

We will not discuss how to use these receivers here. See the relevant posts on latency and out of sequence detection tests for more information. 

What is important is how to pass the TimeTag and/or SequenceTag information (at the TX side) to a Latency and/or OutOfSequence receiver (at the RX side). This is needed because:

• The receiver must know where within the frame he must look for a tag.
• This cannot be done at the server side, because the receiving port may be located on another server. Even when tags are placed automatically, the generated tag position should be passed to the receiver.
• In future, multiple tag metrics and/or tag formats may be supported. When using non-default properties, this should be passed to the receiver.

The default metric and format values are the same as the default TX values for that server type (see above). Note that in future, servers may have support for multiple metrics and formats and that RX support may differ from TX support. For example, a server may need an alignment of 8 to insert a TimeTag, while being able to read TimeTags at any position.

The default position values are:

These values correspond with the automatic positions when the frames are used by themselves.

However, if both tags are enabled, the SequenceTag position will be 16 by default. In this case (even though both frames are positioned automatically), the default RX settings will be incorrect!

Therefore, passing the FrameTag properties to the RX side, should always be done explicitly by the client script. This is the safest option and works in all situations.

For a situation where both tags are used, this can be done as follows:

Tcl

$latencyObject FrameTag.Set [ $frameObject FrameTag.Time.Get ]
$outofsequenceObject FrameTag.Set [ $frameObject FrameTag.Sequence.Get ]