Programming

API Structure and Conventions

This chapter discusses general structure of the Ixia Tcl commands and suggested programming sequence.

Most of the Tcl commands have the following same basic structure:

Standard Sub-Commands

The standard sub-commands that come with most commands are mentioned in the following table:

Table:Standard Options

Method Usage

config

Sets a specified value to a specific option, which is most often a desired hardware setting. The value is stored in an object in IxTclHAL temporarily.

cget

Gets a specified option's value, which was stored in the IxTclHAL object.

set

Information is transferred from the IxTclHAL object to the IxHal software layer, but not sent to the hardware. The set method takes as arguments the chassis ID, card number and port number being addressed.

write

Information previously transferred to the IxHal software layer is sent to the hardware.The write method takes as arguments the chassis ID, card number and port number being addressed. Although each class provides its own write method, it is usually more convenient to call ixWriteConfigToHardware, which sends all outstanding set's to the hardware at the same time.

get

Information from the hardware is read out to the IxHal layer and into the member variables. In many cases, the IxHal layer holds more information than is represented in a single set of member variables and additional methods are needed to obtain more data. The get method takes as arguments the chassis ID, card number and port number being addressed.

setDefault

Default values for the members are set.

decode

A captured frame is analyzed and appropriate member variables are set to reflect the contents of the frame.

In general, hardware parameters may be saved through the use of a ‘config’ and ‘set’ option and then retrieved at any later time by a ‘get’ option followed by a ‘cget’ option. This is because the IxHal level maintains memory of all of the settings. This relationship of methods is illustrated in Table:Standard Options.

Note that a single instance of each command exists, with a set of associated data variables, called standard options. The standard options from one command are often used in another. For example, the ipAddressTable command uses the standard options from the ipAddressTableItem command. The most recent standard options from the ipAddressTableItem command are used by the ipAddressTable command. Ensure that the standard options from dependent commands are set immediately before being used. Intervening commands may interfere.

The values defined in the tables for each of the API commands may be used in the following ways:

Figure: Standard Method Relationships

Standard Return Codes

All commands in the TCL API use a common set of return codes. These codes are listed in Table:TCL API Return Codes. These codes are global TCL variables, which may be referred with a preceding ‘$’ (for example, $ixTcl_ok) in a global context or a preceding ‘$::’ (for example, $::ixTcl_ok) in any context. The symbolic codes should be used in preference to literal values.

Table:TCL API Return Codes

Code Value Usage

ixTcl_ok
TCL_ OK

0

No error, successful return.

ixTcl_generalError
TCL_ ERROR

1

An error has occurred.

ixTcl_versionMismatch

2

The software version for the TCL API does not match that used on a connected chassis.

ixTcl_chassisTimeout

3

A timeout occurred while connecting to a chassis.

ixTcl_notAvailable

100

A port may not exist or may be in use by another user.

ixTcl_unsupportedFeature

101

The port does not support a feature.

ixTcl_outOfMemory

102

The TCL execution has run out of main memory.

ixTcl_addedAsDisabled

103

The entry was added, but was disabled due to quantity or volume constraints.

ixTcl_notLicensed

104

Not licensed

ixTcl_noWriteRequired

200

Writing not required

ixTcl_invalidChassisChain

201

Invalid chassis chain

ixTcl_hardwareConflict

202

When adding a load module, a duplicate load module serial number was encountered.

Sequence of Steps

The following sequence of steps should be followed to write a successful Tcl script:

  1. Load the IxTclHal package.
  2. The IxTclHal package contains all the Ixia Tcl Library commands. After loading this package, these commands are made available in the test script. The format of using the package command is as follows:

    package require IxTclHal

    Note that this adds a large number of commands to Tcl, which causes the '?' command (list available commands) to take up to a minute to execute.

  3. Connect to the chassis on which the test is to be executed.
  4. After loading the package, the chassis has to be connected to where the test is going to be executed. The following commands are used to connect and set up the chassis parameters:

    chassis add <hostname or IPv4/IPv6 address>

    chassis config -id <chassisID>

    chassis set <hostname or IPv4/IPv6 address>

    The chassis add command connects to the chassis. The chassis config -id command associates a numeric ID with the chassis. The chassis set command sets the ID of the chassis in IxHAL. It is important to assign a chassisID to the chassis as it is used in the map command. If multiple chassis are to be used, then multiple chassis add commands must be given and each chassis should be assigned a unique ID.

    Alternatively, the following sequence could be used:

    ixConnectToChassis <hostname or IPv4/IPv6 address>

    set chassisID [ixGetChassisID <hostname or IPv4/IPv6 address>]

    The ixConnectToChasssis takes care of all three steps in the previous example, assigning a chassis ID on its own. The call to ixGetChassisID is needed to retrieve the assigned chassis ID for future use.

  5. Set up the traffic mapping
  6. This is an optional step. The mechanism for setting up traffic mapping is provided only for convenience. You may use your own methods for storing this information.

    Before any test can be executed, it is important to specify the flow of traffic, that is, the transmit and receive ports. The mapping for these ports is specified using the map command as follows:

    map config –type one2one; # or one2many, many2one, many2many

    map add <TxChassisID> <TxCardID> <TxPortID> <RxChassisID> <RxCardID> <RxPortID>

    This command stores the transmit chassis, card, port and receive chassis, card, port combinations in a Tcl array within the scope of the Tcl script. There are four types of mappings, as mentioned in the following list:

    1. One to One mapping
    2. One to Many mapping
    3. Many to One mapping
    4. Many to Many mapping

    For the mappings specified in a), b), c), and d) above, the chassis, card, port combinations are stored in Tcl arrays one2oneArray, one2manyArray, many2oneArray and many2manyArray, respectively.

    Each Transmit/Receive combination in one2oneArray is unique. That is, there is only one Receive port for each Transmit port. The Receive port may also be set as Transmit port. Similarly, for the one2manyArray, any Transmit port cannot be used as a Receive port for a different set, and for the many2oneArray, any Receive port cannot be used in a different set of the many-to-one map. The many2manyArray can contain any combination of transmit and receive ports. A port can be assigned to be a Receive port for any number of Transmit ports and can also act as a Transmit port for several Receive ports.

    Table:Traffic Map Array

    Array Type Format

    one2oneArray

    one2oneArray(txChassis,txCard,txPort)
    {{rxChassis rxCard rxPort}}

    one2manyArray

    one2manyArray(txChassis,txCard,txPort)
    {{rxChassis1 rxCard1 rxPort1}
    {rxChassis2 rxCard2 rxPort2} …………
    {rxChassisN rxCardN rxPortN}}

    many2oneArray

    many2oneArray(rxChassis,rxCard,rxPort)
    {{txChassis1 txCard1 txPort1}
    {txChassis2 txCard2 txPort2} ……….
    {txChassisN txCardN txPortN}}

    many2manyArray

    many2manyArray(txChassis,txCard,txPort)
    {{rxChassis1 rxCard1 rxPort1}
    {rxChassis2 rxCard2 rxPort2} …….
    {rxChassisN rxCardN rxPortN}}

    The map command is very useful when writing scripts. Upon closer inspection, it is apparent that the Transmit ports in the traffic flow are all stored as elements of the arrays (except for many2oneArray) and the Receive ports are stored as values (Tcl Lists) of these arrays. This method of storage allows a great deal of flexibility when this information is needed. In Tcl, the command [array names one2oneArray], for example, gives access to all the Transmit ports and to access the Receive port, $one2oneArray($txChassis,$txCard,$txPort) gives the list with the Receive chassis, card, port combination.

  7. Set up test related parameters
  8. The test related information such as duration of test, number of trials, configuration of learn frames and IP/IPX addresses may be set up next.

  9. Configure the port parameters
  10. The port parameters such as speed, duplex, loopback and auto-negotiation must be set in IxHAL and then in hardware (by sending the message to IxServer). The following steps should be followed to configure the ports:

    port config -autonegotiate true

    port config -duplex full

    port config -numAddresses 1

    port config -MacAddress {00 01 02 03 04 05}

    port set $chassisID $cardID $portID

    port write $chassisID $cardID $portID

    The addresses for the ports are assigned in this step. Note that for the Tcl scripts, the addresses are assigned to ports but they are actually configured in the streams (see step 6). This is due to the fact that when executing tests that send and receive traffic from switches and routers, addresses are assigned to physical ports. The concept of streams is invisible to the switches and routers. The MAC address is assigned to the port using the port config -MacAddress command. The source and destination IP addresses are assigned to ports using the ip command. Similarly, the IPX network and node addresses and sockets are assigned to ports using the ipx command. The following example shows the assignment of IP addresses to a port:

    ip config -sourceIpAddr 198.18.1.100

    ip config -destDutIpAddr 198.18.1.1

    ip config -destClass classC

    ip config -sourceClass classC

    ip set $chassisID $cardID $portID

  11. Configure the streams on the transmit ports
  12. The traffic is sent in streams, which contain the frame characteristics. Multiple streams may be created per port. The important parameters in the stream are frame size, inter-frame gap, frame data type, the number of frames to be transmitted, the source and destination MAC addresses in each frame and whether they are incrementing, decrementing or fixed. When configuring the protocol related parameters such as MAC, IP or IPX addresses, the protocol configuration is not be written to hardware until a stream set command is used. In addition, the User Defined Fields (UDFs) can be configured to overlay a 1 to 4 byte custom pattern over the specified frame data. Examples of usage for UDFs include setting up filters on the receive ports for a particular UDF pattern, allowing an incrementing IP address or IPX socket, and adding a sequence ID to the frame.

    The following code shows stream configurations:

    stream config -numFrames 10000

    stream config -name "MyStream"

    stream config -dma stopStream

     

    # Calculate the inter-frame gap using the utility command, calculateGap

    stream config -ifg [calculateGap $rate $framesize $preambleSize $speed]

     

    # get the transmit chassis, card, port combination from the Tcl

    # array created by the map command by using [array names <mapArray>].

    # For example, the txChassis,txCard,txPort combination for the first

    # set in the one2oneArray can be obtained as follows:

    # set txMap [lindex [array names one2oneArray] 0]

    # scan $txMap "%d %d %d" txChassis txCard txPort

    port get $txChassis $txCard $txPort

    set txPortMacAddress [port cget -MacAddress]

     

    # The source MAC address of the port is set in the stream

    stream config -sa $txPortMacAddress

     

    # The destination MAC address of this transmit port can be obtained

    # from the receive port by using:

    # set rxMap $<mapArray> ($txChassis $txCard $txPort)

    # scan rxMap "%d %d %d" rxChassis rxCard rxPort

    port get $rxChassis $rxCard $rxPort

    stream config -da [port cget -MacAddress]

     

    # overwrite 4 bytes of the frame data at offset 42 with magic

    # pattern "BE EF" using UDF 4

    udf config -offset 42

    udf config -enable true

    udf config -countertype c8x8

    udf config -initval "BE EF"

    udf set 4

     

    # set the current stream configuration in IxHAL as the first stream

    # on this port

    stream set $txChassis $txCard $txPort 1

  13. Configure the filters parameters on receive ports
  14. The filters are used to count or capture desired format of frames. To capture the frames, the capture trigger and capture filter parameters have to be enabled. Two counters, User Defined Statistics Counter 1 and User Defined Statistics Counter 2, can be enabled to count frames that match the defined constraints. The UDF values that are set using the stream command can be filtered upon and counted using these counters. To define the constraints on these counters, the filterPallette command can be used to specify up to two Destination MAC addresses, two Source MAC addresses and up to two patterns.

    # Enable the User Defined Statistics Counter 1, Capture

    # trigger and capture filter counters

    filter config -userDefinedStat1Enable true

    filter config -captureFilterEnable true

    filter config -captureTriggerEnable true

     

    # set the User Defined Statistics Counter 1 to count frames

    # that have destination MAC address "00 01 02 03 04 05"

    filter config -userDefinedStat1DA "00 01 02 03 04 05"

     

    # set the capture filter counter to capture frames

    # that have pattern "BE EF"

    filter config - captureFilterPattern "BE EF"

     

    # set up the filter pallette

    filterPallette config -DA1 "00 01 02 03 04 05"

    filterPallette config -pattern1 "BE EF"

    filterPallette config -patternOffset1 42

     

    # obtain the receive chassis, card, port combination and set the

    # filter and filter pallette on the receive port

    filter set $rxChassis $rxCard $rxPort

    filterPallette set $rxChassis $rxCard $rxPort

  15. Write the configuration into hardware
  16. After the stream and filter configurations are set in IxHAL, a message must be sent to IxServer to commit these configurations to hardware. Every command has a write sub-command that writes that command related information into the hardware. However, it is inefficient to commit to hardware after updating every parameter as it might effect the performance of system. A more efficient method of writing to hardware is to update all the IxHAL objects first and send out one message to IxServer. For example, after all the chassis, ports, filters and stream information is set up in IxHAL, a message can be sent to the IxServer requesting it to write every configuration on a chassis.

    We recommend one of the following two methods of writing to hardware:

    1. If a traffic map was set-up in step (3):
    2. ixWriteConfigToHardware <map>

      Here the <map> is one of one2oneArray, one2manyArray, many2oneArray or many2manyArray.

    3. If a traffic map was not set-up in step (3):
    4. set portlist {{1 1 1} {1 1 2} {1 1 3} {1 1 4}}

      ixWriteConfigToHardware portlist

      The portlist variable is a list of lists, each member containing three elements: chassis, card, and port.

    Note that ixWriteConfigToHardware does not send port configuration changes (for example, mii settings, port speed or auto-negotiation) to the hardware. If changes have been made to these parameters, use ixWritePortsToHardware. However, this may result in a loss of link, depending on the changes that have been made.

  17. Start the transmission
  18. Now that the configuration is set in hardware, transmission of the streams on all the involved ports is started. A utility command startTx is provided that starts the transmission on all the ports simultaneously. StartTx command is called with the array created by the map command (one2oneArray, one2manyArray, many2oneArray, or many2manyArray) as an argument. This command uses the portGroup command to add all the Transmit ports in the array to a group with a given ID. This group ID is then used to send a message to the IxServer to start transmission at the same time.

  19. Validate the received frames on receive ports
  20. Usually, only frames that were transmitted must be counted to obtain reasonable results. The DUT may be transmitting management frames periodically, which should not be counted in the validating scheme of the test. As discussed earlier, the UDFs and filters are used in streams to achieve this. The statistics counters such as the User Defined Statistics Counters are used to count the valid frames and calculations may be performed to get desired results. Frames may also be captured that may be decoded and counted.

  21. Output results
  22. Finally, the results may be obtained from the statistics or frames captured in the capture buffer and stored in any desired format.

How to write efficient scripts

A script is a logical sequence of operations that are sequentially executed. However, a script is an application program that must be designed carefully just like a normal C or C++ program. Because a Tcl script does not need to be compiled as in a C/C++ code, it is actually more difficult to get the best optimized code for a Tcl script.

Also, compared to a GUI application where events take place very slowly (clicking on buttons using a mouse), a script passes through the same events very quickly. This speed of execution may cause time synchronization problems with the IxServer application on the chassis. Therefore, it is very important to implement the sequence of events in a very intelligent way so as to achieve the most optimized execution of these events.

Before writing any script, it helps to first design the logic of the test using flow-charts or similar methods. More importantly, the logic should first be implemented in the IxExplorer GUI application to test the algorithm of the script. Therefore, it is of paramount importance that you understand the concepts of streams, filters, UDFs, capture buffers, and so on before writing any script. These are described in the Ixia Reference Guide.

It is important to follow the sequence of steps outlined in Sequence of Steps The following list provides the reasons:

  1. It is important to configure the Port Properties in the very beginning of the script. For example, on a 10/100 card, there is an autonegotiation parameter. If this parameter is to be turned on, then during the auto-negotiation process, the link goes down and it takes a small amount of time to come up again. If there are a number of ports involved, the setting of port properties can take a long time. Therefore, we recommend that the ports be set first. This is done using the port set and port write commands. Do not implement this step in the middle of the script since it only slows down the total time of execution of the test.
  2. To send and receive traffic on the ports, the transmit and receive port mappings must be defined and the port numbers stored in a structured array or list. This way, when streams and filters are to be configured, this array or list only needs to be looped through.
  3. Before creating streams on the transmit ports, decide how many streams are needed to achieve the traffic profile to be used. It is possible that only one stream is needed in most cases. If not certain, use the IxExplorer GUI application to create the stream and transmit frames on it. Try to avoid creating streams for every iteration of the test. Sometimes it is easier to create all the necessary streams and simply disable the unneeded ones during the iterations.
  4. To verify the filters, use the IxExplorer GUI to first mimic the situation. Use magic numbers in the payload of the frames wherever possible so that only the frames involved in the test are received. The magic numbers eliminate the inclusion of loopback, management frames or Spanning Tree BPDUs, for example, forwarded by the DUT.
  5. If your script is running in a small loop and requesting data very quickly from IxServer, it is possible IxServer is not be able to keep up with the requests. If your script must request statistics or other data in a small for or while loop, consider using delays using the Tcl after command.

Multi-Client Usage

It is occasionally helpful to run IxExplorer at the same time as the Tcl Development environment. IxExplorer can provide instant visual verification. When doing so, it is important to perform a Chassis Refresh operation in IxExplorer after executing the following Tcl setup commands:

Mpexpr versus Expr

Statistics and other values used in the Ixia Tcl environment are 64-bit as opposed to 32-bit values. It is important to use mpexpr, as opposed to expr, to calculate expressions and maintain 64-bit accuracy. The 64-bit values are indicated in the individual descriptive pages for the following commands: