flowoutofsequence.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 out of sequence detection scenarios that forces the required TX and RX components to be present and returns only out of sequence values.
#
# @copyright Excentis nv - www.excentis.com
#

##
# @brief Executes an out of sequence detecting scenario based on a declarative scenario configuration and returns the calculated out of sequence 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 out of sequence detection or for background traffic.}
# @ulitem{A background flow may only have one or more TX parts\, but no RX parts.}
# @ulitem{An out of sequence flow may only have a single TX part\, which must have the 'outofsequence' option enabled.}
# @ulitem{An out of sequence flow may have zero\, one or more RX parts. They must all have a basic out of sequence 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 frames out of sequence per flow in the scenario.}
#                    @enddlist
#                    @defaultvalue{numbers}
#           }
#           @enddlist
#
# @return
#           The out of sequence values per are returned based on the value of the @command{return} option.
#           @dlist
#           @dlitem{numbers,Simplified nested list structure with out of sequence 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 2 values: the amount of received frames and
#                       the amount of frames out of sequence.}
#                     @endulist
#           }
#           @enddlist
#
proc FlowOutofsequence { 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 FlowOutofsequence error: Invalid argument '$option'"
            }
        }
    }

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

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

proc x.FlowOutofsequence.ScenarioConfig.Validate { scenarioConfig } {
#
# This parses and validates the flow list for an out of sequence scenario. This
# is needed because a flow out of sequence scenario imposes stricter rules on
# the flow configuration then a generic scenario used by 'ExecuteScenario'.
#
# If the stricter configuration is not met, an error is thrown.
#
# @arg 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 outofsequenceTxCount 0

        # Count TX and RX parts
        foreach {item value} $flowConfig {
            switch -- $item {
                -tx {
                    incr txCount
                    set txParamList $value
                    set index [ lsearch $txParamList "-outofsequence" ]
                    if { $index != -1 && [ lindex $txParamList [ expr $index + 1 ] ] == 1 } {
                        incr outofsequenceTxCount
                    }
                }
                -rx {
                    incr rxCount
                    # Rx part is validated later
                }
                default { error "ByteBlowerHL FlowOutofsequence error: Invalid flow paremter '$item'" }
            }
        }; # end parse flow parameters

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

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

proc x.FlowOutofsequence.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.OutOfSequence.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.
#

    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: 'FramesOutOfSequence <outofsequenceValue> NrOfFrames <value>'
                        # Required format: '<value> <outofsequenceValue>' (note: reverse order!)
                        set rxNumbersResult [ list [lindex $rxCounters 3] [lindex $rxCounters 1] ]
                        lappend flowNumbersResult "-rx" $rxNumbersResult
                    } else {
                        lappend flowNumbersResult "-rx" $value
                    }
                }
            }
        }
        lappend scenarioNumbersResult $flowNumbersResult
    }
    return $scenarioNumbersResult
}

}

}