executescenario.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 Core module that <b>executes higher-layer scenario configurations</b> and <b>returns the scenario results</b> requested through that configuration.
#
# This module and its two main methods <tt>ExecuteScenario</tt> and <tt>ExecuteScenarioRT</tt> form the core of the ByteBlower higher-layer (HL) Tcl API:
# <ul>
# <li>Scenario configurations, which is nothing more then a list of traffic flow configurations, are passed as input to these methods.</li>
# <li>They are subsequently parsed and mapped to objects in the lower-layer API. This happens transparent to the user.</li>
# <li>The scenario is then immediately executed (i.e. all traffic flows are started).</li>
# <li>After the scenario is finished, a set of result values are returned. The structure of the result is based on the provided scenario configuration.</li>
# <li>Finally, all objects created before and during execution are destroyed, so the ByteBlower server is in the same state as before.</li>
# </ul>
#
# The real-time variant makes sure a callback method containing intermediate results is executed at a fixed time interval. This method can be implemented
# by the calling script to handle real-time results as desired.
#
# Most other modules in the ByteBlowerHL API are built as wrappers around these calls, adding extra logic or predefining some of settings in the scenario configuration.
#
# @copyright Excentis nv - www.excentis.com
#

package require excentis_basic

set ::ByteBlowerExecuteScenarioResult ""
set ::ByteBlowerExecuteScenarioDone 0
set ::ByteBlowerExecuteScenarioWait 1

##
# @brief Method to retrieve the objects to pass at Ports.Start and WirelessEndpoints.Start
# 
proc x.GetDevicesToStart { txPorts rxPorts } {
    set portsToStart [ list ]
    set wepsToStart [ list ]
    foreach txPort $txPorts {
        switch -- [ $txPort Get _ClassName ] {
            "ByteBlowerPort" {
                if { [ lsearch $portsToStart $txPort ] == -1 } {
                    lappend portsToStart $txPort
                }
            }
            "WirelessEndpoint" {
                if { [ lsearch $wepsToStart $txPort ] == -1 } {
                    lappend wepsToStart $txPort
                }
            }
            
        }
    }
    
    foreach rxPort $rxPorts {
        switch -- [ $rxPort Get _ClassName ] {
            "WirelessEndpoint" {
                if { [ lsearch $wepsToStart $rxPort ] == -1 } {
                    lappend wepsToStart $rxPort
                }
            }
            
        }
    }
    return [ list $portsToStart $wepsToStart ]
}

##
# @brief Method to start the wireless endpoints.
# @return nothing
#
proc x.StartWirelessEndpoints { wirelessEndpoints } {
    foreach wirelessEndpoint $wirelessEndpoints {
        # Claim the devices, it is ours!
        $wirelessEndpoint Lock 1
        
        # Clear previously stored results
        $wirelessEndpoint Result.Clear
    }
    
    set bb [ ByteBlower Instance.Get ]
    eval $bb WirelessEndpoints.Prepare.Async $wirelessEndpoints
    eval $bb WirelessEndpoints.Prepare $wirelessEndpoints
    
    eval $bb WirelessEndpoints.StartAndWait $wirelessEndpoints
    
}

proc x.StopWirelessEndpoints { wirelessEndpoints } {

}

proc x.WaitForWirelessEndpoints { wirelessEndpoints } {

    set check_interval 1000;#ms
    
    foreach endpoint $wirelessEndpoints {
        set ::wep_hb($endpoint) [ $endpoint Heartbeat.Timestamp.Last.Get ]
        set hb_interval [ expr int(double([$endpoint Heartbeat.Interval.Get ]) / 1000000) ]
        if { ${hb_interval} < $check_interval} {
            set check_interval $hb_interval
        }
    }
    
    set check_interval [ expr $check_interval / 2 ]
    
    while 1 {
        set ::hb_check_after 0
        after $check_interval "set ::hb_check_after 1"
        vwait ::hb_check_after
        unset ::hb_check_after
        
        set nrOk 0
        foreach endpoint $wirelessEndpoints {
            set cur_heartbeat [ $endpoint Heartbeat.Timestamp.Last.Get ]
            if { $cur_heartbeat > $::wep_hb($endpoint)} {
                incr nrOk
            }
        }
        if { $nrOk == [ llength $wirelessEndpoints ]} {
            array unset ::wep_hb
            return 1
        }
    }
    
    array unset ::wep_hb
    return 0

}

##
# @brief Central method of the higher-layer API which executes declarative scenario configurations and returns the scenario results.
#
# This method sets up the scenario flows, runs them and collects information about them. After executing the scenario all created 
# objects are removed from the interacting @apiref{ByteBlowerPort} objects, so thay return to the same pre-scenario state.
#
# This method is synchronous and will return the global scenario results once it is finished. To handle intermediate results, there is
# a similar method @apiref{excentis::ByteBlower::ExecuteScenarioRT,ExecuteScenarioRT}.
#
# @note
# At this point, only frame blasting scenarios can be run with the higher-layer API.
#
# @param scenarioConfig
#           The declarative scenario configuration. 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{-extended, Flag that changes default types of various scenario components to return extended results. It may be overridden by the specific component characteristics.
#                              @defaultvalue{0}
#           }
#           @dlitem{-finaltimetowait, Sets the time in ms to wait after the last flow is finished. This allows packets which are in transit to arrive at their destination.
#                              @defaultvalue{5000 (5s)}
#           }
#           @dlitem{-scoutingfinaltimetowait, Sets the time in ms to wait after the last scouting frames is transmitted. This allows packets which are in transit to prepare the network path and arrive at their destination.
#                              @defaultvalue{1000 (1s)}
#           }
#           @enddlist
#
# @return
#           The result data structure. See the @ref TclApiHLOverview "higher-layer API overview" for more information.
#
proc ExecuteScenario { scenarioConfig args } {
    set scenarioResultList [ list ]

    #--
    #-- PARSE ARGS
    #--
    set extended 0
    set timetowait 5000
    set scoutingTimetowait 1000

    set walker 0
    for { set walker 0} { $walker < [ llength $args ]} { incr walker} {
        set arg [ lindex $args $walker ]
        switch -- $arg {
            -extended {
                set extended 1
            }
            -finaltimetowait {
                incr walker
                set timetowait [ lindex $args $walker ]
            }
            -scoutingfinaltimetowait {
                incr walker
                set scoutingTimetowait [ lindex $args $walker ]
            }
        }
    }

    #--
    #-- PREPARE
    #--
    set temp [ x.ExecuteScenario.ScenarioConfig.Parse $scenarioConfig $extended ]
    set txPorts [ lindex $temp 0 ]
    set rxPorts [ lindex $temp 1 ]
    set duration [ lindex $temp 2 ]
    set scenarioObjectList [ lindex $temp 3 ]
    set scenarioPrepareObjectList [ lindex $temp 4 ]

    if { [ catch {
        x.ExecuteScenario.PrepareNetwork $scenarioPrepareObjectList $scoutingTimetowait
    } dummy ]} {
        # --- Cleanup all created objects (using 'catching' version)
        x.ExecuteScenario.Cleanup $scenarioPrepareObjectList
        x.ExecuteScenario.Error $scenarioObjectList $dummy
    }

    #--
    #-- CLEANUP of prepare objects
    #--
    x.ExecuteScenario.Cleanup $scenarioPrepareObjectList

    switch -exact -- [ catch {
        #--
        #-- INIT RX SIDE
        #--
        foreach flowObjectList $scenarioObjectList {
            foreach {item value} $flowObjectList {
                if { [ string equal $item "-rx" ] && ![ string equal $value "NA" ] } {
                    # If the rx side has a capture active, start is.
                    # If it has another trigger, reset it.
                    set description [ $value Description.Get ]
                    if { [ regexp {capture} $description ] } {
                        $value Start
                    } else {
                        $value Result.Clear
                    }
                }
            }
        }

        #--
        #-- START SCENARIO
        #--
        set stop 0
        
        
        # Select byteblower ports to start, select wireless endpoints to start
        foreach { portsToStart wepsToStart } [ x.GetDevicesToStart $txPorts $rxPorts ] { break; }
        x.StartWirelessEndpoints $wepsToStart
        
                
        # Start traffic on tx ports
        eval ByteBlower Ports.Start $portsToStart
        # Calculate the duration
        set duration [expr int(ceil($duration))  ]
        # Recalculate duration ( duration - sum (all inital times to wait) )
        set duration [expr $duration - [ x.ExecuteScenario.CheckTxErrors $scenarioObjectList $txPorts ] ]
        if { $::ByteBlowerExecuteScenarioWait } {
            # Wait for traffic to stop
            after $duration set stop 1
            vwait stop
            unset stop

            #--
            #-- STOP SCENARIO + GET RESULTS
            #--
            eval ByteBlower Ports.Stop $portsToStart
            
            #
            # -- Wait for timetowait
            #
            if { $timetowait != 0 } {
                set stop 0
                after $timetowait set stop 1
                vwait stop
                unset stop            
            }
            x.StopWirelessEndpoints $wepsToStart
            x.WaitForWirelessEndpoints $wepsToStart
            
            
            set scenarioResultList [ x.ExecuteScenario.Results.Get $scenarioObjectList $extended ]
        } else {
            set command [ list ::excentis::ByteBlower::x.ExecuteScenario.Finished  [ list $txPorts]  [ list $scenarioObjectList ]  [ list $extended ] ]
            eval after $duration $command
            return
        }
    } dummy ] {
        # TCL_ERROR
        1 {
            # --- Cleanup all created objects (using 'catching' version)
            x.ExecuteScenario.Error $scenarioObjectList $dummy
        }
        # TCL_RETURN
        2 {
            return $dummy
        }
        default {
                #--
                #-- CLEANUP + RETURN RESULTS
                #--
                x.ExecuteScenario.Cleanup $scenarioObjectList
                return $scenarioResultList          
        }
    }
}

##
# @brief Central method of the higher-layer API which executes declarative scenario configurations and returns the scenario results.
#
# This method sets up the scenario flows, runs them and collects information about them. After executing the scenario all created 
# objects are removed from the interacting @apiref{ByteBlowerPort} objects, so thay return to the same pre-scenario state.
#
# The method is synchronous and will return the global scenario results once it has finished. However, it will also periodically 
# execute a callback method containing the intermediate results. If this real-time result functionality is not required, a similar method
# @apiref{excentis::ByteBlower::ExecuteScenario,ExecuteScenario} may also be used. 
#
# @note
# At this point, only frame blasting scenarios can be run with the higher-layer API.
#
# @param scenarioConfig
#           The declarative scenario configuration. 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{-extended,Flag that changes default types of various scenario components to return extended results. It may be overridden by the specific component characteristics.
#                              @defaultvalue{0}
#           }
#           @dlitem{-finaltimetowait,Sets the time in ms to wait after the last flow is finished. This allows packets which are in transit to arrive at their destination.
#                              @defaultvalue{5000 (5s)}
#           }
#           @dlitem{-scoutingfinaltimetowait, Sets the time in ms to wait after the last scouting frames is transmitted. This allows packets which are in transit to prepare the network path and arrive at their destination.
#                              @defaultvalue{1000 (1s)}
#           }
#           @dlitem{-updateinterval,Sets the time in ms between result updates. After every update interval the callback procedure is called.
#                                   @defaultvalue{1000 (1s)}
#           }
#           @dlitem{-callback,Sets the callback method called at every update interval by specifying the method name. The procedure itself is defined by the calling script and
#                             has a single parameter @command{scenarioResultList} which contains the interval results.
#                             @defaultvalue{"DefaultCallback"}
#           }
#           @enddlist
#
# @return
#           The result data structure. See the @ref TclApiHLOverview "higher-layer API overview" for more information.
#           If an exception happens during the execution of the scenario, this exception object will be returned. The method Message.Get on this exception object will return the error-message.
#           @apiexample
#           @apisnippet{source IPv4.run.tcl}
#           @apisnippetretval{ByteBlowerObject_1530880908_2}
#           @apisnippet{% ByteBlowerObject_1530880908_2 Message.Get}
#           @apisnippetretval{-server localhost Failed to connect with the ByteBlower server: byteblower-tp-p860.lab.excentis.com:9002}
#           @endapiexample
#
proc ExecuteScenarioRT { scenarioConfig args } {
    set scenarioResultList [ list ]

    #--
    #-- PARSE ARGS
    #--
    set extended 0
    set timetowait 5000
    set scoutingTimetowait 1000
    set updateinterval 1000
    set callback 0

    set walker 0
    for { set walker 0} { $walker < [ llength $args ]} { incr walker} {
        set arg [ lindex $args $walker ]
        switch -- $arg {
            -extended {
                set extended 1
            }
            -finaltimetowait {
                incr walker
                set timetowait [lindex $args $walker ]
            }
            -scoutingfinaltimetowait {
                incr walker
                set scoutingTimetowait [ lindex $args $walker ]
            }
            -updateinterval {
                incr walker
                set updateinterval [lindex $args $walker ]
            }
            -callback {
                incr walker
                set callback 1
                set callbackMethod [ lindex $args $walker ]
            }
        }
    }

    if {$callback == 0} {
        # Apply default callback method
        set callback 1
        set callbackMethod "DefaultCallback"
    }

    #--
    #-- PREPARE
    #--
    set temp [ x.ExecuteScenario.ScenarioConfig.Parse $scenarioConfig $extended]
    set txPorts [ lindex $temp 0 ]
    set rxPorts [ lindex $temp 1 ]
    set duration [ lindex $temp 2 ]
    set scenarioObjectList [ lindex $temp 3 ]
    set scenarioPrepareObjectList [ lindex $temp 4 ]

    if { [ catch {
        x.ExecuteScenario.PrepareNetwork $scenarioPrepareObjectList $scoutingTimetowait
    } dummy ]} {
        # --- Cleanup all created objects (using 'catching' version)
        x.ExecuteScenario.Cleanup $scenarioPrepareObjectList
        x.ExecuteScenario.Error $scenarioObjectList $dummy
    }

    #--
    #-- CLEANUP of prepare objects
    #--
    x.ExecuteScenario.Cleanup $scenarioPrepareObjectList

    if { [ catch {
        #--
        #-- INIT RX SIDE
        #--
        foreach flowObjectList $scenarioObjectList {
            foreach {item value} $flowObjectList {
                if { [ string equal $item "-rx" ] && ![ string equal $value "NA" ] } {
                    # If the rx side has a capture active, start it.
                    # If it has another trigger, reset it.
                    set description [ $value Description.Get ]
                    if { [ regexp {capture} $description ] } {
                        $value Start
                    } else {
                        $value Result.Clear
                    }
                }
            }
        }

        #--
        #-- START SCENARIO
        #--
        set poll 0
        set ::stop 0
        
        # Select byteblower ports to start, select wireless endpoints to start

        foreach { portsToStart wepsToStart } [ x.GetDevicesToStart $txPorts $rxPorts ] { break; }
        x.StartWirelessEndpoints $wepsToStart
        
                
        # Start traffic on tx ports
        eval ByteBlower Ports.Start $portsToStart
        # Calculate the duration
        set duration [expr int(ceil($duration)) + $timetowait ]
        # Wait for traffic to stop
        after $duration  "set ::stop 1"
        set timestamp 0
        while { $::stop != 1 } {
            update
            after $updateinterval set poll 1
            vwait poll
            set poll 0
            # We just want a result of one flow, so we don't kill any ByteBlower server.
            # Now, we will log
            set timestamp [ x.ExecuteScenario.Timestamp.Next.Get $scenarioObjectList $timestamp $updateinterval ]
            set scenarioTempResultList [ x.ExecuteScenario.InterRunResults.Get $scenarioObjectList $txPorts $extended $timestamp  ]
            

            if {$callback == 1} {
                eval $callbackMethod {$scenarioTempResultList}
            }
            update
        }

        #--
        #-- STOP SCENARIO + GET RESULTS
        #--
        eval ByteBlower Ports.Stop $portsToStart
        
        x.StopWirelessEndpoints $wepsToStart
        x.WaitForWirelessEndpoints $wepsToStart
        set scenarioResultList [ x.ExecuteScenario.Results.Get $scenarioObjectList $extended ]
    } dummy ]} {
        # --- Cleanup all created objects (using 'catching' version)
        #puts $::errorInfo
        x.ExecuteScenario.Error $scenarioObjectList $dummy
    }

    #--
    #-- CLEANUP + RETURN RESULTS
    #--
    x.ExecuteScenario.Cleanup $scenarioObjectList
    return $scenarioResultList
}

##
# @brief Default callback method for processing the real-time results that simply prints result values on every update interval. 
#
# @param scenarioResultList
#           The intermediate scenario result. It has the same format as the final scenario result, which is based on the 
#           scenario configuration.
proc DefaultCallback { scenarioResultList } {
    set flowid 1
    foreach flowResultList $scenarioResultList {
        set txResult [ lindex [ lindex $flowResultList 1 ] 1 ]
        set rxResult [ lindex [ lindex $flowResultList 3 ] 1 ]
        puts "[clock format [clock seconds] -format {%Y-%m-%d %H:%M:%S}]\t$flowid\t$txResult\t$rxResult"
        incr flowid 1
    }
}

proc x.ExecuteScenario.PrepareNetwork { scenarioPrepareObjectList scoutingTimetowait } {
#
# This method is called when the ExecuteScenario is about to start the
# Flow. When scouting frames are configured, they will be sent here.
#
# @param scenarioPrepareObjectList
#     The scenario prepare object list. The scouting streams of all
#     the objects in this list will be started.
#

    # Only wait when we actually have scouting frames to send
    set doTimetowait 0

    #--
    #-- TX SCOUTING STREAMS
    #--
    foreach flowPrepareObjectList $scenarioPrepareObjectList {
        foreach { item value } $flowPrepareObjectList {
            if { [ string equal $item "-scouting_tx" ]} {
                foreach { scoutingStream scoutingDuration } $value { break}

                # Calculate the duration
                set scoutingDuration [ expr int(ceil($scoutingDuration)) ]
                #puts "Transmitting scouting frame for ${scoutingDuration}\[ms\]"

                $scoutingStream Start

                set ::scouting_stop 0
                after $scoutingDuration { set ::scouting_stop 1 }
                vwait ::scouting_stop
                unset ::scouting_stop

                $scoutingStream Stop

                catch { unset scoutingStream } dummy
                catch { unset scoutingDuration } dummy

                set doTimetowait $scoutingTimetowait
            } else {
                error "ByteBlowerHL error: Unsupported scenario prepare item '$item'"
            }
        }
    }

    #
    # -- Wait for scoutingTimetowait
    #
    if { $doTimetowait != 0} {
        set ::scouting_stop 0
        after $doTimetowait { set ::scouting_stop 1 }
        vwait ::scouting_stop
        unset ::scouting_stop            
    }
    
}

proc x.ExecuteScenario.Finished { txPorts scenarioObjectList extended } {
#
# This method is just called when a scenario is finished, and the user didn't want to wait 
# for the results. This method will increment the variable ::ByteBlowerExcecuteScenarioDone
# and will store the result in ::ByteBlowerExecuteScenarioResult
#
# @param txPorts
#           The list of transmitting ports, to match a failing stream to its
#           source port.
#
# @param scenarioObjectList
#           The scenario object list. The counters of all the objects in this
#           list will be parsed and returned to the callback method.
#
# @param extended
#           Boolean defines extended results are requested or not. Note this can
#           be overridden using specific Tx and Rx parameters.
#

    incr ::ByteBlowerExecuteScenarioDone
    puts "TxPorts: $txPorts"
    puts "ObjectList: $scenarioObjectList"
    puts "Extended: $extended"
    eval ByteBlower Ports.Stop $txPorts
    set ::ByteBlowerExecuteScenarioResult [ x.ExecuteScenario.Results.Get $scenarioObjectList $extended ]
    x.ExecuteScenario.Cleanup $scenarioObjectList
}

proc x.ExecuteScenario.GetWirelessEndpoints { scenarioObjectList } {
    set wirelessEndpoints [ list ]
    
    foreach flow $scenarioObjectList {
        foreach { key value } $flow {
            switch -- $key {
                "-tx" -
                "-rx" {
                    if { [ TOOP Info -isobject $value ] } {
                        switch -- [ $value Get _ClassName ] {
                            "Tx.Stream.Mobile" -
                            "Rx.Trigger.Basic.Mobile" -
                            "Rx.Latency.Basic.Mobile" {
                                set parent [ $value Parent.Get ]
                                if { [ $parent Info -implements "WirelessEndpoint" ] } {
                                    if { [ lsearch wirelessEndpoints $parent ] == -1 } {
                                        lappend wirelessEndpoints $parent
                                    }
                                }
                            }
                        }
                    }  
                }
            }
        }
    }
    
    return $wirelessEndpoints
}

proc x.ExecuteScenario.ScenarioConfig.Parse { scenarioConfig extended } {
#
# This method will just parse the configurations of the flows and create the
# various TX and RX flow objects, streams and receivers respectively. It also
# calculated the duration of the scenario, based on the duration of the flows in
# it.
#
# @param scenarioConfig
#           Flow list as described in the Excecute scenario. This means it is a
#           list of flow configurations. A flow configuration is itself a list
#           of a Tx configuration and zero, one or more Rx configurations. Such
#           Tx and Rx configurations are themself lists of name-value pairs.
#
# @param extended
#           Boolean defines extended results are requested or not. Note this can
#           be overridden using specific Tx and Rx parameters.
#
# @return
#           List containing port and flow objects (oid's) and other relevant
#           information that define.
#           @list
#                   List of four elements: (1) a list of all Tx ports that will
#                   transmit flow traffic, (2) a list of all Rx ports that will
#                   receive flow traffic, (3) the duration of the test (in ns).
#                   The last element is (4) a list containing one list of flow
#                   objects for each flow. These flow objects define the flow
#                   data and consist of the Tx stream object(s) and the Rx
#                   receiver object(s).
#

    set txPorts [ list ]
    set rxPorts [ list ]
    set ::excentis::basic::rxPcapFileNames [ list ]
    set scenarioObjectList [ list ]
    set duration 0; #duration of longest flow in nanoseconds
    set scenarioPrepareObjectList [ list ]

    if { [ catch {
        foreach flowConfig $scenarioConfig {
            set flowObjectList [ list ]
            set flowPrepareObjectList [ list ]
            # parse flow parameters
            foreach {item value} $flowConfig {
                switch -- $item {
                    -tx {
                        set txParamList $value
                        # parse tx parameters and configure tx port
                        foreach { txPort stream streamDuration scoutingStreamList } [ x.ExecuteScenario.TxParam.Parse $txParamList ] break
                        lappend flowObjectList "-tx" $stream
                        foreach scoutingStreamInfo $scoutingStreamList {
                            lappend flowPrepareObjectList "-scouting_tx" $scoutingStreamInfo
                        }
                        if { $streamDuration > $duration } {
                            set duration $streamDuration
                        }
                        # keep record of unique tx ports
                        if { [lsearch $txPorts $txPort] == -1 } {
                            lappend txPorts $txPort
                        }
                    }
                    -rx {
                        set rxParamList $value
                        # parse rx parameters and configure rx ports
                        foreach { rxPort trigger } [ x.ExecuteScenario.RxParam.Parse $rxParamList $extended ] break
                        lappend flowObjectList "-rx" $trigger
                        # keep record of unique rx ports
                        if { [lsearch $rxPorts $rxPort] == -1 } {
                            lappend rxPorts $rxPort
                        }
                    }
                    default {
                        puts "ByteBlowerHL warning: Invalid flow parameter ignored: $item"
                    }
                }
            }; # end parse flow configuration
            lappend scenarioObjectList $flowObjectList
            lappend scenarioPrepareObjectList $flowPrepareObjectList
        }; # end parse scenario configuration
    } dummy ]} {
        # --- Cleanup all created objects (using 'catching' version)
        x.ExecuteScenario.Error $scenarioObjectList $dummy
    }
    return [ list $txPorts $rxPorts $duration $scenarioObjectList $scenarioPrepareObjectList ]
}

proc x.ExecuteScenario.CheckTxErrors { scenarioObjectList txPorts } {
#
# This procedure assesses the running scenario untill all the TX streams are
# running smoothly. If a TX stream could not be started, an error is thrown.
#
# @param scenarioObjectList
#           The scenario object list. The counters of all the objects in this
#           list will be parsed and returned to the callback method.
#
# @param txPorts
#           The list of transmitting ports, to match a failing stream to its
#           source port.
#
# @return
#           The amount of time passed until all TX streams are correctly
#           started. This is based on the start time of the streams. The
#           scenario takes this passed time in account when measuring how long
#           the scenario has to run further.
#
# @exception @varitem{tcl_error}
#           If a TX stream could not be started, an error is thrown.
#

    set txList [ list ]

    #--- List all the tx flows
    foreach flowObjectList $scenarioObjectList {
        foreach {item value} $flowObjectList {
            if {$item == "-tx"} {
                set flow [ list $value [expr int([ $value InitialTimeToWait.Get ] / 1e6)] ]
                lappend txList $flow
            }
        }
    }

    #--- Sort them by InitailTimeToWait
    set txList [ lsort -integer -index 1 $txList ]

    #--- Timeshift of 500ms
    set timeWaited 0
    after 500

    foreach txInfo $txList {
        set flowStream [ lindex $txInfo 0 ]
        set InitialTimeToWait [ lindex $txInfo 1 ]

        #--- Wait until this flow has started
        set stop 0
        set timer [ expr $InitialTimeToWait - $timeWaited ]
        after [ expr $timer + 500 ] set stop 1
        vwait stop

        #--- Check error
        set txError "None"
        if { [ $flowStream Info -implements Tx.Stream ]} {
            set txError [ [ $flowStream Status.Get ] ErrorStatus.Get ]
        }
        if { $txError != "None"} {
            # FOUND an ERROR on a flow
            foreach txPort $txPorts {
                foreach txPortStream [ $txPort Tx.Stream.Get ] {
                    if { $txPortStream == $flowStream} {
                        set descr [lindex [ split [ $txPort Description.Get ] "\n" ] 0 ]
                        error "ByteBlowerHL error: $txError on $descr"
                    }
                }
            }
        }
        

        #--- Update the total time spent up until this flow
        set timeWaited [ expr $timeWaited + $timer ]
    }

    #--- Return total time spent in this check method
    return $timeWaited
}

proc x.ExecuteScenario.Results.Get { scenarioObjectList extended } {
#
# This procedure gets the counter values for all the counter objects in the
# scenario and formats them according to the scenario configuration.
#
# @param scenarioObjectList
#           The scenario object list. The counters of all the objects in this
#           list will be parsed and returned as the scenario result.
#
# @param extended
#           Boolean defines extended results are requested or not. Note it is
#           used only for the TX part here. RX parts looked at extended value
#           when they were parsed.
# @return
#           The scenario result. Its structure is based on the scenario config.
#

    set wirelessEndpoints [ x.ExecuteScenario.GetWirelessEndpoints $scenarioObjectList ]
    foreach wirelessEndpoint $wirelessEndpoints {
        $wirelessEndpoint Result.Get
    }

    # Stop captures on rx ports and get counters
    set scenarioResultList [ list ]
    set captureCounter 0
    foreach flowObjectList $scenarioObjectList {
        set flowResultList [ list ]
        # Fill flow result list
        foreach {item value} $flowObjectList {
            switch -exact -- $item {
            -rx {
                if { $value != "NA"} {
                    # If the rx side has a capture active, start it.
                    # If it has another trigger, reset it.
                    if { [$value Info -implements Rx.Capture.Basic ] } {
                        $value Stop
                        lappend flowResultList "-rx" [$value Frames.Get]
                        # If we want a pcap file, we should perform this here.
                        set fileName [ lindex $::excentis::basic::rxPcapFileNames $captureCounter ]
                        if { $fileName != "" } {
                            $value Pcap.Save $fileName
                        }
                        incr captureCounter 1
                    } elseif { [$value Info -implements Rx.Trigger.SizeDistribution ] } {
                        #SizeDistribution triggers do not support Result yet!
                        set result [ $value Result.Get ]
                        set counters [ list ]
                        lappend counters NrOfFrames [ $result PacketCount.Get ]
                        lappend counters NrOfOctets [ $result ByteCount.Get ]
                        lappend counters NrOfUndersized [ $result PacketCount.BelowMinimum.Get ]
                        lappend counters NrOfOversized [ $result PacketCount.AboveMaximum.Get]
                        lappend flowResultList "-rx" $counters
                    } elseif { [$value Info -implements Rx.Latency.Basic ] || \
                               [$value Info -implements Rx.Latency.Basic.Mobile ] } {
                        set result [ $value Result.Get ]
                        $result Refresh
                        
                        set packetcount [$result PacketCount.Get]
                        set latencyminimum 0
                        set latencymaximum 0
                        set latencyaverage 0
                        set jitter 0
                        if { $packetcount != 0 } {
                            set latencyminimum [$result Latency.Minimum.Get]
                            set latencymaximum [$result Latency.Maximum.Get]
                            set latencyaverage [$result Latency.Average.Get]
                            set jitter [ $result Jitter.Get ]
                        }
                        
                        lappend flowResultList "-rx" [ list \
                                                        NrOfFrames $packetcount \
                                                        MinLatency $latencyminimum \
                                                        AvgLatency $latencyaverage \
                                                        MaxLatency $latencymaximum \
                                                        Jitter $jitter \
                                                    ]
                        $result Destructor
                    } elseif { [$value Info -implements Rx.OutOfSequence.Basic ] } {
                        set result [ $value Result.Get ]
                        $result Refresh
                        set rxFrames [ $result PacketCount.Get ]
                        
                        set rxOoS 0
                        if { $rxFrames != 0 } {
                            set rxOoS [ $result PacketCount.OutOfSequence.Get ]
                        }
                        
                        lappend flowResultList "-rx" [ list \
                                                        FramesOutOfSequence $rxOoS \
                                                        NrOfFrames $rxFrames \
                                                     ]
                        $result Destructor
                    } else {
                        set result [$value Result.Get]
                        $result Refresh
                        lappend flowResultList "-rx" [ list \
                                                        NrOfFrames [ $result PacketCount.Get ] \
                                                        NrOfOctets [ $result ByteCount.Get ] \
                                                     ]
                        $result Destructor
                    }
                } else {
                    lappend flowResultList "-rx" "NA"
                }
            }
            -tx {
                if { $extended == 0 } {
                    set result [$value Result.Get]
                    $result Refresh
                    lappend flowResultList "-tx" [ list NrOfFramesSent [ $result PacketCount.Get ] ]
                   $result Destructor
                } else {
                    set result [$value Result.Get]
                    $result Refresh
                    set output [ list NrOfFramesSent [ $result PacketCount.Get ] NrOfOctetsSent [ $result ByteCount.Get ] ]
                    # TODO: Add SizeDistribution...
                    

                    foreach frame [ $value Frame.Get ] {
                        set frameOut [ list ]
                        set frameResult  [ $frame Result.Get ]
                        lappend frameOut "NrOfFrames" [ $frameResult PacketCount.Get ]
                        lappend frameOut "NrOfOctets" [ $frameResult ByteCount.Get ]
                        
                        # Mobile frames only have a limited set of counters
                        if { ![ $frame Info -implements Frame.Mobile ] } {
                            lappend frameOut "FrameSizeMinimum" [ $frameResult Framesize.Minimum.Get ]
                            lappend frameOut "FrameSizeMaximum" [ $frameResult Framesize.Maximum.Get ]
                        }                            
                        lappend output $frame $frameOut

                    }
                    
                    lappend flowResultList "-tx" $output
                }

                # Add error info the result list
                # If a server error can be seen, include it
                # If not check manually for possible other (unexpected) errors
                set txError "None"
                if { [ $value Info -implements Tx.Stream ] } {
                    set txError [ [ $value Status.Get ] ErrorStatus.Get ]
                }
                if { $txError != "None" } {
                    lappend flowResultList "-error" $txError
                } else {
                    # Throughput too high for Tx side?
                    set result [$value Result.Get]
                    $result Refresh
                    set framesSent [ $result PacketCount.Get ]
                    set framesRequested [ $value NumberOfFrames.Get ]
                    if { $framesSent < $framesRequested } {
                        lappend flowResultList "-error" "UnexpectedOutOfResources"
                    }
                   $result Destructor
                }
            }
            default {
                puts "ByteBlowerHL warning: Unknown flow parameter: '$item', not getting results for '$value'"
            }
            }
        }

        # Add flow result list to the main list
        lappend scenarioResultList $flowResultList
    }
    return $scenarioResultList
}

proc x.ExecuteScenario.Timestamp.Next.Get { scenarioObjectList prevTimestamp updateinterval } {
    if { $prevTimestamp == 0} {
        # search the initial timestamp  
        # this is the first timestamp all history objects know + updateinterval(seconds) buckets
        set timestamp 0
        set historyObjects [ list ]
        foreach flowObjectList $scenarioObjectList {
            foreach {item value} $flowObjectList {
                switch -exact -- $item {
                -rx {
                    if { $value != "NA"} {
                        if { [$value Info -implements Rx.Trigger.Basic ] } {    
                            set resultHistory [ $value Result.History.Get ]
                            $resultHistory Refresh
                            lappend historyObjects $resultHistory
                        }
                    } 
                }
                -tx {
                    set resultHistory [ $value Result.History.Get ]
                    $resultHistory Refresh
                    lappend historyObjects $resultHistory
                }
                default {
                    puts "ByteBlowerHL warning: Unknown flow parameter: '$item', not getting next timestamp for '$value'"
                }
                }
            }
        }
        

        
        set first_ho [ lindex $historyObjects 0 ]
        foreach fhob [ $first_ho Cumulative.Get ] {
            set bts [ $fhob Timestamp.Get ]
            
            set all_hobs_found 1
            foreach ho [ lrange $historyObjects 1 end ] {
                set hob_found  0
                foreach hob [ $ho Cumulative.Get ] {
                    if { $bts == [ $hob Timestamp.Get ]} {
                        set hob_found 1
                        break;
                        #found in this history object
                    }
                }
                if { $hob_found == 0} {
                    set all_hobs_found 0
                }
            }
            if { $all_hobs_found == 0} {
                continue
            } else {
                return [ expr $bts + ( $updateinterval * 1000000 ) ]
            }
            
        }

        
    }  else {
        return [ expr $prevTimestamp + ( $updateinterval * 1000000 ) ]
    }
    

    
    
    
    return $timestamp
}

proc x.ExecuteScenario.Bucket.Search { bucketlist timestamp  } {
#
# This procedure searches the next bucket to check in the bucketlist
#
# @return
#     the next bucket object


    foreach bucket $bucketlist {
        if { [ $bucket Timestamp.Get ] == $timestamp} {
            return $bucket
        }
    }
    
}

proc x.ExecuteScenario.InterRunResults.Get { scenarioObjectList txPorts extended timestamp } {
#
# This procedure gets the real-time counter values for all the counter objects
# in the scenario and formats them according to the scenario configuration.
# It also looks if all TX streams are still running and gives an error if one
# has failed.
#
# @param scenarioObjectList
#     The scenario object list. The counters of all the objects in this list
#     will be parsed and returned to the callback method.
#
# @param txPorts
#           The list of transmitting ports, to match a failing stream to its
#           source port.
#
# @param extended
#           Boolean defines extended results are requested or not. Note it is
#           used only for the TX part here. RX parts looked at extended value
#           when they were parsed.
#
# @param timestamp
#     Timestamp of the snapshot to search. If the snapshot is not available,
#     we will use the latest available snapshot.
#
# @return
#           A real-time result. Its structure is based on the scenario config.
#
# @exception @varitem{tcl_error}
#           If a TX stream has failed at this time, an error is thrown.
#
    
    set scenarioResultList [ list ]
    
    
    foreach flowObjectList $scenarioObjectList {
        set flowResultList [ list ]
        foreach {item value} $flowObjectList {
            switch -exact -- $item {
            -rx {
                if { $value != "NA"} {
                    if { [$value Info -implements Rx.Capture.Basic ] } {
                        #  The -rx value is a RX Capture
                        lappend flowResultList "-rx" [$value Frames.Get]    
                                            
                    } elseif { [$value Info -implements Rx.Trigger.Basic ] } {    
                        # The -rx Value is a RX Basic trigger
                        # use the ResultHistory to fetch the latest "Cumulative
                        # Result" to add as numRx entry
                        set resultHistory [ $value Result.History.Get ]
                        

                        $resultHistory Refresh
                        
                        set buckets [ $resultHistory Cumulative.Get ]
                        set the_bucket [ x.ExecuteScenario.Bucket.Search $buckets $timestamp ]
                        if { $the_bucket == "" } {
                            set the_bucket [ lindex $buckets end ]
                        }
                        set rxFrames [ $the_bucket PacketCount.Get ]

                        lappend flowResultList "-rx" [ list "NrOfFrames" $rxFrames ]
                    } elseif { [ $value Info -implements Rx.Trigger.Basic.Mobile ] } {
                        # we don't have temporary results.  Omit it...
                        lappend flowResultList "-rx" [ list "NrOfFrames" 0 ]
                    } elseif { ![$value Info -implements Rx.Trigger.SizeDistribution ] } {   
                        # Not trigger basic, not capture, not sizedistribution...
                        set result [ $value Result.Get ]
                        $result Refresh
                        lappend flowResultList "-rx" [ list "NrOfFrames" [ $result PacketCount.Get ] ]
                        $result Destructor
                    
                    } else {

                        # SizeDistribution                        
                        set result [ $value Result.Get ]
                        $result Refresh
                        
                        set output [ list "NrOfFrames" [ $result PacketCount.Get ] ]
                        lappend output "NrOfOctets" [ $result ByteCount.Get ]
                        lappend output "NrOfUndersized" [ $result PacketCount.BelowMinimum.Get ]
                        lappend output "NrOfOversized" [ $result PacketCount.AboveMaximum.Get ]
                        lappend flowResultList "-rx" $output
                    }
                } else {
                    lappend flowResultList "-rx" "NA"
                }
            }
            -tx {
                if { $extended == 0 } {
                    
                    set resultHistory [ $value Result.History.Get ]
                    

                    $resultHistory Refresh
                    
                    set buckets [ $resultHistory Cumulative.Get ]
                    set the_bucket [ x.ExecuteScenario.Bucket.Search $buckets $timestamp ]
                    if { $the_bucket == "" } {
                        set the_bucket [ lindex $buckets end ]
                    }
                    set txFrames [ $the_bucket PacketCount.Get ]
                    
                    
                    
                    lappend flowResultList "-tx" [ list "NrOfFramesSent" $txFrames ]
                    #lappend flowResultList "-tx" [ $value Counters.Brief.Get ]
                    
                } else {
                    set result [$value Result.Get]
                    $result Refresh
                    set output [ list NrOfFramesSent [ $result PacketCount.Get ] ]
                    # TODO: Add SizeDistribution...
                    lappend flowResultList "-tx" $output
                }
                # --- Check error
                set txError "None"
                if { [ $value Info -implements Tx.Stream ] } {
                    set txError [ [ $value Status.Get ] ErrorStatus.Get ]
                }
                if { $txError != "None" } {
                    # FOUND an ERROR on a flow
                    foreach txPort $txPorts {
                        foreach txPortStream [ $txPort Tx.Stream.Get ] {
                            if { $txPortStream == $value } {
                                set descr [lindex [ split [ $txPort Description.Get ] "\n" ] 0 ]
                                error "ByteBlowerHL error: $txError on $descr"
                            }
                        }
                    }
                }
            }
            default {
                puts "ByteBlowerHL warning: Unknown flow parameter: '$item', not getting inter-run results for '$value'"
            }
            }
        }
        lappend scenarioResultList $flowResultList
    }
    return $scenarioResultList 
}

proc x.ExecuteScenario.Cleanup { scenarioObjectList } {
#
# Cleans up the objects created during this scenario. This way, the port objects
# are as clean as before the scenario was started.
#
# @param scenarioObjectList
#           The scenario object list. All the objects in this list will be
#           destroyed.
#
    # Retrieve the Wireless Endpoints
    set wirelessEndpoints [ x.ExecuteScenario.GetWirelessEndpoints $scenarioObjectList ]
    
    
    foreach flowObjectList $scenarioObjectList {
        foreach {item value} $flowObjectList {
            switch -exact -- $item {
            -tcp {
                foreach {tcpitem tcpvalue} $value {
                    catch { $tcpvalue Destructor } dummy
                }
            }
            -scouting_tx {
                foreach { scoutingStream scoutingDuration } $value { break }
                catch { $scoutingStream Destructor } dummy
            }
            -rx -
            -tx {
                catch { $value Destructor } dummy
            }
            default {
                puts "ByteBlowerHL warning: Unknown flow parameter: '$item', calling Destructor on '$value'"
                catch { $value Destructor } dummy
            }
            }
        }
    }
    
    foreach wirelessEndpoint $wirelessEndpoints {
        catch { $wirelessEndpoint Result.Clear } 
        catch { $wirelessEndpoint Lock 0 } 
    }
}

proc x.ExecuteScenario.Error { scenarioObjectList errorInfo } {
#
# Handles an error that occured during scenario execution. Specifically, this
# procedure calls the destructor on all object created during the execution,
# so the port objects are as clean as before the scenario was started.
#
# @param scenarioObjectList
#           The scenario object list. All the objects in this list will be
#           destroyed.
#
# @param errorInfo
#           The caught error information.
#
# @exception @varitem{tcl_error}
#           The original error is rethrown after cleanup.
#

    x.ExecuteScenario.Cleanup $scenarioObjectList

    error $errorInfo
}

proc x.ExecuteScenario.TxParam.Parse { txParamList } {
#
# Parses the Tx port parameters and configures the specified port according to
# them.If not all parameters are given, the defaults will be used.
#
# @param txParamList
#           The TX part configuration of a flow.
#
# @return
#           The Tx side objects (oid's) that were created using the parameters
#           and other relevant information.
#           @list
#                   List of three elements: (1) the configured Tx port object,
#                   (2) the Tx stream object, (3) the duration of this flow
#                   (in nanoseconds) and (4) the list of scouting frame stream info.
#

    # set default tx parameters
    set txPort ""
    set portFound 0

    set srcFrameList [ list ]
    set numberOfFrames 100; set interframegap 10000000; set initialTimeToWait 0
    set timingModifier "none"; set frameModifier "none"
    set latencyEnable 0; set outOfSequenceEnable 0

    set srcScoutingFrameList [ list ]
    set scoutingNumberOfFrames 2; set scoutingInitialTimeToWait 0
    set scoutingInterframegap 10000000 ;# 10[ms]
    set scoutingStreamLeadOutTime 100000000 ;# [100ms]

    set scoutingStreamList [ list ]

    # parse tx parameters
    #puts "TxParam.Parse: txParamList: $txParamList"
    foreach {item value} $txParamList {
        #puts "TxParam.Parse: Parsing item $item with value $value"
        switch -- $item {
            -port {
                if { ! $portFound } {
                    set portFound 1
                    set txPort $value
                } else {
                    error "ByteBlowerHL error: Only 1 tx port allowed per tx port parameter list"
                }
            }
            -frame             { lappend srcFrameList $value }
            -numberofframes    { set numberOfFrames $value }
            -interframegap     { set interframegap $value }
            -initialtimetowait { set initialTimeToWait $value }
            -framemodifier     { 
                if { $frameModifier == "none" } {
                    set frameModifier $value 
                } else {
                    error "ByteBlowerHL error: Only 1 FrameModifier per frame is allowed"
                }
            }
                        
            -timingmodifier    { set timingModifier $value }
            -latency           { set latencyEnable $value }
            -outofsequence     { set outOfSequenceEnable $value }
            -scoutingframe     { lappend srcScoutingFrameList $value }
            -scoutinginterframegap { set scoutingInterframegap $value }
            default            { error "ByteBlowerHL error: Invalid tx port parameter: $item" }
        }
    }

    if { ! $portFound} {
        error "ByteBlowerHL error: No tx port found in flow parameter list"
    }
    if { $numberOfFrames < 0} {
        error "ByteBlowerHL error: Tx port parameter <numberofframes> must be a positive integer"
    }

    # create and configure the stream for scouting frames
    foreach srcScoutingFrame $srcScoutingFrameList {
        set scoutingStream [ $txPort Tx.Stream.Add ]

        #puts "TxParam.Parse: Creating scouting frame for $srcScoutingFrame"
        set scoutingFrameObject [ x.ExecuteScenario.TxParam.ScoutingFrame.Parse $scoutingStream $srcScoutingFrame ]

        $scoutingStream InitialTimeToWait.Set $scoutingInitialTimeToWait
        $scoutingStream InterFrameGap.Set $scoutingInterframegap
        $scoutingStream NumberOfFrames.Set $scoutingNumberOfFrames

        # calculate total scouting stream duration in milliseconds
        set scoutingDuration [ expr ( [ $scoutingStream InitialTimeToWait.Get ] / 1e6 ) + ( [ $scoutingStream InterFrameGap.Get ] / 1e6 * [ $scoutingStream NumberOfFrames.Get ] ) + ( $scoutingStreamLeadOutTime / 1e6 ) ]

        lappend scoutingStreamList [ list $scoutingStream $scoutingDuration ]
    }

    # create and configure the stream
    set stream [$txPort Tx.Stream.Add]
    foreach srcFrame $srcFrameList {
        #puts "TxParam.Parse: Creating frame for $srcFrame"
        set frameObject [ x.ExecuteScenario.TxParam.Frame.Parse $stream $srcFrame ]
        if {$latencyEnable == 1} {
            [ $frameObject FrameTag.Time.Get ] Enable 1
        } elseif {$latencyEnable == 0} {
            #do nothing
        } else {
            error "ByteBlowerHL error: Invalid latency flag: $latencyEnable"
        }
        if {$outOfSequenceEnable == 1} {
            [ $frameObject FrameTag.Sequence.Get ] Enable 1
        } elseif {$outOfSequenceEnable == 0} {
            #do nothing
        } else {
            error "ByteBlowerHL error: Invalid out-of-sequence flag: $outOfSequenceEnable"
        }
    }
    $stream InitialTimeToWait.Set $initialTimeToWait
    $stream InterFrameGap.Set $interframegap
    $stream NumberOfFrames.Set $numberOfFrames

    # calculate total flow duration in milliseconds
    set duration [expr ([$stream InitialTimeToWait.Get]/1e6) + ([$stream InterFrameGap.Get] / 1e6 * $numberOfFrames)]

    # apply the provided frame and/or time modifiers
    if { $frameModifier != "none"} {
        set frameMod [ x.ExecuteScenario.TxParam.FrameModifier.Parse $stream $frameModifier ]
    }
    if { $timingModifier != "none"} {
        set timingModifierObject [ x.ExecuteScenario.TxParam.TimingModifier.Parse $stream $timingModifier ]
        # adjust total flow duration for interburstgap
        if { [ string compare [ $timingModifierObject Get _ClassName ]  TimingModifier.MultiBurst ] ==  0} {
            set nofInterBurstGap [expr $numberOfFrames / [$timingModifierObject BurstSize.Get]]
            if {[expr fmod($numberOfFrames,[$timingModifierObject BurstSize.Get])] == 0} {
                incr nofInterBurstGap -1
            }
            set duration [expr $duration + ($nofInterBurstGap * [$timingModifierObject InterBurstGap.Get]/1e6)]
        }
    }

    # return the flow and its duration
    return [ list $txPort $stream $duration $scoutingStreamList ]
}

proc x.ExecuteScenario.TxParam.Frame.Parse { stream frameDescription } {
    if { [ string range [ lindex $frameDescription 0 ] 0 0 ] != "-"} {
        # old behaviour
        puts "ByteBlowerHL warning: Creating a frame using -frame { byte byte byte } which will be deprecated, please use -frame { -bytes { byte byte byte ... } }"
        set frame [ $stream Frame.Add ]
        $frame Bytes.Set $frameDescription
        return $frame
    }
    
    # new behaviour
    set bytes [ list ]
    set payload [ list ]
    set destinationAddress ""
    set sourcePort 0
    set destinationPort 0
    set sizemodifier "none"
    set fieldmodifiers [ list ]
    set l3autochecksum 0
    set l3autolength 0
    set l4autochecksum 0
    set l4autolength 0
    
    foreach { item value } $frameDescription {
        #puts "TxParam.Frame.Parse: Parsing $item with value $value"
        switch -- $item {
            -bytes {
                set bytes $value
            }
            -payload {
                set payload $value
            }
            -sourcePort {
                set sourcePort $value
            }
            -destinationPort {
                set destinationPort $value
            }
            -destinationAddress {
                set destinationAddress $value
            }
            
            -sizemodifier {
                if { $sizemodifier != "none" } {
                    error "ByteBlowerHL error: Only one size modifier is allowed per frame."
                }
                set sizemodifier $value
            }
            
            -fieldmodifier {
                lappend fieldmodifiers $value
            }
            -l3autochecksum {
                set l3autochecksum $value
            }
            -l3autolength {
                set l3autolength $value
            }
            -l4autochecksum {
                set l4autochecksum $value
            }
            -l4autolength {
                set l4autolength $value
            }            
            default {
                error "ByteBlowerHL error: Unknown frame descriptor: $item $value."
            }
        }
    }
    
    if { [ llength $bytes ] == 0 && [ llength $payload ] == 0} {
        error "ByteBlowerHL error: either -bytes or -payload must be given when creating a frame."
    }
    
    if { [ llength $bytes ] != 0 && [ llength $payload ] != 0} {
        error "ByteBlowerHL error: only one of -bytes and -payload must be given when creating a frame."
    }
    
    if { [ llength $payload ] != 0 && ( $sourcePort == 0 || $destinationPort == 0 || $destinationAddress == "" )} {
        error "ByteBlowerHL error: when using -payload, -sourcePort, -destinationPort and -destinationAddress must also be given!"
    }
    
    
    set frame [ $stream Frame.Add ]
    #puts "TxParam.Frame.Parse: Setting bytes $bytes"
    if { [ llength $bytes ] != 0} {
        if { ! [ $stream Info -implements Tx.Stream ]} {
            error "ByteBlowerHL error: -bytes can only be used on a ByteBlowerPort"
        }
        $frame Bytes.Set $bytes
    } elseif { [ llength $payload ] != 0} {
        if { ! [ $stream Info -implements Tx.Stream.Mobile ]} {
            error "ByteBlowerHL error: -payload can only be used on a Wireless Endpoint"
        }
    
        $frame Payload.Set $payload
        $stream Source.Port.Set $sourcePort
        $stream Destination.Port.Set $destinationPort
        $stream Destination.Address.Set $destinationAddress
    }
    
    if { ![ string equal $sizemodifier "none" ]} {
        #puts "TxParam.Frame.Parse: Parsing size modifier $sizemodifier"
        x.ExecuteScenario.TxParam.FrameSizeModifier.Parse $frame $sizemodifier
    }
    
    foreach fieldmodifier $fieldmodifiers {
        #puts "TxParam.Frame.Parse: Parsing field modifier $fieldmodifier"
        x.ExecuteScenario.TxParam.FrameFieldModifier.Parse $frame $fieldmodifier
    }

    if { $l3autochecksum} {
        $frame L3.Auto.Checksum.Enable 1
    }
    if { $l3autolength} {
        $frame L3.Auto.Length.Enable 1
    }
    if { $l4autochecksum} {
        $frame L4.Auto.Checksum.Enable 1
    }
    if { $l3autolength} {
        $frame L4.Auto.Length.Enable 1
    }




    #puts "TxParam.Frame.Parse: Done"
    return $frame
}

proc x.ExecuteScenario.TxParam.ScoutingFrame.Parse { scoutingStream frameDescription } {
#
#
# @param scoutingStream
#     Stream to configure the scouting frame on
#
# @param frameDescription
#     -bytes
#         Frame content
#     -l3autochecksum
#         Enable automatic Layer3 checksum correction
#         Default: enabled (1)
#     -l3autolength
#         Enable automatic Layer3 length correction
#         Default: enabled (1)
#     -l4autochecksum
#         Enable automatic Layer4 checksum correction
#         Default: enabled (1)
#     -l4autolength
#         Enable automatic Layer4 length correction
#         Default: enabled (1)
#

    set bytes [ list ]
    set l3autochecksum 1
    set l3autolength 1
    set l4autochecksum 1
    set l4autolength 1

    foreach { item value } $frameDescription {
        #puts "TxParam.ScoutingFrame.Parse: Parsing $item with value $value"
        switch -- $item {
            -bytes {
                set bytes $value
            }
            -l3autochecksum {
                set l3autochecksum $value
            }
            -l3autolength {
                set l3autolength $value
            }
            -l4autochecksum {
                set l4autochecksum $value
            }
            -l4autolength {
                set l4autolength $value
            }
            default {
                error "ByteBlowerHL error: Unknown frame descriptor: $item $value."
            }
        }
    }

    if { [ llength $bytes ] == 0} {
        error "ByteBlowerHL error: -bytes must be given when creating a frame."
    }

    set scoutingFrame [ $scoutingStream Frame.Add ]
    #puts "TxParam.ScoutingFrame.Parse: Setting bytes $bytes"
    $scoutingFrame Bytes.Set $bytes

    if { $l3autochecksum} {
        $scoutingFrame L3.Auto.Checksum.Enable 1
    }
    if { $l3autolength} {
        $scoutingFrame L3.Auto.Length.Enable 1
    }
    if { $l4autochecksum} {
        $scoutingFrame L4.Auto.Length.Enable 1
    }
    if { $l3autolength} {
        $scoutingFrame L4.Auto.Checksum.Enable 1
    }

    #puts "TxParam.ScoutingFrame.Parse: Done"
    return $scoutingFrame
}

proc x.ExecuteScenario.TxParam.FrameFieldModifier.Parse { frame fieldModifier } {
#
# Parses the arguments specific for a frame field modifier option and creates a
# frame modifier using that configuration.
#
# @param frame
#           The frame object (oid) on which the size modifier should be
#           applied.
# @param frameModifier
#           The frame modifier configuration.
# @return
#           The frame modifier object (oid)
#
    set type "none"
    set offset 58
    set length 2
    set minimum 0
    set maximum 65535
    set step 1
    set initialvalue 0
    
    foreach {item value} $fieldModifier {
        switch -- $item {
            -type {
                set type $value
            }
            -offset {
                set offset $value
            }
            -length {
                set length $value
            }
            -minimum {
                set minimum $value
            }
            -maximum {
                set maximum $value
            }
            -step {
                set step $value
            }
            -initialvalue {
                set initialvalue $value
            }
            default {
                error "ByteBlowerHL error: Unknown configuration item for a FrameFieldModifier $item $value"
            }
        }
    }
    
    switch -- $type {
    incremental -
    random {
        set modifier [ $frame Modifier.Field.[ string totitle $type ].Add ]
    }
    none {
        error "ByteBlowerHL error: -type must be given in the FrameFieldModifier configuration"
    }
    default {
        error "ByteBlowerHL error: Unknown Frame Field Modifier type $type"
    }
    }

    $modifier Offset.Set $offset
    $modifier Length.Set $length
    $modifier Minimum.Set $minimum
    $modifier Maximum.Set $maximum
    
    switch -- $type {
    incremental {
        $modifier Step.Set $step
        $modifier InitialValue.Set $initialvalue
    }
    random {
        # nothing else to do
    }
    }

    return $modifier

}

proc x.ExecuteScenario.TxParam.FrameSizeModifier.Parse { frame frameModifier } {
#
# Parses the arguments specific for a frame size modifier Tx option and creates a
# frame modifier using that configuration.
#
# @param frame
#           The frame object (oid) on which the size modifier should be
#           applied.
# @param frameModifier
#           The frame modifier configuration.
# @return
#           The frame modifier object (oid)
#

    if { ![ string equal $frameModifier "none" ]} {
        # set default parameters
        set type ""
        set typeFound 0
        set minimum 60; set maximum 1514; set step 1; set iteration 1

        # parse parameters
        foreach {item value} $frameModifier {
            switch -- $item {
                -type {
                    if { ! $typeFound } {
                        set typeFound 1
                        set type [string tolower $value]
                    } else {
                        error "ByteBlowerHL error: Only 1 type allowed per frame size modifier parameter list"
                    }
                }
                -minimum   { set minimum $value }
                -maximum   { set maximum $value }
                -step      { set step $value }
                -iteration { set iteration $value }
                default    { error "ByteBlowerHL error: Invalid frame size modifier parameter: $item"}
            }
        }
        
        if { ! $typeFound} {
            error "ByteBlowerHL error: No type found in frame size modifier parameter list"
        }

        
        # configure the flow
        set frameModifierObjects [ list ]
        switch -- $type {
            random {
                set frameModifierObject [ $frame Modifier.Size.Random.Set ]
                $frameModifierObject Minimum.Set $minimum
                $frameModifierObject Maximum.Set $maximum
            }
            growing {
                set frameModifierObject [ $frame Modifier.Size.Growing.Set ]
                $frameModifierObject Minimum.Set $minimum
                $frameModifierObject Maximum.Set $maximum
                $frameModifierObject Iteration.Set $iteration
                $frameModifierObject Step.Set $step
            }
            default { error "ByteBlowerHL error: Unknown frame size modifier type: $type" }
        }
        lappend frameModifierObjects $frameModifier


        # return the frame modifier
        return $frameModifierObjects
    }
}

proc x.ExecuteScenario.TxParam.FrameModifier.Parse { stream frameModifier } {
#
# Parses the arguments specific for a framemodifier Tx option and creates a
# frame modifier using that configuration.
#
# @deprecated
# 
# @param stream
#           The stream object (oid) on which the frame modifier should be
#           applied.
# @param frameModifier
#           The frame modifier configuration.
# @return
#           The frame modifier object (oid)
#
    puts "\[DEPRECATED\] Creating a FrameModifier on a stream is deprecated!  Please create the SizeModifier on a frame."
    foreach frame [ $stream Frame.Get ] {
        x.ExecuteScenario.TxParam.FrameSizeModifier.Parse $frame $frameModifier
    }
    return
}

proc x.ExecuteScenario.TxParam.TimingModifier.Parse { stream timingModifier } {
#
# Parses the arguments specific for a timingmodifier Tx option and creates a
# timing modifier using that configuration.
#
# @param stream
#           The stream object (oid) on which the timing modifier should be
#           applied.
# @param frameModifier
#           The timing modifier configuration.
# @return
#           The timing modifier object (oid)
#

    if { ($timingModifier != "none")} {
        # set default parameters
        set type ""; 
        set typeFound 0;
        set burstSize 100; set interBurstGap 1000000000;

        # parse parameters
        foreach {item value} $timingModifier {
            switch -- $item {
                -type {
                    if { ! $typeFound } {
                        set typeFound 1
                        set type [string tolower $value]
                    } else {
                        error "ByteBlowerHL error: Only 1 type allowed per timing modifier parameter list"
                    }
                }
                -burstsize     { set burstSize $value }
                -interburstgap { set interBurstGap $value }
                default        { error "ByteBlowerHL error: Invalid timing modifier parameter: $item" }
            }
        }
        
        if { ! $typeFound} {
            error "ByteBlowerHL error: No type found in timing modifier parameter list"
        }

        # configure the flow
        set timingModifierObject [ $stream Modifier.Timing.Set $type ]
        switch -- $type {
            multiburst {
                $timingModifierObject BurstSize.Set $burstSize
                $timingModifierObject InterBurstGap.Set $interBurstGap
            }
            default { error "ByteBlowerHL error: Unknown timing modifier type: $type" }
        }

        # return the timing modifier
        return $timingModifierObject
    }
}

proc x.ExecuteScenario.RxTupleFilter.Parse { triggerObject filter } {
    set remoteIP ""
    set remoteUdpPort ""
    set localUdpPort ""
    
    foreach  { field value } $filter {
        switch -- [ string tolower $field ] {
            "-sourceaddress" { set remoteIP $value }
            "-udpdestinationport" { set localUdpPort $value }
            "-udpsourceport" { set remoteUdpPort $value }
            default {
                error "ByteBlowerHL error: filter format $filterFormat does not support $field"
            }
        }
    }
    
    if { $remoteIP == "" || $remoteUdpPort == "" || $localUdpPort == ""} {
        error "ByteBlowerHL error: filter format syntax error: all entries of -sourceaddress, -udpdestinationport and -udpsourceport are required!"
    }
    
    $triggerObject Filter.SourceAddress.Set $remoteIP
    $triggerObject Filter.Udp.DestinationPort.Set $localUdpPort
    $triggerObject Filter.Udp.SourcePort.Set $remoteUdpPort

}

proc x.ExecuteScenario.RxParam.Parse { rxParamList extended } {
#
# @brief Parses the Rx port parameters and configures the specified port with either a 
#        trigger, a latency or out-of-sequence detector or a capture tool.
#
# Only one such specifier (trigger/latency/outofsequence/capture) is allowed per
# Rx parameter list. Multiple Rx parameter lists on the same port are possible
# however.
#
# @note The receiver will not yet be started; it will not yet listen to incoming
#       data.
#
# @param rxParamList
#           A declarative RX component configuration.
#
# @param extended
#           Boolean defining whether extended results are requested or not.
#           The flag only affects default values, and thus can always be overridden by RX parameters.
#
# @return
#           The RX component objects that were created using the Rx component configuration.
#           This is a list of two elements: the port object and the incoming packet processor object.
#

    # set default rx parameters
    set rxPort ""
    set portFound 0
    set trigger ""; set latency ""; set outofsequence ""; set capture ""
    set receiverFound 0

    # parse rx parameters
    #puts "rxParamList: $rxParamList"
    foreach {item value} $rxParamList {
        switch -- $item {
            -port {
                if { ! $portFound } {
                    set portFound 1
                    set rxPort $value
                } else {
                    error "ByteBlowerHL error: Only 1 rx port allowed per rx port parameter list"
                }
            }
            -trigger {
                if { ! $receiverFound } {
                    set receiverFound 1
                    set trigger $value
                } else {
                    error "ByteBlowerHL error: Only 1 trigger/latency/outofsequence/capture allowed per rx port parameter list"
                }
            }
            -latency {
                if { ! $receiverFound } {
                    set receiverFound 1
                    set latency $value
                } else {
                    error "ByteBlowerHL error: Only 1 trigger/latency/outofsequence/capture allowed per rx port parameter list"
                }
            }
            -outofsequence {
                if { ! $receiverFound } {
                    set receiverFound 1
                    set outofsequence $value
                } else {
                    error "ByteBlowerHL error: Only 1 trigger/latency/outofsequence/capture allowed per rx port parameter list"
                }
            }
            -capture {
                if { ! $receiverFound } {
                    set receiverFound 1
                    set capture $value
                } else {
                    error "ByteBlowerHL error: Only 1 trigger/latency/outofsequence/capture allowed per rx port parameter list"
                }
            }
            default {
                error "ByteBlowerHL error: Invalid rx port parameter: $item"
            }
        }
    }

    if { ! $portFound} {
        error "ByteBlowerHL error: No rx port found in flow parameter list"
    }

    # parse trigger settings, configure trigger object and return it
    if { $trigger != ""} {
        set filter ""
        set filterFormat "display"
        set duration 0
        if { ! $extended} {
            set type "basic"
        } else {
            set type "sizedistribution"
        }
        foreach {item value} $trigger {
            switch -- $item {
                -type         { set type $value }
                -filterFormat { set filterFormat $value }
                -filter       { set filter $value }
                -duration     { set duration $value }
                default       { error "ByteBlowerHL error: Invalid trigger parameter: $item" }
            }
        }
        if { $filter == ""} {
            error "ByteBlowerHL error: Please define a non-empty filter for the trigger option of the rx port"
        }
        set triggerObject ""
        switch -- $type {
            "basic" { set triggerObject [ $rxPort Rx.Trigger.Basic.Add ] }
            "sizedistribution" { 
                if { [ $rxPort Info -implements WirelessEndpoint ] } {
                    error "ByteBlowerHL error: sizedistribution trigger not supported by a WirelessEndpoint!"
                }
                set triggerObject [ $rxPort Rx.Trigger.SizeDistribution.Add ] 
            }
            default { error "ByteBlowerHL error: Invalid trigger type: $type" }
        }
        switch -- $filterFormat {
            display { $triggerObject Filter.Set [ ::excentis::basic::ParseFilter $filter ] }
            bpf     { $triggerObject Filter.Set $filter }
            tuple {  
                if { ! [ $rxPort Info -implements WirelessEndpoint ] } {
                    error "ByteBlowerHL error: filter format $filterFormat not supported by object of type [ $rxPort Get _ClassName ]"
                }
                
                x.ExecuteScenario.RxTupleFilter.Parse $triggerObject $filter
                
            }
            default { error "ByteBlowerHL error: FilterType on rx port must be bpf, display or tuple" }
        }
        
        if { $duration != 0} {
            if { [ $rxPort Info -implements WirelessEndpoint ]} {
                $triggerObject Duration.Set $duration
            } else {
                default { error "ByteBlowerHL error: -duration can only be set on Wireless Endpoints!" }
            }
        }

        return [ list $rxPort $triggerObject ]
    }

    # parse latency settings, configure latency object and return it
    if { $latency != ""} {
        set filter ""
        set filterFormat "display"
        set duration 0
        if { ! $extended} {
            set type "basic"
        } else {
            set type "distribution"
        }
        foreach {item value} $latency {
            switch -- $item {
                -type   { set type $value }
                -filterFormat { set filterFormat $value }
                -filter { set filter $value }
                -duration { set duration $value }
                default { error "ByteBlowerHL error: Invalid latency parameter: $item" }
            }
        }
        if { $filter == ""} {
            error "ByteBlowerHL error: Please define a non-empty filter for the latency option of the rx port"
        }
        switch -- [ string tolower $type ] {
            basic -
            distribution { set latencyObject [ $rxPort Rx.Latency.[ string totitle $type ].Add ] }
            default { error "ByteBlowerHL error: Unsupported latency type '${type}'" }
        }
        
        switch -- $filterFormat {
            display { $latencyObject Filter.Set [ ::excentis::basic::ParseFilter $filter ] }
            bpf     { $latencyObject Filter.Set $filter }
            tuple {  
                if { ! [ $rxPort Info -implements WirelessEndpoint ] } {
                    error "ByteBlowerHL error: filter format $filterFormat not supported by object of type [ $rxPort Get _ClassName ]"
                }
                
                x.ExecuteScenario.RxTupleFilter.Parse $latencyObject $filter
                
            }
            default { error "ByteBlowerHL error: FilterType on rx port must be bpf, display or tuple" }
        }
        
        if { $duration != 0} {
            if { [ $rxPort Info -implements WirelessEndpoint ]} {
                $latencyObject Duration.Set $duration
            } else {
                default { error "ByteBlowerHL error: -duration can only be set on Wireless Endpoints!" }
            }
        }
        return [ list $rxPort $latencyObject ]
    }

    # parse outofsequence settings, configure outofsequence object and return it
    if { $outofsequence != ""} {
        set filter ""
        set type "basic"
        foreach {item value} $outofsequence {
            switch -- $item {
                -type   { set type $value }
                -filter { set filter $value }
                default { error "ByteBlowerHL error: Invalid outofsequence parameter: $item" }
            }
        }
        if { $filter == ""} {
            error "ByteBlowerHL error: Please define a non-empty filter for the outofsequence option of the rx port"
        }
        switch -- [ string tolower $type ] {
            basic { set outofsequenceObject [ $rxPort Rx.OutOfSequence.[ string totitle $type ].Add ] }
            default { error "ByteBlowerHL error: Unsupported out-of-sequence type '${type}'" }
        }
        $outofsequenceObject Filter.Set [ ::excentis::basic::ParseFilter $filter ]

        return [ list $rxPort $outofsequenceObject ]
    }

    # parse capture settings, configure capture object and return it
    if { $capture != ""} {
        set filter ""
        set pcap ""
        foreach {item value} $capture {
            switch -- $item {
                -pcap   { set pcap $value }
                -filter { set filter $value }
                default { error "ByteBlowerHL error: Invalid capture parameter: $item" }
            }
        }
        set captureObject [ $rxPort Rx.Capture.Basic.Add ]
        $captureObject Filter.Set [ ::excentis::basic::ParseFilter $filter ]
        lappend ::excentis::basic::rxPcapFileNames $pcap

        return [ list $rxPort $captureObject ]
    }

    # return 'not applicable' if neither trigger, latency, outofsequence nor capture was provided
    return [ list $rxPort "NA" ]
}

}

}