Introduction
FrameTags are added to a ByteBlower Frame object and can be used to automatically insert dynamic information into the different frames of a ByteBlower traffic stream.
Consider a ByteBlower Port on which a Tx.Stream is created. A Frame 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.
- how frame tags are structured and what their properties are. Note that this may depend on the type of the (transmitting) ByteBlower server!
- where those tags are placed by default and how to override this position. Note this may depend on the type of the (transmitting) ByteBlower server!
- 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.
Note that to perform latency measurements and/or out of sequence detection, the test script needs to be configured at two different places:
- At the TX side, we need to add the FrameTag(s) to the Frame object. This causes the server to insert the tag before transmission.
- 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).
This post only describes the TX side! See relevant posts on latency and out of sequence detection for more information.
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 deprectated 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:
1000 series
| |
Alignment |
Length |
| TimeTag |
1 |
8 |
| SequenceTag |
1 |
8 |
2000 series
| |
Alignment |
Length |
| TimeTag |
8 |
8 |
| SequenceTag |
1 |
8 |
The current tag formats are:
1000 series (pre-1.10.18 version)
| |
Format (enum) |
Format (string) |
| TimeTag |
TimeStamp_Microseconds_CRC |
TimeStamp-Microseconds_CRC |
| SequenceTag |
SequenceNumber_0_CRC |
SequenceNumber-0_CRC |
1000 series (post-1.10.18 version)
| |
Format (enum) |
Format (string) |
| TimeTag |
TimeStamp_10Nanoseconds |
TimeStamp-10Nanoseconds |
| SequenceTag |
SequenceNumber_0_CRC |
SequenceNumber-0_CRC |
2000 series
| |
Format (enum) |
Format (string) |
| TimeTag |
TimeStamp_10Nanoseconds |
TimeStamp-10Nanoseconds |
| SequenceTag |
SequenceNumber_0_CRC |
SequenceNumber-0_CRC |
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
This section will explain exactly how a tag is inserted into a frame.
Case 1: Alignment value is 1
When the alignment value is 1, the tag can be inserted into the frame at every byte. The tag is inserted as follows:
- Start at the back of the frame.
- Go back position bytes.
- 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).
Case 2: Alignment value is greater than 1
When the alignment value is greater than 1, the exact position of the tag value cannot be determined by the API. Specifically, when a FrameSizeModifier is applied to the frame, the tag position (which is a constant offset relative to the end of the frame), will be located at different positions relative to the start of the frame when the frame size changes.
This means an extra offset is needed and that this extra offset can vary between different frames.
The tag is inserted as follows:
- Start at the back of the frame.
- Go back position bytes.
- Go towards the front of the frame until the first aligned position and remember the offset between the position of the FrameTag and this aligned position (denoted as x in the pictures).
- The tag value starts at this aligned location.
- Go to byte position+length and store this offset (x).
Requirement: The tag position should always be larger than its length. If a smaller position is set, an error will be thrown (even if the FrameTag is currently disabled!)
The best case occurs, when the position matches the frames alignment. In this case:
- the extra offset is 0
- the total space required to place the tag is its length
The worst case occurs, when the position points to 1 byte before the frames alignment. In this case:
- the extra offset is alignment - 1
- the total space required to place the tag is length + alignment - 1
Multiple tags
Multiple tags can be added into a single frame object. Each of them has its own position and based on that position, some space in the frame is reserved for it. The reserved space is equal to the maximum space that could be needed in the worst aligning situation.
The interval for the worst alignment case of a FrameTag is equal to [position+alignment-1, position-length[. When the alignment is 1, this boils down to [position, position-length[ as one might expect. Note that in these intervals the left boundary is larger then the right, because a larger value means closer to the start of the frame.
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
The automatic behaviour is determined by the transmitting server type. The general principles that define the automatic behaviour are:
- If a single tag is enabled, its position is length. This makes sure it is placed completely at the back of the frame.
- If both TimeTag and SequenceTag are enabled and both are positioned automatically, will be placed next to each other at the back of the frame.
- If both TimeTag and SequenceTag are enabled and one of them has an explicit position, the other tag will be placed as close to the rear as possible:
- If there is enough place after the fixed tag to fit (the worst case of) the automatic tag, the automatic tag will be placed behind it and as much to the end as possible.
- If there is not enough place after the fixed tag to fit (the worst case of) the automatic tag, the automatic tag will be placed immediately before the fixed tag.
1000 series examples
In the 1000 series both tags have an alignment of 1. This means we can place both tags at any position in the frame.
Example 1: Full automatic behaviour
The tags are placed at the end of the frame. If both are enabled, the SequenceTag is placed before the TimeTag:
| |
TimeTag only |
SequenceTag only |
Both |
| TimeTag position |
8 |
N/A |
8 |
| SequenceTag position |
N/A |
8 |
16 |
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. If it is less than 16, the SequenceTag is placed right in front of the TimeTag.
Note this works in a similar manner when the SequenceTag has an explicit position.
2000 series examples
In the 2000 series the TimeTag has an alignment of 8, while the SequenceTag has an alignment of 1.
Example 1: Full automatic behaviour
Tags are placed at the end of the frame. If both tags are enabled, the TimeTag is placed before the SequenceTag. Note this is the opposite from the 1000 series! We place the SequenceTag last, because it has an alignment of 1 and thus has a fixed length.
| |
TimeTag only |
SequenceTag only |
Both |
| TimeTag position |
9 |
N/A |
17 |
| SequenceTag position |
N/A |
8 |
8 |
Example 2: TimeTag has an explicit position
The explicit position is always respected. If the TimeTag position is greater than or equal to 17, the SequenceTag can be placed behind it. If not, the SequenceTag is placed in front of it. Note that when its placed in front of it, it respects the reserved interval of the TimeTag!
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:
1000 series
| Headers |
header length |
no tags |
TimeTag |
SequenceTag |
both tags |
| EthII-IPv4-UDP |
14+20+8=42 |
42* |
50* |
50* |
58* |
| EthII-IPv4-TCP |
14+20+20=54 |
54* |
62 |
62 |
70 |
| EthII-IPv6 |
14+40=54 |
54* |
62 |
62 |
70 |
| EthII-IPv6-UDP |
14+40+8=62 |
62 |
70 |
70 |
78 |
| EthII-IPv6-TCP |
14+40+20=74 |
74 |
82 |
82 |
90 |
2000 series
| Headers |
header length |
no tags |
TimeTag |
SequenceTag |
both tags |
| EthII-IPv4-UDP |
14+20+8=42 |
42* |
57* |
50* |
65 |
| EthII-IPv4-TCP |
14+20+20=54 |
54* |
65 |
62 |
73 |
| EthII-IPv6 |
14+40=54 |
54* |
65 |
62 |
73 |
| EthII-IPv6-UDP |
14+40+8=62 |
62 |
73 |
70 |
81 |
| EthII-IPv6-TCP |
14+40+20=74 |
74 |
89 |
82 |
97 |
Note that frame sizes with an asterisk (*) are smaller than 60 bytes, the minimum frame size required by the Ethernet specification.
Passing FrameTag settings to triggers at the RX side
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:
1000 series
| |
Position |
| TimeTag |
8 |
| SequenceTag |
8 |
2000 series
| |
Position |
| TimeTag |
9 |
| SequenceTag |
8 |
Note these values correspond with the positions of the tags when they are used by themselves and positioned automatically. Note, that these default RX settings are always incorrect when using multiple FrameTags in a frame, even when all of them are positioned automatically by the server!
Therefore, passing the FrameTag properties to the RX side, should always be done explicitly by the client script. 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 ]
