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

##
# Calculates the loss rate for the provided @p flowlist according to RFC 1242
#
# Definition:
#     Percentage of frames that should have been forwarded
#     by a network device under steady state (constant)
#     load that were not forwarded due to lack of
#     resources.
#
# @note
#     A trigger must be defined per receiving flow
# 
# @note
#     If non-basic triggers are defined in the flows then these triggers are ignored.
#     E.g.: sizedistribution and rate triggers are ignored
#     If Latency and Capture options are defined, they will be ignored too.
#     So if besides tx parameters, rx parameters are defined, and these rx
#     parameters do not include a basic trigger option, the flow will transmit, but
#     we will not be able to determine the received frames.
#
# @note
#     When for a particular flow only tx parameters are given, this
#     flow will provide background traffic. This flow will be used
#     to send traffic, but will not be taken into account for the
#     calculation of the frame loss rate.
#
# @param flowlist
#           The declarative scenario configuration. See the @ref TclApiHLOverview "higher-layer API overview" for more information.
#
# @param args
#           Output-level option list in the form of a list of key-value pairs:
#           @dlist
#           @dlitem{-return, Defines the output mode
#               @dlist
#               @dlitem{percentage, Percentage of frames lost during transmission vs. offered load
#                           as an aggregate over all flows in the @p flowlist}
#               @dlitem{numbers, Number of transmitted and received frames per flow in the flowlist.}
#               @dlitem{percentagePerFlow, Percentage of the frames lost during transmission vs offered load.
#                           Result for each flow in the @p flowlist}
#               @enddlist
#               @defaultvalue{percentage}
#           }
#           @enddlist
# @return
#     Loss percentage or number of transmitted and received frames per flow, depending on @p \-return
#     @dlist
#         @dlitem{percentage, 0.02}
#         @dlitem{numbers, { {-tx 100} {-tx 100 -rx 100} {-tx 100 -rx NA} {-tx 100 -rx 100 -rx 100} }}
#     @enddlist
#     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 FlowLossRate { flowlist args } {

    set flowexecutelist [ list ]
    set newArgs [ list ]
    set outputmode "percentage"
    if {$args != ""} {
        foreach { item value } $args {
            set item [ string tolower $item ]
            switch -- $item {
                -return {
                    set outputmode $value
                }
                default {
                    # Pass it on to ExecuteScenario.
                    append newArgs "$item $value"
                }
            }
        }
    }

    # parse flowlist to exclude non-basic triggers/latency/capture
    foreach flow $flowlist {
        set flowtoexecute [ list ]
        # parse flow parameters
        foreach {item value} $flow {
            switch -- $item {
                -tx {
                    set txparam $value
                    lappend flowtoexecute "-tx" $txparam
                }
                -rx {
                    set rxparam $value
                    # parse rx parameters to exclude non-basic triggers / latency/capture
                    set rxparam [x.RxParam.FlowLoss.Parse $rxparam]
                    lappend flowtoexecute "-rx" $rxparam
                }
                default {
                    error "ByteBlowerHL error: Invalid flow parameter: $item"
                }
            }
        }; # end parse flow parameters
        lappend flowexecutelist $flowtoexecute
    }; # end parse flowlist

    set result [ eval ExecuteScenario [ list $flowexecutelist ] $newArgs ]
    if { [string equal $outputmode "percentage"]} {
        set resulttx 0; set resultrx 0
        set errormessage ""
        set losspercentage [ list ]
        foreach flow $result {
            # We only need to count flows that have both tx and rx results
            set index [lsearch $flow "-rx"]
            if {$index != -1} {
                foreach {item value} $flow {
                    switch -- $item {
                        -tx {
                            incr resulttx [x.TxResult.FlowLoss.Parse $value]
                        }
                        -rx {
                            if {$value != "NA"} {
                                incr resultrx [x.RxResult.FlowLoss.Parse $value]
                            }
                        }
                        -error {
                            puts stderr "ByteBlowerHL warning: Flow error detected. Loss percentage may be wrong. Error code: $value"
                            set errormessage $value
                        }
                    }
                }
            }
        }
        lappend losspercentage [ expr $resulttx != 0 ? (1.0 - (double($resultrx) / $resulttx)) * 100 : 0 ]
        if { ![ string equal $errormessage "" ]} {
            lappend losspercentage "-error" $errormessage
        }
        return $losspercentage
    } elseif { [ string equal $outputmode "percentagePerFlow" ]} {
        set resultList [ list ]
        foreach flow $result {
            # We only need to count flows that have both tx and rx results
            set resulttx 0; set resultrx 0
            set errormessage ""
            set losspercentage [ list ]
            set index [lsearch $flow "-rx"]
            if {$index != -1} {
                foreach {item value} $flow {
                    switch -- $item {
                        -tx {
                            incr resulttx [x.TxResult.FlowLoss.Parse $value]
                        }
                        -rx {
                            if {$value != "NA"} {
                                incr resultrx [x.RxResult.FlowLoss.Parse $value]
                            }
                        }
                        -error {
                            puts stderr "ByteBlowerHL warning: Flow error detected. Loss percentage may be wrong. Error code: $value"
                            set errormessage $value
                        }
                    }
                }
            }
            lappend losspercentage [ expr $resulttx != 0 ? (1.0 - (double($resultrx) / $resulttx)) * 100 : 0 ]
            if { ![ string equal $errormessage "" ]} {
                lappend losspercentage "-error" $errormessage
            }
            # Return the result
            lappend resultList $losspercentage
        }
        return $resultList
    } else {
        set numbers [ list ]
        foreach flow $result {
            set resulttx 0; set resultrx 0
            set fresult [ list ]
            foreach {item value} $flow {
                switch -- $item {
                    -tx {
                        set resulttx [x.TxResult.FlowLoss.Parse $value]
                        lappend fresult "-tx" $resulttx
                    }
                    -rx {
                        if {$value != "NA"} {
                            set resultrx [x.RxResult.FlowLoss.Parse $value]
                            lappend fresult "-rx" $resultrx
                        } else {
                            lappend fresult "-rx" $value
                        }
                    }
                    -error {
                        puts stderr "ByteBlowerHL warning: Flow error detected. Loss percentage may be wrong. Error code: $value"
                        lappend fresult "-error" $value
                    }
                }
            }
            lappend numbers $fresult
        }
        return $numbers
    }
}

proc x.RxParam.FlowLoss.Parse { rxparamlist } {
    # Parses the rx port parameters.
    # Removes latency and capture options.
    # Removes non-basic trigger options.
    #
    # @return
    #    - list of rx parameters valid for framelosstest
    #    - empty list if no valid rx parameters were found

    set trigger ""
    set found 0
    set result [ list ]
    foreach {item value} $rxparamlist {
        switch -- $item {
            -trigger {
                if {$found == 0} {
                    set found 1
                    set trigger $value
                } else {
                    error "Only 1 trigger allowed per rx port parameter list"
                }
            }
            -latency {
                # do nothing, latency will be ignored
            }
            -capture {
                # do nothing, capture will be ignored
            }
            default {
                lappend result $item $value
            }
        }
    }

    if { $found == 0} {
        # if there is no trigger option, the flow will be transmitted, but there is nothing to receive
        return $result
    }

    if { $trigger != ""} {
        set filter ""; set type "basic"
        foreach {item value} $trigger {
            switch -- $item {
                -type {
                    set type $value
                    if {$type != "basic"} {
                        # if the trigger type is other than basic, the flow will transmit, but not receive
                        return $result
                    }
                }
                -filterFormat {
                    set filterFormat $value
                }
                -filter {
                    set filter $value
                }
                -duration {}
                default {
                    error "Not a valid trigger parameter: \"$item\""
                }
            }
        }
        lappend result "-trigger" $trigger
    }

    return $result
}

proc x.TxResult.FlowLoss.Parse {counter} {
    # Parse the output from Tx.Stream.Counter.Brief.Get.
    # This output is in the form: { NrOfFramesSent } { value } { FrameOid_1 } { value_1 } {FrameOid_2 } { value_2 } ....
    #   Where - value is the total number of frames sent
    #         - FrameOid_1 is the oid of the first frame
    #         - value_1 is the number of frames sent of the first frame
    #         - FrameOid_2 is the oid of the second frame
    #         - value_2 is the number of frames sent of the second frame
    #         - ...
    #
    # @return
    #   number of frames sent

    return [lindex $counter 1]
}

proc x.RxResult.FlowLoss.Parse {counter} {
    # Parse the output from Rx.Trigger.Basic.Counters.Get.
    # This output is in the form: { NrOfFrames } { value }
    #   Where - value is the total number of frames received
    #
    # @return
    #   number of frames received

    return [lindex $counter 1]
}


}

}