flowlatency.tcl

Go to the documentation of this file.

##
# @brief Basic namespace for all Excentis Tcl extensions
#
namespace eval excentis {

##
# @brief This namespace holds all ByteBlower-related Tcl extensions, including the ByteBlower higher-layer Tcl API.
#
# These procedures are developed for higher-level usage of the ByteBlower API.
# They are mainly used to simplify running specific Test Scenarios similar to
# scenarios you know from the ByteBlower GUI.
#
namespace eval ByteBlower {

## \file
#
# @brief Wrapper module for latency measurement scenarios that forces the required TX and RX components to be present and returns only latency values.
#
# @copyright Excentis nv - www.excentis.com
#


##
# @brief Executes a latency calculating scenario based on a declarative scenario configuration and returns the calculated latency values.
#
# This method assumes the scenario configuration has certain properties and returns clear error messages when a scenario configuration is malformed.
# The scenario configuration requirements are:
# @ulist
# @ulitem{A flow should either be used for latency or for background traffic.}
# @ulitem{A background flow may only have one or more TX parts\, but no RX parts.}
# @ulitem{A latency flow may only have a single TX part\, which must have the 'latency' option enabled.}
# @ulitem{A latency flow may have zero\, one or more RX parts. They must all have a basic latency detector configured.}
# @endulist
#
# @param scenarioConfig
#           The scenario configuration as expected by the @apiref{excentis::ByteBlower::ExecuteScenario,ExecuteScenario} function.
#           See the @ref TclApiHLOverview "higher-layer API overview" for more information.
#
# @param args
#           Scenario-level option list in the form of a list of key-value pairs:
#           @dlist
#           @dlitem{-return, Defines the output mode. Following output modes are supported:
#                    @dlist
#                    @dlitem{numbers, Number of transmitted\, received frames and latency values per flow in the scenario.}
#                    @enddlist
#                    @defaultvalue{numbers}
#           }
#           @enddlist
#
# @return
#           The latency values per are returned based on the value of the
#           @command{return} option.
#           @dlist
#           @dlitem{numbers,Simplified nested list structure with latency values:
#                     @ulist
#                     @ulitem{Scenario structure (flows) and flow structures (TX and RX) are maintained.}
#                     @ulitem{The TX return value is one element\, the number of transmitted frames.}
#                     @ulitem{The RX return value is a list of 5 values: the amount of received frames\,
#                       the minimum\, average and maximum latency and the jitter.}
#                     @ulitem{All the latency values are presented in nanoseconds.}
#                     @endulist
#           }
#           @enddlist
#
proc FlowLatency { scenarioConfig args } {
    # Default args
    set outputmode "numbers"

    # Parsing args
    foreach { option value } $args {
        set option [ string tolower $option ]
        switch -- $option {
            -return {
                set outputmode $value
            }
            default {
                error "ByteBlowerHL FlowLatency error: Invalid argument '$option'"
            }
        }
    }

    x.FlowLatency.ScenarioConfig.Validate $scenarioConfig
    set scenarioResult [ ExecuteScenario $scenarioConfig ]

    if {$outputmode == "numbers"} {
        return [ x.FlowLatency.Result.Parse.Numbers $scenarioResult ]
    }
}

proc x.FlowLatency.ScenarioConfig.Validate { scenarioConfig } {
#
# This parses and validates the scenario configuration (or flow list) for a
# latency scenario. This is needed because a flow latency scenario imposes
# stricter rules on the flow configuration than a generic scenario used by
# 'ExecuteScenario'.
#
# If the stricter configuration is not met, an error is thrown.
#
# @param scenarioConfig
#           The scenario configuration passed by the user.
# @error
#           Error is thrown if validation of scenario configuration fails
#

    foreach flowConfig $scenarioConfig {
        set txCount 0
        set rxCount 0
        set latencyTxCount 0

        # Count TX and RX parts
        foreach {item value} $flowConfig {
            switch -- $item {
                -tx {
                    incr txCount
                    set txParamList $value
                    set index [ lsearch $txParamList "-latency" ]
                    if { $index != -1 && [ lindex $txParamList [ expr $index + 1 ] ] == 1 } {
                        incr latencyTxCount
                    }
                }
                -rx {
                    incr rxCount
                    # Rx part is validated later
                }
                default { error "ByteBlowerHL FlowLatency error: Invalid flow parameter '$item'\n   flow configuration: '$flowConfig'" }
            }
        }; # end validate flow configuration

        # TX and RX count validation
        if { $txCount == 0} {
            error "ByteBlowerHL FlowLatency error: flow must have at least one TX part\n   flow configuration: '$flowConfig'"
        }
        if { $txCount > 1 && $latencyTxCount > 0} {
            error "ByteBlowerHL FlowLatency error: flow with a latency-enabled TX part may have no other TX parts\n   flow configuration: '$flowConfig'"
        }
        if { $latencyTxCount == 0 && $rxCount > 0} {
            error "ByteBlowerHL FlowLatency error: flow without a latency-enabled TX part may not contain RX parts\n   flow configuration: '$flowConfig'"
        }
        if { $latencyTxCount == 1 && $rxCount == 0} {
            error "ByteBlowerHL FlowLatency error: flow with a latency-enabled TX part must have at least one latency-enabled RX part\n   flow configuration: '$flowConfig'"
        }

        # Validate RX parts
        foreach {item value} $flowConfig {
            switch -- $item {
                -rx {
                    set rxParamList $value
                    set basicLatencyCount 0
                    foreach {option value} $rxParamList {
                        switch -- $option {
                            -latency {
                                incr basicLatencyCount
                                foreach {latOption latValue} $value {
                                    # if type option is present, it must be 'basic' (basic is also default value)
                                    switch -- $latOption {
                                        -type {
                                            if { ! [ string equal $latValue "" ] && ! [ string equal $latValue basic ] } {
                                                error "ByteBlowerHL FlowLatency error: flow RX part may not contain '$latValue' type latency detector\n   flow configuration: '$flowConfig'"
                                            }
                                        }
                                    }
                                }
                            }
                            -trigger {
                                error "ByteBlowerHL FlowLatency error: latency flow RX part may not contain trigger\n   flow configuration: '$flowConfig'"
                            }
                            -capture {
                                error "ByteBlowerHL FlowLatency error: latency flow RX part may not contain capture tool\n   flow configuration: '$flowConfig'"
                            }
                            -outofsequence {
                                error "ByteBlowerHL FlowLatency error: latency flow RX part may not contain out of sequence detector\n   flow configuration: '$flowConfig'"
                            }
                            default {
                                # ignore other parameters, not our task to validate them
                            }
                        }
                    }
                    if { $basicLatencyCount == 0 } {
                        error "ByteBlowerHL FlowLatency error: latency flow RX part must contain a latency detector\n   flow configuration: '$flowConfig'"
                    }
                    if { $basicLatencyCount > 1 } {
                        error "ByteBlowerHL FlowLatency error: latency flow RX part must contain exactly one latency detector\n   flow configuration: '$flowConfig'"
                    }
                }
            }
        }; # end validate flow config
    }; # end validate scenario config
}

proc x.FlowLatency.Result.Parse.Numbers { scenarioResult } {
#
# Parse the scenario result for the numbers option. Because of our setup the
# scenario result has a specific format.
# * The scenario structure is maintained.
# * TX parts within a flow are 'Tx.Stream.Counter.Brief.Get' values
# * RX parts within a flow are 'Rx.Latency.Basic.Counters.Get' values
#
# @param scenarioResult
#           The normal scenario result returned by ExecuteScenario.
# @return
#           Return information in the format as specified by the 'numbers'
#           option in @ref FlowLatency.
#
    set scenarioNumbersResult [ list ]
    foreach flowResult $scenarioResult {
        set flowNumbersResult [ list ]
        foreach {item value} $flowResult {
            switch -- $item {
                -tx {
                    set txCounters $value
                    # Format: 'NrOfFramesSent <value> <FrameOid_1> <value_1> <FrameOid_2> ...'
                    # Required format: '<value>'
                    set txNumbersResult [ lindex $txCounters 1 ]
                    lappend flowNumbersResult "-tx" $txNumbersResult
                }
                -rx {
                    if {$value != "NA"} {
                        set rxCounters $value
                        # Format: 'NrOfFrames <value> MinLatency <value> AvgLatency <value>
                        #               MaxLatency <value> Jitter <value>'
                        # Required format: '<value> <value> <value> <value> <value>' (same order)
                        set rxNumbersResult [ list [lindex $rxCounters 1] [lindex $rxCounters 3] [lindex $rxCounters 5] [lindex $rxCounters 7] [lindex $rxCounters 9] ]
                        lappend flowNumbersResult "-rx" $rxNumbersResult
                    } else {
                        lappend flowNumbersResult "-rx" $value
                    }
                }
            }
        }
        lappend scenarioNumbersResult $flowNumbersResult
    }
    return $scenarioNumbersResult
}

}

}