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:
- A number of configuration options that are used to set test and other parameters.
- A standard set of options that push the data options toward the hardware and read information back from the hardware.
- Additional command specific options used to perform special settings or operations.
Standard Sub-Commands
The standard sub-commands that come with most commands are mentioned in the following table:
Method | Usage |
---|---|
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. |
|
Gets a specified option's value, which was stored in the IxTclHAL object. |
|
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. |
|
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. |
|
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. |
|
Default values for the members are set. |
|
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:
- As an argument to a config command. For example:
- As a variable used for comparison. For example:
port config -masterSlave portMaster -and
port config -masterSlave $::portMaster
are valid. In the first case, the port config command figures out the value of portMaster (0). In the second case, the global variable $::portMaster (which is defined in the IxTclHal package) is used to determine a value of 0. The :: qualifier indicates that the variable is defined in the global context.
port get 1 1 1
set msValue [port cget -masterSlave]
if [$msValue == $::portMaster] ...
Here the $:: form must be used to refer to the value of portMaster
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.
Code | Value | Usage |
---|---|---|
ixTcl_ok |
0 |
No error, successful return. |
ixTcl_generalError |
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:
- Load the IxTclHal package.
- Connect to the chassis on which the test is to be executed.
- Set up the traffic mapping
- One to One mapping
- One to Many mapping
- Many to One mapping
- Many to Many mapping
- Set up test related parameters
- Configure the port parameters
- Configure the streams on the transmit ports
- Configure the filters parameters on receive ports
- Write the configuration into hardware
- If a traffic map was set-up in step (3):
- If a traffic map was not set-up in step (3):
- Start the transmission
- Validate the received frames on receive ports
- Output results
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.
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.
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:
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) |
one2manyArray |
one2manyArray(txChassis,txCard,txPort) |
many2oneArray |
many2oneArray(rxChassis,rxCard,rxPort) |
many2manyArray |
many2manyArray(txChassis,txCard,txPort) |
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.
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.
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
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 -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
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
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:
ixWriteConfigToHardware <map>
Here the <map> is one of one2oneArray, one2manyArray, many2oneArray or many2manyArray.
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.
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.
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.
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:
- 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.
- 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.
- 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.
- 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.
- 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:
- ixSetCaptureMode
- ixSetPacketFlowMode
- ixSetPacketGroupMode
- ixSetPacketStreamMode
- ixSetPortCaptureMode
- ixSetPortPacketFlowMode
- ixSetPortPacketGroupMode
- ixSetPortPacketStreamMode
- ixWriteConfigToHardware
- ixWritePortsToHardware
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: