Upload
ngonhu
View
214
Download
0
Embed Size (px)
Citation preview
P/N 71-000621 REV A
SmartLibraryOverview and ProceduresProgramming Library Version 6.00March 2006
Spirent Communications, Inc.26750 Agoura RoadCalabasas, CA91302 USA
Support ContactsU.S.E-mail: [email protected]: http://support.spirentcom.comToll Free: +1 800-SPIRENT (+1 800-774-7368)Phone: +1 818-676-2616Fax: +1 818-880-9154
ChinaE-mail: [email protected]: http://support.spirentcom.com.cnToll Free: +1 800-810-9529 (mainland China only)Phone: +86 10 8233 0033 (rest of the world)Fax: +86 10 8233 0022
Copyright© 2006 Spirent Communications, Inc. All Rights Reserved.
All of the company names and/or brand names and/or product names referred to in this document, in particular, the name “Spirent” and its logo device, are either registered trademarks or trademarks of Spirent plc and its subsidiaries, pending registration in accordance with relevant national laws. All other registered trademarks or trademarks are the property of their respective owners. The information contained in this document is subject to change without notice and does not represent a commitment on the part of Spirent Communications. The information in this document is believed to be accurate and reliable, however, Spirent Communications assumes no responsibility or liability for any errors or inaccuracies that may appear in the document.
Limited WarrantySpirent Communications, Inc. (“Spirent”) warrants that its Products will conform to the description on the face of order, that it will convey good title thereto, and that the Product will be delivered free from any lawful security interest or other lien or encumbrance.
Spirent further warrants to Customer that hardware which it supplies and the tangible media on which it supplies software will be free from significant defects in materials and workmanship for a period of twelve (12) months, except as otherwise noted, from the date of delivery (the “Hardware Warranty Period”), under normal use and conditions.
To the extent the Product is or contains software (“Software”), Spirent also warrants that, if properly used by Customer in accordance with the Software License Agreement, the Software which it supplies will operate in material conformity with the specifications supplied by Spirent for such Software for a period of ninety (90) days from the date of delivery (the “Software Warranty Period”). The “Product Warranty Period” shall mean the Hardware Warranty Period or the Software Warranty Period, as applicable. Spirent does not warrant that the functions contained in the Software will meet a specific requirement or that the operation will be uninterrupted or error free. Spirent shall have no warranty obligations whatsoever with respect to any Software which has been modified in any manner by Customer or any third party.
Defective Products and Software under warranty shall be, at Spirent's discretion, repaired or replaced or a credit issued to Customer's account for an amount equal to the price paid for such Product provided that: (a) such Product is returned to Spirent after first obtaining a return authorization number and shipping instructions, freight prepaid, to Spirent's location in the United States; (b) Customer provides a written explanation of the defect or Software failure claimed by Customer; and (c) the claimed defect actually exists and was not caused by neglect, accident, misuse, improper installation, improper repair, fire, flood, lightning, power surges, earthquake, or alteration. Spirent will ship repaired Products to Customer, freight prepaid, within ten (10) working days after the receipt of defective Products. Except as otherwise stated, any claim on account of defective materials or for any other cause whatsoever will conclusively be deemed waived by Customer unless written notice thereof is given to Spirent within the Warranty Period. Spirent reserves the right to change the warranty and service policy set forth above at any time, after reasonable notice and without liability to Customer.
TO THE EXTENT PERMITTED BY APPLICABLE LAW, ALL IMPLIED WARRANTIES, INCLUDING BUT NOT LIMITED TO IMPLIED WARRANTIES OF MERCHANTABILITY, NONINFRINGEMENT AND FITNESS FOR A PARTICULAR PURPOSE, ARE HEREBY EXCLUDED, AND THE LIABILITY OF SPIRENT, IF ANY, FOR DAMAGE RELATING TO ANY ALLEGEDLY DEFECTIVE PRODUCT SHALL BE LIMITED TO THE ACTUAL PRICE PAID BY THE CUSTOMER FOR SUCH PRODUCT. THE PROVISIONS SET FORTH ABOVE STATE SPIRENT'S ENTIRE RESPONSIBILITY AND CUSTOMER'S SOLE AND EXCLUSIVE REMEDY WITH RESPECT TO ANY BREACH OF ANY WARRANTY.
EuropeE-mail: [email protected]: http://support.spirentcom.comPhone: +33 (0) 1 61 37 22 70Fax: +33 (0) 1 61 37 22 51
SmartLibrary Overview and Procedures | 3
Procedures in this Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
About this Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Related Documentation and Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14“Documented/Not Documented” Guidelines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14How to Contact Us. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Chapter 1: Introducing SmartLibrary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17What is SmartLibrary? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Commands, SmartBits Automation, and Spirent Connect. . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Frequently Asked Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Naming Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Chapter 2: SmartLibrary Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Frames, Streams, and Test Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28Traditional Mode – A Closer Look . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29SmartMetrics Mode – A Closer Look . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31SmartLibrary Tutorial Using Tcl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35Basic Stream Configuration Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44Layer 3 Stream Extension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Chapter 3: Default Configuration Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Default Values in SmartLibrary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52How to Use Default Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53Editing the Defaults File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Chapter 4: Traffic Rates and Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60Rate and Load . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60Controls (Including TeraMetrics) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61Basic Rate Calculation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65Basic Load Calculation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66POS-3500B/Bs, LAN-3201B/C Scheduler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Contents
Contents
4 | SmartLibrary Overview and Procedures
Chapter 5: Histogram Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75What Are Histograms?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76How to Set Up Histograms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80Card Support for Latency “Buckets” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Chapter 6: General Programming Information . . . . . . . . . . . . . . . . . . . . . . . . . . 85Firmware Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86Guidelines for All Environments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86Establishing a Link from the PC to SmartBits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87Automatic Defaults for Message Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89How to Identify Hubs, Slots, and Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94Compatible and Native Modes for the SmartBits 600x/6000x . . . . . . . . . . . . . . . . . . . . . . . . 94Stacking and Synchronizing Multiple Chassis. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100Understanding Multi-user Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Chapter 7: Programming in MS Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108General Programming Notes for Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109Directory Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110Developing with Tcl. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111Developing with Visual Basic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112Developing with C/C++. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114Creating a Program with Microsoft Visual C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Chapter 8: Programming in UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128Directory Structure and Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130Developing with C/C++. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131Developing with Tcl. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Chapter 9: Code Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133Tcl Code Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134C/C++ Code Samples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157Visual Basic (VB) Code Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
Chapter 10: Using Tcl and SmartLibrary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163Using the New smartlib.tcl Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164Default Values with the Tcl Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168Converting Existing Scripts for the New Tcl. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
Chapter 11: LibX: Simplified Library Control . . . . . . . . . . . . . . . . . . . . . . . . . . . 177System Requirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178Example 1: Loading LibX with loadx.tcl. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179Command Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181Example 2: set_default and set_link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183Example 3: Transmit and Count . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185Example 4: set_capture/show_capture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
Contents
SmartLibrary Overview and Procedures | 5
Example 5: set_mii/show_mii . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192Example 6: set_l3/show_l3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197Example 7 - set_streamxx/show_stream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199Example 8 – Other Stream Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203Summary of LibX Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
Chapter 12: ATM Testing – SmartBits 200/2000 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207ATM Card Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208ATM Streams and Connections – SmartBits 200/2000 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209Set Up Basic PVC Tests – SmartBits 200/2000 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212 Set Up Basic SVC Tests – SmartBits 200/2000 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217Set Up Tests for PPP over ATM – SmartBits 200/2000 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
Chapter 13: ATM Testing – SmartBits 600x/6000x. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228Traffic Rates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229Interleave Depth. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229Set Up Tests with ATM-345xA(s) TeraMetrics Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . 233Latency Measurement Limitations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
Chapter 14: 10/100 Mbps Ethernet Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253Set Tests with 10/100 Mbps Ethernet Cards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
Chapter 15: WAN (Frame Relay) Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259Set Up Tests with Channelized WAN Cards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260Set Up Tests for PPP over HDLC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280Set Up Tests with Fractional WAN Cards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283Set Up Tests for PPP over Frame Relay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
Chapter 16: 100 Mbps Fast Ethernet Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . 293Set Up Tests With Fast Ethernet Cards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
Chapter 17: Gigabit Ethernet Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299Set Up Traditional Gigabit Ethernet Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
Chapter 18: SmartMetrics/TeraMetrics Testing . . . . . . . . . . . . . . . . . . . . . . . . 309Set Up Ethernet SmartMetrics Streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310Using the New Stream Configuration Commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319Set Up SmartMetrics Tests on TeraMetrics-based Modules . . . . . . . . . . . . . . . . . . . . . . . . . 329Test with IPv6 Streams on TeraMetrics Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343Set Up IPv6 Neighbor Discovery. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357Test with IPv6 Over IPv4 Tunneled Streams. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363Set Up Tests for LAN-3710A 10GbE Modules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369Set Up Alternate Key on TeraMetrics Modules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379Set Up SmartMetrics Tests with the LAN-3201B/C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385Set Up Tests with the ML-5710A . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393Set Up DHCP Streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397
Contents
6 | SmartLibrary Overview and Procedures
Set Up Stream Grouping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402Set Up PPP Over Ethernet (PPPoE). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408Getting Real-Time Statistics with LAN TeraMetrics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411Getting Enhanced Real-Time Statistics with TeraMetrics XD/XFP/XLW Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419
Chapter 19: Packet Over SONET Testing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431Set Up Tests with POS-3500B/Bs Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432Set Up Tests with POS-3519As/Ar and 3518As/Ar Modules . . . . . . . . . . . . . . . . . . . . . . . . 441Test with IPv6 Streams on POS TeraMetrics Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453
Chapter 20: IGMP Testing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467Set Up IGMPv2 Multicast Groups. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468Set Up IGMPv3 Multicast Groups. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474Getting Test Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478Set Up Multicast Listener Discovery (version 1). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480Set Up Multicast Listener Discovery (version 2). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 485
Chapter 21: Dynamic MPLS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491Set Up Dynamic MPLS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 492
Chapter 22: Fibre Channel Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499Set Up Fibre Channel Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500Set Up Custom Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512
Chapter 23: Using NTP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 517What is NTP? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 518Procedure to Use NTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 520
Chapter 24: 802.1x Supplicant Emulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 530Set Up 802.1x Supplicant Emulation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533
Appendix A: Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 541
Appendix B: Transmit Calculations for ATM-345xA(s) Modules . . . . . . . . . 547Sizes, Encapsulations, Utilization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 547Transmit Modes, Burst Counts, Burst Gaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 548
Appendix C: Scheduler Technical Calculations . . . . . . . . . . . . . . . . . . . . . . . . . 555About POS Wire Speed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 556POS Frame Rate Calculation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 557LAN-3201B/C Frame Rate Calculation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 565Optimizing Utilization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 571
Appendix D: Inhibit Clearing Latency Counters . . . . . . . . . . . . . . . . . . . . . . . . . 573
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 577
SmartLibrary Overview and Procedures | 9
Procedures in this Manual
Your SmartLibrary documentation includes three guides:• This Overview and Procedures manual. It provides general information about
SmartLibrary and includes tutorials and “how-to” procedures for all card families.• The Command Reference manuals (two volumes). These describe all SmartLibrary
commands, including the Original Functions and the Message Function iType1 commands.
This document contains numerous procedures, with basic steps for all the different test types. Table 1-1 lists these procedures. You will also find two procedures in Volume 1 of the SmartLibrary Command Reference. Table 1-2 on page 11 lists these.
Note: Be sure to review Supported SmartCards/Modules at the front of each chapter that includes a setup procedure, to identify the compatible SmartBits cards and modules.
Table 1-1. Procedures in This Manual
Card Family/Application How to: Page
ATM Set Up Basic PVC Tests – SmartBits 200/2000 212
Set Up Basic SVC Tests – SmartBits 200/2000 217
Set Up Tests for PPP over ATM – SmartBits 200/2000 224
Set Up Tests with ATM-345xA(s) TeraMetrics Modules 233
10/100 Mbps Ethernet Set Tests with 10/100 Mbps Ethernet Cards 254
WAN (Frame Relay) Set Up Tests with Fractional WAN Cards 283
Set Up Tests for PPP over Frame Relay 290
100 Mbps Fast Ethernet Set Up Tests With Fast Ethernet Cards 294
Gigabit Ethernet Set Up Traditional Gigabit Ethernet Tests 300
Continues –>
Procedures in this Manual
10 | SmartLibrary Overview and Procedures
Layer 3 SmartMetrics:ML-7710LAN-3101ALAN-3101BLAN-3300ALAN-3310ALAN-3710AOthers
Set Up Ethernet SmartMetrics Streams 310
Using the New Stream Configuration Commands 319
Set Up SmartMetrics Tests on TeraMetrics-based Modules 329
Test with IPv6 Streams on TeraMetrics Modules 343
Set Up IPv6 Neighbor Discovery 357
Test with IPv6 Over IPv4 Tunneled Streams 363
Set Up Tests for LAN-3710A 10GbE Modules 369
Set Up Alternate Key on TeraMetrics Modules 379
Set Up SmartMetrics Tests with the LAN-3201B/C 379
Set Up Tests with the ML-5710A 393
Set Up DHCP Streams 397
Set Up Stream Grouping 402
Set Up PPP Over Ethernet (PPPoE) 408
Getting Real-Time Statistics with LAN TeraMetrics 411
Getting Enhanced Real-Time Statistics with TeraMetrics XD/XFP/XLW Modules
419
Packet Over SONET (POS) Set Up Tests with POS-3500B/Bs Modules 432
Set Up Tests with POS-3519As/Ar and 3518As/Ar Modules 441
Test with IPv6 Streams on POS TeraMetrics Modules 453
IGMP Set Up IGMPv2 Multicast Groups 468
Set Up IGMPv3 Multicast Groups 474
Set Up Multicast Listener Discovery (version 1) 480
Set Up Multicast Listener Discovery (version 2) 485
Fibre Channel/SAN Set Up Fibre Channel Tests 500
Set Up Custom Frames 512
Dynamic MPLS Set Up Dynamic MPLS 492
NTP (Network Time Protocol) Procedure to Use NTP 520
802.1x Supplicant Emulation Set Up 802.1x Supplicant Emulation 533
Table 1-1. Procedures in This Manual
Card Family/Application How to: Page
Procedures in this Manual
SmartLibrary Overview and Procedures | 11
Table 1-2. Procedures in the SmartLibrary Command Reference – Volume 1
Card Family/Application How-To Procedure See
All How to Inhibit Latency Counters Chapter 3, “Original Functions and Structures”
All Using NSCreateFrame to Define Frame Templates
Chapter 3, “Original Functions and Structures”
12 | SmartLibrary Overview and Procedures
SmartLibrary Overview and Procedures | 13
About this Guide
In About this Guide...
• Introduction . . . . 14
• Related Documentation and Applications . . . . 14
• “Documented/Not Documented” Guidelines . . . . 14
• How to Contact Us . . . . 15
About this GuideIntroduction
14 | SmartLibrary Overview and Procedures
IntroductionThis SmartLibrary Overview and Procedures is one of a set of three documents that describes how to use the SmartLibrary Programming Library. This guide provides basic information about SmartLibrary, including the following:
• An overview of how to test using SmartLibrary
• Library installation
• Programming notes
SmartLibrary Overview and Procedures also includes detailed tutorials on key concepts and methods. It provides step-by-step “how-to” procedures that show how to use SmartLibrary commands to test different network technologies and devices.
This manual is intended for users of SmartBits systems who want to develop custom test applications. It is assumed that the reader has a moderate familiarity with SmartBits equipment and an intermediate-level understanding of data communications theory and practice.
Related Documentation and ApplicationsThe SmartLibrary documentation set includes two Command Reference volumes. These provide detailed descriptions of all SmartLibrary commands, including the Original Functions and the newer card-specific Message Function iType1s.
Much of the capability provided by SmartLibrary is also available in SmartBits applications that provide a graphical user interface (GUI), such as the application called SmartWindow. For information on all these applications, refer to the SmartBits System Reference Manual.
“Documented/Not Documented” GuidelinesEach release of the SmartLibrary Programming Library can contain code that has been added in anticipation of upcoming SmartBits enhancements but that is not yet officially supported. In general, all supported SmartLibrary features are documented in the SmartLibrary Overview and Procedures manual and in the SmartLibrary Command Reference, as well as in the API User Guides. Capabilities that are not documented in one of these manuals (or addenda) are not supported and should not be used, as they may produce unpredictable results.
About this GuideHow to Contact Us
SmartLibrary Overview and Procedures | 15
How to Contact UsTo obtain technical support for any Spirent Communications product, please contact our Support Services department using any of the following methods:
U.S.
E-mail: [email protected]: http://support.spirentcom.comToll Free: +1 800-SPIRENT (+1 800-774-7368) (US and Canada)Phone: +1 818-676-2616Fax: +1 818-880-9154Operating Hours: Monday through Friday, 06:00 to 18:00 Pacific Time
Europe
E-mail: [email protected]: http://support.spirentcom.comPhone: +33 (0) 1 61 37 22 70Fax: +33 (0) 1 61 37 22 51Operating Hours: Monday through Thursday, 09:00 to 18:00, Friday, 09:00 to 17:00, Paris Time
China
E-mail: [email protected]: http://support.spirentcom.com.cnToll Free: +1 800-810-9529 (mainland China only)Phone: +86 10 8233 0033 (rest of the world)Fax: +86 10 8233 0022Operating Hours: Monday through Friday, 09:00 to 18:00 Beijing Time
The latest versions of user manuals, application notes, and software and firmware updates are available on the Spirent Communications Customer Service Center websites at http://support.spirentcom.com and http://support.spirentcom.com.cn (China).Information about Spirent Communications and its products and services can be found on the main company websites at http://www.spirentcom.com andhttp://www.spirentcom.com.cn (China).
Company Address
Spirent Communications, Inc.26750 Agoura RoadCalabasas, CA 91302USA
16 | SmartLibrary Overview and Procedures
SmartLibrary Overview and Procedures | 17
Chapter 1
Introducing SmartLibrary
In this chapter...
• What is SmartLibrary? . . . . 18
• Commands, SmartBits Automation, and Spirent Connect . . . . 19
• Frequently Asked Questions . . . . 22
• Naming Conventions . . . . 24
• Compatibility . . . . 24
• Troubleshooting . . . . 25
Chapter 1: Introducing SmartLibraryWhat is SmartLibrary?
18 | SmartLibrary Overview and Procedures
What is SmartLibrary?
Product OverviewThe SmartLibrary Programming Library is a powerful programming tool used by developers to create custom test applications running on SmartBits Performance Analysis Systems.
SmartLibrary enables these users to run tests for networks and network devices on theSmartBits 200/2000, SmartBits 600x/6000x, and 1000 chassis using the complete range of SmartBits cards and modules.
The SmartLibrary Software Developer's Kit includes programming library files, many code examples, and thorough documentation.
You can use SmartLibrary to:
• Automate complex suites of tests.
• Create simplified GUIs specifically tailored for a production line.
• Test unique network components.
Key Features
• Tests for ATM, Ethernet, Fibre Channel, Frame Relay, POS, and devices.
• Constantly updated with the latest technology.
• Supports all controllable SmartCard parameters.
• Offers Tcl scripting, C/C++, and Visual Basic® interfaces.
• Can be installed on UNIX and Windows.
• Fully documented including in-depth manuals, over 70 code examples, and well-commented source code.
Supported Technologies
• Ethernet 10Mbps, 100Mbps, 1000Mbps (Gigabit), and 10 Gigabit systems.
• Packet Over SONET with OC-3c, OC-12c, OC-48c, and OC-192c interfaces.
• VG/AnyLan in Ethernet models.
• ATM technologies including DS1, E1, 25 Mbps, E3, DS3, OC-3c, and OC-12c, with signaling control, as well as traffic generation.
• Frame Relay V.35 and RS-45; T1/E1 (fractional and channelized), and DS3.
Chapter 1: Introducing SmartLibraryCommands, SmartBits Automation, and Spirent Connect
SmartLibrary Overview and Procedures | 19
Commands, SmartBits Automation, and Spirent ConnectSmartLibrary provides four methods to develop custom test applications. Each of these methods uses the commands found in the SmartLibrary programming library. The four methods are summarized below. They are described in more detail on page 20.
Figure 1-1 illustrates how the pieces work together.
SmartLibrary CommandsThese include both the Original Functions and the Message Functions. You can use these to create code based on individual library commands.• Original Functions interface with the hardware and firmware of older SmartCards, as
well as with many newer SmartCards and modules.• Message Functions provide a more standardized syntax to interface with the hardware
and firmware of newer SmartCards and modules.Spirent Connect for TclProvides a convenient editor, utilities, and wizards.Code SamplesCan be used to cut and paste applicable code into a script or application.SmartBits AutomationOffers programming interfaces to SmartBits applications.
Figure 1-1. Relationship of SmartLibrary to Spirent Connect, GUI Applications, and SmartBits Automation
SmartBits Chassis/Cards
SmartLibrary
SmartBits GUI User GUIUser
Application
Spirent Connect
SmartBits Automation
SmartWindow
Chapter 1: Introducing SmartLibraryCommands, SmartBits Automation, and Spirent Connect
20 | SmartLibrary Overview and Procedures
SmartLibrary CommandsYou can use SmartLibrary commands to develop custom scripts, with in-depth control of SmartBits systems. You will find detailed documentation for all supported SmartLibrary commands in the two volumes of the SmartLibrary Command Reference.
Spirent ConnectSpirent Connect is a visual scripting tool. It reduces script development time by enabling quick setup of tests, or the use of predefined scripts that are provided with Spirent Connect.
Spirent Connect makes it easy to maintain your test suites and navigate between scripts. It is ideal for the beginning programmer, with capabilities that make building a script simple and fast. For experienced users, Spirent Connect provides a powerful interface for creating automated procedures, designing custom tests, and running Tcl scripts.
Spirent Connect is written entirely in Tcl/Tk and works in Windows, UNIX, or Linux environments. Scripting code is automatically generated, based on GUI input at three different levels. Entire tests, specific routines, or single commands can all be easily generated and inserted into an editor window. A set of card-independent extended commands is also provided, for use anywhere within a script.
Sample CodeSmartLibrary installs with a large number of well-tested, heavily commented code samples. These include Tcl samples that cover almost every available card and exercise almost every library command. There is also a group of excellent Visual Basic samples, complete with a sample GUI window used to select from the available samples. SmartLibrary 3.11 also includes a group of C/C++ samples.You can modify these samples for your own use, copy and paste portions, or simply use them as a reference. For complete information, refer to Chapter 9, “Code Samples” (page 133).
SmartBits Automation
SmartBits Automation offers programming interfaces to selected SmartBits GUI applications. You can use it to develop custom test scripts.
Figure 1-2 illustrates how SmartBits Automation fits into the SmartBits product family. It is an umbrella term for a family of individual APIs (application programming interfaces), each with a specific application “engine” suited to specific test requirements. All the APIs share a common architecture, syntax, and set of functions, so the basic statement usage is uniform. This enables you to write test programs for any application using a small set of common functions, along with required protocol-specific test parameters. Available as part of SmartBits Automation are the Script Automation Interface (SAI) tools. These scripting solutions enable you to write your test definition in a standard text file, run the test, and then use API functions to modify your test setup.
Chapter 1: Introducing SmartLibraryCommands, SmartBits Automation, and Spirent Connect
SmartLibrary Overview and Procedures | 21
Figure 1-2. SmartBits Automation in the SmartBits Programming Environment
Library InterfacesYour Software Developer's Kit includes three interfaces to the library, designed for use with C/C++, Tcl, and Visual Basic.
SmartBits System Hardware
SmartLibrary Programming LIbrary
SmartBits Automation
Application (API) Application (API)Application EngineApplication (API)
Firmware
C/C++ and Tcl – Spirent Connect
Chapter 1: Introducing SmartLibraryFrequently Asked Questions
22 | SmartLibrary Overview and Procedures
Frequently Asked QuestionsDoes SmartLibrary include online capabilities?
Yes. SmartLibrary manuals are provided in PDF format, with numerous hot links in the Table of Contents, Index, command lists, and summary lists. Hot links appear in the PDF files in green font, and the cursor changes to a “pointer” (see below) when passed over them.• You can jump from any Table of Contents entry or Index entry. Move the cursor
(pointer) to the topic entry or page number. Click to jump.
• In the SmartLibrary Command Reference, you can jump from entries in the four commands lists at the beginning of the guide. Doing this takes you quickly to the detailed description of any Original Function, a related structure, any Message Function iType1 command, or its related structure.
• Again in the SmartLibrary Command Reference, each chapter begins with a Sum-mary Table that lists all Message Function iType1 commands described in the chapter. When viewing the manual in PDF format, you can jump from these lists.
• All chapters begin with a topic summary. These are hot-linked.
How do I find a Step-by-Step procedure for my card?See “Procedures in this Manual” (page 9) for a summary of step-by-step procedures.
Do you provide examples of how to use SmartLibrary?The SmartLibrary installation from the CD includes many sample scripts in Tcl; a basic set of scripts in C; and a greatly enhanced set of scripts in Visual Basic (VB). The Overview and Procedures describes the function of each sample script and which commands it includes. For more information, see Chapter 9, “Code Samples.”
Which commands work with my card?The SmartLibrary Command Reference includes compatibility tables that show which Original Functions and Message Functions can be used with each type of SmartCard and module.
How do I find what has changed in the current documentation from the previous version?See the User Guide Revision History in each volume for a detailed list of changes in the user guide. Also refer to Appendix B, “Library Revision History,” (page 535) for a listing of code revisions. Note that code can remain the same while its related com-ments or documentation notes are updated.
Chapter 1: Introducing SmartLibraryFrequently Asked Questions
SmartLibrary Overview and Procedures | 23
Why are some commands present in the header files but not documented in the manuals?Each SmartLibrary release can contain code that has been added in anticipation of upcoming enhancements, but is not yet officially supported. Some of this code is sim-ply obsoleted. It is wise not to use this code, as it may not be released, or may be released in a radically different format. In general, any SmartLibrary command that is not documented in the manuals is not currently supported.
Why are there three different SmartLibrary manuals?SmartLibrary Overview and Procedures covers general topics such as installation, programming environments, and compatibility. It also includes tutorials and “how-to” procedures.The SmartLibrary Command Reference (two volumes) documents the commands. These include:• Original Functions, which are used to:
– Control the SmartBits chassis– Perform basic operations such as starting traffic and resetting ports.– Configure and control older cards.– Perform Traditional Mode (Layer 2) tests.
• Message Function iType1 commands, which are card-specific commands for card families, such as Ethernet and POS. These commands can be used to run both Traditional Mode and SmartMetrics Mode tests.
Where are the SmartBits Automation manuals?All SmartBits Automation user guides are included with the core SmartBits documen-tation.
Where is information about Spirent Connect?See the Spirent Connect Framework User Guide and related content manuals for com-plete documentation.
Chapter 1: Introducing SmartLibraryNaming Conventions
24 | SmartLibrary Overview and Procedures
Naming Conventions
Function Prefixes: ET, HT, HG, NSAll SmartLibrary function names have one of four prefixes: ET, HT, HG, or NS. These indicate the compatible SmartBits systems or cards, as follows.
What are SmartCards and Modules?SmartCards are custom-designed printed circuit boards (PCBs) that fit in a SmartBits chassis and generate, capture, and track network packet data. They are used in SmartBits 1000 and SmartBits 200/2000 chassis.Modules consist of one custom-designed PCB and offer a higher port density than do SmartCards. They are designed for use in the SmartBits 600x/6000x chassis.
CompatibilityAs SmartLibrary evolves, every effort is made to maintain compatibility, so that applications and scripts developed for older modules will work either without modification or with minimal modification. You may, however, need to recompile programs to make use of new features and product releases.To determine the compatibility of the Original Functions and Message Functions with cards in the different card families, refer to the compatibility tables in the command compatibility chapters in both volumes of the SmartLibrary Command Reference.
Note: Be sure to check the readme.pdf file included with each release. See also Appendix B, “Library Revision History,” for changes that might affect your programs.
Function Prefix Description
ET Functions that interact with the SmartBits controller. They are not designed to work with SmartCards and modules.
HT Functions that communicate with a single card.
HG Functions that communicate with a group of cards.
NS Functions that communicate with a SmartBits controller or that perform an action for a range of cards from different card families.
Chapter 1: Introducing SmartLibraryTroubleshooting
SmartLibrary Overview and Procedures | 25
TroubleshootingIf you have difficulty working with the SmartLibrary Programming Library, consider these pointers:
• Make sure your manual is up-to-date. Check the part number in lower right corner of the cover. The most current documentation is available at the Spirent website at:
http://www.spirentcom.com
• Create your programs one module at a time, and test often. The Tcl programming language (provided with SmartLibrary) is particularly useful in this way, because it enables you to test each command without compiling. Instead, you can send function calls directly from the command line.
• Use sample code. It provides clear examples of how to perform basic tasks with all card types and can be used to cut and paste code directly to your test script. See Chapter 9, “Code Samples” (page 133).
• Have you followed the step-by-step procedure(s) for your card? See “Procedures in this Manual” (page 9) for a complete list.
• When reading back result counters, have you left enough time between sending test traffic and collecting data? You may need to insert a one-second pause in your script. Cards update their internal counters periodically, typically every one second.
For information on how to contact SmartBits Technical Support, see “How to Contact Us” in “About this Guide.”
26 | SmartLibrary Overview and Procedures
SmartLibrary Overview and Procedures | 27
Chapter 2
SmartLibrary Basics
Read this chapter to gain a foundation in SmartBits testing with SmartLibrary. It covers the following essential topics:
• Core concepts of SmartBits test equipment and terminology.
• A beginner’s tutorial on installation, linking, and running sample scripts (included on the library CD).
• Core commands to configure SmartBits traffic.
Note: The tutorial included here uses Tcl because it is easy to learn. SmartLibrary also supports the C/C++ and Visual Basic programming languages.
In this chapter...
• Frames, Streams, and Test Modes . . . . 28
• Traditional Mode – A Closer Look . . . . 29
• SmartMetrics Mode – A Closer Look . . . . 31
• SmartLibrary Tutorial Using Tcl . . . . 35
• Basic Stream Configuration Commands . . . . 44
• Layer 3 Stream Extension . . . . 50
Chapter 2: SmartLibrary BasicsFrames, Streams, and Test Modes
28 | SmartLibrary Overview and Procedures
Frames, Streams, and Test ModesFrames To assess the performance of a device under test (DUT), a SmartBits system emulates and
analyzes the appropriate network traffic. One test port sends traffic to the DUT, then a second port receives the forwarded traffic, and the results are analyzed. Put simply, the SmartBits system transmits and tracks test frames to obtain a performance profile of the DUT for certain operating characteristics.
Streams To set up the test traffic to be sent, you define a frame template that the SmartBits can use to generate streams of traffic. Each template sets the makeup (such as size and content) of one of the test frames to be sent, and it is used to generate a unique, trackable stream.
The template itself is often termed a stream on the SmartBits card. You use commands such as L3_DEFINE_IP_STREAM or NSCreateStreamConfigObject to define a stream. Although SmartBits cards are capable of generating many individual streams, you can increase this number greatly by setting up flows—by incrementing or decrementing certain fields within the stream definition as each frame is sent. This enables the card to use one stream template to emulate thousands of streams of test traffic.
In summary, a stream of traffic is a number of frames or cells transmitted from the SmartBits port. In contrast, for programming purposes, a stream on a card is a set of instructions that tells the card how to generate these frames.
Traditional and SmartMetrics Test Modes
SmartCards and modules can generate test streams in one of two modes: Traditional mode and SmartMetrics mode. In each case, the card generates, transmits, and analyzes traffic based on stream definitions. But there are important differences in stream makeup and test results between the two modes.
Traditional mode Traditional mode cards support a single stream definition. This one stream definition, however, can be used to emulate many streams of traffic.
SmartMetrics SmartMetrics cards support many unique stream definitions, each of which also can emulate many streams of traffic. In addition, SmartMetrics cards use a signature field in each frame, which enables the receiving port to track latency, sequence, and other characteristics both for individual streams and for frames.
Card Support for Test Modes
Support for the two modes—Traditional and SmartMetrics—varies for different cards and modules. To find which mode or modes a card supports, refer to the compatibility tables in each volume of the SmartLibrary Command Reference. Use the following rule of thumb:
• If a card supports the HTVFD Original Function or L3_DEFINE_VFD Message Function, it supports the Traditional mode.
• If a card supports the Message Function iType1 command L3_HIST_ACTIVE_TEST_INFO (or FR_HIST_ACTIVE_TEST_INFO for WAN testing), it supports SmartMetrics mode.
Chapter 2: SmartLibrary BasicsTraditional Mode – A Closer Look
SmartLibrary Overview and Procedures | 29
Traditional Mode – A Closer LookIn the Traditional mode, a stream definition includes:
• Frame length (also can be set to random).
• Frame content, including:• Customized Fill Pattern (which can also be set to generate a random pattern)• Manually entered header and payload content.
• CRC integrity check.
• Variable Field Definitions (VFDs). These allow the card to generate different frames with a single stream definition.
Transmit variables such as port speed, gap between frames, and half- or full-duplex are used with the stream definition.
Variable Field Definitions (VFDs)
The Traditional Mode provides for a single stream definition. But you can use the Variable Field Definitions (VFDs) included in each frame definition to generate frames with different content, even though they are based on the one definition.
You can specify up to three VFDs in each stream definition. AVFD can be located at any offset from the beginning of the frame, and the fields can increment, decrement, or vary in pattern within the frame. This enables the port to simulate more than one stream per port and create traffic with varied frame content.
VFD 1 and 2 VFD1 and VFD2 are both six-byte fields. Within each field, one or more bytes can be set to specified values. Then the field(s) can be set to increment, decrement, or generate random values.
For example, in an Ethernet stream (frame) in the Traditional mode, VFD1 can be set to increment at the location of the IP Destination Address in the frame. As the field increments with each frame sent, frames are sent to thousands of IP addresses. In contrast, placing VFD1 at the offset of the IP Source Address would create frames that appear to come from different devices.
Note: Current SmartMetrics cards have limited support for VFD1 and VFD2. See the card specifics and SmartLibrary code comments for more detail.
VFD3 VFD3 is actually a large buffer. You specify the VFD3 values, then a range of bytes to be written into each transmitted frame, one segment at a time. In this way, VFD3 can be used to create frames with differing content that you specify.
Dest MAC
Src MAC Type
Src IP(Static, No VFD)
Dest IP(Increment VFD1)
Payload (Selected Fill Pattern) CRC
Chapter 2: SmartLibrary BasicsTraditional Mode – A Closer Look
30 | SmartLibrary Overview and Procedures
Example VFD3 buffer content:
Six test frames transmitted using two-byte segments from the VFD3 pattern.
Traditional Transmit Controls
Traditional cards control the flow of traffic in several ways.• Interframe gap helps determine the load of a given port. (Frame length is also a
factor.) To set the interframe gap, use the HTGap command.• If you want bursty traffic, you can also set the interburst gap. Use the HTBurstGap
command.• Some cards also support a simpler alternate stream, typically used to intersperse
management frames in the test traffic in Traditional mode. To set up alternate streams, use the Message Function iType1 command FST_ALTERNATE_TX.
Traditional Mode Features
Traditional cards provide the following important benefits:• You can configure frame content to test both Layer 2 and Layer 3 devices.• They provide an economical way to stress-test devices and systems.• Because of the single stream definition, configuration is relatively fast and simple.• The cards offer “packet-blasting” of traffic at full wire rate.• VFDs can be placed at any offset within the defined payload area of the frame, giving
you flexibility to zero-in on problem areas of network traffic or to exhaustively test large tables of addresses.
• A CRC is calculated on a per-frame basis.• Traffic is tracked on a per-port basis with the use of filters (triggers) and counters.
11112222AFAF44445555
VFD3
Frame 1 1111
Frame 2 2222
Frame 3 AFAF
Frame 4 4444
Frame 5 5555
Frame 6 1111
Chapter 2: SmartLibrary BasicsSmartMetrics Mode – A Closer Look
SmartLibrary Overview and Procedures | 31
SmartMetrics Mode – A Closer LookHere are some of the important characteristics of SmartMetrics mode.
SmartMetrics Stream Definitions
Each of the many stream types in the SmartMetrics mode include:
• Frame length (fixed or random).
• Protocol header information (which can include fields and related behavior for IPv4 and IPv6, UDP, TCP, and other protocols). SmartMetrics cards also support the SmartBits stream, a completely customizable header.
• An 18-byte SmartBits signature field that can be enabled or disabled.
• Payload content comprised of a custom fill pattern. This can also be set to generate a random payload.
• A CRC integrity check.
• Some support for Variable Field Definitions (VFDs). Support varies among the different SmartMetrics cards, but typically it is for two six-byte VFDs at the MAC and IP address locations.
The diagram below represents a possible stream configuration for an Ethernet SmartMetrics card. Note the different frame sizes, protocol headers, and the Signature fields.
Note: For Ethernet, POS, and ATM TeraMetrics cards, the stream at index zero usually is disabled in SmartMetrics mode and enabled in Traditional mode.
Index 0MAC Dest MAC Src UDP Protocol Header Signature CRCPayloadMAC Dest MAC Src IPX Protocol Header Signature CRCPayloadMAC Dest MAC Src IP Protocol Header Signature CRCPayloadMAC Dest MAC Src IP Protocol Header Signature CRCPayloadMAC Dest MAC Src SMB Signature CRCPayload
Index 1Index 2Index 3Index 4Index 5
Chapter 2: SmartLibrary BasicsSmartMetrics Mode – A Closer Look
32 | SmartLibrary Overview and Procedures
SmartMetrics Transmit Controls
SmartMetrics cards enable you to define the traffic rate and transmission order per stream.
Note: For a detailed discussion including card models, see “Sending Traffic” on page 49.
Traffic-generation capabilities include the following:
• Transmission rate using interframe gap (IFG). This is set on a global, per-port basis.• Transmission rate using the traffic scheduler, which supports frames-per-second for
individual streams. Currently, this is supported on the following modules:• FBC-3601A/3602A• LAN-3201B/C (see note below)• LAN-3300A/3301A• LAN-3306A• LAN-3310A/3311A• LAN-3320A/3321A, LAN-3324A/3325A, LAN-3327A• LAN-3710AL/AE/AS• POS-3500B/3500BS (see note below)• POS-3502A/3502AS (see note below)• POS-3505As/3504As• POS-3511As/3510As• POS-3518AR/s/3519AR/s• XLW-372xA/XFP-373xA
• Bursty traffic using interburst gap. This setting can be global or per stream, depending on card type.
• Half or full duplex, for Ethernet cards.• Card speed for multi-speed cards.
Note: The scheduling algorithm used on the noted modules differs from the algorithm used on the more recent cards described here. Refer to Chapter 4, “Traffic Rates and Patterns” and to Appendix C, “Scheduler Technical Calculations” for further information on the scheduler for the earlier, noted cards.
For newer cards, see the related “how-to” procedure in this manual:
Module See “How to” Procedure
ATM-345xA(s) Chapter 13, “ATM Testing – SmartBits 600x/6000x”
LAN-33xxA Chapter 18, “SmartMetrics/TeraMetrics Testing”
POS-35xxAs Chapter 19, “Packet Over SONET Testing”
Chapter 2: SmartLibrary BasicsSmartMetrics Mode – A Closer Look
SmartLibrary Overview and Procedures | 33
Signature Field and Histogram Results
With thousands of different stream definitions, how can each SmartBits-generated frame be tracked at full wire rate? The answer is the signature field, a data pattern that is inserted in the frame at the end of the payload.
The signature field contains:• Stream ID, used to track frames of a given stream definition.• Transmit timestamp, used for advanced latency calculation.• Stream sequence number, used to track the sequence accuracy for a given stream
source and definition.
SmartMetrics cards also are capable of analyzing test results using advanced tracking methods that produce histograms: results information that shows the overall pattern or sequence of performance data. When a histogram is enabled on the receiving card, information from any frame containing a signature field is used to create a profile of information, such as latency over time, latency distribution, and frame sequence.
Important: SmartMetrics result histograms can be used only when the signature field is enabled on the transmitting card(s), and when the desired histogram is selected on the receiving card. When you want bi-directional analysis, you can enable signature fields and histograms on both the receiving and transmitting cards.
SmartMetrics Features
SmartMetrics cards provide the following important benefits.• You can configure many unique stream definitions, for extensive control over the
traffic you create. This includes frame content as well as the order of frames sent.• You can track each frame transmitted from a SmartMetrics port. • Tracking capabilities include powerful analyzers (histograms) that give many views
of the traffic profile.• In-depth counters are available, as well as filters (triggers).• Most cards support frame capture.• Most cards support incrementing fields—for example, for IP source and destination
addresses.
Chapter 2: SmartLibrary BasicsSmartMetrics Mode – A Closer Look
34 | SmartLibrary Overview and Procedures
More Terminology
What is a Flow?
A flow is simply a traffic pattern to be tracked (as opposed to a mechanism on the card). A flow is one or more frames from one or more sources to one or more destinations that is tracked as a single entity. Hence, a flow can comprise a single stream or multiple streams. It can be all traffic from a given source, or all traffic to a given destination. If you include a VFD in the stream definition, you could even have multiple flows from a single stream. As an example: a flow might contain all traffic with a given QoS.
Obsolete Terms
You may find the following terms in SmartBits documentation. They are obsolete and are being phased out.
• The Traditional mode cards and test are sometimes referred to as Layer 2. This usage is incomplete, because Traditional cards can also be used to test other layers in the OSI model, including both Layer 2 and Layer 3.
• SmartMetrics cards and tests are sometimes referred to as Layer 3 or Multilayer. This usage is incomplete because SmartMetrics cards can also test other layers, including Layers 2 and 4.
Chapter 2: SmartLibrary BasicsSmartLibrary Tutorial Using Tcl
SmartLibrary Overview and Procedures | 35
SmartLibrary Tutorial Using TclThis section is designed to give you a hands-on introduction to SmartLibrary. It is written for both the inexperienced programmer and the experienced programmer who is new to SmartLibrary.
For this tutorial you will need SmartLibrary 3.10 software or later, a PC connected to a SmartBits chassis with two card or module ports, and knowledge of working with your PC. It is assumed that you have neither SmartLibrary nor Tcl currently loaded on your workstation.
Note: Tcl is used in the tutorial because it is one of the easier languages to learn. SmartLibrary also supports interface files and sample code for C/C++ and Visual Basic programming languages.
About Tcl
Tcl is a scripting language. This means that you create a text-based script or application that is run from a Tcl shell. This is different from compiled languages like C or C++ that create stand-alone, executable programs.
Tk is a graphic interface toolkit for Tcl. You can use it to create GUI interfaces that work with your SmartLibrary scripts.
One advantage of using Tcl is that you can send commands one at a time from the command line without compiling. For example, you can enter:
ETLink $ETCOM1
—and press <Enter> to link a computer to the SmartBits chassis. There is no procedure definition and no compilation. To create a script, you use a basic text editor or programming editor, enter Tcl commands and commands from the SmartLibrary programming library, save it as text only, and run the script.
Note: Tcl scripts must be saved as text only. Any other text format (such as the format of an MS-Word file) will corrupt your scripts. For this reason, it is best to create scripts in a programming editor or a simple text editor.
Below you will find information and step-by-step instructions on:
• Installing SmartLibrary and Tcl.
• Setting up SmartLibrary with Tcl.
• Setting up your files.
• Test driving SmartLibrary with the Tcl shell.
• Running one of the sample scripts.
Chapter 2: SmartLibrary BasicsSmartLibrary Tutorial Using Tcl
36 | SmartLibrary Overview and Procedures
Installing TCL and SmartLibrary
Installation of SmartLibrary and Tcl is a simple, automated process. The SmartLibrary CD and Web download provide an installer for the Tcl scripting language and for the SmartLibrary programming library, including Tcl interface files for supported versions of Tcl.
To install both the current version of SmartLibrary and the Tcl scripting language, run the setup utility. From the SmartLibrary CD run:
• UNIX — <your CD>/SmartLibrary/setup.sh
• Windows — <your CD>\SmartLibrary\setup.exe
The Setup installer will walk you step-by-step through the installation of both SmartLibrary and Tcl. If you already have Tcl on your computer, you can choose to only install the SmartLibrary programming library.
If you install from a Web download, you will need to unzip the files first. For more detailed instructions check the specific sections for UNIX and Windows.
Note: Be sure to note the version of Tcl installed on your computer, so you can use the correct SmartLibrary Tcl interface files later.
Chapter 2: SmartLibrary BasicsSmartLibrary Tutorial Using Tcl
SmartLibrary Overview and Procedures | 37
Setting up SmartLibrary with TCL
You can set up your files and working directories in a number of ways, depending on your needs. This section explains which files you need and suggests one possible configuration.
Files You Need
To create Tcl scripts with SmartLibrary commands, you need to be able to run the Tcl shell, as well as load the proper files to make the SmartLibrary commands available. The tables below list the files you need. All are supplied on the installation CD.
SmartLibrary Files
File Use
smartlib.tcl The improved new SmartLib Tcl interface file. This easier interface contains the same SmartLib commands that you use from your TCL shell. This file is not used if you use the older interface file: et1000.tcl.
et1000.tcl The old SmartLibrary Tcl interface file. It contains the SmartLibrary commands that you use from your Tcl shell. This file is not used if you use the newer interface file: SmartLib.tcl.
libetsmb.so (UNIX)
The main UNIX SmartLibrary file that must be loaded regardless of which programming language you use.
ETSMBW32.DLL (Win32)
The main Windows SmartLibrary file that must be loaded regardless of which programming language you use.
tclet100.so (UNIX)
The UNIX file that maps the Tcl interface file to the commands in the main SmartLibrary file.
TCLET100.DLL (Win32)
The Windows file that maps the Tcl interface file to the commands in the main SmartLibrary file.
misc.tcl(optional)
A SmartBits utility file used to display error/result messages when working with the Tcl shell.
NOTE: This file is optional since these commands are now included in the SmartLibrary Tcl interface files (as of SmartLibrary 3.09 and later).
Chapter 2: SmartLibrary BasicsSmartLibrary Tutorial Using Tcl
38 | SmartLibrary Overview and Procedures
TCL Files
TCL Version
File Use8.3 8.4
tclsh83 (UNIX) • Runs the Tcl shell. This shell gives you a simple text-based window that you can type commands in.tclsh84 (UNIX) •
tclsh83.exe (Win) •
tclsh84.exe (Win) •
libtcl8.4.so (UNIX) • The main file used by the Tcl scripting language.
libtcl8.3.so (UNIX) •
Tcl 84.DLL (Win) •
Tcl 83.DLL (Win) •
libtclStruct.so (UNIX) • • A Tcl utility file used for creating structures. This utility must be used when using Tcl with SmartLibrary.TCLSTRUC.DLL (Win) • •
Chapter 2: SmartLibrary BasicsSmartLibrary Tutorial Using Tcl
SmartLibrary Overview and Procedures | 39
Setting up Your Files
Some files depend on others to run. Here are four ways to ensure that needed files are available:• Put files in a shared system directory, e.g. \Windows\System for Windows or
/usr/bin for UNIX.• Copy dependent files into the same working directory.
• For Windows, put the full path into your path environment variable.
For this basic configuration, use a combination of the first two methods above.Step 1 Copy shared files to a shared directory.
All four *.DLL or *.so files (listed below) should be in the shared directory of your operating system. Two examples:
UNIX[your directory] /lib/libetsmb.so
/tclet100.so/libtcl84.so/libtclStruct.so
Windows
\ Windows\System\ETSMBW32.DLL\TCLET100.DLL\TCL84.DLL\TCLSTRUC.DLL
Step 2 Copy other needed files to a local directory.
Put necessary files into a working directory. For example:
UNIX
/YourTclWork/smartlib.tcl – or – et1000.tcl (for older scripts)/tclsh84/YourTclScripts.tcl
Windows
\YourTclWork\smartlib.tcl – or – et1000.tcl (for older scripts)\tclsh84.exe\YourTclScripts.tc
Chapter 2: SmartLibrary BasicsSmartLibrary Tutorial Using Tcl
40 | SmartLibrary Overview and Procedures
Test Driving the Tcl Shell with SmartBits
If you followed the two previous sections, you have both SmartLibrary and Tcl installed on your computer, and the files you need are available from your working directory and the shared system directory.
Your Hardware Setup
To make use of SmartLibrary, the computer must be hooked up to the SmartBits chassis. Here is a very basic discussion of getting the PC and SmartBits chassis hooked up.
Note: See the SmartBits Installation Guide provided with your chassis in hard copy or on the SmartBits Documentation CD for a more extensive discussion of chassis setup.
For the initial setup, use both the serial connection and the Ethernet connection on the back panel of the SmartBits. Use the serial connection to configure the chassis's IP address. Once the IP address is set, you can use the Ethernet address to communicate to the chassis.
Setting the IP Address on the SmartBits
Step 1 Connect the computer to the SmartBits chassis
Connect the computer COM Port to the chassis COM Port with the RS-232 straight-through cable supplied with your chassis. This cable is not a null-modem cable, although it has two male ends.
Important: Use the Ethernet port on the backplane of the chassis. The ports on the front of cards can generate enough traffic to bring down a live network.
Step 2 Set IP address on the SmartBits
Get an IP address from your Network Manager. Use a terminal-emulation software such as Hyper Terminal or Procomm Plus. With an 8 bit, 38,400 bps connection, use the following commands to set the IP address:>>ipaddr>>ipaddr <put your IP address here nnn.nnn.nnn.nnn>>>ipaddr
Step 3 Reset the System
Close the terminal software and turn the chassis off and then on again. On a SmartBits 200/2000, the Link light on the chassis with blink on, then off again. This means the chassis is ready to be linked to the PC. On a SmartBits 600x/6000x, the chassis is ready to link when the Status light is green.
Chapter 2: SmartLibrary BasicsSmartLibrary Tutorial Using Tcl
SmartLibrary Overview and Procedures | 41
Use the Tcl Shell with a SmartLibrary Command
This section walks you through sending very basic SmartLibrary commands from the Tcl shell. This example uses Tcl version 8.3.4. Note: Remember that Tcl is case-sensitive.
Step 1 Run the tclsh83/tclsh84 shell
Go to your working directory (the one that contains tclsh80 or tclsh80.exe). Once you run the Tcl shell, you will see a text window with the “%” Tcl prompt.
Step 2 Load the SmartLibrary Tcl interface file (smartlib.tcl)
To do this, at the % prompt type:source smartlib.tcl
When these SmartLibrary commands are loaded, the message:SmartBits Programming Library <version number>
—is displayed on the screen.
If this command is successful, the SmartLibrary commands are available and all needed DLLs or SOs have loaded automatically. If this command fails, check the location of your files.
Step 3 Try two basic SmartLibrary commands from the Tcl % prompt
If your computer-to-chassis connection is an Ethernet connection, use this command:ETSocketLink nnn.nnn.nnn.nnn 16385
—where nnn.nnn.nnn.nnn is the chassis IP address and 16385 is the TCP port.
Press <Enter>. The green Link light on the chassis will light up when the link is complete.
If instead you want to make a COM Port connection, use this command:ETLink $ETCOMn (where n is your COM Port)
Press <Enter>. The green Link light on the chassis light up when the link is complete.
When working with a SmartBits, there are three possible IP address locations that you can configure. Make sure that these addresses do not conflict.• The IP address of the Chassis.• The optional IP address of each card that supports a local stack (used for generating
management frames like PINGs and ARPs).• The IP address of each stream if you are generating IP test traffic.
Step 4 UnlinkType ETUnLink and press <Enter>. The Link light will go off.
Step 5 Close the Tcl shellType exit and press <Enter>.
Chapter 2: SmartLibrary BasicsSmartLibrary Tutorial Using Tcl
42 | SmartLibrary Overview and Procedures
Congratulations! You now have a working environment (hardware and software), and you are ready to try one of the sample scripts included with the SmartLibrary programming library.
Running a Sample Script
Once you have installed SmartLibrary and Tcl and established the link between your PC and the SmartBits chassis, you can run one of the many sample scripts provided on the CD.
SmartLibrary installs code samples on your computer under the Sample/Tcl directory. Open them with a basic text editor or your favorite code editor and read the comments before you run the scripts.
The comments in the files will tell you:• What tasks the script is accomplishing.• What type of cards and which slots are used. (Many scripts demo a back-to-back
connection between the first two cards in a chassis.)
Step-by-Step: Running a Tcl Sample Script
Below is a step-by-step procedure to run one of the supplied Tcl sample scripts. The selected sample is for two Ethernet SmartMetrics cards. If you are working with other cards (such as ATM or WAN), follow the same procedure with an appropriate sample file. For a list of the sample files, see Chapter 9, “Code Samples” (page 133).
Step 1 Copy a script to your working directory
Copy a sample Tcl script into your Tcl working directory. For this tutorial, start with 1stBasic.tcl. You can locate this sample Tcl script in the SmartLibrary Tcl samples directory:
./samples/tcl/smartlib_tcl/Layer3/L3Basic.tcl
SmartLibrary sample Tcl scripts now include code to automate loading the library and linking to the chassis. You will see this standard capability in a commented section at the beginning of each Tcl sample file.
Step 2 Set up the SmartCards
Make sure you have two SmartMetrics SmartCards in the first two slots of the SmartBits chassis (for example, ML-7710 cards in slots 0 and 1). Use a back-to-back cable to connect the two cards.
Step 3 Review the script
Use a basic text editor or code editor to view the code and to read the comments in your sample script. Then close the scripts. Save scripts as text only if you make any changes.
Step 4 Run TclFrom your Tcl working directory, run the tclsh83/tclsh84 shell.
Chapter 2: SmartLibrary BasicsSmartLibrary Tutorial Using Tcl
SmartLibrary Overview and Procedures | 43
Step 5 Load the scriptAt the Tcl command prompt (%), source your selected sample Tcl script. When you source (or load) a sample script, the SmartLibrary Tcl interface file is also sourced, and all the SmartLibrary commands become available to you. Type:
source L3Basic.tcl.
Step 6 Enter your IP address
When prompted, enter the correct link information at the command prompt.
Step 7 View the test traffic and results
As the script runs, the traffic statistics are displayed on your monitor as well as the final test results. Note that this first sample script is quite basic.
Step 8 Clean up
When the script is done, you can run another script of your choice. Type exit when you want to close the Tcl shell.
Congratulations! By following the steps in this tutorial, you now know you have a basic, working SmartBits/SmartLibrary system. You also have a good understanding of how to navigate and use our sample code as you automate your network tests with the SmartLibrary programming library.
Chapter 2: SmartLibrary BasicsBasic Stream Configuration Commands
44 | SmartLibrary Overview and Procedures
Basic Stream Configuration CommandsThis section discusses how to create traffic on SmartCards and modules. There are different sets of commands for Traditional mode and SmartMetrics mode.
Note: There are several new stream configuration commands that are intended to replace the stream commands described in this section. For more information, see “Using the New Stream Configuration Commands” on page 319.
Traditional Traffic Configuration
You can define the single stream used in Traditional mode by using two to three basic SmartLibrary commands. You can use either Original Functions or Message Functions (refer to the SmartLibrary Command Reference volumes for all command descriptions).
Traditional Mode Using Original Functions
You can use the following Original Functions to set up Traditional-mode traffic:
• HTDataLengthSets the length of the frames to be transmitted. This can include a random length selection. The four-byte CRC value is appended to the end of each frame.
• HTFillPatternSets the values contained in the frame. The fill pattern is overwritten by the VFDs. The fill pattern can include header information, payload, etc.
• HTVFDSets the location, behavior, and content of up to three VFD fields in the stream definition.
These are the basic commands for defining frame content. In addition, you can specify traffic modifiers such as duplex, gap, errors, bursty traffic, and so on.
Traditional Mode Using Message Functions
To set up Traditional-mode traffic using Message Functions, see the following.For 10/100 Ethernet cards:
• ETH_FILL_PATTERNSets the values contained in the frame. The fill pattern is overwritten by the VFDs.
• ETH_TRANSMITSets up most traffic parameters, including VFDs.
For Gigabit Ethernet cards:
• GIG_STRUC_FILL_PATTERNSets the values contained in the frame. The fill pattern is overwritten by the VFDs.
• GIG_STRUC_TXSets up most traffic parameters, including VFDs.
Chapter 2: SmartLibrary BasicsBasic Stream Configuration Commands
SmartLibrary Overview and Procedures | 45
• GIG_STRUC_VFD3Sets up the VFD3 buffer values.
SmartMetrics Traffic Configuration
Here are the steps to set up streams.
Setting up a Single Stream
It is best to clear all streams, to set the card to a known state. You can do this either by power-cycling the chassis or by using the HTResetPort command.
Step 1 (Optional) Define the global background fill pattern
Use HTFillPattern or HGFillPattern to define the background pattern for all streams on a port. This is a global, per-port command. The default fill pattern is all zeros.
Note: For added flexibility the LAN-3201B/C and POS-3500B/Bs cards support 16 different fill patterns. Newer SmartMetrics and TeraMetrics modules support two fill patterns. These newer modules include:
• POS-35xxAR/As• LAN-33xxA• LAN-37xxAL/AE/AS• XLW-372xA/XFP-373xA• ATM-345xA/As
For more information, see Chapter 4, “Traffic Rates and Patterns” on page 59.
This fill pattern (or background pattern) is laid into the frame first. All other fields overwrite the fill pattern at various offsets, so that it usually is exposed only in the payload. Use the fill pattern to put data into the frame, in addition to the other specified elements that are also copied in.
Example: A fill pattern of all As.
Example: The same frame with fields overlaying the fill pattern.
Step 2 Set the SmartMetrics stream values
For a single stream, use the L3_DEFINE_<n>_STREAM command. (Use the FR prefix for the WAN cards). The protocol header fields available will depend on which command you select. For example:
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
MAC Dest Address
MAC Src Address
Type = IP
Protocol Header
PayloadAAAAAAAAAAAAAAAAAAAA
Signature18 Bytes
CRC
Chapter 2: SmartLibrary BasicsBasic Stream Configuration Commands
46 | SmartLibrary Overview and Procedures
L3_DEFINE_IP_STREAM L3_DEFINE_TCP_STREAM L3_DEFINE_UDP_STREAM
You can use all default values, or specify values for the fields. See Chapter 3, “Default Configuration Values” for further information.
Tcl commandexample
The elements shown above include:• HTSetStructure
Original Function that sends the information to the card.• L3_DEFINE_IP_STREAM
This is a Message Function, termed iType1 because it is the first parameter. This is the command to the card.
• pMyIPStreamThe structure, array of structures, or list that contains the values used to create IP frames. In this example, the structure is of type StreamIP. In the SmartLibrary Tcl interface, using structures is optional.
• 0sizeof(0)The size of the structure (times the number of elements if it is an array of structures). For Tcl users, this parameter is not used, so it is always set to 0.
Some stream fields to note:• ucTagField must be enabled for signature fields to be inserted into each test frame.
Signature field data is used to collect histogram results.• VFD3 in the SmartBits stream is the byte pattern for the customizable frame content.
• ucActive sets a stream to active or inactive. This provides a way to skip a stream while leaving stream index numbers intact.
Notes: • ATM TeraMetrics modules are fully SmartMetrics-compatible. See Chapter 13, “ATM Testing – SmartBits 600x/6000x” for step-by-step instructions.
• ATM SmartCards for the SmartBits 200/2000 chassis are not fully SmartMetrics-compatible, in that they do not support a Signature field or histograms. Refer to Chapter 12, “ATM Testing – SmartBits 200/2000” for step-by-step instructions.
HTSetStructure $L3_DEFINE_IP_STREAM 0 0 0 pMyIPStream 0 /
Chapter 2: SmartLibrary BasicsBasic Stream Configuration Commands
SmartLibrary Overview and Procedures | 47
Three Key Stream Commands
This section says more about three commands used to define SmartMetrics streams:L3_DEFINE_<n>_STREAM L3_DEFINE_MULTI_<n>_STREAM L3_MOD_<n>_STREAM
If you are working with WAN cards, use the FR prefix instead of the L3 prefix.
L3_DEFINE_<n>_STREAM (Creating One or More Streams)
L3_DEFINE_<n>_STREAM defines a stream or group of streams.
Ethernet, POS, and ATM TeraMetrics Cards. For these cards, this command clears all previously defined streams, putting the first stream at index 1 and disabling the stream at index 0. (This ensures backward compatibility so that index 0 is reserved for Traditional mode.)
On WAN cards, this command simply adds streams at the specified index. The first stream is at index 0 if no index is specified.
You can use L3_DEFINE_<n>_STREAM to define many streams by defining an array instead of a single structure or list.
L3_DEFINE_MULTI_<n>_STREAM (Using One to Create Many)
L3_DEFINE_MULTI_<n>_STREAM appends new streams based on an existing stream that is used as a base. The parameters specified are deltas, as opposed to actual values in the frame. That is, they specify how much the specified value should change with each stream. The iType2 (index) specifies the stream to be used as the prototype. The iType3 (count) specifies the number of streams to append to the list.
Example: You use L3_DEFINE_MULTI_UDP_STREAM and set the uiFrameLength field to 2, the index (iType2) to 1, and the count (iType3) to 5. This would result in five new streams, based on the first stream you created, with a frame length that increased by two bytes with each successive stream definition.
A value of 0 maintains the current value of a structure member. Note that some fields will not increment.
WAN cards currently do not support this command.
Notes: • It is a good idea not to set the index (iType2) to 0 on the Ethernet, POS, and ATM TeraMetrics cards, since this stream is often inactive for use with Traditional mode. This avoids accidentally using a disabled Traditional-type stream as your prototype.
• For ATM Terametrics cards, it is required to enter the correct ucProtocolType fields in the stream structure—for example, STREAM_PROTOCOL_IP with StreamIP structure, STREAM_PROTOCOL_UDP for StreamUDP structure, and so on. In addition, all streams must be the VCs to run the test.
Chapter 2: SmartLibrary BasicsBasic Stream Configuration Commands
48 | SmartLibrary Overview and Procedures
Differences for Newer Cards
When using L3_DEFINE_MULTI_<n>_STREAM with TeraMetrics-based modules (see list below), the added streams always begin at one index greater than the prototype index given by iType2. In addition, they overwrite any streams already existing at that index.
Example You use L3_DEFINE_MULTI_UDP_STREAMS and set uiFrameLength field to 2, the index (iType2) to 1, and the count (iType3) to 5. The first new stream will begin at index 2, one greater than what is specified by iType2. The five new streams overwrite any streams already defined at index 2 and greater.
For this functionality, applicable modules include TeraMetrics-based ATM, POS, and LAN modules, including the following:
• ATM-3451A/As, ATM-3453A/As
• POS-3505As/AR, POS-3511A/As, POS-3519AS/AR
• LAN-3300A/3301A, LAN-3310A/3311A
• LAN-3710AL
• XLW-372xA/XFP-373xA
L3_MOD_<n>_STREAM (Overwriting or Appending a Stream)
L3_MOD_<n>_STREAM overwrites an existing stream at a specified index. This command replaces the entire stream: the structure values are not delta values. To change stream attributes, a complete structure is sent to the card.
WAN cards currently do not support this command. You can achieve the same results, however, by using FR_DEFINE_<n>_STREAM at a given index.
Note: Although L3_MOD_<n>_STREAM can modify the stream at index 0, for Traditional/SmartMetrics cards, it is best to work with streams starting at index 1.
Clearing All Streams (Traditional/SmartMetrics Mode)
To clear streams, use L3_DEFINE_<n>_STREAM, and set the structure pointer (pData) to NULL. This clears all streams except stream 0, which will be set to inactive.
Clearing all streams except the stream at index 0 puts the card into Traditional Mode if the card supports both SmartMetrics and Traditional mode. Once the card is in Traditional mode, Traditional functions apply. For example, you can enable Signature fields only in SmartMetrics mode. If the card is in Traditional mode, use the Traditional functions to set up traffic. To switch these cards to SmartMetrics mode, create one or more streams starting at index 1.
To clear streams on the WAN card, use FR_STREAM_DELETE_ALL.
Chapter 2: SmartLibrary BasicsBasic Stream Configuration Commands
SmartLibrary Overview and Procedures | 49
Sending Traffic
Once the streams are configured, you can start and stop the configured test traffic. To start and stop test traffic, see the following group of commands in the SmartLibrary Command Reference:
• HGRun/HTRun
• HGStart
• HGStop
• HGStep
Note: Cards with RIP, PING, or ARP enabled will automatically send these frames at specified increments. See HTLayer3SetAddress in the SmartLibrary Command Reference.
Frame Order
Whether you send a constant stream of traffic, a burst of traffic, or one frame of traffic from each stream, the common order of frames sent is round-robin. The first frame from each stream is sent, then the second frame from each stream. The order is from the smallest stream index to the largest, looping back to the smallest. Inactive streams are skipped. For more information, see Chapter 4, “Traffic Rates and Patterns.”
Note: For ATM TeraMetrics modules, the schedule mechanism is different from the round-robin method described above. For details, see Chapter 13, “ATM Testing – SmartBits 600x/6000x.”
Additional Commands for Stream Manipulation
To Do This: Use This Command (iType1):
Modify one field in a group of streams. This is faster than sending an entire group of structures to the card.
L3_MOD_STREAMS_ARRAY
Check how many streams are configured on the card. The returned value includes the placeholder stream at index 0.
L3_DEFINED_STREAM_COUNT_INFO
Retrieve the stream structure at a specific index. L3_STREAM_INFO
Set up address and gateway information for the card and specify PING, SNMP, or RIP frame transmission.
HTLayer3SetAddress
NOTE: This command sets up the card, not the test streams. The IP address must be unique.
Put the card into a group for group start commands. HGSetGroup
Chapter 2: SmartLibrary BasicsLayer 3 Stream Extension
50 | SmartLibrary Overview and Procedures
Layer 3 Stream ExtensionThe Layer 3 Stream Extension commands provide additional traffic configuration options not included in the initial stream definition commands. These commands include:• L3_DEFINE_STREAM_EXTENSION• L3_DEFINE_MULTI_STREAM_EXTENSION• L3_MOD_STREAM_EXTENSION
They are used with:• L3_DEFINE_<n>_STREAM• L3_DEFINE_MULTI_<n>_STREAM• L3_MOD_<n>_STREAM
You can combine the commands in any order; however, when the configuration is complete, each stream extension must be matched with a stream definition on the card.
Note: Refer to Chapter 4, “Traffic Rates and Patterns.” for additional information on the topics covered here. For ATM TeraMetrics modules, refer to Chapter 13, “ATM Testing – SmartBits 600x/6000x.”
Required or Optional?
Because the LAN-3201B/C and POS-3500B/Bs replace the Gap commands with a frames-per-second scheduler, stream extensions are required by these cards. Stream extensions are also required by the ATM-345xA TeraMetrics modules to specify the frame rate of the streams.
In contrast, the ML-7710 and LAN-3101A use three fields in the L3StreamExtension structure to configure multiple IP and/or MAC addresses per stream. The LAN-3101A/B also uses the data integrity field. Stream extensions are optional for these cards. These fields used are:• ucIPManipulateMode• ucStepCount• uiIPLimitCount• ucDataIntegrityErrorEnable (LAN-3101A, POS-3500B/BS, and LAN-3201x)
Note: For in-depth information about using the stream extensions to configure the scheduler, see Chapter 4, “Traffic Rates and Patterns.” For ATM TeraMetrics modules, see Chapter 13, “ATM Testing – SmartBits 600x/6000x.”
For further information about IP address and MAC address configuration, see the stream extension commands in the SmartLibrary Command Reference.
SmartLibrary Overview and Procedures | 51
Chapter 3
Default Configuration Values
The SmartLibrary programming library provides default configuration values for all Message Functions. This feature is available on all supported platforms and for all supported programming languages.
Note: In Release 3.09 and later, default values are available for Message Functions only, not for Original Functions.
In this chapter...
• Default Values in SmartLibrary . . . . 52
• How to Use Default Values . . . . 53
• Editing the Defaults File . . . . 55
Chapter 3: Default Configuration ValuesDefault Values in SmartLibrary
52 | SmartLibrary Overview and Procedures
Default Values in SmartLibraryThe availability of default configuration values provides a number of benefits:
• Development SpeedYou can simply specify the parameters you are interested in. Other values are filled in automatically.
• Short Learning TimeDefault values are valid within the context of the card and the command. This allows you to use our values while you are learning new technologies and equipment.
• Fewer Errors Supplied default values reduces the chance of introducing errors when you are entering long lists of values.
• Shared ConfigurationsYou can modify the values so that a customized defaults file can be shared between people and across projects.
Default Values File (smartlib.dft)
The default values are contained in an ASCII file: smartlib.dft. The values for each structure are separated by a carriage return.
This file is installed in a shared directory:
• MS Windows – This file is installed in the Windows directory.
• UNIX – This file is installed in the home directory of the current user.
SmartLibrary will search first the current directory, then the system’s shared directory to find smartlib.dft.
Note: An error (FILE_IO_ERROR) is returned if default values are used and SmartLibrary cannot find smartlib.dft.
Chapter 3: Default Configuration ValuesHow to Use Default Values
SmartLibrary Overview and Procedures | 53
How to Use Default ValuesUse HTDefaultStructure to populate a structure with some or all default values.
Note: The syntax for the Tcl interface has added options. Refer to Chapter 10, “Using Tcl and SmartLibrary” (see “Default Values with the Tcl Interfaces” on page 168).
Note the following important guidelines:• HTDefaultStructure is used only to create structures (that is, groups of configuration
values). It looks similar to the HTSetStructure/HTGetStructure/HTSetCommand iType1s, but is different in this way. It also requires a different number of parameters than do these other commands.
• HTDefaultStructure does not send the default values to the card. It only fills the structure with default values. The structure must then be sent to the card using HTSetStructure or HTSetCommand.
• HTDefaultStructure requires Hub, Slot, Port parameters so that the card model can be checked. This means that, for defaults to take effect, the link from your computer to the chassis must be active.
HTDefaultStructure
Description Puts appropriate default values in the specified Message Function structure.Note: HTDefaultStructure does not send the default values to the card. It fills the structure with default values. The structure must then be sent to the card using HTSetStructure or HTSetCommand.
Syntax int HTDefaultStructure(int iType1,void* pData,int iSize,int iHub, int iSlot, int iPort);
Parameters iType1 int Defines the command action.pData void* Pointer to a structure (or an array of structures) that
will receive the default values.iSize int Indicates the size of pData. iHub int Identifies the hub where the card is located.
The range is 0 (first hub) through N (number of hubs − 1). Remember to subtract one since the hub identification starts at 0.
iSlot int Identifies the slot where the card is located. Range: 0 (first slot in Hub) to nn (last card in Hub).
iPort int Identifies the port on the card or module.
Return Value The return value is >= 0 if the function executed successfully. The return value is < 0 if the function failed.
Comments This command is used in conjunction with the Message Functions: HTSetCommand() and HTSetStructure(). Select the desired iType1 and related structure.
Chapter 3: Default Configuration ValuesHow to Use Default Values
54 | SmartLibrary Overview and Procedures
Here are examples of using HTDefaultStructure to set the traffic configuration on a Gigabit SmartCard. This example sets up default values for the Gigabit Transmit structure and then overwrites the gap setting.
C/C++ Example
Tcl Example
GIGTransmit myGigTx;HTDefaultStructure(GIG_STRUC_TX, &myGigTx, sizeof(GIGTransmit),iHub, iSlot, iPort);
myGigTx.ulGap = 960;// ... set any other non-default parameters here
HTSetStructure(GIG_STRUC_TX, 0, 0, 0, &myGigTx, sizeof(GIGTranmit),iHub, iSlot, iPort);
struct_new myGigTx GIGTransmit HTDefaultStructure $GIG_STRUC_TX myGigTx 0 $iHub $iSlot $iPort set myGigTx(ulGap) 960# ... set any other non-default parameters here
HTSetStructure $GIG_STRUC_TX 0 0 0 myGigTx 0 $iHub $iSlot $iPort
Chapter 3: Default Configuration ValuesEditing the Defaults File
SmartLibrary Overview and Procedures | 55
Editing the Defaults FileSmartLibrary provides an ASCII file containing default values for Message Functions, where you can set values (predominantly the HTSetStructure commands). You can edit this file, add comments, even rename the file to create multiple customized files.
Example Here is an example of an entry in the smartlib.dft file, showing a set of configuration options for a 1000Mbps Ethernet SmartCard:
If you want to edit the default values, simply open smartlib.dft with a text editor, and replace existing values of the iType1 that you are working with.
Different Card Models/Different Defaults
In some cases, you may want to use the same command with different defaults for different cards (see Figure 3-1 on page 56 for an example). You can specify more than one set of values for a given command by using iCardModel to specify the card to which the values apply.
Note: For a list of the currently supported card model constants, you can search et1000.* for CM_.
Where no card model is specified, values apply to all cards that accept the command (except for cards specified in another entry for the same command).
Where a card model is specified by iCardModel, values are used with only that card.
An error is returned if defaults for a card are requested and the only default values for that command are specified for use with a different card. To avoid this error, provide one group of defaults for a command that does not have a card specified.
iType1: FST_VLANucVLANEnable: 0uiTPID: 0x8100ucPRI: VLAN_PRI_0ucCFE: VLAN_CFI_RIF_ABSENTuiVID: 0
Command (iType1)
Relatedfield/membernames areterminatedby a colon
Values are separatedby a carriage return
Chapter 3: Default Configuration ValuesEditing the Defaults File
56 | SmartLibrary Overview and Procedures
Figure 3-1. Using Two Sets of Values for One Command
Syntax for smartlib.dft
Below is a list of guidelines for working with smartlib.dft.
• smartlib.dft is case sensitive.
• Do not use carriage returns within a group of values. Carriage returns are used between different iType parameter groups.
• Other than carriage returns, white space does not affect value interpretation.
• You can enter constants or their numeric counterparts.
• Prefix hexadecimal values with 0x.
• Prefix octal values with a leading 0 (zero).
• To specify an array of values, specify the number of elements within square brackets, then the values of each element, separated by a space. If you specify more elements than values, the last value is repeated for a full number of elements:Example: ucFieldName[6]: 1 2 3This would result in the array 1 2 3 3 3 3.
iType: ATM_DS1_E1_LINE_PARAMiCardModel: CM_AT_9015ucTxClockSource: ATM_INTERNAL_CLOCKucCellScrambling: 1ucHecCoset: 1ucRxErroredCells: ATM_CORRECT_ERRORED_CELLSucLoopbackEnable: ATM_LOOPBACK_DISABLEDucIdleCellHeader: 0ucFramingMode: ATM_CS_1_CELL_FRAMINGucLineBuildout: ATM_DS1_0_TO_133_BUILDOUTucLineCoding: ATM_DS1_B8ZS_ENCODINGucLineFraming: ATM_DS1_ESF_LINE_FRAMING
iType: ATM_DS1_E1_LINE_PARAMiCardModel: CM_AT_9020ucTxClockSource: ATM_INTERNAL_CLOCKucCellScrambling: 1ucHecCoset: 1ucRxErroredCells: ATM_CORRECT_ERRORED_CELLSucLoopbackEnable: ATM_LOOPBACK_DISABLEDucIdleCellHeader: 0ucFramingMode: ATM_E1_CELL_FRAMINGucLineBuildout: ATM_E1_BUILDOUTucLineCoding: ATM_E1_HDB3_ENCODINGucLineFraming: 0
Here are two setsof values for onecommand. Notethe iCardModeland card value.
Chapter 3: Default Configuration ValuesEditing the Defaults File
SmartLibrary Overview and Procedures | 57
• Comments may be entered on any line, within value groupings or between them. If you place a comment within a value group, be sure not to split the comment by carriage returns.
• No special characters are needed to signify a comment.
• Avoid putting comments on lines with values. Put comments on separate lines.
• There must be a value specified for each field (the value can be 0).
Different Default Files
If you want to have different *.dft files, you can save the file under a different file name. Specify the active *.dft file using the NSSetDefaultsFile command (refer to the SmartLibrary Command Reference). You can use this command to specify either:
• The active default values file name.
• The full path.
If the library cannot find a defaults file and your program uses default values, the error code File I/O error (−35) is returned.
58 | SmartLibrary Overview and Procedures
SmartLibrary Overview and Procedures | 59
Chapter 4
Traffic Rates and Patterns
All SmartBits cards support a combination of traffic configuration controls. This chapter first reviews basic traffic controls. It then explains how to work with the advanced features provided by selected cards.
Note: This chapter assumes that you are familiar with the concept of streams as generated by SmartBits cards. For a definition of streams and related configuration information, see Chapter 2, “SmartLibrary Basics.”
In this chapter...
• Overview . . . . 60
• Rate and Load . . . . 60
• Controls (Including TeraMetrics) . . . . 61
• Basic Rate Calculation . . . . 65
• Basic Load Calculation . . . . 66
• POS-3500B/Bs, LAN-3201B/C Scheduler . . . . 68
Chapter 4: Traffic Rates and PatternsOverview
60 | SmartLibrary Overview and Procedures
OverviewSmartCards and modules offer a number of ways to configure test traffic patterns, including:
• Global, per-port gap, used to set the load (percentage of bandwidth used).
• Frames-per-second, per-stream, with an automatic global per-port gap.
• Frames-per-second, per-stream, with an automatic varied gap.
• Ratio of one stream to other streams.
• Order in which streams transmit a frame.
• Incrementing/decrementing address fields for a given stream.
• A simple alternate stream (Traditional cards only).
An additional factor is whether test traffic is sent in a constant, even manner or is “bursty”—that is, characterized by periods of heavy traffic interspersed with periods of little or no traffic.
Rate and load are two important topics explained in this chapter.
Rate and LoadRate refers to the number of frames or bits transmitted per second.
Load refers to the amount of available bandwidth being used. 100% load can be described as all frames sent with the minimum interframe gap. Even with a minimum interframe gap, larger frame sizes can change the stress on the system by allowing fewer interframe gaps per second.
Ratio describes the mix of traffic—for example, 90% IP traffic, 9% UDP traffic, and 1% management frames. On cards that support multiple rates per stream, you can control the ratio by setting varying rates for different streams. On cards with a single gap per port, the ratio is usually controlled by creating multiple streams with the given attribute. In this way, even though one frame is sent from each stream for each cycle, multiple streams are sending the same information.
Rate and load are different in important ways. For example, setting up a 60% load implies a drastically reduced number of frames per second. Conversely, a rate of 10,000 frames per second will generally determine the load (unless, as supported on certain cards, there is more than one rate per port).
The following section (“Controls (Including TeraMetrics)” on page 61) explains some of the factors affecting rate and load. “Basic Rate Calculation” on page 65 and “Basic Load Calculation” on page 66 explain the equations you can use to calculate rate (frames per second) and load.
Chapter 4: Traffic Rates and PatternsControls (Including TeraMetrics)
SmartLibrary Overview and Procedures | 61
Controls (Including TeraMetrics)
Gap
The interframe gap (“gap”) is the number of bit times between frames. Gap is the most common control for setting load, with the minimum legal interframe gap defining 100% load. On most cards, interframe gap is a global, per-port setting.
When bursty traffic is generated, there is an additional setting of interburst gap. Bursty traffic also includes the interframe gap, but with a separate interburst gap inserted after a prescribed number of frames.
With SmartLibrary 3.09 and later, setting the gap with auto negotiation enabled is fully supported. An internal algorithm is used to determine the status of the negotiation and the correct speed of the card. There is a slight delay for a gap command when negotiation is still occurring.
Depending on card type, you can set the gap value by using:• HTGap• ETH_TRANSMIT• GIG_STRUC_TX• NS_PORT_TRANSMIT
Note: To determine card support for different commands, refer to the compatibility tables in the SmartLibrary Command Reference volumes.
For gap, related commands are:• HGGap• HTGapAndScale• HTBurstGap• HTBurstGapAndScale• HTBurstCount
Note: For information on how gap is handled for the POS-3500B/BS and LAN-3201B/C cards, see the “POS-3500B/Bs, LAN-3201B/C Scheduler” on page 68.
Chapter 4: Traffic Rates and PatternsControls (Including TeraMetrics)
62 | SmartLibrary Overview and Procedures
Frame Size
You define the frame size when configuring streams. (When calculating the total frame size, remember to add the CRC and preamble to the length you specify. For Ethernet cards, the CRC is 32 bits, and the preamble is 64 bits.)• In Traditional mode, set the frame size by using HTDataLength, ETH_TRANSMIT,
GIG_STRUC_TX, or NS_PORT_TRANSMIT.• In SmartMetrics mode, set the frame size by using the stream definition commands,
such as L3_DEFINE_IP_STREAM.
Speed
Speed here refers to the speed of the card. When a card has multiple speeds (for example, the GX-1420B), use HTSetSpeed to change speeds.
Burst
Bursty traffic is used to simulate traffic characterized by periods of heavy traffic interspersed with “lull” periods of little or no traffic. Bursty traffic is often used to test the buffer capabilities of the Device Under Test.
With SmartCards, the mechanism used to produce bursty traffic is the interburst gap. This is a second gap size inserted in the traffic at specified intervals. Commands used are:
• ETH_TRANSMIT
• GIG_STRUC_TX
• NS_PORT_TRANSMIT
• HTTransmitMode
• HTBurstGap
• HTBurstGapAndScale
• HTBurstCount
Note: For information on interburst gap for the POS-3500B/BS and LAN-3201B/C cards, see the “POS-3500B/Bs, LAN-3201B/C Scheduler” on page 68.
Chapter 4: Traffic Rates and PatternsControls (Including TeraMetrics)
SmartLibrary Overview and Procedures | 63
VFD
Although they do not affect the gap or speed, VFDs can be set to repeat fields at a given frequency, so that a percentage of frames containing certain content can be established. Particularly in Traditional mode, VFDs are used to set the percentage of different types of traffic. See the following commands:
• HTVFD
• ETH_TRANSMIT
• GIG_STRUC_TX
• FR_DEFINE_IP_STREAM
Many SmartMetrics cards support a changing IP address and/or MAC address field. See:
• L3_DEFINE_STREAM_EXTENSION.
Stream Order
By default, for SmartCards that support multiple stream definitions, the transmit order is round-robin based on the stream index. One frame is sent from each stream definition, starting at index 1, until all streams have transmitted, then the process repeats.
In this case, the percentage of different traffic types depends upon the number of stream definitions with different characteristics. For example, if you have defined 30 streams with a high QOS, and 70 streams with a lower QOS, then 30 percent of the traffic will have the high QOS.
Note: Most cards use the round-robin stream order. Exceptions are TeraMetrics cards in Frame-Rate mode (see“Frames-per-Second With TeraMetrics Modules” on page 64) and the POS-3500B/BS and LAN-3201B/C cards (see the“POS-3500B/Bs, LAN-3201B/C Scheduler” on page 68).
Alternate Stream
In Traditional mode, you can define an additional simple stream that is inserted in the traffic pattern at specified intervals. This is often used to simulate management frames.
For 10/100Mbps Ethernet cards, see the following:
• FST_ALTERNATE_TX
Gigabit Ethernet Cards support the use of two alternate streams. To set up alternate traffic patterns, use:
• GIG_STRUC_TX and GIG_STRUC_ALT_TX
• GIG_STRUC_BG1 and GIG_STRUC_BG2
Chapter 4: Traffic Rates and PatternsControls (Including TeraMetrics)
64 | SmartLibrary Overview and Procedures
Frames-per-Second With TeraMetrics Modules
TeraMetrics-based modules support the basic per-port gap and burst commands supported by most existing cards and modules. These modules also provide a frames-per-second mode, which offers the convenience of automatic frame-per-second calculation, with the predictable (and automatically calculated) single gap per-port.
These modules use a global per-port gap, the specified frame sizes, and stream transmit ratio to provide an accurate frame-per-second transmission pattern. In SmartLibrary 3.10 and later, the order of stream transmission is not configurable, but care is taken to intersperse streams and prevent clumping of any given stream wherever applicable.
The global-gap and frames-per-second modes are exclusive. You can select which mode to use with either of these commands:
• HTScheduleMode (an Original command).
• NS_PORT_TRANSMIT (a Message Function command).
If gap mode is selected, use the regular gap and burst commands. If frame rate mode is selected, use L3_DEFINE_STREAM_EXTENSION to specify the frames-per-second.
The Stream Extension commands must be coupled with the Stream Define commands, for example:
• L3_DEFINE_<n>_STREAM (the common stream definition command) — and —
• L3_DEFINE_STREAM_EXTENSION (to create streams with a per-stream rate)
Note: For more information on the TeraMetrics-based modules (including POS and LAN), see the related “how-to” procedures in this manual.
Frames-Per-Second With POS-3500B/BS and LAN-3201B/C Modules
The POS-3500B/BS and LAN-3201B/C scheduler lets you specify frame-per-second per-stream rates while automatically calculating varied gaps per stream based on the specified frame rate. Unlike other cards, these modules use a varying inter-frame-gap to achieve the frame-per-second rate. They do not support the global gap. They use the L3 Stream Extension command exclusively to set up traffic patterns.
If you over-subscribe the module, an error is generated. Over-subscribing means specifying a combination of (a) number of streams and (b) frame rates that causes more traffic than the medium is capable of sustaining.
Note: See the“POS-3500B/Bs, LAN-3201B/C Scheduler” on page 68 for further information on the varied-gap scheduler.
Chapter 4: Traffic Rates and PatternsBasic Rate Calculation
SmartLibrary Overview and Procedures | 65
Basic Rate CalculationUse this calculation to find the interframe gap for a given port when the frame rate and frame size(s) are known. The unit used is bit times, which varies depending on port speed. At 100Mbps, there are 100 million bit times per second. The concept is to calculate the total number of bits sent per second, then subtract that from the total number of bits per second available. What is left is the total gap, which is then divided so that there is an even gap between each frame.
100% Load Total possible bits per second– Rate Total number of bits transmitted (this is also valid with more
than one frame size).= Total gap (bits) Remaining bandwidth. Divide this number by the number of
frames per second to find the Interframe Gap.
Desired Frame Rate Formula
InterFrame Gap = [100% load - (frame size * frame rate)] / frames per second
— or —
G = [B – (A*C) ] / C
Variables
A) Total frame size in bits: frame data size + CRC + preamble. (Multiply frame data size by 8 to convert it from bytes to bits).
B) Bit times per second for 100% load: bits per second, based on the card speed.
C) Frames per second: desired frame rate for the port.
G) Interframe Gap: interframe gap (in bit times) for a desired rate.
Example
Calculate the gap to achieve 100,000 frames a second (with a frame size of 896 bits).
A) Total frame size in bits = 896 = (32-bit CRC, 64-bit preamble, 100 bytes of data).
(Multiply frame data size by 8 to convert it from bytes to bits).
B) Bit times per second for 100% load = 100,000,000 (for 100Mbps Ethernet).
C) Frames per second = 100,000 frames per second.
G) Interframe gap = Unknown.
To configure a rate of 100,000 fps, calculate the interframe gap as [100,000,000 – (896*100,000)]. This gives the total time in which no frames are sent. Divide this by the number of frames. The result is the interframe gap: 104 bit times. Set HTGap to 104.
Chapter 4: Traffic Rates and PatternsBasic Load Calculation
66 | SmartLibrary Overview and Procedures
Basic Load CalculationThis equation is used to calculate the global interframe gap when the desired load (percentage of bandwidth used) is known. Use the load equation first to calculate frames per second, based on desired load. Then enter frames-per-second into the initial rate calculation to find a correct gap. The unit used is bit times, which varies depending on the port speed. For example, with a 100Mb port, there are 100 million bit times per second.
Desired Load Formula
Frame Rate = [100%load / (frame size + min frame gap)] * desired load
Enter frame rate:
InterFrame Gap = [100% load – (frame size * frame rate)] / frames per second
— or —
C = [B / (A+E)] * D
G = [B – (A*C) ] / C
Variables
This example shows calculating the gap for a 70% load.
A) Total frame size in bits: Frame data size + CRC + preamble.
(Multiply frame data size by 8 to convert it from bytes to bits).
B) Bit times per second for 100% load: Bits per second, based on the card speed.
C) Frames per second: Desired frame rate for the port.
D) Desired load: Percent of bandwidth that you want to use.
E) Minimum legal interframe gap: Based on the medium used.
G) Interframe gap: Interframe gap (in bit times) for a desired load.
Example
A) Total frame size in bits = 896 (32-bit CRC, 64-bit preamble, 100 bytes of data).
(Multiply frame data size by 8 to convert from bytes to bits).
B) Bit times per second for 100% load = 100,000,000 bps (for 100Mbps Ethernet).
C) Frames per second = Unknown.
D) Desired load = 70%.
E) Minimum legal interframe gap = 96 bits.
G) Interframe gap = Unknown.
Chapter 4: Traffic Rates and PatternsBasic Load Calculation
SmartLibrary Overview and Procedures | 67
To configure the gap for 70% traffic load (frame size of 896 bits):
C = [100,000,000 / (896 + 96 bits)] *0.7= 70564 frames per second
G = [100,000,000 – (896 * 70564)] / 70564= 521 bits
Divide 100,000,000 by (896 + 96); this gives you the number of frames per second to achieve 100% load (100806 frames per second). Now take 100% frame rate, and multiply it by the percentage of bandwidth use desired (in this example, 70% or 70564 frames per second).
Now that you have frames per second, use the previous rate calculation to find the correct interframe gap.
Desired Frame Rate – 70564 frames per second.
[100,000,000 – (896 * 70564 )] = 36,774,656. This is the total gap: the time in which no frames are sent. Divide this amount by the number of frames per second to find the interframe gap needed to achieve a 70% load at 100Mbps. The result is a gap of 521 bits. Set HTGap to 521.
Chapter 4: Traffic Rates and PatternsPOS-3500B/Bs, LAN-3201B/C Scheduler
68 | SmartLibrary Overview and Procedures
POS-3500B/Bs, LAN-3201B/C SchedulerThe scheduler on the LAN-3201B/C, POS-3500B/BS, and POS-3502A/AS modules enables you to specify the number frames transmitted per second for each stream on a port. It takes into account the selected frame size, rate, and speed of the card, and sets the appropriate gaps. For these cards, the scheduler replaces setting traffic rates with a global gap setting.
A powerful new feature of these cards is the ability to set multiple rates on a single port. It allows you to calculate percentages of different traffic types by setting frames-per-second on a per-stream basis.
Because of calculations needed to produce frames-per-second on a multi-stream card, stream order and interframe gap are set by the card. The frames are sent in round-robin order unless the rates of streams are different. In many cases, setting the frames-per-second is straightforward, resulting in expected traffic loads and rates. Setting the card to use a severe variation in rates, or configuring the card to use an exact gap size with a high bandwidth load, requires a bit of calculation.
Additional Resources
For basic rate calculation, use the concepts presented in this section. For a quick, easy GUI representation, you can also use SmartWindow Rate/Load calculator available in the Transmit Setup dialog for the LAN-3201B/C, POS-3500B/BS, and POS-3502A/AS modules.
Note: For information about card specifications and calculating for specific loads and rates, see Appendix C, “Scheduler Technical Calculations.”
How to Specify Frame Rates
To configure traffic on cards that support the scheduler, use the same stream definitions that you use on all other SmartMetrics cards. These include:
• L3_DEFINE_<n>_STREAM
• L3_MOD_<n>_STREAM
Then, instead of manually calculating the gap and setting it with the HTGap and HTBurstGap commands, use the following:
• L3_DEFINE_STREAM_EXTENSION
• L3_DEFINE_MULTI_STREAM_EXTENSION
• L3_MOD_STREAM_EXTENSION
Important: For the newer modules listed above, each stream Define command must be matched with a stream Extension command. The default stream Extension values are set to 0, which translates to zero frames per second if left unspecified. It does not matter in
Chapter 4: Traffic Rates and PatternsPOS-3500B/Bs, LAN-3201B/C Scheduler
SmartLibrary Overview and Procedures | 69
what order the streams and stream Extensions are defined, as long as an Extension is defined for each stream before transmission begins.
Note: In addition to scheduling configuration, L3_DEFINE_STREAM_EXTENSION and related commands support a number optional stream features. See “Layer 3 Stream Extension” on page 50.
Fields Used to Configure the Scheduler
The only required fields are ulFrameRate and ulTxMode. If the transmission mode is set for bursty traffic, then use one or more of the burst fields to configure the bursts.
ulFrameRate; /* Required for POS-3500x/LAN-3201x *//* Frame transmit rate, in frames-per-second */
/* Minimum frame rate PER STREAM is 31 frames per */ second */
ulTxMode; /* Required for POS-3500x/LAN-3201x *//* Frame transmit mode, use one: */ L3_CONTINUOUS_MODE, */ L3_SINGLE_BURST_MODE, */ L3_MULTIBURST_MODE, L3_CONTINUOUS_MULTIBURST_MODE */
ulBurstCount; /* Optional for POS-3500x/LAN-3201x *//* The number of frames in a burst. This value is used if ulTxMode is set to one of the BURST modes. */
ulMBurstCount; /* Optional for POS-3500x/LAN-3201x *//* The number of bursts transmitted. This value is used if ulTxMode is set to L3_MULTIBURST_MODE. */
ulBurstGap; /* Optional for POS-3500x/LAN-3201x *//* The gap between bursts. This value is used if ulTxMode is set to L3_MULTIBURST_MODE or L3_CONTINUOUS_MULTIBURST_MODE. Unit size is 32ns. */
/* The Maximum ulBurstGap value is 128121.875 (or 32 * 4,099,900 nanoseconds) */
ulStartOffset; /* Optional for POS-3500x/LAN-3201x *//* Sets the gap between the end of the previous frame and the transmission of this one. Used in conjunction with frame size to force a specific interframe gap. Units are 320ns.*/
Chapter 4: Traffic Rates and PatternsPOS-3500B/Bs, LAN-3201B/C Scheduler
70 | SmartLibrary Overview and Procedures
Field Configuration and Related Behavior
ulFrame RateThis value is the number of frames to transmit per second for the given stream. If a single stream is defined on the card, then frames are transmitted at even intervals. For example, if a single stream is set to 10,000 frames per second, the frames are transmitted so that 10,000 frames are transmitted each second, with an interframe gap that is consistent (or as close to consistent as possible to achieve 10,000 frames per second).
If two streams are defined, both streams are evenly dispersed, so that a capture for each stream you would show even gaps on a per stream basis. However, since the two streams are interspersed, if you view a capture for all frames combined, you will see different gaps to accommodate the two different rates. Regardless of the number of streams, traffic is spread out so that it is fairly continuous, unless “bursty” traffic is specified.
ulTxModeThis specifies whether frames from the given stream are transmitted at even intervals or have intervals of heavier traffic interspersed with lulls or interburst gaps where no frames are sent from the stream. Continuous mode sends frames at even intervals. Single Burst mode sends a set number of frames. Multiburst mode sends a set number of frames, interspersed with a set number of interburst gaps. Continuous Multiburst mode sends continuous bursts of traffic. The frames-per-second rate is only true for traffic within the burst. This rate is then interrupted by the interburst gap.
ulBurstCountThis value specifies the number of frames transmitted in a given burst. Use this field if any of the burst modes are specified in ulTxMode.
ulMBurstCountUse this field if multiburst mode is specified. This value is the total number of bursts transmitted for the given stream, not a per-second rate. For example: If ulBurstCount is set to 10 (frames in a burst), and ulMBurstCount is set to 300 (bursts in total), then the specific stream will stop transmitting after 3,000 frames are sent.
ulBurstGapUse this field if either Multiburst or Continuous Burst mode is specified. This value is the size of the interburst gap inserted into the traffic. It is set in units of 32 nanoseconds, so ulBurstGap set to 200 will result in 6400 nanosecond gaps inserted into the traffic every (ulBurstCount) number of frames.
ulStartOffsetThe card’s scheduler calculates interframe gaps based on: the frame size, the frames-per-second rate, and the number of streams defined. The Start Offset is used for more control over the interframe gap. It sets the start time to transmit from a given stream. This can be used to more evenly space the traffic during lower bandwidth use.
The StartOffset represents the delta between sending one frame and the next frame. When specifying the StartOffset value, include the transmission time for the previous frame plus the desired gap. When ulStartOffset is not specified, the first frame of each stream is transmitted immediately after the first frame of the prior stream.
Chapter 4: Traffic Rates and PatternsPOS-3500B/Bs, LAN-3201B/C Scheduler
SmartLibrary Overview and Procedures | 71
Understanding Traffic Behavior
When you configure traffic on a POS-3500B/BS or a LAN-3201B/C, the cards calculate the transmit pattern for you, based on the frame rate you selected. Below is an explanation of the traffic patterns you can expect depending on the number of streams you configure and the transfer mode (continuous, bursty, etc.) you select.
One-Second Snapshot (Avoiding Oversubscription)
Because the rate is set in “frames per second,” the scheduler operates in units of one second. All traffic patterns specified take place within the span of one second. Frames from each stream on a port are transmitted at the specified frame rate within the course of a second. This includes the interburst gaps specified. This creates a snapshot effect. The complete traffic pattern takes place during a second; then the pattern is repeated. If more traffic is configured than can occur in one second, the card is oversubscribed, and will not transmit. Currently, the library returns a generic card error (–33) when this occurs.
Frame Rate Snapshot: The number of bits per second, including the sum of (frame rate * frame size) for each stream, cannot exceed 100% load for the medium.
InterBurst Gap Snapshot: The sum of the frames per second (calculated above), plus an interburst gap per stream, cannot exceed 100% load for the medium.
Note: The number of bursts (ulMBurstCount) and the number of frames in a burst (ulBurstCount) are the only scheduler settings that can actually traverse across multiple seconds, so that a burst can be several seconds long. A BurstGap, however, must fit within the one-second snapshot. The maximum allowable interburst gap is 4,099,900 nanoseconds (just over 4 ms).
Per Stream vs. Per Port
Traffic is configured on a per-stream basis; traffic is transmitted on a per-port basis (an aggregate of all streams on the card). Bursty traffic for a given stream simply means that there are gaps during which the given stream is not transmitting; other streams will continue to transmit if they are scheduled to do so. Conversely, while Continuous mode traffic is evenly dispersed per stream across the one second time slot, each stream sends its first frame as soon as possible. This means that the first frames of each stream are sent with minimum legal interframe gap. Then, interframe gaps are used to achieve the appropriate frame rate. For a light load, this produces traffic that is slightly bursty. For a heavy load, or for streams with varied frame rates, the traffic is more even.
For a clear demonstration of the different traffic effects, see the discussions below.
Chapter 4: Traffic Rates and PatternsPOS-3500B/Bs, LAN-3201B/C Scheduler
72 | SmartLibrary Overview and Procedures
Single Stream – Continuous Mode
Using a single stream definition results in the port transmitting the specified number of frames spread evenly across the one-second time slot. The gap is as close to even as possible while still achieving the frame rate.
Light Load/Single Stream (where X is a frame)
Multiple Streams – Continuous Mode
When multiple streams are transmitted, the gap between one frame and the next of a given stream is even, but the gap between one stream and the next is minimal. The initial frame of each stream is transmitted as close to the same time as possible (minimum interframe gap). This means that the gap between the first frame of stream 1 and the first frame of stream 2 may be smaller than the prescribed interframe gap for a given stream. The tables below illustrate how the three basic variables affect traffic patterns.
Light Load/Multiple Streams/Same Rate (where X is a frame):
Heavy Load/Multiple Streams/Same Rate (where X is a frame):
Moderate Load/Multiple Streams/Different Rates (where X is a frame):
Stream 1 X_________X_________X_________X_________X________ Even distribution
Aggregate Port Traffic X_________X_________X_________X_________X________ Large gap for light traffic
Stream 1 X_________X_________X_________X_________X________ Even distribution
Stream 2 _X_________X_________X_________X_________X_________ Even distribution
Stream 3 __X_________X_________X_________X_________X_________ Even distribution
Aggregate Port Traffic XXX_______XXX_______XXX_______XXX_______XXX_______ Large gap for light traffic
Stream 1 X__X__X__X__X__X__X__X__X__X__ Even distribution
Stream 2 _X__X__X__X__X__X__X__X__X__X_ Even distribution
Stream 3 __X__X__X__X__X__X__X__X__X__X Even distribution
Aggregate Port Traffic XXXXXXXXXXXXXXXXXXXXXXXXXXXXX Even distribution with heavy traffic
Stream 1 X_________X_________X_________X_________X________ Even distribution
Stream 2 __XX___XX___XX___XX___XX___XX___XX___XX___XX___ Even distribution
Stream 3 ____X__________X___________X_________X__________ Even distribution
Aggregate Port Traffic XXXX__XXX_XX_X__XXX__XX__XXX_X_XX_X_XXX__XX_ More even distribution with multiple rates
Chapter 4: Traffic Rates and PatternsPOS-3500B/Bs, LAN-3201B/C Scheduler
SmartLibrary Overview and Procedures | 73
Single Stream – Burst Mode
If one stream is defined on a port with transmit mode set to bursty, the calculated frame rate is used within the bursts, with the interburst gap inserted after a specified number of frames. The gap between bursts is not included in the frames-per-second rate calculation.
Multiple Streams – Burst Mode
Depending on the number of streams defined, “bursty traffic” for a given stream may simply translate to a lower rate for that stream rather than actual bursty traffic.
Using the Start Offset
In many cases it is not necessary to use the Start Offset. If you are transmitting minimal load with multiple streams and are interested in very consistently spaced frames, you can use the Start Offset for more control.
Light Load/Multiple Streams/Same Rate with StartOffset (where X is a frame):
Stream 1 Second #1 XXXXXXXXXX
Second #1XX_____XXXXX
Second #1XXXXXXX____
Two burst over three seconds
Aggregate Port Traffic Second #1XXXXXXXXXX
Second #1XX_____XXXXX
Second #1XXXXXXX____
Bursts affect port
Stream 1 XXXX______________XXXX_________________XXXX Bursty Stream
Stream 2 ____X_____X_____X______X_____X_____X_____X____ Continuous Stream
Stream 3 _____X_____X______X_______X_____X_____X_____X____ Continuous Stream
Aggregate Port Traffic XXXXXX__X_X_X__XX__XXXX__X__X__X__X_X__XXXXX_ Fairly Even per Port
Stream 1 X__________X_________X_________X_________X_________ Even Distribution
Stream 2 offsetX_________X_________X_________X_________X_____ Even Distribution
Stream 3 ___offsetX_________X_________X_________X__________X____ Even Distribution
Aggregate Port Traffic X__X__X__X__X__X___X___X___X__X__X___X___X___X___X__ Even Distribution with Start Offset
74 | SmartLibrary Overview and Procedures
SmartLibrary Overview and Procedures | 75
Chapter 5
Histogram Results
SmartMetrics test results are based on histograms, which distill and analyze received test traffic to provide sophisticated results about the performance and behavior of networks and devices.
In this chapter...
• What Are Histograms? . . . . 76
• How to Set Up Histograms . . . . 80
• Card Support for Latency “Buckets” . . . . 83
Chapter 5: Histogram ResultsWhat Are Histograms?
76 | SmartLibrary Overview and Procedures
What Are Histograms?Histograms offer a powerful way to look at test results. Whereas counters supply cumulative totals for specified events, histograms provide relational information about stream behavior over time.
Five Histogram Types
You can enable one histogram for each card each time a test is run. The selected histogram is used to analyze the results for current test traffic. For each test and card, you can enable one of the following five histogram types.
V2_LATENCY (Latency over Time)This histogram provides the average, maximum, and minimum latency values for network traffic at specified intervals during the test. The values are the composite result of all streams averaged together. This histogram answers a question like: “What was the overall average latency in the first second?” You configure this histogram to analyze data at specified intervals. For example, you can specify latency measurements during the first nanosecond, second, third, and so forth.
V2_LATENCY_PER_STREAM (Combination Histogram)This histogram gives a picture of latency per stream. It provides the minimum, maximum, and average latency values over the course of the test (Latency Over Time), tracking the occurrence of specific latency values on a per-stream basis (Latency Distribution). It also reports whether frames were received in-sequence for each stream (Sequence Tracking). Latency values are shown for both in-sequence and out-of-sequence frames.
LATENCY_DISTRIBUTION (Latency Distribution)This histogram tracks the occurrence of specific latency values on a per-stream basis. It can show typical latency values and/or the distribution of multiple latency values.
You set the ranges of latency values using Latency_Results_Settings. A range of latency values can consist of consecutive values (such as in .4, .5, .6 microseconds) or varying values (such as .2, .5, 1.9…2.3 microseconds).
SEQUENCE (Sequence Tracking)A revised Sequence Histogram was introduced with the release of the POS-3500B/Bs and LAN-3201B/C cards. It has been adopted as the common algorithm used by LAN cards. The ML-7710 was updated with this algorithm with the release of firmware version 1.16. WAN cards use the original method.
From a SmartLibrary perspective, the same commands are used for both methods represented in firmware. The difference is that the later version (version II), does not return values for ulDuplicate, and ulLost now contains the out-of-sequence frame count in the L3_HIST_SEQUENCE_INFO command.
Chapter 5: Histogram ResultsWhat Are Histograms?
SmartLibrary Overview and Procedures | 77
Sequence Histogram Version IIThis Histogram increments the in-sequence counter only for frames that are received in the expected order. It is based on two values: the expected sequence number which is set to one more than the received sequence number, and the in-sequence counter which is incremented when an expected sequence number is received.
• When a frame with a Signature field is received, if the sequence number matches the expected number, then both the in-sequence counter and the expected sequence value are incremented.
• If the sequence number in the Signature field does not match the expected number, the in-sequence number is not incremented. The expected sequence value is changed to be one greater than the sequence number that was received.
Tx S
eque
nce
Rx
Seq
uenc
e
Nex
t Exp
ecte
d #
Bas
ed o
n Al
gori
thm
In S
eque
nce
Out
of S
eque
nce
0 0 0 X
1 1 1 X
2 3 2 X
3 4 4 X
4 6 5 X
5 5 7 X
6 7 6 X
7 8 8 X
8 8 9 X
9 10 9 X
10 11 11 X
11 9 12 X
12 12 10 X
13 13 Totals 5 8
Chapter 5: Histogram ResultsWhat Are Histograms?
78 | SmartLibrary Overview and Procedures
Sequence Histogram Version IThis histogram reports whether or not frames were received in sequence on a per-stream basis, and it identifies duplicate and dropped frames. Its algorithm is designed to match the operation of an actual TCP stack, and is as follows:
• As long as frames are received in sequence, the In Sequence counter is incremented.
• If a frame is received with a frame sequence number that is greater than the one expected, the number of missing frames (hole size) is noted, and a variable for the first of the missing frames is set. No counter is set, so the Out of Sequence value increments.
• Subsequent in-order frames falling after the sequence hole increment the In Sequence variable.
• If the frame from the start of the hole is received, the hole-size variable is decremented.
• If a frame from the middle of the hole is received, the earlier frames still not received from the sequence hole are counted as Lost. The hole-size variable is decremented, and the start of the hole begins after the received frame. The expected frame continues to be one more than the last frame received in sequence.
• If another out-of-sequence frame is received before the previous sequence hole is filled, the Lost variable is incremented by the size of the previous sequence hole. The new hole is then tracked.
• If while the new sequence hole is being tracked, a previous out-of-sequence frame arrives, the Duplicate variable is incremented.
• The In Sequence value continues to increment for every frame received in sequence after the current sequence hole. For example:
1, 2, 3 Three frames in sequence.
1, 2, 3, 9, 10, 11 Sequence hole five frames. 10, 11, in sequence.
1, 2, 3, 9, 10, 11, 4 Sequence hole is now four frames.
1, 2, 3, 9, 10, 11, 4, 15 First hole closed, Lost incremented by four. New hole three frames long.
1, 2, 3, 9, 10, 11, 4, 15, 5 Duplicate incremented by one. (5 is counted as a duplicate since the previous hole is no longer tracked).
Chapter 5: Histogram ResultsWhat Are Histograms?
SmartLibrary Overview and Procedures | 79
The out-of-sequence values are calculated by subtracting the sum of the other values from the number of frames received.
RAW_TAGS (Bulk Data)This histogram provides a list of statistics on a per-frame basis. It differs from other histogram results in that the data is not analyzed. Rather, Raw Tags gives you access to test data, so that you can analyze the information any way you wish. Because it generates records on a per-frame basis, Raw Tags creates a large number of records quickly.
Tx S
eque
nce
Expe
cted
#B
ased
on
Algo
rith
m
Rx
Seq
uenc
e
In S
eque
nce
Out
of S
eque
nce
Lost
Dup
licat
e
Hol
e tr
acki
ng
0 0 0 X 0
Missing frm #2 is tracked by Hole (size of Hole is 1)
1 1 1 X 0
2 2 3 X 2-3
3 4 4 X 2-3
Second hole opens, so first Hole is closed, “Lost” counter is incremented by (Hole size).
4 5 6 X 5-6
5 7 5 X 0
6 7 7 X 0
7 8 8 X 0
No Hole, and #8 is less than expected, so “Duplicate” is incremented. “Expected” is not incremented.
8 9 8 X 0
9 9 10 X 9-10
10 11 11 X 9-10
Frame #9 was the frame from the “Hole,” so the “Expected” number is not incremented. The hole is closed and #9 can now be labeled as “Out of Seq.” as apposed to “Lost” or “Dup.”
11 12 9 X 0
12 12 12 X 0
13 Totals 13 7 4 1 1 Internal Mechanism Only
Chapter 5: Histogram ResultsHow to Set Up Histograms
80 | SmartLibrary Overview and Procedures
How to Set Up HistogramsUse the following steps to set up SmartMetrics histograms and retrieve results.
Note: The number of latency ranges (“buckets”) supported varies depending on card type.Step 1 Enable the Signature Field (Transmit Card)
Histograms depend on information in the Signature field. The Signature field must be enabled when a stream is defined. When creating frames with any of the following, enable the Signature field by setting ucTagField = 1, as shown below.
Step 2 Activate the Histogram (Receive Card)
Activate the desired histogram on the card by using HTSetCommand with NS_HIST_n or HTSetStructure with FR_HIST_n. The histogram is now in receive mode until you query it for information or records.
Histogram types include the following for NS.
HTSetStructureL3_DEFINE_x_STREAML3_DEFINE_MULTI_x_STREAML3_MOD_x_STREAMFR_DEFINE_x_STREAMFR_MOD_x_STREAMucTagField = 1
Original Function
Message Function iType Parameter
Related Structure Description
HTSetCommand NS_HIST_<type> See below Activate the desired histogram.
HTSetStructure FR_HIST_<type> See below Activate the desired histogram.
Histogram iType1 (Related Structure)
Latency over Time NS_HIST_LATENCY_OVER_TIME (NSHistLayerOverTime)
Latency per Stream NS_HIST_COMBO_PER_STREAM (NSHistLatencyDistPerStream)
Latency Distribution NS_HIST_LATENCY_DISTRIBUTION (Layer3HistDistribution)
Sequence Tracking NS_HIST_SEQUENCE_PER_STREAM ( )
Raw Tags NS_HIST_RAW_SIGNATURE ( )
Chapter 5: Histogram ResultsHow to Set Up Histograms
SmartLibrary Overview and Procedures | 81
Histogram types include the following for frame relay (FR).
Step 3 Clear Previous Records (Receive Card – Optional)
You can clear all previous records by using the HTSetCommand with L3_HIST_START. (There is no equivalent FR_HIST_START command.)
Step 4 Transmit Test Traffic (Transmit Card)
Start transmitting test traffic using a function such as HTRun or HGRun. You can send traffic however you wish (Step, Burst, or Constant stream). The port will continue to collect histogram data until histogram records or information is retrieved.
Note: After you start transmitting, remember to allow enough time before attempting to retrieve histogram results.
Step 5 Query Card for Test Information (Receive Card — Optional)
You can find out how many records are on the card by using HTGetStructure with L3_HIST_ACTIVE_TEST_INFO or FR_HIST_ACTIVE_TEST_INFO. This information is useful, for example, when you do not want to retrieve all records.
Histogram Message Function iType Parameter
Latency over Time FR_HIST_V2_LATENCY
Latency per Stream FR_HIST_V2_LATENCY_PER_STREAM
Latency Distribution FR_HIST_LATENCY_DISTRIBUTION
Sequence Tracking FR_HIST_SEQUENCE
Original Function
Message FunctioniType1 Parameter
Related Structure Description
HTSetCommand L3_HIST_START None Clear previous records. (There is no equivalent FR function.)
Original Function
Message FunctioniType1 Parameter Related Structure Description
HTGetStructure L3_HIST_ACTIVE_TEST_INFO Layer3HistActiveTest Get the number of histogram records and the active histogram.FR_HIST_ACTIVE_TEST_INFO None
Chapter 5: Histogram ResultsHow to Set Up Histograms
82 | SmartLibrary Overview and Procedures
Step 6 Retrieve Histogram Results (Receive Card)
Once test traffic has been sent, retrieve histogram results using HTGetStructure with L3_HIST_x_INFO or FR_HIST_x_INFO.
The number of histogram records retrieved is determined by:
• The starting record specified by the index (iType2).
• The number of structures defined in pData.
The histogram records remain on the card until you clear them, select another histogram, or power off.
Once a histogram is enabled, it is in receive mode. It will continue to analyze all incoming frames containing signatures until it is queried for information or records.
You can stop the histogram receive process in two ways:
• Get histogram records using HTGetStructure by using L3_HIST_x_INFO.
• Get information about the histogram using L3_ACTIVE_TEST_INFO.
Original FunctionMessage FunctioniType1 Parameter Related Structure Description
HTGetStructure L3_HIST_<type>_INFO L3<type>Info Get histogram results for active histogram <type>.FR_HIST_<type>_INFO None
Chapter 5: Histogram ResultsCard Support for Latency “Buckets”
SmartLibrary Overview and Procedures | 83
Card Support for Latency “Buckets”The SmartMetrics and TeraMetrics-based modules support either eight or 16 latency range settings (“buckets”), depending on module type. Table 5-1 lists the ATM, Ethernet, Fibre Channel, and POS modules for the SmartBits 600x/6000x and shows the number of latency buckets provided by each module type.
Table 5-1. Number of Latency “Buckets” by Card Type
Module Number of Latency Buckets
ATM
ATM-345xA/As 16
Ethernet
LAN-3100A N/A
LAN-3101A/B 16
LAN-3102A 16
LAN-3111A/AS 16
LAN-3150A N/A
LAN-3300A 16
LAN-3301A 16
LAN-3302A 16
Gigabit Ethernet
LAN-3200A/AS N/A
LAN-3201B/C 8
LAN-3310A 16
LAN-3311A 16
LAN-3710AE 8
LAN-3710AL 8
LAN-3710AS 8
XLW-372xA 16
XFP-373xA 16
Chapter 5: Histogram ResultsCard Support for Latency “Buckets”
84 | SmartLibrary Overview and Procedures
Module Number of Latency Buckets
Ethernet Dual Media
LAN-3320A 16
LAN-3321A 16
LAN-3324A 16
LAN-3325A 16
LAN-3327A 16
Fibre Channel
FBC-3601A 16
FBC-3602A 16
POS
POS-3500B/BS 8
POS-3502A/AS 8
POS-3504As/AR 16
POS-3505As/AR 16
POS-3510A/AS 16
POS-3511A/AS 16
POS-3518As/AR 16
POS-3519As/AR 16
Table 5-1. Number of Latency “Buckets” by Card Type (continued)
SmartLibrary Overview and Procedures | 85
Chapter 6
General Programming Information
In this chapter...
• Firmware Requirements . . . . 86
• Guidelines for All Environments . . . . 86
• Establishing a Link from the PC to SmartBits . . . . 87
• Automatic Defaults for Message Functions . . . . 89
• How to Identify Hubs, Slots, and Ports . . . . 94
• Compatible and Native Modes for the SmartBits 600x/6000x . . . . 94
• Stacking and Synchronizing Multiple Chassis . . . . 100
• Understanding Multi-user Access . . . . 103
Chapter 6: General Programming InformationFirmware Requirements
86 | SmartLibrary Overview and Procedures
Firmware RequirementsRefer to the Release Notes included on your SmartLibrary distribution CD for a complete listing of chassis firmware and card firmware supported by the SmartLibrary 4.00 release.
You can obtain the most current release of SmartBits firmware from the Spirent web site.1 Go to http://www.spirentcom.com2 Select SmartBits.3 Click on the Support link.
Guidelines for All EnvironmentsHere are general programming notes for working with SmartLibrary. For information on programming in specific environments, see the appropriate chapters in this manual—either Programming in MS Windows™ or Programming in UNIX.
Including Header FilesSource code/interface modules that call SmartLibrary library routines must include the appropriate header file, such as et1000.h for C/C++ or smartlib.bas for 32-bit Visual Basic.
Linking with Library FilesApplications that call SmartLibrary functions must link with the appropriate SmartLibrary library file. Each programming environment has a facility for configuring a list of library/shared object subdirectories. The SmartLibrary library file must reside in one of the directories on the library subdirectory list. Some programming environments require that this library be added to the project manually.
Tcl Stubs
SmartLibrary version 3.12 and later supports Tcl stubs. This allows Tcl extension packages built using the feature to be used with Tcl versions 8.1 and higher. As a result, SmartLibrary Tcl extension packages (tclstruct and tclet100) do not need to be rebuilt in order to be used with newer versions of Tcl (for example, Tcl 8.4).
Chapter 6: General Programming InformationEstablishing a Link from the PC to SmartBits
SmartLibrary Overview and Procedures | 87
Establishing a Link from the PC to SmartBitsYou can use several commands to establish a connection (either serial or IP) from the PC to the SmartBits chassis and to break the link.
Use NSSocketLink in Multi-user ApplicationsETSocketLink, by default, reserves all available slots in the chassis to the issuing user. In contrast, with NSSocketLink, you can reserve either all available slots, or none of the slots. When you reserve no slots using NSSocketLink, you can use HTSlotReserve to reserve a subset of slots, leaving other slots available to other users. This creates a multi-user environment for the SmartBits chassis. See “Understanding Multi-user Access” on page 103 for further information.
Avoiding Link Time-outsA serial link between the PC and SmartBits never times out. An Ethernet link, in contrast, normally times out after 30 minutes of inactivity. If the PC does not initiate communications for 30 minutes, the SmartBits chassis will close the socket connection. This frees the SmartBits to accept other link attempts, should the initial link connection be lost. The library, however, includes a keep-alive thread that will keep an idle chassis socket connection from timing out. Implementation of a separate keep-alive routine is no longer required.
Command Function Notes
ETLink Establishes a serial link to a SmartBits 1000 orSmartBits 200/2000.
—
ETSocketLink Establishes an IP socket connection to a SmartBits chassis.
Use a serial-port connection to define the SmartBits IP address.
ETUnLink Breaks the current connection set up by using ETLink, ETSocketLink, or NSSocketLink.
—
NSSocketLink Establishes an IP socket connection to a SmartBits chassis. Optionally, in multi-user-compatible chassis, reserves either all cards or none of the cards in the chassis.
Use a serial-port connection to define the SmartBits IP address.
See “Understanding Multi-user Access” on page 103 for further information.
NSUnLink Breaks the current connection set up by using ETLink, ETSocketLink, or NSSocketLink.
—
Chapter 6: General Programming InformationEstablishing a Link from the PC to SmartBits
88 | SmartLibrary Overview and Procedures
SmartLibrary Response to a Broken Link or Link Time-outUsually a link is closed through an ETUnLink or NSUnLink command. Occasionally a link becomes broken because of network failure, power loss, or chassis time-out. If a link breaks while a SmartLibrary script or application is executing, the next SmartLibrary command that is issued attempts to elicit a response from the SmartBits link for 30 seconds, then reports an error.
You can increase or decrease the SmartLibrary time-out value with the ETSetTimeout command.
Note: Earlier SmartLibrary releases attempted to get a response for five minutes (default) before assuming a broken link.
Chapter 6: General Programming InformationAutomatic Defaults for Message Functions
SmartLibrary Overview and Procedures | 89
Automatic Defaults for Message FunctionsThe SmartLibrary programming library provides default configuration values for all Message Functions. (The Message Functions are described in detail in the SmartLibrary Command Reference). This feature, first introduced in version 3.07, is available on all supported platforms and for all supported programming languages.
Note: Default values are available only for the Message Functions, not for Original Functions.The availability of default configuration values provides a number of benefits:
• Development SpeedYou can simply specify the parameters you are interested in. Other values are filled in automatically.
• Short Learning TimeDefault values are valid within the context of the card and the command. This allows you to use our values while you are learning new technologies and equipment.
• Fewer ErrorsSupplied default values reduces the chance of introducing errors when you are entering long lists of values.
• Shared ConfigurationsYou can modify the values so that a customized defaults file can be shared between people and across projects.
Default Values File (smartlib.dft)The default values are contained in an ASCII file: smartlib.dft. The values for each structure are separated by a carriage return.
This file is installed in a shared directory:
• MS Windows It is installed in the Windows directory.
• UNIX It is installed in the home directory of the current user.
SmartLibrary will search first the current directory, then the system’s shared directory to find smartlib.dft.
Note: A –35 (file I/O error) is returned if default values are used and SmartLibrary cannot find smartlib.dft.
Chapter 6: General Programming InformationAutomatic Defaults for Message Functions
90 | SmartLibrary Overview and Procedures
How to Use Default ValuesYou can use the default values in your applications and scripts in a number of ways.
Note: The syntax for the Tcl interface has added options. Refer to Chapter 10, “Using Tcl and SmartLibrary” (see “Default Values with the Tcl Interfaces” on page 168).
HTDefaultStructureUse HTDefaultStructure to populate a structure with all or some default values. HTDefaultStructure looks similar to the other three Message Functions; however, it is only used to create structures (groups of configuration values). Also, it requires a different number of parameters from the regular Message Functions.
Note: HTDefaultStructure requires Hub, Slot, Port parameters, so that the card model can be checked. This means that for defaults to take effect the link from your computer to the chassis must be active.
HTDefaultStructure
Below are examples of using the new function HTDefaultStructure to set the traffic configuration on a Gigabit SmartCard. The example sets up default values for the Gigabit Transmit structure and then overwrites the gap setting.
Description Puts appropriate default values in the specified Message Function structure.
Syntax int HTDefaultStructure(int iType1,void* pData,int iSize,int iHub, int iSlot, int iPort);
Parameters iType1 int Defines the command action.pData void* Pointer to a structure (or an array of structures) that
will receive the default values.iSize int Indicates the size of pData. iHub int Identifies the hub where the card is located.
The range is 0 (first hub) through N (number of hubs − 1). Remember to subtract one since the hub identification starts at 0.
iSlot int Identifies the slot where the card is located. Range: 0 (first slot in Hub) to nn (last card in Hub).
iPort int Identifies the port on the card or module.
Return Value The return value is >= 0 if the function executed successfully. The return value is < 0 if the function failed.
Comments This command is used with the Message Functions: HTSetCommand() and HTSetStructure(). Select the desired iType1 and related structure.
Chapter 6: General Programming InformationAutomatic Defaults for Message Functions
SmartLibrary Overview and Procedures | 91
C/C++ Example
Tcl Example
Editing the Defaults FileSmartLibrary includes an ASCII file containing default values for Message Functions, where you can set values (predominantly the HTSetStructure commands). You can edit this file, add comments, even rename the file to create multiple customized files.
ExampleHere is an example of an entry in the smartlib.dft file, showing a set of configuration options for a 1000Mbps Ethernet SmartCard:
If you want to edit the default values, simply open smartlib.dft with a text editor, and replace existing values of the iType1 that you are working with.
GIGTransmit myGigTx;HTDefaultStructure(GIG_STRUC_TX, &myGigTx, sizeof(GIGTransmit),iHub, iSlot, iPort);
myGigTx.ulGap = 960;// ... set any other non-default parameters here
HTSetStructure(GIG_STRUC_TX, 0, 0, 0, &myGigTx, sizeof(GIGTransmit),iHub, iSlot, iPort);
struct_new myGigTx GIGTransmit HTDefaultStructure $GIG_STRUC_TX myGigTx 0 $iHub $iSlot $iPort set myGigTx(ulGap) 960# ... set any other non-default parameters here
HTSetStructure $GIG_STRUC_TX 0 0 0 myGigTx 0 $iHub $iSlot $iPort
iType1: FST_VLANucVLANEnable: 0uiTPID: 0x8100ucPRI: VLAN_PRI_0ucCFE: VLAN_CFI_RIF_ABSENTuiVID: 0
Command (iType1)
Relatedfield/membernames areterminatedby a colon
Values are separatedby a carriage return
Chapter 6: General Programming InformationAutomatic Defaults for Message Functions
92 | SmartLibrary Overview and Procedures
Different Card Models/Different Defaults
In some cases, you may want to use the same command with different defaults for different cards. You can specify more than one set of values for a given command by using iCardModel to specify the card to which the values apply.
Note: For a list of the currently supported card model constants, you can search et1000.* for CM_.
Where no card model is specified, values apply to all cards that accept the command (except for cards specified in another entry for the same command).
Where a card model is specified by iCardModel, values are used with only that card.
An error is returned if defaults for a card are requested and the only default values for that command are specified for use with a different card. To avoid this error, provide one group of defaults for a command that does not have a card specified.
iType: ATM_DS1_E1_LINE_PARAMiCardModel: CM_AT_9015ucTxClockSource: ATM_INTERNAL_CLOCKucCellScrambling: 1ucHecCoset: 1ucRxErroredCells: ATM_CORRECT_ERRORED_CELLSucLoopbackEnable: ATM_LOOPBACK_DISABLEDucIdleCellHeader: 0ucFramingMode: ATM_CS_1_CELL_FRAMINGucLineBuildout: ATM_DS1_0_TO_133_BUILDOUTucLineCoding: ATM_DS1_B8ZS_ENCODINGucLineFraming: ATM_DS1_ESF_LINE_FRAMING
iType: ATM_DS1_E1_LINE_PARAMiCardModel: CM_AT_9020ucTxClockSource: ATM_INTERNAL_CLOCKucCellScrambling: 1ucHecCoset: 1ucRxErroredCells: ATM_CORRECT_ERRORED_CELLSucLoopbackEnable: ATM_LOOPBACK_DISABLEDucIdleCellHeader: 0ucFramingMode: ATM_E1_CELL_FRAMINGucLineBuildout: ATM_E1_BUILDOUTucLineCoding: ATM_E1_HDB3_ENCODINGucLineFraming: 0
Here are two setsof values for onecommand. Notethe iCardModeland card value.
Chapter 6: General Programming InformationAutomatic Defaults for Message Functions
SmartLibrary Overview and Procedures | 93
Syntax for smartlib.dftBelow is a list of guidelines for working with smartlib.dft.
• smartlib.dft is case sensitive.
• Do not use carriage returns within a group of values. Carriage returns are used between different iType parameter groups.
• Other than carriage returns, white space does not affect value interpretation.
• You can enter constants or their numeric counterparts.
• Prefix hexadecimal values with 0x.
• Prefix octal values with a leading 0 (zero).
• To specify an array of values, specify the number of elements within square brackets, then the values of each element, separated by a comma. If you specify more elements than values, the last value is repeated for a full number of elements:Example: ucFieldName[6]: 1 2 3This would result in the array 1 2 3 3 3 3.
• Comments may be entered on any line, within value groupings or between them. If you place a comment within a value group, be sure not to split the comment by carriage returns.
• No special characters are needed to signify a comment.
• Avoid putting comments on lines with values. Put comments on separate lines.
• There must be a value specified for each field (the value can be 0).
Different Default FilesIf you want to have different *.dft files, you can save the file under a different file name. Specify the active *.dft file using the NSSetDefaultsFile command. You can use this command to specify either:
• The active default values file name.
• The full path.
If the library cannot find a defaults file and your program uses default values, the error code −35 (file I/O error) is returned.
Chapter 6: General Programming InformationHow to Identify Hubs, Slots, and Ports
94 | SmartLibrary Overview and Procedures
How to Identify Hubs, Slots, and PortsTo identify a port in a SmartBits chassis, you specify three values:
• Hub # The SmartBits chassis that contains the SmartCard or module
• Slot # The slot where the card or module is inserted
• Port # The port on the card or module
These are referred to collectively as the Hub/Slot/Port triple. For all three values, numbering starts at 0. For example, the values iHub 0, iSlot 2, and iPort 0 specify the first hub (0), third slot (2), and first port (0).
Compatible and Native Modes for the SmartBits 600x/6000xWith a SmartBits 600x/6000x chassis, you can use either of two port mapping modes to identify card and port locations. These are termed the Compatible and Native modes. You use the NSSetPortMappingMode function to set the port mapping mode. See “Library Functions for Port Mapping Modes” on page 98.
Compatible Mode in SmartBits 600x/6000xWhen used with a SmartBits 600x/6000x chassis, the Compatible mode enables you to use the same hub/slot/port values as with a SmartBits 1000 or SmartBits 2000. For compatibility, each SmartBits 600x/6000x port is considered to be the same as a slot and is assigned a slot number, even though a module has multiple ports. After 20 ports (“slots”), the hub number increases by one (see figure).
In the Compatible mode with the SmartBits 600x/6000x, the Hub/Slot/Port triple consists of:
• iHub 0, 1, 2, or 3
• iSlot 0 − 19
• iPort 0
Numbering with Four-port ModulesFor modules with four ports, Compatible port mapping in a SmartBits 6000x is as shown in the figure below. In this example:
• Slot numbering runs from top left to bottom right.
• Each module has four ports (“slots”).
• The first five modules fill the first “hub” of 20 ports (H0).
• The last module begins the second hub (H1). Slot numbers start at 0 again.
Chapter 6: General Programming InformationCompatible and Native Modes for the SmartBits 600x/6000x
SmartLibrary Overview and Procedures | 95
Numbering with Two-port ModulesWith two-port modules in a SmartBits 600x/6000x, each port still counts as one slot. The hub number increments when 20 ports (“slots”) have been counted.In the example below, the top four modules each have two ports (eight “slots” total). The fifth and sixth modules each have eight ports (“slots”). This causes the second “hub” (H1) to begin after the 4th port in the sixth module.
H0 / S0 / P0H0 / S1 / P0
SmartBits 6000
H0 / S2 / P0H0 / S3 / P0
H1 / S1 / P0H1 / S0 / P0
H1 / S3 / P0H1 / S2 / P0
Hub #0
Hub #1
SmartBits 6000x
= Hub 0, Slots 0 - 19= Hub 1, Slots 0 - 15
H1 / S0 / P0
H0 / S0 / P0
SmartBits 6000SmartBits 6000x
Chapter 6: General Programming InformationCompatible and Native Modes for the SmartBits 600x/6000x
96 | SmartLibrary Overview and Procedures
Maximum Port Count in Compatible ModeUsing eight-port modules in a SmartBits 6000x chassis, you could have as many as 96 ports installed. With the Compatible mode, however, only 80 of these ports can be addressed—that is, four “hubs” of 20 ports each. The remaining 16 ports cannot be addressed and so cannot be used.
All ports are available when the Native mode is used. See “Native Mode in SmartBits 600x/6000x” on page 97 for further information.
Numbering with Empty SlotsIn Compatible mode, slot numbers increment only when ports are physically installed. If there are empty card positions and slots, the slot numbers continue with the next card or module that is physically installed.
H0 / S0 / P0
SmartBits 6000
Slot numbers incrementonly when ports arephysically installed. H0 / S7 / P0
H0 / S8 / P0
SmartBits 6000x
Chapter 6: General Programming InformationCompatible and Native Modes for the SmartBits 600x/6000x
SmartLibrary Overview and Procedures | 97
Native Mode in SmartBits 600x/6000xThe Native port mapping mode can be used with any SmartBits chassis. It was developed originally for the SmartBits 6000 chassis. In the Native mode, the Hub/Slot/Port triple consists of the following:
Numbering with Empty SlotsWith Native port mapping, slot numbers increment whether or not ports are physically installed. In the example below, slots 4 and 5 are counted even though a module is not installed.
Value SmartBits 200/2000 SmartBits 600x/6000x
iHub 0, 1, 2, 3 0
iSlot 0 through 19 0 − 1 (SmartBits 600x)
0 − 11 (SmartBits 6000x)
Each module counts as one slot with one or more ports.
iPort 0 0 − 7 (depending on module type)
H0 / S0 / P0
SmartBits 6000
Slots 4 and 5 are countedeven though no module isinstalled.
H0 / S3 / P1
H0 / S6 / P0
SmartBits 6000x
Chapter 6: General Programming InformationCompatible and Native Modes for the SmartBits 600x/6000x
98 | SmartLibrary Overview and Procedures
Library Functions for Port Mapping ModesThe following SmartLibrary commands are used to manage the port mapping modes described above.
• NSSetPortMappingModeThis function sets the port mapping mode (either Compatible or Native) for the SmartBits chassis.
• NSGetMaxHubsThis function returns the maximum number of hubs per stack. It returns a value of 4 whether the connection is to a stack of SmartBits 2000s or a SmartBits 6000x. This function replaces the constant MAX_HUBS. It is useful when allocating memory.
• NSGetMaxSlotsThis function returns the maximum number of slots per hub. It replaces the constant MAX_SLOTS. It is useful when allocating memory.
• NSGetMaxPortsThis function returns the maximum number of ports per slot/card. It replaces the constant MAX_PORTS. It is useful when allocating memory.
• NSGetNumHubsThis function returns the number of hubs possible for the chassis type. Values returned are 4 for a SmartBits 2000 and 1 for a SmartBits 600x/6000x or SmartBits 200.
• NSGetNumSlotsThis function returns the number of slots possible for the specified chassis (not the number of cards available).
• NSGetNumPortsThis function returns the number of ports possible for a specified card. SmartCards have one port per card. Modules have two or more ports per module.
The NSGetNum functions are useful for creating a loop to access all ports. For example:
for (iHub=0; iHub < NSGetNumHubs(); iHub++) for (iSlot=0; iSlot < NSGetNumSlots(iHub); iSlot++) for (iPort=0; iPort < NSGetNumPorts(iHub,iSlot); iPort++) HTSetStructure (iType1….. iHub,iSlot,iPort);
Chapter 6: General Programming InformationCompatible and Native Modes for the SmartBits 600x/6000x
SmartLibrary Overview and Procedures | 99
Summary of Returned ValuesFor the functions described above, SmartBits returns the following values for each SmartBits chassis. Hard-coding these values into a script, rather than using the functions, reduces the portability of your script and is highly discouraged.
Command SmartBits 2000 SmartBits 200 SmartBits 6000x SmartBits 600x
NSGetMaxHubs 4 4 4 4
NSGetMaxSlots 20 20 32 32
NSGetMaxPorts 2 2 16 16
NSGetNumHubs 4 1 1 1
NSGetNumSlots 20 4 12 2
NSGetNumPorts Card-dependent Card-dependent Card-dependent Card-dependent
Chapter 6: General Programming InformationStacking and Synchronizing Multiple Chassis
100 | SmartLibrary Overview and Procedures
Stacking and Synchronizing Multiple ChassisChassis management and hub numbering follow specific rules when SmartBits chassis are stacked or interconnected for synchronization.
Stacking Multiple SmartBits
SmartBits 2000You can interconnect SmartBits 2000 chassis in a stack of up to four hubs by using the37-pin stacking connector on the back panel.
When this is done, the top chassis becomes the controller chassis. You then use a connection from the PC to the controlling chassis to manage all hubs in the stack. In effect, the controllers of the other hubs are disabled.
Note: The SmartBits 200 chassis may not be stacked.
SmartBits 600x/6000xSmartBits 600x/6000x chassis may not be stacked, but individual chassis can be connected to the same PC through separate controller links.
Synchronizing Chassis or StacksYou can interconnect the controlling chassis in SmartBits 200/2000 and SmartBits 600x/6000x chassis, to synchronize all the chassis. One chassis, termed the master controller, is used to synchronize all the chassis. Each controlling chassis that uses the master controller's clock is considered a slave controller.
Note: Chassis also can be synchronized through GPS connections. Refer to Using GPS with SmartBits Chassis for further information.
Chapter 6: General Programming InformationStacking and Synchronizing Multiple Chassis
SmartLibrary Overview and Procedures | 101
Identifying Hub Values for Stacked ChassisThe iHub values for controller hubs start at 0 and increment by four (that is, 0, 4, 8, 12, and so on). This is true whether or not the controller hub has other hubs connected to it (using the 37-pin stacking cable), and whether or not the stack is “full” (contains all four hubs).
SmartBits 6000xFigure 6-1 shows three SmartBits 6000x chassis connected to the PC by separate controller links. Hub numbers are 0, 4, and 8.
Figure 6-1. Multiple SmartBits 6000x Hubs
SmartBits 2000Figure 6-2 on page 102 shows three stacks of SmartBits 2000 chassis.
The chassis at the top of each stack is the controller chassis for its stack. For synchronization among the stacks, the three controlling chassis are all interconnected through expansion links.
Hub numbers for the controller chassis in each stack increment by four, no matter how many chassis are actually present in each stack. Notice, for example, that the controller hub in the third stack is hub number 8 even though the first two stacks contain a total of only six chassis (four in the first stack and two in the second stack).
SmartBits 6000xHub 0
SmartBits 6000xHub 4
SmartBits 6000xHub 8
PCPC Links
Expansion Links tosynchronize hubs
Hubs 0, 4, and 8 link to the PC through individual controller links. They alsoare linked to one another, for synchronization, by using expansion links.
Chapter 6: General Programming InformationStacking and Synchronizing Multiple Chassis
102 | SmartLibrary Overview and Procedures
Synchronized Commands for Hub StacksIn Figure 6-2, only Hub 0 will receive synchronized commands such as HGStart, because the expansion connections signify that it is the master controller for all three stacks.
Note: For the master controller, only the OUT expansion connector is used, not the IN expansion connector.
Figure 6-2. Synchronizing Commands for Hub Stacks
PCPC Links
Expansion Links tosynchronize hubs
ControllerHub 0
ControllerHub 4
ControllerHub 8
Not PresentHub 1 Hub 5
Not Present Not PresentHub 2
Not Present Not PresentHub 3
ControllersHubs 0, 4, and 8are linked directlyto the PC andcontrol other hubsin their stacks.
Master HubBecause of theexpansion linkconnections, onlyHub 0 will receivesynchronizedcommands, such asHGStart.
See:HTSeparateHubCommands
Stacking Connectionsbetween hubs
Chapter 6: General Programming InformationUnderstanding Multi-user Access
SmartLibrary Overview and Procedures | 103
Understanding Multi-user AccessSmartLibrary releases after version 3.07 enable multiple users to gain access to a SmartBits 600x/6000x or SmartBits 2000 chassis and reserve slots for use in different tests. (Through this discussion, “SmartBits 6000x” comments apply to SmartBits 600x chassis as well.) Each user can become the owner of a subset of the cards or modules in the chassis. Reserved slots are used in tests, then may be released when no longer needed, to make them available to other users.
The multi-user capability is based on three new functions.
• HTSlotReserveReserves a specified slot to a user.
• HTSlotReleaseReleases slots that have been reserved through the HTSlotReserve function.
• HTSlotOwnershipShows current slot ownership.
Two additional new, related functions are:
• NSSocketLinkMakes an IP connection to the SmartBits chassis while reserving either all the available slots or none of the available slots in the chassis.
• NSUnLinkBreaks the connection on the current link and releases all reserved slots.
How Is NSSocketLink Different from ETSocketLink?Both NSSocketLink and ETSocketLink create an IP connection to the SmartBits chassis, but they differ as follows:
• ETSocketLink, by default, reserves all available slots in a chassis to one user.
• NSSocketLink can reserve either all available slots or none of these slots.
If you use NSSocketLink and reserve none of the slots, you can use HTSlotReserve to reserve a subset of the slots (one or more), leaving the other slots available to other users.
Chapter 6: General Programming InformationUnderstanding Multi-user Access
104 | SmartLibrary Overview and Procedures
Getting Hub, Slot, and Card Information in Multi-user ModeMulti-user mode allows you to get hub, port, and card information on slots that you have reserved, as well on slots that are unreserved or reserved by another user.
You can use the Original Functions listed below.
Multi-user Access with the SmartBits 2000
SmartBits 2000 chassis with backplane revision D or later support multi-user access, using the functions described above.
Note: If you install a ST-6405, or ST-6410 SmartCard in a multi-user SmartBits 2000, the entire chassis automatically reverts to the single-user mode.
Mixing Multi-user and Single-user Chassis
You can connect a SmartBits 600x/6000x to a SmartBits 2000 with multi-user capability and use library functions in the normal way. If the SmartBits 2000 does not have multi-user capability, however, a connected SmartBits 6000x also becomes single-user (see table below). As examples, the following chassis combinations are possible:
Original Function Description
HTCardModels Gets the card model number.
HTGetCardModel Gets the card model number.
HTHubId Get currently connected port types.
HTHubSlotPorts Get currently connected port types.
HTPortProperty Find the card type at a specified hub/slot/port.
HTPortType Find the card type at a specified hub/slot/port.
SmartBits Connected To SmartBits
SmartBits 600x (Multi-user) ↔ SmartBits 6000x (Multi-user)
SmartBits 6000x (Multi-user) ↔ SmartBits 2000 (Multi-user)
SmartBits 6000x (Single-user) ↔ SmartBits 2000 (Single-user)
Chapter 6: General Programming InformationUnderstanding Multi-user Access
SmartLibrary Overview and Procedures | 105
Testing with Multiple SmartBits Chassis
When using a multiple chassis arrangement that contains SmartBits 6000x or 600x chassis, you must use a synchronous, CAT-5, straight-through (not crossover) cable to connect the chassis together. The cable should be one meter (1m) or less in length (an appropriate synchronous, CAT-5, straight-through cable is shipped with your SmartBits chassis). The use of the synchronous cable is required for overall test results to be accurate (not just latency test results, but all test results).
In addition, all chassis in the arrangement must be booted in the proper order. You must first boot the chassis that contains the master clock. Next, wait ten seconds and then boot the next chassis in the chain. Wait another ten seconds and then boot the next chassis, and so on. It is important that you wait ten seconds before booting the next chassis in line.
For detailed information on multiple chassis operation, refer to the SmartBits 200/2000 Installation Guide or the SmartBits 600x/6000x Installation Guide.
Multi-user and GPSSmartBits 600x/6000x systems can use GPS (Global Positioning System) synchronization for end-to-end performance testing when SmartBits systems are deployed in remote locations.
The multi-user capability is compatible with GPS synchronization, provided that the following guidelines are observed:
• A user requesting a GPS-synchronized action (start or stop) becomes the sole user of GPS functions during a period of about 10 seconds.
• If a second user requests a GPS-synchronized action on the same SmartBits chassis during the 10-second “lock-out,” SmartBits returns MULTI_USER_CONFLICT (−37).
• When using GPS in a multi-user environment, set your scripts to handle such conflicts. If MULTI_USER_CONFLICT (−37) is encountered, create a loop to pause for 10 seconds then repeat the request for synchronized action.
106 | SmartLibrary Overview and Procedures
SmartLibrary Overview and Procedures | 107
Chapter 7
Programming in MS Windows
This chapter provides information on programming in the Microsoft Windows environment. It includes installation instructions, directory and file definitions, general tips, and information specific to the C/C++, Tcl, and Visual Basic compilers.
You can use this set of library functions to develop Microsoft Windows™-based applications on any IBM PC or compatible system that supports MS Windows.
SmartLibrary functions can be called from any program using the cdecl convention or the FAR PASCAL convention. Any MS Windows application capable of calling a Dynamic Link Library (such as Excel, National Instruments LabView, and Visual Basic) can use these functions.
Note: Delphi support was discontinued in SmartLibrary 3.40.
In this Chapter...
• Installation . . . . 108
• General Programming Notes for Windows . . . . 109
• Directory Contents . . . . 110
• Developing with Tcl . . . . 111
• Developing with Visual Basic . . . . 112
• Developing with C/C++ . . . . 114
• Creating a Program with Microsoft Visual C++ . . . . 116
• Creating a Program with Microsoft Visual C++ . . . . 116
Chapter 7: Programming in MS WindowsInstallation
108 | SmartLibrary Overview and Procedures
Installation
Platform SupportSmartLibrary has been tested under the Windows versions listed below:
InstallationAutoPlay for CDs automatically runs the SmartLibrary installation script when you put the CD into your PC. If AutoPlay is not enabled, run the Setup.exe from the root directory. Then follow the step-by-step instructions. SmartLibrary will be installed in a directory you choose.
The Setup.exe program creates the directory structure shown below.
These directories organize files by programming language. SmartLibrary provides multiple program interfaces with header and project files for each program environment. Complete source code comments can be found in the C/C++ files contained in the Commlib directory.
See “Directory Contents” on page 110 for details on the files for each programming language.
Version
Windows 2000 Professional Edition SP4
Windows XP Professional Edition SP1/1a/2
Chapter 7: Programming in MS WindowsGeneral Programming Notes for Windows
SmartLibrary Overview and Procedures | 109
General Programming Notes for WindowsThe MS Windows link libraries are compiled with the Large memory model.
CompatibilityEvery effort is made to keep SmartLibrary compatible with earlier versions. As more functions are added, you may need to re-link your application with the new library. For Microsoft Windows applications using the DLL, re-linking may not be necessary.
Chapter 7: Programming in MS WindowsDirectory Contents
110 | SmartLibrary Overview and Procedures
Directory ContentsThe folders in the SmartLibrary directory have the following contents.
Note: Sample code in Tcl, C, and VB can be found either on the CD or in your installation directory.
\SmartLibThis directory (or the directory you selected for SmartLibrary) contains directories that hold program-specific files. In addition, it contains two files, readme.pdf and license.pdf.
\WindowsThis directory contains four subdirectories with the SmartLibrary files for MS Windows systems, as listed below. It also contains the smartlib.dft file, which holds default values for data structures. See Chapter 3, “Default Configuration Values” for further information.
\CommlibThis directory contains SmartLibrary's compiled DLL files for 32-bit Microsoft Windows. It also contains project and header files for C\C++. These contain the Original Functions and Message Functions. This directory also contains legacy Visual Basic *.txt files (included for compatibility).
\SamplesThis directory contains SmartLibrary sample scripts in C, Tcl, and Visual Basic.
\TclThis directory contains one subdirectory with all Tcl files, as listed below.
Notes: • SmartLibrary uses the same set of Tcl interface files for all supported versions of Tcl (8.3.5 and 8.4.5).
• SmartLibrary 3.12 and later supports Tcl stubs. This allows Tcl extension packages built using the feature to be used with Tcl versions 8.1 and higher. As a result, SmartLibrary Tcl extension packages (tclstruct and tclet100) do not need to be rebuilt in order to be used with newer versions of Tcl.
\TclFiles
This directory contains the Tcl files for Tcl 8.3 and Tcl 8.4, the SmartLibrary files tclet100.dll and tclstruc.dll, and additional files for use with either Tcl version.
\VB
This directory contains SmartLibrary project and header file for Microsoft Visual Basic, smartlib.bas.
Chapter 7: Programming in MS WindowsDeveloping with Tcl
SmartLibrary Overview and Procedures | 111
Developing with TclTcl is a flexible programming language, noted for its on-the-fly command-line capabilities. Tcl enables you to test a function call from the text-based command line without having to compile a program. This allows you to test your code line by line.
SmartLibrary supports Tcl Versions Tcl 8.3.5, and 8.4.5 in both Windows and UNIX. These Tcl versions are included with the SmartLibrary Software Developer's Kit, along with the SmartLibrary files needed to develop test applications with Tcl.
Related InformationFor an extensive discussion on using SmartLibrary with Tcl, see Working with Tcl in this manual. For Tcl examples, see the files under \Samples\Tcl\ on the CD or your installation drive.
Tcl DirectoryThe Tcl directory contains one subdirectory with the files listed below. SmartLibrary uses the same set of Tcl interface files for all supported versions of Tcl (8.3.5 and 8.4.5).
File Name Description
et1000.tcl SmartLibrary header file containing SmartLibrary defines, structure definitions, and function prototypes for the original SmartLibrary Tcl interface.
misc.tcl Tcl error-handling utility used to capture return values.
show.tcl Tcl utility used to view elements in a structure.
smartlib.tcl SmartLibrary header file for the new SmartLibrary Tcl interface.
tclet100.dll SmartLibrary API for Tcl. This file maps Tcl calls to the main ETSMB*.DLL.
tclstruc.dll Tcl DLL used for creating structures.
Chapter 7: Programming in MS WindowsDeveloping with Visual Basic
112 | SmartLibrary Overview and Procedures
Developing with Visual BasicThe SmartLibrary Programming Library includes files for the Microsoft Visual Basic environment. Much of the information for C/C++ also applies to Visual Basic. Exceptions and differences are noted in this section.
Important Differences between Visual Basic and C/C++
Case Sensitivity and Parameter NamesC/C++ is case sensitive; Visual Basic is not. Some parameters with identical functions have different names in each language, as shown below.
Space for IntegersIn Visual Basic, integers require the same amount of space in both the 16-bit and32-bit versions. In C/C++, int requires a larger memory allocation in the 32-bit version than in the 16-bit version. This means that items appearing in this manual as int are declared as Long in the SmartLibrary header and LIB files for 32-bit Visual Basic.
Unsigned TypesVisual Basic does not support unsigned types. In some cases where unsigned types are specified, conversions must be made. An example is a counter result where all 32 bits are used to represent a positive number.
C/C++
Visual Basic(SmartLibrary Previous)
Visual Basic(SmartLibrary 3.02 and Later)
HTSTOP HTRUN_STOP Use either name.
HTSTEP HTRUN_STEP Use either name.
HTRUN HTRUN_RUN HTRUN_RUN or HTRUN_ VALUE
NOTE: Applies only to constant parameter. Do not change the name of the HTRUN function.
ETSTOP ETRUN_STOP Use either name.
ETSTEP ETRUN_STEP Use either name.
ETRUN ETRUN_RUN Use either name.
Chapter 7: Programming in MS WindowsDeveloping with Visual Basic
SmartLibrary Overview and Procedures | 113
Parameters for the HTVFDStructureVB parameter names for the HTVFDStructure now match more closely the parameter names used in C/C++.
Files for Visual BasicThe interface file needed to use SmartLibrary with Visual Basic is in the Vb directory. For file descriptions, see “Developing with Visual Basic” on page 112.
The following files are used when developing with Visual Basic.
C/C++Visual Basic(SmartLibrary Previous)
Visual Basic(SmartLibrary 3.02 and Later)
*Data iPointer pData
DataCount iLength DataCount
File Name Description
ETSMBW32.DLL Dynamic link library for use with 32-bit applications developed for Windows. This file is located in the Commlib directory and installed in your Windows\System directory.
SMARTLIB.BAS Library header files of defines, structure definitions, and function prototypes.
ETSMBW32.TXT Visual Basic legacy files located in the Commlib directory.
ATMITM32.TXT Visual Basic legacy files located in the Commlib directory.
Chapter 7: Programming in MS WindowsDeveloping with C/C++
114 | SmartLibrary Overview and Procedures
Developing with C/C++For C/C++ program development, you must reference the ET1000.H file by using an include statement in your source files. This file provides the function prototypes, defined values, and structure declarations used by the library. You must also link with the SmartLibrary *.LIB files that match your development environment.
Compiling Files
When developing with Microsoft Visual C/C++, compile using SMBW32VC.LIB.
File Descriptions (Commlib Directory)The files in the Commlib directory are used mainly when developing with C/C++, but this directory also contains SmartLibrary's central DLL files and legacy Visual Basic files.
File Name Description
atmapi.h In development for future release.
atmtmitems.h Library header file of defines and structure definitions for ATM TeraMetrics modules.
atmitems.h Library header file of defines and structure definitions for ATM SmartCards.
atmitm32.txt Visual Basic 5 legacy file needed only for compatibility with earlier Visual Basic/SmartLibrary applications.
atmsgapi.h Library header file of the Smart API for ATM Signaling tests.
et1000.h Library header file of basic defines, structure definitions, and all function prototypes.
ethitems.h Library header file of defines and structure definitions for the new Ethernet Message Functions.
Etsmbw32.dll Dynamic link library for use with 32-bit applications developed for Windows 98 or NT.
etsmbw32.txt Visual Basic 5 legacy file needed only for compatibility with earlier Visual Basic/SmartLibrary applications.
ettypes.h Library header file of necessary ETSMB variable types (such as U64 when working with 64-bit numbers).
fcitems.h Library header file of defines and structures for the Fibre Channel modules.
Continues –>
Chapter 7: Programming in MS WindowsDeveloping with C/C++
SmartLibrary Overview and Procedures | 115
frame.h Library header file for the newer, easier frame-building functions: NSCreateFrame, NSSetPayLoad, HTFrame, NSDeleteFrame, NSCreateFrameAndPayload, NSModifyFrame.
fritems.h Library header file of defines and structure definitions for the Frame Relay cards.
fstitems.h Library header file of defines and structure definitions for the Fast Ethernet (100MB) cards.
gigitems.h Library header file of defines and structure definitions for Gigabit Ethernet cards.
l2items.h Library header file of defines and structure definitions for Layer 2 cards.
l3items.h Library header file of defines and structure definitions for Layer 3 and Multi-layer cards.
nsitems.h Library header file of defines and structure definitions for Universal commands that apply across card families.
positems.h Library header file of defines and structure definitions for POS cards.
pppitems.h Library header file of defines and structure definitions for PPP functions.
smbw32vc.lib The Visual C/C++ compatible import library used with the ETSMBW32.DLL for 32-bit applications.
stmitems.h Library header file of defines and structure definitions for some common Stream items.
tcpisp.h In development for future release.
tcpitems.h In development for future release.
testapi.h Library header file of the Smart API for RFC-1242 and RFC-1944 Tests.
testcmmn.h Library header file of common defines and structure definitions.
wanitems.h Library header file of defines and structure definitions common to both Wide Area Network SmartCards (ATM and Frame Relay). This file includes defines such as DSI, EI, and DS3.
File Name Description
Chapter 7: Programming in MS WindowsCreating a Program with Microsoft Visual C++
116 | SmartLibrary Overview and Procedures
Creating a Program with Microsoft Visual C++This section explains step-by-step how to use Microsoft Visual C++ to create a SmartLibrary program.
Note: For detailed information on Visual C++, refer to your product documentation.
Creating a Basic Application with VC++Before you start, make sure that etsmbw32.dll is in your Windows system directory.
Then use the following steps.Step 1 Open Visual C++. Select File > New from the Main menu.
Chapter 7: Programming in MS WindowsCreating a Program with Microsoft Visual C++
SmartLibrary Overview and Procedures | 117
Step 2 Select Win32 Console Application as the Project Type. Type the name for your project in the Project name box.
Step 3 When prompted for the type of console application you want to create, select An empty project. We have created a basic empty project shell. Now we will set it up for a SmartLi-brary application.
Chapter 7: Programming in MS WindowsCreating a Program with Microsoft Visual C++
118 | SmartLibrary Overview and Procedures
Setting Up a SmartLibrary ApplicationStep 1 Select Project > Add to Project > New from the Main menu.
Step 2 Select C++ Source File. Enter the name for your source file in the File Name box.
Chapter 7: Programming in MS WindowsCreating a Program with Microsoft Visual C++
SmartLibrary Overview and Procedures | 119
Step 3 Select Project > Add to Project > Files from the Main Menu.
Step 4 Set the Look in: combo box to the CommLib directory of your SmartLibrary installation. Select smbw32vc.lib.
Chapter 7: Programming in MS WindowsCreating a Program with Microsoft Visual C++
120 | SmartLibrary Overview and Procedures
Step 5 Now select Tools > Options from the Main Menu.
Step 6 Add the CommLib directory from your SmartLibrary installation to the list of included directories. In the example shown below, the library was installed at C:\Net-com\PL307SP3, so we add the path to C:\Netcom\PL307SP3\CommLib to the list.
Chapter 7: Programming in MS WindowsCreating a Program with Microsoft Visual C++
SmartLibrary Overview and Procedures | 121
Writing a Simple ProgramNow you are ready to write your program. At the top of the program put #include "et1000.h" to include the SmartLibrary resources in your project. Do not include any other header files from the CommLib directory.
The simple C program below will link and UnLink to a SmartBits chassis.
When you are finished, select Build > Execute from the Main Menu, or just click the red exclamation point icon on the tool bar. You should see a command shell start and link to the chassis.
Chapter 7: Programming in MS WindowsCreating a Program with Microsoft Visual C++
122 | SmartLibrary Overview and Procedures
Next StepsThe simple program you have just created is not useful for much more than testing that the library and Microsoft Visual C++ are installed correctly and you have configured your base project correctly. We’ll need to add some more commands to actually test anything.
Input and Error HandlingOur simple program “hardcodes” the IP address of the SmartBits chassis. It also makes no provision for errors, which would occur if the chassis were switched off or not connected to the network.
We can modify our program to make it more robust and flexible with something like this:
We set up space for the user to input the IP address in a character string named ipaddr. Then we use a printf and scanf to prompt the user and store the address in ipaddr.
Then we use a variable named iRet to store the ETSocketLink function’s return value. In SmartLibrary, if a command does not succeed, it will return a negative number as its return value. We insert a simple for loop that tests the value of iRet, and if it is negative prints an error message for the user. In a real application, you probably would want to do something more helpful than simply print a message.
Card Numbering/Resetting Smart CardsThe hub slot port notation indicates the position of the SmartCard in the SmartBits. chassis. It is zero based, so the first card in the first chassis has a hub slot port number of 0 0 0. It is recommended that you set the hub slot port numbers of cards you will use to variables, so you can later change the cards used by changing the single variable assignment.
You can’t always be sure of the state of SmartCards when you start a test. They may still retain settings from a previous application. Sophisticated applications will often have their own custom reinitialization routines, but for a simple application we can use the HTResetPort library command.
int iRet;char ipaddr[16];
// prompt for IP and link to chassisprintf("Enter IP address of SmartBits chassis ==> ");scanf("%s",ipaddr);printf("Linking on %s \n", ipaddr);
// negative return value means command failediRet=ETSocketLink(ipaddr, 16385);if (iRet < 0){
printf("Error linking to chassis: %d \n",iRet);return iRet;
Chapter 7: Programming in MS WindowsCreating a Program with Microsoft Visual C++
SmartLibrary Overview and Procedures | 123
Transmission ParametersYou can use SmartLibrary to configure virtually every transmission parameter of a SmartCard, including packet length, contents, speed, duplex mode, and continuous or burst transmission.
In this program we’ll use the simplest HT commands to set the card to send a single burst of 100,000 packets.
Note: The HT commands and all Original Functions are described in Volume 1 of the SmartLibrary Command Reference.
Starting and Stopping TransmissionThe simplest way to start and stop transmission is by using the HTRun command. HTRun with the HTRUN mode argument will start the card transmitting. HTRun with the HTSTOP mode argument will stop the transmission.
Since we are transmitting a single burst, we don’t need in this case to send an explicit STOP. We would need to allow time for the 100,000 packets to be sent, if we didn’t have the Press ENTER prompt and read to stop program execution.
int hub1 = 0;int slot1 = 0;int port1 = 0;int hub2 = 0;int slot2 = 1;int port2 = 0;
// reset cardsHTResetPort(RESET_FULL,hub1,slot1,port1);HTResetPort(RESET_FULL,hub2,slot2,port2);
int numPackets = 100000;
// set transmission parameters, single burst of numPackets packets
HTTransmitMode(SINGLE_BURST_MODE,hub1,slot1,port1);
HTBurstCount(numPackets,hub1,slot1,port1);
// start transmitting from the first card
HTRun(HTRUN,hub1,slot1,port1);
// you could need a delay here before reading counter data
printf("Press ENTER key to get counts\n");
fflush(stdin);
getc(stdin);
Chapter 7: Programming in MS WindowsCreating a Program with Microsoft Visual C++
124 | SmartLibrary Overview and Procedures
Counters and StructuresEach card has counters that keep track of transmitted and received packet counts. Commands such as HTGetCounters transfer the counter data from the SmartCard to the controlling computer.
Before you get the counter data from the card, you need to set aside memory to hold it on the controlling computer by creating a structure.
This creates a structure named cs with the dimensions of the HTCountStructure blueprint. The elements of HTCountStructure are documented in the SmartLibrary Command Reference, with syntax and usage of the HTGetCounters command.
To read the counters, use HTGetCounters and pass the address of cs, then the hub/slot /port of the card from which you want the counter data.
Checking Test ResultsThere are more sophisticated ways of getting counters than have been shown, which has illustrated a simple method for a first program.
We assign the value of one of the counter elements from card 1, TmtPkt (Transmitted Packets), to a variable txPackets. We then read the data from card 2 into the same cs structure with HTGetCounters. Again we read the value of one element RcvPkt (Received Packets) into the variable rxPackets.
Now that we have the number of packets sent by card 1 and the number of packets received by card 2 we can make a simple test.
In an actual test through a multi-port device, you would need to be more discriminating. For example, a real test would need to filter out flooded packets and management frames. This gives an idea of how it is done, however.
// create counter structure
HTCountStructure cs;
// get the transmit counts from card1 then receive counts from card2HTGetCounters(&cs,hub1,slot1,port1);
txPackets = cs.TmtPkt;
HTGetCounters(&cs,hub2,slot2,port2);
rxPackets = cs.RcvPkt;
if (txPackets == rxPackets)
{
printf(“Test Passed! %d packets transmitted and card %d packets received\n”, txPackets, rxPackets);
} else {
Chapter 7: Programming in MS WindowsCreating a Program with Microsoft Visual C++
SmartLibrary Overview and Procedures | 125
Complete Program Listing#include <stdio.h>
#include "et1000.h"
int main()
{
int hub1 = 0;
int slot1 = 0;
int port1 = 0;
int hub2 = 0;
int slot2 = 1;
int port2 = 0;
int iRet;
int txPackets;
int rxPackets;
int numPackets = 100000;
char ipaddr[16];
HTCountStructure cs;
// prompt for IP and link to chassis
printf("Enter IP address of SmartBits chassis ==> ");
scanf("%s",ipaddr);
printf("Linking on %s \n", ipaddr);
// negative return value means command failed
iRet=ETSocketLink(ipaddr, 16385);
if (iRet < 0)
{
printf("Error linking to chassis: %d \n",iRet);
return iRet;
}
// reset cards
HTResetPort(RESET_FULL,hub1,slot1,port1);
HTResetPort(RESET_FULL,hub2,slot2,port2);
// set transmission parameters, single burst of numPackets packets
HTTransmitMode(SINGLE_BURST_MODE,hub1,slot1,port1);
HTBurstCount(numPackets,hub1,slot1,port1);
// start transmitting from the first card
HTRun(HTRUN,hub1,slot1,port1);
// you could need a delay here before reading counter data
printf("Press ENTER key to get counts\n");
fflush(stdin);
getc(stdin);
// get the transmit counts from card1 then the receive counts from card2
HTGetCounters(&cs,hub1,slot1,port1);
txPackets = cs.TmtPkt;
Chapter 7: Programming in MS WindowsCreating a Program with Microsoft Visual C++
126 | SmartLibrary Overview and Procedures
HTGetCounters(&cs,hub2,slot2,port2);
rxPackets = cs.RcvPkt;
if (txPackets == rxPackets)
{
printf("Test Passed! %d packets transmitted and card %d packets received\n",txPackets, rxPackets);
} else {
printf("Test Failed! \n");
}
ETUnLink();
return 0;
}
SmartLibrary Overview and Procedures | 127
Chapter 8
Programming in UNIX
This chapter provides information on programming in the UNIX environment. It includes installation instructions, directory and file definitions, general tips, and information specific to the C/C++ and Tcl compilers.
SmartLibrary supports C and Tcl (Versions 8.3.5 and 8.4.5) for the UNIX programming environment. It includes extensive Tcl and C code examples.
In this chapter...
• Installation . . . . 128
• Directory Structure and Content . . . . 130
• Developing with C/C++ . . . . 131
• Developing with Tcl . . . . 131
Chapter 8: Programming in UNIXInstallation
128 | SmartLibrary Overview and Procedures
Installation
Platform Support
SmartLibrary has been tested under the UNIX versions listed below:
ProcedureTo install SmartLibrary under UNIX, run the setup.sh installation utility. The CD contains both source code and pre-compiled shared libraries. Installation help is available during installation as a menu option. Use the following steps.
Note: Before you install SmartLibrary, the following programs must be installed on your system and in your PATH: gcc (including the standard C++ library), make, and gunzip.1 Insert the SmartLibrary CD-ROM into your CD drive.2 Mount the CD. This works differently on different platforms:
• Under Solaris, it is automatic. Your CD will be mounted at /cdrom/netcom. • Under Linux, enter mount -r /dev/cdrom /mnt/cdrom. Your CD will be
mounted at /mnt/cdrom. 3 Change to the directory where the CD is mounted. 4 Run the Setup script setup.sh. The SmartLibrary Installation Menu lets you to cus-
tomize the SmartLibrary installation to meet your needs. The following options are available:Install DirectorySelect this option to define the installation directory for SmartLibrary. Several subdi-rectories are created, depending on which features you choose to install:• The default destination directory for system-wide access is /usr/local/netcom/
smartlib.• The default destination directory for local access is <user’s home directory/net-
com/smartlib.The directory is created if it does not already exist.
Version Architecture GCC Version
Solaris 2.7 Sparc 2.95.2
Solaris 2.8 Sparc 2.95.2
Red Hat Linux 7.3 x86 2.96
Red Hat Linux EL3 (Enterprise Linux 3) WS
x86 3.20
Chapter 8: Programming in UNIXInstallation
SmartLibrary Overview and Procedures | 129
For system-wide access, it is best to install to the root directory and place SmartLi-brary in /usr/local. If you don't have root access, you can install in your account. For example, if your home directory is /export/home/jdoe, enter the following:
/export/home/jdoe/smartlib—for the whole path or simply:
smartlib
Library Installation OptionsThis menu choice presents different options, depending on whether your current sys-tem is supported by SmartLibrary. If the system is supported, you have the option of installing from precompiled binaries or from source. If the system is not supported, you can install SmartLibrary only from source. You can also select none to not install SmartLibrary. This option can be used with the Install Tcl option when you wish to install the Tcl files without installing the library.In most cases, it is best to use the tested precompiled versions for a quicker install. If you elect not to install the precompiled version, the source files are installed, then compiled in your environment during the installation process. The precompiled ver-sions are not available if the system is not supported by the library. In this case, your only option to install SmartLibrary is to select the compiled version.When installing with Linux, libc.so and libn.so may be renamed with the result that our installation script cannot find them. To correct this problem, create a symbolic link (a small pointer file) in the directory where you would like libc.so.n and libn.so.n to reside. An example is shown below.
ln -s libc.so libc.so.5ln -s libn.so libn.so.5
TCL Installation OptionsThis selects the version of Tcl to install:• Tcl 8.3• Tcl 8.4• None
If you install SmartLibrary but choose not to install Tcl, and Tcl is detected on the sys-tem, TclStruct 1.3 and Tcl Extension will be installed for that version of Tcl. If Tcl is not detected on the system, TclStruct 1.3 and Tcl Extension will not be installed.
• Tclstruc.dll and libtclStruct.so have been modified to work with the Tcl 8.3 and SmartLibrary. There are no apparent differences in behavior, but it is important to use the supplied modified file when using SmartLibrary with newer versions of Tcl.
Chapter 8: Programming in UNIXDirectory Structure and Content
130 | SmartLibrary Overview and Procedures
5 After the installation is complete, the bin and lib directories in the install directory should be added to the PATH and LD_LIBRARY_PATH environment variables, respectively, using the setenv or set command. The bin directory contains the Tcl pro-gram. The lib directory contains the binaries for SmartLibrary, TclStruct, Tcl Exten-sion and Tcl.
Directory Structure and ContentThe UNIX directory contains several subdirectories with the SmartLibrary files for UNIX systems, as listed below. It also contains the smartlib.dft file, which holds default values for data structures. See Chapter 3, “Default Configuration Values” for further information.The following are all possible directories that can be created when installing SmartLibrary under UNIX. In practice, a subset of these will be loaded on your computer, depending on your selections during installation. This directory structure can be expanded. The list describes the top-level directories./ProgLib
/includeContains C header files and Tcl files used when coding with SmartLibrary./libContains the library and Tcl (if applicable) and *.so files.
/SamplesContains SmartLibrary sample scripts in C and Tcl.
/manContains the Tcl man program.
/binContains the Tcl program.
Chapter 8: Programming in UNIXDeveloping with C/C++
SmartLibrary Overview and Procedures | 131
Developing with C/C++For information and file descriptions specific to the SmartLibrary C/C++ interface, see “Developing with C/C++” on page 114. Also refer to the C/C++ samples in Chapter 9, “Code Samples.”The following is an example of how to compile a C/C++ program in UNIX:
gcc -I{include dir} -L{directory of *.so files} -letsmb {source files}
Developing with Tcl
Basic Programming InformationFor file descriptions specific to the Tcl interface, see “Developing with Tcl” on page 111.
Step-by-step InformationFor an in-depth discussion of using SmartLibrary with Tcl, see Chapter 10, “Using Tcl and SmartLibrary.”
Code SamplesFor Tcl examples, see the files under Samples\Tcl\ on the CD or on your installation drive. Also see the additional samples available on the Spirent website.
132 | SmartLibrary Overview and Procedures
SmartLibrary Overview and Procedures | 133
Chapter 9
Code Samples
SmartLibrary provides extensive source code examples in C++, Tcl, and Visual Basic, to guide you through the basic tasks in working with SmartLibrary.
• The Tcl demo scripts contain well-commented code that is used both in training and in the field.
• The C examples walk you through a series of basic tasks while configuring different cards for Traditional and SmartMetrics traffic.
• Visual Basic (VB) examples show basic test procedures when using Microsoft Visual Basic.
We recommend that you look at the Tcl examples regardless of your actual programming environment.
In this chapter...
• Tcl Code Samples . . . . 134
• C/C++ Code Samples . . . . 157
• Visual Basic (VB) Code Samples . . . . 159
Chapter 9: Code SamplesTcl Code Samples
134 | SmartLibrary Overview and Procedures
Tcl Code Samples
Cross-reference to Functions and Tcl Code SamplesEach coding example illustrates the use of one or more Original Functions or Message Functions. To help you find instances of function use in the Tcl examples, the tables that follow list each coding example, describe its purpose, and also cite the functions that it demonstrates.
Note: Many Tcl coding examples include the same commonly used functions—for example, to link the PC to the SmartBits, group cards for testing, and start and stop tests. These common functions are included in each instance, but most coding examples also illustrate functions that are unique to the sample script.
Where to Find the Code ExamplesThe SmartLibrary examples are located in the following directories.
Tcl Demo ScriptsThe Tcl demo scripts cover key tasks in SmartLibrary. They have been created, refined, and used by our Technical Support Specialists and offer practical answers to questions received from customers. The scripts are heavily commented and contain information useful to SmartLibrary programmers working in any environment.The tables below summarize the scripts available for the different card families. For step-by-step instructions on working with the Tcl scripts, see Chapter 10, “Using Tcl and SmartLibrary” in this manual.
Note: SmartLibrary 3.07 and later contains Tcl examples for both the older Tcl interface (et1000.tcl) and the new improved Tcl interface (smartlib.tcl). If you do not find an example in the smartlib_tcl directory, you can check in the et1000_tcl directory and then make basic modifications needed for the new Tcl interface.
Look for sample scriptsin these directories of yourinstallation.
Chapter 9: Code SamplesTcl Code Samples
SmartLibrary Overview and Procedures | 135
Examples in the et1000_tcl Directory
et1000_tcl/AllCardsThese scripts show basic, preliminary tasks executed by SmartLibrary. They are used with the older Tcl interface, et1000.tcl.
Table 9-1. Example Scripts in the et1000_tcl/AllCards Directory
File Name Description Demonstrates
1stBasic.tcl Sets up Traditional mode traffic packets on Ethernet cards and display counters.
HTResetPortHTFillPatternHTDataLengthHTTransmitModeHTBurstCountHTGapAndScaleHGAddtoGroupHGClearPortHTRunHGGetCounters
1stlink.tcl Demonstrates the steps required to connect to a SmartBits chassis using COM ports.
ETLinkETUnLink
backoff.tcl Sets the backoff time (how quickly an Ethernet card attempts to transmit after a collision).
HGClearGroupHGAddtoGroupHGResetPortHGCollisionBackoff AggressivenessHGStart/HGStop
cardmod.tcl Probes a SmartBits stack and displays:• Card number defined in et1000.tcl.• Card model associated with the card
number.Changes port mapping mode from compatible mode to native mode.
NSSetPortMappingModeNSGetNumSlotsHTGetCardModel
gap.tcl Sends a burst of 500 packets starting with a gap of 30 uS. keeps a running count of packets transmitted and received.
HTResetPortHTSet SpeedHTDuplexModeHTTransmitModeHTDataLengthHTBurstCountHTGapHTGetCounters
Chapter 9: Code SamplesTcl Code Samples
136 | SmartLibrary Overview and Procedures
gappercent.tcl Calculates the % utilization and sets the Tx parameters at that rate. (This sample code does not work with ATM and WAN cards.)
HTDataLengthHTSetSpeedHTGapHTClearPortHTGetCounters
group.tcl Sets a group of cards. Clears group settings. Adds the cards to the group. Resets the cards in the group to the defaults. Transmits some data.
HGClearGroupHGAddtoGroupHGResetPortHGStart
groupcount.tcl Tests card membership. An array of counter structures is created to:• Hold the group counter data,• Draw a simple report, and• Fill in the counter data.
NSGetNumSlotsHGAddtoGroupHGResetPortHGIsHubSlotPortInGroupHGClearPortHGGetCounters
libver.tcl Demonstrates how functions that expect a stream are run in Tcl and displays the library version.
ETGetLibVersion
multilink.tcl Links to multiple chassis. User has the choice to select an Ethernet link or a serial-port link. Links to multiple chassis the total number of links. Transmits packets to the multiple chassis.
ETSocketLinkETLinkETGetTotalLinksETUnLink
trigger.tcl Sets a group of two cards. Tests the card membership. Sets up a VFD and a trigger to match. An array of counter structures is created to hold the group counter data.
HGSetGroupHGAddtoGroupHGVFD
vfd.tcl Demonstrates use of VFDs by setting VFD1, VFD2, and VFD3.
HTBurstCountHTDataLengthHTFillPatternHTVFD
Table 9-1. Example Scripts in the et1000_tcl/AllCards Directory (continued)
File Name Description Demonstrates
Chapter 9: Code SamplesTcl Code Samples
SmartLibrary Overview and Procedures | 137
et1000_tcl/ATMCardThese scripts work with the ATM SmartCards.
Table 9-2. Example Scripts in the et1000_tcl/ATMCard Directory
File Name Description Demonstrates
atm_ilmi.TCL Allows an ATM Card to register its 20-byte address with the network device (ATM switch) to which it is connected. After successful registration, it displays the ILMI Status information.
HTSetStructure withATM_ILMI
HTSetCommand with:ATM_ILMI_REGISTERATM_ILMI_DEREGISTER
HTGetStructure with:ATM_ILMI_INFO
atm_saal.tcl Establishes management connections with an ATM switch.
HTSetCommand with:ATM_SAAL_ESTABLISH
HTGetStructure with:ATM_SAAL_INFO
atm_setcount.tcl A back-to-back test, it ensures that the number of frames received equals the number of frames transmitted.
HTGetStructure with:ATM_CARD_CAPABILITYATM_STREAM_DETAILATM_VCC_INFO
HTSetStructure with:ATM_STREAM_CONTROLATM_STREAM
atm_status.tcl Uses HTGetEnhancedStatus to check the status and LED state of an ATM card.
HTGetEnhancedStatus
atm_trig.tcl Uses atm_setcount.tcl as a base, but adds triggers and uses a different mechanism to retrieve individual VCC frame counts.
HTGetStructure with:ATM_CARD_CAPABILITYATM_STREAM_DETAIL_INFOATM_VCC_INFOATM_CONN_TRIGGER_INFO
HTSetStructure withATM_STREAM_CONTROLATM_FRAMEATM_GLOBAL_TRIGGER_PARAMSATM_CONN_TRIGGER_PARAMS
Chapter 9: Code SamplesTcl Code Samples
138 | SmartLibrary Overview and Procedures
atmclip.tcl Shows Classical PVC to PVC connections between two cards; creates two PVC streams. This demo requires connection to a device with a CLIP server if you use the CLIP server commands.
HTGetStructure with:ATM_CARD_CAPABILITY
HTSetStructure with:ATM_STREAMATM_FRAME_DEFATM_STREAM_CONTROL
atmdata.tcl Retrieves and displays the settings and capabilities of an ATM card. (Updated to show ATM-2 card and extended capabilities.)
HTGetStructure with:ATM_CARD_TYPEATM_CARD_INFOATM_CARD_CAPABILITY
atmgetcounts.tcl Simple PVC-to-PVC connection between two cards. Shows use of enhanced stream indexes by using the newer ATM_STREAM_VCC_INFO command to get per-stream data, without needing to get the connection index first.
HTGetStructure with:ATM_CARD_CAPABILITYATM_LAYER_INFOATM_AAL5_INFOATM_STREAM_VCC_INFO
HTSetStructure with:ATM_STREAM_CONTROLATM-STREAMATM_FRAME_DEF
atmsonetinfo.tcl Retrieves and displays SONET Section/Line/Path error information.
HTGetStructure with:ATM_SONET_INFO
pppdemo.tcl Tests PPP frames encapsulated over ATM using LLC Encapsulation per RFC-1483, Multiprotocol Encapsulation over ATM AAL-5, or the VC-based multiplexing techinique per RFC-2364, PPP over AAL-5.
HTGetStructure with:ATM_CARD_CAPABILITYATM_STREAM_DETAIL_INFOPPP_STATUS_INFOATM_STREAM_VCC_INFO
HTSetStructure with:ATM_STREAM_CONTROLATM_LINEATM_STREAMATM_STREAM_PARAMS_COPYATM_STREAM_PARAMS_FILLATM_FRAME_DEFPPP_CONFIGPPP_PARAMS_COPYPPP_SET_CTRL
Table 9-2. Example Scripts in the et1000_tcl/ATMCard Directory (continued)
File Name Description Demonstrates
Chapter 9: Code SamplesTcl Code Samples
SmartLibrary Overview and Procedures | 139
et1000_tcl/et1000These scripts deal with ET-1000 capabilities. The ET-1000 is a precursor to the SmartBits 1000 with two ports and SmartCards that are not removable.
The ET-1000 examples include code for an ET-1000 as well as for ST-64XX cards emulating an ET-1000. This functionality can be useful when, for example, you haveST-6410 SmartCards and want to capture test frames.
The ET functions listed below are documented in the SmartLibrary Command Reference. See Original Functions for the ET-1000 Only.
Table 9-3. Example Scripts in the et1000_tcl/et1000 Directory
File Name Description Demonstrates
etvfd_cycle.tcl Sets up VFD data and transmits data. ETDataLengthETDataPatternETVFDParamsETSetSelETVFDRunETBurstETRun
multi.tcl General overview of ET-1000 capabilities. Sets up a 14-byte VFD; sets up a 12-byte matching trigger. Sets counter structure with multi-function counter seton Port B to count received triggers, then transmits TX_NUM packets one at a time.
ETDataLengthETDataPatternETSetSelETReceiveTriggerETMFCounterETCaptureParamsETVFDRunETVFDParamsETBurstETCaptureRunETGetCapturePacketETGetCounters
Chapter 9: Code SamplesTcl Code Samples
140 | SmartLibrary Overview and Procedures
et1000_tcl/ETHThese scripts work 10Mbps or 10/100Mbps Ethernet cards and 10/100Mbps Layer 3 cards. For completeness, the properties for all cards are presented; however, running against non-Ethernet cards will return an error code from the function.
et1000_tcl/FastCardThese scripts work with the SX-7210 and SX-7410 Fast Ethernet SmartCards, which support 10/100Mbps traffic. The cards do not support histograms and VTEs (there is no signature field).
Table 9-4. Example Scripts in the et1000_tcl/ETH Directory
File Name Description Demonstrates
ethcardinfo.tcl Demonstrates use of the ETH_CARD_INFO message function. Allows use of legacy Ethernet card functions with HTGetStructure Message Function.
HTGetStructure with:ETH_CARD_INFO
ethtransmit.tcl Demonstrates how to set up test frames, then transmit.
HTSetStructure with:ETH_TRANSMIT
Table 9-5. Example Scripts in the et1000_tcl/FastCard Directory
File Name Description Demonstrates
capture.tcl Illustrates capture and Alternate Stream setup on SX-7210 and SX-7410 SmartCards.
HTSetStructure withFST_ALTERNATE_TXFST_CAPTURE_PARAMS
HTGetStructure withFST_CAPTURE_COUNT_INFOFST_CAPTURE_DATA_INFO
collision.tcl Demonstrates how to set up collision generation on SX-74xx and SX-72xx SmartCards.
HTCollisionHGGetCounters
enhancedstats.tcl Uses HTGetCardModel to ensure a FastCard is selected then does a bitwise AND to see if the FAST7410_STATUS_LINK (0x0000200h) is set.
HTGetCardModelHTGetEnhancedStatus
Chapter 9: Code SamplesTcl Code Samples
SmartLibrary Overview and Procedures | 141
et1000_tcl/GIGThese scripts work with the Gigabit Ethernet SmartCards and modules, including the GX-1405B/BS, and LAN-3200A/AS.
fasttrig&vfd.tcl Shows how to set up VFDs and trigger on a particular pattern. Gets the counter data and displays it.
HGTriggerHTVFDHGGetCounters
mii.tcl Demonstrates the use of the HTReadMII and HTWriteMII commands to enable auto negotiation, display the contents of the MII registers and force auto negotiation.
HTFindMIIAddressHTReadMIIHTWriteMII
setspeed.tcl Sets speed on duplex. HGClearGroupHGAddtoGroup HGResetPort HGSetSpeed HGDuplexMode HGTransmitMode HGDataLength HGStartHGStopHClearGroup
Table 9-5. Example Scripts in the et1000_tcl/FastCard Directory (continued)
File Name Description Demonstrates
Table 9-6. Example Scripts in the et1000_tcl/GIG Directory
File Name Description Demonstrates
gigcount.tcl Sets a group of Gigabit cards; creates an array of counter structures to hold the group counter data; then draws a simple report and fill in the counter data.
HTSetStructure withGIG_STRUC_TX
HGGetCounters
gigvfd.tcl Basic start, transmit, capture, and display for Gigabit Ethernet cards.
HTSetStructure withGIG_STRUC_TXGIG_STRUC_FILL_PATTERNGIG_STRUC_VFD3GIG_STRUC_CAPTURE_SETUP
HTGetStructure with GIG_STRUC_CAP_DATA_INFO
Chapter 9: Code SamplesTcl Code Samples
142 | SmartLibrary Overview and Procedures
et1000_tcl/Layer3These scripts illustrate how to create streams with SmartMetrics SmartCards such as the ML-7710, and LAN-3101A/B.
Table 9-7. Example Scripts in the et1000_tcl/Layer3 Directory
File Name Description Demonstrates
l2-l3.tcl Demonstrates the process of switching from L2 to L3 on an ML-7710 card.
HTGetStructure withNS_CAPTURE_DATA_INFO
HTSetCommand withNS_CAPTURE_STARTNS_CAPTURE_STOP
HTSetStructure withL3_DEFINE_IP_STREAMNS_CAPTURE_SETUP
l3_hist_raw_tags.tcl Creates IP streams. HTSetStructure withL3_DEFINE_IP_STREAML3_DEFINE_MULTI_IP_STREAM
HTGetStructure withL3_DEFINED_STREAM_COUNT_INFOL3_HIST_RAW_TAGS_INFO
HTSetCommand withL3_HIST_RAW_TAGS
l3_hist_v2_lat_per_strm.tcl Displays latency and sequence information.
HTSetStructure withL3_DEFINE_IP_STREAML3_DEFINE_MULTI_IP_STREAM
HTGetStructure withL3_DEFINED_STREAM_COUNT_INFO
HTSetCommand withL3_HIST_V2_LATENCY_PER_STREAM
L3_HIST_START
l3_sb.tcl Sets the SmartBits stream, transmits packets in SINGLE_BURST_MODE. Fills in background data.
HTSetStructure withL3_DEFINE_SMARTBITS_STREAMNS_CAPTURE_SETUP
HTSetCommand withNS_CAPTURE_STARTNS_CAPTURE_STOP
HTGetStructure withNS_CAPTURE_COUNT_INFONS_CAPTURE_DATA_INFO
Chapter 9: Code SamplesTcl Code Samples
SmartLibrary Overview and Procedures | 143
l3_stream_info.tcl Sets up one IP stream on an ML-7710 Multilayer card, then reads back and displays the card data.
HTSetStructure withL3_DEFINE_IP_STREAM
HTGetStructure withL3_DEFINED_STREAM_COUNT_INFOL3_STREAM_INFO
l3_v2_hist_lat.tcl Sets up a series of streams (externally by sourcing ipstream.tcl). Transmits a burst of packets. Displays the distribution.
HTSetStructure withL3_DEFINE_IP_STREAML3_DEFINE_MULTI_IP_STREAM
HTSetCommand withL3_HIST_V2_LATENCY
HTGetStructure withL3_DEFINED_STREAM_COUNT_INFOL3_HIST_V2_LATENCY_INFO
l3basic.tcl Creates 10 IP streams (frame blueprints); sends out a single burst of 20 IP frames; then displays the packets captured on the receiver.
HTSetStructure withL3_DEFINE_IP_STREAMNS_CAPTURE_SETUP
HTSetCommand withNS_CAPTURE_STARTNS_CAPTURE_STOP
HTGetStructure withNS_CAPTURE_COUNT_INFONS_CAPTURE_DATA_INFO
l3clearstreams.tcl Displays the number of streams on target Multilayer card.
HTGetStructure withL3_DEFINED_STREAM_COUNT_INFO
HTSetStructure withL3_DEFINE_IP_STREAML3_DEFINE_SMARTBITS_STREAM
l3min.tcl Transmits for three seconds; displays the number of frames specified by NUM_VIEW_CAP_FRAMES; displays "DISPLAY_LINES" per screen.
HTSetStructure withL3_DEFINE_IP_STREAML3_DEFINE_MULTI_IP_STREAMNS_CAPTURE_SETUP
HTSetCommand withNS_CAPTURE_STARTNS_CAPTURE_STOP
HTGetStructure withNS_CAPTURE_COUNT_INFONS_CAPTURE_DATA_INFO
Table 9-7. Example Scripts in the et1000_tcl/Layer3 Directory (continued)
File Name Description Demonstrates
Chapter 9: Code SamplesTcl Code Samples
144 | SmartLibrary Overview and Procedures
l3_mod_stream_array.tcl Sets up IP streams on a Multilayer card; then modifies the length field; demonstrates the effect of the various options on the output.
HTSetStructure withL3_DEFINE_IP_STREAML3_DEFINE_MULTI_IP_STREAML3_MOD_STREAMS_ARRAY
l3pngcount.tcl Sets up the Layer 3 stack on the ML-7710 card.
HTSetStructure withL3_DEFINE_IP_STREAML3_DEFINE_MULTI_IP_STREAM
HTLayer3SetAddressHTGetEnhancedCounters
l3stack.tcl Sets the Layer 3 information for the card in first slot only.
HTLayer3GetAddress
l3trigger.tcl Demonstrates the use of triggers on Multilayer cards.
HGTrigger
HTSetStructure withL3_DEFINE_IP_STREAML3_DEFINE_MULTI_IP_STREAMNS_CAPTURE_SETUP
HTSetCommand withNS_CAPTURE_STARTNS_CAPTURE_STOP
HTGetStructure withNS_CAPTURE_COUNT_INFONS_CAPTURE_DATA_INFO
Table 9-7. Example Scripts in the et1000_tcl/Layer3 Directory (continued)
File Name Description Demonstrates
Chapter 9: Code SamplesTcl Code Samples
SmartLibrary Overview and Procedures | 145
et1000_tcl/POSThis script illustrates how to work with the Packet Over SONET (POS) modules(POS-3500B/BS).
et1000_tcl/SMB6000This script works with SmartBits 600x/6000x and 200/2000 systems.
Examples in the libx directoryThe LibX Utilities are a family of Tcl procedures, created with SmartLibrary, that simplify setting up and operating cards and chassis. Developed for technical support, they provide a quick, command line-based method to set up cards, display essential configuration parameters, and run test programs.See Chapter 11, “LibX: Simplified Library Control,” for complete information, as well as the ReadMe.pdf file in the LibX directory.The LibX directory contains the following files:
Table 9-8. Example Scripts in the et1000_tcl/POS Directory
File Name Description Demonstrates
L3Extension.tcl Uses two POS−3500B/BS modules connected back-to-back in a SmartBits.
HGSetGroupHGAddtoGroupHGClearPortHGGetCounters
HTSetStructure withPOS_CARD_LINE_CONFIGPOS_CARD_PORT_ENCAPL3_DEFINE_IP_STREAML3_DEFINE_STREAM_EXTENSION
Table 9-9. Example Scripts in the et1000_tcl/SMB6000 Directory
File Name Description Demonstrates
controller.tcl Illustrates differences between the SmartBits 200/2000 and SmartBits 600x/6000x chassis types, along with the two port-mapping modes: Compatible and Native.
ETSocketLinkETGetProductFamilyETGetControllerNSSetPortMappingModeETUnLink
Chapter 9: Code SamplesTcl Code Samples
146 | SmartLibrary Overview and Procedures
Table 9-10. Example Scripts in the libx Directory
File Name Description
loadx.tcl A Tcl script that loads the LibX components.
libx.tcl Core LibX commands and definitions.
slibx.tcl
l3x.tcl Layer 3/SmartMetrics stream commands.
sl3x.tcl
unloadx.tcl A Tcl script that unloads the LibX components.
Chapter 9: Code SamplesTcl Code Samples
SmartLibrary Overview and Procedures | 147
Examples in the smartlib_tcl DirectoryThese examples make use of the improved Tcl interface provided by the smartlib.tcl interface file. Many of them mirror the functionality of the samples in /Samples/et1000_tcl/, with the exception that they use the default values file. For this reason, some configuration settings may be different.
smartlib_tcl/ATMThese scripts work with the ATM SmartCards.
Table 9-11. Example Scripts in the smartlib_tcl/ATM Directory
File Name Description Demonstrates
atmbasic.tcl Sets up two streams each on two cards, then starts, stops the streams on card 1. Displays Tx Rx counts on both cards.
HTSetStructure withATM_LINEATM_STREAM_CONTROLATM_STREAMATM_FRAME_COPY
HTGetStructure withATM_CARD_CAPABILITY
atmcount.tcl Establishes a PVC-to-PVC connection between two cards. Demonstrates the various per-port and per-stream ATM counters.
HTGetStructure withATM_CARD_CAPABILITYATM_LAYER_INFOATM_AAL5_INFOATM_STREAM_EXT_VCC_INFO
HTSetStructure withATM_STREAM_CONTROLATM_STREAMATM_FRAME_DEF
atmppp.tcl Sets up multiple PPP sessions on two cards, then starts/stops the streams as a group. Displays Tx and Rx counts on both cards.
HTSetStructure withATM_LINEATM_STREAM_CONTROLPPP_CONFIGPPP_PARAMS_COPYATM_STREAMATM_FRAME_DEFATM_PER_STREAM_BURST
HTGetStructure withATM_CARD_CAPABILITY
Chapter 9: Code SamplesTcl Code Samples
148 | SmartLibrary Overview and Procedures
smartlib_tcl/ATMTMThese scripts work with the ATM TeraMetrics modules: ATM-3451A/As and ATM-3453A/As.
atmtrigger.tcl Demonstrates the use of triggers on ATM cards.
HTGetStructure withATM_CARD_CAPABILITYATM_STREAM_EXT_VCC_INFOATM_STREAM_TRIGGER_TIME_INFO
HTSetStructure withATM_STREAM_CONTROLATM_STREAMATM_FRAME_DEFATM_STREAM_TRIGGER_PARAMS
Table 9-11. Example Scripts in the smartlib_tcl/ATM Directory (continued)
File Name Description Demonstrates
Table 9-12. Example Scripts in the smartlib_tcl/ATMTM Directory
File Name Description Demonstrates
ATMTMBasic.tcl Demonstrates the use of the ATM Terametrics cards by creating four VCs, 12 IP streams. Each VC is bound to three IP streams and sends one single burst of three streams. The package are captured and displayed on the receiver.
Original Functions with: HTGetCounters
HTGetStructure withAT_PORT_COUNTER_INFOAT_VC_COUNTER_INFONS_CAPTURE_COUNT_INFONS_CAPTURE_DATA_INFO
HTSetCommand withNS_COMMIT_CONFIGNS_CAPTURE_STARTNS_CAPTURE_STOP
HTSetStructure withAT_PORT_CONFIGAT_VC_CREATE L3_DEFINE_IP_STREAML3_DEFINE_MULTI_IP_STREAML3_DEFINE_STREAM_EXTENSIONL3_DEFINE_MULTI_STREAM_EXTENSIONL3_DEFINE_STREAM_BINDINGNS_CAPTURE_SETUP
Chapter 9: Code SamplesTcl Code Samples
SmartLibrary Overview and Procedures | 149
ATMTMCounters.tcl Demonstrates the use of the most of the fields of the ATM counter messages for the ATM Terametrics card.
HTGetStructure withAT_PORT_COUNTER_INFOAT_VC_COUNTER_INFOAT_STREAM_TX_COUNTER_INFOAT_VC_INFO
HTSetCommand withNS_COMMIT_CONFIGAT_VC_DELETE_ALL
HTSetStructure withAT_PORT_CONFIGAT_VC_CREATE AT_VC_MODIFYL3_DEFINE_IP_STREAML3_DEFINE_STREAM_EXTENSIONL3_MOD_STREAM_EXTENSIONL3_DEFINE_STREAM_BINDING
ATMTMAvgLat.tcl This sample script creates four VCs, 12 IP streams with OC3 speed port. Each VC is bound with three IP streams, and sends a single burst of 300 IP frames. It then uses histogram to obtain latency statistics for each stream.
HTGetStructure withL3_HIST_ACTIVE_TEST_INFONS_HIST_COMBO_PER_STREAM_INFO
HTSetCommand withNS_COMMIT_CONFIGNS_HIST_COMBO_PER_STREAMNS_HIST_STARTNS_HIST_LATENCY_OPTIONAT_VC_DELETE_ALL
HTSetStructure withAT_PORT_CONFIGAT_VC_CREATE L3_DEFINE_IP_STREAML3_DEFINE_STREAM_EXTENSIONL3_DEFINE_STREAM_BINDING
Table 9-12. Example Scripts in the smartlib_tcl/ATMTM Directory (continued)
File Name Description Demonstrates
Chapter 9: Code SamplesTcl Code Samples
150 | SmartLibrary Overview and Procedures
smartlib_tcl/GIGThese scripts are the same as those the same-named scripts in the /et1000_tcl/ directory. See “Examples in the et1000_tcl Directory” on page 135.
ATMTM_ns_hist_combo_per_stream.tcl
This sample script creates one VC and 10 IP streams, with OC3 speed port. The VC is bound with the 10 IP streams and sends a single burst of 10000 IP frames. It then uses histogram to displays latency and sequence information
HTGetStructure withL3_DEFINED_STREAM_COUNT_INFONS_HIST_ACTIVE_TEST_INFONS_HIST_COMBO_PER_STREAM_INFO
HTSetCommand withNS_COMMIT_CONFIGNS_HIST_COMBO_PER_STREAMNS_HIST_START
HTSetStructure withAT_PORT_CONFIGAT_VC_CREATE L3_DEFINE_IP_STREAML3_DEFINE_MULTI_IP_STREAML3_DEFINE_STREAM_EXTENSIONL3_DEFINE_MULTI_STREAM_EXTENSIONL3_DEFINE_STREAM_BINDINGL3_DEFINE_MULTI_STREAM_BINDING
Table 9-12. Example Scripts in the smartlib_tcl/ATMTM Directory (continued)
File Name Description Demonstrates
Table 9-13. Example Scripts in the smartlib_tcl/GIG Directory
File Name Description Demonstrates
gigcount.tcl Sets a group of Gigabit ports; creates an array of counter structures to hold the group counter data; draws a simple report and fills in the counter data.
HTSetStructure withGIG_STRUC_TX
HGGetCounters
gigvfd.tcl Basic start, transmit, capture, and display for Gigabit Ethernet cards.
HTSetStructure withGIG_STRUC_TXGIG_STRUC_FILL_PATTERNGIG_STRUC_VFD3GIG_STRUC_CAPTURE_SETUP
HTGetStructure withGIG_STRUC_CAP_COUNT_INFO
Chapter 9: Code SamplesTcl Code Samples
SmartLibrary Overview and Procedures | 151
smartlib_tcl/Layer3These scripts illustrate how to create streams with SmartMetrics SmartCards such as the L3-6710, ML-7710, and LAN-3101A/B.
Table 9-14. Example Scripts in the smartlib_tcl/Layer3 Directory
File Name Description Demonstrates
l2-l3.tcl Demonstrates the process of switching from Layer 2 to Layer 3 on an ML-7710 card.
HTGetStructure withNS_CAPTURE_DATA_INFO
HTSetCommand withNS_CAPTURE_STARTNS_CAPTURE_STOP
HTSetStructure withL3_DEFINE_IP_STREAMNS_CAPTURE_SETUP
l3_gw_mod_stream_array.tcl Sets up IP streams on a Layer 3 card, then modifies the 3rd gateway octet.
HTGetStructure withL3_DEFINED_STREAM_COUNT_INFOL3_STREAM_INFO
HTSetStructure withL3_DEFINE_IP_STREAML3_DEFINE_MULTI_IP_STREAML3_MOD_STREAMS_ARRAY
l3_hist_raw_tags.tcl Sets up a series of streams (externally by sourcing ipstream.tcl), then transmits a burst of packets and displays the distribution.
HTSetStructure withL3_DEFINE_IP_STREAML3_DEFINE_MULTI_IP_STREAM
HTGetStructure withL3_DEFINED_STREAM_COUNT_INFOL3_HIST_RAW_TAGS_INFO
HTSetCommand withL3_HIST_RAW_TAGS
l3_hist_v2_lat_per_strm.tcl Displays latency and sequence information.
HTSetStructure withL3_DEFINE_IP_STREAML3_DEFINE_MULTI_IP_ STREAM
HTGetStructure withL3_DEFINED_STREAM_COUNT_INFOL3_HIST_V2_LATENCY_PER_STREAM_INFO
HTSetCommand withL3_HIST_V2_LATENCY_PER_STREAML3_HIST_START
Chapter 9: Code SamplesTcl Code Samples
152 | SmartLibrary Overview and Procedures
File Name Description Demonstrates
l3_sb.tcl Transmits for three seconds, then displays the number of frames specified by NUM_VIEW_CAP_FRAME, and DISPLAY_LINES per screen.
HTSetStructure withL3_DEFINE_SMARTBITS_STREAMNS_CAPTURE_SETUP
HTSetCommand withNS_CAPTURE_STARTNS_CAPTURE_STOP
HTGetStructure withNS_CAPTURE_COUNT_INFONS_CAPTURE_DATA_INFO
l3_stream_info.tcl Sets up one IP stream on a Layer 3 card, then reads back and displays the card data on an ML-7710.
HTSetStructure withL3_DEFINE_IP_STREAM
HTGetStructure withL3_DEFINED_STREAM_COUNT_INFOL3_STREAM_INFO
l3_tcp.tcl Sets up a single stream on each of two cards.
HTSetCommand withNS_CAPTURE_STARTNS_CAPTURE_STOPL3_START_ARPS
HTGetStructure withNS_CAPTURE_COUNT_INFONS_CAPTURE_DATA_INFO
HTSetStructure withL3_DEFINE_TCP_STREAMNS_CAPTURE_SETUP
l3_v2_hist_lat.tcl Sets up a series of streams (externally by sourcing ipstream.tcl), then transmits a burst of packets and displays the distribution.
HTSetStructure withL3_DEFINE_IP_STREAML3_DEFINE_MULTI_IP_STREAM
HTGetStructure withL3_DEFINED_STREAM_COUNT_INFOL3_HIST_V2_LATENCY_INFO
HTSetCommand withL3_HIST_V2_LATENCY
Table 9-14. Example Scripts in the smartlib_tcl/Layer3 Directory (continued)
Chapter 9: Code SamplesTcl Code Samples
SmartLibrary Overview and Procedures | 153
File Name Description Demonstrates
l3Basic.tcl Creates 10 IP streams (frame blueprints) and sends out a single burst of 20 IP frames. Displays the packets captured on the receiver.
HTSetStructure withL3_DEFINE_IP_STREAML3_DEFINE_MULTI_IP_STREAMNS_CAPTURE_SETUP
HTSetCommand withNS_CAPTURE_STARTNS_CAPTURE_STOP
HTGetStructure withNS_CAPTURE_COUNT_INFONS_CAPTURE_DATA_INFO
l3min.tcl Basic streams setup, transmit, and capture.
HTSetStructure withL3_DEFINE_IP_STREAML3_DEFINE_MULTI_IP_STREAMNS_CAPTURE_SETUP
HTSetCommand withL3_START_ARPSNS_CAPTURE_STARTNS_CAPTURE_STOP
HTGetStructure withNS_CAPTURE_COUNT_INFONS_CAPTURE_DATA_INFO
mod_stream_array.tcl Sets up IP streams on a Layer 3 card, then modifies the length field. Demonstrates the effect of the various options on the output.
HTSetStructure withL3_DEFINE_IP_STREAML3_DEFINE_MULTI_IP_STREAML3_MOD_STREAMS_ARRAY
l3pingcount.tcl Sets up the Layer 3 stack on the ML-7710 card.
HTLayer3SetAddressHTGetEnhancedCounters
l3stack.tcl Sets the Layer 3 information for the card in first slot only.
HTLayer3SetAddress
Table 9-14. Example Scripts in the smartlib_tcl/Layer3 Directory (continued)
Chapter 9: Code SamplesTcl Code Samples
154 | SmartLibrary Overview and Procedures
smartlib_tcl/POSThese scripts illustrate how to work with selected Packet Over SONET (POS) modules, the POS-3500B and POS-3500BS.
File Name Description Demonstrates
l3trigger.tcl Demonstrates the use of triggers on Layer 3 cards.
HTGetStructure withNS_CAPTURE_COUNT_INFONS_CAPTURE_DATA_INFO
HTSetStructure withL3_DEFINE_IP_STREAML3_DEFINE_MULTI_IP_STREAMNS_CAPTURE_SETUP
HTSetCommand withNS_CAPTURE_STARTNS_CAPTURE_STOPL3_CAPTURE_TRIGGERS_TYPE
l3zero.tcl Shows number of streams on target Layer 3 card and prompts user if the streams should be removed.
HTGetStructure withL3_DEFINED_STREAM_COUNT_INFOL3_DEFINED_STREAM_COUNT_INFO
HTSetStructure withL3_DEFINE_SMARTBITS_STREAM
Table 9-14. Example Scripts in the smartlib_tcl/Layer3 Directory (continued)
Table 9-15. Example Scripts in the smartlib_tcl/POS Directory
File Name Description Demonstrates
l3extension.tcl Tests against two POS-3500B/BS modules in a SmartBits 600x.
NSEnableAutoDefaultsHGIsHubSlotPortInGroup
HTSetStructure withPOS_CARD_LINE_CONFIGPOS_CARD_PORT_ENCAPL3_DEFINE_IP_STREAML3_DEFINE_STREAM_EXTENSION
HTDefaultStructure withL3_DEFINE_IP_STREAM
Chapter 9: Code SamplesTcl Code Samples
SmartLibrary Overview and Procedures | 155
posbasic.tcl Sets up multiple IP streams. HTSetCommand withNS_CAPTURE_STARTNS_CAPTURE_STOP
HTGetStructure withNS_CAPTURE_COUNT_INFONS_CAPTURE_DATA_INFO
HTSetStructure withPOS_CARD_LINE_CONFIGPOS_CARD_PORT_ENCAPL3_DEFINE_IP_STREAML3_DEFINE_MULTI_IP_STREAML3_DEFINE_STREAM_EXTENSIONNS_CAPTURE_SETUP
posppp.tcl Sets up PPP on POS. HTSetCommand withNS_CAPTURE_STARTNS_CAPTURE_STOP
HTGetStructure withNS_CAPTURE_COUNT_INFONS_CAPTURE_DATA_INFOPPP_STATS_INFOPPP_STATUS_INFO
HTSetStructure withPOS_CARD_LINE_CONFIGPOS_CARD_PORT_ENCAPPPP_CONFIGL3_DEFINE_IP_STREAML3_DEFINE_STREAM_EXTENSIONPPP_SET_CTRLNS_CAPTURE_SETUP
Table 9-15. Example Scripts in the smartlib_tcl/POS Directory (continued)
File Name Description Demonstrates
Chapter 9: Code SamplesTcl Code Samples
156 | SmartLibrary Overview and Procedures
smartlib_tcl/SMB6000This script works with SmartBits 600x/6000x and 200/2000 systems.
Table 9-16. Example Scripts in the smartlib_tcl/SMB6000 Directory
File Name Description Demonstrates
controller.tcl Illustrates differences between the SmartBits 200/2000 and SmartBits 600x/6000x chassis types, along with the two port-mapping modes: Compatible and Native.
NSSetPortMappingMode
Chapter 9: Code SamplesC/C++ Code Samples
SmartLibrary Overview and Procedures | 157
C/C++ Code SamplesThe Samples\C subdirectory includes demo modules for ATM, the LAN-3100A module, Layer 2, and Layer 3.
These modules are divided into steps to enable you to see the actions needed for basic testing with SmartLibrary.
ATM (Atm)The ATM C demo module illustrates a two-port test. It creates two PVCs on each port, then transmits continuous data in a bidirectional pattern. The sample code is contained in the following files:
Atm.hatm.cppMain.hMain.cppResults.cpp
LAN-3100A (Lan3100a)This demo module demonstrates how to work with the LAN-3100A module. It is based on the following steps.
Step 1 Connect to SmartBits shows how to use NSSocketLink( ) to connect to the SmartBits chassis, using the Native port mapping mode.
Note: Throughout the demo, the equivalent functions for the Compatible port mapping are shown as comments.
Step 2 Learn Target Port MAC Addresses shows how to generate ARP and PING frames and to retrieve the MAC address of the device with the target IP address. This step uses the fol-lowing two functions:
HTSetStructure(FST_PROTOCOL_PARAMETERS,0,0,0
&ProtocolParams,sizeof(ProtocolParams),
iHub,Islot,iPort)
HTGetStructure(FST_PROTOCOL_PARAMETER_INFO,0,0,0
&ProtocolParams,sizeof(ProtocolParams),
iHub,Islot,iPort)
Step 3 Select Transmit and Receive Ports shows a simple algorithm that is used to pair up the ports and verify the results of the management frames generated in Step 2, based on the table PortAddrTable PreSettingPortsTable[NumPorts] defined in the demo.h file.
Step 4 Set up Burst of IP Frames demonstrates how to use NSCreateFrame( ), NSModify-Frame( ), and HTFrame( ) to configure IP traffic on the transmit ports.
Chapter 9: Code SamplesC/C++ Code Samples
158 | SmartLibrary Overview and Procedures
Step 5 Test Layer 2 and Layer 3 Counters demonstrates the counters on the LAN-3100A. using HTGetStructure with the ETH_COUNTER_INFO and FST_PROTOCOL_COUNTER_INFO iType1s. This step uses the following two func-tions:
HTGetStructure(ETH_COUNTER_INFO,0,0,0
&l2Counters,sizeof(l2Counters),
iHub,Islot,iPort)
HTGetStructure(FST_PROTOCOL_PARAMETER_INFO,0,0,0
&l3Counters,sizeof(l3Counters),
iHub,Islot,iPort)
Step 6 Test IP Checksum demonstrates the ability of SmartLibrary to generate IP traffic with invalid IP checksums and the LAN-3100A's ability to count these packets, as well as to calculate the correct checksum when configured to do so.
Step 7 Display Capture Data shows the capture features of the LAN-3100A and backward com-patibility with the SX-7410.
Step 8 Disconnect and Clean-up is self-explanatory.
Layer 2The Layer 2 module demonstrates the basic setup of SmartBits Traditional-mode cards or SmartMetrics cards in the Traditional mode. Each step is outlined in the main function.
SmartMetricsThe SmartMetrics module demonstrates the basic setup of SmartBits SmartMetrics cards such as ML-7710, L3-6710, and ML-5710. Each functional step is outlined in the main function.
Chapter 9: Code SamplesVisual Basic (VB) Code Samples
SmartLibrary Overview and Procedures | 159
Visual Basic (VB) Code SamplesThe Visual Basic demo module is intended to show basic test procedures when using Microsoft Visual Basic.
To launch the demo:1 Go to the SmartLib\Samples\VB directory from the SmartLibrary CD.2 Double-click on the sample.exe icon.
The SmartLib Sample Suite window opens. (To view the source code, launch sample.vbp.)
Select a script to run from the Samples menu.
Provides status messages as the script runs.
Explains what the sample does.
The Setup pane identifies the selected script and shows which cards can be used with it.
Shows connection type. Use the Change Connection button to select a different connection.
Show which cards are being tested. Select cards by modifying the Hub, Slot, Port fields and selecting Change Hub Slot Port.
Control test operation.
Chapter 9: Code SamplesVisual Basic (VB) Code Samples
160 | SmartLibrary Overview and Procedures
How to Run a SampleUse the following steps to run a VB sample.1 From the Samples pull-down menu, select a sample to run.2 The Sample Description text box explains the sample, which is identified by the
Sample Name (here, Basic Test).3 The Supported Cards text box displays the cards which can be used by the selected
sample script.4 Current Connection shows the current interface between the PC and the SmartBits.
Select Change Connection to change between a serial port or Ethernet connection and to specify the IP address.
5 The Hub Slot Port Info boxes show which cards are involved in the test by their locations in the SmartBits chassis. To select different cards, modify the appropriate fields and click the Change Hub Slot Port button.
6 Select Run to start the sample.7 The Test Progress text box displays status messages as the procedure runs.
Setting Break PointsYou can view the actual SmartLibrary functions that are executed by the sample by going to the VB debug mode and setting a break point at the Run command. Doing this can show you in detail how Library functions are used in each sample.
VB Sample Scripts
Table 9-17. Sample VB Scripts
Sample Heading Sample NameCards Supported Description
All Cards All Cards All Cards This test retrieves the model and slot ownership for all cards in up to four connected chassis.
Layer2 Basic L2 Test ML-7710SX-7410GX-1405B/BSST-6405ST-6410ML-5710ALAN-3101A/B
This test sets the card parameters including data length, gap size, speed, and duplex. In addition, VFDs 1, 2, and 3 are set. Fill and trigger patterns are created. Packets are sent and the card counters are retrieved and displayed.
Chapter 9: Code SamplesVisual Basic (VB) Code Samples
SmartLibrary Overview and Procedures | 161
Sample Heading Sample NameCards Supported Description
Layer2(continued)
L2 Group Test ML-7710SX-7410LAN-3100AGX-1420B
This test demonstrates the HG (group) functions. The test first sets the card parameters including data length, gap size, speed, and duplex. In addition VFDs 1, 2, and 3 are set. Fill and trigger patterns are created. Packets are sent and the card counters are retrieved and displayed.
Layer3 L3 Capture ML-7710ML-5710A
This test defines and configures Layer 3 IP Streams. The IP Streams are sent and captured on the destination card. Captured data packets are output in Hex.
ATM General Card Info AT-9015AT-9020AT-9025AT-9029AT-9034BAT-9155CAT-9155CSAT-9622/s
This sample test retrieves and displays settings and capabilities of a single ATM card. This information includes card type, version, build, version type, firmware components, capabilities, and supported features
Basic ATM Test AT-9015AT-9034BAT-9045BAT-9155CAT-9155CsAT-9020AT-9025AT-9622/s
This module performs a back-to-back test on two ATM cards, ensuring that the number of frames transmitted equals the number of frames received. Streams are created with the AAL5 payload specified. The connections are established and the data is sent from card1 to card2. The number of frames transmitted and received are displayed for each card.
Fast Ethernet (FST) Basic FST Test SX-7410LAN-3100A
First VFD 1, 2, and 3 are created. Next, an alternate stream is created. This alternate stream is sent every fifth packet causing the trigger counter to increment by one. Packets are sent and the first 20 are displayed. Counters are also retrieved and displayed.
Table 9-17. Sample VB Scripts (continued)
Chapter 9: Code SamplesVisual Basic (VB) Code Samples
162 | SmartLibrary Overview and Procedures
Sample Heading Sample NameCards Supported Description
Gigabit Ethernet Basic Gigabit Test GX-1405B/BS This module sets up transmit parameters on card1 including VFD 1, 2, and 3. Trigger patterns are created which increment the trigger counter every 20th frame. Next, 20 bursts of 100,000 packets are sent to card2. The first 20 packets are displayed. Last the counters from both card1 and card2 are retrieved and displayed.
Packet Over SONET Basic POS Test POS-3500B/BS This test configures a group of POS cards for testing back-to-back. IP streams are defined on both Card1 and Card2. Two bursts of 10,000 packets are sent from Card1 to Card2. Counters from each card are retrieved and displayed.
Table 9-17. Sample VB Scripts (continued)
SmartLibrary Overview and Procedures | 163
Chapter 10
Using Tcl and SmartLibrary
SmartLibrary supports a number of programming languages. This chapter provides overview information on using Tcl with SmartLibrary. It describes the Tcl interface, explains how to use default values, and sets forth the steps to convert existing Tcl scripts based on earlier library versions to the run under the new Tcl interface.
For additional information, see the Tcl/SmartLibrary tutorial in Chapter 2, “SmartLibrary Basics.” That chapter also includes:
• An overview of SmartBits terminology and concepts
• Steps to using streams in testing.
For complete, in-depth information on Tcl, consult one of the books or manuals that covers the Tcl language. A good source of information is the Scriptics website at www.scriptics.com.
In this chapter...
• Using the New smartlib.tcl Interface . . . . 164
• Default Values with the Tcl Interfaces . . . . 168
• Converting Existing Scripts for the New Tcl . . . . 171
• Additional Information . . . . 172
Chapter 10: Using Tcl and SmartLibraryUsing the New smartlib.tcl Interface
164 | SmartLibrary Overview and Procedures
Using the New smartlib.tcl InterfaceSmartLibrary versions after 3.07 include a new Tcl interface that is easier to use than previous library versions, while keeping the same library commands as in previous versions. For example, the new Tcl interface supports simpler format and list commands.
Backward CompatibilityThe old Tcl interface remains available, for continued support of existing scripts. See “Converting Existing Scripts for the New Tcl” on page 171 if you wish to use old scripts with the simpler Tcl interface.
What Has Changed?The Tcl focus for SmartLibrary has been less typing, more results. If you are using our Tcl interface, you will notice Tcl-specific benefits, as well as the new default values for all Message Function commands. Improvements include:
How Do I Run the New Tcl Interface?SmartLibrary includes two Tcl interface files:
• et1000.tcl Continued support for scripts written with SmartLibrary 3.06b and before.
• smartlib.tcl For scripts written with SmartLibrary 3.07 and later.
If you are creating new Tcl SmartLibrary scripts, source smartlib.tcl to use the improved Tcl interface. If you are working with existing scripts and you don’t want to convert them to work with smartlib.tcl, et1000.tcl will continue to support the older interface with no modifications needed.
Enhancement
Available with Interface
Old New
Lists instead of arrays No Yes
No special formatting for character fields No Yes
Default values for all Message Functions Yes Yes
Informative message when the library is sourced Yes Yes
Ability to send a single structure as an element of an array Yes Yes
Chapter 10: Using Tcl and SmartLibraryUsing the New smartlib.tcl Interface
SmartLibrary Overview and Procedures | 165
Note: The two interface files et1000.tcl and smartlib.tcl are not compatible. Remember to use the correct interface file with your scripts. See “Easy Checking for the Correct Tcl Interface” on page 165 for information on how to check the interface in use.
Easy Checking for the Correct Tcl InterfaceSmartLibrary helps you ensure you are working with the correct Tcl interface in three ways:
• For the TCL sample code, SmartLibrary automatically checks for and loads the correct Tcl interface file (either et1000.tcl or smartlib.tcl).
• The library file includes a variable, NSTclFile, that shows which interface file (et1000.tcl or smartlib.tcl) has been sourced.
• You can use the loadlib command in the misc.tcl file to query which interface has been loaded or (if necessary) load the desired file.
Sample CodeThe SmartLibrary sample call automatically checks for and (if necessary) loads the correct interface for use with each of the Tcl code samples.
NSTclFile VariableAfter you source either et1000.tcl or smartlib.tcl, the NSTclFile variable will contain one of the following strings, to identify which interface file is in use:
“et1000.tcl”or“smartlib.tcl”
Using the loadlib CommandYou can use the loadlib command (in the misc.tcl file) to query which interface has been loaded and (if necessary) to load the desired file.
Enter the command in the following format:loadlib <interface_file_name>
For example:loadlib smartlib.tcl
—or—
loadlib et1000.tcl
The command returns messages to tell you whether or not the desired interface is already loaded. If it is not, it loads the interface.
Chapter 10: Using Tcl and SmartLibraryUsing the New smartlib.tcl Interface
166 | SmartLibrary Overview and Procedures
Comparative Usage ExamplesThis section covers the Tcl improvements in detail. The smartlib.tcl examples are for SmartLibrary versions 3.07 and later. The et1000.tcl examples support the older interface (versions 3.06b and earlier).
Lists Instead of Arrays (New Interface Only)You can now use the native Tcl lists to send a list of numeric values with a SmartLibrary function. This is different from the earlier interface, where each value was sent as an element of an array.
smartlib.tcl example (new list of values):set MyConfig(ucVFD1Data) {20 22 25 26 26 33 27 21}
et1000.tcl example (old array of values):set MyConfig(ucVFD1Data.0.uc) [format %c 20]set MyConfig(ucVFD1Data.1.uc) [format %c 22]set MyConfig(ucVFD1Data.2.uc) [format %c 25]set MyConfig(ucVFD1Data.3.uc) [format %c 26]set MyConfig(ucVFD1Data.4.uc) [format %c 26]set MyConfig(ucVFD1Data.5.uc) [format %c 33]set MyConfig(ucVFD1Data.6.uc) [format %c 27]set MyConfig(ucVFD1Data.7.uc) [format %c 21]
Note: Arrays are still supported in smartlib.tcl. The format of SmartLibrary Tcl arrays has been simplified, however.
smartlib.tcl example (new array element format):set MyConfig(ucVFD1Data.0) 20
et1000.tcl example (old array element format):set MyConfig(ucVFD1Data.0.uc) [format %c 20]
No Special Formatting for Character Types (New Interface Only)
Characters are used extensively in the SmartLibrary Tcl interface to pass numeric values to the SmartCards. These values are now automatically recognized as numeric values (as opposed to ASCII characters) and require no additional formatting.
smartlib.tcl example (new passing the numeric value 20):set MyConfig(ucVFD1Data.0) 20
et1000.tcl example (old passing a value using the Tcl formatting commands):set MyConfig(ucVFD1Data.0.uc) [format %c 20]
Default Values
See “Default Values with the Tcl Interfaces” on page 168 for a complete discussion.
Chapter 10: Using Tcl and SmartLibraryUsing the New smartlib.tcl Interface
SmartLibrary Overview and Procedures | 167
Informative Message When the Library is Sourced(Both Interfaces)
This is a convenient, although very minor, improvement in the Tcl interface. When the Tcl interface is sourced (smartlib.tcl loaded in memory) you will now see:SmartLib Programming Library <version number>
—displayed. Previously, when the Tcl interface (et1000.tcl) was sourced (loaded in memory), the name of the last structure was displayed PortPairStruct.
Ability to Send One Array Element at a Time, When Arrays Are Used (Both Interfaces)
This improvement allows you to create an array of structures, then only send one member of the array. For example, you might use an array of structures to define multiple streams in L3_DEFINE_IP_STREAM.
Chapter 10: Using Tcl and SmartLibraryDefault Values with the Tcl Interfaces
168 | SmartLibrary Overview and Procedures
Default Values with the Tcl Interfaces
Default Values for All Message Functions (Both Interfaces)
Default configuration values are an important feature of SmartLibrary versions 3.07 and later. These values are supported in both smartlib.tcl and et1000.tcl, as well as in all supported languages including Tcl, C/C++ and Visual Basic.
The benefit of these values is that you send the configuration values you are interested in, and other default values are filled in for you.
Note: Default values are covered in depth in the SmartLibrary Message Functions manual (see Chapter 3, “Default Configuration Values”). They are also covered in this chapter because the additional automated defaults are available in the Tcl interface.
Automated Default Values
Automated default values are available in smartlib.tcl only. When you source smartlib.tcl, automated defaults are off by default. Use the NSEnableAutoDefaults command to make automated defaults available in your script. This command takes no parameters and is used once in the script, before the use of any default values. A related command, NSDisableAutoDefaults, turns off the automated defaults. (For descriptions of all SmartLibrary commands, refer to the two volumes of the SmartLibrary Command Reference.)
Default Value Examples
The default value interface is quite flexible. Below are the different ways you can use them from Tcl.
You can use the message function commands, using a dash ("−") to indicate the default structure. This will send all default values for the function.
Example
Tcl Interface
Use smartlib.tcl et1000.tcl
Send default values without defining a structure. Yes No
NSEnableAutoDefaults
HTSetStructure $GIG_STRUC_TX 0 0 0 - 0 $iTxHub $iTxSlot $iTxPort \
This dash means “Use defaults. Don’t store a structure.”
Chapter 10: Using Tcl and SmartLibraryDefault Values with the Tcl Interfaces
SmartLibrary Overview and Procedures | 169
You can use the dash (default values) and still specify certain values within the command.
Example
You can specify a structure name so that your configuration values can be used later in your script. By putting the structure name as the fifth parameter of the Message Function, SmartLibrary will save your configuration values under the specified structure name.
Example
Tcl Interface
Use smartlib.tcl et1000.tcl
Specify values without specifying a structure. Yes No
Tcl Interface
Use smartlib.tcl et1000.tcl
Specify a structure name so that configuration values can be accessed later.
Yes No
NSEnableAutoDefaultsHTSetStructure $GIG_STRUC_TX 0 0 0 - 0 $iTxHub $iTxSlot $iTxPort \-ulGap 9600 \-ucVFD1Pattern {20 22 25 26 26 33 26 21} \-ucVFD2Pattern {30 32 35 36 36 43 37 31} \
without defining a structure.
Three configuration valuesare now specified. Theseoverride the defaults forGap, VFD1, and VFD2.
This dash is still used to specify default values
NSEnableAutoDefaultsHTSetStructure $GIG_STRUC_TX 0 0 0 MyConfig 0 $iTxHub $iTxSlot $iTxPort \-ulGap 9600 \-ucVFD1Pattern {20 22 25 26 26 33 26 21} \-ucVFD2Pattern {30 32 35 36 36 43 37 31} \
The complete configuration, including defaultvalues, Gap, VFD1, and VFD2, will be saved inthe automatically created structure MyConfig.
Chapter 10: Using Tcl and SmartLibraryDefault Values with the Tcl Interfaces
170 | SmartLibrary Overview and Procedures
Example
Sending Character Strings
The new interface allows you to send lists of numeric values. What if, within SmartLibrary or one of the SmartAPIs, you need to send a string?
To send a string within SmartLibrary, you can use this syntax to specify that it is a character string (different from a numeric list separated by spaces).
struct_new MyTestSetup TestSetup
set MyTestSetup(szLogFilename._char_) LogFileName.log
Note: This is a tip for working with strings in either smartlib.tcl or et1000.tcl.
Tcl Interface
Use smartlib.tcl et1000.tcl
Define a configuration structure (with or without default values) so that configuration values can be reused.
Yes Yes
struct_new MyConfig GigTransmit
-set MyConfig(ulGap) 9600 \ -set MyConfig (ucVFD1Pattern) {20 22 25 26 26 33 26 21} \-set MyConfig (ucVFD2Pattern) {30 32 35 36 36 43 37 31} \
MyConfig is specified as the structure name.
HTDefaultStructure $GIG_STRUC_TX MyConfig 0 $iHub $iSlot $iPort
HTSetStructure $GIG_STRUC_TX 0 0 0 MyConfig 0 $iHub $iSlot $iPort
MyConfig is used with the function call. It canbe modified or called later in the script.
Chapter 10: Using Tcl and SmartLibraryConverting Existing Scripts for the New Tcl
SmartLibrary Overview and Procedures | 171
Converting Existing Scripts for the New TclAs mentioned earlier, both old and new Tcl interfaces are supported. However, if have existing scripts, and wish to take advantage of the new, simplified Tcl interface, you will need to make some changes.
The paragraphs below describe possible cases when changes to existing scripts will be needed. They describe the changes a user must make to transform a script from old style to new style Tcl interface.
Step 1 Use smartlib.tcl instead of et1000.tcl.OLDsource et1000.tcl
NEWsource smartlib.tcl
Step 2 Remove character formatting for characters.Any lines that perform character formatting need to be modified.OLDset gigtx(ucTransmitMode) [format %c $GIG_CONTINUOUS_MODE]
NEWset gigtx(ucTransmitMode) $GIG_CONTINUOUS_MODE
Step 3 Remove unnecessary type fields (.c and .uc) from array fields.OLDset gigtx(ucVFD1Data.0.uc) [format %c 0xAA]set gigtx(ucVFD1Data.1.uc) [format %c 0xAB]
NEWset gigtx(ucVFD1Data.0) 0xAAset gigtx(ucVFD1Data.1) 0xAB
Step 4 Add character casting for any structure fields that are character arrays representing strings.
OLDset testsetup(szLogFilename.0.c) "a"
set testsetup(szLogFilename.1.c) "."
set testsetup(szLogFilename.2.c) "l"
set testsetup(szLogFilename.3.c) "o"
set testsetup(szLogFilename.4.c) "g"
NEWset testsetup(szLogFilename._char_) "a.log"
Chapter 10: Using Tcl and SmartLibraryAdditional Information
172 | SmartLibrary Overview and Procedures
Step 5 Remove any ConvertCtoI commands (from misc.tcl) or any other use of the scan command which converts chars to ints.
OLDputs "[ConvertCtoI $myCapData(ucData.0.uc)]"
NEWputs "$myCapData(ucData.0)"
Additional InformationHere is additional information about the SmartLibrary Tcl interface.
When SmartLibrary is Loaded
When SmartLibrary is loaded (either smartlib.tcl or et1000.tcl), it does the following:1 Loads the interface library (tclet100.dll in Windows, tclet100.so in Unix). This
library maps the Tcl SmartLibrary commands to their corresponding C/C++ SmartLi-brary commands. (The interface library loads the C/C++ SmartLibrary: etsmbw32.dll in Windows, libetsmb.so in Unix.)
2 Loads the TclStruct 1.3 library. TclStruct is an extension to Tcl used to represent data structures in Tcl.
3 Initializes all predefined constants. All the #define statements in the C/C++ Smart-Library header files have been translated to set statements in Tcl. This enables you to use these constants in your scripts.
4 Creates the SmartLibrary data structure types.
Error Checking
It is important to check for error conditions as your script is running. The utility file misc.tcl contains error-checking commands.
• LIBCMD displays the function name, arguments, and return value if an error is received.
• DCMD returns the function name, arguments, and any return value.
ExampleLIBCMD HTGetCounters GigCounters $iRxHub $iRxSlot $iRxPort
Chapter 10: Using Tcl and SmartLibraryAdditional Information
SmartLibrary Overview and Procedures | 173
Understanding Data Structures
Data structures are named groups of parameter values. With the new Tcl interface (smartlib.tcl), defining structures is optional. The older et1000.tcl interface required that you declare data structures.
All data structure types are declared in both smartlib.tcl and et1000.tcl using the struct_typedef command. To create a data structure using a declared structure from either interface file, use the struct_new command. For example, to create a data structure named Mygt of the type GIGTransmit, use the following syntax:
struct_new Mygt GIGTransmit
You can also create arrays of data structures by using the struct_new command. The following example creates the variable MyStrms to be an array of five StreamIP structures:
struct_new MyStrms StreamIP*5
Data structure fields are referenced by this syntax. The structure name is followed by an open parenthesis (followed by the name of the desired field to reference, followed by a close parenthesis). Sub-fields are separated by periods ( . ). For example, using the MyStrms variable created above, you could set the third stream's uiFrameLength field to 60 with:
set Mystrms(2.uiFrameLength) 60
Memory allocated for data structures using the struct_new command can be freed like any other variable in Tcl, by using the unset command. For example:
unset Mygtunset MyStreams
Note: When using et1000.tcl, you may not use the variable name str when declaring a structure.
Multi-Dimensional Arrays
Some SmartLibrary commands have multi-dimensional array arguments. Examples are HTHubSlotPorts and HTCardModels. SmartLibrary provides two utility functions, ETMake2DArray and ETMake3DArray, that create two- and three-dimensional arrays, respectively. The example below shows how to create and use a multi-dimensional array:
ETMake3DArray HSP $MAX_HUBS $MAX_SLOTS $MAX_PORTSHTHubSlotPorts HSPfor {set iPort 0} {$iPort < $MAX_PORTS} {incr iPort} {for {set iHub 0} {$iHub < $MAX_HUBS} {incr iHub} {for {set iSlot 0} {$iSlot < $MAX_SLOTS} {incr iSlot} {puts $HSP($iHub,$iSlot,$iPort)
}}
}
Chapter 10: Using Tcl and SmartLibraryAdditional Information
174 | SmartLibrary Overview and Procedures
Pointers
In rare cases within SmartLibrary, a structure field may be a pointer to an array or structure. An example of this is the Data field of the HTVFDStructure structure. In C/C++ form, the HTVFDStructure is declared in et1000.h like this:
Since Tcl does not support pointers, we use another form of indirection. The Data field is declared as a character array instead. The Tcl structure as declared in et1000.tcl and smartlib.tcl is:
The Data field is used to hold the name of an integer array created locally. The integer array is created as an array of Int structures:
struct_new mylocalData Int*50
For example purposes, let’s say we have created a variable of type
HTVFDStructure:struct_new myvfd HTVFDStructure
After filling in the local data array...set mylocalData(0) 0xAA
set mylocalData(1) 0xAB
# ... etc ...
Set the Data field to be the name of the newly created integer array:set myvfd(Data) mylocalData
Notice that there is no $ in front of mylocalData. This is because the Data field is set to the actual string mylocalData, the name of the variable, not the value of that variable.
typedef struct} int Configuration; int Range; int Offset; int* Data; /*pointer to an array*/ int DataCount;} HTVFDStructure;
struct_typedef HTVFDStructure {struct{int Configuration}{int Range}{int Offset}{char*256 Data} #holds name of the array (up to 256 chars){int DataCount}}
Chapter 10: Using Tcl and SmartLibraryAdditional Information
SmartLibrary Overview and Procedures | 175
Sending Arrays
In some instances, you may want to pass multiple structures (an array of basic elements as the pData argument) when using HTSetStructure, HTGetStructure, and HTSetCommands. In these cases you must use an array of one of the single element utility structures: UChar, Char, Int, etc. Create an array of these structures and use that as the pData argument. The following example sets the background data to an incrementing pattern of 60 bytes:
OLDstruct_new mydata UChar*60
for {set i 0} {$i < 60} {incr i} {
set mydata($i.uc) [format %c $i]
}
HTSetStructure $GIG_STRUC_FILL_PATTERN 0 0 0 mydata 0 $iHub $iSlot $iPort
NEWstruct_new mydata UChar*60
for {set i 0} {$i < 60} {incr i} {
set mydata($i) $i
}
HTSetStructure $GIG_STRUC_FILL_PATTERN 0 0 0 mydata 0 $iHub $iSlot $iPort
Although you may use the uiLen argument to specify the size of the data being sent or received in the pData argument, it is not actually necessary to do so when using the Tcl interface (note the " " as the sixth parameter). The SmartLibrary Tcl interface calculates the size of the data being sent or received itself and passes this value on to the core SmartLibrary.
176 | SmartLibrary Overview and Procedures
SmartLibrary Overview and Procedures | 177
Chapter 11
LibX: Simplified Library Control
The LibX Utilities are a family of Tcl procedures, created using the Programming Library and designed to simplify the process of setting up and operating SmartBits cards and chassis.
These procedures were developed for Technical Support to allow quick, command line-based procedures to set up SmartCards and display essential card configuration parameters and test-program output.
This chapter briefly explains fundamental concepts for LibX, and also includes simple exercises that illustrate each concept. These examples are identified by the Try It! heading.
All the examples in this chapter were run on a SmartBits 200 with four ML-7710 SmartMetrics SmartCards connected to a Windows 95 PC. Commands you enter are shown in bold courier type—for example, set_capture $card1.
In this chapter...
• System Requirements . . . . 178
• Command Usage . . . . 181
• Summary of LibX Procedures . . . . 204
Chapter 11: LibX: Simplified Library ControlSystem Requirements
178 | SmartLibrary Overview and Procedures
System RequirementsLibX requires Tcl version 8.0 or higher, because it makes use of capabilities such as namespaces that were introduced with Tcl 8.0.
Cards Supported
The current release of LibX focuses primarily on Ethernet cards in SmartMetrics mode. However, many of the functions described here work across a range of card types.
LibX Components
LibX consists of the files listed below. When you run loadx.tcl to load LibX, it automatically checks to find which Tcl interface files are sourced (et1000.tcl or smartlib.tcl), then loads the appropriate Core LibX and Layer 3/SmartMetrics command files (below): either libx.tcl and l3x.tcl or slibx.tcl and sl3x.tcl.
File Name Description
loadx.tcl A Tcl script that loads the LibX components.
libx.tcl Core LibX commands and definitions.
slibx.tcl
l3x.tcl Layer 3/SmartMetrics stream commands.
sl3x.tcl
unloadx.tcl A Tcl script that unloads the LibX components.
Chapter 11: LibX: Simplified Library ControlExample 1: Loading LibX with loadx.tcl
SmartLibrary Overview and Procedures | 179
Example 1: Loading LibX with loadx.tclBefore running LibX, you must start the Tcl Shell and source the library interface files, either et1000.tcl or smartlib.tcl. This loads the programming library.
Try It! Load LIBX
1 Start the Tcl Shell and source et1000.tcl or smartlib.tcl.2 cd to the directory holding the LibX files.3 Enter source loadx.tcl.
How Does It Work?
After a series of checks, loadx.tcl sources the component files (either libx.tcl and l3x.tcl, or slibx.tcl and sl3x.tcl), then imports only the procedure names from each into the global namespace.
Load Problems
If the message was not displayed, there was a problem installing LibX. Possible error messages include:ERROR libx requires Tcl version 8.0 or higher
You are using a version of Tcl older than 8.0. You must upgrade before using LibX.
Files libx.tcl and/or l3x.tcl were not found
The component files are not in the local directory. Check the current directory (using pwd) and be sure it is the directory that contains the LibX files.
Can't import command “check_link”: already exists
There is a command in the global namespace that has the same name as one of the LibX commands. You have to remove or rename the existing command before you can load LibX. This is a safety feature of LibX that prevents it from silently replacing a command or procedure that already exists.
To remove a conflict of this type, use the Tcl rename command. For example, to rename the procedure check_link as check_link.org, use rename check_link check_link.org. The sequence is shown below.
Chapter 11: LibX: Simplified Library ControlExample 1: Loading LibX with loadx.tcl
180 | SmartLibrary Overview and Procedures
Listing Commands
LibX adds a series of new commands to the Tcl environment. Before starting, you could check for all the commands that start with set, show, or check as follows:
The only command above is the Tcl set command. After installing LibX, if we repeat the same command sequence, we get the following. These new commands are LibX.
Chapter 11: LibX: Simplified Library ControlCommand Usage
SmartLibrary Overview and Procedures | 181
Command UsageHere are guidelines on command format and card numbering.
Format
All LibX commands have the same format:command root => one of: set_ | show_ | check_ | run_ | stop_ | burst_
The command root is appended to the appropriate action, such as:set_streamip Sets up IP data streams on the target card.sset_link Connects to the SmartBits chassis.set_capture Sets up and starts a capture on the target card.show_stream Shows the streams currently established on the target card.
For simplicity and consistency, all LibX commands have the underscore character ( _ ) only following the command root and nowhere else. Commands are always lower-case and always singular, never plural.
See the summary table at the end of this chapter for a complete list of the currently defined LibX commands.
Card Numbering Conventions
Some LibX commands, such as set_link, have no arguments. Most commands, however, have at least the ID of target SmartCard.
The Programming Library identifies a card's position in the chassis or chassis stack by the Hub Slot Port triple. This numbering system is zero-based, so the first card in the first chassis is identified as Hub Slot Port 0 0 0.
LibX simplifies this by defining each potential chassis position with a card number. For example, the first card in the first chassis (Hub Slot Port 0 0 0) is defined as card1.
You can see how card1 is defined using the puts command.
Note that the {0 0 0} is not the same as 0 0 0. The LibX commands expect a list to identify a card, not individual numbers. Using lists to reference cards rather than the Hub Slot Port triple allows us to expand the concept of groups.
Chapter 11: LibX: Simplified Library ControlCommand Usage
182 | SmartLibrary Overview and Procedures
Example To set capture on the first card in the first chassis, you would enter:set_capture $card1
Since the LibX commands accept a list as an argument, you can create a group as a list of lists and pass the group list to the LibX command exactly as you would a single card.
Currently LibX does not include a set_group command; you have to create your own. The usage is conceptually the same as to define a single card. For example, to set up a group called txgroup with cards 1, 3, 4, and 12 as members, then start a capture on all group members, you would use:set txgroup [list $card1 $card3 $card4 $card12]set_capture $txgroup
This will set capture on card 1, 3, 4, and 12. (Although the library has group commands for many functions, capture is not one of them.)
In cases where the parent library does not have a group capability (such as setting a capture), LibX will create an appropriate loop mechanism, usually a Tcl foreach command, to achieve this purpose. In cases where the parent library already provides a group command, LibX will convert the card list into a SmartLibrary group, then execute the appropriate group command.
Chapter 11: LibX: Simplified Library ControlExample 2: set_default and set_link
SmartLibrary Overview and Procedures | 183
Example 2: set_default and set_linkLibX has a set_default procedure that sets the card to a predefined base state. The base state is approximately the base state established by the SmartWindow application when you select File>New.
This is different from the default state established on power-up or by using the library HTResetPort $RESET_FULL command. For example, a power-up or ResetPort will set the background pattern for an Ethernet card to all zero. SmartWindow and set_default create a basic Ethernet frame. For example, for card 2 it will set the destination MAC address to FF FF FF FF FF FF and the source MAC address to 00 00 00 00 00 02.
With the power-on default of all zero, you generally will not be able to send packets through a switch, since almost any switch will block an all-zero packet. With the SmartWindow or set_default packet, in contrast, the packets will pass.
Try It! set_default
1 Set up two SmartCards in slots 1 and 2.2 Power on the chassis.3 Start the Tcl Shell and source et1000.tcl.4 Set card 1 to the default state with set_default $card1.
Normally, you would not be able to send a command to a SmartBits chassis, since you didn't link. Attempting to send a command before linking would produce an error.
LibX always checks the system's state before executing. If you are not linked, it will prompt for a serial port or Ethernet address and link before executing the command, as shown below.5 When prompted, enter the COM port number to connect via serial connection, or
enter E to select an Ethernet link.If linking via Ethernet, enter the IP address and TCP port number.After the link is complete (as indicated by the Ethernet linked message), the card type is displayed by the set_default procedure.
Chapter 11: LibX: Simplified Library ControlExample 2: set_default and set_link
184 | SmartLibrary Overview and Procedures
How Does It Work?
If you look at the set_default procedure (in libx.tcl), you will see that it starts as follows:proc set_default { {group} } {check_link
The set_default procedure has one argument, group, which we have seen is the list defining the card—in this case, $card1. The first step is to call the procedure check_link, which checks the link state. If it is not linked, it calls a second procedure, set_link, which actually sets up the link.
You may want to change the default Ethernet address in set_link. The easiest way is to open libx.tcl in a programming editor and search for the line:
set IPADDRESS "192.168.100.10"
Change it to the desired address. Reload LibX and the new default will be the value you entered.
The set_default procedure identifies the target card using HTGetCardModel. Based upon the name returned it runs the default setting procedure appropriate to the card. A part of the set_default procedure is shown below:
set cardname ""set cardname ““
LIBCMD HTGetCardModel cardname $H $S $Pswitch $cardname {
SE-6205 -SC-6305 -ST-6405 -ST-6410 {puts "L2 10Mb Ethernet"set_ethernet $H $S $P}SX-7205 -SX-7210 −
Chapter 11: LibX: Simplified Library ControlExample 3: Transmit and Count
SmartLibrary Overview and Procedures | 185
Example 3: Transmit and CountThree commands control transmission in LibX:
• run Starts transmission on the target card.
• stop Stops transmission on the target card.
• burst Sends a burst from the target card.
Transmit
Try It! Run and Stop
1 Ensure the Tcl Shell is started and the library is loaded.2 Connect card 1 and card 2 either back to back with a crossover cable or through a
device.3 Start card 1 transmitting with run $card1. The TX LED will light on card 1 and
the RX LED will light on card 2.4 Stop card 1 with stop $card1. The LEDs will go out.
How Does It Work?
The transmit procedures are some of the simplest in LibX. Here is the run procedure in its entirety:
Here is what the procedure does:
proc run {group} { check_link list2group $group LIBCMD HGStart}
Command/Argument Description
run Procedure name.
group The only argument: a card or a group of cards.
check_link Checks for the link (as described above).
list2group $group Calls an internal procedure that converts the group list into a SmartBits group.
HGStart This group command starts the group transmitting.
Chapter 11: LibX: Simplified Library ControlExample 3: Transmit and Count
186 | SmartLibrary Overview and Procedures
Counters
Two LibX procedures give control over the card counters:• set_count Clears the on card counters.• show_count Displays the current card counter data.
Note: SmartBits counters are always enabled. At any time, you can retrieve the counter data, and the data will show all the counts since the counters were last reset or since the chassis was powered on.
Try It! Counters
After ensuring the system is ready to send commands, do the following:1 Read the counter data on card 2 by entering show_count $card2. The counter
data from card 2 will be displayed as shown. Here, card 2 has received a little over four million packets but hasn't transmitted anything.
2 Clear the counters on card 2 by entering set_count $card2. Now use show_count to display the counter data again showing all the counts have been reset to zero.
3 Start card 1 transmitting using the run command. While the card is still transmitting, display the counts on card 2 with show_count.
4 The show_count display will now show the packets received (Events) plus the pack-ets-per-second rate (Rates).
Chapter 11: LibX: Simplified Library ControlExample 3: Transmit and Count
SmartLibrary Overview and Procedures | 187
5 Leave card 1 transmitting. Show the counter data from card 1 this time, using show_count.How is the counter data from card 1 different?Answer: Card 1 will show transmitted packets and no received packets. Card 2 shows received packets and no transmitted packets.
6 While card 1 is still transmitting, start card 2 transmitting using the run command. Display the counter data for both cards. If the cards are in half-duplex mode, you will now see the collision and undersize counts increasing as shown. You may or may not see a trigger count depending on what state the background on the card is in.
Remember! Counter Rates are only displayed while transmission is in progress. If you stop the transmission, the rates are always zero.
Troubleshooting Tip: Sometimes you may have a Tcl script that seems to be transmitting and receiving (the TX and RX LEDs are lit), but the received packet counts in your program are always zero. Load LibX and use set_count to zero the counters on the receiving card. Run the problem program. Then use show_count to display the counters.
If the program has set the packet length to be greater that the maximum length or less than the minimum legal length, the packets will be shown as undersize or oversize, not received packets. If the transmit card was set to transmit CRC errors, the packets will be shown under CRC errors, etc.
Chapter 11: LibX: Simplified Library ControlExample 3: Transmit and Count
188 | SmartLibrary Overview and Procedures
Procedure Defaults
There are optional defaults on many LibX procedures. The summary table at the end of this chapter shows the syntax of all LibX commands.
The burst command is shown as:burst GROUP <burst size 100>
The command name is burst. As —we have seen, the GROUP argument is the target card entered as $card1 or $card2, etc. The third argument in angle brackets, here burst size, is an optional argument. If you enter:burst $card1
—card 1 will transmit 100 packets. The default value of 100 is used.
If you enter:burst $card1 10000
—card 1 will transmit 10000 packets. The value 10000 overrides the default value.
If you look at the first line of the burst procedure in libx.tcl, it looks like this:proc burst { {group} {burst_size 100} } {
The argument burst_size and the default value 100 are enclosed in curly braces. Arguments that are not optional, such as group, do not have a default value. If you call burst without the group argument, you will get an error.
Try It! Procedure Defaults
1 Clear the counters on both cards.2 Send a 100-packet burst using the default value. 3 Display the counters to verify that 100 packets were sent.4 Send a 5000-packet burst by specifying the burst count.5 Display the counter data to verify that 5000 packets were sent this time.
Chapter 11: LibX: Simplified Library ControlExample 4: set_capture/show_capture
SmartLibrary Overview and Procedures | 189
Example 4: set_capture/show_captureCounters give you a rough idea of the packets transmitted and received, but in many cases you will want to capture and view the packet data. This is especially true if you are setting up a program and want to be sure of the packets you think you are sending.
The LibX capture commands will work on all capture-capable cards, including the SX-7210/7410, L3-6710, ML-7710, and Gigabit cards.
set_capture
Unlike counters, which are “running” all the time, capture must be started first. There are varying options for each card capture type. The LibX capture procedures set them all the same:
• Capture all packets.
• Capture complete packets.
• Capture as much as possible.
Accordingly, the usage is the same for all cards: set_capture GROUP.
show_capture
This command stops the currently running capture and displays the specified number of packets, formatted in the traditional 16-bytes-per-line hex dump.
Checking the syntax in the summary table (end of chapter), you will find:show_capture GROUP <NUM> <output>
—where NUM is the number of packets to display (default is 5), and output is an optional output file. All LibX show commands have the option of redirecting the output to a file rather than to the display.
Writing Output to a File
If you look at the first line of the show_capture procedure, you will see:proc show_capture { {group} {CAP_COUNT 5} {output stdout} } {
All the puts statements in the procedure specify $output as the output target. For example:puts $output "No packets captured on card [expr $S + 1]"
Chapter 11: LibX: Simplified Library ControlExample 4: set_capture/show_capture
190 | SmartLibrary Overview and Procedures
Since output is defaulted to stdout (the display), if you don't specify a value for output, the output goes to the screen (as always). If you do want the output redirected, the calling program opens a file and passes in the handle as the argument to output. Now all puts commands will send the output to the file. To be explicit: If you wanted to send the first 100 packets captured to a file named capture.log, you would use a sequence like this:
Try It! set_capture/show_capture
1 Ensure the system is ready for LibX commands.2 Connect card 1 and card 2 back to back with a crossover cable and ensure the cards
are linked.3 Start a capture on card 2 with set_capture $card2.4 Start transmitting from card1.5 Stop and display the capture on card 2 with show_capture $card2.
Notice the packet contents are not all zero, as they are on power up. The source and destination MAC addresses were set by the set_default procedure. The last four non-zero bytes are the packet CRC.
If you request a larger number to display than are in the capture buffer, the procedure will adjust the number to display to the actual number in the capture buffer.
set fileID [open capture.log a]set_capture $card2run $card1after 1000show_capture $card2 100 $fileID
Chapter 11: LibX: Simplified Library ControlExample 4: set_capture/show_capture
SmartLibrary Overview and Procedures | 191
Capture Problems
It seems obvious that if you want to capture the packets transmitted from card 1, you should start the capture on another card (and not on card 1), but this is a common mistake.
By default, SmartMetrics cards do not capture ARP packets. The L3-6710 card has never done this, because it doesn't have sufficient processing power to capture and respond to ARPs at the same time. The ML-7710 card has enough processing power (since it has two separate processors) and now has the capability in firmware, but the function is not yet part of the Programming Library.
Chapter 11: LibX: Simplified Library ControlExample 5: set_mii/show_mii
192 | SmartLibrary Overview and Procedures
Example 5: set_mii/show_miiTwo LibX procedures read and write the MII registers on 10/100 cards. These procedures will work on any 10/100 Ethernet card (including the SX-7410, SX-7210, and ML-7710).
MII Overview
Manipulating the values in the MII registers controls the speed and duplex mode of the FastCard. We will discuss the first six registers:
• Register 0 Control register (READ/WRITE). Controls the configuration ofthe local PHY or physical interface.
• Register 1 Status register (READ ONLY). Shows the status of the localPHY.
• Register 2 and 3 ID registers (READ ONLY). Shows the make and model of thePHY.
• Register 4 Advertisement (READ/WRITE). Sets the speed and duplexmodes we will accept during the auto negotiation process.
• Register 5 Link Partner (READ ONLY). Sets the speed and duplex modethe device on the other end of the link is willing to accept.
Essentially, there are two ways to set the speed and duplex mode on a device.1 Disable auto negotiation by clearing the Enable Auto Negotiation bit in the Control
Register, then forcing the speed and duplex mode by setting the corresponding bits on the Control Register.
2 Enable auto negotiation by setting the Enable Auto Negotiation bit in the Control Register. The link speed and duplex mode will then be negotiated by the two devices on the link. The outcome will be the highest common mode on Register 4 (what we are advertising) and Register 5 (what the other side is advertising).
The Control Register
The Control Register is where we enable and disable auto negotiation, restart auto negotiation, and where, if auto negotiation is disabled, we set the speed and duplex mode for the local device.
The bit position identification for the MII Control Register is shown in the SmartWindow MII window (see below). The most significant bits are as follows:
Chapter 11: LibX: Simplified Library ControlExample 5: set_mii/show_mii
SmartLibrary Overview and Procedures | 193
Control Register: Most Significant Bits
Bit Description
12 Enables and disables auto negotiation.
9 Restarts auto negotiation.
13 Sets the speed for the local device if bit 12 is cleared (auto negotiation disabled).
8 Sets the duplex mode for the local device if bit 12 is cleared (auto negotiation disabled).
Chapter 11: LibX: Simplified Library ControlExample 5: set_mii/show_mii
194 | SmartLibrary Overview and Procedures
The Status Register
The bit position identification for the MII Status Register also is shown in the SmartWindow MII window (see below). The most significant bits are as follows:
Status Register: Most Significant Bits
Bit Description
11-14 Modes supported by this PHY.
5 Auto Negotiation Complete. Indicates that the auto negotiation cycle has completed.
3 Indicates that this PHY is auto negotiation-capable.
2 Indicates that the link is up.
Chapter 11: LibX: Simplified Library ControlExample 5: set_mii/show_mii
SmartLibrary Overview and Procedures | 195
Try It! set_mii/show_mii
1 Ensure the system is ready to accept LibX commands (shell started, library loaded, etc).
2 Enter show_mii $card1. The current state of the first six MII registers is displayed, as shown below.
Q. The current value of the Control Register is 0x3100. What does this indicate?
A. The bits for 100Mb (0x2000), Enable Auto Negotiation (0x1000), and Full Duplex Mode (0x0100) are set.
Q. Does this setting mean the device is linked at 100Mb Full Duplex Mode?
A. No. The speed and duplex settings in the Control Register have meaning only if auto negotiation is disabled. When auto negotiation is enabled in the Control Register, the speed and duplex mode are determined by negotiation between the two devices on the link.
Q. What value would we need to write as the Control Word to force the local device to 10Mb, Half Duplex?
A. 0x0000. This would clear the 100Mb and Full Duplex bits and disable auto negotiation.
Let's try it. First look at the summary table for the syntax of the set_mii command. It is shown as:
set_mii GROUP <WORD> <REG>
We should be pretty familiar with the command GROUP part of a LibX command by now. WORD is the control word we want to write to the register, and REG is the number of the register we want to write to.
Chapter 11: LibX: Simplified Library ControlExample 5: set_mii/show_mii
196 | SmartLibrary Overview and Procedures
So to send the control word 0x0000 to register 0, we would use set_mii $card1 0x0000 0:
• Use the set_mii command to force card1 to 10Mb Half Duplex.
• Use show_mii to display the register settings.
The result should be as shown below. This will also probably drop the link unless the other side happens to be at 10Mb Half Duplex. If you look at the bit pattern of the status register, you will see the Link bit is no longer set.
• Enable auto negotiation and force an auto negotiation by writing 0x1200 to the control register (0x1000 = Enable auto negotiation, 0X0200 = Restart auto negotiation).
The cards should relink.
MII Write Problems
Note that the control word is formatted with a leading 0x. This indicates the value is in hex. If you do not use the leading 0x, the value you enter will be interpreted as decimal, probably not what you intended. When you read it back with show_mii, it will be displayed in hex, which might leave you wondering “What happened?” Now you know.
Not all fields on the READ/WRITE registers on all transceivers are writable. If you send a 7 you may read back a 5 (assuming the 2 bit is not writable).
Chapter 11: LibX: Simplified Library ControlExample 6: set_l3/show_l3
SmartLibrary Overview and Procedures | 197
Example 6: set_l3/show_l3The set_l3/show_l3 commands set, configure, and display the Layer 3 settings for a target SmartMetrics card. These settings set the MAC address and IP address of the card stack, specify the default gateway, and configure, enable, or disable background packet generation (PING, RIP, and ICMP).
set_l3The set_l3 LibX function will prompt for the most significant Layer 3 settings. You enter the parameters when prompted and the card configuration is set.
Try It! set_l3
1 Ensure the system is set to receive LibX commands.2 Run the set_l3 procedure for card1 by entering set_l3 $card1.3 Enter configuration values when prompted, as shown below.
In the example above, we set the following values:• Default gateway address (the IP address of the router port you are connected to).• Card stack IP address (normally in the same subnet as the router port).• IP address of the PING target (if PINGs were enabled this would be the address we
would be PING-ing for).• Control word.
Bits 2 and 4 enable and disable background packet generation. Bit 1 will cause the card to replay to ALL ARPs on the network and should never be set on a live network.
Chapter 11: LibX: Simplified Library ControlExample 6: set_l3/show_l3
198 | SmartLibrary Overview and Procedures
show_l3
The companion command is show_l3. This command will display the current setting of the most significant L3 settings on the target card.
Try It! show_l3
To display the Layer 3 settings for card 1, enter show_l3 $card1.
The Layer 3 settings are displayed with formatting as shown below. Note that the user was not prompted by set_l3 for some fields displayed here, such as Netmask and Card MAC. If necessary, the program can be modified by the end user to prompt for fields specific to his/her own requirements.
Chapter 11: LibX: Simplified Library ControlExample 7 - set_streamxx/show_stream
SmartLibrary Overview and Procedures | 199
Example 7 − set_streamxx/show_streamStreams are the core of the SmartMetrics cards. They allow you to set up over 1000 different VTEs or streams per card, with control over the contents of every protocol header field. The trick is to set up all those streams without making a mistake, such as having the same IP address for more than one MAC address, duplicating IP addresses, or setting the wrong streams to the wrong gateway.
set_streamip
The LibX set_stream commands automate the stream creation process and will usually allow you to set up streams without duplications or mismatches.
There are three stream-creation commands: set_streamip, set_streamudp, and set_streamipx, used to create groups of IP, UDP, or IPX packets, respectively.
If we look at summary table for the syntax of the set_streamip command, we see:set_streamip GRP1 GRP2 <NUM 10> <sourceIP> <destIP>
The arguments are as follows:
Let's look at the default case first. If we enter set_streamip $card1 $card2, we will set up ten streams on card1. The stream creation commands require two GROUP or card arguments, because we use the card numbers to generate unique stream numbers.
The default pattern for IP addresses is 10.X.1.10. When the streams are created, the X is replaced with the card number. So in our example, if we are transmitting from card 1 to card 2, the source IP would be 10.1.1.10 and the destination IP would be 10.2.1.10.
The card number also replaces the third byte of the MAC address. So the source MAC address for the first stream created on card 2 would be 00 00 00 02 00 01.
Each successive stream created increments the LSB of both MAC address and the least significant octet of both IP addresses.
The MAC addresses and IP addresses for the ten streams created (card1 to card2) would be as shown in the table below.
Argument Description
GRP1 Transmitting card or group of cards.
GRP2 Receiving card or group of cards.
NUM Number of streams to create.
sourceIP Source IP address of the first stream.
destIP Destination IP address of the first stream.
Chapter 11: LibX: Simplified Library ControlExample 7 - set_streamxx/show_stream
200 | SmartLibrary Overview and Procedures
To create a second set of matching streams on card 2, you would enter set_streamip $card2 $card1.
Try It! set_streamip
• Ensure the system is ready for LibX commands.
• Create the default 10 streams on card 1 with set_streamip $card1 $card2.
• Create a matching set of streams on card 2 with set_streamip $card2 $card1.
show_stream
Now that you have created the streams, how can you check them? You could start a capture on one card and transmit from the other and view the captured packets, but decoding raw hex dumps can be tedious. LibX has a command, show_stream, that will display the protocol data on the target card, formatted to make it easier to read.
The syntax (from the summary table) is:show_stream GROUP <NUM 5> <output>
So by default, it will display the protocol data for the first 5 streams. Like all show commands, the output can be redirected to a file (see page 189).
Stream # Source IP Source MAC Destination IP Destination MAC
1 10.1.1.10 00 00 00 01 00 01 10.2.1.10 00 00 00 02 00 01
2 10.1.1.11 00 00 00 01 00 02 10.2.1.11 00 00 00 02 00 02
3 10.1.1.12 00 00 00 01 00 03 10.2.1.12 00 00 00 02 00 03
4 10.1.1.13 00 00 00 01 00 04 10.2.1.13 00 00 00 02 00 04
5 10.1.1.14 00 00 00 01 00 05 10.2.1.14 00 00 00 02 00 05
6 10.1.1.15 00 00 00 01 00 06 10.2.1.15 00 00 00 02 00 06
7 10.1.1.16 00 00 00 01 00 07 10.2.1.16 00 00 00 02 00 07
8 10.1.1.17 00 00 00 01 00 08 10.2.1.17 00 00 00 02 00 08
9 10.1.1.18 00 00 00 01 00 09 10.2.1.18 00 00 00 02 00 09
10 10.1.1.19 00 00 00 01 00 10 10.2.1.19 00 00 00 02 00 10
Chapter 11: LibX: Simplified Library ControlExample 7 - set_streamxx/show_stream
SmartLibrary Overview and Procedures | 201
Try It! show_stream
After you have created the streams on card 1 and 2 as outlined on the previous page, display the protocol data by entering show_stream $card1. Notice the MAC and IP addresses substitute the card numbers at the places explained previously. Notice also the frame length and ARP status for this stream is displayed below the IP addresses.
Display the protocol data for card 2 using the show_stream command. Note again how the default-addressing scheme replaces the indicated values with the card number.
Adding Additional Streams and Removing Streams
To add additional streams, simply run the desired stream creation command again. The set_stream commands will append new streams to those already on the card.
If you want to remove all the streams on the card you can:
• Use a set_stream command passing zero as the number of streams—for example, set_streamip $card1 $card2 0.
• Use the LibX set_default procedure. The default for SmartMetrics cards is zero streams.
• Use the set_l2 LibX command (covered in the next section).
• Use the library HTResetPort command (a reset erases all streams).
Chapter 11: LibX: Simplified Library ControlExample 7 - set_streamxx/show_stream
202 | SmartLibrary Overview and Procedures
Non-default IP Addresses
If you do not want the default IP addressing scheme, you can pass in a new IP address. The syntax of the set_stream command is:
set_streamip GRP1 GRP2 <NUM 10> <sourceIP> <destIP>
To set up a group of 10 streams starting with 192.168.X.10 (where X will be replaced with the card number) transmitting to a group of streams starting with 13.X.27.20, you would enter set_streamip $card1 $card2 10 192.168.X.10 13.X.27.20.
Note that if you want to override a default value, you have to set all optional values to the left of that value. In this case for example, we have to explicitly pass in the NUM value of 10, even though that is the default value, if we want to change the IP addresses.
Many to One and One to Many
You can take advantage of LibX's ability to accept groups as arguments to specify test setups of one to many, many to one, or many to many.
As covered previously, it is possible to set a group of cards using the form:set RxGroup [list $card2 $card3 $card4]
This creates a virtual group of three cards that can be passed into any LibX command. For example, after creating the RxGroup we could start capture on all three by entering set_capture $RxGroup.
We can use the same capability to do many-to-one or one-to-many tests.
For example, set_streamudp $card1 $RxGroup will set up 30 streams on card 1, 10 addressed for card 2, 10 addressed for card 3, and 10 addressed for card 4.
Chapter 11: LibX: Simplified Library ControlExample 8 – Other Stream Commands
SmartLibrary Overview and Procedures | 203
Example 8 – Other Stream CommandsThere are two additional stream commands to know:
• set_l2 Displays the number of streams on the card and gives the user theopportunity to erase the streams and switch to layer 2 (Traditional) mode.
• set_arp Sends ARP requests from all active streams on the card.
set_l2
Erasing all streams puts the card in Layer 2 (Traditional or L2) mode. The syntax is set_l2 GROUP.
set_arp
Sends ARP requests from all active streams. Remember that the show_stream command also displays ARP status. You can use that to check that the ARP cycles are complete. The syntax is set_arp GROUP.
Chapter 11: LibX: Simplified Library ControlSummary of LibX Procedures
204 | SmartLibrary Overview and Procedures
Summary of LibX ProceduresTable 11-1. Summary of LibX Procedures
Procedure Arguments Description
run GROUP Starts card transmitting (continuous mode).
stop GROUP Stops transmitting.
burst GROUP <burst size 100> Sends a burst of packets (restores to continuous mode on exit).
set_link – Checks for library file installation and current link. If not linked, prompts for COM port or Ethernet address.
check_link – Checks for link. Calls set_link if not linked.
set_count GROUP Resets counters with HTClearPort.
show_count GROUP <output> Displays standard counter data. Output option allows file handle to be used as output target (write to a file rather than stdout).
set_capture GROUP Resets counters to capture all. Works on Fast Ethernet and L3 cards.
show_capture GROUP <NUM> <output> Displays number of packets set by NUM. Default is 5 packets. Works with both L3 and Fast Ethernet cards. Output option same as for show_count.
set_mii GROUP <WORD> <REG> Sets register REG with the value of WORD. Defaults are 0 and 0x0000.
show_mii GROUP <output> Shows current contents of first 5 MII registers. Output option same as for show_count.
check_cardlink CARD Checks the card's current link state. Returns 1 if the link is up, −1 if the link is down.
set_default GROUP Sets target card to reasonable default values. Works on Fast Ethernet, L3, Gigabit, and ATM cards. Defaults are generally those of SmartWindow.
set_streamip GRP1 GRP2 <NUM 10> Sets up NUM IP streams on the card(s) in the GRP1 list (default 10). It uses the source and destination CardList Elements to generate the streams where the IP addresses are 10.x.1.10 (X = number of card) and MAC addresses of 00 00 00 XX 00 01 (XX = card number).
Chapter 11: LibX: Simplified Library ControlSummary of LibX Procedures
SmartLibrary Overview and Procedures | 205
set_streamudp GRP1 GRP2 <NUM 10> Similar to set_streamip above.
set_streamipx GRP1 GRP2 <NUM 10> Similar to above, but uses a similar scheme to generate Host and Network numbers.
show_stream GROUP <NUM 5> <output> Shows streams on the target card. Breaks out fundamental information such as protocol, source and destination IP addresses, source and destination MAC addresses, and length. Shows raw data dump under protocol breakout. Output option same as show_count.
set_l3 GROUP Interactive utility for configuring L3 parameters. Prompts user for gateway, SmartCard, and PING destination IP addresses and Control word.
show_l3 GROUP <output> Shows L3 configuration. Output options same as for show_count.
set_l2 GROUP Displays the number of transmitting streams on target card and allows the user to remove them, setting the card in L2 mode.
Table 11-1. Summary of LibX Procedures (continued)
Procedure Arguments Description
206 | SmartLibrary Overview and Procedures
SmartLibrary Overview and Procedures | 207
Chapter 12
ATM Testing – SmartBits 200/2000
This chapter describes how to set up tests using ATM SmartCards for the SmartBits 200/2000 chassis.
In this chapter...
• ATM Card Types . . . . 208
• ATM Streams and Connections – SmartBits 200/2000 . . . . 209
• Set Up Basic PVC Tests – SmartBits 200/2000 . . . . 212
• Set Up Basic SVC Tests – SmartBits 200/2000 . . . . 217
• Set Up Tests for PPP over ATM – SmartBits 200/2000 . . . . 224
Chapter 12: ATM Testing – SmartBits 200/2000ATM Card Types
208 | SmartLibrary Overview and Procedures
ATM Card TypesThis chapter deals with ATM SmartCards used in the SmartBits 200/2000 chassis. You can find a step-by-step procedure for ATM modules for SmartBits 600x/6000x chassis in Chapter 13, “ATM Testing – SmartBits 600x/6000x.”
ATM SmartCards for the SmartBits 200/2000 chassis are divided into two groups, termed ATM-1 and ATM-2, as shown in Table 12-1.
Table 12-1. ATM SmartCards (SmartBits 200/2000)
SmartCard ATM-1 ATM-2 Description
AT-9015 ATM DS1, 1-port
AT-9020 v ATM E1, 1-port
AT-9025 v ATM 25.6 Mbps, 1-port
AT-9034B v ATM E3, 1-port
AT-9045B v ATM DS3, 1-port
AT-9155C v ATM OC-3c (STM-1c), 1-port, multi-mode, 1300nm
AT-9155Cs v ATM OC-3c (STM-1c), 1-port, single mode, 1310nm
AT-9622 v ATM OC-12c (STM-1c), 1-port, multi-mode, 1300nm
AT-9622s v ATM OC-12c (STM-1c), 1-port, single mode, 1310nm
Chapter 12: ATM Testing – SmartBits 200/2000ATM Streams and Connections – SmartBits 200/2000
SmartLibrary Overview and Procedures | 209
ATM Streams and Connections – SmartBits 200/2000ATM SmartCards support multiple, independent streams (frame blueprints) per port and connections with a wide range of powerful controls. They do not support signature fields or, as a result, data analysis by using histograms. Histograms are described in Chapter 5, “Histogram Results.”
SmartLibrary provides two methods of working with ATM streams:
• By using stream indexes and connection indexes together.
• By using enhanced stream indexes without connection indexes.
These two methods are described below.
Enhanced Stream Indexes
As compared to the use of stream and connection indexes (see “Using Stream Indexes and Connection Indexes (Older Method)” on page 209), enhanced stream indexes provide a simpler method of gathering test information. This functionality (available in SmartLibrary release 3.06 beta 2 and later) enables you to retrieve test results by specifying the stream index without a connection index.
Note: ATM enhanced stream indexes requires SmartCard firmware Release 2.0 or later.
Connection indexes are still available and work as described below, but they are not a necessary part of the test procedure. Instead, with enhanced stream indexes, there is a one-to-one correlation between stream indexes and connections. This means that if you are using LAN Emulation (LANE) and have configured numerous streams to use the same VPI/VCI, a stream index gives you aggregate results for all streams using that VPI/VCI (connection/channel).
Using Stream Indexes and Connection Indexes (Older Method)
This “older method” of working with ATM streams was available in SmartLibrary releases before 3.05 patch 2. It may still be used, if desired, with current SmartLibrary releases.
With this method, an ATM stream is created by using the ATM_STREAM iType parameter. This action defines the connection parameters, as well as the encapsulation type, cell rate, and so forth.
The payload of the ATM frames is defined by ATM_FRAME_DEF. It includes a static stream index, as set by the uiIndex element in the stream structure. This stream index can be used to query the SmartCard for information about the stream structure.
Once the stream connection has been made, the SmartCard allocates a connection index, which can be used to gather test results information. The connection index, however, is different from the stream index, because it is allocated on an as-available basis. As a
Chapter 12: ATM Testing – SmartBits 200/2000ATM Streams and Connections – SmartBits 200/2000
210 | SmartLibrary Overview and Procedures
result, before you can use a connection index to gather test information, you must identify the correct connection index for each stream.
Note: See the Tcl example in “Example of Stream Indexes with Connection Indexes” below for a coding example that shows how to retrieve information using connection indexes.
This older method of working with ATM streams is still supported in SmartLibrary releases. An alternate and simpler method, however, became available in SmartLibrary release 3.06 beta 2 and is supported in all later releases. This is the use of enhanced stream indexes. This method is described in “Enhanced Stream Indexes” on page 209.
Example of Stream Indexes with Connection Indexes
The snippet of Tcl code below illustrates how to retrieve information using connection indexes.
The ATM SmartCard assigns a connection index each time a connection is established. For a valid connection index, the card must be queried each time the stream is connected.
##############################################################################################################################struct_new vcc_info ATMVCCInfostruct_new stream_info ATMStreamDetailedInfo
# Use ATM_STREAM_DETAIL to get the connection indexLIBCMD HTGetStructure $ATM_STREAM_DETAIL_INFO 0 $NUM_STREAMS 0stream_info 0 $iHub $iSlot $iPort
# Use ATM_VCC_INFO to get the statsfor {set j 0} {$j < $NUM_STREAMS} { incr j} { puts "Checking status on Tx Card (Connection Index$stream_info(status.$j.uiConnIndex))" LIBCMD HTGetStructure $ATM_VCC_INFO$stream_info(status.$j.uiConnIndex) 1 0 vcc_info 0 $iHub $iSlot $iPort puts "Stats for stream $j..." # Cell header is decimal by default - force to hex... puts "Cell Header [format "%08X"$vcc_info(status.0.ulCellHeader)]" puts "Tx Frame count ==> $vcc_info(status.0.ulTxFrame)" puts ""}
Chapter 12: ATM Testing – SmartBits 200/2000ATM Streams and Connections – SmartBits 200/2000
SmartLibrary Overview and Procedures | 211
iType1 Command for Enhanced Stream Indexes
The following iType1 commands support the use of enhanced stream indexes.
Note: Commented functions and structures can be found in the atmitems.h header file. The message functions and structures are also included in the Tcl and Visual Basic interfaces.
Description with Message Function iType1 Data Type (Structure)
Extended VCC statistics ATM_EXT_VCC_INFO ATMExtVCCInfo
Per-stream burst configuration ATM_PER_STREAM_BURST ATMPerConnBurstCount
Stream-based extended VCC statistics
ATM_STREAM_EXT_VCC_INFO ATMExtVCCInfo
Stream-based configuration of the per-connection trigger
ATM_STREAM_TRIGGER_PARAMS ATMConnTriggerParams
Stream-based retrieval of per-connection trigger statistics
ATM_STREAM_TRIGGER_INFO ATMConnTriggerInfo
Stream-based retrieval of per-connection trigger time statistics
ATM_STREAM_TRIGGER_TIME_INFO ATMStreamTriggerTimeInfo
Stream-based VCC statistics ATM_STREAM_VCC_INFO ATMVCCInfo
Chapter 12: ATM Testing – SmartBits 200/2000Set Up Basic PVC Tests – SmartBits 200/2000
212 | SmartLibrary Overview and Procedures
Set Up Basic PVC Tests – SmartBits 200/2000
Applicable Commands
Summary of commands
Table 12-2 is a summary of commands you can use to set up tests with ATM PVCs.Not all commands are required. This list is an overview.
A basic setup See “Example of Setup Steps” on page 213 for a basic setup procedure, as well as optional commands and actions.
Table 12-2. Applicable Commands for ATM PVC Tests
Applicable Commands
What the Commands Do Original Function Message Function iType1/Notes
Reset all streams. HTSetStructure ATM_STREAM_CONTROL
Set up line parameters. HTSetStructure Depending on card type:
ATM_DS1_E1_LINE_PARAM
ATM_DS3_E3_LINE_PARAM
ATM_LINE
Check the line state. HTGetStructure Depending on card type:
ATM_DS1_E1_LINE_INFO
ATM_DS3_E3_LINE_INFO
ATM_SONET_INFO
Configure the stream as a PVC. HTSetStructure ATM_STREAM
Set up the frame template(s). HTSetStructure ATM_FRAME_DEF
Connect. HTSetStructure ATM_STREAM_CONTROL
Confirm that a connection has been established. HTGetStructure ATM_STREAM_DETAIL_INFO
Set triggers to filter for patterns in the payload. HTSetStructure ATM_STREAM_TRIGGER_PARAMS
Transmit. HTSetStructure ATM_STREAM_CONTROL
Stop test traffic. HTSetStructure ATM_STREAM_CONTROL
Retrieve frame counts (per-connection only). HTGetStructure ATM_STREAM_VCC_INFO
Retrieve trigger statistics. HTGetStructure ATM_STREAM_TRIGGER_INFO
Chapter 12: ATM Testing – SmartBits 200/2000Set Up Basic PVC Tests – SmartBits 200/2000
SmartLibrary Overview and Procedures | 213
Example of Setup Steps
Here is an example of how to set up basic PVC tests. It assumes no previous configuration. It shows selected commands, not all possible commands or actions.
Step 1 Reset all streams.
Step 2 Set up the line parameters. Depending on card type, use one of the following iType1 commands to set up line parameters.
Optional/RelatedOptional or related commands and actions (if applicable) are shown in a shaded box. These actions are not required for a basic test setup.
UseOriginal Function
WithMessage Function iType1 Related Structure
HTSetStructure ATM_STREAM_CONTROL None
HTClearPort — None
ATM CardUseOriginal Function
WithMessage Function iType1 Related Structure
AT-9015, AT-9020 HTSetStructure ATM_DS1_E1_LINE_PARAM ATMDS1E1LineParams
AT-9034B, AT-9045B ATM_DS3_E3_LINE_PARAM ATMDS3E3LineParams
AT-9025, AT-9155C/CSAT-9622/S
ATM_LINE ATMLineParams
Chapter 12: ATM Testing – SmartBits 200/2000Set Up Basic PVC Tests – SmartBits 200/2000
214 | SmartLibrary Overview and Procedures
Step 3 Check the line state. Depending on card type, use the following to check the line state.
Step 4 Configure the stream as a PVC. Specify the stream index as part of the stream defini-tion.
Step 5 Set up frame template(s).
Step 6 Connect.
Step 7 Confirm that a connection has been established.
ATM Card Check UseOriginal Function
withMessage Function iType1(Structure)
AT-9015, AT-9020 DS1/E1 line state HTSetStructure ATM_DS1_E1_LINE_INFO(ATMDS1E1LineInfo)
AT-9034B, AT-9045B DS3/E3 line state ATM_DS3_E3_LINE_INFO(ATMDS3E3LineInfo)
AT-9025, AT-9155C/CS, AT-9622/S SONET state ATM_SONET_INFO(ATMSonetLineInfo)
Use Original Function with Message Function iType1 Related Structure
HTSetStructure ATM_STREAM ATMStream
Use Original Function with Message Function iType1 Related Structure
HTSetStructure ATM_FRAME_DEF ATMFrameDefinition
Use Original Function with Message Function iType1 Related Structure
HTSetStructure ATM_STREAM_CONTROL ATMStreamControl
Use Original Function with Message Function iType1 Related Structure
HTSetStructure ATM_STREAM_DETAIL_INFO ATMStreamDetailedStatus
Chapter 12: ATM Testing – SmartBits 200/2000Set Up Basic PVC Tests – SmartBits 200/2000
SmartLibrary Overview and Procedures | 215
Step 8 (Optional) Set triggers to filter for patterns in the payload.
Step 9 (Optional) Set up port groups
To set up a port group, use HGSetGroup and HGAddtoGroup to define the port group and to add ports to a group.
Step 10 Send test traffic.
For group start, use HGStart.
Step 11 Stop test traffic.
For group stop, use HGStop.
End of Required Steps for Basic Setup
This completes the basic steps needed to transmit test traffic. The usefulness of your test, however, depends on getting test results. See “Getting Test Results” on page 216 for the steps to gather results information.
Use Original Function with Message Function iType1 Structure
HTSetStructure ATM_STREAM_TRIGGER_PARAMS
ATMConnTriggerParams
Original Function Description
HGSetGroupHGAddtoGroup
Define a group of SmartBits ports. Add ports to the group. You can control group ports by using the HG commands.
Use Original Function with Message Function iType1 Structure
HTSetStructure ATM_STREAM_CONTROL ATMStreamControl
Original Function Description
HGStart Transmit test frames.
Use Original Function with Message Function iType1 Structure
HTSetStructure ATM_STREAM_CONTROL ATMStreamControl
Original Function Description
HGStop Stop the test (if running continuous traffic rather than step or burst mode).
Chapter 12: ATM Testing – SmartBits 200/2000Set Up Basic PVC Tests – SmartBits 200/2000
216 | SmartLibrary Overview and Procedures
Getting Test Results
Use the following steps to get frame counts and trigger statistics with PVC tests.Step 1 Retrieve frame counts (per-connection only).
Use the stream index from Step 4 on page 214 to retrieve connection statistics.
Step 2 (Optional) Retrieve trigger statistics.
Use the stream index from Step 4 on page 214 to retrieve trigger statistics.
Use Original Function with Message Function iType1 Structure
HTGetStructure ATM_STREAM_VCC_INFO ATMStreamVCCInfo and
ATMStreamVCCIStatus
Use Original Function with Message Function iType1 Structure
HTGetStructure ATM_STREAM_TRIGGER_INFO
ATMTriggerInfo
Chapter 12: ATM Testing – SmartBits 200/2000Set Up Basic SVC Tests – SmartBits 200/2000
SmartLibrary Overview and Procedures | 217
Set Up Basic SVC Tests – SmartBits 200/2000Table 12-3 is a summary of commands you can use to set up tests with ATM SVCs.Not all commands are required. This list is an overview.
A basic setup See “Example of Setup Steps” on page 213 for a basic setup procedure, as well as optional commands and actions.
Table 12-3. Applicable Commands for ATM SVC Tests
Applicable Commands
What the Commands Do Original Function Message Function iType1/Notes
Reset all streams. HTSetStructure ATM_STREAM_CONTROL
Set up line parameters. HTSetStructure Depending on card type:
ATM_DS1_E1_LINE_PARAM
ATM_DS3_E3_LINE_PARAM
ATM_LINE
Check the line state. HTGetStructure Depending on card type:
ATM_DS1_E1_LINE_INFO
ATM_DS3_E3_LINE_INFO
ATM_SONET_INFO
Set the ILMI parameters. HTSetStructure ATM_ILMI
Register the ATM address (if dynamic ILMI). HTSetCommand ATM_ILMI_REGISTER
Get the ILMI status. HTGetStructure ATM_ILMI_INFO
Configure the SSCOP. HTSetStructure ATM_SSCOP
Configure the UNI signaling parameters. HTSetStructure ATM_UNI
Establish the SAAL interface. HTSetCommand ATM_SAAL_ESTABLISH
Get the SAAL status. HTGetStructure ATM_SAAL_INFO
Configure the stream as a PVC. HTSetStructure ATM_STREAM
Set up the frame template(s). HTSetStructure ATM_FRAME_DEF
Connect. HTSetStructure ATM_STREAM_CONTROL
Confirm that a connection has been established. HTGetStructure ATM_STREAM_DETAIL_INFO
Continues –>
Chapter 12: ATM Testing – SmartBits 200/2000Set Up Basic SVC Tests – SmartBits 200/2000
218 | SmartLibrary Overview and Procedures
Example of Setup Steps
Here is an example of how to set up basic PVC tests. It assumes no previous configuration. It shows selected commands, not all possible commands or actions.
Use the following steps to configure SVC connections and traffic and retrieve results.Step 1 Reset all streams.
Step 2 Set up the line parameters.
Depending on card type, use the following to set up line parameters.
Transmit. HTSetStructure ATM_STREAM_CONTROL
Stop test traffic. HTSetStructure ATM_STREAM_CONTROL
Retrieve frame counts (per-connection only). HTGetStructure ATM_STREAM_VCC_INFO
Retrieve trigger statistics. HTGetStructure ATM_STREAM_TRIGGER_INFO
Table 12-3. Applicable Commands for ATM SVC Tests (continued)
Applicable Commands
What the Commands Do Original Function Message Function iType1/Notes
Optional/RelatedOptional or related commands and actions (if applicable) are shown in a shaded box. These actions are not required for a basic test setup.
UseOriginal Function
WithMessage Function iType1 Related Structure
HTSetStructure ATM_STREAM_CONTROL None
HTClearPort — None
ATM CardUseOriginal Function
WithMessage Function iType1 Related Structure
AT-9015, AT-9020 HTSetStructure ATM_DS1_E1_LINE_PARAM ATMDS1E1LineParams
AT-9034, AT-9045B ATM_DS3_E3_LINE_PARAM ATMDS3E3LineParams
AT-9025, AT-9155C/CS,AT-9622/S
ATM_LINE ATMLineParams
Chapter 12: ATM Testing – SmartBits 200/2000Set Up Basic SVC Tests – SmartBits 200/2000
SmartLibrary Overview and Procedures | 219
Step 3 Check the line state.
Depending on card type, use the following to check the line state.
Step 4 Set the ILMI parameters to indicate the desired end-system identifier.
Step 5 Register the ATM address, if the ILMI method is dynamic.
Step 6 Get the ILMI status.
Step 7 Configure the SSCOP level of the ATM interface.
ATM Card Check UseOriginal Function
withMessage Function iType1(Structure)
AT-9015, AT-9020 DS1/E1 line state HTSetStructure ATM_DS1_E1_LINE_INFO(ATMDS1E1LineInfo)
AT-9034, AT-9045B DS3/E3 line state ATM_DS3_E3_LINE_INFO(ATMDS3E3LineInfo)
AT-9025, AT-9125, AT-9155C/CS, AT-9622/S
SONET state ATM_SONET_INFO(ATMSonetLineInfo)
Use Original Function with Message Function iType1 Related Structure
HTSetStructure ATM_ILMI ATMILMIParams
Use Original Function with Message Function iType1 Related Structure
HTSetStructure ATM_ILMI_REGISTER ATMILMIStaticParams
Use Original Function with Message Function iType1 Related Structure
HTGetStructure ATM_ILMI_INFO ATMILMIInfo
Use Original Function with Message Function iType1 Related Structure
HTSetStructure ATM_SSCOP ATMSSCOPParams
Chapter 12: ATM Testing – SmartBits 200/2000Set Up Basic SVC Tests – SmartBits 200/2000
220 | SmartLibrary Overview and Procedures
Step 8 Configure the UNI signaling parameters.
Step 9 Establish the SAAL interface.
Step 10 Get the SAAL status.
Step 11 Configure the stream as an SVC.
Specify the stream index as part of the stream definition.
Step 12 Set up frame template(s).
Step 13 Connect.
Use Original Function with Message Function iType1 Related Structure
HTSetStructure ATM_UNI ATMUNIParams
Use Original Function with Message Function iType1 Related Structure
HTSetCommand ATM_SAAL_ESTABLISH None
Use Original Function with Message Function iType1 Related Structure
HTGetStructure ATM_SAAL_INFO ATMSAALInfo
Use Original Function with Message Function iType1 Related Structure
HTSetStructure ATM_STREAM ATMStream
Use Original Function with Message Function iType1 Related Structure
HTSetStructure ATM_FRAME_DEF ATMFrameDefinition
Use Original Function with Message Function iType1 Related Structure
HTSetStructure ATM_STREAM_CONTROL ATMStreamControl
Chapter 12: ATM Testing – SmartBits 200/2000Set Up Basic SVC Tests – SmartBits 200/2000
SmartLibrary Overview and Procedures | 221
Step 14 Confirm that a connection has been established.
Step 15 (Optional) Set triggers to filter for patterns in the payload.
Step 16 (Optional) Set up port groups
To set up a port group, use HGSetGroup and HGAddtoGroup to define the port group and to add ports to a group.
Step 17 Send test traffic.
For group start, use HGStart.
Use Original Function with Message Function iType1 Related Structure
HTSetStructure ATM_STREAM_DETAIL_INFO ATMStreamDetailedStatus
Use Original Function with Message Function iType1 Structure
HTSetStructure ATM_STREAM_TRIGGER_PARAMS
ATMConnTriggerParams
Original Function Description
HGSetGroupHGAddtoGroup
Define a group of SmartBits ports. Add ports to the group. You can control group ports by using the HG commands.
Use Original Function with Message Function iType1 Structure
HTSetStructure ATM_STREAM_CONTROL ATMStreamControl
Original Function Description
HGStart Transmit test frames.
Chapter 12: ATM Testing – SmartBits 200/2000Set Up Basic SVC Tests – SmartBits 200/2000
222 | SmartLibrary Overview and Procedures
Step 18 Stop test traffic.
For group stop, use HGStop.
End of Required Steps for Basic Setup
This completes the basic steps needed to transmit test traffic. The usefulness of your test, however, depends on getting test results. See “Getting Test Results” below for the steps to gather results information.
Getting Test Results
Use the following steps to get frame counts and trigger statistics with SVC tests.Step 1 Retrieve frame counts (per-connection only). Use the stream index from Step 11 on
page 220 to retrieve connection statistics.
Step 2 (Optional) Retrieve trigger statistics.
Use the stream index from Step 11 on page 220 to retrieve trigger statistics.
Step 3 Release the SAAL.
Use Original Function with Message Function iType1 Structure
HTSetStructure ATM_STREAM_CONTROL ATMStreamControl
Original Function Description
HGStop Stop the test (if running continuous traffic rather than step or burst mode).
Use Original Function with Message Function iType1 Related Structure
HTGetStructure ATM_ILMI_INFO ATMILMIInfo
Use Original Function with Message Function iType1 Related Structure
HTGetStructure ATM_ILMI_INFO ATMILMIInfo
Use Original Function with Message Function iType1 Related Structure
HTSetCommand ATM_SAAL_RELEASE None
Chapter 12: ATM Testing – SmartBits 200/2000Set Up Basic SVC Tests – SmartBits 200/2000
SmartLibrary Overview and Procedures | 223
Step 4 Deregister the ATM address.
Use Original Function with Message Function iType1 Related Structure
HTSetCommand ATM_ILMI_DEREGISTER None
Chapter 12: ATM Testing – SmartBits 200/2000Set Up Tests for PPP over ATM – SmartBits 200/2000
224 | SmartLibrary Overview and Procedures
Set Up Tests for PPP over ATM – SmartBits 200/2000
Summary
Table 12-4 is a summary of the general steps to configure PPP over ATM. For basic steps to configure ATM PVCs and SVCs, see also:
• “Set Up Basic PVC Tests – SmartBits 200/2000” on page 212.
• “Set Up Basic SVC Tests – SmartBits 200/2000” on page 217.
Note: PPP over ATM currently may be used only with ATM-2 cards. See “ATM Card Types” on page 208).
Detailed Steps
Here is a detailed description of the steps summarized in Table 12-4.Step 1 Reset All Previously Configured Streams
Use HTSetStructure with ATM_STREAM_CONTROL(ATMStream) to reset all existing ATM streams.
Step 2 Set up the Line Parameters
Use HTSetStructure with ATM_LINE(ATMLine) to set up the ATM line parameters.
Table 12-4. Applicable Commands for PPP over ATM
Step Description Original Function Message Function iType1
1 Reset all previously configured streams.
HTSetStructure ATM_STREAM_CONTROL
2 Set up the line parameters. HTSetStructure ATM_LINE
3 Set up the streams. HTSetStructure ATM_STREAM
4 Set up the frame definition. HTSetStructure ATM_FRAME_DEF
5 Configure the PPP connection. HTSetStructure PPP_CONFIG
6 Issue the Echo control request. HTSetStructure PPP_SET_CTRL
7 Issue a connect request. HTSetStructure ATM_STREAM_CONTROL
8 Send test traffic and stop the test. HGRunHGStepHGStop
See SmartLibrary Command Referencefor parameters and use.
9 Get PPP status information. HTGetStructure PPP_STATUS_INFO
Chapter 12: ATM Testing – SmartBits 200/2000Set Up Tests for PPP over ATM – SmartBits 200/2000
SmartLibrary Overview and Procedures | 225
Step 3 Set up the Streams
Use HTSetStructure with ATM_STREAM(ATMStream) to set up the streams, specifying the following:
Connection Type:PVCEncapsulation Type:STR_ENCAP-TYPE-LLC_PPP — or—
STR_ENCAP_TYPE_VC_MULTIPLEXED_PPP
Step 4 Set up the Frame Content
Use HTSetStructure with ATM_FRAME_DEF(ATMFrameDefinition) to set up the frame definition.
Encapsulation Type = LLC PPPIf the encapsulation type in Step 3 is STR_ENCAP_TYPE_LCC_PPP, the AAL5 payload would be as shown below, with the following, values:
DSAP= 0xFESSAP= 0xFECtrl= 0x03NLPID= 0xCFProtocol ID= 0x00-21
Encapsulation Type = VC MULTIPLEXED PPPIf the encapsulation type in Step 3 is STR_ENCAP_TYPE_VC_MULTIPLEXED_PPP, the AAL5 payload would be as shown below, with the following value:
Protocol ID= 0x00-21
Step 5 Configure the PPP Connection
Use HTSetStructure with PPP_CONFIG(pppParamCfg) to define PPP characteristics.
Step 6 Issue the Echo Control Request
Use HTSetStructure with PPP_SET_CTRL(pppControlCfg) to enable or disable echo.
← LLC → ← PPP Payload →
DSAP SSAP Ctrl NLPID Protocol ID PPP Information
Padding
← 1 → ← 1 → ← 1 → ← 1 → ← 2 →
← PPP Payload →
Protocol ID PPP Information
Padding
← 2 →
Chapter 12: ATM Testing – SmartBits 200/2000Set Up Tests for PPP over ATM – SmartBits 200/2000
226 | SmartLibrary Overview and Procedures
Step 7 Issue a Connect Request
Use HTSetStructure with ATM_STREAM_CONTROL(ATMStreamControl) to issue a connection request.
Step 8 When the connection becomes established (return code 5), it indicates that all negotia-tion has been completed. Check the connection by using ATM_STREAM_DETAIL_INFO.
Step 9 Send Test Traffic, Stop Traffic
Use the HTRun or HGRun command to run the test.
Use HTStop to stop the test when you run the test with continuous traffic.
Step 10 Retrieve PPP Status Information
Use HTGetStructure with PPP_STATUS_INFO(PPPStatusInfo) to retrieve PPP status information.
Original Function Description
HTRun Set the run state of the port.
HGRun Set the run state for all ports that have been associated with the PortIdGroup, as defined by your HGSetGroup(PortIdGroup) command.
HTStop Stop the test when running continuous traffic.
SmartLibrary Overview and Procedures | 227
Chapter 13
ATM Testing – SmartBits 600x/6000x
This chapter describes how to set up tests using ATM TeraMetrics modules for the SmartBits 600x/6000x chassis.
In this chapter...
• Overview . . . . 228
• Traffic Rates . . . . 229
• Interleave Depth . . . . 229
• Set Up Tests with ATM-345xA(s) TeraMetrics Modules . . . . 233
• Latency Measurement Limitations . . . . 251
Chapter 13: ATM Testing – SmartBits 600x/6000xOverview
228 | SmartLibrary Overview and Procedures
OverviewATM TeraMetrics modules for the SmartBits 600x/6000x chassis include the following.
Important: Before you start, review important overview information. These topics include the following:
• Traffic RatesSee “Traffic Rates” on page 229 for the traffic rate with the ATM-345xA(s) modules listed above. Detailed information about transmit calculations can be found in Appendix B, “Transmit Calculations for ATM-345xA(s) Modules.”
• Interleave Depth“Interleave Depth” on page 229 explains the interleave depth when testing with ATM-345xA(s) modules.
Summary of commands
Table 13-2 on page 233 is a summary of the commands you can use in testing with the ATM-345xA(s) modules listed above. Not all commands are required, and not all commands are listed. This list is an overview.
A basic setup See “Example of Setup Steps” on page 237 for a basic setup procedure, as well as optional commands and actions.
Latency measurement limitations
“Latency Measurement Limitations” on page 251 explains some limitations with Latency measurement.
Table 13-1. ATM TeraMetrics Modules
Module Description
SmartBitsChassis
600x/6000x
ATM-3451A TeraMetrics ATM OC-3c, 2 ports, multi-mode
ATM-3451As TeraMetrics ATM OC-3c, 2 ports, single-mode
ATM-3453A TeraMetrics ATM OC-3c/OC-12c, 2 ports, multi-mode
ATM-3453As TeraMetrics ATM OC-3c/OC-12c, 2 ports, single-mode
Chapter 13: ATM Testing – SmartBits 600x/6000xTraffic Rates
SmartLibrary Overview and Procedures | 229
Traffic RatesWith ATM-345xA(s) modules, you specify the frame rate by calling stream extension commands (L3_DEFINE_STREAM_EXTENSION, L3_MOD_STREAM_EXTENSION, L3_DEFINE_MULTI_STREAM_EXTENSION). All streams associated with a particular VC must have the same frame rate (ulFrameRate). Other stream transmit parameters—such as transmit mode, burst count, multiburst count, burst gap—are specified for each VC (AT_VC_CREATE).
Rate Class (CBR/UBR), PCR (Peak Cell Rate) and CDVT (Cell Delay Variation Tolerance) are specified for each VC (AT_VC_CREATE). But they are not used to generate traffic. They are used to verify the cell sequence created by a scheduling algorithm based on the frame rate. NS_COMMIT_CONFIG must be called before HTRun (or HGRun). The commit action will fail and return an error code if a defined frame rate on a VC violates the VC’s PCR or CDVT. This is a basic check that helps to ensure you do not violate the traffic contracts configured on a DUT.
ATM-345xA(s) modules do not support interframe gap (IFG) as a way to specify a traffic rate. This is because of the different scheduling algorithm used with the assigned and idle cells for the modules. For this reason, the HTGap, HTGapAndScale, HTScheduleMode, and NS_PORT_TRANSMIT commands are not supported for these modules.
Notes: • NS_COMMIT_CONFIG must be called before HTRun (HGRun). It applies all stream configurations—that is, schedules the streams and VCs for transmission. It completes the configuration procedures.
• Refer to Appendix B, “Transmit Calculations for ATM-345xA(s) Modules” for detailed information on transmit calculation.
Interleave DepthTo support testing of DUTs with a limited number of AAL5 reassembly buffers, ATM-345xA(s) modules provide a way to control precisely the amount of AAL5 frame interleaving when simultaneously transmitting on multiple VCs.
The ulVCInterleaveDepth parameter in the ATPortConfig structure is used to set the interleave depth. Interleave depth is the maximum number of VCs on which the scheduler is allowed to interleave frames. The maximum number of VCs on which frames are interleaved, along with the maximum frame size, determines the maximum number of reassembly buffers that will be required by a DUT in order to simultaneously reassemble them.
For example, assume the following:
• Five VCs with identical parameters are configured with one AAL5 stream;
• Each AAL5 frame is segmented into two ATM cells;
• Interleave depth is 2.
Chapter 13: ATM Testing – SmartBits 600x/6000xInterleave Depth
230 | SmartLibrary Overview and Procedures
The generated cell sequence will look like the following:[VC1 Cell 1][VC2 Cell 1][VC1 Cell 2][VC2 Cell 2][VC3 Cell 1][VC4 Cell 1][VC3 Cell 2][VC4 Cell 2][VC5 Cell 1][VC5 Cell 2]
If Interleave depth = 1, frames on all VCs will be transmitted serially (one after the other), with no frames interleaved on any VCs. If Interleave depth is any number greater than a number of configured VCs, frames on all the VCs will be interleaved. SmartLibrary defines the AT_VC_INTERLEAVE_ALL at 8191, which is the maximum number of VCs that can be configured on the module. Interleave depth of 0 is undefined, and if used will be changed to AT_VC_INTERLEAVE_ALL by the firmware.
If the Interleave depth = N, where N is less than the number of VCs configured, the VCs will be divided into N groups. Frames on VCs within the same group will be transmitted serially. Frames on VCs from different groups will be allowed to interleave.
The following restrictions are imposed by the stream scheduler, in order to determine which VCs can be grouped together.
• VCs that can be placed in the same group must be configured as UBR (Unspecified Bit Rate) and must have the same set of transmit parameters (frame rate, Tx mode, burst size, burst count, IBG and so on).
• If a group is using Burst mode, the burst size for the group will be the burst size of the individual VCs multiplied by the number of VCs in the group. The IBG for the group will be the IBG of the individual VCs.
• Each CBR (Constant Bit Rate) VC will be placed in a group by itself, to guarantee its CDVT.
• The NS_COMMIT_CONFIG command will return an error code if the VCs cannot be grouped to guarantee that the maximum Interleave Depth is satisfied. If this occurs, either the Interleave depth should be increased, or the transmit characteristics of the streams/VCs should be modified to allow more VCs to be grouped (into fewer groups).
Known limitations regarding the Interleave Depth function.
The following are known limitations:
• Commit fails if Interleave Depth is applied on CBR VCs. Currently, in order to use Interleave Depth, all VCs must be UBR.
• If VCs configured for burst mode are grouped together to control Interleave Depth, the Burst Count for the group will be the Burst Count configured for the individual VCs rather than the Burst Count for the Individual VCs in the group multiplied by the number of VCs in the group.
Chapter 13: ATM Testing – SmartBits 600x/6000xInterleave Depth
SmartLibrary Overview and Procedures | 231
• Commit fails if Interleave Depth is applied on VCs configured for multiburst or continuous burst mode. Currently, to use Interleave Depth, all VCs must be either continuous mode or single burst mode.
Examples The following are two examples to illustrate the grouping mechanism with interleave depth feature.
Example 1
Assume the following:
• Four VCs with identical parameters are configured with two AAL5 streams per VC;
• Each AAL5 frame is of the same length;
• Interleave depth is 2.
The VCs will be grouped like this:Group1: VC1 VC2Group2: VC3 VC4
and consequently the frames will be grouped as follows:Group1:[VC1 Stream1 Frame1] [VC1 Stream2 Frame1] [VC2 Stream1 Frame1] [VC2 Stream2 Frame1][VC1 Stream1 Frame2] [VC1 Stream2 Frame2] [VC2 Stream1 Frame2] [VC2 Stream2 Frame2][VC1 Stream1 Frame3] [VC1 Stream2 Frame3] [VC2 Stream1 Frame3] [VC2 Stream2 Frame3]…
Group2:[VC3 Stream1 Frame1] [VC3 Stream2 Frame1] [VC4 Stream1 Frame1] [VC4 Stream2 Frame1][VC3 Stream1 Frame2] [VC3 Stream2 Frame2] [VC4 Stream1 Frame2] [VC4 Stream2 Frame2][VC3 Stream1 Frame3] [VC3 Stream2 Frame3] [VC4 Stream1 Frame3] [VC4 Stream2 Frame3]…
Frames from the same group go out serially, and frames from different groups go out parallel. The generated frame sequence will look like the following:
[VC1 Stream1 Frame1] - [VC3 Stream1 Frame1][VC1 Stream2 Frame1] - [VC3 Stream2 Frame1][VC2 Stream1 Frame1] - [VC4 Stream1 Frame1][VC2 Stream2 Frame1] - [VC4 Stream2 Frame1][VC1 Stream1 Frame2] - [VC3 Stream1 Frame2][VC1 Stream2 Frame2] - [VC3 Stream2 Frame2][VC2 Stream1 Frame2] - [VC4 Stream1 Frame2][VC2 Stream2 Frame2] - [VC4 Stream2 Frame2][VC1 Stream1 Frame3] - [VC3 Stream1 Frame3][VC1 Stream2 Frame3] - [VC3 Stream2 Frame3][VC2 Stream1 Frame3] - [VC4 Stream1 Frame3][VC2 Stream2 Frame3] - [VC4 Stream2 Frame3]
In the example above, [VC1 Stream1 Frame1] and [VC3 Stream1 Frame1] will go out in parallel—that is, the cells from these two frames might be interleaved. [VC1 Stream2
Chapter 13: ATM Testing – SmartBits 600x/6000xInterleave Depth
232 | SmartLibrary Overview and Procedures
Frame1] and [VC3 Stream2 Frame1] and subsequent parallel frames may have cells that are interleaved.
Example 2
Assume the following:
• Three VCs with identical parameters are configured with two AAL5 streams per VC;
• Each AAL5 frame is of the same length;
• Interleave depth is 2.
The VCs will be grouped as follows:Group1: VC1 VC2Group2: VC3
and consequently the frames will be grouped asGroup1:[VC1 Stream1 Frame1] [VC1 Stream2 Frame1] [VC2 Stream1 Frame1] [VC2 Stream2 Frame1][VC1 Stream1 Frame2] [VC1 Stream2 Frame2] [VC2 Stream1 Frame2] [VC2 Stream2 Frame2][VC1 Stream1 Frame3] [VC1 Stream2 Frame3] [VC2 Stream1 Frame3] [VC2 Stream2 Frame3]…Group2:[VC3 Stream1 Frame1] [VC3 Stream2 Frame1] [VC3 Stream1 Frame2] [VC3 Stream2 Frame2][VC3 Stream1 Frame3] [VC3 Stream2 Frame3]…
As in the previous example, frames from the same group go out serially, and frames from different groups go out parallel. More time slots, however, are allocated for Group1 than for Group2. In fact, allocating time slots is a function of the scheduler, which takes PCR (cell rate of the group), frame rate, class of service, and CDVT (for CBR) into account. For this example, the number of time slots for Group1 is twice of that of Group2, because the number of VCs in Group1 is twice the number of VCs in Group2. Furthermore, since all the AAL5 frames are the same length, and the VCs are transmitting at the same cell rate, the generated frame sequence will look like the following:
[VC1 Stream1 Frame1] - [VC3 Stream1 Frame1][VC1 Stream2 Frame1][VC2 Stream1 Frame1] - [VC3 Stream2 Frame1][VC2 Stream2 Frame1][VC1 Stream1 Frame2] - [VC3 Stream1 Frame2] [VC1 Stream2 Frame2][VC2 Stream1 Frame2] - [VC3 Stream2 Frame2][VC2 Stream2 Frame2][VC1 Stream1 Frame3] - [VC3 Stream1 Frame3][VC1 Stream2 Frame3]
In the above example, [VC1 Stream1 Frame1] and [VC3 Stream1 Frame1] will go out in parallel—that is, the cells from these two frames will be interleaved; [VC1 Stream2 Frame1] will go out after [VC1 Stream1 Frame1] and [VC3 Stream1 Frame1] finish, and before [VC2 Stream1 Frame1] – [VC3 Stream2 Frame1] start to transmit; and so on.
Chapter 13: ATM Testing – SmartBits 600x/6000xSet Up Tests with ATM-345xA(s) TeraMetrics Modules
SmartLibrary Overview and Procedures | 233
Set Up Tests with ATM-345xA(s) TeraMetrics ModulesTable 13-2 is a summary of the main applicable commands you can use to test with the ATM-345xA(s) modules. This list is an overview.
Table 13-2. Main Applicable Commands for Tests with ATM-345xA(s) Modules
Applicable Commands
What the Commands Do Original Function Message Function iType1/Notes
Reserve the module. HTSlotReserve N/A
Reset the port. This action includes the following:– Clears all streams– Deletes all PVCs– Clears all general counters– Clears SONET statistics counters– Resets Trigger setup to the default
“Off” state– With RESET_FULL, configures the
port to the default setting.
HTResetPort N/A
This message clears Layer 2 and ATM port counters, VC counters, SONET counters, SONET stats, and stream TX counters.
HTClearPort N/A
Get the LED status. HTGetLEDs N/A
ATM port configuration. This message is also used to turn on/off the flag to allow/disallow bad frame length for the latency measurement limitations.
HTSetStructure AT_PORT_CONFIG
Retrieve the port configuration. HTGetStructure AT_PORT_CONFIG_INFO
Optional: Set the port speed. HTSetCommand AT_SET_SPEED
HTSetSpeed N/A
Configure VCs (virtual connections).Configure transmit parameters, including Tx mode and burst count, during the VC create step.
HTSetStructure AT_VC_CREATEAT_VC_COPYAT_VC_MODIFY
Modify an array of VCs. HTSetStructure AT_MOD_VC_ARRAY
Retrieve the configuration of one VC. HTGetStructure AT_VC_INFO
Delete VC or VCs. HTSetCommand AT_VC_DELETEAT_VC_DELETE_ALL
Configure a background fill pattern. HTSetCommand L3_WRITE_STREAM_BG
Chapter 13: ATM Testing – SmartBits 600x/6000xSet Up Tests with ATM-345xA(s) TeraMetrics Modules
234 | SmartLibrary Overview and Procedures
Read back the background fill pattern. HTGetCommand L3_READ_STREAM_BG
Configure streams. HTSetStructure Depending on protocol type, various commands may be used:
Define:
L3_DEFINE_IP_STREAML3_DEFINE_UDP_STREAML3_DEFINE_TCP_STREAML3_DEFINE_ICMP_STREAML3_DEFINE_IPV6_STREAML3_DEFINE_UDP_IPV6_STREAML3_DEFINE_TCP_IPV6_STREAML3_DEFINE_ICMP_IPV6_STREAML3_DEFINE_SMARTBITS_STREAML3_DEFINE_SMARTBITS_128_STREAM
Modify:
L3_MOD_IP_STREAML3_MOD_UDP_STREAML3_MOD_TCP_STREAML3_MOD_ICMP_STREAML3_MOD_IPV6_STREAML3_MOD_UDP_IPV6_STREAML3_MOD_TCP_IPV6_STREAML3_MOD_ICMP_IPV6_STREAML3_MOD_SMARTBITS_STREAML3_MOD_SMARTBITS_128_STREAM
Define Multiple:
L3_DEFINE_MULTI_IP_STREAML3_DEFINE_MULTI_UDP_STREAML3_DEFINE_MULTI_TCP_STREAML3_DEFINE_MULTI_IPV6_STREAML3_DEFINE_MULTI_UDP_IPV6_STREAML3_DEFINE_MULTI_TCP_IPV6_STREAML3_DEFINE_MULTI_ICMP_STREAML3_DEFINE_MULTI_ICMP_IPV6_STREAML3_DEFINE_MULTI_SMARTBITS_STREAML3_DEFINE_MULTI_SMARTBITS_128_STREAM
Modify selected fields in an array of streams.
HTSetStructure L3_MOD_STREAMS_ARRAY
Set frame rate, initial sequence number, data integrity enable, custom stream ID, and other parameters.
HTSetStructure L3_DEFINE_STREAM_EXTENSION
Read the stream extension information. HTGetStructure L3_READ_STREAM_EXTENSION
Table 13-2. Main Applicable Commands for Tests with ATM-345xA(s) Modules (continued)
Applicable Commands
What the Commands Do Original Function Message Function iType1/Notes
Chapter 13: ATM Testing – SmartBits 600x/6000xSet Up Tests with ATM-345xA(s) TeraMetrics Modules
SmartLibrary Overview and Procedures | 235
Configure the MPLS label in the stream.
HTSetStructure L3_DEFINE_MPLSL3_MOD_MPLS
Bind streams to VC, and set CLP bit for streams. All streams must be bound to a VC before the test can be run.
HTSetStructure L3_DEFINE_STREAM_BINDINGL3_MOD_STREAM_BINDINGL3_DEFINE_MULTI_STREAM_BINDING
Configure an alternate key to use in grouping frames for statistical purposes.
HTSetStructure NS_ALTERNATE_KEY_CONFIG
Configure the alternate key hash. HTSetStructure NS_ALTERNATE_KEY_HASH_CONFIG
Configure transmit/receive triggers. HTSetStructure NS_TRIGGER_CONFIG
Set up histogram.
—or—
HTSetStructure Various commands may be used:
NS_HIST_COMBO_PER_STREAMNS_HIST_LATENCY_DIST_PER_STREAMNS_HIST_LATENCY_OPTIONNS_HIST_LATENCY_OVER_TIMENS_HIST_RAW_SIGNATURENS_HIST_SEQUENCE_PER_STREAM
Set up data capture. HTSetStructure NS_CAPTURE_SETUP
Start data capture (if selected).
—or—
HTSetCommand NS_CAPTURE_START
Start the histogram (if selected). HTSetCommand NS_HIST_START
Applies all stream configurations: Schedules the streams and VCs for transmission. It completes the configuration procedures.
HTSetCommand NS_COMMIT_CONFIG
Run the test. If a histogram test is selected, HGRun must be used.
Note: NS_COMMIT_CONFIG must be called before HTRun/HGRun.
HTRun/HGRun N/A
Stop data capture (if selected). HTSetCommand NS_CAPTURE_STOP
Retrieve test counters. HTGetCountersHTGetEnhancedCounters
HTGetStructure
N/AN/A
ETH_EXTENDED_COUNTER_INFOL2_READ_COUNTERSL2_READ_RATES
Table 13-2. Main Applicable Commands for Tests with ATM-345xA(s) Modules (continued)
Applicable Commands
What the Commands Do Original Function Message Function iType1/Notes
Chapter 13: ATM Testing – SmartBits 600x/6000xSet Up Tests with ATM-345xA(s) TeraMetrics Modules
236 | SmartLibrary Overview and Procedures
Retrieve stream counters. HTGetStructure NS_PER_STREAM_COUNTER_INFOAT_STREAM_TX_COUNTER_INFONS_PROTOCOL_COUNTER_INFONS_PROTOCOL_RATE_INFO
Retrieve ATM/SONET test counters. HTGetStructure AT_PORT_COUNTER_INFOAT_PORT_CLIP_COUNTER_INFOAT_VC_COUNTER_INFOAT_VC_CLIP_COUNTER_INFONS_SONET_COUNTER_INFO
Retrieve capture results (if selected). HTGetSTructure NS_CAPTURE_COUNT_INFONS_CAPTURE_DATA_INFONS_CAPTURE_STATS_INFO
Retrieve histogram results (if selected). HTGetStructure Various commands may be used:
L3_HIST_ACTIVE_TEST_INFONS_HIST_COMBO_PER_STREAM_INFONS_HIST_LATENCY_DIST_PER_STREAM_INFONS_HIST_LATENCY_OVER_TIME_INFONS_HIST_RAW_SIGNATURE_INFONS_HIST_SEQUENCE_PER_STREAM_INFO
Table 13-2. Main Applicable Commands for Tests with ATM-345xA(s) Modules (continued)
Applicable Commands
What the Commands Do Original Function Message Function iType1/Notes
Chapter 13: ATM Testing – SmartBits 600x/6000xSet Up Tests with ATM-345xA(s) TeraMetrics Modules
SmartLibrary Overview and Procedures | 237
Example of Setup Steps
Here is a basic setup procedure for testing using ATM-345xA(s) modules. It assumes that this is a first setup. It does not include all possible commands or actions.
Step 1 Reserve the port.
Step 2 Reset the port.
Step 3 Configure the port. Use HTSetStructure with AT_PORT_CONFIG to configure the port.
Note: Remember to turn on/off the port flag (ulFlags in ATPortConfig) to allow/disallow “bad” frame length for the latency measurement limitations.
Step 4 Configure the VCs. Use HTSetStructure with AT_VC_CREATE to create virtual connec-tions.
The valid VC index range is 0 to 8190; the maximum number of VCs that can be created on a port is 8191.
UseOriginal Function
WithMessage Function iType1 Description
HTSlotReserve N/A Reserve the module for use.
UseOriginal Function
WithMessage Function iType1 Description
HTResetPort N/A Reset the port.
UseOriginal Function
WithMessage Function iType1 Related Structure
HTSetStructure AT_PORT_CONFIG ATPortConfig
UseOriginal Function
WithMessage Function iType1 Related Structure
HTSetStructure AT_VC_CREATE ATVC
Chapter 13: ATM Testing – SmartBits 600x/6000xSet Up Tests with ATM-345xA(s) TeraMetrics Modules
238 | SmartLibrary Overview and Procedures
Step 5 Configure streams. You can create the following stream types: IP, UDP, TCP, ICMP, IPv6, UDP/IPv6, TCP/IPv6, ICMP/IPv6, SmartBits1, and SmartBits128.
a First, use one of the DEFINE or MOD commands to create the streams.
Note: You must set the right ucProtocolType in these structures based on the bound VC encapsulation type. For example, using SteamIP:
• Set STREAM_PROTOCOL_BRIDGED when the bound VC is Bridged (LLC Bridged or VCMux Bridged)
• Set STREAM_PROTOCOL_IP when the bound VC is not Bridged, and so on.The value of ucProtocolType determines whether the Ethernet (802.3) header is included in the protocol stack of the stream. The Ethernet header is included if STREAM_PROTOCOL_BRIDGED is used, and it is not included if STREAM_PROTOCOL_IP, STREAM_PROTOCOL_UDP, and so on, are used.
Also note the following:
• The maximum number of TX streams supported on ATM TeraMetrics modules depends on the encapsulation/protocol header length, that is:• For an LLC Routed IPv4 stream the length is 28, which is 8 (LLC Routed encap-
sulation length) + 20 (IPv4 header length)
1. Both the SmartBits and SmartBits128 stream types are raw streams you can customize.
Use Original Function with Message Function iType1 Related Structure
HTSetStructure L3_DEFINE_IP_STREAML3_DEFINE_UDP_STREAML3_DEFINE_TCP_STREAML3_DEFINE_ICMP_STREAML3_DEFINE_IPV6_STREAML3_DEFINE_UDP_IPV6_STREAML3_DEFINE_TCP_IPV6_STREAML3_DEFINE_ICMP_IPV6_STREAML3_DEFINE_SMARTBITS_STREAML3_DEFINE_SMARTBITS_128_STREAM
L3_MOD_IP_STREAML3_MOD_UDP_STREAML3_MOD_TCP_STREAML3_MOD_ICMP_STREAML3_MOD_IPV6_STREAML3_MOD_UDP_IPV6_STREAML3_MOD_TCP_IPV6_STREAML3_MOD_ICMP_IPV6_STREAML3_MOD_SMARTBITS_STREAML3_MOD_SMARTBITS_128_STREAM
StreamIP*StreamUDP*StreamTCP*StreamICMP*StreamIPv6*StreamUDPIPv6*StreamTCPIPv6*StreamICMPIPv6*StreamSmartBitsStreamSmartBits128
StreamIP*StreamUDP*StreamTCP*StreamICMP*StreamIPv6*StreamUDPIPv6*StreamTCPIPv6*StreamICMPIPv6*StreamSmartBitsStreamSmartBits128
* See Note below
Chapter 13: ATM Testing – SmartBits 600x/6000xSet Up Tests with ATM-345xA(s) TeraMetrics Modules
SmartLibrary Overview and Procedures | 239
• For an IPv6 TCP over MPLS stream (e.g. 11 labels), the length is 104, which is 0 (VCMux encapsulation length) + 44 (11 MPLS labels) + 40 (IPv6 header length) + 20 (TCP header length)
• 8191 streams are supported if the encapsulation/protocol header length is one cell long, 48 bytes or less.
• 5905 streams are supported if the encapsulation/protocol header length is two cells long, between 49 and 96 bytes.
• 4616 streams are supported if the encapsulation/protocol header length is three cells long, between 97 and 144 bytes.
• The encapsulation/protocol header length of all the streams supported by ATM Terametrics modules are within 3 cells (144 bytes).
• The maximum number of RX streams supported on the ATM Terametrics cards is 64K if using custom stream ID, or the Alternate Key/Hashing algorithm. Otherwise, 3171 RX streams are supported.
b Then use the Stream Extension command to set the frame rate for reach stream:
c (optional) Insert MPLS label in the stream:
Note: The MPLS stream should be bound to a VC of encapsulation type VCMux MPLS (AT_ENCAP_TYPE_VCMUX_MPLS).
Step 6 Bind the streams to the VCs.
Use HTSetStructure with one of the DEFINE or MOD commands for stream binding to associate streams with VCs.
Note: Any stream must be bound to one VC with the stream binding command before the Commit can be done to run the test.
Use Original Function with Message Function iType1 Related Structure
HTSetStructure L3_DEFINE_STREAM_EXTENSION L3StreamExtension
Use Original Function with Message Function iType1 Related Structure
HTSetStructure L3_DEFINE_MPLSL3_MOD_MPLS
NSMPLSListNSMPLSList
Use Original Function with Message Function iType1 Related Structure
HTSetStructure L3_DEFINE_STREAM_BINDINGL3_MOD_STREAM_BINDING
L3StreamBinding
Chapter 13: ATM Testing – SmartBits 600x/6000xSet Up Tests with ATM-345xA(s) TeraMetrics Modules
240 | SmartLibrary Overview and Procedures
Step 7 Start the capture, if selected.
Step 8 Commit the configuration.
Use the HTSetCommand with NS_COMMIT_CONFIG to apply all stream configurations. This command schedules the streams and VCs for transmission.
Note: NS_COMMIT_CONFIG is required before every test run (HTRun/HGRun). It applies all stream configurations; schedules the streams and VCs for transmission; and completes the configuration process.
Step 9 Run the test.
Use HTRun to transmit test traffic from an individual module. Or, use HGRun to start test traffic from a group of modules.
Step 10 Stop the capture, if selected.
End of Required Steps for Basic Setup
This completes the basic steps needed to transmit test traffic. The next section summarizes how you match the built stream with VCs of different encapsulations. If the stream and VC are mismatched, the NS_COMMIT_CONFIG command will fail and return an error.
Original Function Message Function iType1 Description
HTSetCommand NS_CAPTURE_START Clear the buffer and start the capture.
Use Original Function with Message Function iType1 Description
HTSetCommand NS_COMMIT_CONFIG Schedules the streams and VCs for transmission.
Use Original Function with Message Function iType1 Structure
HTRunHGRun
N/A Transmit test frames.
Original Function Message Function iType1 Description
HTSetCommand NS_CAPTURE_STOP Stop capture.
Chapter 13: ATM Testing – SmartBits 600x/6000xSet Up Tests with ATM-345xA(s) TeraMetrics Modules
SmartLibrary Overview and Procedures | 241
Matching Streams and VC Encapsulations
It is important to use the right encapsulation type for a stream’s protocol stack. The following lists show which protocol stacks (ATM + IPv4, ATM + MPLS + IPv6, and so on) can use which VC encapsulations.
The ucEncapType member, which specifies the type of encapsulation, is part of the ATVC structure.
The ucProtocolType member referred to in the lists is found in several stream structures. The stream structures that can be used with the following protocol stacks are:
• StreamIP
• StreamIPv6
• StreamTCP
• StreamTCPIPv6
• StreamUDP
• StreamUDPIPv6
• StreamICMP
• StreamICMPIPv6
IPv4 and IPv6 Protocol Stacks
ATM + IPv4 ucEncapType
Use one of the following:
• AT_ENCAP_TYPE_VCMUX_ROUTED• AT_ENCAP_TYPE_LLC_ROUTED
ucProtocolType
Use one of the following:
• STREAM_PROTOCOL_IP• STREAM_PROTOCOL_UDP• STREAM_PROTOCOL_TCP• STREAM_PROTOCOL_ICMP
ATM + ETH + IPv4
ucEncapTypeAT_ENCAP_TYPE_LLC_BRIDGED
ucProtocolTypeSTREAM_PROTOCOL_LLC_BRIDGED
Chapter 13: ATM Testing – SmartBits 600x/6000xSet Up Tests with ATM-345xA(s) TeraMetrics Modules
242 | SmartLibrary Overview and Procedures
ATM + MPLS + IPv4
ucEncapTypeAT_ENCAP_TYPE_VCMUX_MPLS
ucProtocolType
Use one of the following:
• STREAM_PROTOCOL_IP• STREAM_PROTOCOL_UDP• STREAM_PROTOCOL_TCP• STREAM_PROTOCOL_ICMP
iType1 Call to Insert MPLS Labels
Use one of the following:
• L3_DEFINE_MPLS• L3_MOD_MPLS
ATM + IPv6 ucEncapType
Use one of the following:
• AT_ENCAP_TYPE_VCMUX_ROUTED• AT_ENCAP_TYPE_LLC_ROUTED
ucProtocolType
Use one of the following:
• STREAM_PROTOCOL_IPV6• STREAM_PROTOCOL_UDP_IPV6• STREAM_PROTOCOL_TCP_IPV6• STREAM_PROTOCOL_ICMPV6
ATM + ETH + IPv6
ucEncapTypeAT_ENCAP_TYPE_LLC_BRIDGED
ucProtocolTypeSTREAM_PROTOCOL_LLC_BRIDGED
ATM + MPLS + IPv6
ucEncapTypeAT_ENCAP_TYPE_VCMUX_MPLS
ucProtocolType
Use one of the following:
• STREAM_PROTOCOL_IPV6• STREAM_PROTOCOL_UDP_IPV6• STREAM_PROTOCOL_TCP_IPV6• STREAM_PROTOCOL_ICMP_IPV6
Chapter 13: ATM Testing – SmartBits 600x/6000xSet Up Tests with ATM-345xA(s) TeraMetrics Modules
SmartLibrary Overview and Procedures | 243
iType1 call to insert MPLS labels
Use one of the following:
• L3_DEFINE_MPLS• L3_MOD_MPLS
Custom Protocol Stacks
All encapsulation types can be used with custom streams (SmartBits and SmartBits128). The protocol stack is always “NULL + SMB64/SMB128”, except that when the VC is of VCMUX_MPLS encapsulation type, the first word is interpreted as an MPLS label.
Notes: • To test MPLS with custom streams (SmartBits and SmartBits128), the MPLS labels should be configured as part of the custom stream. The L3_DEFINE_MPLS and L3_MOD_MPLS message functions are not applicable.
• No checking is done for VC encapsulation and stream protocol stack when the commit is performed. Instead, the following happens: If the VC is VCMUX_MPLS, the first word is interpreted as an MPLS label. Otherwise, the first word is the start of the SMB64/SMB128 protocol.
NULL + SMB64/SMB128
ucEncapType
Use one of the following:
• AT_ENCAP_TYPE_NULL• AT_ENCAP_TYPE_VCMUX_ROUTED• AT_ENCAP_TYPE_VCMUX_BRIDGED• AT_ENCAP_TYPE_LLC_ROUTED• AT_ENCAP_TYPE_LLC_BRIDGED
ucProtocolType STREAM_PROTOCOL_SMARTBITS
NULL+ MPLS + SMB64/SMB128
ucEncapType AT_ENCAP_TYPE_VCMUX_MPLS
ucProtocolType STREAM_PROTOCOL_SMARTBITS
The usefulness of your test, however, depends on getting test results. The following sections explain how to get test results, as well as SONET status information and alarms.
Chapter 13: ATM Testing – SmartBits 600x/6000xSet Up Tests with ATM-345xA(s) TeraMetrics Modules
244 | SmartLibrary Overview and Procedures
How to Get Status and Alarms Information
Use NS_SONET_COUNTER_INFO to get the SONET alarms and status information for ATM-345xA(s) modules.
Getting Test Results
Your test can provide three types of results. These are:– Counters– Captured data — or —– Histograms
Counters Counters are always available. You need not enable them or set them up explicitly. You can get counter information during the test or after it stops. See “How to Get Counter Information” below.
Captured data and histograms
You can also retrieve captured data or histograms, but not both in the same test. For these, you must specify the type of results desired, and you must enable the function. You set up data capture or histogram results before you start your test. You obtain either type of results after you run the test. See “How to Set Up Data Capture” on page 245 and “How to Set Up SmartMetrics Histograms” on page 248.
How to Get Counter Information
Use the following commands to get counters for the test.
Port Counters
Use Original Function with Message Function iType1 Related Structure
HTGetStructure NS_SONET_COUNTER_INFO NSSonetCounterInfo
Original Function Message Function iType1 Related Structure
HTGetCounters N/A N/A
HTGetEnhancedCounters N/A EnhancedCounterStructure
HTGetStructure AT_PORT_COUNTER_INFO ATPortCounterInfo
HTGetStructure AT_PORT_CLIP_COUNTER_INFO ATPortCLIPCounterInfo
Chapter 13: ATM Testing – SmartBits 600x/6000xSet Up Tests with ATM-345xA(s) TeraMetrics Modules
SmartLibrary Overview and Procedures | 245
VC Counters
Stream Counters
Layer 2 Counters
How to Set Up Data Capture
You can specify data capture for the receiving port.
Step 1 Enable capture on the VC.
Capture and transmit must be enabled on the VC that is to do capture. This setup is done during VC configuration, by enabling fields ucRxEnable and ucCaptureEnable (see page 237).
Step 2 Set the capture mode.
Use HTSetStructure with NS_CAPTURE_SETUP(NSCaptureSetup) to specify the capture mode, length, and event.
Original Function Message Function iType1 Related Structure
HTGetStructure AT_VC_COUNTER_INFO ATVCCounterInfo
HTGetStructure AT_VC_CLIP_COUNTER_INFO ATVCCLIPCounterInfo
Original Function Message Function iType1 Related Structure
HTGetStructure NS_PER_STREAM_COUNTER_INFO NSPerStreamCounterInfo
HTGetStructure AT_STREAM_TX_COUNTER_INFO ATStreamCounterInfo
HTGetStructure NS_PROTOCOL_COUNTER_INFO NSProtocolCounterInfo
HTGetStructure NS_PROTOCOL_RATE_INFO NSProtocolCounterInfo
Original Function Message Function iType1 Related Structure
HTGetStructure L2_READ_COUNTERS L2StatsInfo
HTGetStructure L2_READ_RATES L2RateInfo
HTGetStructure ETH_EXTENDED_COUNTER_INFO ETHExtendedCounterInfo
Original Function Message Function iType1 Related Structure
HTSetStructure NS_CAPTURE_SETUP NSCaptureSetup
Chapter 13: ATM Testing – SmartBits 600x/6000xSet Up Tests with ATM-345xA(s) TeraMetrics Modules
246 | SmartLibrary Overview and Procedures
Capture Mode. Valid options for NSCaptureSetup(ulCaptureMode) include:
Capture Events. Valid options for NSCaptureSetup(ulCaptureEvents) include the following:
Capture Length. Valid options for NSCaptureSetup(ulCaptureLength) include:
Capture Mode Description
CAPTURE_MODE_FILTER_ON_EVENTS Capture only packets with the specified event, such as packets with trigger.
CAPTURE_MODE_START_ON_EVENTS Capture all packets following the specified event. For example, begin capture when the first packet with a trigger is received, then capture all packets.
Capture Event Description
CAPTURE_EVENTS_RX_TRIGGER Capture all frames that contain receive trigger patterns. Note: The trigger pattern must be defined in the first cell (48 bytes) of the frame.
CAPTURE_EVENTS_ALL_FRAMES Capture all frames.
Capture Length Description
CAPTURE_LENGTH_ENTIRE_FRAME Capture complete frame.
CAPTURE_LENGTH_1ST_64_BYTES Capture only the first 64 bytes in the frame.
CAPTURE_LENGTH_LAST_64_BYTES Capture only the last 64 bytes in the frame.
CAPTURE_LENGTH_1ST_128_BYTES Capture only the first 128 bytes in the frame.
CAPTURE_LENGTH_LAST_128_BYTES Capture only the last 128 bytes in the frame.
CAPTURE_LENGTH_CUSTOM Capture only the first specified number bytes in the frame, set by uiCustomCaptureLength.
uiCustomCaptureLengthThis field specifies the number of bytes to capture. Because ATM-345xA(s) modules capture frames on cell boundaries, the capture slice count will be rounded up to the next cell boundary (48 bytes). For example, if 60 bytes are requested, 96 bytes will be captured and returned (using NS_CAPTURE_DATA_INFO).
Chapter 13: ATM Testing – SmartBits 600x/6000xSet Up Tests with ATM-345xA(s) TeraMetrics Modules
SmartLibrary Overview and Procedures | 247
Step 3 Start capture before you run the test. Stop capture when the test is complete.
Use NS_CAPTURE_START and NS_CAPTURE_STOP to start the capture (before starting the test) and to stop capture when the test is done.
Step 4 Get the captured data.
Use the following commands to get capture results.
Original Function Message Function iType1 Description
HTSetCommand NS_CAPTURE_START Start capture.
NS_CAPTURE_STOP Stop capture.
Original Function Message Function iType1 Related Structure Description
HTGetStructure NS_CAPTURE_COUNT_INFO NSCaptureCountInfo Find the number of frames in the buffer.
NS_CAPTURE_DATA_INFO NSCaptureDataInfo Get the captured frames.
NS_CAPTURE_STATS_INFO NSCaptureStatsInfo To get statistics about one or more captured frames.
Chapter 13: ATM Testing – SmartBits 600x/6000xSet Up Tests with ATM-345xA(s) TeraMetrics Modules
248 | SmartLibrary Overview and Procedures
How to Set Up SmartMetrics Histograms
Histograms provide in-depth test results, including sequence and latency information. Histogram information is gathered on the receiving card.
Step 1 Enable the histogram type.
Before you start the test, specify the type of histogram information you wish to be gathered.
To set up the histogram on the receiving port: The NS_HIST command must be called for the receiving port on which you with to enable the histogram. Use HTSetCommand with one of the iType1s listed below.
Original FunctionMessage Function iType1 /Related Structure Description
HTSetCommand NS_HIST_SEQUENCE_PER_STREAM(0) 64-bit histogram. Shows whether packets were dropped or received out of order.
HTSetStructure NS_HIST_LATENCY_OVER_TIME(NSHistLatencyOverTime)
64-bit Latency over Time histogram. Provides minimum, maximum, and average latency for all streams at specified intervals.
NS_HIST_LATENCY_DIST_PER_STREAM(NSHistLatencyDistPerStream)
64-bit Latency Distribution histogram. Defines the time interval ranges used in the Latency Distribution histogram—that is, sets forwarding delay as distributed over a series of time intervals.
NS_HIST_COMBO_PER_STREAM(NSHistComboPerStream)
64-bit Combination histogram.
This histogram tracks:– Minimum, maximum, and average latency per
stream.– Sequence tracking.– Latency distribution.
HTSetCommand NS_HIST_RAW_SIGNATURE(0) Shows packet sequence number, source VTE stream, destination VTE stream, and timestamp.
Chapter 13: ATM Testing – SmartBits 600x/6000xSet Up Tests with ATM-345xA(s) TeraMetrics Modules
SmartLibrary Overview and Procedures | 249
Step 2 Set Up Port Groups
When SmartMetrics results are desired, you must set up a port group, since histogram results require a group start. Use HGSetGroup and HGAddtoGroup to define the port group and to add ports to a group.
Step 3 Start the histogram.
Use the following command to clear existing histogram records and start the histogram test.
Step 4 Gather Histogram Information
After the test stops, use HTGetStructure with the iType1s listed below to collect histogram information.
Original Function Description
HGSetGroup Define a group of SmartBits ports.
HGAddtoGroup Add ports to the group. You control grouped ports by using the HG commands.
Original Function Message Function iType1 Related Structure
HTSetCommand NS_HIST_START N/A
Original FunctionMessage Function iType1 /Related Structure Description
HTGetStructure NS_HIST_ACTIVE_TEST_INFO(Layer3HistActiveTest)
Used to retrieve the total number of records generated by the active histogram on the specified port. Also reports which histogram is active.
NS_HIST_SEQUENCE_PER_STREAM_INFO(NSHistSequencePerStreamInfo)
Sequence tracing counts the number of framer per stream that are in-sequence or out-of-sequence. A separate record is generated for each test stream received by the specified port. Sequence is tracked using the Signature field embedded in each test frame.
NS_HIST_LATENCY_OVER_TIME_INFO(NSHistLatencyOverTimeInfo)
Provides the minimum, maximum, and average latency for all streams at specified intervals.
NS_HIST_LATENCY_DIST_PER_STREAM_INFO(NSHistLatencyDistPerStreamInfo)
Provides Latency Distribution information, tracking how many frames fall within a give latency range. There are 16 configurable ranges, in units of .1 microseconds.
Chapter 13: ATM Testing – SmartBits 600x/6000xSet Up Tests with ATM-345xA(s) TeraMetrics Modules
250 | SmartLibrary Overview and Procedures
HTGetStructure NS_HIST_COMBO_PER_STREAM_INFO(NSHistComboPerStreamInfo)
64-bit Combination histogram.
This histogram tracks:– Minimum, maximum, and average latency per
stream.– Sequence tracking.– Latency distribution.
One record is generated for each stream received. Statistics are tracked using the Signature field embedded within each test frame.
NS_HIST_RAW_SIGNATURE_INFO(NSHistRawSignatureInfo)
Shows packet sequence number, source VTE stream, destination VTE stream, and timestamp.
Original FunctionMessage Function iType1 /Related Structure Description
Chapter 13: ATM Testing – SmartBits 600x/6000xLatency Measurement Limitations
SmartLibrary Overview and Procedures | 251
Latency Measurement LimitationsFor some frame sizes, latency measurements in the ATM-345xA(s) modules will result in inaccurate values. This is because TeraMetrics cards make “last bit out to last bit in” latency measurements and, because of the AAL5 segmentation process, the end of the AAL5 frame payload (where the Signature timestamp field is located) may not necessarily be located in the last cell of the frame. For frame lengths that cause the Signature timestamp field (or a portion of the timestamp field) to be placed in the second-to-the-last cell of the frame (see Figure 13-1), the Signature timestamp will reflect the time that the last bit of the second-to-the-last cell went out, rather than the time that the last bit of the last cell of the AAL5 frame went out. The resulting latency measurement for these cases will be inaccurate.
As shown in Figure 13-1, this condition can occur every 15 out of 48 frame sizes—For example, frame sizes in the range 41-55, 89-103, or 137-151, and so on.
Figure 13-1. Latency Measurements with ATM-345xA(s) Modules
Continues –>
Chapter 13: ATM Testing – SmartBits 600x/6000xLatency Measurement Limitations
252 | SmartLibrary Overview and Procedures
To help compensate for this, a dual-state variable is implemented in the module, on a per-port basis. You can select one of these modes as part of port configuration (ulFlags with AT_PORT_CONFIG). The two options are:1 Reject “bad” frame sizes (AT_PORT_DEFAULT_FLAGS)
If you select this option (the default), stream configurations that contain frame sizes that will cause a bad measurement will be rejected. Encapsulation sizes will be taken into account in this algorithm. The reject will occur during the NS_COMMIT_CONFIG command.
2 Ignore the issue (AT_PORT_ALLOW_ALL_FRAME_SIZES)If you select this option, the streams will be committed with the configured value of frame size. This assumes that you are primarily interested in measuring throughput for this frame size and not in measuring the latency.
SmartLibrary Overview and Procedures | 253
Chapter 14
10/100 Mbps Ethernet Testing
This chapter provides step-by-step procedures you can use to set up Ethernet tests.
In this chapter...
• Set Tests with 10/100 Mbps Ethernet Cards . . . . 254
Chapter 14: 10/100 Mbps Ethernet TestingSet Tests with 10/100 Mbps Ethernet Cards
254 | SmartLibrary Overview and Procedures
Set Tests with 10/100 Mbps Ethernet CardsThis section explains how to set up tests for 10/100Mbps Ethernet SmartCards and modules.
Related Topics
For related information, see:
• Chapter 2, “SmartLibrary Basics” for information on how to set up SmartMetrics (Layer 3) tests.
• The Layer 2 Sample Code from the SmartLibrary directory on your computer. It illustrates how to use the Original Functions to set up Layer 2 tests.
Applicable Commands
Summary of commands
Table 14-1 is a summary of commands you can use in 10/100Mbps Ethernet tests. Not all commands are required. This list is an overview.
A basic setup See “Example of Setup Steps” on page 255 for a basic setup procedure, as well as optional commands and actions.
Table 14-1. Applicable Commands for 10/100Mbps Ethernet Tests
What the Commands Do
Applicable Commands
Original Function Message Function iType1 (or Notes)
Reset card to the default state. HTSetCommand ETH_RESET_PORT
Initialize counters. ETH_CLEAR_PORT
Set up the test parameters. HTSetStructure ETH_TRANSMIT
ETH_FILL_PATTERN
ETH_COLLISIONNote: Cannot be used with the ML-7710 SmartCard.
ETH_LATENCY
ETH_TRIGGER
(Optional) Set up port groups. HGSetGroupHGAddtoGroup
See “Example of Setup Steps” on page 255.
Continues –>
Chapter 14: 10/100 Mbps Ethernet TestingSet Tests with 10/100 Mbps Ethernet Cards
SmartLibrary Overview and Procedures | 255
Example of Setup Steps
Here is an example of how to set up 10/100Mbps Ethernet tests. It assumes no previous configuration. It shows selected commands, not all possible commands or actions.
Step 1 Reset the Card and Clear All Counters
Use HTSetCommand with ETH_RESET_PORT to set the card to a known, default state. Use ETH_CLEAR_PORT to clear all counters.
Continues –>
What the Commands Do
Applicable Commands
Original FunctionMessage Function iType1(or Notes)
Transmit test frames, then stop the test. HTRunHTStop
For single-port start/stop.
HGRunHGStepHGStop
For group start/stop.
Get test results. HTGetStructure ETH_COUNTER_INFO
ETH_ENHANCED_COUNTER_INFO
ETH_LATENCY_INFO
Table 14-1. Applicable Commands for 10/100Mbps Ethernet Tests (continued)
Optional/RelatedOptional or related commands and actions (if applicable) are shown in a shaded box. These actions are not required for a basic test setup.
Use: with Message Function iType1 Related Structure
HTSetCommand ETH_RESET_PORT None
ETH_CLEAR_PORT None
Chapter 14: 10/100 Mbps Ethernet TestingSet Tests with 10/100 Mbps Ethernet Cards
256 | SmartLibrary Overview and Procedures
Step 2 Set Up the Test Parameters
Use HTSetStructure with the iType1s listed below to define the test parameters.
Step 3 (Optional) Set Up Port Groups
To set up a port group, use HGSetGroup and HGAddtoGroup to define the port group and to add ports to the group.
Step 4 Send Test Traffic, Then Stop the Test
Use the HTRun or HGRun command to run the test.
If you run the test with continuous traffic, use HTStop or HGStop to stop the test.
UsewithMessage Function iType1 Related Structure Description
HTSetStructure ETH_TRANSMIT ETHTransmit Specify the basic transmit parameters for the test, including burst mode, duplex mode, number of frames, and VFDs.
ETH_FILL_PATTERN None Define the background fill pattern, using an array of unsigned characters.
ETH_COLLISION ETHCollision Specify the collision mode, offset, duration, and count.
Note: This command cannot be used with the ML-7710 SmartCard.
ETH_LATENCY ETHLatency Set up the card for latency measurements.
ETH_TRIGGER ETHTrigger Set up the triggers.
Use Description
HGSetGroup Define a group of SmartBits ports. Add ports to the group. You can control group ports by using the HG commands.
HGAddtoGroup
Use Description
HTRun/HTStop Transmit test frames, then stop the test (if running continuous traffic rather than step or burst mode).
HGRun/HGStep/HGStop
Chapter 14: 10/100 Mbps Ethernet TestingSet Tests with 10/100 Mbps Ethernet Cards
SmartLibrary Overview and Procedures | 257
End of Required Steps for Basic Setup
This completes the basic steps needed to transmit test traffic. The usefulness of your test, however, depends on getting test results.
See “Getting Test Results” below for the commands to get counter information on test traffic.
Getting Test Results
Your test provides counter information.
Note: For the steps to set up SmartMetrics tests with histogram results and data capture, see Chapter 18, “SmartMetrics/TeraMetrics Testing.”
How to Get Counter Information
Counters are always available. You do not need to enable or set up counters explicitly. You can get counter information during the test or after it stops.
Use HTGetStructure with one of the iType1s listed below to gather test results.
UsewithMessage Function iType1 Related Structure Description
HTGetStructure ETH_COUNTER_INFO ETHCounterInfo Get counter information.
ETH_ENHANCED_COUNTER_INFO
ETHEnhancedCounterInfo Get additional counter information.
ETH_LATENCY_INFO ETHLatencyInfo Get latency measurements.
258 | SmartLibrary Overview and Procedures
SmartLibrary Overview and Procedures | 259
Chapter 15
WAN (Frame Relay) Testing
This chapter provides step-by-step procedures you can use to set up tests with WAN SmartCards.
In this chapter...
• Set Up Tests with Channelized WAN Cards . . . . 260
• Set Up Tests for PPP over HDLC . . . . 280
• Set Up Tests with Fractional WAN Cards . . . . 283
• Set Up Tests for PPP over Frame Relay . . . . 290
Chapter 15: WAN (Frame Relay) TestingSet Up Tests with Channelized WAN Cards
260 | SmartLibrary Overview and Procedures
Set Up Tests with Channelized WAN CardsThis section provides an example of how to set up tests for frame relay streams on channelized WAN cards, including the following:
• WN-3441A (WAN T1, Frame Relay/PPP, channelized, 4-port, SmartMetrics)
• WN-3442A (WAN E1, Frame Relay/PPP, channelized, 4-port, SmartMetrics)
• WN-3445A (WAN DS3, Frame Relay/PPP, channelized, 4-port, SmartMetrics)
Applicable Commands
Table 15-1 on page 261 lists the commands that apply to tests for frame relay using the channelized WAN cards listed above. Not all commands are required. The list is an overview.
Four basic command actions
The commands can be grouped into four types. Each performs one of these actions:
• Configure (including delete)
• Control
• Get status
• Get statistics (including alarms)
A basic setup See “Example of Setup Steps” on page 264 for a basic setup procedure, as well as optional commands and actions.
Card-based commands
Some commands are card-based. With all card-based commands, you need not send the commands port by port (this applies to the WN-3441A and WN-3442A; the WN-3445A has one port). With commands that are not card-based, you must specify the port/line number when sending the command.
Table 15-1 on page 261 identifies which commands are card-based. It also notes specific card requirements (for example, some commands apply only to the WN-3445A).
Chapter 15: WAN (Frame Relay) TestingSet Up Tests with Channelized WAN Cards
SmartLibrary Overview and Procedures | 261
Table 15-1. Applicable Commands: Frame Relay Testing with Channelized WAN Cards
Applicable Commands
What the Commands Do Original Function Message Function iType1 Card-based?
Initiate the configuration procedure.
HTSetCommand WN_START_CFG Yes
Reset the card’s configuration.
HTSetCommand WN_T1E1_LINE_DEL_ALL Yes
WN_CHANNEL_DEL_ALL Yes
WN_PVC_DEL_ALL Yes
WN_STREAM_DEL_ALL Yes
WN_LMI_DEL_ALL Yes
WN_TRIGGER_DEL_ALL Yes
Configure the DS3 line(WN-3445A only)
HTSetStructure WN_DS3_LINE_CFG WN-3445Aonly
Configure the T1/E1 lines. HTSetStructure WN_T1E1_LINE_CFG No
Configure and control channels.
HTSetStructure WN_CHANNEL_PHYS_CFG
WN_CHANNEL_ATTRIB_CFG
WN_CHANNEL_CTRL
WN_CHANNEL_DEL
No
Configure and control the frame relay protocol.
HTSetStructure WN_PVC_CFG
WN_PVC_CTRL
WN_PVC_DEL
No
Configure and control the Link Management protocol.
HTSetStructure WN_LMI_CFG
WN_LMI_DEL
No
Chapter 15: WAN (Frame Relay) TestingSet Up Tests with Channelized WAN Cards
262 | SmartLibrary Overview and Procedures
Configure and control streams.
HTSetStructure L3_DEFINE_IP_STREAM
L3_DEFINE_UDP_STREAM
L3_DEFINE_SMARTBITS_STREAM
L3_MOD_IP_STREAM
L3_MOD_UDP_STREAM
L3_MOD_SMARTBITS_STREAM
Yes
WN_STREAM_EXT_CFG
WN_STREAM_CTRL
WN_STREAM_DEL
No
Configure a background fill pattern.
HTSetStructure WN_FILL_PATTERN Yes
Configure transmit/receive triggers.
HTSetStructure WN_TRIGGER_CFG
WN_TRIGGER_CTRL
WN_TRIGGER_DEL
No
Complete the configuration procedure.
HTSetCommand WN_COMMIT_CFG Yes
Clear port counters. HTClearPort — Yes
Enable the T1/E1 lines. HTSetStructure WN_T1E1_LINE_CTRL No
Enable the DS3 line(WN-3445A only)
HTSetStructure WN_DS3_LINE_CTRL WN-3445Aonly
Set up histograms.
— or —
HTSetStructure L3_HIST_V2_LATENCYL3_HIST_V2_LATENCY_PER_STREAML3_HIST_V2_LATENCY_DISTRIBUTIONL3_HIST_RAW_TAGSL3_HIST_SEQUENCE
No
Set up data capture. HTSetStructureHTSetCommand
NS_CAPTURE_SETUPNS_CAPTURE_START
No
Activate histograms.
— or —
Activate capture.
HTSetStructure WN_HIST_CTRLWN_HIST_CTRL_ALL
No
HTSetStructure WN_CAPTURE_CTRLWN_CAPTURE_CTRL_ALL
No
Table 15-1. Applicable Commands: Frame Relay Testing with Channelized WAN Cards (continued)
Applicable Commands
What the Commands Do Original Function Message Function iType1 Card-based?
Chapter 15: WAN (Frame Relay) TestingSet Up Tests with Channelized WAN Cards
SmartLibrary Overview and Procedures | 263
Verify line and channel status.
HTGetStructure WN_DS3_LINE_STATUS
WN_DS3_LINE_INFO
WN_T1E1_ALARM_COUNTER_INFO
WN_T1E1_LINE_STATUS
WN_CHANNEL_STATUS
WN_PVC_STATUS
—
Run the test. HTRun/HGRun — Yes
Retrieve test counters. HTGetStructure WN_PORT_INFO
WN_DS3_LINE_INFO
WN_T1E1_ALARM_COUNTER_INFO
WN_CHANNEL_INFO
WN_PVC_INFO
WN_LMI_INFO
—
Retrieve capture results.
— or —
Retrieve histogram results.
HTGetStructure NS_CAPTURE_COUNT_INFO
NS_CAPTURE_DATA_INFO
L3_CAPTURE_DETAIL_INFO
—
HTGetStructure L3_HIST_ACTIVE_TEST_INFO
L3_HIST_SEQUENCE_INFO
L3_HIST_RAW_TAGS_INFO
L3_HIST_V2_LATENCY_INFO
L3_HIST_V2_LATENCY_PER_STREAM_INFO
L3_HIST_LATENCY_DISTRIBUTION_INFO
—
Table 15-1. Applicable Commands: Frame Relay Testing with Channelized WAN Cards (continued)
Applicable Commands
What the Commands Do Original Function Message Function iType1 Card-based?
Chapter 15: WAN (Frame Relay) TestingSet Up Tests with Channelized WAN Cards
264 | SmartLibrary Overview and Procedures
Example of Setup Steps
Here is a basic setup procedure for frame relay testing. It assumes that this is a first setup. It does not include all possible commands or actions.
Step 1 Initiate the configuration procedure.
Use HTSetCommand with WN_START_CFG to stop test traffic and indicate that configuration is pending.
All test traffic stops when you send this command.
Step 2 Reset the card’s configuration.Clear the card’s configuration. The commands listed below remove the card’s existing configuration entirely.
Step 3 Configure the physical link.
Configure the physical link (SmartCard port). You use different commands, depending on card and port type.
Note: With the WN-3441A and WN-3342A, the T1/E1 line number is equivalent to the port number.
OptionalOptional commands and actions are shown in a shaded box. These actions are not required for a basic test setup.
All Cards
Use: with Message Function iType1 Related Structure
HTSetCommand WN_START_CFG None
Use with Message Function iType1 To Clear
HTSetCommand WN_T1E1_LINE_DEL_ALL T1/E1 lines
WN_CHANNEL_DEL_ALL Channels
WN_PVC_DEL_ALL PVCs
WN_LMI_DEL_ALL LMI
WN_STREAM_DEL_ALL Streams
WN_TRIGGER_DEL_ALL Triggers
Chapter 15: WAN (Frame Relay) TestingSet Up Tests with Channelized WAN Cards
SmartLibrary Overview and Procedures | 265
Important: With all three cards, it is important to keep the DS3 line and T1/E1 line(s) disabled until you complete the entire configuration. To do this, set ucActive to 0 in the related configuration structure. These structures are:
WN-3445A WNDS3LineCfgWN-3441A and WN-3442A WNT1E1LineCfg
Optionally, to disable a T1/E1 line, you can use WN_T1E1_LINE_CTRL, setting ucEnable to 0 in the WnT1E1LineCtrl structure.
WN-3445A:a. First configure the DS3 line.
b. Then configure the T1/E1 lines.
WN-3441A and WN-3442A: Configure the T1/E1 line.
Notes Line configurations cause the line to be restarted. The line is brought down for a short duration (much less than 1 second). If a line is already disabled, it remains disabled.
You can define up to:
• 24 x 28 channels in each DS3 line.
• 24 channels in each T1 line.
• 31 channels in each E1 line (the first DS0 is reserved for signaling).
Step 4 Configure the channels.
First configure the channels’ physical setup, such as channel number and time slots.
Then set up other attributes, including connection type (frame relay) and transmit mode.
Important: Be sure to enable each channel. To do this, set ucEnable to 1 in the WNChannelAttribCfg structure.
WN-3445A
Use: with Message Function iType1 Related Structure
HTSetStructure WN_DS3_LINE_CFG WNDS3LineCfg
Use: with Message Function iType1 Related Structure
HTSetStructure WN_T1E1_LINE_CFG WNT1E1LineCfg
WN-3441A and WN-3442A
Use: with Message Function iType1 Related Structure
HTSetStructure WN_T1E1_LINE_CFG WNT1E1LineCfg
Chapter 15: WAN (Frame Relay) TestingSet Up Tests with Channelized WAN Cards
266 | SmartLibrary Overview and Procedures
a. First set up the physical configuration.
b. Then set up channel attributes.
Step 5 Configure the frame relay PVCs.
Notes A channel must exist before you can configure a PVC.
Be sure to enable each PVC by setting ucPVCEnable to 1.
WN-3441A and WN-3442A: With these cards, DLCI is a card-based value: It is global across the card. You may not have duplicate DLCIs in one card, even if they apply to different ports.
DLCIs 0 and 1023 are reserved and should not be used, unless appropriate for your test.
If the DLCI exists, the PVC is overwritten with the new configuration.
When you modify a PVC configuration, test traffic is stopped immediately. Adding a PVC configuration does not stop test traffic.
A new PVC is not used until test traffic is restarted after an WN_COMMIT_CFG command.
All Cards
Use: with Message Function iType1 Related Structure
HTSetStructure WN_CHANNEL_PHYS_CFG WNChannelPhysCfg
Use: with Message Function iType1 Related Structure
HTSetStructure WN_CHANNEL_ATTRIB_CFG WNChannelAttribCfg
OptionalRelated commands include:HTSetStructure with WN_CHANNEL_CTRL(WNChannelCtrl) to enable and disable channels.HTSetStructure with WN_CHANNEL_DEL(WNChannelDel) to delete channels.
All Cards
Use: with Message Function iType1 Related Structure
HTSetStructure WN_PVC_CFG WNPVCCfg
OptionalRelated commands include:HTSetStructure with WN_PVC_CTRL(WNPVCCtrl) to enable and disable PVCs.HTSetStructure with WN_PVC_DEL(WNPVCDel) to delete PVCs.
Chapter 15: WAN (Frame Relay) TestingSet Up Tests with Channelized WAN Cards
SmartLibrary Overview and Procedures | 267
Step 6 Configure the Link Management Protocol (LMI).
By default, no LMI is configured. You can use this default setting. To operate with a specified LMI type, however, you must set it explicitly.
Notes You can define one LMI per channel. Each T1 or E1 line can include multiple channels. Each channel, in turn, can contain multiple PVCs. Each of these channel can have its own assigned LMI.
You can change the LMI configuration on the fly. However, it is important to restart the physical link. This ensures that the LMI is synchronized with the DUT. See Step 10 on page 269.
You can change the Link Integrity Verification timer (NT3) and events counter n393/nN3) on the fly. Changing the UNI mode or Link Management Protocol (LMP) will reset the LMI.
Step 7 Configure streams.
You can create three streams types: IP, UDP, and SmartBits (a raw stream you can customize).
a. First use the one of the MOD commands to create streams
It is simplest to create streams by using one of the MOD commands shown below. This is because this command form includes stream index 0 (the first stream). In contrast, the DEFINE command form (such as L3_DEFINE_IP_STREAM) starts with index 1. (Note also that the L3_DEFINE commands clear all existing streams each time they are called, setting up a new stream configuration.)
New streams are not included in test traffic until the test traffic is restarted after an WN_COMMIT_CFG command.
All Cards
Use: with Message Function iType1 Related Structure
HTSetStructure WN_LMI_CFG WNLMICfg
OptionalRelated commands include:HTSetStructure with WN_LMI_DEL(WNLMIDel) to delete an LMI.
Chapter 15: WAN (Frame Relay) TestingSet Up Tests with Channelized WAN Cards
268 | SmartLibrary Overview and Procedures
Notes The channel must exist before you can add streams using the following commands.
b. Then configure WAN-related stream characteristics
Some stream characteristics apply directly to WAN SmartCards. After creating a stream, use WN_STREAM_EXT_CFG to set these parameter values.
The stream and channel must already exist to use this command.
Important: The WN_STREAM_EXT_CFG command maps the stream to the line and channel. Be sure to specify this mapping. In addition, you must set a valid frame rate.
Step 8 Configure a background fill pattern (optional).
All Cards
Use: with Message Function iType1 Related Structure
HTSetStructure L3_MOD_IP_STREAM StreamIP
L3_MOD_UDP_STREAM StreamUDP
L3_MOD_SMARTBITS_STREAM StreamSmartBits
All Cards
Use: with Message Function iType1 Related Structure
HTSetStructure WN_STREAM_EXT_CFG WNStreamExtCfg
OptionalRelated commands include:HTSetStructure with WN_STREAM_CTRL(WNStreamCtrl) to enable and disable streams.HTSetStructure with WN_STREAM_DEL(WNStreamDel) to delete streams.
All Cards
Use: with Message Function iType1 Related Structure
HTSetStructure WN_FILL_PATTERN UChar
OptionalYou can define a background fill pattern to be applied to the payload portion of each frame.If defined, the background pattern applies to all ports on the card.This step is not required.
Chapter 15: WAN (Frame Relay) TestingSet Up Tests with Channelized WAN Cards
SmartLibrary Overview and Procedures | 269
Step 9 Configure channel-based transmit and receive triggers (optional).
Notes The offset is specified in bytes from the start of the frame header.
Mask values determine which bits are compared in the pattern against the frame. If a mask bit is set, then the corresponding bit in the pattern is tested. If a bit is zero, then the corresponding bit is ignored.
The “match” field (ucCompCombo) causes the trigger to be fired on matching pattern.
Step 10 Enable the line.Enable the DS3 and/or T1/E1 line(s). You use different commands, depending on card type (see below).
Important: In the related structure, you must set ucEnable to 1 to enable the line.
WN-3445A:a. First enable the T1 or E1 lines.
b. Then enable the DS3 line.
All Cards
Use: with Message Function iType1 Related Structure
HTSetStructure WN_TRIGGER_CFG WNTriggerCfg
OptionalYou can set up triggers. These cause the card to count frames that contain the defined trigger pattern. You can define a trigger in the both the transmit and receive direction.This step is not required.
If you define triggers, the following commands also may be used:WN_TRIGGER_CTRL(WNTriggerCtrl) to enable and disable triggers.WN_TRIGGER_DEL(WNTriggerDel) to delete a trigger.
WN-3445A
Use: with Message Function iType1 Related Structure
HTSetStructure WN_T1E1_LINE_CTRL WNT1E1LineCtrl
Use: with Message Function iType1 Related Structure
HTSetStructure WN_DS3_LINE_CTRL WNDS3LineCtrl
Chapter 15: WAN (Frame Relay) TestingSet Up Tests with Channelized WAN Cards
270 | SmartLibrary Overview and Procedures
WN-3441A and WN-3442A: Enable the T1 or E1 line.
Step 11 Commit the configuration.
Notes This command instructs the card to apply the new configuration and perform all the processing necessary to make the card ready for operation.The command ensures that all configuration data sent to the card becomes active at the same time and that all internal data structures are made consistent.
Test traffic is stopped immediately, if it is already running.
Step 12 Verify line and channel status.
The line is not active until it is clear of alarms. You can verify this in one of two ways:
• Wait for the card to complete processing. Plan to allow 30 to 60 seconds; the needed time varies, depending on the number of streams. If you have configured a large number of channels on the WN-3445A (the maximum is 672), it may require several minutes for all channels to come up.
• Poll for line status. To do this, use the following commands:
DS3 status
T1/E1 status
WN-3441A and WN-3442A
Use: with Message Function iType1 Related Structure
HTSetStructure WN_T1E1_LINE_CTRL WNT1E1LineCtrl
All Cards
Use: with Message Function iType1 Related Structure
HTSetCommand WN_COMMIT_CFG None
WN-3445A
Use: with Message Function iType1 Related Structure
HTGetStructure WN_DS3_LINE_STATUS WNDS3LineStatus
All Cards
Use: with Message Function iType1 Related Structure
HTGetStructure WN_T1E1_LINE_STATUS WNT1E1LineStatus
Chapter 15: WAN (Frame Relay) TestingSet Up Tests with Channelized WAN Cards
SmartLibrary Overview and Procedures | 271
Channel status Similarly, you cannot send traffic until channels are active. You can poll for the status of each channel by using the following command:
Step 13 Clear the port counters.
HTClearPort clears all previous port counters. This ensures new test results.
Step 14 Run the test.
Use the HTRun command to transmit test traffic from an individual card.
Use HGRun to start test traffic from a group of cards.
End of Required Steps for Basic Setup
This completes the basic steps needed to transmit test traffic. The usefulness of your test, however, depends on getting test results. The section “Getting Test Results” on page 273 describes how you can use counters, capture, or histograms to measure test traffic.
Getting Status and Alarms
See “How to Get Status and Alarms Information” on page 272 for a summary of the commands you can use to get status and alarms information.
All Cards
Use: with Message Function iType1 Related Structure
HTGetStructure WN_CHANNEL_STATUS WNChannelStatus
All Cards
Use: with Message Function iType1 Related Structure
HTClearPort None None
Chapter 15: WAN (Frame Relay) TestingSet Up Tests with Channelized WAN Cards
272 | SmartLibrary Overview and Procedures
How to Get Status and Alarms Information
As noted in Step 10 above, the DS3 or T1/E1 line is not active until it is clear of alarms. Similarly, you cannot send test traffic until channels are active.
The following commands can be used to get alarms and status information for the DS3 line, T1/E1 lines, channels, PVCs, and LMIs.
DS3 line status and alarms
T1/E1 line status and alarms
Channel status
PVC status
LMI status
WN-3445A
Use: with Message Function iType1 Related Structure
HTGetStructure WN_DS3_LINE_STATUS WNDS3LineStatus
WN_DS3_LINE_INFO WNDS3LineInfo
All Cards
Use: with Message Function iType1 Related Structure
HTGetStructure WN_T1E1_LINE_STATUS WNT1E1LineStatus
WN_T1E1_ALARM_COUNTER_INFO
WNT1E1AlarmCounterInfo
All Cards
Use: with Message Function iType1 Related Structure
HTGetStructure WN_CHANNEL_STATUS WNChannelStatus
All Cards
Use: with Message Function iType1 Related Structure
HTGetStructure WN_PVC_STATUS WNPVCStatus
All Cards
Use: with Message Function iType1 Related Structure
HTGetStructure WN_LMI_INFO WNLMIInfo
Chapter 15: WAN (Frame Relay) TestingSet Up Tests with Channelized WAN Cards
SmartLibrary Overview and Procedures | 273
Getting Test Results
You can set up your test to provide three types of results. These are:– Counters– Captured data — or —– Histograms
Counters Counters are always available. You need not enable them or set them up explicitly. You can get counter information during the test or after it stops.
Captured data and histograms
You can also retrieve captured data or histograms, but not both in the same test. For these, you must specify the type of results desired, and you must enable the function. You set up data capture or histogram results before you start your test. You obtain either type of results after you run the test.
How to Get Counter Information
Use the following commands to get counters from the test.
Port counters
DS3 alarms counters
T1/E1 alarms counters
All Cards
Use: with Message Function iType1 Related Structure
HTGetStructure WN_PORT_INFO WNPortInfo
WN-3445A
Use: with Message Function iType1 Related Structure
HTGetStructure WN_DS3_LINE_INFO WNDS3LineInfo
All Cards
Use: with Message Function iType1 Related Structure
HTGetStructure WN_T1E1_ALARM_COUNTER_INFO
WNT1E1AlarmCounterInfo
Chapter 15: WAN (Frame Relay) TestingSet Up Tests with Channelized WAN Cards
274 | SmartLibrary Overview and Procedures
Channel counters
PVC counters
LMI counters
All Cards
Use: with Message Function iType1 Related Structure
HTGetStructure WN_CHANNEL_INFO WNChannelInfo
All Cards
Use: with Message Function iType1 Related Structure
HTGetStructure WN_PVC_INFO WNPVCInfo
All Cards
Use: with Message Function iType1 Related Structure
HTGetStructure WN_LMI_INFO WNLMIInfo
Chapter 15: WAN (Frame Relay) TestingSet Up Tests with Channelized WAN Cards
SmartLibrary Overview and Procedures | 275
How to Set Up Data Capture
You can specify data capture for the receiving port.
Data capture includes the first 512 bytes of each frame, including CRC.
Step 1 Set up data capture.
You must set up capture for each line
The NS_CAPTURE_SETUP command must be called for each T1 or E1 line on which you wish capture to take place. The same type of capture must be used with all lines on one card (see the sections on capture mode, length, and events below). Use iType2 to identify the T1/E1 line.
How to set the capture mode
Use the NSCaptureSetup structure to specify the capture mode, length, and event (see below).
Capture Mode
Valid options for NSCaptureSetup(ulCaptureMode) include:
All Cards
Use: with Message Function iType1 Related Structure
HTSetStructure NS_CAPTURE_SETUP NSCaptureSetup
Capture Mode Description
CAPTURE_MODE_FILTER_ON_EVENTS Capture only packets with the specified event, such as CRC errors, undersize packets, or oversize packets.
CAPTURE_MODE_START_ON_EVENTS Capture all packets following the specified event. For example, begin capture when the first packet with a CRC error is received, then capture all packets.
CAPTURE_MODE_STOP_ON_EVENTS Capture all packets until the specified event. For example, capture all packets until the first packet with a CRC error is received, then stop the capture.
Chapter 15: WAN (Frame Relay) TestingSet Up Tests with Channelized WAN Cards
276 | SmartLibrary Overview and Procedures
Capture Length
Valid options for NSCaptureSetup(ulCaptureLength) include:
Capture Events
Valid options for NSCaptureSetup(ulCaptureEvents) include:
Step 2 Activate the capture.
Use the following commands to activate capture, either on a specified T1/E1 line or on all lines.
Capture Length Description
CAPTURE_LENGTH_ENTIRE_FRAME Capture complete frame.
CAPTURE_LENGTH_1ST_64_BYTES Capture only the first 64 bytes in the frame.
CAPTURE_LENGTH_LAST_64_BYTES Capture only the last 64 bytes in the frame.
Capture Event Description
CAPTURE_EVENTS_CRC_ERRORS Capture all frames with CRC errors.
CAPTURE_EVENTS_UNDERSIZE Capture all undersize frames.
CAPTURE_EVENTS_OVERSIZE Capture all oversize frames.
CAPTURE_EVENTS_RX_TRIGGER Capture all frames with Rx trigger.
CAPTURE_EVENTS_ABORT Capture all aborted frames.
CAPTURE_EVENTS_ALGNMENT_ERRORS Capture all non-aligned frames.
CAPTURE_EVENTS_ALL_FRAMES Capture all frames.
All Cards
Use: with Message Function iType1 Related Structure Description
HTSetStructure WN_CAPTURE_CTRL WNFeatureCtrl Activate capture on a specified T1/E1 line.
WN_CAPTURE_CTRL_ALL WNFeatureCtrlAll Activate capture on all T1/E1 lines.
Chapter 15: WAN (Frame Relay) TestingSet Up Tests with Channelized WAN Cards
SmartLibrary Overview and Procedures | 277
Step 3 Get the captured data.
Use the following commands to get the captured data.
To get the count of captured frames
To get the captured data
To get details of the captured packets
All Cards
Use: with Message Function iType1 Related Structure
HTGetStructure NS_CAPTURE_COUNT_INFO NSCaptureCountInfo
All Cards
Use: with Message Function iType1 Related Structure
HTGetStructure NS_CAPTURE_DATA_INFO NSCaptureDataInfo
All Cards
Use: with Message Function iType1 Related Structure
HTGetStructure L3_CAPTURE_DETAIL_INFO Layer3CaptureDetailinfo
Chapter 15: WAN (Frame Relay) TestingSet Up Tests with Channelized WAN Cards
278 | SmartLibrary Overview and Procedures
How to Set Up SmartMetrics Histograms
Histograms provide in-depth test results, including sequence and latency information.
Histogram information is gathered on the receiving card.
These commands apply to all three WAN cards.
Step 1 Enable the histogram type.
Before you start the test, specify the type of histogram information you wish to be gathered.
You must set up the histogram for each line
The L3_HIST_ command must be called for each T1 or E1 line on which you wish to enable the histogram. You must use the same histogram type for all lines on the card.
Use HTSetCommand with one of the iType1s listed below.
Continues –>
Message Function iType1 Histogram Type Description
L3_HIST_V2_LATENCYwith Layer3HistLatency
32-bit Latency Sets 32-bit latency histogram results.
L3_HIST_V2_LATENCY_PER_STREAMwith Layer3HistDistribution
32-bit Latency per Stream Sets 32-bit latency per-stream histogram results.
L3_HIST_V2_LATENCY_DISTRIBUTIONwith Layer3TrackingDistribution
32-bit Latency Distribution Sets forwarding delay as distributed over a series of time intervals (buckets).
L3_HIST_RAW_TAGS(0) Signature Information Shows packet sequence number, source VTE stream, destination VTE stream, and timestamp.
L3_HIST_SEQUENCE(0) Sequence Shows whether packets were dropped or received out of order.
NS_HIST_MULTICAST_LATENCY_PER_STREAM
IGMP Multicast Group Latency per Stream
Sets 32-bit latency per-stream histogram results for IGMP ports.
Chapter 15: WAN (Frame Relay) TestingSet Up Tests with Channelized WAN Cards
SmartLibrary Overview and Procedures | 279
Step 2 Activate the histogram.
Use the following commands to activate histograms, either on a specified T1/E1 line or on all lines.
Step 3 Gather histogram information.
After the test stops, use HTGetStructure with the iType1s listed below to collect histogram information.
All Cards
Use: with Message Function iType1 Related Structure Description
HTSetStructure WN_HIST_CTRL WNFeatureCtrl Activate histograms on a specified T1/E1 line.
WN_HIST_CTRL_ALL WNFeatureCtrlAll Activate histograms on allT1/E1 lines.
Message Function iType1 Related Structure Description
L3_HIST_ACTIVE_TEST_INFO Layer3HistActiveTest Shows selected histogram type.
L3_HIST_SEQUENCE_INFO Layer3SequenceInfo Shows sequence information.
L3_HIST_RAW_TAGS_INFO Layer3HistTagsInfo Shows raw tags (signature) information.
L3_HIST_V2_LATENCY_INFO Layer3LongLatencyInfo Shows 32-bit Latency over Time histogram.
L3_HIST_V2_LATENCY_PER_STREAM_INFO
Layer3StreamLongLatencyInfo Shows 32-bit Latency per Stream histogram.
L3_HIST_LATENCY_DISTRIBUTION_INFO
Layer3StreamDistributionInfo Full Latency Distribution histogram results: How many frames fall within specified intervals.
NS_HIST_MULTICAST_LATENCY_PER_STREAM_INFO
NSHistMulticastLatencyPerStreamInfo
Shows 32-bit Latency per Stream histogram for IGMP ports.
Chapter 15: WAN (Frame Relay) TestingSet Up Tests for PPP over HDLC
280 | SmartLibrary Overview and Procedures
Set Up Tests for PPP over HDLCYou can set up your test so that channels carry PPP connections instead of frame relay PVCs.
To do this, use the steps below in place of Step 5 and Step 6 in the procedure for frame relay (see “Set Up Tests with Channelized WAN Cards” on page 260).
All other steps—to set up lines, channels, and streams—remain the same, except for the commands to get counters.
PPP statistics and status
To get PPP counters, you use PPP_STATS_INFO and PPP_STATUS_INFO. To set up data capture or histograms, use the same steps described for frame relay (see “How to Get Status and Alarms Information” on page 272).
Applicable Commands
Table 15-2 lists the commands that apply to tests for PPP over HDLC.
See “Example of Setup Steps” on page 281 for a basic setup procedure.
Table 15-2. Applicable Commands: Tests for PPP over HDLC
Applicable Commands
What the Commands Do Original Function Message Function iType1
Configure the PPP connection. HTSetStructure PPP_CONFIG
Set up PPP handshaking and establish the PPP connection.
HTSetStructure PPP_SET_CTRL
Verify PPP session status. HTGetStructure PPP_STATUS_INFO
Send test traffic. HTRun/HGRun —
Retrieve test results. HTGetStructure PPP_STATS_INFO
Chapter 15: WAN (Frame Relay) TestingSet Up Tests for PPP over HDLC
SmartLibrary Overview and Procedures | 281
Example of Setup Steps
Step 1 Begin the general WAN setup procedure.
Perform Step 1 through Step 4 in the main procedure for WAN tests (see “Set Up Tests with Channelized WAN Cards” on page 260).
Then use the following steps in place of Step 4 and Step 5 in that procedure.
Step 2 Configure the PPP connection.
Use HTSetStructure with PPP_CONFIG to configure the PPP connection.
Step 3 Set up PPP handshaking and establish the PPP connection.
Use HTSetStructure with PPP_SET_CTRL to set up PPP handshaking and to establish the connection.
Step 4 Verify the PPP session status.
Before sending traffic, verify that the IP/NCP session is established. Sending IP traffic before the session is established can adversely affect the DUT and the SmartBits.
Step 5 Run the test.
Use the HTRun command to transmit test traffic from an individual card.
Use HGRun to start test traffic from a group of cards.
All Cards
Use: with Message Function iType1 Related Structure
HTSetStructure PPP_CONFIG PPPParamCfg
All Cards
Use: with Message Function iType1 Related Structure
HTSetStructure PPP_SET_CTRL PPPControlCfg
All Cards
Use: with Message Function iType1 Related Structure
HTGetStructure PPP_STATUS_INFO PPPStatusInfo
Chapter 15: WAN (Frame Relay) TestingSet Up Tests for PPP over HDLC
282 | SmartLibrary Overview and Procedures
Step 6 Get test counters.
For PPP connections, use the following command to get test statistics.
Capture and histograms
See “How to Set Up Data Capture” on page 275 and “How to Set Up SmartMetrics Histograms” on page 278 for the steps to set up data capture or histogram results.
All Cards
Use: with Message Function iType1 Related Structure
HTGetStructure PPP_STATS_INFO PPPStatsInfo
Chapter 15: WAN (Frame Relay) TestingSet Up Tests with Fractional WAN Cards
SmartLibrary Overview and Procedures | 283
Set Up Tests with Fractional WAN CardsThis section provides an example of how to set up tests for frame relay streams on non-channelized, fractional WAN cards, including the following:
• WN-3405 (WAN V.35, 6/8 Mbps, Frame Relay/PPP, 1-port, SmartMetrics)
• WN-3415 (WAN T1/FT1, Frame Relay/PPP, 1-port, SmartMetrics)
• WN-3420A (WAN E1/FT1, Frame Relay/PPP, 1-port, SmartMetrics)
Summary of Steps
Table 15-3 lists the commands that apply to tests for frame relay using the fractional WAN cards listed above. Not all commands are required. The list is an overview.
Four basic command actions
The commands can be grouped into four types. Each performs one of these actions:
• Configure (including delete)
• Control
• Get status
• Get statistics (including alarms)
A basic setup See “Example of Setup Steps” on page 285 for a basic setup procedure, as well as optional commands and actions.
is a summary of the steps to set up frame relay streams. See “Example of Setup Steps” on page 285 for further information.
Table 15-3. Applicable Commands: How to Set Up Frame Relay Tests
Step Description Original FunctionMessage Function iType1(or Notes)
1 Initiate the configuration procedure. HTSetCommand FR_SET_START_CONFIG
2 Configure the link and management protocols.
HTSetStructure FR_SET_PROTO_STACK
FR_LINEFR_T1E1_LINE
FR_CARD_CFG
FR_LMI
3 Configure PVCs. HTSetCommand FR_PVC_DELETE_ALL
HTSetStructure FR_PVC
Chapter 15: WAN (Frame Relay) TestingSet Up Tests with Fractional WAN Cards
284 | SmartLibrary Overview and Procedures
4 Configure streams. HTSetStructure FR_STREAM_DELETE_ALL
FR_DEFINE_<n>_STREAM
FR_PVC_STREAM_MAP_CONFIG
FR_STRM_CTRL
FR_FILL_PATTERN
5 Configure global transmit/receive triggers.
HTSetStructure FR_TRIGGER
6 Enable the desired histogram. HTSetStructure FR_HIST_<n>
7 Enable the port. HTSetCommand FR_ENABLE_PORT
8 Send the configuration to the card. HTSetCommand FR_COMMIT_CONFIG
9 Clear the port counters. HTSetCommand FR_CLEAR_PORT
10 Run the test. HTRun/HGRun See Detailed Steps below.
11 Retrieve counters or histogram results.
Various See Detailed Steps below.
Table 15-3. Applicable Commands: How to Set Up Frame Relay Tests (continued)
Step Description Original FunctionMessage Function iType1(or Notes)
Chapter 15: WAN (Frame Relay) TestingSet Up Tests with Fractional WAN Cards
SmartLibrary Overview and Procedures | 285
Example of Setup Steps
Step 1 Initiate the Configuration ProcedureHere is a more detailed description of the summary presented in Table 15-4. To initiate the configuration procedure, use the HTSetCommand with FR_SET_START_CONFIG. This command and FR_COMMIT_CFG ensure that all configuration data sent to the card becomes active at the same time and that all internal data structures are made consistent. FR_SET_START_CONFIG stops test traffic and indicates that configuration is pending.
Step 2 Define the Physical ConfigurationConfigure the SmartCard and the physical link.• Use FR_LINE (FRLineCfg) to define the operating characteristics of a V.35 link.• Use FR_T1E1LINE (FRT1E1LineCfg) for a T1/E1 link.
The related data structures define the physical interface appearance (DTE or DCE), encoding method, clock source and polarity, line speed, and related values.
Note: 1. Line configurations cause the line to be restarted. The line is brought down for a short duration (much less than 1 second). If the line is already disabled, it remains disabled.
2. In software Release 3.09 and later, an interface with physical DTE interface appearance must use external clocking. An interface with a physical DCE interface appearance must use internal clocking.
Step 3 Configure Protocol and LMI
Define the card protocol, encapsulation method, and the LMI.(Optional) Use FR_LMI (FRLmiCfg) to configure the Local Management Interface. You can change the LMI configuration “on the fly.” Use caution, however: the DTE and DCE can get out of sequence. If this should occur, reset the link.
You can change the Link Integrity Verification timer (NT3) and events counter (n393/nN3) on the fly. Changing the UNI mode or Link Management Protocol (LMP) will reset the LMI.
Original Function Message Function iType1 Related Structure
HTSetStructure FR_CARD_CFG FRCardCfg
FR_LINE FRLineCfg
FR_T1E1LINE FRT1E1LineCfg
Original Function Message Function iType1 Related Structure
HTSetStructure FR_SET_PROTO_STACK FRCardProtoCfgParmType
FR_LMI FRLMICfg
Chapter 15: WAN (Frame Relay) TestingSet Up Tests with Fractional WAN Cards
286 | SmartLibrary Overview and Procedures
Step 4 Configure Virtual Circuits
Delete Existing PVCs. Before configuring new PVCs, use FR_PVC_DELETE_ALL to remove all old PVCs. All test traffic is stopped automatically.
Then use FR_PVC (FRPVCTableEntry) to add or modify a PVC configuration. If ulDLCI exists, the PVC is overwritten with the new configuration.
When you modify a PVC configuration, test traffic is stopped immediately. In contrast, adding a PVC configuration does not stop test traffic. The new PVC is not used until test traffic is restarted after an FR_COMMIT_CFG command.
When you add a PVC configuration, it appears differently depending on the UNI mode, as shown below. The link status is not affected.
Step 5 Configure Streams
Delete Existing Streams. Before configuring a new stream setup, use FR_STREAM_DELETE_ALL to remove all old (existing) streams. All test traffic is stopped automatically.
Configure New Streams. Use FR_DEFINE_<n>_STREAM to add or modify a stream configuration, where x identifies the stream type (see below). Test traffic will continue. Some stream parameters, such as changes in protocol type, do not go into effect until test traffic is restarted again. New streams are not included in test traffic until the test traffic is restarted after an FR_COMMIT_CFG command.
Possible stream types are:
Original Function Message Function iType1 Related Structure
HTSetCommand FR_PVC_DELETE_ALL None
FR_PVC FRPvcTableEntry
UNI Mode PVC Appears As
DCE New, Inactive
DTE Active
Disabled Configured
Original Function Message Function iType1 Related Structure
HTSetCommand FR_STREAM_DELETE_ALL None
HTSetStructure FR_DEFINE_<n>_STREAMS FRPvcStrmMapCfg
Chapter 15: WAN (Frame Relay) TestingSet Up Tests with Fractional WAN Cards
SmartLibrary Overview and Procedures | 287
Configure Per-Stream Parameters. Use FR_PVC_STREAM_MAP_CFG (FRPvcStrmMapCfg) to configure stream parameters related to the WAN.
The FRPvcStrmMapCfg structure determines such values as:
• Length of the global background fill.
• FCS and ABORT error insertion.
• FECN, BECN, DE and CR bit in the Q.922 header for frame relay.
• RFC 1490 encapsulation type.
Control Streams. Use FR_STRM_CTRL (FRStreamControl) to modify one or more fields of a stream—for example, to enable and disable the stream or generate errors
Set the Global Background Fill Pattern. Use FR_FILL_PATTERN (0) to configure the global background fill pattern of streams.
Configure Global Transmit and Receive Triggers Use FR_TRIGGER (FRTriggerCfg) to define the conditions that count as a trigger event. The offset is specified in bytes from the start of the frame header. Mask values determine which bits are compared in the pattern against the frame. If a mask bit is set, then the corresponding bit in the pattern is tested. If a bit is zero, then the corresponding bit is ignored. The match field causes the trigger to be fired on matching pattern.
Note: In software Release 3.09 and later, the direction control (ucDirection) has no effect. The trigger pattern is used for both incoming and outgoing frames. Changes in trigger configuration are effective immediately.
Step 6 Configure SmartMetrics (Histograms)
Use FR_HIST_<n> to enable the type of histogram information you wish to gather in the test, where n identifies the histogram type. Histogram information is gathered on the receiving card.
The histogram type may be one of the following:
Message Function iType1 Stream Type
FR_DEFINE_SMARTBITS_STREAM Raw stream.
FR_DEFINE_IP_STREAM IP
FR_DEFINE_UDP_STREAM UDP
Chapter 15: WAN (Frame Relay) TestingSet Up Tests with Fractional WAN Cards
288 | SmartLibrary Overview and Procedures
Step 7 Enable the Port
Use FR_ENABLE_PORT (FREnablePort) to enable the WAN port.
Step 8 Commit the Configuration
Use FR_COMMIT_CFG (FRCommitCfg) to instruct the intended card to commit (apply) the new configuration and perform all the processing necessary to make the card ready for operation. Test traffic is stopped immediately if it is already running.
Step 9 Clear Port Counters
Use FR_CLEAR_PORT (FRClearPort) to clear all previous port counters, to ensure new test results.
Step 10 Run the Test
Use the HTRun command to transmit test traffic from an individual card. Use HGRun to start test traffic from a group of cards.
Step 11 Get Test Results and Histogram Information
To collect test results and histogram information, use HTGetStructure with the commands listed below.
Message Function iType1 Histogram Type Description
FR_HIST_SEQUENCE Sequence Shows whether packets were dropped or received out of order.
FR_HIST_LATENCY_DISTRIBUTION Latency Distribution Shows forwarding delay as distributed over a series of time intervals (“buckets”).
FR_HIST_RAW_TAGS Signature Information Shows packet sequence number, source VTE stream, destination VTE stream, and timestamp.
FR_HIST_V2_LATENCY Latency Shows latency histogram results.
FR_HIST_V2_LATENCY_PER_STREAM Latency per Stream Shows latency per-stream histogram results.
Message Function iType1 Description
FR_CARD_VERSION_INFO Card firmware version: Returns revision information for the firmware and diagnostic/identification information for the hardware.
FR_DEFINED_STREAM_COUNT_INFO Number of defined streams.
FR_HIST_ACTIVE_TEST_INFO Shows selected histogram type.
FR_HIST_LATENCY_DISTRIBUTION_INFO Latency Distribution results: How many frames fall within specified intervals.
FR_HIST_SEQUENCE_INFO Sequence information.
FR_HIST_V2_LATENCY_INFO Latency over time histogram.
Chapter 15: WAN (Frame Relay) TestingSet Up Tests with Fractional WAN Cards
SmartLibrary Overview and Procedures | 289
FR_HIST_V2_LATENCY_PER_STREAM_INFO Latency per Stream histogram.
FR_IP_STREAM_INFO IP stream configuration information.
FR_LINK_INFO Link statistics counters.
FR_LINK_STATUS_INFO Link status information.
FR_LMI_INFO LMP statistics counters.
FR_PVC_INFO Per-PVC statistics counters.
FR_PVC_STATUS_INFO Status information for all 1024 PVCs.
FR_SMARTBITS_STREAM_INFO Raw stream configuration information.
FR_T1E1_LINE_INFO T1/E1 physical layer information.
Message Function iType1 Description
Chapter 15: WAN (Frame Relay) TestingSet Up Tests for PPP over Frame Relay
290 | SmartLibrary Overview and Procedures
Set Up Tests for PPP over Frame RelayUse the following steps to set up tests for PPP over frame relay using the WAN SmartCards.
Summary of Steps
Table 15-4 is a summary of steps. See “Detailed Steps” below for further information.
Detailed Steps
Here is a more detailed description of the summary presented in Table 15-4.Step 1 Set the Card for PPP over Frame Relay
Use HTSetStructure with FR_SET_PROTO_STACK to define the card protocol as PPP.
Step 2 Configure the PPP Connection
Use HTSetStructure with PPP_CONFIG to configure the PPP connection.
Table 15-4. Summary: How to Set Up PPP over Frame Relay Tests
Step Description Original FunctionMessage Function iType1(or Notes)
1 Set the card for PPP over frame relay.
HTSetStructure FR_SET_PROTO_STACK
2 Configure the PPP connection. HTSetStructure PPP_CONFIG
3 Set up PPP handshaking and establish the PPP connection.
HTSetStructure PPP_SET_CTRL
4 Send traffic. HTRun/HGRun See Detailed Steps below.
5 Retrieve test results. HTGetStructure PPP_STATUS_INFO-or-PPP_STATS_INFO
Original Function Message Function iType1 Related Structure
HTSetStructure FR_SET_PROTO_STACK FRCardProtocolCfg
Original Function Message Function iType1 Related Structure
HTSetStructure PPP_CONFIG PPPParamCfg
Chapter 15: WAN (Frame Relay) TestingSet Up Tests for PPP over Frame Relay
SmartLibrary Overview and Procedures | 291
Step 3 Set Up PPP Handshaking and Establish the PPP Connection
Use HTSetStructure with PPP_SET_CTRL to set up PPP handshaking and to establish the connection
Step 4 Send Test Traffic
Use the HTRun command to start test traffic from an individual card. Use HGRun to start test traffic from a group of cards.
Step 5 Get Test Results
Use HTGetStructure with one of the iType1 commands listed below to retrieve PPP status and statistics information.
Original Function Message Function iType1 Related Structure
HTSetStructure PPP_SET_CTRL PPPControlCfg
Message Function iType1 Description
PPP_STATUS_INFO Obtain status information on the PPP connection, such as LCP state, IPCP state, MRU, and MTU.
PPP_STATS_INFO Obtain PPP statistics, such as number of LCP messages sent and PAP/CHAP authentication exchanges.
292 | SmartLibrary Overview and Procedures
SmartLibrary Overview and Procedures | 293
Chapter 16
100 Mbps Fast Ethernet Testing
This chapter provides step-by-step procedures you can use to set up Fast Ethernet tests.
In this chapter...
• Set Up Tests With Fast Ethernet Cards . . . . 294
Chapter 16: 100 Mbps Fast Ethernet TestingSet Up Tests With Fast Ethernet Cards
294 | SmartLibrary Overview and Procedures
Set Up Tests With Fast Ethernet CardsFor tests with Fast Ethernet cards, you use the FST Message Function commands and a subset of the ETH Message Function commands.For related information, see:• Setting up Ethernet SmartMetrics Streams in Chapter 18, “SmartMetrics/TeraMetrics
Testing.”
• The Layer 2 Sample Code from the SmartLibrary directory on your computer. It illustrates how to use the Original Functions to set up tests.
Applicable CommandsTable 16-1 is a summary of commands you can use to set up your test. Not all commands are required. This list is an overview.
A basic setup See “Example of Setup Steps” on page 295 for a basic setup procedure, as well as optional commands and actions.
Table 16-1. Applicable Commands for Fast Ethernet Tests
Applicable Commands
What the Commands Do Original Function Message Function iType1/Notes
Reset card to the default state. HTSetCommand ETH_RESET_PORT
Initialize counters. ETH_CLEAR_PORT
Set up the test parameters. HTSetStructure ETH_TRANSMIT
ETH_FILL_PATTERN
ETH_COLLISION
ETH_LATENCY
ETH_TRIGGER
FST_ALTERNATE_TX
FST_CAPTURE_PARAMS
FST_CONTROL_AUX
FST_VLAN
(Optional) Set up port groups. HGSetGroupHGAddtoGroup
See “Example of Setup Steps” on page 295
Continues –>
Chapter 16: 100 Mbps Fast Ethernet TestingSet Up Tests With Fast Ethernet Cards
SmartLibrary Overview and Procedures | 295
Example of Setup Steps
Here is an example of how to set up your test. It assumes no previous configuration. It shows selected commands, not all possible commands or actions.
Step 1 Reset the card and clear all counters
Use HTSetCommand with ETH_RESET_PORT to set the card to a known, default state. Use ETH_CLEAR_PORT to clear all counters.
Applicable Commands
What the Commands Do Original Function Message Function iType1/Notes
Transmit test frames, then stop the test. HTRunHTStop
For single-port start/stop.
HGRunHGStepHGStop
For group start/stop.
Get test results. HTGetStructure ETH_COUNTER_INFO
ETH_FIND_MII_ADDR_INFO
ETH_ENHANCED_COUNTER_INFO
ETH_LATENCY_INFO
FST_CAPTURE_COUNT_INFO
FST_CAPTURE_DATA_INFO
FST_CAPTURE_INFO
Table 16-1. Applicable Commands for Fast Ethernet Tests
Optional/RelatedOptional or related commands and actions (if applicable) are shown in a shaded box. These actions are not required for a basic test setup.
Use Original Function with Message Function iType1 Structure
HTSetCommand ETH_RESET_PORT None
ETH_CLEAR_PORT None
Chapter 16: 100 Mbps Fast Ethernet TestingSet Up Tests With Fast Ethernet Cards
296 | SmartLibrary Overview and Procedures
Step 2 Set up the test parameters
Use HTSetStructure with the iTypes below to specify the test parameters.
Step 3 (Optional) Set up port groups
To set up a port group, use HGSetGroup and HGAddtoGroup to define the port group and to add ports to a group.
Step 4 Send test traffic, then stop the test
Use the HTRun or HGRun command to run the test.
If you run the test with continuous traffic, use HTStop or HGStop to stop the test.
Original Function Message Function iType1 Related Structure Description
HTSetStructure ETH_TRANSMIT ETHTransmit Specify the basic transmit parameters for the test, including burst mode, duplex mode, number of frames, and VFDs.
ETH_FILL_PATTERN None Define the background fill pattern, using an array of unsigned characters.
ETH_COLLISION ETHCollision Specify the collision mode, offset, duration, and count.
ETH_LATENCY ETHLatency Set up the card for latency measurements.
ETH_TRIGGER ETHTrigger Set up the triggers.
FST_ALTERNATE_TX FSTAlternateTx Set up the alternate transmit stream.
FST_CAPTURE_PARAMS FSTCaptureParams Define the capture filters and controls.
Start and stop capture.
FST_CONTROL_AUX FSTControlAux Set the preamble length and define flow control.
FST_VLAN FSTVLAN Enable VLAN tag information.
Original Function Description
HGSetGroupHGAddtoGroup
Define a group of SmartBits ports. Add ports to the group. You can control group ports by using the HG commands.
Original Function Description
HTRun/HTStop Transmit test frames, then stop the test (if running continuous traffic rather than step or burst mode).
HGRun/HGStep/HGStop
Chapter 16: 100 Mbps Fast Ethernet TestingSet Up Tests With Fast Ethernet Cards
SmartLibrary Overview and Procedures | 297
End of Required Steps for Basic Setup
This completes the basic steps needed to transmit test traffic. The usefulness of your test, however, depends on getting test results. See “Getting Test Results” on page 297 for the steps to use counters, capture, or histograms to measure test traffic.
Getting Test Results
Your test can provide results in two forms:– Counters, including latency measurements– Captured data
Counters Counters are always available. You need not enable or set up counters explicitly. You can get counter information during the test or after it stops.
Data capture You can also retrieve captured data if you set up the capture engine when configuring your test. For data capture, you must specify the type of results desired, and you must enable the function. You must set up data capture before you start your test. You obtain results after you run the test.
How to Get Counter and Latency Information
Use HTGetStructure with the iType1s listed below to get test counters, including latency measurements.
Original Function Message Function iType1 Related Structure Description
HTSetStructure ETH_COUNTER_INFO ETHCounterInfo Get counter information.
ETH_ENHANCED_COUNTER_INFO
ETHEnhancedCounterInfo Get additional counter information.
ETH_LATENCY_INFO ETHLatencyInfo Get latency measurements.
Chapter 16: 100 Mbps Fast Ethernet TestingSet Up Tests With Fast Ethernet Cards
298 | SmartLibrary Overview and Procedures
How to Set Up Data Capture
Use the following steps to set up data capture.
Step 1 Set up the capture parameters.
Use HTSetStructure with the FST_CAPTURE_PARAMS to define the capture filters and controls.
Step 2 Start the capture, then stop it.
Use the ucStartStop element in the FSTCaptureParams structure to start and stop data capture.
Step 3 Get the captured data.
Original Function Message Function iType1 Related Structure
HTSetStructure FST_CAPTURE_PARAMS FSTCaptureParams
Original Function Message Function iType1 Description
HTSetStructure FST_CAPTURE_PARAMS FSTCaptureParams
Use the ucStartStop element to start and stop capture.
Message Function iType1 Related Structure Description
HTSetStructure FST_CAPTURE_COUNT_INFO FSTCaptureCountInfo Get the number of frames captured.
FST_CAPTURE_DATA_INFO FSTCaptureDataInfo Get captured frame data.
FST_CAPTURE_INFO FSTCaptureInfo Get information about the captured frames.
SmartLibrary Overview and Procedures | 299
Chapter 17
Gigabit Ethernet Testing
This chapter provides step-by-step procedures you can use to set up Gigabit Ethernet tests in the Traditional mode.
Note: There is a different procedure to set up SmartMetrics tests with Gigabit cards. See Chapter 18, “SmartMetrics/TeraMetrics Testing.”
In this chapter...
• Set Up Traditional Gigabit Ethernet Tests . . . . 300
Chapter 17: Gigabit Ethernet TestingSet Up Traditional Gigabit Ethernet Tests
300 | SmartLibrary Overview and Procedures
Set Up Traditional Gigabit Ethernet TestsThis section explains how to set up Gigabit Ethernet tests in the Traditional mode. Traditional mode refers to a test with a single stream plus an alternate stream.
With a few exceptions, these steps can be applied to any Gigabit-capable card or module. The important exceptions are as follows:
• Different commands may be used to get test results (see Table 17-1 on page 302 and the “Example of Setup Steps” on page 303).
• With the GX-1420B, you can use additional functions that cannot be used with other Gigabit modules (see “When Using the GX-1420B” below).
Related Topics
See the following for related information.
• “When Using the GX-1420B” below.
• “Set Up Tests for LAN-3710A 10GbE Modules” on page 369.
• The Gigabit Sample Code from the SmartLibrary directory on your computer. It illustrates how to use the Original Functions to set up Traditional (single-stream) tests. (All Original Functions are documented in the SmartLibrary Command Reference.)
When Using the GX-1420B
Observe the following important guidelines for tests with this card.
SmartBits 2000 Installation Guidelines
! Caution: When installing GX-1420B SmartCards in a SmartBits 2000 chassis, take care to observe the following guidelines on power-consumption issues. Failure to observe these cautions can result in blown fuses in the SmartBits 2000 chassis.
• A maximum of eight (8) GX-1420B SmartCards may be installed in a SmartBits 2000. This will populate 16 of the chassis’s card slots.
• The remaining four card slots should be covered with blank panels. This helps to maintain proper air flow through the chassis.
• When using fewer than eight GX-1420B SmartCards in a SmartBits 2000, you can populate the remaining empty card slots with other card types, as follows:For every GX-1420B card less than the recommended maximum of eight, you can substitute:• One GX-1405B/BS or AT-9xxx SmartCard — or —• Two SX-xxxx/ML-xxxx, WAN-xxxx SmartCards
Chapter 17: Gigabit Ethernet TestingSet Up Traditional Gigabit Ethernet Tests
SmartLibrary Overview and Procedures | 301
ETH Functions Used with the GX-1420B
Five ETH functions may be used with the GX-1420B. Aside from this difference, you can use the steps described in the following pages with the GX-1420B.
The five ETH functions are summarized below. They are described in detail in Chapter 14, “10/100 Mbps Ethernet Testing.”
Note: No FST functions are used with the GX-1420B, even though it can be set up for Fast Ethernet (100Mbps) tests. The ETH_SET_SPEED function sets the port speed.
ETH Message Function iType1 Description
ETH_PROTOCOL_PARAMETERS Set up Layer 3 parameters.
ETH_SET_SPEED Specify the transmission speed (either 100Mbps or 1000Mbps).
ETH_VLAN Clear the Set VLAN characteristics (if desired).
ETH_EXTENDED_CARD_INFO Get additional card information.
ETH_PROTOCOL_PARAMETERS_INFO Get information on Layer 3 parameters.
Chapter 17: Gigabit Ethernet TestingSet Up Traditional Gigabit Ethernet Tests
302 | SmartLibrary Overview and Procedures
Applicable Commands
Table 17-1 is a summary of commands you can use. Not all commands are required. This list is an overview.
A basic setup See “Example of Setup Steps” on page 303 for a basic setup procedure.
Table 17-1. Applicable Commands for Traditional Gigabit Ethernet Tests
Applicable Commands
What the Commands Do Original Function Message Function iType1/Notes
Reset card to the default state. HTResetPort See “Example of Setup Steps” on page 303.
Clear counters. HTClearPort See “Example of Setup Steps” on page 303.
Set up negotiation parameters. HTSetSpeed For copper-interface cards/modules.
HTWriteMII For copper-interface cards/modules.
HTSetStructure
For fiber-interface cards/modules.
GIG_STRUC_AUTO_FIBER_NEGOTIATE
Set up the test parameters. HTSetStructure GIG_STRUC_TX
GIG_STRUC_FILL_PATTERN
GIG_STRUC_VFD3
GIG_STRUC_ALT_TX
GIG_STRUC_TRIGGER
GIG_STRUC_CAPTURE_SETUP
(Optional) Set up port groups. HGSetGroupHGAddtoGroup
See “Example of Setup Steps” on page 303.
Transmit test frames, then stop the test.
HTRunHTStop
For single-port start/stop.
HGRunHGStepHGStop
For group start/stop.
Continues –>
Chapter 17: Gigabit Ethernet TestingSet Up Traditional Gigabit Ethernet Tests
SmartLibrary Overview and Procedures | 303
Example of Setup Steps
Here is an example of how to set up your test. It assumes no previous configuration. It shows selected commands, not all possible commands or actions.
Step 1 Reset the Card and Clear All Counters
Use HTResetPort to set the card to a known, default state.
Use HTClearPort to clear all counters.
Applicable Commands
What the Commands Do Original Function Message Function iType1/Notes
Get test results:
GX-1405B/BSGX-1420BLAN-3200A/AS
HTGetStructure GIG_STRUC_CAP_COUNT_INFO
GIG_STRUC_CAP_DATA_INFO
GIG_STRUC_CAP_INFO
GIG_STRUC_COUNTER_INFO
GIG_STRUC_RATE_INFO
Get capture results:
LAN-3201B/CLAN-3300A and LAN-3301ALAN-3310A and LAN-3311A
HTGetStructure NS_CAPTURE_DATA_INFO
NS_CAPTURE_COUNT_INFO
Table 17-1. Applicable Commands for Traditional Gigabit Ethernet Tests (continued)
Optional/RelatedOptional or related commands and actions (if applicable) are shown in a shaded box. These actions are not required for a basic test setup.
Original Function Description
HTResetPort Reset the card or module to a default state.
HTClearPort Clear the port counters.
Chapter 17: Gigabit Ethernet TestingSet Up Traditional Gigabit Ethernet Tests
304 | SmartLibrary Overview and Procedures
Step 2 Set Up Negotiation Parameters
Configure the port speed.
Set up auto negotiation or fiber negotiation, as appropriate for the interface type.
Step 3 Set Up the Test Parameters
Configure the frame template, triggers, and other parameters.
Step 4 (Optional) Set Up Port Groups
Optionally, set up a port group.
Use HGSetGroup to define a port group.
Use HGAddtoGroup to add ports to a group.
Original Function Message Function iType1 Related Structure Description
HTSetSpeed — — Set the port speed.
HTWriteMII — — Copper interface cards and modules: GX-1420B, LAN-3300A, LAN-3301A.
Set up auto negotiation.
HTSetStructure GIG_STRUC_AUTO_FIBER_NEGOTIATE
GIGAutoFiberNegotiate Fiber interface modules:LAN-3200A/AS, LAN-3201B/C,LAN-3310A, LAN-3311A.
Set up AutoFiber Negotiation.
Original Function Message Function iType1 Related Structure Description
HTSetStructure GIG_STRUC_TX GIGTransmit Define the basic parameters for the card, including VFD1 and VFD2.
GIG_STRUC_ALT_TX GIGAltTransmit Enable alternate and periodic frames and PAUSE frame recognition.
GIG_STRUC_TRIGGER GIGTrigger Set up triggers.
GIG_STRUC_VFD None Set up the VFD3 fields.
GIG_STRUC_FILL_ PATTERN UChar Set up the background fill pattern.
Original Function Description
HGSetGroupHGAddtoGroup
Define a group of SmartBits ports. Add ports to the group. You can control group ports by using the HG commands.
Chapter 17: Gigabit Ethernet TestingSet Up Traditional Gigabit Ethernet Tests
SmartLibrary Overview and Procedures | 305
Step 5 Send Test Traffic, Then Stop the Test
Use HTRun or HGRun to run the test.
If you run the test with continuous traffic, use HTStop or HGStop to stop the test.
Getting Test Results
Your test can provide results in two forms:– Counters– Captured data
Counters Counters are always available. You need not enable or set up counters explicitly. You can get counter information during the test or after it stops.
Data capture You can also retrieve captured data if you set up the capture engine when configuring your test. For data capture, you must specify the type of results desired, and you must enable the function. You must set up data capture before you start your test. You obtain results after you run the test.
How to Get Counter Information
GX-1405B/BS, GX-1420B, LAN-3200A/AS
With these cards and modules, use HTGetStructure with the iType1s listed below to get the test counters.
Original Function Description
HTRun/HTStop Transmit test frames. Stop the test, if running continuous traffic rather than step or burst mode.
HGRun/HGStep/HGStop
Original Function Message Function iType1 Related Structure Description
HTGetStructure
GX-1405B/BSGX-1420BLAN-3200A/AS
GIG_COUNTER_INFO GIGCounterInfo Get counter information for the card or module.
GIG_STRUC_RATE _INFO GIGRateInfo Get rate information.
Chapter 17: Gigabit Ethernet TestingSet Up Traditional Gigabit Ethernet Tests
306 | SmartLibrary Overview and Procedures
How to Set Up Data Capture
Use the following steps to set up data capture.
Step 1 Set up the capture parameters.
Use HTSetStructure with GIG_STRUC_CAPTURE_SETUP (GigCaptureSetup) to specify the capture parameters.
Use the GigCaptureSetup structure to specify:
• When capture should start and stop (ucStartStopOnConditionMode).
• What events should trigger capture (ucFilterMode).
• The length of the captured data.
Step 2 Start the capture, then stop it.
Use the ucStartStop element in the GIGCaptureSetup structure to start and stop data capture.
Step 3a Get capture results (GX-1405B/BS, GX-1420B, LAN-3200A/AS)
With these cards, use the commands below to get the captured data. (See Step 3b for other Gigabit cards.)
Original Function Message Function iType1 Related Structure
HTSetStructure GIG_STRUC_CAPTURE _SETUP GIGCaptureSetup
Original Function Message Function iType1 Related Structure
HTSetStructure GIG_STRUC_CAPTURE _SETUP GIGCaptureSetup
Original Function Message Function iType1 Related Structure Description
HTGetStructure
GX-1405B/BSGX-1420BLAN-3200A/AS
GIG_STRUC_CAP_COUNT_INFO
GIGCaptureCountInfo Get the number of captured frames.
GIG_STRUC_CAP_DATA_INFO GIGCaptureDataInfo Get the data of one captured frame.
GIG_STRUC_CAP_INFO GIGCaptureInfo Get information about a range of captured frames.
Chapter 17: Gigabit Ethernet TestingSet Up Traditional Gigabit Ethernet Tests
SmartLibrary Overview and Procedures | 307
Step 3b Get capture results (LAN-3201B/C, LAN-3300A/3301A, LAN-3310A/3311A)
Use HTGetStructure with NS_CAPTURE_COUNT_INFO to find the number of frames in the buffer.
Use HTGetStructure with NS_CAPTURE_DATA_INFO to get the captured frames.
Original Function Message Function iType1 Related Structure Description
HTGetStructure
LAN-3201B/CLAN-3300A and LAN-3301ALAN-3310A and LAN-3311A
NS_CAPTURE_COUNT_ INFO NSCaptureCountInfo Get the number of captured frames.
NS_CAPTURE_DATA_INFO NSCaptureData Get the frame’s captured data.
308 | SmartLibrary Overview and Procedures
SmartLibrary Overview and Procedures | 309
Chapter 18
SmartMetrics/TeraMetrics Testing
This chapter provides step-by-step procedures you can use to set up Ethernet tests using the SmartMetrics and TeraMetrics card families.
Note: For a detailed discussion on creating streams, refer to Chapter 4, “Traffic Rates and Patterns.”
In this chapter...
• Set Up Ethernet SmartMetrics Streams . . . . 310
• Using the New Stream Configuration Commands . . . . 319
• Set Up SmartMetrics Tests on TeraMetrics-based Modules . . . . 329
• Test with IPv6 Streams on TeraMetrics Modules . . . . 343
• Set Up IPv6 Neighbor Discovery . . . . 357
• Test with IPv6 Over IPv4 Tunneled Streams . . . . 363
• Set Up Tests for LAN-3710A 10GbE Modules . . . . 369
• Set Up Alternate Key on TeraMetrics Modules . . . . 379
• Set Up SmartMetrics Tests with the LAN-3201B/C . . . . 385
• Set Up Tests with the ML-5710A . . . . 393
• Set Up DHCP Streams . . . . 397
• Set Up Stream Grouping . . . . 402
• Set Up PPP Over Ethernet (PPPoE) . . . . 408
• Getting Real-Time Statistics with LAN TeraMetrics . . . . 411
• Getting Enhanced Real-Time Statistics with TeraMetrics XD/XFP/XLW Modules . . . . 419
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up Ethernet SmartMetrics Streams
310 | SmartLibrary Overview and Procedures
Set Up Ethernet SmartMetrics StreamsThis section explains how to configure and manipulate SmartMetrics streams, and how to set up histogram results. You can use these steps with the following SmartMetrics cards and modules:
Note: You can find additional information on histograms in Chapter 5, “Histogram Results.” For a detailed discussion on creating streams, refer to Chapter 4, “Traffic Rates and Patterns.”
Applicable Commands
Table 18-1 on page 311 is a summary of commands you can use. Not all commands are required. This list is an overview.
A basic setup See “Example of Setup Steps” on page 312 for a basic setup procedure, as well as optional commands and actions.
SmartCard/Module Description
SmartBits Chassis
200/2000 600x/6000x
ML-5710A 10Base-T Ethernet/USB, 2-port, SmartMetrics
ML-7710 10/100Base-TX Ethernet, 1-port, SmartMetrics
ML-7711ML-7711s
100Base-FX Ethernet, 1-port, multi-mode, 1300nm, SmartMetrics100Base-FX Ethernet, 1-port, single mode, 1310nm, SmartMetrics
LAN-3101A/BLAN-3102ALAN-3111ALAN-3111AS
10/100Base-T Ethernet, 6-port, SmartMetrics10/100Base-T Ethernet, 6-port, SmartMetrics100Base-FX Ethernet, 6-port, multi-mode, 1300nm, SmartMetrics100Base-FX Ethernet, 6-port, single mode, 1310nm, SmartMetrics
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up Ethernet SmartMetrics Streams
SmartLibrary Overview and Procedures | 311
Table 18-1. Applicable Commands: Ethernet SmartMetrics Streams
Applicable Commands
What the Commands Do Original Function Message Function iType1/Notes
Reset card to the default state.
HTResetPort See “Example of Setup Steps” on page 332.
Clear counters. HTClearPort See “Example of Setup Steps” on page 332.
Set up streams. HTSetStructure L3_DEFINE_<n>_STREAML3_DEFINE_<n>_STREAM_EXTENSIONL3_DEFINE_MULTI_<n>_STREAML3_DEFINE_MULTI_<n>_STREAM_EXTENSIONL3_MOD_<n>_STREAM
Specify SmartMetrics (histogram) results.
—or—
HTSetCommand NS_HIST_COMBO_PER_STREAMNS_HIST_LATENCY_OVER_TIMENS_HIST_RAW_SIGNATURENS_HIST_SEQUENCE_PER_STREAMNS_HIST_LATENCY_DIST_PER_STREAM
Set up data capture. HTSetStructure NS_CAPTURE_SETUP
Set up port groups. HGSetGroupHGAddtoGroup
See “Example of Setup Steps” on page 332.
Specify other transmit parameters.
HTTransmitModeHTGapHTFillPatternHTBurstCountHTBurstGap
See “Example of Setup Steps” on page 332.
Transmit test frames, then stop the test.
HTRunHTStop
For single-port start/stop.
HGRunHGStepHGStop
For group start/stop.
Get histogram results.
— or —
HTGetStructure
— or —
NS_HIST_COMBO_PER_STREAM_INFONS_HIST_LATENCY_OVER_TIME_INFONS_HIST_RAW_SIGNATURE_INFONS_HIST_SEQUENCE_PER_STREAM_INFONS_HIST_LATENCY_DIST_PER_STREAM_INFO
Get capture results. HTGetStructure NS_CAPTURE_COUNT_INFONS_CAPTURE_DATA_INFONS_CAPTURE_STATS_INFO
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up Ethernet SmartMetrics Streams
312 | SmartLibrary Overview and Procedures
Example of Setup Steps
Here is an example of how to set up your test. It assumes no previous configuration. It shows selected commands, not all possible commands or actions.
Step 1 Connect to the SmartBits chassis and reserve ports.
See the following:
• “Establishing a Link from the PC to SmartBits” on page 87.
• “How to Identify Hubs, Slots, and Ports” on page 94.
Step 2 Reset the Card and Clear All Counters
Use HTResetPort to set the card to a known, default state. Use HTClearPort to clear all counters.
Step 3 Set Up the Streams
Use HTSetStructure with L3_DEFINE_<n>_STREAM to configure test traffic. Here, <n> represents the stream type and can be IP, IPX, UDP, TCP, or SmartBits. This function specifies the stream template—that is, the structure of frames to be sent.
Use L3_DEFINE_STREAM_EXTENSION to configure additional stream characteristics, such as the frame rate, burst count, transmit mode, IP manipulation mode, and data integrity check.
Define Multiple Streams.
Use L3_DEFINE_MULTI_<n>_STREAM to define multiple streams (<n> represents the stream type and can be IP, IPX, UDP, TCP, or SmartBits).
With multiple streams, use L3_DEFINE_MULTI_STREAM_EXTENSION to set up the stream characteristics.
Optional/RelatedOptional or related commands and actions (if applicable) are shown in a shaded box. These actions are not required for a basic test setup.
Original Function Description
HTResetPort Reset the card or module to a default state.
HTClearPort Clear the port counters.
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up Ethernet SmartMetrics Streams
SmartLibrary Overview and Procedures | 313
Define Streams with VLAN Tags.
Use the VLAN version of the L3_DEFINE, L3_DEFINE_MULTI, and L3_MOD commands to set up IP streams with VLAN tagging. Again, <n> represents the stream type and can be IP, UDP, TCP.
Step 4 Set Up Port Groups (Optional)
When SmartMetrics results are desired, you must set up a port group, since histogram results require a group start. Use HGSetGroup and HGAddtoGroup to define the port group and to add ports to a group.
Step 5 Specify Other Transmit Parameters
Use the Original Functions listed below to set up other transmit parameters not set by the L3_DEFINE functions in Step 3.
Original Function Message Function iType1 Related Structure
HTSetStructure L3_DEFINE_<n>_STREAM Stream<n>
L3_DEFINE_MULTI_<n>_STREAM Stream<n>
L3_DEFINE_STREAM_EXTENSION StreamExtension
L3_DEFINE_MULTI_STREAM_EXTENSION StreamExtension
L3_MOD_<n>_STREAM Stream<n>
Original Function Message Function iType1 Related Structure
HTSetStructure L3_DEFINE_<n>_STREAM_VLAN Stream<n>VLAN
L3_DEFINE_MULTI_<n>_STREAM_VLAN Stream<n>VLAN
L3_MOD_<n>_STREAM_VLAN Stream<n>VLAN
Original Function Description
HGSetGroup Define a group of SmartBits ports.
HGAddtoGroup Add ports to the group. You control grouped ports by using the HG commands.
Original Function Description
HTTransmitMode Set the transmit mode.
HTGap Define the interpacket gap.
HTFillPattern Set the fill pattern.
HTBurstCount/HTBurstGap Define number of packets per burst and the gap between bursts.
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up Ethernet SmartMetrics Streams
314 | SmartLibrary Overview and Procedures
Step 6 Send Test Traffic, Stop Test Traffic
Use the HTRun or HGRun command to run the test.
Use HTStop or HGStop to stop the test when run with continuous traffic.
End of Required Steps for Basic Setup
This completes the basic steps needed to transmit test traffic. The usefulness of your test, however, depends on getting test results. See “Getting Test Results” on page 314 for the steps to use counters, capture, or histograms to measure test traffic.
Getting Test Results
Your test can provide three types of results. These are:– Counters– Captured data — or —– Histograms
Counters Counters are always available. You need not enable them or set them up explicitly. You can get counter information during the test or after it stops.
Captured data and histograms
You can also retrieve captured data or histograms, but not both in the same test. For these, you must specify the type of results desired, and you must enable the function. You set up data capture or histogram results before you start your test. You obtain either type of results after you run the test.
How to Get Counter Information
Use HTGetCounters to get basic counters for your test.
Note: Other counters commands also may apply for the card or module in use. Refer to the compatibility tables in the SmartLibrary Command Reference (Volumes 1 and 2), to determine what other commands might be used.
Original Function Description
HTRun Send test traffic.
HGStop/HGRun (HGStep) For a group start, first initialize the timestamps on all cards using the “Timestamp-Initialization Sequence.” Then send test traffic using HGRun or HGStep.
HTStop/HGStop Stop the test traffic, if running continuous traffic as opposed to step or burst.
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up Ethernet SmartMetrics Streams
SmartLibrary Overview and Procedures | 315
How to Set Up Data Capture
Use the following steps to set up data capture. You can enable either data capture or SmartMetrics histogram results (see “How to Set Up SmartMetrics Histograms” on page 317).
Step 1 Set up the capture parameters.
Use HTSetStructure with NS_CAPTURE_SETUP(NSCaptureSetup) to specify the capture mode, length, and event.
Capture Mode. Valid options for NSCaptureSetup(ulCaptureMode) include:
Capture Length. Valid options for NSCaptureSetup(ulCaptureLength) include:
Original Function Description
HTGetCounters Retrieve basic test counters, including frame counts and errors.
Original Function Message Function iType1 Related Structure
HTSetStructure NS_CAPTURE_SETUP NSCaptureSetup
Capture Mode Description
CAPTURE_MODE_FILTER_ON_EVENTS Capture only packets with the specified event, such as CRC errors, undersize packets, or oversize packets.
CAPTURE_MODE_START_ON_EVENTS Capture all packets following the specified event. For example, begin capture when the first packet with a CRC error is received, then capture all packets.
CAPTURE_MODE_STOP_ON_EVENTS Capture all packets until the specified event. For example, capture all packets until the first packet with a CRC error is received, then stop the capture.
Capture Length Description
CAPTURE_LENGTH_ENTIRE_FRAME Capture complete frame.
CAPTURE_LENGTH_1ST_64_BYTES Capture only the first 64 bytes in the frame.
CAPTURE_LENGTH_LAST_64_BYTES Capture only the last 64 bytes in the frame.
CAPTURE_LENGTH_1ST_128_BYTES Capture only the first 128 bytes in the frame.
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up Ethernet SmartMetrics Streams
316 | SmartLibrary Overview and Procedures
Capture Event. The CAPTURE_EVENTS element in NSCaptureSetup defines what frame types should be captured. Valid options for NSCaptureSetup(ulCaptureEvents) include:
Step 2 Start the capture, then stop it.
Capture Event Description
CAPTURE_EVENTS_CRC_ERRORS Capture all frames with CRC errors.
CAPTURE_EVENTS_UNDERSIZE Capture all undersize frames
CAPTURE_EVENTS_OVERSIZE Capture all oversize frames.
CAPTURE_EVENTS_VLAN_TAG Capture all frames with VLAN tags.
CAPTURE_EVENTS_IP_CHECKSUM_ERROR Capture all frames with IP checksum errors.
CAPTURE_EVENTS_DATA_INTEGRITY_ERROR Capture all frames in which the payload contents have become corrupted.
CAPTURE_EVENTS_RX_TRIGGER Capture all frames that contain receive trigger patterns.
CAPTURE_EVENTS_RUNNING_DISPARITY_ERRORS Capture all frames with running disparity errors.
CAPTURE_EVENTS_ABORT Capture all frames with abort errors.
CAPTURE_EVENTS_COLLISIONS Capture all frames with collision errors.
CAPTURE_EVENTS_ALIGNMENT_ERRORS Capture all frames with alignment errors.
CAPTURE_EVENTS_OUT_OF_SEQUENCE Capture all out-of-sequence frames.
CAPTURE_EVENTS_SIGNATURE Capture all frames that include the SmartBits Signature field
CAPTURE_EVENTS_NO_SIGNATURE Capture all frames that do not include the SmartBits Signature field.
CAPTURE_EVENTS_FILTER_FRAME_LENGTH Capture all frames of a specified frame length (LAN-3710A only). The specified length includes 2-byte or 4-byte CRC.
CAPTURE_EVENTS_OAM_FRAME_ONLY Capture only frames that contain an OAM preamble (LAN-3710A only).
Original Function Message Function iType1 Description
HTSetCommand NS_CAPTURE_START Clear the buffer and start the capture.
NS_CAPTURE_STOP Stop capture.
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up Ethernet SmartMetrics Streams
SmartLibrary Overview and Procedures | 317
Step 3 Get the captured data.
Use HTGetStructure with NS_CAPTURE_COUNT_INFO to find the number of frames in the buffer.
Use HTGetStructure with NS_CAPTURE_DATA_INFO to get the captured frames.
How to Set Up SmartMetrics Histograms
Histograms provide in-depth test results, including sequence and latency information.
Histogram information is gathered on the receiving card.
Step 1 Enable the histogram type.
For SmartMetrics histograms results, specify the histogram type. All SmartMetrics cards and modules support the same histogram types.
Original Function Message Function iType1 Related Structure
HTGetStructure NS_CAPTURE_COUNT_INFO NSCaptureCountInfo
NS_CAPTURE_DATA_INFO NSCaptureDataInfo
NS_CAPTURE_STATS_INFO NSCaptureStatsInfo
Original Function Message Function iType1 Description
HTSetStructure NS_HIST_COMBO_PER_STREAM(NSHistComboPerStream)
Gives an overall picture of latency per stream. Provides the following results:
Latency per Stream. Shows minimum, maximum, and average latency values over the course of the test.
Latency Distribution. Shows the occurrence of specific latency values per stream.
Sequence Tracking. Reports whether or not frames were received in sequence per stream.
HTSetStructure NS_HIST_LATENCY_OVER_TIME(NSHistLatencyOverTime)
Provides Latency over Time histogram on the receive module.
HTSetCommand NS_HIST_RAW_SIGNATURE Signature information only, showing transmit time, receive time, and delta in microseconds.
HTSetCommand NS_HIST_SEQUENCE_PER_STREAM Sequence information only. Reports whether or not frames were received in sequence per stream.
HTSetStructure NS_HIST_LATENCY_DIST_PER_STREAM(NSHistComboPerStream)
Latency distribution information only. Shows the occurrence of specific latency values per stream.
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up Ethernet SmartMetrics Streams
318 | SmartLibrary Overview and Procedures
Step 2 Set up port groups.
For SmartMetrics histogram results, you must set up a port group. Histogram results require a group start.
Use HGSetGroup and HGAddtoGroup to define the port group and to add ports to a group.
Step 3 Gather histogram information.
After the test runs, gather the results for the SmartMetrics histogram you specified in Step 1. Use HTGetStructure with the appropriate iType1, as shown below.
Original Function Description
HGSetGroup Define a group of SmartBits ports.
HGAddtoGroup Add ports to the group. You control grouped ports by using the HG commands.
Original Function Message Function iType1 Description
HTGetStructure NS_HIST_COMBO_PER_STREAM_INFO(NSHistComboPerStreamInfo)
Latency Distribution histogram results.
NS_HIST_LATENCY_OVER_TIME_INFO(NSHistLatencyOverTimeInfo)
Latency over Time histogram results.
NS_HIST_RAW_SIGNATURE_INFO(NSHistRawSignatureInfo)
Signature information only.
NS_HIST_SEQUENCE_PER_STREAM_INFO(NSSequenceInfo)
Sequence Tracking histogram results.
NS_HIST_LATENCY_DIST_PER_STREAM_INFO(NSHistComboPerStreamInfo)
Latency Distribution histogram results.
Chapter 18: SmartMetrics/TeraMetrics TestingUsing the New Stream Configuration Commands
SmartLibrary Overview and Procedures | 319
Using the New Stream Configuration CommandsThere are several new stream configuration functions that are intended to replace the following families of stream configuration message functions:
• L3_DEFINE_*(For example, L3_DEFINE_IP_STREAM, L3_DEFINE_TCP_IPV6_STREAM)
• L3_MOD_*(For example, L3_MOD_IP_STREAM, L3_MOD_TCP_STREAM)
• L3_DEFINE_MULTI_*(For example, L3_DEFINE_MULTI_IP_STREAM)
This section describes how to use these new stream commands. For a full description of each individual function, see the chapter on original functions and structures in the SmartLibrary Command Reference Volume 1.
Note: There are restrictions on the way you can use protocols with these functions. For more information, see the appendix about streams and protocols in SmartLibrary Command Reference, Volume 1.
Sample Script
There is a sample script that contains examples of use of the new stream configuration commands. It is in the following place in the SmartLibrary installation:
Samples\Tcl\smartlib_tcl\TeraMetrics\nsstreamconfig.tcl
Commands
Summary of commands
Table 18-2 is a summary of the commands used with the new stream configuration functions, and also the new functions themselves. Not all commands are required. This list is an overview.
A basic setup See “Example of Test Configuration Steps” on page 324 for a basic setup procedure, as well as optional commands and actions.
Table 18-2. New Stream Configuration Functions
What the Commands Do Applicable Commands
Original Function Message Function iType1 (or Notes)
Reset the port to the default state.
HTResetPort —
Clear the counters. HTClearPort —
Chapter 18: SmartMetrics/TeraMetrics TestingUsing the New Stream Configuration Commands
320 | SmartLibrary Overview and Procedures
Create a stream configuration object.
NSCreateStreamConfigObject —
Delete a stream configuration object.
NSDeleteStreamConfigObject —
Create one or more streams for a stream configuration object.
NSCreateStream —
Create one or more streams based on an existing stream.
NSCopyStream —
Delete all streams in a stream configuration object.
NSDeleteAllStreams —
Retrieve the number of streams defined in a stream configuration object.
NSGetStreamCount Note that the information retrieved is from the configuration stored in the library and not from a physical port.
Create a protocol header for one or more streams.
NSCreateProtocolHeader —
Update a protocol header for one or more streams.
NSUpdateProtocolHeader —
Create/modify a protocol header for one or more streams based upon an existing stream's header.
NSCopyProtocolHeader —
Retrieve header information for one or more streams.
NSGetProtocolHeader Note that the information retrieved is from the configuration stored in the library and not from a physical port.
Retrieve information about the protocol types for each of the headers in a stream.
NSGetProtocolHeaderStackInfo Note that the information retrieved is from the configuration stored in the library and not from a physical port.
Update the transmit settings for one or more streams.
NSUpdateTxConfig —
Table 18-2. New Stream Configuration Functions (continued)
What the Commands Do Applicable Commands
Original Function Message Function iType1 (or Notes)
Chapter 18: SmartMetrics/TeraMetrics TestingUsing the New Stream Configuration Commands
SmartLibrary Overview and Procedures | 321
Modify the transmit settings for one or more streams based upon the transmit settings of an existing stream.
NSCopyTxConfig —
Retrieve the transmit settings for one or more streams.
NSGetTxConfig Note that the information retrieved is from the configuration stored in the library and not from a physical port.
Update VFD settings for one or more streams.
NSUpdateVFD —
Retrieve VFD settings for one or more streams.
NSGetVFD Note that the information retrieved is from the configuration stored in the library and not from a physical port.
Commit/send down the configuration for a stream configuration object to a physical port on a module.
NSCommitStreamConfigObject —
Delete all streams in a stream configuration object.
NSDeleteAllStreams —
Modify a field for a block of streams.
HTSetStructure L3_MOD_STREAMS_ARRAY
Specify SmartMetrics (histogram) results.
— or —
HTSetCommand NS_HIST_COMBO_PER_STREAMNS_HIST_LATENCY_OVER_TIMENS_HIST_RAW_SIGNATURENS_HIST_SEQUENCE_PER_STREAMNS_HIST_LATENCY_DIST_PER_STREAM
Set up data capture. HTSetStructure NS_CAPTURE_SETUP
Set up port groups. HGSetGroupHGAddtoGroup
—
Specify port transmit parameters.
HTSetStructure NS_PORT_TRANSMIT
Table 18-2. New Stream Configuration Functions (continued)
What the Commands Do Applicable Commands
Original Function Message Function iType1 (or Notes)
Chapter 18: SmartMetrics/TeraMetrics TestingUsing the New Stream Configuration Commands
322 | SmartLibrary Overview and Procedures
Transmit test frames and then stop the test.
HTRunHTStop
HGStartHGStepHGStop
For single-port start/stop.
For group start/stop.
Get histogram results.
— or —
HTGetStructure NS_HIST_COMBO_PER_STREAM_INFONS_HIST_LATENCY_OVER_TIME_INFONS_HIST_RAW_SIGNATURE_INFONS_HIST_SEQUENCE_PER_STREAM_INFONS_HIST_LATENCY_DIST_PER_STREAM_INFO
Get capture results. HTGetStructure NS_CAPTURE_COUNT_INFONS_CAPTURE_DATA_INFONS_CAPTURE_STATS_INFO
Table 18-2. New Stream Configuration Functions (continued)
What the Commands Do Applicable Commands
Original Function Message Function iType1 (or Notes)
Chapter 18: SmartMetrics/TeraMetrics TestingUsing the New Stream Configuration Commands
SmartLibrary Overview and Procedures | 323
Diagram of Stream Commands
The Figure 18-1 shows the relationship between the main new stream commands.
Figure 18-1. Relationship between main stream functions
Stream configurationobject
Create withNSCreateStreamConfigObject()
Commit the stream configuration to a port withNSCommitStreamConfigObject()
Create withNSCreateStream()
Create withNSCreateStream()
Update Tx settings withNSUpdateTxConfig()
Update VFD withNSUpdateVFD()
Create withNSCreateProtocolHeader()
Stream 1(includes VFD andtransmit settings)
Stream 2(includes VFD andtransmit settings)
Physical port
Ethernetheader
IPv6header
Create withNSCreateProtocolHeader()
Ethernetheader
IPv4header
Chapter 18: SmartMetrics/TeraMetrics TestingUsing the New Stream Configuration Commands
324 | SmartLibrary Overview and Procedures
Example of Test Configuration Steps
The following is an example of how to run a test with the new stream configuration functions. It assumes no previous configuration. It shows selected commands, not all possible commands or actions.
Step 1 Connect to the SmartBits chassis, and reserve modules.
Step 2 Reset the card and clear all counters.
Step 3 Create a stream configuration object.
Step 4 Create one or more streams for the stream configuration object.
Step 5 Define a header for one or more streams.
Step 6 Configure the transmit settings.
Use Description
NSSocketLink Connect to the chassis.
HTSlotReserve Reserve modules.
Use Description
HTResetPort Reset the card and clear all counters.
Use Description
NSCreateStreamConfigObject Create the stream configuration object.
Use Description
NSCreateStream Create a stream that is inserted in or appended to the stream configuration object.
Use Description
NSCreateProtocolHeader Create a protocol header that is inserted in or appended to one or more streams.
Use Description
NSUpdateTxConfig Updates the transmission-related settings for one or more streams.
Chapter 18: SmartMetrics/TeraMetrics TestingUsing the New Stream Configuration Commands
SmartLibrary Overview and Procedures | 325
Step 7 Configure VFD1 and VFD2 settings.
Step 8 Commit the streams to a port.
Step 9 Configure the port transmit setting.
Step 10 (optional) Modify a field in a block of streams.
Note that this command does not update the stream configuration settings stored in the library.
Step 11 (optional) Set up port groups.
Use Description
NSUpdateVFD Updates VFD (Variable Field Definition) settings for one or more streams.
Use Description
NSCommitStreamConfigObject Commit the streams in the stream configuration object to a port.
Use with Message Function iType1 Related Structure
HTSetStructure NS_PORT_TRANSMIT NSPortTransmit
Use with Message Function iType1 Related Structure
HTSetStructure L3_MOD_STREAMS_ARRAY Layer3ModifyStreamArray
Use Description
HGSetGroup Groups a number of SmartBits ports.
HGAddtoGroup Used with HGSetGroup to add individual hub/slot/port cards to a group.
Chapter 18: SmartMetrics/TeraMetrics TestingUsing the New Stream Configuration Commands
326 | SmartLibrary Overview and Procedures
Step 12 (optional) Set up capture or enable a histogram test.
Note that the modules do not support capture and histogram tracking simultaneously.
Use HTSetStructure with NS_CAPTURE_SETUP and NS_CAPTURE_START to set up capture.
Use the NS_HIST_* message functions to enable a histogram test. The following table shows the different histogram test types:
Table 18-3.
Original Function Message Function iType1 Related Structure/Description
HTSetStructure NS_HIST_COMBO_PER_STREAM NSHistComboPerStream
Gives an overall picture of latency per stream. Provides the following results:• Latency per stream – Shows
minimum, maximum, and average latency values over the course of the test.
• Latency distribution – Shows the occurrence of specific latency values per stream.
• Sequence tracking – Reports whether or not frames were received in sequence per stream.
HTSetStructure NS_HIST_LATENCY_OVER_TIME NSHistLatencyOverTime
Provides latency over lime histogram on the receive module.
HTSetCommand NS_HIST_RAW_SIGNATURE Signature information only, showing transmit time, receive time, and delta in microseconds.
HTSetCommand NS_HIST_SEQUENCE_PER_STREAM Sequence information only. Reports whether or not frames were received in sequence per stream.
HTSetStructure NS_HIST_LATENCY_DIST_PER_STREAM NSHistComboPerStream
Latency distribution information only. Shows the occurrence of specific latency values per stream.
Chapter 18: SmartMetrics/TeraMetrics TestingUsing the New Stream Configuration Commands
SmartLibrary Overview and Procedures | 327
Step 13 Send test traffic and stop test traffic.
Step 14 Stop capture, if applicable to your test.
Step 15 Retrieve capture information or histogram results.
Get the count of frames in the capture buffer with NS_CAPTURE_COUNT_INFO.
Get a captured frame with NS_CAPTURE_DATA_INFO.
Retrieve histogram results using the NS_HIST_*_INFO message functions. The following table gives the commands used to retrieve histogram results:
Use Description
HTRun Start or stop transmission of packets
HGStart (alternate) Start transmission of packets
HGStop Stop transmission of packets
Use with Message Function iType1 Related Structure
HTSetCommand NS_CAPTURE_STOP None
Use with Message Function iType1 Related Structure
HTGetStructure NS_CAPTURE_COUNT_INFO NSCaptureCountInfo
HTGetStructure NS_CAPTURE_DATA_INFO NSCaptureDataInfo
Table 0-1.
Original Function Message Function iType1 Related Structure/Description
HTGetStructure NS_HIST_COMBO_PER_STREAM_INFO NSHistComboPerStreamInfo
Latency distribution histogram results.
HTGetStructure NS_HIST_LATENCY_OVER_TIME_INFO NSHistLatencyOverTimeInfo
Latency over time histogram results.
HTGetStructure NS_HIST_RAW_SIGNATURE_INFO NSHistRawSignatureInfo
Signature information only.
HTGetStructure NS_HIST_SEQUENCE_PER_STREAM_INFO NSSequenceInfo
Sequence tracking histogram results.
Chapter 18: SmartMetrics/TeraMetrics TestingUsing the New Stream Configuration Commands
328 | SmartLibrary Overview and Procedures
Step 16 (optional) Delete all streams.
Step 17 Delete the stream configuration object.
Step 18 Release all reserved modules and unlink from the SmartBits chassis.
End of Test Configuration Steps
This completes the steps needed to run a simple test with the new stream configuration functions.
HTGetStructure NS_HIST_LATENCY_DIST_PER_STREAM_INFO NSHistLatencyDistPerStreamInfo
Latency distribution histogram results.
Table 0-1.
Original Function Message Function iType1 Related Structure/Description
Use Description
NSDeleteAllStreams Deletes all streams in a stream configuration object.
Use Description
NSDeleteStreamConfigObject Delete the stream configuration object and all associated child objects (that is, the stream and protocol header).
Use Description
HTSlotRelease Releases a slot, making it available for others.
NSUnLink Ends the connection to the SmartBits chassis.
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up SmartMetrics Tests on TeraMetrics-based Modules
SmartLibrary Overview and Procedures | 329
Set Up SmartMetrics Tests on TeraMetrics-based ModulesUse the following steps to set up SmartMetrics tests with Ethernet TeraMetrics or SmartMetrics modules.
What are Dual Media Modules?
The SmartBits Dual media modules listed in Table 18-4 are capable of operating using either a copper interface (10/100/1000BASE-T) or fiber interface (1000BASE-X) for each port. The LAN-3320A/3321A and LAN-3324A/3325A modules provide two and four ports, respectively. The LAN-3327A module provides one port. On multiport modules, individual ports can operate in either interface mode (only one mode may be active on a port at any time).
Table 18-4. SmartMetrics/TeraMetrics Ethernet Modules in This Setup
Module DescriptionSmartBits 600x/6000x
LAN-3300ALAN-3301ALAN-3302A
10/100/1000Base-T Ethernet, Copper, 2-port, SmartMetrics 10/100/1000Base-T Ethernet, Copper, 2-port, TeraMetrics 10/100Base-TX Ethernet, Copper, 2-port, TeraMetrics
v
LAN-3306A 10/100Base-TX Ethernet, Copper, 4-port, TeraMetrics XD v
LAN-3310ALAN-3311A
1000Base-X Ethernet, GBIC, 2-port, SmartMetrics1000Base-X Ethernet, GBIC, 2-port, TeraMetrics
v
LAN-3320A
LAN-3321A
10/100/1000 Mbps and Gigabit Ethernet Fiber, 2-port, SmartMetrics XD10/100/1000 Mbps and Gigabit Ethernet Fiber, 2-port, TeraMetrics XD
v
LAN-3324A
LAN-3325A
10/100/1000 Mbps and Gigabit Ethernet Fiber, 4-port, SmartMetrics XD10/100/1000 Mbps and Gigabit Ethernet Fiber, 4-port, TeraMetrics XD
v
LAN-3327A 10/100/1000 Mbps and Gigabit Ethernet Fiber, 1-port, TeraMetrics XD
v
LAN-3710AELAN-3710ALLAN-3710AS
10GBase-ER Ethernet, 1-port, 2-slot, single mode, 1550nm10GBase-ER Ethernet, 1-port, 2-slot, single mode, 1310nm 10GBase-ER Ethernet, 1-port, 2-slot, single mode, 850nm
v
XLW-3720AXLW-3721A
10GBase Ethernet XENPAK MSA, 1-port, 2-slot SmartMetrics10GBase Ethernet XENPAK MSA, 1-port, 2-slot, TeraMetrics
v
XFP-3730AXFP-3731A
10GBase Ethernet XFP MSA, 1-port, 1-slot, SmartMetrics 10GBase Ethernet XFP MSA, 1-port, 1-slot, TeraMetrics
v
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up SmartMetrics Tests on TeraMetrics-based Modules
330 | SmartLibrary Overview and Procedures
The operation of Dual Media modules is closely similar to that of the LAN-3301A and LAN-3311A modules. The two interface modes differ, however, and certain SmartLibrary commands take effect only when the related interface mode is set for the port.
Applicable Commands
Table 18-5 is a summary of commands you can use. Not all commands are required. This list is an overview.
A basic setup See “Example of Setup Steps” on page 332 for a basic setup procedure, as well as optional commands and actions.
Table 18-5. Applicable Commands: SmartMetrics Tests with LAN-33xxA Modules
Applicable Commands
What the Commands Do Use Original Function With Message Function iType1 / Comments
Reset card to the default state. HTResetPort See “Example of Setup Steps” on page 332.
Clear counters. HTClearPort See “Example of Setup Steps” on page 332.
Dual media modules only:Set the interface mode.
HTSetStructure NS_PHY_CONFIG
Dual media modules only:Query the interface mode.
HTGetStructure NS_PHY_CONFIG_INFO
Dual media modules only:Check the LEDs.
HTGetLEDs HTLED_LINKED shows the link status.
Set up streams. HTSetStructure L3_DEFINE_<n>_STREAM
Note: Using L3_DEFINE_<n>_STREAM puts the module into the SmartMetrics mode. The library may then generate error messages in response to commands that pertain to Traditional mode operation. See the Note on page 333.
(Optional) Set up additional stream characteristics.
HTSetStructure L3_DEFINE_STREAM_EXTENSION
Specify the scheduling mode (either gap-based or rate-based).
HTSetStructure—or—HTScheduleMode
NS_PORT_TRANSMIT
—
Set the port speed. HTSetSpeed—or—HTSetStructure
—
ETH_SET_SPEED
Continues –>
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up SmartMetrics Tests on TeraMetrics-based Modules
SmartLibrary Overview and Procedures | 331
Applicable Commands
What the Commands Do Use Original Function With Message Function iType1
Set up MII registers for auto negotiation (100Mb and 1000Mb only).
HTFindMIIAddressHTReadMIIHTWriteMII—or—HTGetStructure
HTSetStructure
ETH_FIND_MII_ADDR_INFOETH_READ_MII_INFO
ETH_WRITE_MII
Specify SmartMetrics (histogram) results.
—or—
HTSetStructureHTSetStructureHTSetCommandHTSetCommandHTSetStructure
NS_HIST_COMBO_PER_STREAMNS_HIST_LATENCY_OVER_TIMENS_HIST_RAW_SIGNATURENS_HIST_SEQUENCE_PER_STREAMNS_HIST_LATENCY_DIST_PER_STREAM
Set up data capture. HTSetStructure NS_CAPTURE_SETUP
(Optional) Set up port groups. HGSetGroupHGAddtoGroup
See “Example of Setup Steps” on page 332.
Start data capture (if selected). HTSetCommand NS_CAPTURE_START
Transmit test frames. HTRun For single-port start.
HGRunHGStep
For group start.
Stop the test. HTStopHGStop
See “Example of Setup Steps” on page 332.
Stop data capture (if selected). HTSetCommand NS_CAPTURE_STOP
Get histogram information.
—or—
HTGetStructure NS_HIST_COMBO_PER_STREAM_INFONS_HIST_LATENCY_OVER_TIME_INFONS_HIST_RAW_SIGNATURE_INFONS_HIST_SEQUENCE_PER_STREAM_INFONS_HIST_LATENCY_DIST_PER_STREAM_INFO
Get captured data. HTGetStructure NS_CAPTURE_COUNT_INFONS_CAPTURE_DATA_INFO
Table 18-5. Applicable Commands: SmartMetrics Tests with LAN-33xxA Modules
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up SmartMetrics Tests on TeraMetrics-based Modules
332 | SmartLibrary Overview and Procedures
Example of Setup Steps
Here is a more detailed description of the steps summarized above.
Step 1 Connect to the SmartBits chassis and reserve ports.
See the following:
• “Establishing a Link from the PC to SmartBits” on page 87.
• “How to Identify Hubs, Slots, and Ports” on page 94.
Step 2 Reset the Card and Clear All Counters
Use HTResetPort to set the card to a known, default state. Use HTClearPort to clear all counters.
Step 3 (Optional) Set the Interface Mode
Use HTSetStructure with NS_PHY_CONFIG(NSPhyConfig) to specify which medium (copper or fiber) will be active for each port. In NSPhyConfig, ulMediaMode must be set to MEDIA_USER_EXPLICIT_MODE (the default and only permitted value).
Step 4 (Optional) Read Back the Interface Mode
Use HTGetStructure with NS_PHY_CONFIG_INFO(NSPhyConfig) to query the active interface mode for each port.
Optional/RelatedOptional or related commands and actions (if applicable) are shown in a shaded box. These actions are not required for a basic test setup.
Original Function Description
HTResetPort Reset the card or module to a default state.
HTClearPort Clear the port counters.
Optional – Dual Media ModulesStep 3 through Step 5 apply only to the LAN-332xA Dual Media modules. See “What are Dual Media Modules?” on page 329.
Original Function Message Function iType1 Related Structure
HTSetStructure NS_PHY_CONFIG NSPhyConfig
Original Function Message Function iType1 Related Structure
HTGetStructure NS_PHY_CONFIG_INFO NSPhyConfig
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up SmartMetrics Tests on TeraMetrics-based Modules
SmartLibrary Overview and Procedures | 333
Step 5 (Optional) Get the LED State
Use HTGetLEDs to ensure that HTLED_LINKED is present on both ports. This verifies that the link is up and ready to operate.
Step 6 Set Up StreamsUse HTSetStructure with L3_DEFINE_<n>_STREAM to configure at least one stream on the receiving port. Here, <n> represents the stream type and can be IP, IPX, UDP, TCP, or SmartBits.
Use L3_DEFINE_STREAM_EXTENSION to define additional stream characteristics, including transmit mode, IP manipulation mode, and data integrity check. Two members in the L3StreamExtension structure do not apply to this module: ulTxMode and ucIPManipulateMode.
Defining Multiple Streams.
To define multiple streams, use L3_DEFINE_MULTI_<n>_STREAM. Stream types <n> can be IP, IPX, UDP, TCP, or SmartBits.
Note: Using L3_DEFINE_<n>_STREAM (or L3_DEFINE_<n>_MULTI_STREAM) places the module into SmartMetrics mode, and the use of commands that pertain to Traditional mode may clear existing streams. Such commands include GIG_STRUC_TX, GIG_STRUC_ALT_TX, HTEcho, HTFillPattern, HTLatency, and HTVFD.
Modifying a Stream.
Use L3_MOD_<n>_STREAM to modify an existing stream at a specified index. This function replaces the entire stream: to change one or more attributes, a complete structure is sent to the card. L3_MOD_<n>_STREAM can modify the stream at index 0, but you should modify streams starting at index 1.
Original Function Description
HTGetLEDs Get the state of HTLED_LINKED, to ensure that the link is ready.
Original Function Message Function iType1 Related Structure
HTSetStructure L3_DEFINE_<n>_STREAM Stream<n>
L3_DEFINE_STREAM_EXTENSION StreamExtension
L3_DEFINE_MULTI_<n>_STREAM Stream<n>
L3_DEFINE_MULTI_STREAM_EXTENSION
StreamExtension
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up SmartMetrics Tests on TeraMetrics-based Modules
334 | SmartLibrary Overview and Procedures
Define Streams with VLAN Tags.
Use the VLAN version of the L3_DEFINE, L3_DEFINE_MULTI, and L3_MOD commands to set up IP streams with VLAN tagging. Again, <n> represents the stream type and can be IP, UDP, TCP.
Step 7 Define the Schedule Mode (Gap-based or Rate-based)
You can specify that the streams generated by the port are scheduled and transmitted based either on interframe gap or frame rate. Specifically, you can select one of three options. Streams can be scheduled by:• Interframe Gap – A fixed number of bit times between frames.• Random IFG – A varying number of bit times between frames.• Frame Rate – A defined frames-per-second rate of transmission for each stream.
Bursty traffic can still be used.
The selected scheduling mode you assign to a port applies to all streams generated by the port. Test traffic is sent in a round-robin fashion, with one frame from each stream generated in sequence.
For all three scheduling options, a software mechanism on the card (termed the scheduler) calculates how to allocate the overall line bandwidth. It builds a static scheduling table that organizes all streams before any traffic is sent. The schedule table is static in that it does not vary as test traffic is sent—even though two of the scheduling options (Random IFG and Frame Rate) appear to be dynamic in behavior, because they allow individual stream frame rates and random interframe gaps.
Note: The scheduling mechanism for earlier SmartBits cards, such as the LAN-3201B/C, differs in important ways. Refer to Chapter 4, “Traffic Rates and Patterns” for detailed information on these cards.
For the three modes, the test streams are organized as follows.
Gap-based Traffic
With the two gap-based modes (IFG and Random IFG), you can control the frame size and gap size (or range of gap sizes) but not the frame rate.
For traffic scheduled by a fixed interframe gap, the card inserts your specified gap (number of bit times) between frames. It then sends out test traffic, with the selected frame size, at the maximum line rate.
Continues –>
Original Function Message Function iType1 Related Structure
HTSetStructure L3_DEFINE_<n>_STREAM_VLAN Stream<n>VLAN
L3_DEFINE_MULTI_<n>_STREAM_VLAN Stream<n>VLAN
L3_MOD_<n>_STREAM_VLAN Stream<n>VLAN
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up SmartMetrics Tests on TeraMetrics-based Modules
SmartLibrary Overview and Procedures | 335
For traffic scheduled by a random interframe gap, a random number generator on the card produces gaps of varying sizes, within the bounds you define by using NS_PORT_TRANSMIT. These gaps are inserted between frames. Then test traffic is sent with the selected frame size at the maximum line rate.
Rate-based Traffic
For traffic scheduled by a frame rate, you can specify a different rate for each stream, but you cannot control the interframe gap. The gaps are calculated and inserted by the card automatically. The card inserts at the least the minimum interframe gap. If you specify frame rates that, altogether, are lower than the maximum line capacity, the “extra” bandwidth is divided among the streams for use as the interframe gap times.
How to Set the Schedule Mode
You can set the schedule mode in two ways:
Option 1: Use NS_PORT_TRANSMIT
Option 2: Use HTScheduleMode
Option 1 Use NS_PORT_TRANSMIT (Message Function)
Use HTSetStructure with NS_PORT_TRANSMIT to specify the schedule mode. Then use the functions below to set global characteristics for the port, as well as per-stream characteristics.
• For gap-based traffic, use NS_PORT_TRANSMIT to set the gap size.
• For rate-based traffic, use L3_DEFINE_STREAM_EXTENSION to set frame rate, background pattern, per-stream errors, and other stream characteristics (but not a gap size).
Original Function Description
NS_PORT_TRANSMIT Specify the desired mode. Then set port and per-stream characteristics as shown below.
For gap-based traffic: Use NS_PORT_TRANSMIT with NSPortTransmit to set the gap size, transmit mode, burst count, and other global (port) variables.
Optionally, you can use L3_DEFINE_STREAM_EXTENSION with L3StreamExtension to set stream characteristics such as background pattern and generated errors (but not frame rate).
For frame rate-based traffic: Use NS_PORT_TRANSMIT with NSPortTransmit to set the transmit mode, burst count, and other global (port) variables (but not gap size).
Use L3_DEFINE_STREAM_ EXTENSION with L3StreamExtension to set the frame rate (as well as stream characteristics such as background pattern and generated errors).
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up SmartMetrics Tests on TeraMetrics-based Modules
336 | SmartLibrary Overview and Procedures
Option 2 Use HTScheduleMode (Original Function)
Use HTScheduleMode to specify the schedule mode. Then use the other functions listed below to set global characteristics for the port, as well as per-stream characteristics.
Step 8 Set the Port Speed
Ports on the LAN-3300A/LAN-3301A modules can operate at 10Mbps, 100Mbps, or 1000Mbps. The LAN-3302A can operate at 10Mbps or 100Mbps.
For these module types, set the port speed.
Original Function Description
HTScheduleMode Specify the schedule mode. Then set port and per-stream characteristics as shown below.
For gap-based traffic:
HTGap Set the gap size.
HTTransmitMode Set the transmit mode (for example, single burst, multi-burst, or continuous).
HTBurstCount Set the burst count (number of packets per burst).
For frame rate-based traffic:
HTTransmitMode Set the transmit mode (for example, single burst, multi-burst, or continuous).
HTBurstCount Set the burst count (number of packets per burst).
HTSetStructure Use L3_DEFINE_STREAM_EXTENSION with L3StreamExtension to set the frame rate, background pattern, per-stream errors (as well as stream characteristics such as background pattern and generated errors).
Original Function Message Function iType1 Data Type/Structure
HTSetStructure ETH_SET_SPEED ULong
HTSetSpeed — —
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up SmartMetrics Tests on TeraMetrics-based Modules
SmartLibrary Overview and Procedures | 337
Step 9 Set Up MII Registers for Auto Negotiation (100Mbps/1000Mbps Only)
When the port speed will be 100Mbps or 1000Mbps, set up the auto negotiation.
Step 10 (Optional) Set up port groups.
To set up a port group, use HGSetGroup to define the port group and HGAddtoGroup to add ports to a group.
Step 11 Start the capture, if selected.
Step 12 Send test traffic, then stop the test.
Use HTRun or HGRun to run the test.
If you run the test with continuous traffic, use HTStop or HGStop to stop the test.
Note: For Latency histogram results, it is important to initialize the timestamps on each module before doing a group start. To do this, use the “Timestamp-Initialization Sequence.”
Original Function Message Function iType1 Related Structure Description
HTFindMIIAddress — — Find the first MII PHY address with a device attached (100 Mbps only).
HTReadMII — — Read a specified MII register (100 Mbps only).
HTWriteMII — — Write to a specified MII register (100 Mbps only).
HTGetStructure ETH_FIND_MII_ADDR_INFO
ETHMII Find the first MII PHY address with a device attached.
HTGetStructure ETH_READ_MII_INFO ETHMII Read (or write to) a specified MII register.
HTSetStructure ETH_WRITE_MII ETHMII Read (or write to) a specified MII register.
Original Function Message Function iType1 Description
HTSetCommand NS_CAPTURE_STOPNS_CAPTURE_START
Clear the buffer and start the capture.
Original Function Description
HTRun/HTStop Transmit test frames, then stop the test (if running continuous traffic rather than step or burst mode).
HGRun/HGStep/HGStop
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up SmartMetrics Tests on TeraMetrics-based Modules
338 | SmartLibrary Overview and Procedures
Step 13 Stop the capture, if selected.
End of Required Steps for Basic Setup
This completes the basic steps needed to transmit test traffic. The usefulness of your test, however, depends on getting test results. See “Getting Test Results” on page 339 for the steps to use counters, capture, or histograms to measure test traffic.
Original Function Message Function iType1 Description
HTSetCommand NS_CAPTURE_STOP Stop capture.
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up SmartMetrics Tests on TeraMetrics-based Modules
SmartLibrary Overview and Procedures | 339
Getting Test Results
Your test can provide three types of results. These are:– Counters– Captured data — or —– Histograms
Counters Counters are always available. You need not enable them or set them up explicitly. You can get counter information during the test or after it stops.
Captured data and histograms
You can also retrieve captured data or histograms, but not both in the same test. For these, you must specify the type of results desired, and you must enable the function. You set up data capture or histogram results before you start your test. You obtain either type of results after you run the test.
How to Get Counter Information
Use HTGetCounters to get basic counters for your test.
Use ETH_EXTENDED_COUNTER_INFO to get additional counters.
You can also use the new NS_MULTI_COUNTER_INFO command, which retrieves all counters supported by TeraMetrics modules.
Note: Other counters commands also may apply for the card or module in use. Refer to the compatibility tables in the SmartLibrary Command Reference (Volumes 1 and 2), to determine what other commands can be used.
How to Set Up Data Capture
Use the following steps to set up data capture. You can enable either data capture or SmartMetrics histogram results (see “How to Set Up SmartMetrics Histograms” on page 341).
Step 1 Set up the capture parameters.
Use HTSetStructure with NS_CAPTURE_SETUP(NSCaptureSetup) to specify the capture mode, length, and event.
Original Function Message Function iType1 Structure/Description
HTGetCounters — Retrieve basic test counters, including frame counts and errors.
HTGetStructure ETH_EXTENDED_COUNTER_INFO ETHExtendedCounterInfo
Original Function Message Function iType1 Related Structure
HTSetStructure NS_CAPTURE_SETUP NSCaptureSetup
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up SmartMetrics Tests on TeraMetrics-based Modules
340 | SmartLibrary Overview and Procedures
Capture Mode. Valid options for NSCaptureSetup(ulCaptureMode) include:
Capture Length. Valid options for NSCaptureSetup(ulCaptureLength) include:
Capture Event. The CAPTURE_EVENTS element in NSCaptureSetup defines what frame types should be captured. Valid options for NSCaptureSetup(ulCaptureEvents) include:
Step 2 Start the capture, then stop it.
Capture Mode Description
CAPTURE_MODE_FILTER_ON_EVENTS Capture only packets with the specified event, such as CRC errors, undersize packets, or oversize packets.
CAPTURE_MODE_START_ON_EVENTS Capture all packets following the specified event. For example, begin capture when the first packet with a CRC error is received, then capture all packets.
CAPTURE_MODE_STOP_ON_EVENTS Capture all packets until the specified event. For example, capture all packets until the first packet with a CRC error is received, then stop the capture.
Capture Length Description
CAPTURE_LENGTH_ENTIRE_FRAME Capture complete frame.
CAPTURE_LENGTH_1ST_64_BYTES Capture only the first 64 bytes in the frame.
CAPTURE_LENGTH_LAST_64_BYTES Capture only the last 64 bytes in the frame.
Capture Event Description
CRC_ERRORS Capture all frames with CRC errors.
IP_CHECKSUM_ERROR Capture all frames with IP checksum errors.
DATA_INTEGRITY_ERROR Capture all frames in which the payload contents have become corrupted.
RX_TRIGGER Capture all frames that contain receive trigger patterns.
Original Function Message Function iType1 Description
HTSetCommand NS_CAPTURE_START Clear the buffer and start the capture.
NS_CAPTURE_STOP Stop capture.
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up SmartMetrics Tests on TeraMetrics-based Modules
SmartLibrary Overview and Procedures | 341
Step 3 Get the captured data.
Use HTGetStructure with NS_CAPTURE_COUNT_INFO to find the number of frames in the buffer.
Use HTGetStructure with NS_CAPTURE_DATA_INFO to get the captured frames.
How to Set Up SmartMetrics Histograms
Histograms provide in-depth test results, including sequence and latency information.
Histogram information is gathered on the receiving card.
Step 1 Enable the histogram type.
For SmartMetrics histograms results, specify the histogram type. All SmartMetrics cards and modules support the same histogram types.
Original Function Message Function iType1 Related Structure
HTGetStructure NS_CAPTURE_COUNT_INFO NSCaptureCountInfo
NS_CAPTURE_DATA_INFO NSCaptureDataInfo
Original Function Message Function iType1 Related Structure/Description
HTSetStructure NS_HIST_COMBO_PER_STREAM NSHistComboPerStream
Gives an overall picture of latency per stream. Provides the following results:
Latency per Stream. Shows minimum, maximum, and average latency values over the course of the test.
Latency Distribution. Shows the occurrence of specific latency values per stream.
Sequence Tracking. Reports whether or not frames were received in sequence per stream.
HTSetStructure NS_HIST_LATENCY_OVER_TIME NSHistLatencyOverTime
Provides Latency over Time histogram on the receive module.
HTSetCommand NS_HIST_RAW_SIGNATURE Signature information only, showing transmit time, receive time, and delta in microseconds.
HTSetCommand NS_HIST_SEQUENCE_PER_STREAM Sequence information only. Reports whether or not frames were received in sequence per stream.
HTSetStructure NS_HIST_LATENCY_DIST_PER_STREAM NSHistComboPerStream
Latency distribution information only. Shows the occurrence of specific latency values per stream.
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up SmartMetrics Tests on TeraMetrics-based Modules
342 | SmartLibrary Overview and Procedures
Step 2 Set up port groups.
For SmartMetrics histogram results, you must set up a port group. Histogram results require a group start.
Use HGSetGroup and HGAddtoGroup to define the port group and to add ports to a group.
Step 3 Gather histogram information.
After the test runs, gather the results for the SmartMetrics histogram you specified in Step 1. Use HTGetStructure with the appropriate iType1, as shown below.
Original Function Description
HGSetGroup Define a group of SmartBits ports.
HGAddtoGroup Add ports to the group. You control grouped ports by using the HG commands.
Original Function Message Function iType1 Related Structure/Description
HTGetStructure NS_HIST_COMBO_PER_STREAM_INFO NSHistComboPerStreamInfo
Latency Distribution histogram results.
NS_HIST_LATENCY_OVER_TIME_INFO NSHistLatencyOverTimeInfo
Latency over Time histogram results.
NS_HIST_RAW_SIGNATURE_INFO NSHistRawSignatureInfo
Signature information only.
NS_HIST_SEQUENCE_PER_STREAM_INFO NSSequenceInfo
Sequence Tracking histogram results.
NS_HIST_LATENCY_DIST_PER_STREAM_INFO NSHistLatencyDistPerStreamInfo
Latency Distribution histogram results.
Chapter 18: SmartMetrics/TeraMetrics TestingTest with IPv6 Streams on TeraMetrics Modules
SmartLibrary Overview and Procedures | 343
Test with IPv6 Streams on TeraMetrics ModulesThis procedure is similar to the one used to set up SmartMetrics tests with IPv4 streams (see “Set Up SmartMetrics Tests on TeraMetrics-based Modules” on page 329).
The important differences are as follows:
• Before defining streams, use NS_PORT_TRANSMIT(NSPortTransmit) to enable the 128-byte header length needed to accommodate the longer IPv6 stream header (TCP, TCP VLAN, and UDP VLAN only). Set ucEnableExtendedPayload to 1. Doing this reduces the maximum possible number of streams by half, from 512 to 256 (except for POS-3518AS/AR and POS-3519AS/AR modules). In addition, any time you switch between enabling and disabling the extended payload, all currently configured streams are deleted.
• When defining streams, set one of the IPv6 stream types (see “Set Up Streams” on page 346). As with IPv4, stream types include native IP, TCP, and UDP.
• To set additional streams or modify streams, use the IPv6 versions of the standard L3_DEFINE_MULTI and L3_MOD commands.
• Set and get IPv6 address information by using L3_TX_IPV6_ADDRESS and L3_TX_IPV6_ADDRESS_INFO.
• Set IPv6 protocol information (Ping settings) by using L3_TX_IPV6_PROTOCOL.
• Perform Neighbor Discovery by using L3_START_ARPS. See “Set Up IPv6 Neighbor Discovery” on page 357 for more related information.
• Get IPv6 counters (events and rates) by using NS_IPV6_COUNTER_INFO and NS_IPV6_RATE_INFO.
Ethernet IPv6 tests can be run with the following TeraMetrics-family modules. See “Test with IPv6 Streams on POS TeraMetrics Modules” on page 453 for the procedure for POS TeraMetrics modules.
Table 18-6. IPv6-Capable TeraMetrics Modules
Module Description
SmartBits Chassis
600x/6000x
LAN-3300ALAN-3301ALAN-3302A
10/100/1000Base-T Ethernet, Copper, 2-port, SmartMetrics10/100/1000Base-T Ethernet, Copper, 2-port, TeraMetrics10/100Base-TX Ethernet, Copper, 2-port, TeraMetrics
v
LAN-3310ALAN-3311A
1000Base-X Ethernet, GBIC, 2-port, SmartMetrics1000Base-X Ethernet, GBIC, 2-port, TeraMetrics
v
LAN-3320ALAN-3321A
10/100/1000 Mbps and Gigabit Ethernet Fiber, 2-port, SmartMetrics XD10/100/1000 Mbps and Gigabit Ethernet Fiber, 2-port, TeraMetrics XD
v
Chapter 18: SmartMetrics/TeraMetrics TestingTest with IPv6 Streams on TeraMetrics Modules
344 | SmartLibrary Overview and Procedures
Applicable Commands
Table 18-7 is a summary of commands you can use. Not all commands are required. This list is an overview.
A basic setup See “Example of Setup Steps” on page 346 for a basic setup procedure, as well as optional commands and actions.
LAN-3324ALAN-3325A
10/100/1000 Mbps and Gigabit Ethernet Fiber, 4-port, SmartMetrics XD 10/100/1000 Mbps and Gigabit Ethernet Fiber, 4-port, TeraMetrics XD
v
LAN-3327A 10/100/1000 Mbps and Gigabit Ethernet Fiber, 1-port, TeraMetrics XD v
XLW-372xAXFP-373xA
10GBase Ethernet XENPAK MSA, 1-port, 2-slot, SmartMetrics/TeraMetrics 10GBase Ethernet XFP MSA, 1-port, 1-slot, SmartMetrics/TeraMetrics
v
Table 18-6. IPv6-Capable TeraMetrics Modules (continued)
Module Description
SmartBits Chassis
600x/6000x
Table 18-7. Applicable Commands: SmartMetrics Tests with IPv6 Streams
What the Commands Do
Applicable Commands
Use Original Function With Message Function iType1
Reset card to the default state. HTResetPort See “Example of Setup Steps” on page 346.
Clear counters. HTClearPort See “Example of Setup Steps” on page 346.
Enable extended header length. HTSetStructure NS_PORT_TRANSMIT (TCP, TCP VLAN, and UDP VLAN only)
Set up streams. HTSetStructure L3_DEFINE_<n>_IPV6_STREAM
Note: Using this command puts the module into the SmartMetrics mode. The library may then generate error messages in response to commands that pertain to Traditional mode operation. See the Note on page 347.
Specify IPv6 address information.
HTSetStructure L3_TX_IPV6_ADDRESS
Get IPv6 address information. HTGetStructure L3_TX_IPV6_ADDRESS_INFO
Specify IPv6 protocol information (Ping settings).
HTSetStructure L3_TX_IPV6_PROTOCOL
Specify the scheduling mode (either gap-based or rate-based).
HTSetStructure
—or—
HTScheduleMode
NS_PORT_TRANSMIT
—
Chapter 18: SmartMetrics/TeraMetrics TestingTest with IPv6 Streams on TeraMetrics Modules
SmartLibrary Overview and Procedures | 345
Set the port speed. HTSetSpeed
—or—
HTSetStructure
—
ETH_SET_SPEED
Set up MII registers for auto negotiation (100Mb and 1000Mb only).
HTFindMIIAddressHTReadMIIHTWriteMII
—or—
HTGetStructure
HTSetStructure
ETH_FIND_MII_ADDR_INFOETH_READ_MII_INFO
ETH_WRITE_MII
Specify SmartMetrics (histogram) results.
—or—
HTSetCommand NS_HIST_COMBO_PER_STREAMNS_HIST_LATENCY_OVER_TIMENS_HIST_RAW_SIGNATURENS_HIST_SEQUENCE_PER_STREAMNS_HIST_LATENCY_DIST_PER_STREAM
Set up data capture. HTSetStructure NS_CAPTURE_SETUP
(Optional) Set up port groups. HGSetGroupHGAddtoGroup
See “Example of Setup Steps” on page 346.
Perform Neighbor Discovery. L3_START_ARPS See “Set Up IPv6 Neighbor Discovery” on page 357 for detailed information.
Transmit test frames. HTRun For single-port start.
HGRunHGStep
For group start.
Start data capture (if selected). HTSetCommand NS_CAPTURE_START
Stop the test. HTStopHGStop
See “Example of Setup Steps” on page 346.
Stop data capture (if selected). HTSetCommand NS_CAPTURE_STOP
Get IPv6 counters and rates. HTGetStructure NS_IPV6_COUNTER_INFONS_IPV6_RATE_INFO
Get histogram information.
—or—
HTGetStructure NS_HIST_COMBO_PER_STREAM_INFONS_HIST_LATENCY_OVER_TIME_INFONS_HIST_RAW_SIGNATURE_INFONS_HIST_SEQUENCE_PER_STREAM_INFONS_HIST_LATENCY_DIST_PER_STREAM_INFO
Get captured data. HTGetStructure NS_CAPTURE_COUNT_INFONS_CAPTURE_DATA_INFO
Table 18-7. Applicable Commands: SmartMetrics Tests with IPv6 Streams (continued)
What the Commands Do
Applicable Commands
Use Original Function With Message Function iType1
Chapter 18: SmartMetrics/TeraMetrics TestingTest with IPv6 Streams on TeraMetrics Modules
346 | SmartLibrary Overview and Procedures
Example of Setup Steps
Here is a more detailed description of the steps summarized above.Step 1 Reset the Card and Clear All Counters
Use HTResetPort to set the card to a known, default state. Use HTClearPort to clear all counters.
Step 2 Enable Extended (128-byte) Stream HeaderIf you will set up TCP, TCP VLAN, and UDP VLAN streams, use HTSetStructure and NS_PORT_TRANSMIT to enable the increased, 128-byte header length needed to accommodate an IPv6 header. Set ucEnableExtendedPayload to 1 to do this.
Enabling 128-byte stream headers reduces the maximum possible number of streams by half, from 512 to 256.Exceptions are the POS-3518As/AR and POS-3519As/AR modules. See “Test with IPv6 Streams on POS TeraMetrics Modules” on page 453.)
In addition, any time you switch between enabling and disabling the extended payload, all currently configured streams are deleted
Step 3 Set Up StreamsUse HTSetStructure and L3_DEFINE_IPV6_<n>_STREAM to configure test traffic. Here <n> represents one of the IPv6 stream types (including TCP and UDP; see table below). This function specifies the stream template (structure of test frames).
Original Function Description
HTResetPort Reset the card or module to a default state.
HTClearPort Clear the port counters.
Original Function Message Function iType1 Related Structure
HTSetStructure NS_PORT_TRANSMIT NSPortTransmit
Original Function Message Function iType1 Related Structure
HTSetStructure L3_DEFINE_IPV6_STREAM StreamIPv6
L3_DEFINE_IPV6_STREAM_VLAN StreamIPv6VLAN
L3_DEFINE_TCP_IPV6_STREAM StreamTCPIPv6
L3_DEFINE_TCP_IPV6_STREAM_VLAN StreamTCPIPv6VLAN
L3_DEFINE_UDP_IPV6_STREAM StreamUDPIPv6
L3_DEFINE_UDP_IPV6_STREAM_VLAN StreamUDPIPv6VLAN
Chapter 18: SmartMetrics/TeraMetrics TestingTest with IPv6 Streams on TeraMetrics Modules
SmartLibrary Overview and Procedures | 347
Defining Multiple Streams
To define multiple streams, use one of the L3_DEFINE_MULTI_<n>_IPV6_STREAM commands. Here are examples for TCP IPv6 streams:
Note: Using L3_DEFINE_<n>_IPV6_STREAM or L3_DEFINE_<n>_IPV6_MULTI_STREAM places the module into SmartMetrics mode. Use of commands that pertain to Traditional mode may then clear existing streams. Such commands include GIG_STRUC_TX, GIG_STRUC_ALT_TX, HTEcho, HTFillPattern, HTLatency, and HTVFD.
Modifying a Stream
Use one of the L3_MOD_<n>_IPV6_STREAM commands to modify an existing stream at a specified index. This function replaces the entire stream: to change one or more attributes, a complete structure is sent to the card. L3_MOD_<n>_IPV6_STREAM can modify the stream at index 0, but you should modify streams starting at index 1.
Here are examples for TCP IPv6 streams:
Step 4 Specify IPv6 Address InformationUse HTSetStructure and L3_TX_IPV6_ADDRESS to set the MAC address, IP address, and Gateway address.
You can use HTGetStructure and L3_TX_IPV6_ADDRESS_INFO to get the address information from the module.
Step 5 Specify IPv6 Protocol Information (Ping Settings)Use HTSetStructure and L3_TX_IPV6_PROTOCOL to set the IPv6 Ping settings (target IP address and Ping interval).
Note: Time values vary by module type: For TeraMetrics modules and the XLW-372xA/XFP-373xA modules, uiPingTime has units of 1 second. For the LAN-3101A/B module, uiPingTime has units of 100 milliseconds.
Original Function Message Function iType1 Related Structure
HTSetStructure L3_DEFINE_MULTI_TCP_IPV6_STREAM StreamTCPIPv6
L3_DEFINE_MULTI_TCP_IPV6_STREAM_VLAN
StreamTCPIPv6VLAN
Original Function Message Function iType1 Related Structure
HTSetStructure L3_MOD_TCP_IPV6_STREAM StreamTCPIPv6
L3_MOD_TCP_IPV6_STREAM_VLAN StreamTCPIPv6VLAN
Original Function Message Function iType1 Related Structure
HTSetStructure L3_TX_IPV6_ADDRESS Layer3IPv6Address
HTGetStructure L3_TX_IPV6_ADDRESS_INFO Same
Chapter 18: SmartMetrics/TeraMetrics TestingTest with IPv6 Streams on TeraMetrics Modules
348 | SmartLibrary Overview and Procedures
Step 6 Define the Schedule Mode (Gap-based or Rate-based)
You can specify that the streams generated by the port are scheduled and transmitted based either on interframe gap or frame rate. Specifically, you can select one of three options. Streams can be scheduled by:• Interframe Gap – A fixed number of bit times between frames.• Random IFG – A varying number of bit times between frames.• Frame Rate – A defined frames-per-second rate of transmission for each stream.
Bursty traffic can still be used.
The selected scheduling mode you assign to a port applies to all streams generated by the port. Test traffic is sent in a round-robin fashion, with one frame from each stream generated in sequence.
For all three scheduling options, a software mechanism on the card (termed the scheduler) calculates how to allocate the overall line bandwidth. It builds a static scheduling table that organizes all streams before any traffic is sent. The schedule table is static in that it does not vary as test traffic is sent—even though two of the scheduling options (Random IFG and Frame Rate) appear to be dynamic in behavior, because they allow individual stream frame rates and random interframe gaps.
Note: The scheduling mechanism for earlier SmartBits cards, such as the LAN-3201B/C, differs in important ways. Refer to Chapter 4, “Traffic Rates and Patterns” for detailed information on these cards.
Gap-based Traffic
With the two gap-based modes (IFG and Random IFG), you can control the frame size and gap size (or range of gap sizes) but not the frame rate.
For traffic scheduled by a fixed interframe gap, the card inserts your specified gap (number of bit times) between frames. It then sends out test traffic, with the selected frame size, at the maximum line rate.
For traffic scheduled by a random interframe gap, a random number generator on the card produces gaps of varying sizes, within the bounds you define by using NS_PORT_TRANSMIT. These gaps are inserted between frames. Then test traffic is sent with the selected frame size at the maximum line rate.
Original Function Message Function iType1 Related Structure
HTSetStructure L3_TX_IPV6_PROTOCOL Layer3IPv6Protocol
Chapter 18: SmartMetrics/TeraMetrics TestingTest with IPv6 Streams on TeraMetrics Modules
SmartLibrary Overview and Procedures | 349
Rate-based Traffic
For traffic scheduled by a frame rate, you can specify a different rate for each stream, but you cannot control the interframe gap. The gaps are calculated and inserted by the card automatically. The card inserts at the least the minimum interframe gap. If you specify frame rates that, altogether, are lower than the maximum line capacity, the “extra” bandwidth is divided among the streams for use as the interframe gap times.
How to Set the Schedule Mode
You can set the schedule mode in two ways:
Option 1: Use NS_PORT_TRANSMIT
Option 2: Use HTScheduleMode
Option 1 Use NS_PORT_TRANSMIT (Message Function)
Use HTSetStructure with NS_PORT_TRANSMIT to specify the schedule mode. Then use the functions below to set global characteristics for the port, as well as per-stream characteristics.
• For gap-based traffic, use NS_PORT_TRANSMIT to set the gap size.
• For rate-based traffic, use L3_DEFINE_STREAM_EXTENSION to set frame rate, background pattern, per-stream errors, and other stream characteristics (but not a gap size).
Original Function Description
NS_PORT_TRANSMIT Specify the desired mode. Then set port and per-stream characteristics as shown below.
For gap-based traffic: Use NS_PORT_TRANSMIT with NSPortTransmit to set the gap size, transmit mode, burst count, and other global (port) variables.
Optionally, you can use L3_DEFINE_STREAM_EXTENSION with L3StreamExtension to set stream characteristics such as background pattern and generated errors (but not frame rate).
For frame rate-based traffic: Use NS_PORT_TRANSMIT with NSPortTransmit to set the transmit mode, burst count, and other global (port) variables (but not gap size).
Use L3_DEFINE_STREAM_ EXTENSION with L3StreamExtension to set the frame rate (as well as stream characteristics such as background pattern and generated errors).
Chapter 18: SmartMetrics/TeraMetrics TestingTest with IPv6 Streams on TeraMetrics Modules
350 | SmartLibrary Overview and Procedures
Option 2 Use HTScheduleMode (Original Function)
Use HTScheduleMode to specify the schedule mode. Then use the other functions listed below to set global characteristics for the port, as well as per-stream characteristics.
Step 7 Set the Port Speed
Ports on the LAN-3300A/LAN-3301A modules can operate at 10Mbps, 100Mbps, or 1000Mbps. The LAN-3302A can operate at 10Mbps or 100Mbps.
For these module types, set the port speed.
Original Function Description
HTScheduleMode Specify the schedule mode. Then set port and per-stream characteristics as shown below.
For gap-based traffic:
HTGap Set the gap size.
HTTransmitMode Set the transmit mode (for example, single burst, multi-burst, or continuous).
HTBurstCount Set the burst count (number of packets per burst).
For frame rate-based traffic:
HTTransmitMode Set the transmit mode (for example, single burst, multi-burst, or continuous).
HTBurstCount Set the burst count (number of packets per burst).
HTSetStructure Use L3_DEFINE_STREAM_EXTENSION with L3StreamExtension to set the frame rate, background pattern, per-stream errors (as well as stream characteristics such as background pattern and generated errors).
Original Function Message Function iType1 Data Type/Structure
HTSetStructure ETH_SET_SPEED ULong
HTSetSpeed — —
Chapter 18: SmartMetrics/TeraMetrics TestingTest with IPv6 Streams on TeraMetrics Modules
SmartLibrary Overview and Procedures | 351
Step 8 Set Up MII Registers for Auto Negotiation (100Mbps/1000Mbps Only)
When the port speed will be 100Mbps or 1000Mbps, set up the auto negotiation.
Step 9 (Optional) Set up port groups.
To set up a port group, use HGSetGroup to define the port group and HGAddToGroup to add ports to a group.
Step 10 Perform IPv6 Neighbor Discovery.
Use HTSetCommand with L3_START_ARPS to perform IPv6 neighbor discovery.
Note: See “Set Up IPv6 Neighbor Discovery” on page 357 for the steps to configure Neighbor Discovery message exchanges.
Original Function Message Function iType1 Related Structure Description
HTFindMIIAddress — — Find the first MII PHY address with a device attached (100 Mbps only).
HTReadMII — — Read a specified MII register (100 Mbps only).
HTWriteMII — — Write to a specified MII register (100 Mbps only).
HTGetStructure ETH_FIND_MII_ADDR_INFO
ETHMII Find the first MII PHY address with a device attached.
HTGetStructure ETH_READ_MII_INFO ETHMII Read (or write to) a specified MII register.
HTSetStructure ETH_WRITE_MII ETHMII Read (or write to) a specified MII register.
Original Function Message Function iType1 Related Structure
HTSetCommand L3_START_ARPS N/A
Chapter 18: SmartMetrics/TeraMetrics TestingTest with IPv6 Streams on TeraMetrics Modules
352 | SmartLibrary Overview and Procedures
Step 11 Send test traffic, then stop the test.
Use HTRun or HGRun to run the test.
If you run the test with continuous traffic, use HTStop or HGStop to stop the test.
Note: For Latency histogram results, it is important to initialize the timestamps on each module before doing a group start. To do this, use the “Timestamp-Initialization Sequence.”
End of Required Steps for Basic Setup
This completes the basic steps needed to transmit test traffic. The usefulness of your test, however, depends on getting test results. See “Getting Test Results” on page 353 for the steps to use counters, capture, or histograms to measure test traffic.
Original Function Description
HTRun/HTStop Transmit test frames, then stop the test (if running continuous traffic rather than step or burst mode).
HGRun/HGStep/HGStop
Chapter 18: SmartMetrics/TeraMetrics TestingTest with IPv6 Streams on TeraMetrics Modules
SmartLibrary Overview and Procedures | 353
Getting Test Results
Your test can provide three types of results. These are:– Counters– Captured data — or —– Histograms
Counters Counters are always available. You need not enable them or set them up explicitly. You can get counter information during the test or after it stops.
Captured data and histograms
You can also retrieve captured data or histograms, but not both in the same test. For these, you must specify the type of results desired, and you must enable the function. You set up data capture or histogram results before you start your test. You obtain either type of results after you run the test.
How to Get Counter Information
Use HTGetStructure with NS_IPV6_COUNTER_INFO to retrieve IPv6 counters.
Use HTGetStructure with NS_IPV6_RATE_INFO to get rate information for the IPv6 streams.
How to Set Up Data Capture
Use the following steps to set up data capture. You can enable either data capture or SmartMetrics histogram results (see “How to Set Up SmartMetrics Histograms” on page 355).
Step 1 Set up the capture parameters.
Use HTSetStructure with NS_CAPTURE_SETUP(NSCaptureSetup) to specify the capture mode, length, and event.
Original Function Message Function iType1 Structure/Description
HTGetStructure NS_IPV6_COUNTER_INFO NSIPv6CounterInfo
HTGetStructure NS_IPV6_RATE_INFO NSIPv6RateInfo
Original Function Message Function iType1 Related Structure
HTSetStructure NS_CAPTURE_SETUP NSCaptureSetup
Chapter 18: SmartMetrics/TeraMetrics TestingTest with IPv6 Streams on TeraMetrics Modules
354 | SmartLibrary Overview and Procedures
Capture Mode. Valid options for NSCaptureSetup(ulCaptureMode) include:
Capture Length. Valid options for NSCaptureSetup(ulCaptureLength) include:
Capture Event. The CAPTURE_EVENTS element in NSCaptureSetup defines what frame types should be captured. Valid options for NSCaptureSetup(ulCaptureEvents) include:
Step 2 Start the capture, then stop it.
Capture Mode Description
CAPTURE_MODE_FILTER_ON_EVENTS Capture only packets with the specified event, such as CRC errors, undersize packets, or oversize packets.
CAPTURE_MODE_START_ON_EVENTS Capture all packets following the specified event. For example, begin capture when the first packet with a CRC error is received, then capture all packets.
CAPTURE_MODE_STOP_ON_EVENTS Capture all packets until the specified event. For example, capture all packets until the first packet with a CRC error is received, then stop the capture.
Capture Length Description
CAPTURE_LENGTH_ENTIRE_FRAME Capture complete frame.
CAPTURE_LENGTH_1ST_64_BYTES Capture only the first 64 bytes in the frame.
CAPTURE_LENGTH_LAST_64_BYTES Capture only the last 64 bytes in the frame.
Capture Event Description
CRC_ERRORS Capture all frames with CRC errors.
IP_CHECKSUM_ERROR Capture all frames with IP checksum errors.
DATA_INTEGRITY_ERROR Capture all frames in which the payload contents have become corrupted.
RX_TRIGGER Capture all frames that contain receive trigger patterns.
Original Function Message Function iType1 Description
HTSetCommand NS_CAPTURE_START Clear the buffer and start the capture.
NS_CAPTURE_STOP Stop capture.
Chapter 18: SmartMetrics/TeraMetrics TestingTest with IPv6 Streams on TeraMetrics Modules
SmartLibrary Overview and Procedures | 355
Step 3 Get the captured data.
Use HTGetStructure with NS_CAPTURE_COUNT_INFO to find the number of frames in the buffer.
Use HTGetStructure with NS_CAPTURE_DATA_INFO to get the captured frames.
How to Set Up SmartMetrics Histograms
Histograms provide in-depth test results, including sequence and latency information.
Histogram information is gathered on the receiving card.
Step 1 Enable the histogram type.
For SmartMetrics histograms results, specify the histogram type. All SmartMetrics cards and modules support the same histogram types.
Original Function Message Function iType1 Related Structure
HTGetStructure NS_CAPTURE_COUNT_INFO NSCaptureCountInfo
NS_CAPTURE_DATA_INFO NSCaptureDataInfo
Original Function Message Function iType1 Related Structure/Description
HTSetStructure NS_HIST_COMBO_PER_STREAM NSHistComboPerStream
Gives an overall picture of latency per stream. Provides the following results:
Latency per Stream. Shows minimum, maximum, and average latency values over the course of the test.
Latency Distribution. Shows the occurrence of specific latency values per stream.
Sequence Tracking. Reports whether or not frames were received in sequence per stream.
HTSetStructure NS_HIST_LATENCY_OVER_TIME NSHistLatencyOverTime
Provides Latency over Time histogram on the receive module.
HTSetCommand NS_HIST_RAW_SIGNATURE Signature information only, showing transmit time, receive time, and delta in microseconds.
HTSetCommand NS_HIST_SEQUENCE_PER_STREAM Sequence information only. Reports whether or not frames were received in sequence per stream.
HTSetStructure NS_HIST_LATENCY_DIST_PER_STREAM NSHistComboPerStream
Latency distribution information only. Shows the occurrence of specific latency values per stream.
Chapter 18: SmartMetrics/TeraMetrics TestingTest with IPv6 Streams on TeraMetrics Modules
356 | SmartLibrary Overview and Procedures
Step 2 Set up port groups.
For SmartMetrics histogram results, you must set up a port group. Histogram results require a group start. Use HGSetGroup and HGAddtoGroup to define the port group and to add ports to a group.
Step 3 Gather histogram information.
After the test runs, gather the results for the SmartMetrics histogram you specified in Step 1. Use HTGetStructure with the appropriate iType1, as shown below.
Original Function Description
HGSetGroup Define a group of SmartBits ports.
HGAddtoGroup Add ports to the group. You control grouped ports by using the HG commands.
Original Function Message Function iType1 Related Structure/Description
HTGetStructure NS_HIST_COMBO_PER_STREAM_INFO NSHistComboPerStreamInfo
Latency Distribution histogram results.
NS_HIST_LATENCY_OVER_TIME_INFO NSHistLatencyOverTimeInfo
Latency over Time histogram results.
NS_HIST_RAW_SIGNATURE_INFO NSHistRawSignatureInfo
Signature information only.
NS_HIST_SEQUENCE_PER_STREAM_INFO NSSequenceInfo
Sequence Tracking histogram results.
NS_HIST_LATENCY_DIST_PER_STREAM_INFO NSHistLatencyDistPerStreamInfo
Latency Distribution histogram results.
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up IPv6 Neighbor Discovery
SmartLibrary Overview and Procedures | 357
Set Up IPv6 Neighbor DiscoveryNeighbor Discovery is used in IPv6 to enable host ports to detect neighbor ports, and it enables hosts to update their caches with IP addresses.
TeraMetrics-based modules that are IPv6-capable can perform Neighbor Discovery in either of two modes:
• Basic Neighbor DiscoveryThe basic function builds and sends the streams with Neighbor Solicitation and Neighbor Advertisement, and resending Neighbor Solicitation messages in case it messages are unresolved. This mode allows for up to 512 base streams.
• Virtual Neighbor DiscoveryWith this mode, each base stream may be used to generate numerous virtual streams, each of which sends Neighbor Solicitation messages. The virtual streams (cyclic flows) are created by altering the source IP address, source MAC address, or destina-tion IP address, or any combination of two of these. The specified values are incre-mented as each virtual stream is sent by the transmitting test port.
Applicable Commands
Table 18-8 is a summary of commands you can use. Not all commands are required. This list is an overview.
A basic setup See “Example of Setup Steps” on page 358 for a setup procedure.
Table 18-8. Applicable Commands: Neighbor Discovery
Applicable Commands
What the Commands Do Original Function Message Function iType1/Notes
Reset card to the default state.
HTResetPort See “Example of Setup Steps” on page 358.
Configure the ARP mode. HTSetStructure NS_ARP_CONFIG
Optional. Set up IPv4 streams.
HTSetStructure L3_DEFINE_<n>_STREAML3_DEFINE_<n>_STREAM_EXTENSIONL3_DEFINE_MULTI_<n>_STREAML3_DEFINE_MULTI_<n>_STREAM_EXTENSIONL3_MOD_<n>_STREAM
Set up IPv6 streams. HTSetStructure L3_DEFINE_<n>_IPV6_STREAM
Configure the ARP gap. HTSetStructure L3_SET_ARP_GAP
Set up data capture. HTSetStructure NS_CAPTURE_SETUP
Start data capture. HTSetCommand NS_CAPTURE_START
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up IPv6 Neighbor Discovery
358 | SmartLibrary Overview and Procedures
Example of Setup Steps
Here is a complete summary of the steps to set up Neighbor Discovery on TeraMetrics-based modules with IPv6 streams.
Step 1 Connect to the SmartBits chassis and reserve ports.
See the following:
• “Establishing a Link from the PC to SmartBits” on page 87.
• “How to Identify Hubs, Slots, and Ports” on page 94.
Step 2 Reset the card
Use HTResetPort to set the card to a known, default state.
Applicable Commands
What the Commands Do Original Function Message Function iType1/Notes
Clear counters. HTClearPort See “Example of Setup Steps” on page 358.
Start Neighbor Discovery and ARPs.
HTSetCommand L3_START_ARPS
Stop data capture. HTSetCommand NS_CAPTURE_STOP
Get the capture count. HTGetStructure NS_CAPTURE_COUNT_INFO
Get the captured packets. HTGetStructure NS_CAPTURE_DATA_INFO
Analyze captured packets. HTGetStructure ETH_EXTENDED_COUNTER_INFO
Get ARPs or Neighbor Discovery status.
HTGetStructure NS_ARP_STATUS_INFO
Resend ARPs or Neighbor Discovery messages.
HTSetCommand L3_ARP_UNRESOLVED
Table 18-8. Applicable Commands: Neighbor Discovery (continued)
Original Function Description
HTResetPort Reset the card or module to a default state.
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up IPv6 Neighbor Discovery
SmartLibrary Overview and Procedures | 359
Step 3 Configure the ARP mode.Use HTSetStructure with NS_ARP_CONFIG to select either the Basic Neighbor Discov-ery mode (ucARPMode = ARP_NORMAL_MODE) or the Virtual Neighbor Discovery mode (ucARPMode = ARP_VIRTUAL_MODE).
Step 4 (Optional) Set up IPv4 streams.Optionally, set up IPv4 streams. Use HTSetStructure with L3_DEFINE_<n>_STREAM to set up at least one stream on the transmitting test port and the receiving test port. Here, <n> represents the stream type and can be IP, IPX, UDP, TCP, or SmartBits. This func-tion specifies the stream template—that is, the structure of frames to be sent.
Stream types and command forms include the following:
Notes: • See “Set Up SmartMetrics Tests on TeraMetrics-based Modules” on page 329 for additional options in setting up multiple streams, modifying stream values, and setting up VLANs.
• Using L3_DEFINE_<n>_STREAM or L3_DEFINE_<n>_MULTI_STREAM places the module into SmartMetrics mode. Use of commands that pertain to Traditional mode may then clear existing streams. Such commands include GIG_STRUC_TX, GIG_STRUC_ALT_TX, HTEcho, HTFillPattern, HTLatency, and HTVFD.
Continues –>
Original Function Message Function iType1 Related Structure
HTSetStructure NS_ARP_CONFIG NSARPConfig
Original Function Message Function iType1 Related Structure
HTSetStructure L3_DEFINE_<n>_STREAM Stream<n>
L3_DEFINE_<n>_STREAM_EXTENSION StreamExtension
L3_DEFINE_MULTI_<n>_STREAM Stream<n>
L3_DEFINE_MULTI_<n>_STREAM_EXTENSION
StreamExtension
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up IPv6 Neighbor Discovery
360 | SmartLibrary Overview and Procedures
Step 5 Set up IPv6 streams.Use HTSetStructure and L3_DEFINE_IPV6_<n>_STREAM to configure at least one stream on the transmitting port and one stream on the receiving port. Options for stream types include the following (see also the Notes below):
Notes: • See “Test with IPv6 Streams on TeraMetrics Modules” on page 343 for additional options in setting up IPv6 streams.
• Using L3_DEFINE_<n>_IPV6_STREAM or L3_DEFINE_<n>_IPV6_MULTI_STREAM places the module into SmartMetrics mode. Use of commands that pertain to Traditional mode may then clear existing streams. Such commands include GIG_STRUC_TX, GIG_STRUC_ALT_TX, HTEcho, HTFillPattern, HTLatency, and HTVFD.
Step 6 Set the ARP gap.
Use L3_SET_ARP_GAP to define the gap between each virtual Neighbor Discovery request. The minimum resolution for this gap is 2 milliseconds.
The Neighbor Discovery gap determines the rate at which Neighbor Discovery messages are sent. The minimum rate that can set with a script file is 100 nanoseconds.
This command applies on a per-port basis.
Step 7 Set up capture on the transmitting and receiving ports.
Use HTSetStructure with NS_CAPTURE_SETUP(NSCaptureSetup) to specify the capture mode, length, and event. See “How to Set Up Data Capture” on page 353 for detailed steps on setting up capture.
Original Function Message Function iType1 Related Structure
HTSetStructure L3_DEFINE_IPV6_STREAM StreamIPv6
L3_DEFINE_IPV6_STREAM_VLAN StreamIPv6VLAN
L3_DEFINE_TCP_IPV6_STREAM StreamTCPIPv6
L3_DEFINE_TCP_IPV6_STREAM_VLAN StreamTCPIPv6VLAN
L3_DEFINE_UDP_IPV6_STREAM StreamUDPIPv6
L3_DEFINE_UDP_IPV6_STREAM_VLAN StreamUDPIPv6VLAN
Original Function Message Function iType1 Related Structure
HTSetStructure L3_SET_ARP_GAP ULong
Original Function Message Function iType1 Related Structure
HTSetStructure NS_CAPTURE_SETUP NSCaptureSetup
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up IPv6 Neighbor Discovery
SmartLibrary Overview and Procedures | 361
Step 8 Start capture on the transmitting and receiving ports.
Use NS_CAPTURE_START to start the capture.
Step 9 Clear all counters
Use HTClearPort to clear all counters.
Step 10 Start Neighbor Discovery and ARPs.
Use HTSetCommand with L3_START_ARPS to start Neighbor Discovery (for IPV6 streams) and ARPs (for IPv4 streams).
Step 11 Wait for Neighbor Discovery and ARPs to complete.
You can use NS_ARP_STATUS_INFO to determine whether or not streams have been resolved or received a response (field ulUnresolved).
Step 12 Stop the capture.
Use NS_CAPTURE_STOP to stop the capture.
Continues –>
Original Function Message Function iType1 Related Structure
HTSetCommand NS_CAPTURE_START —
Original Function Description
HTClearPort Clear the port counters.
Original Function Message Function iType1 Related Structure
HTSetCommand L3_START_ARPS —
Original Function Message Function iType1 Related Structure
HTGetStructure NS_ARP_STATUS_INFO NSARPStatusInfo
Original Function Message Function iType1 Related Structure
HTSetCommand NS_CAPTURE_STOP —
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up IPv6 Neighbor Discovery
362 | SmartLibrary Overview and Procedures
Step 13 Get the capture count.
After the test completes, use NS_CAPTURE_COUNT_INFO to get the number of captured packets.
Step 14 Get the captured packets.
Use NS_CAPTURE_DATA_INFO to get the captured packets.
Step 15 Analyze the captured packets on exchanged streams.
Use ETH_EXTENDED_COUNTER_INFO to get counters on ARP requests and replies.
Step 16 Get ARPs or Neighbor Discovery status.
Step 17 Resend ARPs or Neighbor Discovery messages.
You can use L3_ARP_UNRESOLVED to re-ARP or resend Neighbor Solicitation messages for streams whose initial ARPs or Neighbor Discovery did not get resolved.
Original Function Message Function iType1 Related Structure Description
HTGetStructure NS_CAPTURE_COUNT_INFO NSCaptureCountInfo Find the number of frames in the capture buffer.
Original Function Message Function iType1 Related Structure Description
HTGetStructure NS_CAPTURE_DATA_INFO NSCaptureDataInfo Retrieve a captured frame from the capture buffer.
Original Function Message Function iType1 Related Structure
HTGetStructure ETH_EXTENDED_COUNTER_INFO ETHExtendedCounterInfo
Original Function Message Function iType1 Related Structure
HTGetStructure NS_ARP_STATUS_INFO NSARPStatusInfo
Original Function Message Function iType1 Related Structure
HTSetCommand L3_ARP_UNRESOLVED —
Chapter 18: SmartMetrics/TeraMetrics TestingTest with IPv6 Over IPv4 Tunneled Streams
SmartLibrary Overview and Procedures | 363
Test with IPv6 Over IPv4 Tunneled StreamsTunneling refers to the method of encapsulating IPv6 datagrams within IPv4 packets so that they can be transported across regions of IPv4 routing topology.
The following procedure gives the steps to set up tests with IPv6-over-IPv4 tunneling. It may be used with the LAN-3101A/B family of modules (including LAN-3102A and LAN-3111A/AS) and with LAN and POS TeraMetrics-based modules.
Applicable Commands
Table 18-9 is a summary of commands you can use. Not all commands are required. This list is an overview.
A basic setup See “Example of Setup Steps” on page 364 for a basic setup procedure, as well as optional commands and actions.
Table 18-9. Applicable Commands: IPv6-over-IPv4 Tunneling
Applicable Commands
What the Commands DoUse Original Function With Message Function iType1
Reset card to the default state. HTResetPort See “Example of Setup Steps” on page 364.
Clear counters. HTClearPort See “Example of Setup Steps” on page 364.
Set up streams. HTSetStructure L3_DEFINE_<n>_IPV6_STREAM
Note: Using this command puts the module into the SmartMetrics mode. The library may then generate error messages in response to commands that pertain to Traditional mode operation. See the Note on page 364.
Create IPv6/IPV4 tunneled streams.
– or –
HTSetStructure NS_DEFINE_IPV6_OVER_IPV4_TUNNELING
Modify existing streams to create IPv6/IPV4 tunneling.
HTSetStructure NS_MOD_IPV6_OVER_IPV4_TUNNELING
Optional. Copy and create new tunneled streams.
HTSetStructure NS_DEFINE_MULTI_IPV6_OVER_IPV4_TUNNELING
Set up data capture on the receiving port.
HTSetStructure NS_CAPTURE_SETUP
Start data capture. HTSetCommand NS_CAPTURE_START
Transmit test frames. HTRun For single-port start.
Chapter 18: SmartMetrics/TeraMetrics TestingTest with IPv6 Over IPv4 Tunneled Streams
364 | SmartLibrary Overview and Procedures
Example of Setup Steps
Here is a more detailed description of the steps summarized above.Step 1 Reset the Card
Use HTResetPort to set the card to a known, default state.
Step 2 Clear All Counters
Use HTClearPort to clear all counters.
Step 3 Set Up Streams
Use HTSetStructure and L3_DEFINE_IPV6_<n>_STREAM to configure test traffic. Here <n> represents one of the IPv6 stream types. This function specifies the stream template (structure of test frames).
Note: Using L3_DEFINE_<n>_IPV6_STREAM places the module into SmartMetrics mode. Use of commands that pertain to Traditional mode may then clear existing streams. Such commands include GIG_STRUC_TX, GIG_STRUC_ALT_TX, HTEcho, HTFillPattern, HTLatency, and HTVFD.
Continues –>
Applicable Commands
What the Commands DoUse Original Function With Message Function iType1
Stop data capture. HTSetCommand NS_CAPTURE_STOP
Stop the test. HTStop See “Example of Setup Steps” on page 346.
Get the captured data. HTGetStructure NS_CAPTURE_COUNT_INFONS_CAPTURE_DATA_INFO
Table 18-9. Applicable Commands: IPv6-over-IPv4 Tunneling (continued)
Original Function Description
HTResetPort Reset the card or module to a default state.
Original Function Description
HTClearPort Clear the port counters.
Chapter 18: SmartMetrics/TeraMetrics TestingTest with IPv6 Over IPv4 Tunneled Streams
SmartLibrary Overview and Procedures | 365
Step 4 Define IPv6-over-IPv4 Tunneling
You can do this in two ways:1 Use HTSetStructure and NS_DEFINE_IPV6_OVER_IPV4_TUNNELING. This
command takes an array of structures.
2 Use HTSetStructure and NS_MOD_IPV6_OVER_IPV4_TUNNELING. This com-mand modifies a stream at the specified index. It can be used to create new IPv6-over-IPv4 tunneled streams.
Step 5 Copy and create new tunneled streams.
Use NS_DEFINE_MULTI_IPV6_OVER_IPV4_TUNNELING to create additional tunneled streams, based on your original stream definition. Starting index is iType2; count is iType3.
Original Function Message Function iType1 Related Structure
HTSetStructure NS_DEFINE_IPV6_OVER_IPV4_TUNNELING NSIPv6OverIPv4Tunneling
Original Function Message Function iType1 Related Structure
HTSetStructure NS_MOD_IPV6_OVER_IPV4_TUNNELING NSIPv6OverIPv4Tunneling
Original Function Message Function iType1 Related Structure
HTSetStructure NS_DEFINE_MULTI_IPV6_OVER_IPV4_TUNNELING
NSIPv6OverIPv4Tunneling
Chapter 18: SmartMetrics/TeraMetrics TestingTest with IPv6 Over IPv4 Tunneled Streams
366 | SmartLibrary Overview and Procedures
Step 6 Setup and Start Capture on the Receiving Ports
Use HTSetStructure with NS_CAPTURE_SETUP to configure the capture engine for receiving test ports.
Then use HTSetCommand with NS_CAPTURE_START to start capture.
Note: See “Getting Test Results” on page 367 for detailed steps on setting up capture.
Step 7 Send test traffic, then stop the test.
Use HTRun to run the test.
If you run the test with continuous traffic, use HTStop or HGStop to stop the test.
Step 8 Stop Capture on the Receiving Ports
Stop the capture by using HTSetCommand with NS_CAPTURE_STOP.
Step 9 Get the Number of Captured Frames
Retrieve the number of captured frames on the receiving ports.
Use HTGetStructure with NS_CAPTURE_COUNT_INFO to get the capture count.
Continues –>
Original Function Message Function iType1 Related Structure
HTSetStructure
HTSetCommand
NS_CAPTURE_SETUP
NS_CAPTURE_START
NSCaptureSetup
—
Original Function Description
HTRun/HTStop Transmit test frames, then stop the test (if running continuous traffic rather than step or burst mode).
Original Function Message Function iType1 Related Structure
HTSetCommand NS_CAPTURE_STOP —
Original Function Message Function iType1 Related Structure
HTGetStructure NS_CAPTURE_COUNT_INFO NSCaptureCountInfo
Chapter 18: SmartMetrics/TeraMetrics TestingTest with IPv6 Over IPv4 Tunneled Streams
SmartLibrary Overview and Procedures | 367
Step 10 Get the Captured Frames
Retrieve the captured frames on the receiving ports.
Use HTGetStructure with NS_CAPTURE_DATA_INFO to get the capture count.
End of Required Steps for Basic Setup
This completes the basic steps needed to transmit test traffic.
Getting Test Results
This section provides additional information about setting up capture.
How to Set Up Data Capture
Use the following steps to set up data capture.Step 1 Set up the capture parameters.
Use HTSetStructure with NS_CAPTURE_SETUP(NSCaptureSetup) to specify the capture mode, length, and event.
Capture Mode. Valid options for NSCaptureSetup(ulCaptureMode) include:
Original Function Message Function iType1 Related Structure
HTGetStructure NS_CAPTURE_DATA_INFO NSCaptureDataInfo
Original Function Message Function iType1 Related Structure
HTSetStructure NS_CAPTURE_SETUP NSCaptureSetup
Capture Mode Description
CAPTURE_MODE_FILTER_ON_EVENTS Capture only packets with the specified event, such as CRC errors, undersize packets, or oversize packets.
CAPTURE_MODE_START_ON_EVENTS Capture all packets following the specified event. For example, begin capture when the first packet with a CRC error is received, then capture all packets.
CAPTURE_MODE_STOP_ON_EVENTS Capture all packets until the specified event. For example, capture all packets until the first packet with a CRC error is received, then stop the capture.
Chapter 18: SmartMetrics/TeraMetrics TestingTest with IPv6 Over IPv4 Tunneled Streams
368 | SmartLibrary Overview and Procedures
Capture Length. Valid options for NSCaptureSetup(ulCaptureLength) include:
Capture Event. The CAPTURE_EVENTS element in NSCaptureSetup defines what frame types should be captured. Valid options for NSCaptureSetup(ulCaptureEvents) include:
Step 2 Start the capture, then stop it.
Start the capture, then transmit test traffic. When appropriate, stop the capture.
Step 3 Get the captured data.
Use HTGetStructure with NS_CAPTURE_COUNT_INFO to find the number of frames in the buffer.
Use HTGetStructure with NS_CAPTURE_DATA_INFO to get the captured frames.
Capture Length Description
CAPTURE_LENGTH_ENTIRE_FRAME Capture complete frame.
CAPTURE_LENGTH_1ST_64_BYTES Capture only the first 64 bytes in the frame.
CAPTURE_LENGTH_LAST_64_BYTES Capture only the last 64 bytes in the frame.
Capture Event Description
CRC_ERRORS Capture all frames with CRC errors.
IP_CHECKSUM_ERROR Capture all frames with IP checksum errors.
DATA_INTEGRITY_ERROR Capture all frames in which the payload contents have become corrupted.
RX_TRIGGER Capture all frames that contain receive trigger patterns.
Original Function Message Function iType1 Description
HTSetCommand NS_CAPTURE_START Clear the buffer and start the capture.
NS_CAPTURE_STOP Stop capture.
Original Function Message Function iType1 Related Structure
HTGetStructure NS_CAPTURE_COUNT_INFO NSCaptureCountInfo
NS_CAPTURE_DATA_INFO NSCaptureDataInfo
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up Tests for LAN-3710A 10GbE Modules
SmartLibrary Overview and Procedures | 369
Set Up Tests for LAN-3710A 10GbE ModulesUse the following steps to set up SmartMetrics tests with the LAN-3710A 10BASE-Sx Ethernet modules, including the LAN-3710AE, LAN-3710AL, and LAN-3710AS.
Applicable Commands
Table 18-10 is a summary of commands you can use with this module. Not all commands are required. This list is an overview.
A basic setup See “Example of Setup Steps” on page 370 for a basic setup procedure, as well as optional commands and actions.
Table 18-10.Applicable Commands: 10Gb Ethernet (LAN-3710A)
Applicable Commands
What the Commands Do Original Function Message Function iType1/Notes
Reset card to the default state. HTResetPort See “Example of Setup Steps” on page 370.
Clear counters. HTClearPort See “Example of Setup Steps” on page 370.
Set up streams. HTSetStructure L3_DEFINE_<n>_STREAML3_MOD_<n>_STREAM
You can configure eight streams. You must configure at least one stream on the transmitting port to receive valid results on the receiving port.
Use L3_DEFINE_<n>_STREAM to set up streams 1 through 7.
Use L3_MOD_<n>_STREAM to set up stream 0.
(Optional) Set up additional stream characteristics.
HTSetStructure L3_DEFINE_STREAM_EXTENSIONL3_MOD_STREAM_EXTENSION
Set up the stream schedule table. HTSetStructure NS_STREAM_SCHEDULE
Set up data capture. HTSetStructure NS_CAPTURE_SETUP
(Optional) Set up triggers. HTSetStructure GIG_STRUC_TRIGGER
(Optional) Set up port groups. HGSetGroupHGAddtoGroup
See “Example of Setup Steps” on page 370.
Start data capture. HTSetCommand NS_CAPTURE_START
Transmit test frames. HTRun For single-port start.
HGRunHGStep
For group start.
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up Tests for LAN-3710A 10GbE Modules
370 | SmartLibrary Overview and Procedures
Example of Setup Steps
Here is an example of how to set up your test. It assumes no previous configuration. It shows selected commands, not all possible commands or actions.
Step 1 Reset the Card and Clear All Counters
Use HTResetPort to set the card to a known, default state. Use HTClearPort to clear all counters.
Step 2 Set Up Streams
You can set up eight streams on the module. You can configure the streams at indexes 1 through 7 explicitly. The stream at index 0 is the default stream. You must configure at least one stream on the transmitting port to receive valid results on the receiving port.To configure streams at index 1 through 7: Use HTSetStructure with L3_DEFINE_<n>_STREAM. The maximum number of streams that can be created using L3_DEFINE_IP_STREAM is 7. An inactive default stream will be the first stream created, at index 0.
To configure the default stream at index 0: Use HTSetStructure with L3_MOD_<n>_STREAM.
Both functions specify the stream template (the structure of frames to be sent). In these commands, <n> represents the stream type and can be IP, IPX, UDP, TCP, orSmartBits).
Applicable Commands
What the Commands Do Original Function Message Function iType1/Notes
Stop the test. HTStopHGStop
See “Example of Setup Steps” on page 370.
Stop data capture. HTSetCommand NS_CAPTURE_STOP
Get captured data. HTGetStructure NS_CAPTURE_COUNT_INFONS_CAPTURE_DATA_INFONS_CAPTURE_STATS_INFO
Table 18-10.Applicable Commands: 10Gb Ethernet (LAN-3710A)
Optional/RelatedOptional or related commands and actions (if applicable) are shown in a shaded box. These actions are not required for a basic test setup.
Original Function Description
HTResetPort Reset the card or module to a default state.
HTClearPort Clear the port counters.
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up Tests for LAN-3710A 10GbE Modules
SmartLibrary Overview and Procedures | 371
Use L3_DEFINE_STREAM_EXTENSION to define additional stream characteristics, (including frame rate, BGPPatternIndex, and data integrity check) for streams 1 through 7. Use L3_MOD_STREAM_EXTENSION to do this for stream 0.
Note: Two elements in the L3StreamExtension structure do not apply to theLAN-3710A module: ulTxMode and ucIPManipulateMode.
Defining Multiple Streams. To define multiple streams, use L3_DEFINE_MULTI_<n>_STREAM, where <n> represents the stream type.
Modifying a Stream. Use L3_MOD_<n>_STREAM to modify an existing stream at a specified index. This function replaces the entire stream: to change one or more attributes, a complete structure is sent to the card. L3_MOD_<n>_STREAM can modify the stream at index 0, as well as index 1 through 7.
Step 3 Set Up the Stream Schedule Table
You can set up the card to send streams in any order, and with any number of repetitions for each stream in the transmit cycle. Here are two examples.
Example 1: In this example, all eight streams are sent, but in a varied order and with different degrees of repetition, as follows:
Original Function Message Function iType1 Related Structure
HTSetStructure L3_DEFINE_<n>_STREAM (For streams at index 1 - 7) L3Stream<n>
L3_DEFINE_STREAM_EXTENSION (For streams at index 1 - 7) L3StreamExtension
L3_MOD_<n>_STREAM (For stream at index 0) L3Stream<n>
L3_MOD_STREAM_EXTENSION (For stream at index 0) L3StreamExtension
L3_DEFINE_MULTI_<n>_STREAM L3Stream<n>
L3_DEFINE_MULTI_STREAM_EXTENSION L3StreamExtension
Stream # Repeat Count Result
0 4 Frames from the eight streams will be transmitted in the following order (by stream #):
0 2 1 4 3 6 5 7
In each transmit cycle, the actual frame sequence (by stream #) will be:
0 0 0 0 2 1 1 1 1 4 3 3 3 3 3 3 3 3 6 5 5 5 5 5 5 5 5 7
2 1
1 4
4 1
3 8
6 1
5 8
7 1
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up Tests for LAN-3710A 10GbE Modules
372 | SmartLibrary Overview and Procedures
Example 2: In this example, odd-numbered streams are sent more than once, again with different degrees of repetition, as follows:
Step 4 Set Up Triggers
If you set capture on received triggers (RX_TRIGGER in Step 4), specify the trigger pattern. Trigger setup applies to the receiving port. With LAN-3710A modules, you can to define trigger patterns to the bit level, using GIG_STRUC_TRIGGER and GIGTrigger.
You can define one or (optionally) two trigger patterns, by using ucTrigger1Data and ucTrigger2Data. Only the first six bytes of each pattern are used.
Use the two trigger mask fields ucTrigger1Mask and ucTrigger2Mask to specify which bits in the Trigger1 or Trigger2 pattern should be considered.
Table 18-11 illustrates an example of setting the ucTrigger1Mask and ucTrigger2Mask values and shows the resulting bytes in the active trigger pattern.
Stream # Repeat Count Result
1 1 Frames from the four streams will be transmitted in the following order (by stream #):
1 2 3 3 3 3 5 5 7 7
In each transmit cycle, the actual frame sequence (by stream #) will be:
11 1 1 133 3 3 33 3 3 3 3 3 3 33 3 3 3 3 3 3 3 3 3 3 3 3 3 3 355 5 5 5 5 5 5 57 7 7 7 7 7 7 77 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7
1 4
3 1
3 4
3 8
3 16
5 1
5 8
7 8
7 16
Original Function Message Function iType1 Data Type/Structure
HTSetStructure NS_STREAM_SCHEDULE NSStreamScheduleEntry
Original Function Message Function iType1 Related Structure Description
HTSetStructure GIG_STRUC_TRIGGER GIGTrigger Define trigger data and mask on the receiving port.
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up Tests for LAN-3710A 10GbE Modules
SmartLibrary Overview and Procedures | 373
Important: On the LAN-3710A, the default value for both ucTrigger1Mask and ucTrigger2Mask is 0x00. As a result, you must set an explicit value for the mask field if you wish the trigger pattern to be detected on the receiving port. If you set the mask to all FFs (all ones), any trigger pattern (ucTrigger1Data or ucTrigger2Data) will be detected.
The offset fields (ucTrigger1Offset and ucTrigger2ucTrigger1Offset) specify where in the received frame to start checking for the trigger pattern. An offset of zero refers to the first data byte of the frame. This default setting puts the Trigger1 pattern at the location of MAC Destination address.
Step 5 (Optional) Set Up Port Groups
To set up a port group, use HGSetGroup to define the port group and HGAddtoGroup to add ports to a group.
Step 6 Start capture, if selected.
Use NS_CAPTURE_START to start data capture, when desired.
Step 7 Send Test Traffic
Use HTRun or HGRun to run the test. If you run the test with continuous traffic, use HTStop or HGStop to stop the test.
Table 18-11.Example of Trigger Setup
Byte Data Mask Active Trigger Value
MSB 0x11 0xFF 0x11 00000001 00000001
1 0x22 0xFF 0x22 00000010 00000010
2 0x33 0xFF 0x33 00000011 00000011
3 0x44 0x0F 0x04 00000000 00000100
4 0x55 0xF0 0x50 00000101 00000000
LSB 0x8A 0xF0 0x80 00001000 00000000
Original Function Message Function iType1 Related Structure
HTSetCommand NS_CAPTURE_START —
Original Function Description
HTRun/HTStop Transmit test frames, then stop the test (if running continuous traffic rather than step or burst mode).
HGRun/HGStep/HGStop
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up Tests for LAN-3710A 10GbE Modules
374 | SmartLibrary Overview and Procedures
Step 8 Stop the Test
If you run the test with continuous traffic, use HTStop or HGStop to stop the test.
Step 9 Stop capture (if selected).
Use NS_CAPTURE_STOP to stop data capture, if enabled.
End of Required Steps for Basic Setup
This completes the basic steps needed to transmit test traffic. The usefulness of your test, however, depends on getting test results. See “Getting Test Results” on page 375 for the steps to use counters, capture, or histograms to measure test traffic.
Original Function Description
HTStop/HGStop Stop the test, if running continuous traffic rather than step or burst mode.
Original Function Message Function iType1 Related Structure
HTSetCommand NS_CAPTURE_STOP —
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up Tests for LAN-3710A 10GbE Modules
SmartLibrary Overview and Procedures | 375
Getting Test Results
Your test can provide three types of results. These are:– Counters– Captured data — or —– Histograms
Counters Counters are always available. You need not enable them or set them up explicitly. You can get counter information during the test or after it stops.
Captured data and histograms
You can also retrieve captured data or histograms, but not both in the same test. For these, you must specify the type of results desired, and you must enable the function. You set up data capture or histogram results before you start your test. You obtain either type of results after you run the test.
How to Get Counter Information
Use HTGetCounters to get basic counters for your test.
Use ETH_EXTENDED_COUNTER_INFO to get additional counters.
Note: Other counters commands also may apply for the card or module in use. Refer to the compatibility tables in the SmartLibrary Command Reference (Volumes 1 and 2), to determine what other commands might be used.
Original Function Message Function iType1 Structure/Description
HTGetCounters — Retrieve basic test counters, including frame counts and errors.
HTGetStructure ETH_EXTENDED_COUNTER_INFO ETHExtendedCounterInfo
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up Tests for LAN-3710A 10GbE Modules
376 | SmartLibrary Overview and Procedures
How to Set Up Data Capture
You can specify data capture in place of histogram results.
Step 1 Set up the capture mode, length, and event.
Use HTSetStructure with NS_CAPTURE_SETUP(NSCaptureSetup) to specify the capture mode, length, and event.
Capture Mode. Valid options for NSCaptureSetup(ulCaptureMode) include:
Capture Events. The CAPTURE_EVENTS element in NSCaptureSetup defines what frame types should be captured. Valid options include the following:
Capture Length. Valid options for NSCaptureSetup(ulCaptureLength) include:
Original Function Message Function iType1 Related Structure
HTSetStructure NS_CAPTURE_SETUP NSCaptureSetup
Capture Mode Description
CAPTURE_MODE_FILTER_ON_EVENTS Capture only packets with the specified event, such as CRC errors, undersize packets, or oversize packets.
Capture Event Description
CRC_ERRORS Capture all frames with CRC errors.
IP_CHECKSUM_ERROR Capture all frames with IP checksum errors.
DATA_INTEGRITY_ERROR Capture all frames in which the payload contents have become corrupted.
RX_TRIGGER Capture all frames that contain receive trigger patterns.
Capture Length Description
CAPTURE_LENGTH_ENTIRE_FRAME Capture complete frame.
CAPTURE_LENGTH_1ST_64_BYTES Capture only the first 64 bytes in the frame.
CAPTURE_LENGTH_LAST_64_BYTES Capture only the last 64 bytes in the frame.
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up Tests for LAN-3710A 10GbE Modules
SmartLibrary Overview and Procedures | 377
Step 2 Start capture, then stop.
Before sending test traffic, use NS_CAPTURE_START to start capture.
When the test is done, use NS_CAPTURE_STOP to stop the capture.
Step 3 Get the captured data.
After the test completes, use the following commands to get your capture results.
Original Function Message Function iType1 Related Structure
HTSetCommand NS_CAPTURE_START —
NS_CAPTURE_STOP —
Original Function Message Function iType1 Related Structure Description
HTGetStructure NS_CAPTURE_COUNT_INFO NSCaptureCountInfo Find the number of frames in the capture buffer.
NS_CAPTURE_DATA_INFO NSCaptureDataInfo Retrieve a captured frame from the capture buffer.
NS_CAPTURE_STATS_INFO NSCaptureStatsInfo Get statistics about one or more captured frames.
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up Tests for LAN-3710A 10GbE Modules
378 | SmartLibrary Overview and Procedures
How to Set Up SmartMetrics Histograms
Histograms provide in-depth test results, including sequence and latency information.
Histogram information is gathered on the receiving card.
Step 1 Enable the histogram type.
Before you start the test, specify the type of histogram information you wish to be gathered.
Step 2 Set Up Port Groups
When SmartMetrics results are desired, you must set up a port group, since histogram results require a group start.
Use HGSetGroup and HGAddtoGroup to define the port group and to add ports to a group.
Step 3 Gather Histogram Information
After the test stops, use HTGetStructure with the iType1s listed below to collect histogram information.
Original Function Message Function iType1 Related Structure/Description
HTSetStructure NS_HIST_RAW_SIGNATURE Signature information only, showing transmit time, receive time, and delta in microseconds.
Original Function Description
HGSetGroup Define a group of SmartBits ports.
HGAddtoGroup Add ports to the group. You control grouped ports by using the HG commands.
Original Function Message Function iType1 Related Structure/Description
HTGetStructure L3_HIST_RAW_SIGNATURE_INFO NSHistRawSignatureInfo
Signature information only, showing transmit time, receive time, and delta in microseconds.
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up Alternate Key on TeraMetrics Modules
SmartLibrary Overview and Procedures | 379
Set Up Alternate Key on TeraMetrics ModulesThe Alternate Key and Hashing Algorithm features provide an enhanced means for applications to group received frames for statistical purposes. This grouping is accomplished by creating a key from data in the received frames, then using the key to look up the index in a statistics table. This feature is available on TeraMetrics-based modules.
Technical information
Using the Alternate Key feature, a section of the incoming frame (up to 16 contiguous bits) may be “captured”1 and written to the lookup key, which is constructed from the 32-bit Stream ID2 of the Signature field.
Important: The length of the Stream ID field is not increased when Alternate Key func-tionality is enabled. This means that information normally expected in the Signature field is lost in exchange for information from elsewhere in the frame. Furthermore, for purposes of hashing, the full 32-bits of the Stream ID are not available; only 16 of the 32 bits are guaranteed significant in the hashing process.
Applicable Commands
Table 18-12 is a summary of commands you can use. Not all commands are required. This list is an overview.
A basic setup See “Example of Setup Steps” on page 358 for a setup procedure.
1. This explanation uses the term “capture” in a non-standard way. All SmartBits cards nor-mally run in one of two modes: “histogram” mode or “capture” mode. In the context of Alternate Key, the term “capture” is used to indicate that, while the card is in histogram mode, some bits from the frame are extracted (“captured”) and written into the Lookup Key.
2. A note on terminology: The 32-bit Stream ID is a sub-field of the 18-byte SmartBits Signa-ture field. It is an arbitrary stream label; all packets from a single stream will always be transmitted with the same Stream ID (though other sub-fields of the 18-byte Signature field may vary from packet to packet within a single stream). The contents of this Stream ID are arbitrary and need not necessarily be unique from stream to stream.
Table 18-12.Applicable Commands: Alternate Key and Hash Algorithm
Applicable Commands
What the Commands Do Original Function Message Function iType1/Notes
Reset card to the default state.
HTResetPort See “Example of Setup Steps” on page 358.
Configure the ARP mode. HTSetStructure NS_ARP_CONFIG
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up Alternate Key on TeraMetrics Modules
380 | SmartLibrary Overview and Procedures
How to Set Up Alternate Key
Here is a complete summary of the steps to set up Alternate Key and Hashing Algorithm.
Step 1 Connect to the SmartBits chassis and reserve ports.
See the following:
• “Establishing a Link from the PC to SmartBits” on page 87.
• “How to Identify Hubs, Slots, and Ports” on page 94.
Applicable Commands
What the Commands Do Original Function Message Function iType1/Notes
Optional. Set up IPv4 streams.
HTSetStructure L3_DEFINE_<n>_STREAML3_DEFINE_<n>_STREAM_EXTENSIONL3_DEFINE_MULTI_<n>_STREAML3_DEFINE_MULTI_<n>_STREAM_EXTENSIONL3_MOD_<n>_STREAM
Set up IPv6 streams. HTSetStructure L3_DEFINE_<n>_IPV6_STREAM
Configure the ARP gap. HTSetStructure L3_SET_ARP_GAP
Set up data capture. HTSetStructure NS_CAPTURE_SETUP
Start data capture. HTSetCommand NS_CAPTURE_START
Clear counters. HTClearPort See “Example of Setup Steps” on page 358.
Start Neighbor Discovery and ARPs.
HTSetCommand L3_START_ARPS
Stop data capture. HTSetCommand NS_CAPTURE_STOP
Get the capture count. HTGetStructure NS_CAPTURE_COUNT_INFO
Get the captured packets. HTGetStructure NS_CAPTURE_DATA_INFO
Analyze captured packets. HTGetStructure ETH_EXTENDED_COUNTER_INFO
Get ARPs or Neighbor Discovery status.
HTGetStructure NS_ARP_STATUS_INFO
Resend ARPs or Neighbor Discovery messages.
HTSetCommand L3_ARP_UNRESOLVED
Table 18-12.Applicable Commands: Alternate Key and Hash Algorithm (continued)
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up Alternate Key on TeraMetrics Modules
SmartLibrary Overview and Procedures | 381
Step 2 Reset the card
Use HTResetPort to set the card to a known, default state.
Step 3 Set up the transmit mode and burst count.
On the transmitting port, use HTTransmitMode and HTBurstCount.
With a POS module, set the gap on the transmitting port, using HTGap.
Step 4 Set up streams.
Use HTSetStructure with L3_DEFINE_<n>_STREAM to configure test traffic. Here, <n> represents the stream type and can be IP, IPX, UDP, TCP, or SmartBits. This function specifies the stream template—that is, the structure of frames to be sent.
Use L3_DEFINE_STREAM_EXTENSION to define additional stream characteristics, including transmit mode, IP manipulation mode, and data integrity check.
Note: See “Set Up SmartMetrics Tests on TeraMetrics-based Modules” on page 329 for additional options in setting up multiple streams, modifying stream values, and setting up VLANs.
Original Function Description
HTResetPort Reset the card or module to a default state.
Original Function Description
HTTransmitMode Set transmit mode for the Tx port.
HTBurstCount Set burst count for the Tx port.
HTGap POS Modules only: Set the gap for the Tx port.
Original Function Message Function iType1 Related Structure
HTSetStructure L3_DEFINE_<n>_STREAM Stream<n>
L3_DEFINE_<n>_STREAM_EXTENSION StreamExtension
L3_DEFINE_MULTI_<n>_STREAM Stream<n>
L3_DEFINE_MULTI_<n>_STREAM_EXTENSION
StreamExtension
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up Alternate Key on TeraMetrics Modules
382 | SmartLibrary Overview and Procedures
Step 5 Set up the custom stream extension.
Use HTSetStructure with L3_DEFINE_STREAM_EXTENSION to configure needed fields in at least one stream on the transmitting port. (Like the previous command, L3_DEFINE_<n>_STREAM, this places the card in SmartMetrics mode.)
• Enable the field ucEnableCustomStreamID.
• Assign the Stream ID to ulCustomStreamID.
Step 6 Set up duplex mode and speed, if necessary.
Step 7 Set up the VFD
Use HTSetStructure with L3_DEFINE_VFD to specify the offset for tracking the Alternate Key. For POS modules, the offset starts from the fourth byte. For all other modules, the offset starts from the second byte.
Step 8 Set the Combination histogram test
Define the time interval ranges used in the Latency Distribution histogram. Use HTSetStructure with NS_HIST_COMBO_PER_STREAM.
Step 9 Set the histogram optionYou can configure the port to keep track of either the minimum or total latency when running the latency histogram tests. Use HTSetStructure with NS_HIST_LATENCY_OPTION.
Original Function Message Function iType1 Related Structure
HTSetStructure L3_DEFINE_<n>_STREAM_EXTENSION StreamExtension
Original Function Description
HTDuplexMode Set half or full duplex mode.
HTSpeed Set the port speed.
Original Function Message Function iType1 Related Structure
HTSetStructure L3_DEFINE_VFD NSVFD
Original Function Message Function iType1 Related Structure
HTSetStructure NS_HIST_COMBO_PER_STREAM NSHistComboPerStream
Original Function Message Function iType1 Related Structure
HTSetStructure NS_HIST_LATENCY_OPTION NSHistLatencyOption
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up Alternate Key on TeraMetrics Modules
SmartLibrary Overview and Procedures | 383
Step 10 Optional. Set up the trigger.
To use Alternate Key with trigger ON, set up the trigger.
Step 11 Set up the Alternate Key configuration.Use the NSAlternateKeyConfig structure to define the mode, offset, and mask.
Step 12 Set up the Alternate Key Hash configuration to match the key.
Set up Alternate Key hash configuration for your key arranges. The recommended option is NS_LOOKUP_KEY_CONTIGUOUS_16BIT_MAX.
Step 13 Set up port groups.
For SmartMetrics histogram results, you must set up a port group. Histogram results require a group start. Use HGSetGroup and HGAddtoGroup to define the port group and to add ports to a group.
Step 14 Initialize the timestamp on all ports in the group using “Timestamp-Initialization Sequence” commands.
Note: Whenever the test involves latency-related measurements and a group, the timestamps on all ports in the group must be simultaneously initialized with the “Timestamp-Initialization Sequence.” This is described in the SmartLibrary Command Reference Volume 1. Also, refer to “Inhibit Clearing Latency Counters Procedure” on page 573 for supplemental counter information.
Original Function Message Function iType1 Related Structure
HTSetStructure NS_TRIGGER_CONFIG NSTrigger
Original Function Message Function iType1 Related Structure
HTSetStructure NS_ALTERNATE_KEY_CONFIG NSAlternateKeyConfig
Original Function Message Function iType1 Related Structure
HTSetStructure NS_ALTERNATE_KEY_HASH_CONFIG NSAlternateKeyHashConfig
Original Function Description
HGSetGroup Define a group of SmartBits ports.
HGAddtoGroup Add ports to the group. Control grouped ports by using the HG commands.
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up Alternate Key on TeraMetrics Modules
384 | SmartLibrary Overview and Procedures
Step 15 Use HTRun or HGRun to run the test.
Step 16 Stop test traffic
Use HTStop or HGStop to stop the test (if run with continuous traffic).
Step 17 Check the combination histogram records.
Get the defined active histogram and the number of histogram records.
Step 18 Analyze the results
Use the histogram per-stream information for detailed analysis.
Original Function Description
HTRun/HGRun Transmit test frames.
Original Function Message Function iType1 Related Structure
HTGetStructure L3_HIST_ACTIVE_TEST_INFO Layer3HistActiveTest
OriginalFunction Message Function iType1 Related Structure
HTGetStructure NS_HIST_COMBO_PER_STREAM_INFO NSHistComboPerStreamInfo
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up SmartMetrics Tests with the LAN-3201B/C
SmartLibrary Overview and Procedures | 385
Set Up SmartMetrics Tests with the LAN-3201B/CUse the following steps to set up SmartMetrics tests with the LAN-3201B/C Gigabit SmartMetrics Ethernet module.
Note: See “Set Up Traditional Gigabit Ethernet Tests” on page 300 for the steps to set up Traditional mode tests with the LAN-3201B/C.
Applicable Commands
Table 18-13 summary of commands you can use in your tests with this modules. Not all commands are required. This list is an overview.
A basic setup See “Example of Setup Steps” on page 386 for a basic setup procedure, as well as optional commands and actions.
Table 18-13.Applicable Commands: SmartMetrics Tests with LAN-3201B/C
Applicable Commands
What the Commands Do Original Function Message Function iType1/Notes
Reset card to the default state. HTResetPort See “Example of Setup Steps” on page 386.
Clear counters. HTClearPort See “Example of Setup Steps” on page 386.
Set up streams HTSetStructure L3_DEFINE_<n>_STREAM
Note: Using L3_DEFINE_<n>_STREAM puts the module into the SmartMetrics mode. The library may then generate error messages in response to commands that pertain to Traditional mode operation. See the Note on page 387.
Set up additional stream characteristics, including traffic mode.
HTSetStructure L3_DEFINE_STREAM_EXTENSION
Specify SmartMetrics (histogram) results.
—or—
HTSetCommand NS_HIST_COMBO_PER_STREAMNS_HIST_LATENCY_OVER_TIMENS_HIST_RAW_SIGNATURENS_HIST_SEQUENCE_PER_STREAMNS_HIST_LATENCY_DIST_PER_STREAM
Set up data capture. HTSetStructure NS_CAPTURE_SETUP
(Optional) Set up port groups. HGSetGroupHGAddtoGroup
See “Example of Setup Steps” on page 386.
Transmit test frames. HTRun For single-port start.
HGRunHGStep
For group start.
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up SmartMetrics Tests with the LAN-3201B/C
386 | SmartLibrary Overview and Procedures
Example of Setup Steps
Here is an example of how to set up your test. It assumes no previous configuration. It shows selected commands, not all possible commands or actions.
Step 1 Reset the Card and Clear All Counters
Use HTResetPort to set the card to a known, default state. Use HTClearPort to clear all counters.
Step 2 Set Up StreamsUse HTSetStructure with L3_DEFINE_<n>_STREAM to configure test traffic. Here, <n> represents the stream type and can be IP, IPX, UDP, TCP, or SmartBits. This func-tion specifies the stream template (the structure of frames to be sent).
Use L3_DEFINE_STREAM_EXTENSION to define additional stream characteristics, such as frame rate, burst count, transmit mode, IP manipulation mode, and data integrity check.
Applicable Commands
What the Commands Do Original Function Message Function iType1/Notes
Start data capture (if selected). HTSetCommand NS_CAPTURE_STOPNS_CAPTURE_STARTNS_CAPTURE_STOP
Stop the test. HTStopHGStop
See “Example of Setup Steps” below.
Get histogram information.
—or—
HTGetStructure NS_HIST_COMBO_PER_STREAM_INFONS_HIST_LATENCY_OVER_TIME_INFONS_HIST_RAW_SIGNATURE_INFONS_HIST_SEQUENCE_PER_STREAM_INFONS_HIST_LATENCY_DIST_PER_STREAM_INFO
Get captured data. HTGetStructure NS_CAPTURE_COUNT_INFONS_CAPTURE_DATA_INFO
Table 18-13.Applicable Commands: SmartMetrics Tests with LAN-3201B/C (continued)
Optional/RelatedOptional or related commands and actions (if applicable) are shown in a shaded box. These actions are not required for a basic test setup.
Original Function Description
HTResetPort Reset the card or module to a default state.
HTClearPort Clear the port counters.
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up SmartMetrics Tests with the LAN-3201B/C
SmartLibrary Overview and Procedures | 387
Note: For this module, the L3_DEFINE_STREAM_EXTENSION is required.
Defining Multiple Streams. To define multiple streams, use L3_DEFINE_MULTI_<n>_STREAM. Use L3_DEFINE_MULTI_STREAM_EXTENSION to set up the stream characteristics.
Note: Using L3_DEFINE_<n>_STREAM (or L3_DEFINE_<n>_MULTI_STREAM) (see below) places the module into SmartMetrics mode. The library may then generate error messages in response to commands that pertain to Traditional operation, such as GIG_STRUC_TX, GIG_STRUC_ALT_TX, HTCRC, HTEcho, HTFillPattern, HTLatency, and HTVFD. To put the module into Traditional mode, use HTResetPort (see “Set Up Traditional Gigabit Ethernet Tests” on page 300).
Modifying a Stream. Use L3_MOD_<n>_STREAM to modify an existing stream at a specified index. This function replaces the entire stream: to change one or more attributes, a complete structure is sent to the card. L3_MOD_<n>_STREAM can modify the stream at index 0, but you should modify streams starting at index 1, because the stream at index 0 is typically reserved for Traditional mode.
Step 3 (Optional) Set Up Port Groups
Use HGSetGroup to define the port group and HGAddtoGroup to add ports to a group.
Step 4 Send Test Traffic
Use HTRun or HGRun (or HGStep) to send test traffic.
Note: For Latency histogram results, it is important to initialize the timestamps on each module before doing a group start. To do this, use the “Timestamp-Initialization Sequence.”
Step 5 Stop Test Traffic
Use HTStop or HGStop to stop the test (if run with continuous traffic).
Original Function Message Function iType1 Related Structure
HTSetStructure L3_DEFINE_<n>_STREAM Stream<n>
L3_DEFINE_<n>_STREAM_EXTENSION StreamExtension
L3_DEFINE_MULTI_<n>_STREAM Stream<n>
L3_DEFINE_MULTI_<n>_STREAM_EXTENSION
StreamExtension
Original Function Description
HGSetGroup Define a group of SmartBits ports.
HGAddtoGroup Add ports to the group. You control grouped ports by using the HG commands.
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up SmartMetrics Tests with the LAN-3201B/C
388 | SmartLibrary Overview and Procedures
End of Required Steps for Basic Setup
This completes the basic steps needed to transmit test traffic. The usefulness of your test, however, depends on getting test results. See “Getting Test Results” on page 388 for the steps to use counters, capture, or histograms to measure test traffic.
Getting Test Results
Your test can provide three types of results. These are:– Counters– Captured data — or —– Histograms
Counters Counters are always available. You need not enable them or set them up explicitly. You can get counter information during the test or after it stops.
Captured data and histograms
You can also retrieve captured data or histograms, but not both in the same test. For these, you must specify the type of results desired, and you must enable the function. You set up data capture or histogram results before you start your test. You obtain either type of results after you run the test.
How to Get Counter Information
Use HTGetCounters to get basic counters for your test.
Use ETH_EXTENDED_COUNTER_INFO to get additional counters.
Note: Other counters commands also may apply for the card or module in use. Refer to the compatibility tables in the SmartLibrary Command Reference (Volumes 1 and 2), to determine what other commands might be used.
Original Function Message Function iType1 Structure/Description
HTGetCounters — Retrieve basic test counters, including frame counts and errors.
HTGetStructure ETH_EXTENDED_COUNTER_INFO ETHExtendedCounterInfo
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up SmartMetrics Tests with the LAN-3201B/C
SmartLibrary Overview and Procedures | 389
How to Set Up Data Capture
Use the following steps to set up data capture. You can enable either data capture or SmartMetrics histogram results (see “How to Set Up SmartMetrics Histograms” on page 341).
Step 1 Set up the capture parameters.
Use HTSetStructure with NS_CAPTURE_SETUP(NSCaptureSetup) to specify the capture mode, length, and event.
Capture Mode. Valid options for NSCaptureSetup(ulCaptureMode) include:
Capture Length. Valid options for NSCaptureSetup(ulCaptureLength) include:
Original Function Message Function iType1 Related Structure
HTSetStructure NS_CAPTURE_SETUP NSCaptureSetup
Capture Mode Description
CAPTURE_MODE_FILTER_ON_EVENTS Capture only packets with the specified event, such as CRC errors, undersize packets, or oversize packets.
CAPTURE_MODE_START_ON_EVENTS Capture all packets following the specified event. For example, begin capture when the first packet with a CRC error is received, then capture all packets.
CAPTURE_MODE_STOP_ON_EVENTS Capture all packets until the specified event. For example, capture all packets until the first packet with a CRC error is received, then stop the capture.
Capture Length Description
CAPTURE_LENGTH_ENTIRE_FRAME Capture complete frame.
CAPTURE_LENGTH_1ST_128_BYTES Capture only the first 128 bytes in the frame.
CAPTURE_LENGTH_LAST_128_BYTES Capture only the last 128 bytes in the frame.
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up SmartMetrics Tests with the LAN-3201B/C
390 | SmartLibrary Overview and Procedures
Capture Event. The CAPTURE_EVENTS element in NSCaptureSetup defines what frame types should be captured. Valid options for NSCaptureSetup(ulCaptureEvents) include:
Step 2 Start the capture, then stop it.
Step 3 Get the captured data.
Use HTGetStructure with NS_CAPTURE_COUNT_INFO to find the number of frames in the buffer.
Use HTGetStructure with NS_CAPTURE_DATA_INFO to get the captured frames.
Capture Event Description
CRC_ERRORS Capture all frames with CRC errors.
IP_CHECKSUM_ERROR Capture all frames with IP checksum errors.
DATA_INTEGRITY_ERROR Capture all frames in which the payload contents have become corrupted.
RX_TRIGGER Capture all frames that contain receive trigger patterns.
Original Function Message Function iType1 Description
HTSetCommand NS_CAPTURE_START Clear the buffer and start the capture.
NS_CAPTURE_STOP Stop capture.
Original Function Message Function iType1 Related Structure
HTGetStructure NS_CAPTURE_COUNT_INFO NSCaptureCountInfo
NS_CAPTURE_DATA_INFO NSCaptureDataInfo
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up SmartMetrics Tests with the LAN-3201B/C
SmartLibrary Overview and Procedures | 391
How to Set Up SmartMetrics Histograms
Histograms provide in-depth test results, including sequence and latency information.
Histogram information is gathered on the receiving card.
Step 1 Enable the histogram type.
For SmartMetrics histograms results, specify the histogram type. All SmartMetrics cards and modules support the same histogram types.
Original Function Message Function iType1 Related Structure/Description
HTSetStructure NS_HIST_COMBO_PER_STREAM NSHistComboPerStream
Gives an overall picture of latency per stream. Provides the following results:
Latency per Stream. Shows minimum, maximum, and average latency values over the course of the test.
Latency Distribution. Shows the occurrence of specific latency values per stream.
Sequence Tracking. Reports whether or not frames were received in sequence per stream.
NS_HIST_LATENCY_OVER_TIME NSHistLatencyOverTime
Provides Latency over Time histogram on the receive module.
NS_HIST_RAW_SIGNATURE Signature information only, showing transmit time, receive time, and delta in microseconds.
NS_HIST_SEQUENCE_PER_STREAM Sequence information only. Reports whether or not frames were received in sequence per stream.
NS_HIST_LATENCY_DIST_PER_STREAM NSHistLatencyDistPerStream
Latency distribution information only. Shows the occurrence of specific latency values per stream.
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up SmartMetrics Tests with the LAN-3201B/C
392 | SmartLibrary Overview and Procedures
Step 2 Set up port groups.
For SmartMetrics histogram results, you must set up a port group. Histogram results require a group start.
Use HGSetGroup and HGAddtoGroup to define the port group and to add ports to a group.
Step 3 Gather histogram information.
After the test runs, gather the results for the SmartMetrics histogram you specified in Step 1. Use HTGetStructure with the appropriate iType1, as shown below.
Original Function Description
HGSetGroup Define a group of SmartBits ports.
HGAddtoGroup Add ports to the group. You control grouped ports by using the HG commands.
Original Function Message Function iType1 Related Structure/Description
HTGetStructure NS_HIST_COMBO_PER_STREAM_INFO NSHistComboPerStreamInfo
Latency Distribution histogram results.
NS_HIST_LATENCY_OVER_TIME_INFO NSHistLatencyOverTimeInfo
Latency over Time histogram results.
NS_HIST_RAW_SIGNATURE_INFO NSHistRawSignatureInfo
Signature information only.
NS_HIST_SEQUENCE_PER_STREAM_INFO NSSequenceInfo
Sequence Tracking histogram results.
NS_HIST_LATENCY_DIST_PER_STREAM_INFO NSHistLatencyDistPerStreamInfo
Latency Distribution histogram results.
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up Tests with the ML-5710A
SmartLibrary Overview and Procedures | 393
Set Up Tests with the ML-5710A
Application
In a typical cable modem installation, the head-end device expects to receive a single MAC address for each communicating end-user station (PC) (see figure below). The MAC address is obtained not from the user’s PC, but from the attached cable modem.
In a SmartBits test application, the L3_USB_MODE_ON function is used to instruct the card to use the USB interface. L3_USB_MODE_OFF instructs the card to revert to using the Ethernet interface. The L3_USB_ GET_USB_INFO function is used to obtain the MAC address from the cable modem. This MAC address should be used to set up the VTEs (Virtual Transmit Engines) on the ML-5710A SmartCard, for use in the test.
How to Set Up Tests
The Tcl code samples below illustrate the key steps in setting up the USB parameters. These include:
• Changing to USB mode.
• Checking that the change succeeded.
• Getting and (optionally) displaying the MAC information.
Perform these steps before setting up VTEs (Virtual Transmit Engines) on the card. When setting up the VTEs, use the MAC address for the source MAC address fields.
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up Tests with the ML-5710A
394 | SmartLibrary Overview and Procedures
Step 1 Change to USB Mode
Use L3_USB_MODE_ON to instruct the ML-5710A SmartCard to use the USB interface rather than the Ethernet interface. Use L3_USB_MODE_OFF to revert to using the Ethernet interface.
Example puts "Changing to USB Mode"
puts [HTSetCommand $L3_USB_MODE_ON 0 0 0 "" $hub $slot $port]
Step 2 Check that the Change to USB Port Succeeded
After the ML-5710A SmartCard switches to the USB interface, it polls repeatedly to detect whether a USB device is attached. When it finds the device attached, it can enter the enumeration phase. You can check USB status in two ways:
• To determine whether the USB port is enabled.
• To determine if a USB device has been detected (linked).
Example after 5000
set status 0
puts [HTGetEnhancedStatus status $hub $slot $port]
if {$status & $L3_USB_PORT_ENABLED} {
puts "USB Port Enabled"
} else {
puts "---ERROR--- USB Port Not Enabled"
if {$status & $L3_USB_PORT_LINKED} {
puts "USB Port Linked"
} else {
puts "USB Port Not Linked"
}
Step 3 Get USB MAC Information
Get the MAC address information and store it in a structure of type USBInfo.
Example puts "Getting MAC"
struct_new usbMac USBInfo
puts [HTGetStructure $L3_USB_GET_USB_INFO 0 0 0 usbMac 0 $hub
$slot $port]
Step 4 Display MAC Information
Display the MAC address information.
Example puts ""
set data 0
for {set i 0} [$i < 6} {incr i}}
scan $usbMac(szUSBMAC.$i.uc) %c data
puts -nonewline "[format %x $data] "
}
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up Tests with the ML-5710A
SmartLibrary Overview and Procedures | 395
Step 5 Use usbMac(szUSBMAC) as Source MAC Address in VTEs
When setting up VTEs on the ML-5710A SmartCard, use the obtained MAC address for the source MAC address fields.
Setting Interframe Gap Values with the ML-5710A
When the ML-5710A SmartCard is in USB mode, the range of permitted Interframe Gap (IFG) values is smaller than when the card is in the Ethernet mode. Permitted IFG values are listed below. Use HTGap to set the Interframe Gap for the port.
Change to RNDIS Mode
The ML-5710A SmartCard can operate in either the RNDIS interface mode or Ethernet interface mode.
Use L3_RNDIS_MODE_ON to instruct card to use the RNDIS interface and turn off the Ethernet interface.
To set the card back to Ethernet mode, use L3_ETHERNET_MODE_ON.
IFG Value(HTGap.lPeriod) Gap Time (Approximate)
96 9.6 microseconds
120 12.0 microseconds
250 25.0 microseconds
500 50.0 microseconds
1000 100.0 microseconds
1250 125.0 microseconds
1500 150.0 microseconds
2000 200.0 microseconds
5000 500.0 microseconds
10000 1.0 millisecond
20000 2.0 millisecond
50000 5.0 milliseconds
100000 10.0 milliseconds
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up Tests with the ML-5710A
396 | SmartLibrary Overview and Procedures
Example: To set the card in RNDIS mode:
To set ML-5710A into RNDIS mode:puts "Changing to RNDIS Mode"
puts [HTSetCommand $ L3_RNDIS_MODE_ON 0 0 0 "" $hub $slot $port]
Example: To reset to Ethernet mode:
Use L3_ETHERNET_MODE_ON to instruct ML-5710A to use the Ethernet interface and turn off all other interfaces (USB and RNDIS).
puts "Changing to Ethernet Mode"
puts [HTSetCommand $ L3_ETHERNET_MODE_ON 0 0 0 "" $hub $slot $port]
How to Verify RNDIS Mode
Use HTGetEnhancedStatus to verify that the RNDIS mode is enabled.
Example: after 5000
set status 0
puts [HTGetEnhancedStatus status $hub $slot $port]
if {$status & $ L3_RNDIS_MODE_ENABLED} {
puts " RNDIS mode enabled"
} else {
puts “RNDIS mode not enabled"
}
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up DHCP Streams
SmartLibrary Overview and Procedures | 397
Set Up DHCP Streams
ApplicationThe Dynamic Host Configuration Protocol (DHCP) was defined initially by RFC 1531. It outlines a mechanism through which configuration parameters and IP addresses can be provided by a server to internet hosts.
DHCP is built on a client-server model. An exchange of messages between a designated DHCP server and client hosts enables the DHCP server to allocate network addresses and deliver configuration parameters.
In SmartBits test applications, DHCP makes it possible to dynamically supply IP addresses to the device under test (DUT). This enables the SmartBits system to emulate actual network behavior more closely. On SmartBits cards, the DHCP implementation allows for automatic assignment of IP addresses to configured streams.
All the DHCP-related functions apply to streams that are DHCP-capable. These are IP, UDP, or TCP protocol streams. The LAN-3101A/B modules also support these stream protocol types with VLAN.
Figure 18-2 illustrates the DHCP protocol in a simplified form. The figure shows a successful exchange using a subset of DHCP messages.
Figure 18-2. Outline of DHCP Message Exchange
InternetClient
DHCPServer
1 Discover
2 Offer
3 Request
4 ACK
5 Release
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up DHCP Streams
398 | SmartLibrary Overview and Procedures
Applicable Commands
Table 18-14 is a summary of commands that may be used. Not all commands are required. This list is an overview.
A basic setup See “Example of Setup Steps” on page 399 for a basic setup procedure, as well as optional commands and actions.
Note: The following DHCP commands use iType2 (<index>) to set the starting stream number, and iType3 (<count>) to specify the range:• L3_DHCP_GET_ADDRESS• L3_DHCP_RELEASE_ADDRESS• L3_DHCP_STATS_INFO• L3_DHCP_HOST_INFO• L3_DHCP_EXTENDED_HOST_INFO
In all these commands, if <index> specifies a stream that is not DHCP-capable (i.e., not IP, UDP, or TCP), then the action starts at the first stream that is DHCP-capable. Streams that are not DHCP-capable but are within the <count> range are skipped.
Table 18-14.Applicable Commands: DHCP Streams
Applicable Commands
What the Commands Do Original Function Message Function iType1/Notes
Configure streams. See“Example of Setup Steps” on page 399.
See“Example of Setup Steps” on page 399.
Set the message rate at which messages are sent from the client to the server.
HTSetStructure L3_DHCP_CONFIG
Retrieve the DHCP information (LAN-3101A/B modules only).
HTGetStructure L3_DHCP_CONFIG_INFO
Start the DHCP exchange. HTSetCommand L3_DHCP_GET_ADDRESS
—or—
L3_DHCP_GET_ADDRESS_ALL
Transmit a DHCP Renew/Request message for one or more streams (LAN-3101A/B modules only).
HTSetStructure L3_DHCP_RENEW
Get the count of DHCP-capable streams.
HTGetStructure L3_DHCP_STREAM_COUNT_INFO
Continues –>
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up DHCP Streams
SmartLibrary Overview and Procedures | 399
Example of Setup Steps
Here is an example of how to set up your test. It assumes no previous configuration. It shows selected commands, not all possible commands or actions.
Step 1 Configure Streams
First, configure the SmartMetrics streams using one of the procedures described in this chapter. See the following:
• “Set Up Ethernet SmartMetrics Streams” on page 310
• “Set Up SmartMetrics Tests on TeraMetrics-based Modules” on page 329
• “Set Up Tests for LAN-3710A 10GbE Modules” on page 369
Step 2 Set the Client Message Rate
When multiple DHCP-capable streams will be set up and initiated, use HTSetStructure with L3_DHCP_CONFIG to define the rate (in frames per second) at which Discover and Release messages will be sent to the DHCP server. This can be done to ensure that the server does not become overloaded by messages from multiple clients.
Note: DHCP commands do not return until the related message exchange process completes. The default SmartLibrary timeout on command execution of 30 seconds. To avoid a timeout error, increase this value by using ETSetTimeout.
Continues –>
Applicable Commands
What the Commands Do Original Function Message Function iType1/Notes
Get DHCP streams and host statistics.
HTGetStructure L3_DHCP_STATS_INFO
L3_DHCP_HOST_INFO
L3_DHCP_EXTENDED_HOST_INFO
Release DHCP streams. HTSetCommand L3_DHCP_RELEASE_ADDRESS
—or—
L3_DHCP_GET_RELEASE_ADDRESS_ALL
Table 18-14.Applicable Commands: DHCP Streams (continued)
Original Function Message Function iType1 Related Structure
HTSetStructure L3_DHCP_CONFIG Layer3DHCPConfig
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up DHCP Streams
400 | SmartLibrary Overview and Procedures
Step 3 Get the DHCP Configuration
Use HTGetStructure with L3_DHCP_CONFIG_INFO to retrieve the DHCP configuration.
Step 4 Start the DHCP Exchange
To start the DHCP message exchange for specific streams, use:
• HTSetCommand with L3_DHCP_GET_ADDRESS
To start the DHCP message exchange for all streams, use:
• HTSetCommand with L3_DHCP_GET_ADDRESS_ALL
Step 5 Get the Count of DHCP-Capable Streams
To get the number of DHCP-capable streams, use HTGetStructure with L3_DHCP_STREAM_COUNT_INFO.
Step 6 Get DHCP Streams and Host Statistics
Use the DHCP statistics commands and structures to get statistics information on the DHCP exchange for streams and the DHCP server host.
For streams, information includes the number of messages sent, time-outs, and failures.
For the DHCP server host, it includes address and state information.
Original Function Message Function iType1 Related Structure
HTGetStructure L3_DHCP_CONFIG_INFO Layer3DHCPConfig
Original Function Message Function iType1 Related Structure
HTSetCommand L3_DHCP_GET_ADDRESS
L3_DHCP_GET_ADDRESS_ALL
None
Original Function Message Function iType1 Related Structure
HTGetStructure L3_DHCP_STREAM_COUNT_INFO ULong
Original Function Message Function iType1 Related Structure
HTGetStructure L3_DHCP_STATS_INFO Layer3DHCPStatsInfo
HTGetStructure L3_DHCP_HOST_INFO Layer3DHCPHostInfo
HTGetStructure L3_DHCP_EXTENDED_HOST_INFO Layer3DHCPExtendedHostInfo
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up DHCP Streams
SmartLibrary Overview and Procedures | 401
Step 7 Send DHCP Renew/Request Messages
The DHCP client (stream) must be in the Bound state before a request message will be sent in the Renewing state. This capability is under your control. SmartBits modules do not have the timers needed to send a Request message dynamically in the Renewing state when the lease time expires or is about to expire. In addition, once the Request message is sent, the module does not handle timeouts. You need to resend the command to have the module resend the Request message.
Once the Renewing state is finished, you should poll the module to check if the IP address obtained is different from the address in the original DHCP exchange. The IP address can be obtained by using either of two commands:
• L3_DHCP_HOST_INFO
• L3_DHCP_EXTENDED_HOST_INFO
Original Function Message Function iType1 Related Structure
HTSetStructure L3_DHCP_RENEW Layer3DHCPRenew
HTGetStructure L3_DHCP_HOST_INFO Layer3DHCPHostInfo
HTGetStructure L3_DHCP_EXTENDED_HOST_INFO Layer3DHCPExtendedHostInfo
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up Stream Grouping
402 | SmartLibrary Overview and Procedures
Set Up Stream GroupingThis procedure applies to the LAN-3101A/B 10/100Mbps SmartMetrics module.
You can use stream grouping to define the sequence in which streams are scheduled for transmission from a port. Stream grouping enables you to control more closely the characteristics of different sets of streams within a test. For example, it lets you set different Interframe Gap (IFG) values and frame sizes for the streams in different groups.
Once you have defined stream groups and assigned streams to them, the transmitting port sends frames according to the order of the defined groups and of the streams within each group. You can define up to 10 groups, with up to 100 streams in a single group.
How Test Traffic Differs with Stream Groups
Two figures below illustrate the difference between how streams are transmitted when no stream groups are defined and when stream groups are defined.
No Stream Groups Defined. If no stream groups are set up, the port transmits one frame from each defined stream, following the order of the stream index values. Figure 18-3 depicts a port’s transmit buffer holding seven streams when no stream groups have been set up. The port will transmit one frame from each stream (1 through 7) in order, then repeat the cycle up to the limit defined for the test.
Figure 18-3. Stream Transmission When No Groups Are Defined
Stream Groups Defined. If stream groups have been set up, the port sends one frame from each stream in the first group, then one frame from each stream in the following group, and so on through all defined groups. It repeats this cycle up to the limit defined for the test. Figure 18-4 depicts the port transmit buffer with the same seven streams, but with three stream groups defined, and the transmission sequence.
Figure 18-4. Stream Transmission When Groups Are Defined
Stream 1 Stream 2 Stream 3 Stream 4 Stream 5 Stream 6 Stream 7
No Stream Groups Defined
Stream 1 Stream 2 Stream 3 Stream 4 Stream 5 Stream 6 Stream 7
Three Stream Groups Defined
Group 1: Streams 1 & 3 Group 2: Streams 6 & 7
Group 3: Streams 2 & 4
Stream 1 Stream 3 Stream 6 Stream 7 Stream 2 Stream 4
Transmission Sequence
Note: Stream 5 is not sent. See “Ungrouped Streams Are Not Sent” below.
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up Stream Grouping
SmartLibrary Overview and Procedures | 403
Guidelines on Group Mode
You define create, modify, and delete stream groups by using the iType1 commands L3_STREAM_GROUP_DEFINE and L3_STREAM_GROUP_DELETE.
In addition, you use L3_STREAM_TRANSMIT_MODE to either enable or disable stream grouping for a port.
Here are guidelines on using stream groups.
Operating Modes
You place a port into the stream group mode by creating one or more groups, then sending the iType1 command L3_STREAM_TRANSMIT_MODE.
Once in the group mode, the port operates using the defined stream groups, rather than individual streams. As noted below (see “Ungrouped Streams Are Not Sent” on page 403), when stream groups are defined, the port sends no “independent” streams that have not been assigned to a group.
You also use L3_STREAM_TRANSMIT_MODE to place the port back into the stream mode. The port then transmits individual streams. Defined stream groups remain intact, but the port ignores them.
Ungrouped Streams Are Not Sent
When stream groups are defined, the port does not transmit “independent” streams that have not been assigned to a group. It sends only streams that are members of defined groups.
Streams May Not Overlap Groups
A stream may not be assigned to more than one stream group.
Group Frame Size Overrides Individual Frame Size
The frame size you define for a group applies to all streams in the group. (See “Structure Options”.) It overrides the frame size set for a stream individually.
Note: When the port is placed back into stream mode, the original, individual stream frame sizes are restored.
Transmission Modes Supported
Allowed: Burst and Continuous transmission modes.Not Allowed: Multi Burst and Continuous Multi Burst transmission modes.
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up Stream Grouping
404 | SmartLibrary Overview and Procedures
Default Group 1
A default group (GroupId = 1) is predefined. You can apply this group in tests by setting the needed structure values and assigning streams to it.
! Caution: Group 1 should not be deleted, even if you wish the port to send streams inde-pendently and not as part of a group. To make Group 1 inactive, set the port back into stream mode by using L3_STREAM_TRANSMIT_MODE.
Cautions When Deleting Groups
Observe the following when deleting streams and groups:1 As noted above (“Default Group 1”), the default group (GroupId = 1) should be left
intact, even if you do not wish to use the group mode. To make the group inactive and transmit independent streams, use L3_STREAM_TRANSMIT_MODE to set the port back into stream mode.If you delete the default group, the card firmware resets group parameters and sets the number of streams (uiNumberOfStreams) to 1. Specifically, the following parameter values are reset:• ulFrameLength Frame length for all group streams.• ulFrameGap Gap for all group streams.• uiMembers Group members by stream index; reset to 0.• uiNumberOfStreams Number of streams in the group; reset to 1.
2 If you do delete group 1, stream index 0 (the card’s default stream template) will be set to inactive. If you wish to add group 1 again, be sure to set stream 0 to the active state. It will then be included in the group.
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up Stream Grouping
SmartLibrary Overview and Procedures | 405
How to Define Stream Groups
To define stream groups, use HTSetStructure with L3_STREAM_GROUP_DEFINE and Layer3StreamGroup.
Programming Steps
Use the following steps to set up stream groups.1 Create streams in the normal way. See Chapter 2, “SmartLibrary Basics” for an over-
view and “Set Up Ethernet SmartMetrics Streams” on page 310 for specific steps.2 Use HTSetStructure with L3_STREAM_GROUP_DEFINE(Layer3StreamGroup) to
define each group. Use the Layer3StreamGroup structure to set group characteristics and to identify the stream members of the group.
3 Use HTSetStructure with L3_STREAM_TRANSMIT_MODE to set the port to the group mode.
Structure Options
Options in the Layer3StreamGroup data structure include the following:
Frame Size for Group (ulFrameLength)
Specify the length of frames for all streams in the group.Range: 24 to 1600 for Ethernet. The card will set the minimum value (24 bytes) if the
assigned value is less.
Interframe Gap (ulFrameGap)
Specify the Interframe Gap (IFG) size to be used. This gap will be used between frames of each stream in the group and also between the last frame of this group and the first frame of the next group in sequence.
Range: For 10Mbps traffic, this value = number of 1/10s of microseconds.For 100Mbps traffic, this value = number of 10s of nanoseconds.
For either 10Mbps or 100Mbps test traffic, the gap may range from 80 to 1,600,000.
Stream 1 Stream 3 Stream 6 Stream 7 Stream 2 Stream 4
The interframe gap (IFG) set for a group applies between frames in the group
Group 1 Group 2 Group 3
and between the last frame of the group and the first frame of the next group.
Gap forGroup 1
Gap forGroup 2
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up Stream Grouping
406 | SmartLibrary Overview and Procedures
Examples:
• With 10Mbps transmission, if ulFrameGap = 96, the IFG will be 9.6 microseconds (96 * 0.1 microseconds).
• With 100Mbps transmission, the gap will be 960 nanoseconds (96 * 10 nanoseconds).
These values are the minimum legal IFG for each data rate.
Number of Streams in Group (uiNumberOfStreams)
Define how many streams the group includes.Range: 1 to 100
Assigned Streams in Group (uiMembers)
Identify the streams that are members of the group, by stream index.Range: 0 (template) and 1 to 100
How to Modify Stream Groups
To modify a stream group, use L3_STREAM_GROUP_DEFINE and send the Layer3StreamGroup data structure with the same GroupId but with updated values. The command overwrites the previous group definitions.
How to Delete Stream Groups
To delete a stream group, use HTSetCommand with L3_STREAM_GROUP_DELETE. Identify the group to delete by using iType2 as index to specify the GroupId.
Note: Using L3_STREAM_GROUP_DELETE to delete a stream group does not change the port’s operating mode; the port remains in the group mode.
To place the port into the stream mode, send L3_STREAM_TRANSMIT_MODE (see “Operating Modes”).
See “Cautions When Deleting Groups” for important guidelines.
How Deleting a Group Affects the Transmit Sequence
When you delete a group, its place in the group order is filled by the next group in sequence. If you add the group again (or any other group), it is placed last in the group order. Here is an example:
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up Stream Grouping
SmartLibrary Overview and Procedures | 407
Stream 1 Stream 3 Stream 6 Stream 7 Stream 2 Stream 4
Three stream groups are defined.
Group 1: Streams 1 & 3
You delete Group 2.
Group 2: Streams 6 & 7 Group 3: Streams 2 & 4
Stream 1 Stream 3 Stream 2 Stream 4
The next group in sequence (Group 3) fills that place in the group order.
Stream 1 Stream 3 Stream 2 Stream 4
If you add Group 2 again (or any other group), it is placed last in the group order.
Stream 1 Stream 3 Stream 2 Stream 4 Stream 6 Stream 7
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up PPP Over Ethernet (PPPoE)
408 | SmartLibrary Overview and Procedures
Set Up PPP Over Ethernet (PPPoE)Use the following procedure to set up tests with PPP over Ethernet (PPPoE) streams.
Note: This procedure applies only to the LAN-3101A/B and ML-5710A.
Applicable Commands
Table 18-15 is a summary of commands you can use. Not all possible commands are included. This list is an overview.
A basic setup See “Example of Setup Steps” on page 409 for a basic setup procedure.
Table 18-15.Applicable Commands: PPP over Ethernet (PPPoE)
Applicable Commands
What the Commands Do Original Function Message Function iType1/Notes
Configure streams. See“Example of Setup Steps” on page 409.
See“Example of Setup Steps” on page 409.
Note: The number of IP streams should equal the number of PPP sessions.
Configure the PPP sessions. HTSetStructure PPP_CONFIG
Optional. Get the information on the configuration of the PPP sessions.
HTGetCommand PPP_CONFIG_INFO
Start the PPP sessions. HTSetStructure PPP_SET_CTRL
Optional. Get PPP status and statistics.
HTGetStructure PPP_STATUS_INFO
PPP_STATS_INFO
PPP_STATS_RESET
Send test traffic. HTRun/HGRun
(HTStop/HGStop)
See“Example of Setup Steps” on page 409.
Tear down the PPP sessions. HTSetStructure PPP_SET_CTRL
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up PPP Over Ethernet (PPPoE)
SmartLibrary Overview and Procedures | 409
Example of Setup Steps
Here is an example of how to set up your test. It assumes no previous configuration. It shows selected commands, not all possible commands or actions.
Step 1 Configure streams
First configure SmartMetrics streams using one of the procedures described in this chapter. See one of the following:
• “Set Up Ethernet SmartMetrics Streams” on page 310
• “Set Up SmartMetrics Tests on TeraMetrics-based Modules” on page 329
Step 2 Configure the PPP connection.
Use HTSetStructure with PPP_CONFIG to configure the PPP connection.
Note: In PPPParamCfg, if ucModFrame is set to 0x01, you will not see the source IP address defined in the PPP configuration in transmitted frames. This is owing to the behavior of the PPP stack. Currently, if you enable IP negotiation and define IP addresses in PPP configuration, the PPP sessions won't come up with some routers. We recommend that you enable IP negotiation and leave local IP addresses in the PPP configuration as 0s. Then the sessions should be able to come up properly.
Step 3 Set up PPP handshaking and establish the PPP connection.
Use HTSetStructure with PPP_SET_CTRL to set up PPP handshaking and to establish the connection.
Optional/RelatedOptional or related commands and actions (if applicable) are shown in a shaded box. These actions are not required for a basic test setup.
Original Function Message Function iType1 Related Structure
HTSetStructure PPP_CONFIG PPPParamCfg
OptionalYou can use HTGetStructure with PPP_CONFIG_INFO to review the PPP configuration.
Original Function Message Function iType1 Related Structure
HTSetStructure PPP_SET_CTRL PPPControlCfg
Chapter 18: SmartMetrics/TeraMetrics TestingSet Up PPP Over Ethernet (PPPoE)
410 | SmartLibrary Overview and Procedures
Step 4 Verify the PPP session status.
Before sending traffic, verify that the IP/NCP session is established. Sending IP traffic before the session is established can adversely affect the DUT and the SmartBits.
You can also use HTGetStructure with PPP_STATS_INFO to get PPP session statistics. Use PPP_STATS_RESET to reset the counters.
Step 5 Send Test Traffic, Stop Test Traffic
Use the HTRun or HGRun command to run the test.
Use HTStop or HGStop to stop the test when run with continuous traffic.
Step 6 Get test counters.
For PPP connections, use HTSetStructure with PPP_STATS_INFO to get test statistics.
Use HTSetCommand with PPP_STATS_RESET to reset the counters.
Original Function Message Function iType1 Related Structure
HTGetStructure PPP_STATUS_INFO PPPStatusInfo
HTGetStructure PPP_STATS_INFO PPPStatsInfo
HTSetCommand PPP_STATS_RESET —
Original Function Description
HTRun Send test traffic.
HGStop/HGRun (HGStep) For a group start, first initialize the timestamps on all cards/modules using the “Timestamp-Initialization Sequence.” Then send test traffic using HGRun or HGStep.
HTStop/HGStop Stop the test traffic, if running continuous traffic as opposed to step or burst.
Original Function Message Function iType1 Related Structure
HTSetStructure PPP_STATS_INFO PPPStatsInfo
HTSetCommand PPP_STATS_RESET —
Chapter 18: SmartMetrics/TeraMetrics TestingGetting Real-Time Statistics with LAN TeraMetrics
SmartLibrary Overview and Procedures | 411
Getting Real-Time Statistics with LAN TeraMetricsThis section tells how to retrieve real-time statistics without stopping the test. It uses the new stream configuration functions. For more information on these stream commands, see “Using the New Stream Configuration Commands” on page 319.
Module Support
The commands used for real-time statistics retrieval are supported by the following SmartBits modules.
SmartBits Module Description
LAN-3300A 10/100/1000Base-T Ethernet, Copper, 2-port, SmartMetrics
LAN-3301A 10/100/1000Base-T Ethernet, Copper, 2-port, TeraMetrics
LAN-3302A 10/100Base-TX Ethernet, Copper, 2-port, SmartMetrics
LAN-3306A 10/100Base-TX Ethernet, Copper, 4-port, TeraMetrics XD
LAN-3310A 1000Base-X Ethernet, GBIC, 2-port, SmartMetrics
LAN-3311A 1000Base-X Ethernet, GBIC, 2-port, TeraMetrics
LAN-3320A 10/100/1000 Mbps and Gigabit Ethernet Fiber, 2-port, SmartMetrics XD
LAN-3321A 10/100/1000 Mbps and Gigabit Ethernet Fiber, 2-port, TeraMetrics XD
LAN-3324A 10/100/1000 Mbps and Gigabit Ethernet Fiber, 4-port, SmartMetrics XD
LAN-3325A 10/100/1000 Mbps and Gigabit Ethernet Fiber, 4-port, TeraMetrics XD
LAN-3327A 10/100/1000 Mbps and Gigabit Ethernet Fiber, 12-port, TeraMetrics XD
XLW-3720A 10GBase Ethernet XENPAK MSA, 1-port, 2-slot, SmartMetrics
XLW-3721A 10GBase Ethernet XENPAK MSA, 1-port, 2-slot, TeraMetrics
XFP-3730A 10GBase Ethernet XFP MSA, 1-port, 1-slot, SmartMetrics
XFP-3731A 10GBase Ethernet XFP MSA, 1-port, 2-slot, TeraMetrics
Chapter 18: SmartMetrics/TeraMetrics TestingGetting Real-Time Statistics with LAN TeraMetrics
412 | SmartLibrary Overview and Procedures
Commands
Summary of commands
Table 18-16 is a summary of the commands used in setting up tests with real-time statistics retrieval. Not all commands are required. This list is an overview.
A basic setup See “Example of Test Configuration Steps” on page 415 for a basic setup procedure as well as optional commands and actions.
Table 18-16.Real-Time Statistics Retrieval Commands
What the Commands Do Applicable Commands
Original Function Message Function iType1 (or Notes)
Reset the port to the default state.
HTResetPort —
Clear the counters. HTClearPort —
Create a stream configuration object.
NSCreateStreamConfigObject —
Delete a stream configuration object.
NSDeleteStreamConfigObject —
Create one or more streams for a stream configuration object.
NSCreateStream —
Create one or more streams based on an existing stream.
NSCopyStream —
Delete all streams in a stream configuration object.
NSDeleteAllStreams —
Retrieve the number of streams defined in a stream configuration object.
NSGetStreamCount Note that the information retrieved is from the configuration stored in the library and not from a physical port.
Create a protocol header for one or more streams.
NSCreateProtocolHeader —
Update a protocol header for one or more streams.
NSUpdateProtocolHeader —
Create/modify a protocol header for one or more streams based upon an existing stream's header.
NSCopyProtocolHeader —
Chapter 18: SmartMetrics/TeraMetrics TestingGetting Real-Time Statistics with LAN TeraMetrics
SmartLibrary Overview and Procedures | 413
Retrieve header information for one or more streams.
NSGetProtocolHeader Note that the information retrieved is from the configuration stored in the library and not from a physical port.
Retrieve information about the protocol types for each of the headers in a stream.
NSGetProtocolHeaderStackInfo Note that the information retrieved is from the configuration stored in the library and not from a physical port.
Update the transmit settings for one or more streams.
NSUpdateTxConfig —
Modify the transmit settings for one or more streams based upon the transmit settings of an existing stream.
NSCopyTxConfig —
Retrieve the transmit settings for one or more streams.
NSGetTxConfig Note that the information retrieved is from the configuration stored in the library and not from a physical port.
Update VFD settings for one or more streams.
NSUpdateVFD —
Retrieve VFD settings for one or more streams.
NSGetVFD Note that the information retrieved is from the configuration stored in the library and not from a physical port.
Commit/send down the configuration for a stream configuration object to a physical port on a module.
NSCommitStreamConfigObject —
Delete all streams in a stream configuration object.
NSDeleteAllStreams —
Specify SmartMetrics (histogram) results.
HTSetCommand NS_HIST_COMBO_PER_STREAM
Configure real-time statistics tracking mode.
HTSetStructure NS_HIST_LATENCY_OPTION
Retrieve histogram-related settings.
HTGetStructure NS_HIST_LATENCY_OPTION_INFO
Table 18-16.Real-Time Statistics Retrieval Commands (continued)
What the Commands Do Applicable Commands
Original Function Message Function iType1 (or Notes)
Chapter 18: SmartMetrics/TeraMetrics TestingGetting Real-Time Statistics with LAN TeraMetrics
414 | SmartLibrary Overview and Procedures
Clear previous histogram records and restart the histogram test.
HTSetCommand NS_HIST_START
Set up port groups. HGSetGroupHGAddtoGroup
—
Specify port transmit parameters.
HTSetStructure NS_PORT_TRANSMIT
Transmit test frames and then stop the test.
HTRunHTStop
HGStartHGStepHGStop
For single-port start/stop.
For group start/stop.
Retrieve the stream IDs being tracked on a port. This information is useful when retrieving the histogram results.
HTGetStructure NS_STREAM_ID_TABLE_INFO
Get histogram results. HTGetStructure NS_HIST_COMBO_PER_STREAM_INFO
Table 18-16.Real-Time Statistics Retrieval Commands (continued)
What the Commands Do Applicable Commands
Original Function Message Function iType1 (or Notes)
Chapter 18: SmartMetrics/TeraMetrics TestingGetting Real-Time Statistics with LAN TeraMetrics
SmartLibrary Overview and Procedures | 415
Example of Test Configuration Steps
The following is an example of how to set up and run a test where real-time statistics are retrieved. It assumes no previous configuration. It shows selected commands, not all possible commands or actions.
Step 1 Connect to the SmartBits chassis, and reserve modules.
Step 2 Reset the card and clear all counters.
Step 3 Create a stream configuration object.
Step 4 Create one or more streams for the stream configuration object.
Step 5 Define a header for one or more streams.
Use Description
NSSocketLink Connect to the chassis.
HTSlotReserve Reserve modules.
Use Description
HTResetPort Reset the card and clear all counters.
Use Description
NSCreateStreamConfigObject Create the stream configuration object.
Use Description
NSCreateStream Create a stream that is inserted in or appended to the stream configuration object.
Use Description
NSCreateProtocolHeader Create a protocol header that is inserted in or appended to one or more streams.
Chapter 18: SmartMetrics/TeraMetrics TestingGetting Real-Time Statistics with LAN TeraMetrics
416 | SmartLibrary Overview and Procedures
Step 6 Configure the transmit settings.
Step 7 (optional) Configure VFD1 and VFD2 settings.
Step 8 Commit the streams to a port.
Step 9 Configure the port transmit setting.
Step 10 (optional) Modify a field in a block of streams.
Note that this command does not update the stream configuration settings stored in the library.
Step 11 Set up port groups.
Use Description
NSUpdateTxConfig Updates the transmission-related settings for one or more streams.
Note that you must enable the signature field when running histogram tests. To do this, set the ucEnableSignatureField element in the NSTxConfig structure to 1.
Use Description
NSUpdateVFD Updates VFD (Variable Field Definition) settings for one or more streams.
Use Description
NSCommitStreamConfigObject Commit the streams in the stream configuration object to a port.
Use with Message Function iType1 Related Structure
HTSetStructure NS_PORT_TRANSMIT NSPortTransmit
Use with Message Function iType1 Related Structure
HTSetStructure L3_MOD_STREAMS_ARRAY Layer3ModifyStreamArray
Use Description
HGSetGroup Groups a number of SmartBits ports.
HGAddtoGroup Used with HGSetGroup to add individual hub/slot/port cards to a group.
Chapter 18: SmartMetrics/TeraMetrics TestingGetting Real-Time Statistics with LAN TeraMetrics
SmartLibrary Overview and Procedures | 417
Step 12 Set up a jumbo histogram test.
This histogram test gives an overall picture of latency per stream. It provides the following results:
• Latency per stream – Shows minimum, maximum, and average latency values over the course of the test.
• Latency distribution – Shows the occurrence of specific latency values per stream.
• Sequence tracking – Reports whether or not frames were received in sequence per stream.
Step 13 Configure real-time statistics tracking mode on the receiving port.
Note: In the NSHistLatencyOption structure, set the uiOption element to NS_TRACK_STREAM_ID. This mode is only available when running the jumbo histogram test.
Step 14 Clear the previous histogram records and start the test on the port.
Step 15 Send test traffic.
Step 16 Retrieve the stream IDs being tracked on the receiving port.
Step 17 Retrieve the jumbo histogram results.
Use with Message Function iType1 Related Structure
HTSetStructure NS_HIST_COMBO_PER_STREAM NSHistComboPerStream
Use with Message Function iType1 Related Structure
HTSetStructure NS_HIST_LATENCY_OPTION NSHistLatencyOption
Use with Message Function iType1 Related Structure
HTSetCommand NS_HIST_START —
Use Description
HGStart Start transmission of packets
Use with Message Function iType1 Related Structure
HTGetStructure NS_STREAM_ID_TABLE_INFO NSStreamIDTableInfo
Use with Message Function iType1 Related Structure
HTGetStructure NS_HIST_COMBO_PER_STREAM_INFO NSHistComboPerStreamInfo
Chapter 18: SmartMetrics/TeraMetrics TestingGetting Real-Time Statistics with LAN TeraMetrics
418 | SmartLibrary Overview and Procedures
Step 18 Stop test traffic.
Step 19 (optional) Delete all streams in the stream configuration object.
Step 20 Delete the stream configuration object.
Step 21 Release all reserved modules and unlink from the SmartBits chassis.
End of Test Configuration Steps
This completes the steps needed to run a simple test where real-time statistics are retrieved.
Use Description
HGStop Stop transmission of packets
Use Description
NSDeleteAllStreams Deletes all streams in a stream configuration object.
Use Description
NSDeleteStreamConfigObject Delete the stream configuration object and all associated child objects (that is, the stream and protocol header).
Use Description
HTSlotRelease Releases a slot, making it available for others.
NSUnLink Ends the connection to the SmartBits chassis.
Chapter 18: SmartMetrics/TeraMetrics TestingGetting Enhanced Real-Time Statistics with TeraMetrics XD/XFP/XLW Modules
SmartLibrary Overview and Procedures | 419
Getting Enhanced Real-Time Statistics with TeraMetrics XD/XFP/XLW Modules
This section tells how to retrieve the enhanced real-time statistics on XD/XFP/XLW modules. It uses the new stream configuration functions. For more information on these stream commands, see “Using the New Stream Configuration Commands” on page 319.
If you are using Alternate Key, starting with SmartLib 5.50 and TeraMetrics firmware 5.50, Alternate Key is fully supported for runtime statistics retrieval. This means that if Alternate Key is enabled on the port, the StreamID field will actually contain a Lookup Key, not just a StreamID. The Lookup Key is created by combining the StreamID with the Alternate Key (which is masked-out of the frame at a user-specified location). This means that the user would typically determine – based on test configuration – which lookup keys are expected and specify these Lookup Keys when passing down the array of StreamIDs in the NS_RUNTIME_HIST_STATS_CONFIG message. Then when stats are retrieved using NSEnhancedRunTimeHistStatsInfo, the StreamID field will actually contain the Lookup Key. For further information on the Alternate Key feature see “Set Up Alternate Key on TeraMetrics Modules” on page 379.
Generally a histogram test includes the following countersTotal Latency Frame Count (In Sequence + Out-of-Sequence)Latency Buckets (16 Buckets)Time Stamp (First or Last timestamp)In SequenceOut-of-SequenceMin LatencyMax Latency
Prior to SmartLib 5.50 and TeraMetrics firmware 5.50, a user could only get some of these counters, but not all of them in one test. However for XD/XLW/XFP modules, starting with SmartLib 5.50 and TeraMetrics firmware 5.50, all of the counters are always available in a histogram test. And any combination of them can be chosen with NSEnhancedRunTimeHistStatsInfo.
Therefore for XD/XLW/XFP modules the user does not need to call NS_HIST_LATENCY_OPTION or NS_HIST_ENHANCED_LATENCY_OPTION to set the latency test options. For XD/XLW/XFP modules, NS_HIST_ENHANCED_LATENCY_OPTION is only used to set the timestamp option on the card, that is, to retrieve the timestamp of the first frame received in the stream or the last frame received in the stream.
Chapter 18: SmartMetrics/TeraMetrics TestingGetting Enhanced Real-Time Statistics with TeraMetrics XD/XFP/XLW Modules
420 | SmartLibrary Overview and Procedures
Timestamp Mode
By default, the “FirstTimestamp” mode is set on the cards. The timestamp option can be changed at runtime.
Note: If the port is set in “LastTimestamp” mode at the time the first frame arrives, the first timestamp will be permanently lost.
Module Support
The commands used for real-time statistics retrieval are supported by the following SmartBits modules.
SmartBits Module Description
LAN-3320A 10/100/1000 Mbps and Gigabit Ethernet Fiber, 2-port, SmartMetrics XD
LAN-3321A 10/100/1000 Mbps and Gigabit Ethernet Fiber, 2-port, TeraMetrics XD
LAN-3324A 10/100/1000 Mbps and Gigabit Ethernet Fiber, 4-port, SmartMetrics XD
LAN-3325A 10/100/1000 Mbps and Gigabit Ethernet Fiber, 4-port, TeraMetrics XD
LAN-3327A 10/100/1000 Mbps and Gigabit Ethernet Fiber, 12-port, TeraMetrics XD
XLW-3720A 10GBase Ethernet XENPAK MSA, 1-port, 2-slot, SmartMetrics
XLW-3721A 10GBase Ethernet XENPAK MSA, 1-port, 2-slot, TeraMetrics
XFP-3730A 10GBase Ethernet XFP MSA, 1-port, 1-slot, SmartMetrics
XFP-3731A 10GBase Ethernet XFP MSA, 1-port, 2-slot, TeraMetrics
Chapter 18: SmartMetrics/TeraMetrics TestingGetting Enhanced Real-Time Statistics with TeraMetrics XD/XFP/XLW Modules
SmartLibrary Overview and Procedures | 421
Commands
Summary of commands
Table 18-16 is a summary of the commands used in setting up tests with real-time statistics retrieval. Not all commands are required. This list is an overview.
A basic setup See “Example of Test Configuration Steps” on page 415 for a basic setup procedure as well as optional commands and actions.
Table 18-17.Real-Time Statistics Retrieval Related Commands
What the Commands Do Applicable Commands
Original Function Message Function iType1 (or Notes)
Reset the port to the default state.
HTResetPort —
Clear the counters. HTClearPort —
Create a stream configuration object.
NSCreateStreamConfigObject —
Delete a stream configuration object.
NSDeleteStreamConfigObject —
Create one or more streams for a stream configuration object.
NSCreateStream —
Create one or more streams based on an existing stream.
NSCopyStream —
Delete all streams in a stream configuration object.
NSDeleteAllStreams —
Retrieve the number of streams defined in a stream configuration object.
NSGetStreamCount Note that the information retrieved is from the configuration stored in the library and not from a physical port.
Create a protocol header for one or more streams.
NSCreateProtocolHeader —
Update a protocol header for one or more streams.
NSUpdateProtocolHeader —
Create/modify a protocol header for one or more streams based upon an existing stream's header.
NSCopyProtocolHeader —
Chapter 18: SmartMetrics/TeraMetrics TestingGetting Enhanced Real-Time Statistics with TeraMetrics XD/XFP/XLW Modules
422 | SmartLibrary Overview and Procedures
Retrieve header information for one or more streams.
NSGetProtocolHeader Note that the information retrieved is from the configuration stored in the library and not from a physical port.
Retrieve information about the protocol types for each of the headers in a stream.
NSGetProtocolHeaderStackInfo Note that the information retrieved is from the configuration stored in the library and not from a physical port.
Update the transmit settings for one or more streams.
NSUpdateTxConfig —
Modify the transmit settings for one or more streams based upon the transmit settings of an existing stream.
NSCopyTxConfig —
Retrieve the transmit settings for one or more streams.
NSGetTxConfig Note that the information retrieved is from the configuration stored in the library and not from a physical port.
Update VFD settings for one or more streams.
NSUpdateVFD —
Retrieve VFD settings for one or more streams.
NSGetVFD Note that the information retrieved is from the configuration stored in the library and not from a physical port.
Commit/send down the configuration for a stream configuration object to a physical port on a module.
NSCommitStreamConfigObject —
Delete all streams in a stream configuration object.
NSDeleteAllStreams —
Specify SmartMetrics (histogram) results.
HTSetCommand NS_HIST_COMBO_PER_STREAM(Required)
Set up Alternate Key. HTSetStructure NS_ALTERNATE_KEY_CONFIG(Optional)
Query Alternate Key. HTGetStructure NS_ALTERNATE_KEY_CONFIG_INFO(Optional)
Table 18-17.Real-Time Statistics Retrieval Related Commands (continued)
What the Commands Do Applicable Commands
Original Function Message Function iType1 (or Notes)
Chapter 18: SmartMetrics/TeraMetrics TestingGetting Enhanced Real-Time Statistics with TeraMetrics XD/XFP/XLW Modules
SmartLibrary Overview and Procedures | 423
Configure Alternate Key Hash.
HTSetStructure NS_ALTERNATE_KEY_HASH_CONFIG(Optional)
Query the Configured Alternate Key Hash
HTGetStructure NS_ALTERNATE_KEY_HASH_CONFIG_INFO (Optional)
Clear previous histogram records and restart the histogram test.
HTSetCommand NS_HIST_START(Required)
Table 18-17.Real-Time Statistics Retrieval Related Commands (continued)
What the Commands Do Applicable Commands
Original Function Message Function iType1 (or Notes)
Chapter 18: SmartMetrics/TeraMetrics TestingGetting Enhanced Real-Time Statistics with TeraMetrics XD/XFP/XLW Modules
424 | SmartLibrary Overview and Procedures
Specify the stream IDs to be tracked for Run-Time stats.
HTSetStructure NS_RUNTIME_HIST_STATS_CONFIG
Notes:
1.This command can be sent before or after the start of the test (this “start” is the time that transmission is started on Tx ports). However it is better to send this command before the start of the test so that the construction of the hash table will start immediately on receipt of the first frame
2.The array of 64 StreamIDs may be changed on the fly at any time.
3.The settings specified by the NS_RUNTIME_HIST_STATS_CONFIG message will be erased and disabled if calling command to start the histogram test NS_HIST_START, or any traditional histogram info commands, such as NS_HIST_COMBO_PER_STREAM_INFO.
4.For user using Alternate Key, the hash mode configured by NS_ALTERNATE_KEY_HASH_CONFIG should never be changed after calling NS_RUNTIME_HIST_STATS_CONFIG. However if the mode is set to “RUNTTIME_MODE_OFF”, it effectively disables the feature entirely and then it would be fine to change the hash mode.
5.Depending on the traffic conditions, the user may want to send this message several times to verify that the desired streams have been learned before calling NSEnhancedRunTimeHistStatsInfo.
Table 18-17.Real-Time Statistics Retrieval Related Commands (continued)
What the Commands Do Applicable Commands
Original Function Message Function iType1 (or Notes)
This is an Enhanced Real-time Statistics Command (Required)
Chapter 18: SmartMetrics/TeraMetrics TestingGetting Enhanced Real-Time Statistics with TeraMetrics XD/XFP/XLW Modules
SmartLibrary Overview and Procedures | 425
Configure a port to keep track of a specified latency type when running latency histogram tests. (Only to set timestamp option here.)
HTSetStructure NS_HIST_ENHANCED_LATENCY_OPTION
Notes:
1.For XD/XFP/XLW modules, this command is only to change the timestamp option since their basic histogram stats mode is always NS_HIST_EN_ENHANCED_RUNTIME.
2.User can choose to track the timestamp of the first frame received in this stream or the last frame received in this stream.
3.The timestamp mode can be changed during the runtime. By default, the “FirstTimestamp” mode is set on the cards. Note that if the port is set to “LastTimestamp” mode at the time the first frame arrives, the first timestamp will be permanently lost.
Retrieve Histogram Latency settings
HTGetStructure NS_HIST_ENHANCED_LATENCY_OPTION_INFO
Set up port groups. HGSetGroupHGAddtoGroup
(Required)
Specify port transmit parameters.
HTSetStructure NS_PORT_TRANSMIT
Transmit test frames and then stop the test.
HTRunHTStop
HGStartHGStepHGStop
For single-port start/stop. (Required)
For group start/stop. (Required)
Table 18-17.Real-Time Statistics Retrieval Related Commands (continued)
What the Commands Do Applicable Commands
Original Function Message Function iType1 (or Notes)
This is an Enhanced Real-time Statistics Command (Optional)
This is an Enhanced Real-time Statistics Command (Optional)
Chapter 18: SmartMetrics/TeraMetrics TestingGetting Enhanced Real-Time Statistics with TeraMetrics XD/XFP/XLW Modules
426 | SmartLibrary Overview and Procedures
Retrieve at runtime any combination of the histogram counters which are normally available at the end of the test.
NSEnhancedRunTimeHistStatsInfo
Notes:
1.This command can be called anytime after NS_RUNTIME_HIST_STATS_CONFIG is called. But note that too frequent calls might overload the card if the time interval is too small.
2.It is allowed not to request any fields (ulCounterType can be 0). This can be used to find out if any frames have arrived on a port.
Get histogram results. HTGetStructure NS_HIST_COMBO_PER_STREAM_INFO(Optional, after-test)
Table 18-17.Real-Time Statistics Retrieval Related Commands (continued)
What the Commands Do Applicable Commands
Original Function Message Function iType1 (or Notes)
This is an Enhanced Real-time Statistics Command (Optional)
Chapter 18: SmartMetrics/TeraMetrics TestingGetting Enhanced Real-Time Statistics with TeraMetrics XD/XFP/XLW Modules
SmartLibrary Overview and Procedures | 427
Example of Test Configuration Steps
The following is an example of how to set up and run a test where real-time statistics are retrieved. It assumes no previous configuration. It shows selected commands, not all possible commands or actions.
Step 1 Connect to the SmartBits chassis, and reserve modules.
Step 2 Reset the card and clear all counters.
Step 3 Create a stream configuration object.
Step 4 Create one or more streams for the stream configuration object.
Step 5 Define a header for one or more streams.
Step 6 Configure the transmit settings.
Use Description
NSSocketLink Connect to the chassis.
HTSlotReserve Reserve modules.
Use Description
HTResetPort Reset the card and clear all counters.
Use Description
NSCreateStreamConfigObject Create the stream configuration object.
Use Description
NSCreateStream Create a stream that is inserted in or appended to the stream configuration object.
Use Description
NSCreateProtocolHeader Create a protocol header that is inserted in or appended to one or more streams.
Use Description
NSUpdateTxConfig Updates the transmission-related settings for one or more streams.
Note that you must enable the signature field when running histogram tests. To do this, set the ucEnableSignatureField element in the NSTxConfig structure to 1.
Chapter 18: SmartMetrics/TeraMetrics TestingGetting Enhanced Real-Time Statistics with TeraMetrics XD/XFP/XLW Modules
428 | SmartLibrary Overview and Procedures
Step 7 (optional) Configure VFD1 and VFD2 settings.
Step 8 Commit the streams to a port.
Step 9 Configure the port transmit setting.
Step 10 (optional) Modify a field in a block of streams.
Note that this command does not update the stream configuration settings stored in the library.
Step 11 Set up port groups.
Step 12 Set up a jumbo histogram test.
Step 13 (Optional) Set up Alternate Key.
Use Description
NSUpdateVFD Updates VFD (Variable Field Definition) settings for one or more streams.
Use Description
NSCommitStreamConfigObject Commit the streams in the stream configuration object to a port.
Use with Message Function iType1 Related Structure
HTSetStructure NS_PORT_TRANSMIT NSPortTransmit
Use with Message Function iType1 Related Structure
HTSetStructure L3_MOD_STREAMS_ARRAY Layer3ModifyStreamArray
Use Description
HGSetGroup Groups a number of SmartBits ports.
HGAddtoGroup Used with HGSetGroup to add individual hub/slot/port cards to a group.
Use with Message Function iType1 Related Structure
HTSetStructure NS_HIST_COMBO_PER_STREAM NSHistComboPerStream
Use with Message Function iType1 Related Structure
HTSetStructure NS_ALTERNATE_KEY_COMFIG NSAlternateKey Config
Chapter 18: SmartMetrics/TeraMetrics TestingGetting Enhanced Real-Time Statistics with TeraMetrics XD/XFP/XLW Modules
SmartLibrary Overview and Procedures | 429
Step 14 (Optional) Set up Alternate Key Hash Algorithm
Note: For using Alternate Key, the hash mode configured should never be changed after calling NS_RUNTIME_HIST_STATS_CONFIG.
Step 15 Clear the previous histogram records and start the test on the port.
Step 16 Specify the stream IDs to be tracked for Run-Time stats.
Note: This command can be called at any time during the test.
Step 17 (Optional) Set up the timestamp option.
Note: For XD/XLW/XFP modules, this command is only to set up the timestamp option.
Step 18 Send test traffic.
Step 19 Retrieve the Runtime histogram counters.
Note: This message can be called as frequently as desired but it might overload the card if the time interval is too small..
Use with Message Function iType1 Related Structure
HTSetStructure NS_ALTERNATE_KEY_HASH_CONFIG
NSAlternateKeyHashConfig
Use with Message Function iType1 Related Structure
HTSetCommand NS_HIST_START —
Use with Message Function iType1 Related Structure
HTSetStructure NS_RUNTIME_HIST_STATS_CONFIG
NSRunTimeHistStatsConfig
Use with Message Function iType1 Related Structure
HTSetStructure NS_HIST_ENHANCED_LATENCY_OPTION
NSHistEnhancedLatencyOption
Use Description
HGStart Start transmission of packets
Use Description
NSEnhancedRunTimeHistStatsInfo
Retrieve at runtime any combination of the histogram counters.
Chapter 18: SmartMetrics/TeraMetrics TestingGetting Enhanced Real-Time Statistics with TeraMetrics XD/XFP/XLW Modules
430 | SmartLibrary Overview and Procedures
Step 20 Stop test traffic.
Step 21 (Optional) Retrieve the jumbo histogram results.
Step 22 (optional) Delete all streams in the stream configuration object.
Step 23 Delete the stream configuration object.
Step 24 Release all reserved modules and unlink from the SmartBits chassis.
End of Test Configuration Steps
This completes the steps needed to run a simple test where real-time statistics are retrieved.
Use Description
HGStop Stop transmission of packets
Use with Message Function iType1 Related Structure
HTGetStructure NS_HIST_COMBO_PER_STREAM_INFO
NSHistComboPerStreamInfo
Use Description
NSDeleteAllStreams Deletes all streams in a stream configuration object.
Use Description
NSDeleteStreamConfigObject Delete the stream configuration object and all associated child objects (that is, the stream and protocol header).
Use Description
HTSlotRelease Releases a slot, making it available for others.
NSUnLink Ends the connection to the SmartBits chassis.
SmartLibrary Overview and Procedures | 431
Chapter 19
Packet Over SONET Testing
This chapter provides step-by-step procedures you can use to set up tests with the Packet Over SONET (POS) family of modules.
It includes two procedures: One for the POS-3500B/BS module, and one for the POS-3519AS/AR and POS-3518AS/AR modules.
In this chapter...
• Set Up Tests with POS-3500B/Bs Modules . . . . 432
• Set Up Tests with POS-3519As/Ar and 3518As/Ar Modules . . . . 441
• Test with IPv6 Streams on POS TeraMetrics Modules . . . . 453
Chapter 19: Packet Over SONET TestingSet Up Tests with POS-3500B/Bs Modules
432 | SmartLibrary Overview and Procedures
Set Up Tests with POS-3500B/BS ModulesYou can use the POS-3500B/BS modules to test core and edge POS router capabilities at OC-12c/STM-4 wire rate. SmartMetrics capabilities enable you to measure key metrics such as load capacity, latency, and IP frame sequencing.These POS modules provide:
• Encapsulation using PPP per RFC-1662 or HDLC with Ethertype (Cisco HDLC).• Generation of up to 8,192 streams and analyzing results.• Up to 64,000 flows per stream (a total of 524 million flows per port).• Testing of actual POS router performance using SmartMetrics tests, including the
tracking of:• Per-flow frame-loss• Latency• Latency and Sequence• Latency Distribution
Applicable Commands
Table 19-1 is a summary of commands you can use in POS tests. Not all commands are required. This list is an overview.
A basic setup See “Example of Setup Steps” on page 434 for a basic setup procedure, as well as optional commands and actions.
Table 19-1. Applicable Commands for POS Tests using the POS-3500B/BS Module
Applicable Commands
What the Commands Do Original Function Message Function iType1/Notes
Reset card to the default state. HTResetPort —
Clear counters. HTClearPort —
Set up streams. HTSetStructure L3_DEFINE_<n>_STREAM
Configure the POS port. HTSetStructure POS_CARD_LINE_CONFIGPOS_CARD_PORT_ENCAPPOS_CONFIG
HTSetCommand POS_SET_SPEED
Set up port groups. HGSetGroupHGAddtoGroup
—
Set up SmartMetrics histogram results.
HTSetStructure NS_HIST_COMBO_PER_STREAM
Chapter 19: Packet Over SONET TestingSet Up Tests with POS-3500B/Bs Modules
SmartLibrary Overview and Procedures | 433
—or— —or—
Set up data capture. HTSetStructure NS_CAPTURE_SETUP
Transmit test frames, then stop the test.
HTRunHTStop
For single-port start/stop.
HGRunHGStepHGStop
For group start/stop.
Get test counters. HTGetStructure L2_READ_COUNTERSL2_READ_RATES
Get captured data. HTGetStructure NS_CAPTURE_COUNT_INFONS_CAPTURE_DATA_INFO
—or— —or—
Get SmartMetrics histogram results.
HTGetStructure NS_HIST_COMBO_PER_STREAM
Table 19-1. Applicable Commands for POS Tests using the POS-3500B/BS Module (continued)
Applicable Commands
What the Commands Do Original Function Message Function iType1/Notes
Chapter 19: Packet Over SONET TestingSet Up Tests with POS-3500B/Bs Modules
434 | SmartLibrary Overview and Procedures
Example of Setup Steps
Here is an example of how to set up tests with the POS-3500B/BS. It assumes no previous configuration. It shows selected commands, not all possible commands or actions.
Step 1 Reset the Card and Clear All Counters
Use HTResetPort to set the card to a known, default state.
Use HTClearPort to clear all counters.
Step 2 Set Up the Streams
Use HTSetStructure with L3_DEFINE_<n>_STREAM to configure test traffic. Here, <n> represents the stream type and can be IP, IPX, UDP, TCP, or SmartBits. This function specifies the stream template—that is, the structure of frames to be sent.
Use L3_DEFINE_STREAM_EXTENSION to define additional stream characteristics, such as frame rate, transmit mode, and burst count.
Define Multiple Streams. Use L3_DEFINE_MULTI_<n>_STREAM to define multiple streams. Here, <n> represents the stream type and can be IP, IPX, UDP, TCP, or SmartBits.
With multiple streams, use L3_DEFINE_MULTI_STREAM_EXTENSION to set up the stream characteristics.
Optional/RelatedOptional or related commands and actions (if applicable) are shown in a shaded box. These actions are not required for a basic test setup.
Use: with Message Function iType1 Related Structure
HTResetPort — None
HTClearPort — None
Use: with Message Function iType1 Related Structure
HTSetStructure L3_DEFINE_<n>_STREAM Stream<n>
L3_DEFINE_STREAM_EXTENSION StreamExtension
L3_DEFINE_MULTI_<n>_STREAM Stream<n>
L3_DEFINE_MULTI_STREAM_EXTENSION
StreamExtension
Chapter 19: Packet Over SONET TestingSet Up Tests with POS-3500B/Bs Modules
SmartLibrary Overview and Procedures | 435
Step 3 Configure the POS Port
Configure the POS line parameters, encapsulation type, and port speed.
Step 4 Send Test Traffic, Stop Test Traffic
Use the HTRun or HGRun command to run the test.
Use HTStop or HGStop to stop the test when run with continuous traffic.
End of Required Steps for Basic Setup
This completes the basic steps needed to transmit test traffic. The usefulness of your test, however, depends on getting test results. See “Getting Test Results” on page 436 for the steps to use counters, capture, or histograms to measure test traffic.
Use: with Message Function iType1 Description
HTSetStructure POS_CARD_LINE_CONFIG Configure POS line parameters.
POS_CARD_PORT_ENCAP Define POS encapsulation.
POS_CONFIG Configure the POS transceiver.
HTSetCommand POS_SET_SPEED Set the POS port speed.
Use: Description
HTRun Send test traffic.
HGStop/HGRun (HGStep) For a group start, first initialize the timestamps on all cards/modules using the “Timestamp-Initialization Sequence.” Then send test traffic using HGRun or HGStep.
HTStop/HGStop Stop the test traffic, if running continuous traffic as opposed to step or burst.
Chapter 19: Packet Over SONET TestingSet Up Tests with POS-3500B/Bs Modules
436 | SmartLibrary Overview and Procedures
Getting Test Results
Your test can provide three types of results. These are:– Counters– Captured data — or —– Histograms
Counters Counters are always available. You need not enable them or set them up explicitly. You can get counter information during the test or after it stops.
Captured data and histograms
You can also retrieve captured data or histograms, but not both in the same test. For these, you must specify the type of results desired, and you must enable the function. You set up data capture or histogram results before you start your test. You obtain either type of results after you run the test.
How to Get Counter Information
Use HTGetStructure with L2_READ_COUNTERS to verify that the number of frames received was as expected.
Use HTGetStructure with L2_READ_RATES to get rate information.
Original Function Message Function iType1 Related Structure
HTGetStructure L2_READ_COUNTERS L2StatsInfo
L2_READ_RATES L2RateInfo
Chapter 19: Packet Over SONET TestingSet Up Tests with POS-3500B/Bs Modules
SmartLibrary Overview and Procedures | 437
How to Set Up Data Capture
Use the following steps to set up data capture.Step 1 Set up the capture parameters.
Use HTSetStructure with NS_CAPTURE_SETUP(NSCaptureSetup) to specify the capture mode, length, and event.
Capture Mode. Valid options for Layer3CaptureSetup(ulCaptureMode) include:
Capture Events. The CAPTURE_EVENTS element in Layer3CaptureSetup defines what frame types should be captured. Valid options for Layer3CaptureSetup(ulCaptureEvents) include:
Original Function Message Function iType1 Related Structure
HTSetStructure NS_CAPTURE_SETUP NSCaptureSetup
Capture Mode Description
CAPTURE_MODE_FILTER_ON_EVENTS Capture only packets with the specified event, such as CRC errors, undersize packets, or oversize packets.
CAPTURE_MODE_START_ON_EVENTS Capture all packets following the specified event. For example, begin capture when the first packet with a CRC error is received, then capture all packets.
CAPTURE_MODE_STOP_ON_EVENTS Capture all packets until the specified event. For example, capture all packets until the first packet with a CRC error is received, then stop the capture.
Capture Event Description
CRC_ERRORS Capture all frames with CRC errors.
IP_CHECKSUM_ERROR Capture all frames with IP checksum errors.
DATA_INTEGRITY_ERROR Capture all frames in which the payload contents have become corrupted.
RX_TRIGGER Capture all frames that contain receive trigger patterns.
Chapter 19: Packet Over SONET TestingSet Up Tests with POS-3500B/Bs Modules
438 | SmartLibrary Overview and Procedures
Step 2 Start the capture, then stop it.
Step 3 Get the captured data.
Use HTGetStructure with NS_CAPTURE_COUNT_INFO to find the number of frames in the buffer.
Use HTGetStructure with NS_CAPTURE_DATA_INFO to get the captured frames.
Original Function Message Function iType1 Description
HTSetCommand NS_CAPTURE_START Clear the buffer and start the capture.
NS_CAPTURE_STOP Stop capture.
Original Function Message Function iType1 Related Structure
HTGetStructure NS_CAPTURE_COUNT_INFO NSCaptureCountInfo
NS_CAPTURE_DATA_INFO NSCaptureDataInfo
Chapter 19: Packet Over SONET TestingSet Up Tests with POS-3500B/Bs Modules
SmartLibrary Overview and Procedures | 439
How to Set Up SmartMetrics Histograms
Histograms provide in-depth test results, including sequence and latency information.
Histogram information is gathered on the receiving card.
Step 1 Enable the histogram type.
POS tests use a “jumbo” histogram that provides Latency, Sequence and Latency, and Latency Distribution results. Before you start the test, specify the type of histogram information to be gathered. Use L3_HIST_ V2_LATENCY_PER_STREAM to enable the histogram for the test.
Step 2 Set up port groups.
For SmartMetrics histogram results, you must set up a port group. Histogram results require a group start.
Use HGSetGroup and HGAddtoGroup to define the port group and to add ports to a group.
Original Function Message Function iType1 Related Structure
HTSetCommand NS_HIST_COMBO_PER_STREAM NSHistComboPerStream
Gives an overall picture of latency per stream. Provides the following results:
Latency per Stream. Shows minimum, maximum, and average latency values over the course of the test.
Latency Distribution. Shows the occurrence of specific latency values per stream.
Sequence Tracking. Reports whether or not frames were received in sequence per stream.
Original Function Description
HGSetGroup Define a group of SmartBits ports.
HGAddtoGroup Add ports to the group. You control grouped ports by using the HG commands.
Chapter 19: Packet Over SONET TestingSet Up Tests with POS-3500B/Bs Modules
440 | SmartLibrary Overview and Procedures
Step 3 Gather histogram information.
After the test runs, gather the latency-per-stream histogram information. Use HTGetStructure with NS_HIST_COMBO_PER_STREAM_INFO.
Original Function Message Function iType1 Related Structure
HTGetStructure NS_HIST_COMBO_PER_STREAM_INFO NSHistComboPerStreamInfo
Latency Distribution histogram results.
Chapter 19: Packet Over SONET TestingSet Up Tests with POS-3519As/Ar and 3518As/Ar Modules
SmartLibrary Overview and Procedures | 441
Set Up Tests with POS-3519AS/AR and 3518AS/AR ModulesYou can use the POS-3519AS/AR TeraMetrics module and POS-3518AS/AR SmartMetrics module for frame-level testing of Packet over SONET/SDH routers at full OC-192c/STM-64 wire rate. Both modules are similar in functionality, but the POS-3519AS/AR TeraMetrics module is based on the TeraMetrics™ architecture and includes an on-board Linux operating system. The POS-3518AS/AR SmartMetrics module does not include this TeraMetrics capability.
Applicable Commands
Table 19-2 is a summary of commands you can use in POS tests with these modules. Not all commands are required. This list is an overview.
A basic setup See “Example of Setup Steps” on page 443 for a basic setup procedure, as well as optional commands and actions.
Table 19-2. Applicable Commands: POS Tests Using POS-3519As/3518As Modules
Applicable Commands
What the Commands Do Original Function Message Function iType1/Notes
Reset card to the default state. HTResetPort See “Example of Setup Steps” on page 443.
Clear counters. HTClearPort See“Example of Setup Steps” on page 443.
Set up streams. HTSetStructure L3_DEFINE_<n>_STREAM
Specify the scheduling mode (either gap-based or rate-based).
HTSetStructure
—or—
HTScheduleMode
NS_PORT_TRANSMIT
—
Configure the POS port. HTSetStructure POS_CARD_LINE_CONFIGPOS_CARD_PORT_ENCAPPOS_CONFIGNS_HW_CONFIG
HTSetCommand POS_SET_SPEED
Specify SmartMetrics (histogram) results.
—or—
HTSetStructureHTSetStructureHTSetCommandHTSetCommandHTSetStructure
NS_HIST_COMBO_PER_STREAMNS_HIST_LATENCY_OVER_TIMENS_HIST_RAW_SIGNATURENS_HIST_SEQUENCE_PER_STREAMNS_HIST_LATENCY_DIST_PER_STREAM
Set up data capture. HTSetStructure NS_CAPTURE_SETUP
Continues –>
Chapter 19: Packet Over SONET TestingSet Up Tests with POS-3519As/Ar and 3518As/Ar Modules
442 | SmartLibrary Overview and Procedures
Applicable Commands
What the Commands Do Original Function Message Function iType1/Notes
(Optional) Set up port groups. HGSetGroupHGAddtoGroup
See “Example of Setup Steps” on page 443.
Start data capture (if selected). HTSetCommand NS_CAPTURE_START
Transmit test frames. HTRun For single-port start.
HGRunHGStep
For group start.
Stop the test. HTStopHGStop
See “Example of Setup Steps” on page 443.
Stop data capture (if selected). HTSetCommand NS_CAPTURE_STOP
Get counters and rates. HTGetStructure L2_READ_COUNTERSL2_READ_RATES
Get histogram results.
— or —
HTGetStructure
— or —
NS_HIST_COMBO_PER_STREAM_INFONS_HIST_LATENCY_OVER_TIME_INFONS_HIST_RAW_SIGNATURE_INFONS_HIST_SEQUENCE_PER_STREAM_INFONS_HIST_LATENCY_DIST_PER_STREAM_INFO
Get captured data. HTGetStructure NS_CAPTURE_COUNT_INFONS_CAPTURE_DATA_INFO
Table 19-2. Applicable Commands: POS Tests Using POS-3519As/3518As Modules
Chapter 19: Packet Over SONET TestingSet Up Tests with POS-3519As/Ar and 3518As/Ar Modules
SmartLibrary Overview and Procedures | 443
Example of Setup Steps
Here is an example of how to set up tests with the POS-3519AS/AR and POS-3518AS/AR modules. It assumes no previous configuration. It shows selected commands, not all possible commands or actions.
Step 1 Reset the Card and Clear All Counters
Use HTResetPort to set the card to a known, default state. Use HTClearPort to clear all counters.
Step 2 Set Up the Streams
Use HTSetStructure with L3_DEFINE_<n>_STREAM to configure test traffic (<n> represents the stream type and can be IP, IPX, UDP, TCP, or SmartBits). This function specifies the stream template—that is, the structure of frames to be sent.
Use L3_DEFINE_STREAM_EXTENSION to define additional stream characteristics. These are stream attributes such as the frame rate and data integrity check. Two elements in the L3StreamExtension structure do not apply to this module: ulTxMode and ucIPManipulateMode.
Define Multiple Streams. Use L3_DEFINE_MULTI_<n>_STREAM to define multiple streams (<n> represents the stream type and can be IP, IPX, UDP, TCP, or SmartBits).
Optional/RelatedOptional or related commands and actions (if applicable) are shown in a shaded box. These actions are not required for a basic test setup.
Original Function Description
HTResetPort Reset the card or module to a default state.
HTClearPort Clear the port counters.
Original Function Message Function iType1 Related Structure
HTSetStructure L3_DEFINE_<n>_STREAM Stream<n>
L3_DEFINE_STREAM_EXTENSION StreamExtension
L3_DEFINE_MULTI_<n>_STREAM Stream<n>
L3_DEFINE_MULTI_STREAM_EXTENSION
StreamExtension
Chapter 19: Packet Over SONET TestingSet Up Tests with POS-3519As/Ar and 3518As/Ar Modules
444 | SmartLibrary Overview and Procedures
Step 3 Define the Schedule Mode (Gap-based or Rate-based)
You can specify that the streams generated by the port are scheduled and transmitted based either on interframe gap or frame rate. Specifically, you can select one of three options. Streams can be scheduled by:
• Interframe Gap: a fixed number of bit times between frames.
• Random IFG — A varying number of bit times between frames.• Frame Rate — A defined frames-per-second rate of transmission for each stream.
Bursty traffic can still be used.
The selected scheduling mode you assign to a port applies to all streams generated by the port. Test traffic is sent in a round-robin fashion, with one frame from each stream generated in sequence.
For all three scheduling options, a software mechanism on the card (termed the scheduler) calculates how to allocate the overall line bandwidth. It builds a static scheduling table that organizes all streams before any traffic is sent. The schedule table is static in that it does not vary as test traffic is sent—even though two of the scheduling options (Random IFG and Frame Rate) appear to be dynamic in behavior, because they allow individual stream frame rates and random interframe gaps.
Note: The scheduling mechanism used with earlier POS cards, such as the POS-3500B/BS, differs in important ways. Refer to Chapter 4, “Traffic Rates and Patterns” for detailed information on these cards.
For the three modes, the test streams are organized as follows.
Gap-based Traffic
With the two gap-based modes (IFG and Random IFG), you can control the frame size and gap size (or range of gap sizes) but not the frame rate.
For traffic scheduled by a fixed interframe gap, the card inserts your specified gap (number of bit times) between frames. It then sends out test traffic, with the selected frame size, at the maximum line rate.
For traffic scheduled by a random interframe gap, a random number generator on the card produces gaps of varying sizes, within the bounds you define by using NS_PORT_TRANSMIT. These gaps are inserted between frames. Then test traffic is sent with the selected frame size at the maximum line rate.
Rate-based Traffic
For traffic scheduled by a frame rate, you can specify a different rate for each stream, but you cannot control the interframe gap. The gaps are calculated and inserted by the card automatically. The card inserts at the least the minimum interframe gap. If you specify frame rates that, altogether, are lower than the maximum line capacity, the “extra” bandwidth is divided among the streams for use as the interframe gap times.
Chapter 19: Packet Over SONET TestingSet Up Tests with POS-3519As/Ar and 3518As/Ar Modules
SmartLibrary Overview and Procedures | 445
How to Set the Schedule Mode
You can set the schedule mode in two ways:
Option 1: Use NS_PORT_TRANSMIT
Option 2: Use HTScheduleModeOption 1 Use NS_PORT_TRANSMIT (Message Function)
Use HTSetStructure with NS_PORT_TRANSMIT to specify the schedule mode. Then use the functions below to set global characteristics for the port, as well as per-stream characteristics.
• For gap-based traffic, use NS_PORT_TRANSMIT to set the gap size.
• For rate-based traffic, use L3_DEFINE_STREAM_EXTENSION to set frame rate, background pattern, per-stream errors, and other stream characteristics (but not a gap size).
Continues –>
Original Function Description
NS_PORT_TRANSMIT Specify the desired mode. Then set port and per-stream characteristics as shown below.
For gap-based traffic: Use NS_PORT_TRANSMIT with NSPortTransmit to set the gap size, transmit mode, burst count, and other global (port) variables.
Optionally, you can use L3_DEFINE_STREAM_EXTENSION with L3StreamExtension to set stream characteristics such as background pattern and generated errors (but not frame rate).
For frame rate-based traffic: Use NS_PORT_TRANSMIT with NSPortTransmit to set the transmit mode, burst count, and other global (port) variables (but not gap size).
Use L3_DEFINE_STREAM_ EXTENSION with L3StreamExtension to set the frame rate (as well as stream characteristics such as background pattern and generated errors).
Chapter 19: Packet Over SONET TestingSet Up Tests with POS-3519As/Ar and 3518As/Ar Modules
446 | SmartLibrary Overview and Procedures
Option 2 Use HTScheduleMode (Original Function)
Use HTScheduleMode to specify the schedule mode. Then use the other functions listed below to set global characteristics for the port, as well as per-stream characteristics.
Step 3 Configure the POS Port
Configure the POS line parameters, encapsulation type, and port speed.
Original Function Description
HTScheduleMode Specify the schedule mode. Then set port and per-stream characteristics as shown below.
For gap-based traffic:
HTGap Set the gap size.
HTTransmitMode Set the transmit mode (for example, single burst, multi-burst, or continuous).
HTBurstCount Set the burst count (number of packets per burst).
For frame rate-based traffic:
HTTransmitMode Set the transmit mode (for example, single burst, multi-burst, or continuous).
HTBurstCount Set the burst count (number of packets per burst).
HTSetStructure Use L3_DEFINE_STREAM_EXTENSION with L3StreamExtension to set the frame rate, background pattern, per-stream errors (as well as stream characteristics such as background pattern and generated errors).
Original Function Message Function iType1 Description
HTSetStructure POS_CARD_LINE_CONFIG Configure POS line parameters.
POS_CARD_PORT_ENCAP Define POS encapsulation.
POS_CONFIG Configure the POS transceiver.
NS_HW_CONFIG Set up other port characteristics (timestamp, laser enable).
HTSetCommand POS_SET_SPEED Set the POS port speed.
Chapter 19: Packet Over SONET TestingSet Up Tests with POS-3519As/Ar and 3518As/Ar Modules
SmartLibrary Overview and Procedures | 447
Step 4 Send Test Traffic, Then Stop the Test
Use HTRun or HGRun (or HGStep) to send test traffic.
Note: For Latency histogram results, it is important to initialize the timestamps on each module before doing a group start. To do this, use the “Timestamp-Initialization Sequence.”
If you run the test with continuous traffic, use HTStop or HGStop to stop the test.
End of Required Steps for Basic Setup
This completes the basic steps needed to transmit test traffic. The usefulness of your test, however, depends on getting test results. See “Getting Test Results” on page 448 for the steps to use counters, capture, or histograms to measure test traffic.
Original Function Description
HTRun/HTStop Transmit test frames, then stop the test (if running continuous traffic rather than step or burst mode).
HGRun/HGStep/HGStop
Chapter 19: Packet Over SONET TestingSet Up Tests with POS-3519As/Ar and 3518As/Ar Modules
448 | SmartLibrary Overview and Procedures
Getting Test Results
Your test can provide three types of results. These are:– Counters– Captured data — or —– Histograms
Counters Counters are always available. You need not enable them or set them up explicitly. You can get counter information during the test or after it stops.
Captured data and histograms
You can also retrieve captured data or histograms, but not both in the same test. For these, you must specify the type of results desired, and you must enable the function. You set up data capture or histogram results before you start your test. You obtain either type of results after you run the test.
How to Get Counter Information
Use HTGetStructure with L2_READ_COUNTERS to verify that the number of frames received was as expected.
Use HTGetStructure with L2_READ_RATES to get rate information.
Use NS_MULTI_COUNTER_INFO to retrieve all counters supported by TeraMetrics cards.
Original Function Message Function iType1 Related Structure
HTGetStructure L2_READ_COUNTERS L2StatsInfo
L2_READ_RATES L2RateInfo
Chapter 19: Packet Over SONET TestingSet Up Tests with POS-3519As/Ar and 3518As/Ar Modules
SmartLibrary Overview and Procedures | 449
How to Set Up Data Capture
You can specify data capture in place of histogram results.
Step 1 Set up the capture mode, length, and event.
Use HTSetStructure with NS_CAPTURE_SETUP(NSCaptureSetup) to specify the capture mode, length, and event.
Capture Mode. Valid options for Layer3CaptureSetup(ulCaptureMode) include:
Capture Events. The CAPTURE_EVENTS element in Layer3CaptureSetup defines what frame types should be captured. Valid options include the following:
Original Function Message Function iType1 Related Structure
HTSetStructure NS_CAPTURE_SETUP NSCaptureSetup
Capture Mode Description
CAPTURE_MODE_FILTER_ON_EVENTS Capture only packets with the specified event, such as CRC errors, undersize packets, or oversize packets.
CAPTURE_MODE_START_ON_EVENTS Capture all packets following the specified event. For example, begin capture when the first packet with a CRC error is received, then capture all packets.
CAPTURE_MODE_STOP_ON_EVENTS Capture all packets until the specified event. For example, capture all packets until the first packet with a CRC error is received, then stop the capture.
Capture Event Description
CRC_ERRORS Capture all frames with CRC errors.
IP_CHECKSUM_ERROR Capture all frames with IP checksum errors.
DATA_INTEGRITY_ERROR Capture all frames in which the payload contents have become corrupted.
RX_TRIGGER Capture all frames that contain receive trigger patterns.
Chapter 19: Packet Over SONET TestingSet Up Tests with POS-3519As/Ar and 3518As/Ar Modules
450 | SmartLibrary Overview and Procedures
Capture Length. Valid options for Layer3CaptureSetup(ulCaptureLength) include:
Step 2 Start capture, then stop.
Use NS_CAPTURE_START and NS_CAPTURE_STOP to start and stop the capture.
Step 3 Get the captured data.
Use the following commands to get your capture results.
Capture Length Description
CAPTURE_LENGTH_ENTIRE_FRAME Capture complete frame.
CAPTURE_LENGTH_1ST_64_BYTES Capture only the first 64 bytes in the frame.
CAPTURE_LENGTH_LAST_64_BYTES Capture only the last 64 bytes in the frame.
Original Function Message Function iType1 Related Structure
HTSetCommand NS_CAPTURE_START —
NS_CAPTURE_STOP —
Original Function Message Function iType1 Related Structure Description
HTGetStructure NS_CAPTURE_COUNT_INFO NSCaptureCountInfo Find the number of frames in the buffer.
NS_CAPTURE_DATA_INFO NSCaptureDataInfo Get the captured frames.
Chapter 19: Packet Over SONET TestingSet Up Tests with POS-3519As/Ar and 3518As/Ar Modules
SmartLibrary Overview and Procedures | 451
How to Set Up SmartMetrics Histograms
Histograms provide in-depth test results, including sequence and latency information. This information is gathered on the receiving card.
Step 1 Enable the histogram type.
Before you start the test, specify the type of histogram information you wish to be gathered.
Step 2 Set Up Port Groups
When SmartMetrics results are desired, you must set up a port group, since histogram results require a group start. Use HGSetGroup and HGAddtoGroup to define the port group and to add ports to a group.
Original Function Message Function iType1 Related Structure/Description
HTSetStructure NS_HIST_COMBO_PER_STREAM NSHistComboPerStream
Gives an overall picture of latency per stream. Provides the following results:
Latency per Stream. Shows minimum, maximum, and average latency values over the course of the test.
Latency Distribution. Shows the occurrence of specific latency values per stream.
Sequence Tracking. Reports whether or not frames were received in sequence per stream.
HTSetStructure NS_HIST_LATENCY_OVER_TIME NSHistLatencyOverTime
Provides Latency over Time histogram on the receive module.
HTSetCommand NS_HIST_RAW_SIGNATURE Signature information only, showing transmit time, receive time, and delta in microseconds.
HTSetCommand NS_HIST_SEQUENCE_PER_STREAM Sequence information only. Reports whether or not frames were received in sequence per stream.
HTSetStructure NS_HIST_LATENCY_DIST_PER_STREAM NSHistComboPerStream
Latency distribution information only. Shows the occurrence of specific latency values per stream.
Original Function Description
HGSetGroup Define a group of SmartBits ports.
HGAddtoGroup Add ports to the group. You control grouped ports by using the HG commands.
Chapter 19: Packet Over SONET TestingSet Up Tests with POS-3519As/Ar and 3518As/Ar Modules
452 | SmartLibrary Overview and Procedures
Step 3 Gather Histogram Information
After the test stops, use HTGetStructure with the iType1s listed below to collect histogram information.
Original Function Message Function iType1 Related Structure/Description
HTGetStructure NS_HIST_COMBO_PER_STREAM_INFO NSHistComboPerStreamInfo
Latency Distribution histogram results.
NS_HIST_LATENCY_OVER_TIME_INFO NSHistLatencyOverTimeInfo
Latency over Time histogram results.
NS_HIST_RAW_SIGNATURE_INFO NSHistRawSignatureInfo
Signature information only.
NS_HIST_SEQUENCE_PER_STREAM_INFO Sequence Tracking histogram results.
NS_HIST_LATENCY_DIST_PER_STREAM_INFO NSHistLatencyDistPerStreamInfo
Latency Distribution histogram results.
Chapter 19: Packet Over SONET TestingTest with IPv6 Streams on POS TeraMetrics Modules
SmartLibrary Overview and Procedures | 453
Test with IPv6 Streams on POS TeraMetrics ModulesThis procedure is very similar to the one you would use to set up SmartMetrics tests with IPv4 streams, as described in “Set Up Tests with POS-3519As/Ar and 3518As/Ar Modules” on page 441. The important differences are as follows (see “Example of Setup Steps” on page 456 for a full procedure):
• Before defining streams, use NS_PORT_TRANSMIT(NSPortTransmit) to enable the 128-byte header length needed to accommodate the longer IPv6 stream header (TCP, TCP VLAN, and UDP VLAN only). Set ucEnableExtendedPayload to 1.
Note: Any time you switch between enabling and disabling the extended payload, all currently configured streams are deleted.
• When defining streams, set one of the IPv6 stream types (see “Set Up Streams” on page 456). As with IPv4, stream types include native IP, TCP, and UDP.
• To set additional streams or to modify streams, use the IPv6 versions of the standard L3_DEFINE_MULTI and L3_MOD commands.
• Set and get IPv6 address information by using L3_TX_IPV6_ADDRESS and L3_TX_IPV6_ADDRESS_INFO.
• Set IPv6 protocol information (Ping settings) by using L3_TX_IPV6_PROTOCOL.
• Get IPv6 counters (events and rates) by using NS_IPV6_COUNTER_INFO and NS_IPV6_RATE_INFO.
POS IPv6 tests may be run with the following TeraMetrics-family modules:
Module Description
SmartBits Chassis
200/2000 600x/6000x
POS-3504As/AR
POS-3505As/AR
POS OC-48c (STM-16c), 1-port, single mode, 1310nm/1550nm, SmartMetrics
POS OC-48c (STM-16c), 1-port, single mode, 1310nm/1550nm, TeraMetrics
N/A v
POS-3510A
POS-3510As
POS-3511A
POS-3511As
POS OC3c/OC-12c (STM-1c/STM-4c), 2-port, multi-mode, 1300nm, SmartMetricsPOS OC3c/OC-12c (STM-1c/STM-4c), 2-port, single mode, 1310nm, SmartMetricsPOS OC3c/OC-12c (STM-1c/STM-4c), 2-port, multi-mode, 1300nm, TeraMetricsPOS OC3c/OC-12c (STM-1c/STM-4c), 2-port, multi-mode, 1310nm, TeraMetrics
N/A v
Chapter 19: Packet Over SONET TestingTest with IPv6 Streams on POS TeraMetrics Modules
454 | SmartLibrary Overview and Procedures
Applicable Commands
Table 19-3 is a summary of commands you can use in POS tests with these modules. Not all commands are required. This list is an overview.
A basic setup See “Example of Setup Steps” on page 456 for a basic setup procedure, as well as optional commands and actions.
POS-3518AS/AR
POS-3519AS/AR
POS OC-192c (STM-64c), 1-port, 2-slot, single mode, 1310nm/1550nm, SmartMetricsPOS OC-192c (STM-64c), 1-port, 2-slot, single mode, 1310nm/1550nm, TeraMetrics
N/A v
Module Description
SmartBits Chassis
200/2000 600x/6000x
Table 19-3. Applicable Commands: POS Tests with IPv6 Streams
Applicable Commands
What the Commands Do Original Function Message Function iType1/Notes
Reset card to the default state. HTResetPort See “Example of Setup Steps” on page 456.
Clear counters. HTClearPort See“Example of Setup Steps” on page 456.
Enable extended header length. HTSetStructure NS_PORT_TRANSMIT (TCP, TCP VLAN, and UDP VLAN only)
Set up streams. HTSetStructure L3_DEFINE_<n>_IPV6_STREAM
Specify IPv6 address information. HTSetStructure L3_TX_IPV6_ADDRESS
Get IPv6 address information. HTGetStructure L3_TX_IPV6_ADDRESS_INFO
Specify IPv6 protocol information (Ping settings).
HTSetStructure L3_TX_IPV6_PROTOCOL
Specify the scheduling mode (either gap-based or rate-based).
HTSetStructure
—or—
HTScheduleMode
NS_PORT_TRANSMIT
—
Continued-->
Chapter 19: Packet Over SONET TestingTest with IPv6 Streams on POS TeraMetrics Modules
SmartLibrary Overview and Procedures | 455
Applicable Commands
What the Commands Do Original Function Message Function iType1/Notes
Configure the POS port. HTSetStructure POS_CARD_LINE_CONFIGPOS_CARD_PORT_ENCAPPOS_CONFIGNS_HW_CONFIG
HTSetCommand POS_SET_SPEED
Specify SmartMetrics (histogram) results.
—or—
HTSetStructureHTSetStructureHTSetCommandHTSetCommandHTSetStructure
NS_HIST_COMBO_PER_STREAMNS_HIST_LATENCY_OVER_TIMENS_HIST_RAW_SIGNATURENS_HIST_SEQUENCE_PER_STREAMNS_HIST_LATENCY_DIST_PER_STREAM
Set up data capture. HTSetStructure NS_CAPTURE_SETUP
(Optional) Set up port groups. HGSetGroupHGAddtoGroup
See “Example of Setup Steps” on page 443.
Start data capture (if selected). HTSetCommand NS_CAPTURE_START
Transmit test frames. HTRun For single-port start.
HGRunHGStep
For group start.
Stop the test. HTStopHGStop
See “Example of Setup Steps” on page 443.
Stop data capture (if selected). HTSetCommand NS_CAPTURE_STOP
Get IPv6 counters. HTGetStructure NS_IPV6_COUNTER_INFONS_IPV6_RATE_INFO
Get histogram results.
— or —
HTGetStructure
— or —
NS_HIST_COMBO_PER_STREAM_INFONS_HIST_LATENCY_OVER_TIME_INFONS_HIST_RAW_SIGNATURE_INFONS_HIST_SEQUENCE_PER_STREAM_INFONS_HIST_LATENCY_DIST_PER_STREAM_INFO
Get captured data. HTGetStructure NS_CAPTURE_COUNT_INFONS_CAPTURE_DATA_INFO
Table 19-3. Applicable Commands: POS Tests with IPv6 Streams (continued)
Chapter 19: Packet Over SONET TestingTest with IPv6 Streams on POS TeraMetrics Modules
456 | SmartLibrary Overview and Procedures
Example of Setup Steps
Here is an example of how to set up tests with IPv6 streams using POS TeraMetrics-family modules. It assumes no previous configuration. It shows selected commands, not all possible commands or actions.
Step 1 Reset the Card and Clear All Counters
Use HTResetPort to set the card to a known, default state. Use HTClearPort to clear all counters.
Step 2 Enable Extended (128-byte) Stream HeaderIf you will set up TCP, TCP VLAN, or UDP VLAN streams, use HTSetStructure and NS_PORT_TRANSMIT to enable the increased, 128-byte header length needed to accommodate an IPv6 header. Set ucEnableExtendedPayload to 1 to do this.
Enabling 128-byte stream headers reduces the maximum possible number of streams by half, from 512 to 256. Exceptions are the POS-3518AS/AR and POS-3519AS/AR modules. See “Test with IPv6 Streams on POS TeraMetrics Modules” on page 453.)
In addition, any time you switch between enabling and disabling the extended payload, all currently configured streams are deleted
Step 3 Set Up StreamsUse HTSetStructure and L3_DEFINE_IPV6_<n>_STREAM to configure test traffic. Here <n> represents one of the IPv6 stream types (including TCP and UDP; see table below). This function specifies the stream template (structure of test frames).
Original Function Description
HTResetPort Reset the card or module to a default state.
HTClearPort Clear the port counters.
Original Function Message Function iType1 Related Structure
HTSetStructure NS_PORT_TRANSMIT NSPortTransmit
Original Function Message Function iType1 Related Structure
HTSetStructure L3_DEFINE_IPV6_STREAM StreamIPv6
L3_DEFINE_TCP_IPV6_STREAM StreamTCPIPv6
L3_DEFINE_UDP_IPV6_STREAM StreamUDPIPv6
Chapter 19: Packet Over SONET TestingTest with IPv6 Streams on POS TeraMetrics Modules
SmartLibrary Overview and Procedures | 457
Defining Multiple Streams
To define multiple streams, use one of the L3_DEFINE_MULTI_<n>_IPV6_STREAM commands. Here are examples for IPv6 streams:
Modifying a Stream
Use one of the L3_MOD_<n>_IPV6_STREAM commands to modify an existing stream at a specified index. This function replaces the entire stream: to change one or more attributes, a complete structure is sent to the card. L3_MOD_<n>_IPV6_STREAM can modify the stream at index 0, but you should modify streams starting at index 1.
Here are examples for IPv6 streams:
Step 4 Specify IPv6 Address InformationUse HTSetStructure and L3_TX_IPV6_ADDRESS to set the MAC, IP, gateway addresses. You can use HTGetStructure and L3_TX_IPV6_ADDRESS_INFO to get the address information from the module.
Step 5 Specify IPv6 Protocol Information (Ping Settings)Use HTSetStructure and L3_TX_IPV6_PROTOCOL to set the IPv6 Ping settings (target IP address and Ping interval).
Continues –>
Original Function Message Function iType1 Related Structure
HTSetStructure L3_DEFINE_MULTI_IPV6_STREAM StreamIPv6
L3_DEFINE_MULTI_TCP_IPV6_STREAM StreamIPv6VLAN
Original Function Message Function iType1 Related Structure
HTSetStructure L3_MOD_IPV6_STREAM StreamIPv6
Original Function Message Function iType1 Related Structure
HTSetStructure L3_TX_IPV6_ADDRESS Layer3IPv6Address
HTGetStructure L3_TX_IPV6_ADDRESS_INFO Same
Original Function Message Function iType1 Related Structure
HTSetStructure L3_TX_IPV6_PROTOCOL Layer3IPv6Protocol
Chapter 19: Packet Over SONET TestingTest with IPv6 Streams on POS TeraMetrics Modules
458 | SmartLibrary Overview and Procedures
Step 6 Define the Schedule Mode (Gap-based or Rate-based)
You can specify that the streams generated by the port are scheduled and transmitted based either on interframe gap or frame rate. Specifically, you can select one of three options. Streams can be scheduled by one of the following:
• Interframe Gap — A fixed number of bit times between frames.
• Random IFG — A varying number of bit times between frames.• Frame Rate — A defined frames-per-second rate of transmission for each stream.
Bursty traffic can still be used.
The selected scheduling mode you assign to a port applies to all streams generated by the port. Test traffic is sent in a round-robin fashion, with one frame from each stream generated in sequence.
For all three scheduling options, a software mechanism on the card (termed the scheduler) calculates how to allocate the overall line bandwidth. It builds a static scheduling table that organizes all streams before any traffic is sent. The schedule table is static in that it does not vary as test traffic is sent—even though two of the scheduling options (Random IFG and Frame Rate) appear to be dynamic in behavior, because they allow individual stream frame rates and random interframe gaps.
Note: The scheduling mechanism used with earlier POS cards, such as the POS-3500B/BS, differs in important ways. Refer to Chapter 4, “Traffic Rates and Patterns” for detailed information on these cards.
For the three modes, the test streams are organized as follows.
Gap-based Traffic
With the two gap-based modes (IFG and Random IFG), you can control the frame size and gap size (or range of gap sizes) but not the frame rate.
For traffic scheduled by a fixed interframe gap, the card inserts your specified gap (number of bit times) between frames. It then sends out test traffic, with the selected frame size, at the maximum line rate.
For traffic scheduled by a random interframe gap, a random number generator on the card produces gaps of varying sizes, within the bounds you define by using NS_PORT_TRANSMIT. These gaps are inserted between frames. Then test traffic is sent with the selected frame size at the maximum line rate.
Rate-based Traffic
For traffic scheduled by a frame rate, you can specify a different rate for each stream, but you cannot control the interframe gap. The gaps are calculated and inserted by the card automatically. The card inserts at the least the minimum interframe gap. If you specify frame rates that, altogether, are lower than the maximum line capacity, the “extra” bandwidth is divided among the streams for use as the interframe gap times.
Chapter 19: Packet Over SONET TestingTest with IPv6 Streams on POS TeraMetrics Modules
SmartLibrary Overview and Procedures | 459
How to Set the Schedule Mode
You can set the schedule mode in two ways:
Option 1: Use NS_PORT_TRANSMIT
Option 2: Use HTScheduleMode
Option 1 Use NS_PORT_TRANSMIT (Message Function)
Use HTSetStructure with NS_PORT_TRANSMIT to specify the schedule mode. Then use the functions below to set global characteristics for the port, as well as per-stream characteristics.
• For gap-based traffic, use NS_PORT_TRANSMIT to set the gap size.
• For rate-based traffic, use L3_DEFINE_STREAM_EXTENSION to set frame rate, background pattern, per-stream errors, and other stream characteristics (but not a gap size).
Continues –>
Original Function Description
NS_PORT_TRANSMIT Specify the desired mode. Then set port and per-stream characteristics as shown below.
For gap-based traffic: Use NS_PORT_TRANSMIT with NSPortTransmit to set the gap size, transmit mode, burst count, and other global (port) variables.
Optionally, you can use L3_DEFINE_STREAM_EXTENSION with L3StreamExtension to set stream characteristics such as background pattern and generated errors (but not frame rate).
For frame rate-based traffic: Use NS_PORT_TRANSMIT with NSPortTransmit to set the transmit mode, burst count, and other global (port) variables (but not gap size).
Use L3_DEFINE_STREAM_ EXTENSION with L3StreamExtension to set the frame rate (as well as stream characteristics such as background pattern and generated errors).
Chapter 19: Packet Over SONET TestingTest with IPv6 Streams on POS TeraMetrics Modules
460 | SmartLibrary Overview and Procedures
Option 2 Use HTScheduleMode (Original Function)
Use HTScheduleMode to specify the schedule mode. Then use the other functions listed below to set global characteristics for the port, as well as per-stream characteristics.
Step 3 Configure the POS Port
Configure the POS line parameters, encapsulation type, and port speed.
Original Function Description
HTScheduleMode Specify the schedule mode. Then set port and per-stream characteristics as shown below.
For gap-based traffic:
HTGap Set the gap size.
HTTransmitMode Set the transmit mode (for example, single burst, multi-burst, or continuous).
HTBurstCount Set the burst count (number of packets per burst).
For frame rate-based traffic:
HTTransmitMode Set the transmit mode (for example, single burst, multi-burst, or continuous).
HTBurstCount Set the burst count (number of packets per burst).
HTSetStructure Use L3_DEFINE_STREAM_EXTENSION with L3StreamExtension to set the frame rate, background pattern, per-stream errors (as well as stream characteristics such as background pattern and generated errors).
Original Function Message Function iType1 Description
HTSetStructure POS_CARD_LINE_CONFIG Configure POS line parameters.
POS_CARD_PORT_ENCAP Define POS encapsulation.
POS_CONFIG Configure the POS transceiver.
NS_HW_CONFIG Set up other port characteristics (timestamp, laser enable).
HTSetCommand POS_SET_SPEED Set the POS port speed.
Chapter 19: Packet Over SONET TestingTest with IPv6 Streams on POS TeraMetrics Modules
SmartLibrary Overview and Procedures | 461
Step 4 Start capture, if selected.
Use NS_CAPTURE_START to start data capture, when desired.
Step 5 Send Test Traffic, Then Stop the Test
Use HTRun or HGRun (or HGStep) to send test traffic.
Note: For Latency histogram results, it is important to initialize the timestamps on module before doing a group start. To do this, use the “Timestamp-Initialization Sequence.”
If you run the test with continuous traffic, use HTStop or HGStop to stop the test.
Note: For Latency histogram results, it is important to initialize the timestamps on each module before doing a group start. To do this, use the “Timestamp-Initialization Sequence.”
Step 6 Stop capture (if selected).
Use NS_CAPTURE_STOP to stop data capture, if enabled.
End of Required Steps for Basic Setup
This completes the basic steps needed to transmit test traffic. The usefulness of your test, however, depends on getting test results. See “Getting Test Results” on page 462 for the steps to use counters, capture, or histograms to measure test traffic.
Original Function Message Function iType1 Related Structure
HTSetCommand NS_CAPTURE_START —
Original Function Description
HTRun/HTStop Transmit test frames, then stop the test (if running continuous traffic rather than step or burst mode).
HGRun/HGStep/HGStop
Original Function Message Function iType1 Related Structure
HTSetCommand NS_CAPTURE_STOP —
Chapter 19: Packet Over SONET TestingTest with IPv6 Streams on POS TeraMetrics Modules
462 | SmartLibrary Overview and Procedures
Getting Test Results
Your test can provide three types of results. These are:– Counters– Captured data — or —– Histograms
Counters Counters are always available. You need not enable them or set them up explicitly. You can get counter information during the test or after it stops.
Captured data and histograms
You can also retrieve captured data or histograms, but not both in the same test. For these, you must specify the type of results desired, and you must enable the function. You set up data capture or histogram results before you start your test. You obtain either type of results after you run the test.
How to Get Counter Information
Use HTGetStructure with NS_IPV6_COUNTER_INFO to retrieve IPv6 counters.
Use HTGetStructure with NS_IPV6_RATE_INFO to get rate information for the IPv6 streams.
Original Function Message Function iType1 Structure/Description
HTGetStructure NS_IPV6_COUNTER_INFO NSIPv6CounterInfo
HTGetStructure NS_IPV6_RATE_INFO NSIPv6RateInfo
Chapter 19: Packet Over SONET TestingTest with IPv6 Streams on POS TeraMetrics Modules
SmartLibrary Overview and Procedures | 463
How to Set Up Data Capture
You can specify data capture in place of histogram results.
Step 1 Set up the capture mode, length, and event.
Use HTSetStructure with NS_CAPTURE_SETUP(NSCaptureSetup) to specify the capture mode, length, and event.
Capture Mode. Valid options for Layer3CaptureSetup(ulCaptureMode) include:
Capture Events. The CAPTURE_EVENTS element in Layer3CaptureSetup defines what frame types should be captured. Valid options include the following:
Original Function Message Function iType1 Related Structure
HTSetStructure NS_CAPTURE_SETUP NSCaptureSetup
Capture Mode Description
CAPTURE_MODE_FILTER_ON_EVENTS Capture only packets with the specified event, such as CRC errors, undersize packets, or oversize packets.
CAPTURE_MODE_START_ON_EVENTS Capture all packets following the specified event. For example, begin capture when the first packet with a CRC error is received, then capture all packets.
CAPTURE_MODE_STOP_ON_EVENTS Capture all packets until the specified event. For example, capture all packets until the first packet with a CRC error is received, then stop the capture.
Capture Event Description
CRC_ERRORS Capture all frames with CRC errors.
IP_CHECKSUM_ERROR Capture all frames with IP checksum errors.
DATA_INTEGRITY_ERROR Capture all frames in which the payload contents have become corrupted.
RX_TRIGGER Capture all frames that contain receive trigger patterns.
Chapter 19: Packet Over SONET TestingTest with IPv6 Streams on POS TeraMetrics Modules
464 | SmartLibrary Overview and Procedures
Capture Length. Valid options for Layer3CaptureSetup(ulCaptureLength) include:
Step 2 Start capture, then stop.
Before sending test traffic, use NS_CAPTURE_START to start capture.
When the test is done, use NS_CAPTURE_STOP to stop the capture.
Step 3 Get the captured data.
Use the following commands to get your capture results.
Capture Length Description
CAPTURE_LENGTH_ENTIRE_FRAME Capture complete frame.
CAPTURE_LENGTH_1ST_64_BYTES Capture only the first 64 bytes in the frame.
CAPTURE_LENGTH_LAST_64_BYTES Capture only the last 64 bytes in the frame.
Original Function Message Function iType1 Related Structure
HTSetCommand NS_CAPTURE_START —
NS_CAPTURE_STOP —
Original Function Message Function iType1 Related Structure Description
HTGetStructure NS_CAPTURE_COUNT_INFO NSCaptureCountInfo Find the number of frames in the buffer.
NS_CAPTURE_DATA_INFO NSCaptureDataInfo Get the captured frames.
Chapter 19: Packet Over SONET TestingTest with IPv6 Streams on POS TeraMetrics Modules
SmartLibrary Overview and Procedures | 465
How to Set Up SmartMetrics Histograms
Histograms provide in-depth test results, including sequence and latency information.
Histogram information is gathered on the receiving card.
Step 1 Enable the histogram type.
Before you start the test, specify the type of histogram information you wish to be gathered.
Step 2 Set Up Port Groups
When SmartMetrics results are desired, you must set up a port group, since histogram results require a group start.
Use HGSetGroup and HGAddtoGroup to define the port group and to add ports to a group.
Original Function Message Function iType1 Related Structure/Description
HTSetStructure NS_HIST_COMBO_PER_STREAM NSHistComboPerStream
Gives an overall picture of latency per stream. Provides the following results:
Latency per Stream. Shows minimum, maximum, and average latency values over the course of the test.
Latency Distribution. Shows the occurrence of specific latency values per stream.
Sequence Tracking. Reports whether or not frames were received in sequence per stream.
HTSetStructure NS_HIST_LATENCY_OVER_TIME NSHistLatencyOverTime
Provides Latency over Time histogram on the receive module.
HTSetCommand NS_HIST_RAW_SIGNATURE Signature information only, showing transmit time, receive time, and delta in microseconds.
HTSetCommand NS_HIST_SEQUENCE_PER_STREAM Sequence information only. Reports whether or not frames were received in sequence per stream.
HTSetStructure NS_HIST_LATENCY_DIST_PER_STREAM NSHistComboPerStream
Latency distribution information only. Shows the occurrence of specific latency values per stream.
Chapter 19: Packet Over SONET TestingTest with IPv6 Streams on POS TeraMetrics Modules
466 | SmartLibrary Overview and Procedures
Step 3 Gather Histogram Information
After the test runs, gather the results for the SmartMetrics histogram you specified in Step 1. Use HTGetStructure with the appropriate iType1, as shown below.
Original Function Description
HGSetGroup Define a group of SmartBits ports.
HGAddtoGroup Add ports to the group. You control grouped ports by using the HG commands.
Original Function Message Function iType1 Related Structure/Description
HTGetStructure NS_HIST_COMBO_PER_STREAM_INFO NSHistComboPerStreamInfo
Latency Distribution histogram results.
NS_HIST_LATENCY_OVER_TIME_INFO NSHistLatencyOverTimeInfo
Latency over Time histogram results.
NS_HIST_RAW_SIGNATURE_INFO NSHistRawSignatureInfo
Signature information only.
NS_HIST_SEQUENCE_PER_STREAM_INFO Sequence Tracking histogram results.
NS_HIST_LATENCY_DIST_PER_STREAM_INFO NSHistLatencyDistPerStreamInfo
Latency Distribution histogram results.
SmartLibrary Overview and Procedures | 467
Chapter 20
IGMP Testing
This chapter provides procedures you can use to set up tests with IGMPv2 and IGMPv3 multicast groups and to test Multicast Listener Discovery (MLD).
Note: For detailed information on creating streams, refer to Chapter 4, “Traffic Rates and Patterns”
In this chapter...
• Set Up IGMPv2 Multicast Groups . . . . 468
• Set Up IGMPv3 Multicast Groups . . . . 474
• Set Up Multicast Listener Discovery (version 1) . . . . 480
• Set Up Multicast Listener Discovery (version 2) . . . . 485
• Getting Test Results . . . . 478
Chapter 20: IGMP TestingSet Up IGMPv2 Multicast Groups
468 | SmartLibrary Overview and Procedures
Set Up IGMPv2 Multicast GroupsUse the following steps to set up tests for IGMP Version 2 (IGMPv2) multicast groups and retrieve IGMP counters or histogram results.
For Ethernet and POS modules, SmartLibrary 3.40 introduced a new suite of iType1 commands to use in setting up IGMPv2. These commands are of the form NS_IGMPV2_<action>. Their use is recommended, and they are cited in the procedure that follows. For compatibility, the previously supported commands remain available in SmartLibrary and are supported in SmartLibrary 3.50. These commands are of the form NS_IGMP_<action>. For reference, these commands are cited in the procedure below (in italic font) in this way: Earlier form: <command name>.
The IGMPv2 commands are supported by the LAN-3101A/B module and by all TeraMetrics-based LAN and POS modules. For WAN SmartCards, you should use the earlier command forms, when cited in the procedure.
Applicable CommandsTable 20-1 summary of commands you can use in your tests. Not all commands are required. This list is an overview. See “Example of Setup Steps” on page 470 for a basic setup procedure, as well as optional commands and actions.
Table 20-1. Applicable Commands for IGMPv2 Testing
Applicable Commands
What the Commands Do Original Function Message Function iType1/Notes
Reset card to the default state. HTResetPort See “Example of Setup Steps” on page 470.
Clear counters. HTClearPort See “Example of Setup Steps” on page 470.
Set up streams. HTSetStructure L3_DEFINE_<n>_STREAM
Note: At least one stream must be defined on the Rx port, to place the card into SmartMetrics mode.
Reset the IGMP stack on the transmit and receive ports.
HTSetCommand NS_IGMP_RESET
Ethernet Cards only. Set the MAC and IP addresses on the Tx and Rx ports.
HTLayer3SetAddress See Step 5 on page 471.
Configure the IGMP stack on receiving test ports.
HTSetStructure NS_IGMP_CONFIG
Continues –>
Chapter 20: IGMP TestingSet Up IGMPv2 Multicast Groups
SmartLibrary Overview and Procedures | 469
Applicable Commands
What the Commands Do Original Function Message Function iType1/Notes
Optional. Set up capture, and start capture on the transmitting test port.
HTSetStructure
HTSetCommand
NS_CAPTURE_SETUP
NS_CAPTURE_START
Set up Joins on the groups. HTSetStructure NS_IGMPV2_JOIN
Earlier form: NS_IGMP_JOIN
Ethernet Cards only: You can also use:
NS_IGMP_JOIN_VLAN
Important: After performing a Join, you must insert a wait of at least 30 seconds before retrieving counter information.
Optional. Stop capture on the transmitting test port.
HTSetCommand NS_CAPTURE_STOP
Optional. Get captured Membership Reports on the transmitting port.
HTSetStructure NS_CAPTURE_DATA_INFO
Optional. Perform Leaves. HTSetStructure NS_IGMPV2_LEAVE
Earlier form: NS_IGMP_LEAVE
Ethernet Cards only: You can also use:
NS_IGMP_JOIN_VLAN
Important: After performing a Leave, you must insert a wait of at least 30 seconds before retrieving counter information.
Optional. Retrieve Join and Leave timestamps for a specific multicast group.
HTGetStructure NS_IGMPV2_INFO
Optional. Retrieve Join and Leave timestamps for a specific multicast group.
HTGetStructure NS_IGMPV2_ALL_INFO
Retrieve IGMP counter information. HTGetStructure See “Getting Test Results” on page 478.
Table 20-1. Applicable Commands for IGMPv2 Testing
Chapter 20: IGMP TestingSet Up IGMPv2 Multicast Groups
470 | SmartLibrary Overview and Procedures
Example of Setup Steps
Here is an example of how to set up your test. It assumes no previous configuration. It shows selected commands, not all possible commands or actions.
Step 1 Reset the Card
Use HTResetPort to set the card to a known, default state.
Step 2 Clear All Counters
Use HTClearPort to clear all counters.
Step 3 Set Up StreamsUse HTSetStructure with L3_DEFINE_<n>_STREAM to configure at least one stream on the receiving port. Here, <n> represents the stream type and can be IP, IPX, UDP, TCP, or SmartBits.
Note: Doing this places the card into the SmartMetrics mode. You must set up at least one stream on the Rx port.
Step 4 Reset the IGMP Stack on Tx and Rx Ports
Use HTSetCommand with NS_IGMP_RESET to reset the IGMP stack on the transmitting and receiving test ports.
Original Function Description
HTResetPort Reset the card or module to a default state.
Original Function Description
HTClearPort Clear the port counters.
Original Function Message Function iType1 Related Structure
HTSetStructure L3_DEFINE_<n>_STREAM Stream<n>
L3_DEFINE_STREAM_EXTENSION StreamExtension
L3_DEFINE_MULTI_<n>_STREAM Stream<n>
L3_DEFINE_MULTI_STREAM_EXTENSION StreamExtension
Original Function Message Function iType1 Related Structure
HTSetCommand NS_IGMP_RESET None
Chapter 20: IGMP TestingSet Up IGMPv2 Multicast Groups
SmartLibrary Overview and Procedures | 471
Step 5 Set the MAC and IP Addresses on the Tx and Rx Ports (Ethernet only)
For Ethernet ports, use HTLayer3SetAddress to configure the MAC and IP addresses on the transmitting and receiving test ports.
Step 6 Configure the IGMP Stack on Rx Ports
Use HTSetStructure with NS_IGMPV3_CONFIG to configure the IGMP stack on the receiving test ports. This command lets you set the IGMP version, options, and group characteristics.
The maximum number of groups, by card type, is as follows:
• ML-7710, ML-5710, and LAN-310xA/B cards: 1002
• TeraMetrics-based modules: 20000
• LAN-3201B/C: 2048
• WN-3441A, WN-3442A, WN-3445A: 2048
Step 7 Optional. Start Capture on the Tx Port
Receiving ports will send a Version 2 Membership Report for each IGMP Join. You can use capture on the transmitting port to capture these packets.
Use HTSetStructure with NS_CAPTURE_SETUP(NSCaptureSetup) to configure the capture engine. Use HTSetCommand with NS_CAPTURE_START to start the capture.
Step 8 Set Up Joins on the Groups
Use HTSetStructure with NS_IGMPV2_JOIN to specify the IGMP group address to use in Joins to the multicast group.
WAN Cards With the WN-3441A, WN-3442A, or WN-3445A channelized WAN cards, be sure to specify the line, channel, and local DLCI numbers.
Ethernet VLAN To set up Joins for Ethernet VLAN ports, use NS_IGMP_JOIN_VLAN.
Original Function Message Function iType1 Related Structure
HTSetLayer3SetAddress — Layer3Address
Original Function Message Function iType1 Related Structure
HTSetStructure NS_IGMP_CONFIG NSIGMPConfig
Original Function Message Function iType1 Related Structure
HTSetStructure NS_CAPTURE_SETUP NSCaptureSetup
HTSetCommand NS_CAPTURE_START None
Chapter 20: IGMP TestingSet Up IGMPv2 Multicast Groups
472 | SmartLibrary Overview and Procedures
Important: After performing a Join, you must insert a wait of at least 30 seconds before retrieving counter information.
Step 9 Optional. Stop Capture on the Tx Port
Use HTSetCommand with NS_CAPTURE_STOP to stop the capture on the transmitting port.
Step 10 (Optional) Get Membership Report Packets on Tx Port
Use HTGetStructure with NS_CAPTURE_DATA_INFO to get the Membership Report packets sent by receiving ports.
Step 11 (Optional) Perform Leaves
Use HTSetStructure with NS_IGMPV2_LEAVE to perform Leaves from the multicast group.
WAN Cards With the WN-3441A, WN-3442A, or WN-3445A channelized WAN cards, you must specify the line, channel, and local DLCI numbers.
Important: After performing a Leave, you must insert a wait of at least 30 seconds before retrieving counter information.
Continues –>
Original Function Message Function iType1 Related Structure
HTSetStructure NS_IGMPV2_JOIN
Earlier form: NS_IGMP_JOIN
NSIGMPv2GroupID
NSIGMPAddress
VLAN Ethernet Only: NS_IGMP_JOIN_VLAN NSIGMPAddressVLAN
Original Function Message Function iType1 Related Structure
HTSetCommand NS_CAPTURE_START None
Original Function Message Function iType1 Related Structure
HTGetStructure NS_CAPTURE_DATA_INFO NSCaptureDataInfo
Original Function Message Function iType1 Related Structure
HTSetStructure NS_IGMPV2_LEAVE
Earlier form: NS_IGMP_LEAVE
NSIGMPv2GroupID
NSIGMPAddress
Chapter 20: IGMP TestingSet Up IGMPv2 Multicast Groups
SmartLibrary Overview and Procedures | 473
Step 12 (Optional) Get Join and Leave Timestamps for a Specific Multicast Group
Use HTGetStructure with NS_IGMPV2_INFO to retrieve Join and Leave timestamp information for a specified multicast group.
Step 13 (Optional) Get Join and Leave Timestamps for All Multicast Groups
Use HTGetStructure with NS_IGMPV2_ALL_INFO to retrieve Join and Leave timestamp information for all multicast groups.
End of Required Steps for Basic Setup
This completes the basic steps needed to test with IGMP groups. The usefulness of your test, however, depends on getting test results. See “Getting Test Results” on page 478 for guidelines.
Original Function Message Function iType1 Related Structure
HTGetStructure NS_IGMPV2_INFO NSIGMPv2Info
Original Function Message Function iType1 Related Structure
HTGetStructure NS_IGMPV2_ALL_INFO NSIGMPv2Info
Chapter 20: IGMP TestingSet Up IGMPv3 Multicast Groups
474 | SmartLibrary Overview and Procedures
Set Up IGMPv3 Multicast GroupsUse the following steps to set up test ports as IGMP Version 3 (IGMPv3) multicast groups and retrieve IGMP counters or histogram results.
Note: These commands currently are supported by the LAN-3101A/B module and by TeraMetrics-based LAN and POS modules.
Applicable CommandsTable 20-2 summary of commands you can use in your tests. Not all commands are required. This list is an overview. See “Example of Setup Steps” on page 475 for a basic setup procedure, as well as optional commands and actions.
Table 20-2. Applicable Commands for IGMPv3 Testing
Applicable Commands
What the Commands Do Original Function Message Function iType1/Notes
Reset card to the default state. HTResetPort See “Example of Setup Steps” on page 475.
Clear counters. HTClearPort See “Example of Setup Steps” on page 475.
Set up streams. HTSetStructure L3_DEFINE_<n>_STREAM
Note: At least one stream must be defined on the Rx port, to place the card into SmartMetrics mode.
Reset the IGMP stack on the transmit and receive ports.
HTSetCommand NS_IGMP_RESET
Configure the IGMP stack. HTSetStructure NS_IGMPV3_CONFIG
Configure the groups. HTSetStructure NS_IGMPV3_GROUP_CONFIG
Optional. Change the state of existing groups.
HTSetStructure NS_IGMPV3_GROUP_MOD
Optional. Get Join and Leave timestamps for a multicast group.
HTGetStructure NS_IGMPV3_GROUP_INFO
Optional. Get statistics for a specified multicast group.
HTGetStructure NS_IGMPV3_STATS_INFO
Optional. Get Join and Leave timestamps for all multicast groups.
HTGetStructure NS_IGMPV3_ALL_GROUP_INFO
Leave groups. HTSetCommand NS_IGMPV3_LEAVE_ALL
Retrieve IGMP counter information. HTGetStructure See “Getting Test Results” on page 478.
Chapter 20: IGMP TestingSet Up IGMPv3 Multicast Groups
SmartLibrary Overview and Procedures | 475
Example of Setup Steps
Here is an example of how to set up your test. It assumes no previous configuration. It shows selected commands, not all possible commands or actions.
Step 1 Reset the Card
Use HTResetPort to set the card to a known, default state.
Step 2 Clear All Counters
Use HTClearPort to clear all counters.
Step 3 Set Up StreamsUse HTSetStructure with L3_DEFINE_<n>_STREAM to configure at least one stream on the receiving port. Here, <n> represents the stream type and can be IP, IPX, UDP, TCP, or SmartBits.
Note: Doing this places the card into the SmartMetrics mode. You must set up at least one stream on the Rx port.
Step 4 Reset the IGMP Stack on Transmit and Receive Ports
Use HTSetCommand with NS_IGMP_RESET to reset the IGMP stack on the transmitting and receiving test ports.
Original Function Description
HTResetPort Reset the card or module to a default state.
Original Function Description
HTClearPort Clear the port counters.
Original Function Message Function iType1 Related Structure
HTSetStructure L3_DEFINE_<n>_STREAM Stream<n>
L3_DEFINE_<n>_STREAM_EXTENSION StreamExtension
L3_DEFINE_MULTI_<n>_STREAM Stream<n>
L3_DEFINE_MULTI_<n>_STREAM_EXTENSION StreamExtension
Original Function Message Function iType1 Related Structure
HTSetCommand NS_IGMP_RESET None
Chapter 20: IGMP TestingSet Up IGMPv3 Multicast Groups
476 | SmartLibrary Overview and Procedures
Step 5 Configure the IGMP Stack on Transmit and Receive Ports
Use HTSetStructure with NS_IGMPV3_CONFIG to configure the IGMP stack on the transmitting and receiving test ports. This command lets you set the IGMP version, options, and group characteristics.
Step 6 (Optional) Change the Group Setup
Optionally, you can use HTSetStructure with NS_IGMPV3_GROUP_MOD to make a state change in an existing multicast group, or to add a new multicast group if the multicast group or interface identity is new.
Step 7 (Optional) Get Join and Leave Timestamps for a Specified Group
Optionally, use HTGetStructure with NS_IGMPV3_GROUP_INFO to retrieve Join and Leave timestamps for a specific multicast group and interface.
Step 8 (Optional) Get Group Statistics
Optionally, use HTGetStructure with NS_IGMPV3_STATS_INFO to collect data for groups. This command contains query and membership reports for both Version 1 and Version 2, and it provides statistics on messages sent and received.
Step 9 (Optional) Get Join and Leave Timestamps for All Groups
Optionally, use HTGetStructure with NS_IGMPV3_ALL_GROUP_INFO to retrieve Join and Leave timestamps for all multicast groups and interfaces.
Original Function Message Function iType1 Related Structure
HTSetStructure NS_IGMPV3_CONFIG NSIGMPv3Config
Original Function Message Function iType1 Related Structure
HTSetStructure NS_IGMPV3_GROUP_MOD NSIGMPv3GroupMod
Original Function Message Function iType1 Related Structure
HTGetStructure NS_IGMPV3_GROUP_INFO NSIGMPv3GroupInfo
Original Function Message Function iType1 Related Structure
HTGetStructure NS_IGMPV3_STATS_INFO NSIGMPv3StatsInfo
Original Function Message Function iType1 Related Structure
HTGetStructure NS_IGMPV3_ALL_GROUP_INFO NSIGMPv3GroupInfo
Chapter 20: IGMP TestingSet Up IGMPv3 Multicast Groups
SmartLibrary Overview and Procedures | 477
Step 10 Leave Groups
Use HTSetCommand with NS_IGMPV3_LEAVE_ALL to leave all multicast groups.
End of Required Steps for Basic Setup
This completes the basic steps needed to test with IGMPv3 groups. The usefulness of your test, however, depends on getting test results.
Original Function Message Function iType1 Related Structure
HTSetCommand NS_IGMPV3_LEAVE_ALL —
Chapter 20: IGMP TestingGetting Test Results
478 | SmartLibrary Overview and Procedures
Getting Test ResultsYour test can provide three types of results:– Counters– Captured data — or —– Histograms
Counters Counters are always available. You need not enable them or set them up explicitly. You can get counter information during the test or after it stops.
Captured data and histograms
You can also retrieve captured data or histograms, but not both in the same test. For these, you must specify the type of results desired, and you must enable the function. You set up data capture or histogram results before you start your test. You obtain either type of results after you run the test.
How to Get Counter Information
Different commands are available for IGMPv2 and IGMPv3 results.
IGMPv2 You can use HTGetStructure with NS_IGMP_COUNTER_INFO to get IGMPv2 counters.
You can also use HTGetStructure with NS_IGMP_TIMESTAMP_INFO to get Join and Leave timestamps. It provides timestamp information for a specified multicast group on a specified port.
IGMPv3 Use HTGetStructure with the following commands to get IGMPv3 statistics and counters.
Original Function Message Function iType1 Related Structure
HTGetStructure NS_IGMP_COUNTER_INFO NSIGMPCounterInfo
HTGetStructure NS_IGMP_TIMESTAMP_INFO NSIGMPTimestampInfo
Original Function Message Function iType1 Related Structure
HTGetStructure NS_IGMPV3_GROUP_INFO NSIGMPv3GroupInfo
NS_IGMPV3_ALL_GROUP_INFO NSIGMPv3GroupInfo
NS_IGMPV3_STATS_INFO NSIGMPv3StatsInfo
Chapter 20: IGMP TestingGetting Test Results
SmartLibrary Overview and Procedures | 479
How to Set Up Data Capture
To specify data capture, use the steps described in this user guide the card type in use. See the applicable chapters in this manual:
• LAN-310xA/B Chapter 18, “SmartMetrics/TeraMetrics Testing”
• LAN TeraMetrics Chapter 18, “SmartMetrics/TeraMetrics Testing”
• POS TeraMetrics Chapter 19, “Packet Over SONET Testing”
• WAN Chapter 15, “WAN (Frame Relay) Testing”
How to Set Up SmartMetrics Histograms
Instead of capture, you can set up SmartMetrics histograms.
• Use NS_HIST_MULTICAST_LATENCY_PER_STREAM to set up an IGMP-specific histograms.
• Use NS_HIST_MULTICAST_LATENCY_PER_STREAM_INFO to get histogram results.
See also the steps described in the procedure for the card type in use, in applicable chapter in this manual. Other histogram types may also be used.
Chapter 20: IGMP TestingSet Up Multicast Listener Discovery (version 1)
480 | SmartLibrary Overview and Procedures
Set Up Multicast Listener Discovery (version 1)Use the following steps to set up SmartBits ports for testing Multicast Listener Discovery version 1 (MLDv1). MLDv1 is described in RFC 2710, which specifies “the protocol used by an IPv6 router to discover the presence of multicast listeners (that is, nodes wishing to receive multicast packets) on its directly attached links, and to discover specifically which multicast addresses are of interest to those neighboring nodes. This information is then provided to whichever multicast routing protocol is being used by the router, in order to ensure that multicast packets are delivered to all links where there are interested receivers.”
The following test setup can be used with TeraMetrics-based LAN and POS SmartBits modules.
Applicable CommandsTable 20-3 gives a summary of commands you can use in your tests. Not all commands are required. This list is an overview. See “Example of Setup Steps” on page 481 for a basic setup procedure, as well as optional commands and actions.
Table 20-3. Applicable Commands for MLDv1 Testing
Applicable Commands
What the Commands Do Original Function Message Function iType1/Notes
Reset card to the default state. HTResetPort See “Example of Setup Steps” on page 481.
Clear counters. HTClearPort See “Example of Setup Steps” on page 481.
Set up streams. HTSetStructure L3_DEFINE_<n>_STREAM
Note: At least one stream must be defined on the Rx port, to place the card into SmartMetrics mode.
Reset the MLD stack on the transmit and receive ports.
HTSetCommand NS_MLD_RESET
Set addresses on the transmit and receive ports (including MAC addresses on Ethernet ports).
HTSetStructure L3_TX_IPV6_ADDRESS
Configure the MLD stack on transmitting ports.
HTSetStructure NS_MLD_CONFIG
Optional.
Start capture on receiving ports.
HTSetStructure
HTSetCommand
NS_CAPTURE_SETUP
NS_CAPTURE_START
Start MLD Listen on transmit ports. HTSetStructure NS_MLDV1_LISTEN
Continues –>
Chapter 20: IGMP TestingSet Up Multicast Listener Discovery (version 1)
SmartLibrary Overview and Procedures | 481
Example of Setup Steps
Here is an example of how to set up your test. It assumes no previous configuration. It shows selected commands, not all possible commands or actions.
Step 1 Reset the Card
Use HTResetPort to set the card to a known, default state.
Step 2 Clear All Counters
Use HTClearPort to clear all counters.
Continues –>
Applicable Commands
What the Commands Do Original Function Message Function iType1/Notes
Optional.
Stop capture on receiving ports. HTSetCommand NS_CAPTURE_STOP
Get the number of captured frames. HTGetStructure NS_CAPTURE_COUNT_INFO
Get the captured frames. HTGetStructure NS_CAPTURE_DATA_INFO
Stop MLD Listen on transmit ports. HTSetStructure NS_MLDV1_LISTEN
Retrieve MLD counter information. HTGetStructure NS_MLD_COUNTER_INFO
Retrieve Join and Leave timestamps for all multicast groups.
HTGetStructure NS_MLD_TIMESTAMP_INFO
Table 20-3. Applicable Commands for MLDv1 Testing (continued)
Original Function Description
HTResetPort Reset the card or module to a default state.
Original Function Description
HTClearPort Clear the port counters.
Chapter 20: IGMP TestingSet Up Multicast Listener Discovery (version 1)
482 | SmartLibrary Overview and Procedures
Step 3 Set Up StreamsUse HTSetStructure with L3_DEFINE_<n>_STREAM to configure at least one stream on the receiving port. Here, <n> represents the stream type and can be IP, IPX, UDP, TCP, or SmartBits.
Note: Doing this places the card into the SmartMetrics mode. You must set up at least one stream on the Rx port.
Step 4 Reset the MLD Stack on Transmit and Receive Ports
Use HTSetCommand with NS_MLD_RESET to reset the MLD stack on the transmit and receive test ports.
Step 5 Configure Port Addresses
Configure the IP addresses of transmitting and receiving test ports. With Ethernet ports, set the MAC addresses. Use HTSetStructure with L3_TX_IPV6_ADDRESS.
Step 6 Configure the MLD Stack on Transmitting Ports
Use HTSetStructure with NS_MLDV3_CONFIG to configure the MLD stack on the transmitting test ports.
Original Function Message Function iType1 Related Structure
HTSetStructure L3_DEFINE_<n>_STREAM Stream<n>
L3_DEFINE_<n>_STREAM_EXTENSION StreamExtension
L3_DEFINE_MULTI_<n>_STREAM Stream<n>
L3_DEFINE_MULTI_<n>_STREAM_EXTENSION StreamExtension
Original Function Message Function iType1 Related Structure
HTSetCommand NS_MLD_RESET None
Original Function Message Function iType1 Related Structure
HTSetStructure L3_TX_IPV6_ADDRESS Layer3IPv6Address
Original Function Message Function iType1 Related Structure
HTSetStructure NS_MLD_CONFIG NSMLDConfig
Chapter 20: IGMP TestingSet Up Multicast Listener Discovery (version 1)
SmartLibrary Overview and Procedures | 483
Step 7 (Optional) Start Capture on the Receiving Ports
If desired, use HTSetStructure with NS_CAPTURE_SETUP to configure the capture engine for receiving test ports. Then use HTSetCommand with NS_CAPTURE_START to start capture.
Note: You will find detailed steps on setting up capture in the chapter that covers the module types that may be used:
• LAN TeraMetrics Chapter 18, “SmartMetrics/TeraMetrics Testing”
• POS TeraMetrics Chapter 19, “Packet Over SONET Testing”
Step 8 Start MLD Listen on Transmitting Ports
Use HTSetStructure with NS_MLDV1_LISTEN. The ucAction field should be set to MLDV1_START_LISTEN.
Step 9 (Optional) Stop Capture on the Receiving Ports
The transmitting port will send Multicast Listener Reports to the receiving port after the call to NS_MLDV1_LISTEN. If you have started capture, stop the capture now by using HTSetCommand with NS_CAPTURE_STOP.
Step 10 (Optional) Get the Number of Captured Frames
Retrieve the number of captured frames (Multicast Listener Reports) on the receiving ports. Use HTGetStructure with NS_CAPTURE_COUNT_INFO to get the capture count.
Continues –>
Original Function Message Function iType1 Related Structure
HTSetStructure
HTSetCommand
NS_CAPTURE_SETUP
NS_CAPTURE_START
NSCaptureSetup
—
Original Function Message Function iType1 Related Structure
HTSetStructure NS_MLDV1_LISTEN NSMLDv1Listen
Original Function Message Function iType1 Related Structure
HTSetCommand NS_CAPTURE_STOP —
Original Function Message Function iType1 Related Structure
HTGetStructure NS_CAPTURE_COUNT_INFO NSCaptureCountInfo
Chapter 20: IGMP TestingSet Up Multicast Listener Discovery (version 1)
484 | SmartLibrary Overview and Procedures
Step 11 (Optional) Get the Captured Frames
Retrieve the captured frames (Multicast Listener Reports) on the receiving ports. Use HTGetStructure with NS_CAPTURE_DATA_INFO to get the capture count.
Step 12 Stop MLD Listen on Transmitting Ports
Use HTSetStructure with NS_MLDV1_LISTEN. The ucAction field should be set to MLDV1_STOP_LISTEN.
Step 13 Retrieve MLD Counter Information
Use HTGetStructure with NS_MLD_COUNTER_INFO to get the MLD counters.
Step 14 Retrieve Join and Leave Timestamps for All Multicast Groups
Use HTGetStructure with NS_MLD_TIMESTAMP_INFO to retrieve Join and Leave timestamps for all multicast groups.
End of Steps for Basic Setup
This completes the basic steps needed to test for Multicast Listener Discovery version 1.
Original Function Message Function iType1 Related Structure
HTGetStructure NS_CAPTURE_DATA_INFO NSCaptureDataInfo
Original Function Message Function iType1 Related Structure
HTSetStructure NS_MLDV1_LISTEN NSMLDv1Listen
Original Function Message Function iType1 Related Structure
HTGetStructure NS_MLD_COUNTER_INFO NSMLDCounterInfo
Original Function Message Function iType1 Related Structure
HTGetStructure NS_MLD_TIMESTAMP_INFO NSMLDTimestampInfo
Chapter 20: IGMP TestingSet Up Multicast Listener Discovery (version 2)
SmartLibrary Overview and Procedures | 485
Set Up Multicast Listener Discovery (version 2)The second version of Multicast Listener Discovery (MLDv2) is specified by temporary IETF Internet-Drafts that update RFC 2710. The SmartLibrary implementation of MLDv2 is based on the following Internet-Draft:
draft-vida-mld-v2-07.txt
Use the following steps to set up SmartBits ports for testing MLDv2. The following test setup can be used with TeraMetrics-based LAN and POS SmartBits modules.
Applicable CommandsTable 20-4 gives a summary of commands you can use in your tests. Not all commands are required. This list is an overview. See “Example of Setup Steps” on page 486 for a basic setup procedure, as well as optional commands and actions.
Table 20-4. Applicable Commands for MLDv2 Testing
Applicable Commands
What the Commands Do Original Function Message Function iType1/Notes
Reset card to the default state. HTResetPort See “Example of Setup Steps” on page 486.
Clear counters. HTClearPort See “Example of Setup Steps” on page 486.
Reset the MLD stack on the transmit and receive ports.
HTSetCommand NS_MLD_RESET
Optional.
Set the MAC and IPv6 addresses (Ethernet only).
HTSetStructure L3_TX_IPV6_ADDRESS
Configure the MLD stack on the transmitting port.
HTSetStructure NS_MLD_CONFIG
Optional.
Configure the Type and the Destination Address field to be used for sending Listener Reports.
HTSetStructure NS_MLDV2_LISTENER_REPORT_CONFIG
Optional.
Start capture on receiving port.
HTSetStructure
HTSetCommand
NS_CAPTURE_SETUP
NS_CAPTURE_START
Configure multicast groups, interfaces and set filter mode for groups.
HTSetStructure NS_MLDV2_GROUP_CONFIG
Continues –>
Chapter 20: IGMP TestingSet Up Multicast Listener Discovery (version 2)
486 | SmartLibrary Overview and Procedures
Example of Setup Steps
Here is an example of how to set up your test. It assumes no previous configuration. It shows selected commands, not all possible commands or actions.
Step 1 Reset the card
Use HTResetPort to set the card to a known, default state.
Step 2 Clear all counters
Use HTClearPort to clear all counters.
Applicable Commands
What the Commands Do Original Function Message Function iType1/Notes
Optional.
Make a state change in a multicast group or add a new multicast group.
HTSetStructure NS_MLDV2_GROUP_MOD
Optional.
Stop capture on the receiving port.
HTSetCommand NS_CAPTURE_STOP
Optional.
Capture Multicast Listener Report Messages sent to the receiving port.
HTGetStructure NS_CAPTURE_DATA_INFO
Optional.
Stop listening to all groups on a port.
HTSetCommand NS_MLD_STOP_LISTEN
Optional.
Retrieve report counters for a specific multicast group.
HTGetStructure NS_MLDV2_STATS_INFO
Optional.
Retrieve the join and leave timestamp for a multicast group.
HTGetStructure NS_MLD_GROUP_INFO
Optional.
Retrieve the number of multicast groups on a port.
HTGetStructure NS_MLD_GROUP_COUNT_INFO
Optional.
Retrieve join and leave timestamp for all multicast groups.
HTGetStructure NS_MLD_ALL_GROUP_INFO
Table 20-4. Applicable Commands for MLDv2 Testing (continued)
Original Function Description
HTResetPort Reset the card or module to a default state.
Chapter 20: IGMP TestingSet Up Multicast Listener Discovery (version 2)
SmartLibrary Overview and Procedures | 487
Step 3 Reset the MLD stack on the port
Use HTSetCommand with NS_MLD_RESET to reset the MLD stack on the test port.
Step 4 (Optional) Configure port addresses
Configure the MAC and IP addresses on the test port. (Ethernet only)
Step 5 Configure the MLD stack on the port
Use HTSetStructure with NS_MLD_CONFIG to configure the MLD stack on the test port.
Step 6 (Optional) Configure Type and Destination Address field for Listener Reports
Currently the value for MLDv2 Multicast Listener Report is not available, so you can set it with this command.
Original Function Description
HTClearPort Clear the port counters.
Original Function Message Function iType1 Related Structure
HTSetCommand NS_MLD_RESET None
Original Function Message Function iType1 Related Structure
HTSetStructure L3_TX_IPV6_ADDRESS Layer3IPv6Address
Original Function Message Function iType1 Related Structure
HTSetStructure NS_MLD_CONFIG NSMLDConfig
Original Function Message Function iType1 Related Structure
HTSetStructure NS_MLDV2_LISTENER_REPORT_CONFIG
NSMLDv2ListenerReportConfig
Chapter 20: IGMP TestingSet Up Multicast Listener Discovery (version 2)
488 | SmartLibrary Overview and Procedures
Step 7 (Optional) Start capture on the receiving ports
Start the capture of packets on the receiving port. (The transmitting port will send an MLDv2 Multicast Listener Report Message to the receiving port.)
Use HTSetStructure with NS_CAPTURE_SETUP to configure the capture engine for the receiving test port. Then use HTSetCommand with NS_CAPTURE_START to start capture.
Note: You will find detailed steps on setting up capture in the chapter that covers the module types that can be used:
• LAN TeraMetrics Chapter 18, “SmartMetrics/TeraMetrics Testing”
• POS TeraMetrics Chapter 19, “Packet Over SONET Testing”
Step 8 Configure multicast groups and interfaces, and set filter mode for groups
Step 9 (Optional) Make a state change in a multicast group or add a new multicast group
Make a single state change in an existing multicast group, or add a new multicast group if the multicast group or interface ID is new
Step 10 (Optional) Stop capture on the receiving port
Use HTSetCommand with NS_CAPTURE_STOP to stop capture on the receiving port.
Original Function Message Function iType1 Related Structure
HTSetStructure
HTSetCommand
NS_CAPTURE_SETUP
NS_CAPTURE_START
NSCaptureSetup
—
Original Function Message Function iType1 Related Structure
HTSetStructure NS_MLDV2_GROUP_CONFIG NSMLDv2GroupConfig
Original Function Message Function iType1 Related Structure
HTSetStructure NS_MLDV2_GROUP_MOD NSMLDv2GroupMod
Original Function Message Function iType1 Related Structure
HTSetCommand NS_CAPTURE_STOP —
Chapter 20: IGMP TestingSet Up Multicast Listener Discovery (version 2)
SmartLibrary Overview and Procedures | 489
Step 11 (Optional) Capture the Multicast Listener Report Message on the receiving port
Use HTSetStructure with NS_CAPTURE_DATA_INFO to capture Multicast Listener Report Messages sent to the receiving port.
Step 12 (Optional) Stop listening to all groups
Use HTSetCommand with NS_MLD_STOP_LISTEN to stop listening to all groups on a port.
Step 13 (Optional) Retrieve report counters for a specific multicast group
This command gets the number of MLDv1 and MLDv2 queries received. It also returns the following reports sent from the port:
• MODE_IS_INCLUDE
• MODE_IS_EXCLUDE
• CHANGE_TO_INCLUDE_MODE
• CHANGE_TO_EXCLUDE_MODE
• ALLOW_NEW_SOURCES
• BLOCK_OLD_SOURCES
Step 14 (Optional) Retrieve the join and leave timestamps for a multicast group
Use HTGetStructure with NS_MLD_GROUP_INFO to retrieve join and leave timestamps for a multicast group.
Continues –>
Original Function Message Function iType1 Related Structure
HTGetStructure NS_CAPTURE_DATA_INFO NSCaptureDataInfo
Original Function Message Function iType1 Related Structure
HTSetCommand NS_MLD_STOP_LISTEN —
Original Function Message Function iType1 Related Structure
HTGetStructure NS_MLDV2_STATS_INFO NSMLDv2StatsInfo
Original Function Message Function iType1 Related Structure
HTGetStructure NS_MLD_GROUP_INFO NSMLDGroupInfo
Chapter 20: IGMP TestingSet Up Multicast Listener Discovery (version 2)
490 | SmartLibrary Overview and Procedures
Step 15 (Optional) Retrieve the number of multicast groups on a port
A multicast configuration with the same multicast address but a different multicast interface configuration is considered to be in a separate multicast group.
Step 16 (Optional) Retrieve join and leave timestamps for all multicast groups
This retrieves join and leave timestamps for all multicast groups on a port. The number of groups can be obtained by using NS_MLD_GROUP_COUNT_INFO.
End of Steps for Basic Setup
This completes the basic steps needed to test for Multicast Listener Discovery version 2.
Original Function Message Function iType1 Related Structure
HTGetStructure NS_MLD_GROUP_COUNT_INFO ULong
Original Function Message Function iType1 Related Structure
HTGetStructure NS_MLD_ALL_GROUP_INFO NSMLDGroupInfo
SmartLibrary Overview and Procedures | 491
Chapter 21
Dynamic MPLS
This chapter provides step-by-step procedures you can use to set up tests with dynamic MPLS.
Note: For a detailed discussion on creating streams, refer to Chapter 4, “Traffic Rates and Patterns”
In this chapter...
• Set Up Dynamic MPLS . . . . 492
Chapter 21: Dynamic MPLSSet Up Dynamic MPLS
492 | SmartLibrary Overview and Procedures
Set Up Dynamic MPLSUse the following steps to set up test ports with dynamic MPLS.
Applicable CommandsTable 21-1 summary of commands you can use in your tests. Not all commands are required. This list is an overview. See “Example of Setup Steps” on page 494 for a basic setup procedure, as well as optional commands and actions.
Table 21-1. Applicable Commands for Dynamic MPLS
Applicable Commands
What the Commands Do Original Function Message Function iType1/Notes
Create a subprocess on the module. HTSetStructure NS_CREATE_SUBPROCESS
Create one or more Routing Domains for the port.
HTSetStructure MPLS_ROUTING_DOMAIN_CREATE
Optional. Create objects. HTSetStructure MPLS_SERVICE_OBJECT_CREATE
MPLS_ATTRIBUTE_OBJECT_CREATE
MPLS_EXPLICIT_ROUTE_OBJECT_CREATE
Create one or more LSPs per Routing Domain.
HTSetStructure MPLS_LSP_CREATE
Start the MPLS control-plane transmission.
HTSetStructure MPLS_START
Optional. Get information on whether or not all LSPs have been established.
HTGetStructure MPLS_LSP_NOT_COMPLETE
Optional. Get information on specific LSPs.
HTSetStructure MPLS_LSP_INFO
Optional. Get LSP indexes and labels on a Routing Domain.
HTGetStructure MPLS_LABEL_DATA_INFO
Optional. Get the configuration for a Routing Domain.
HTSetStructure MPLS_RSVP_COUNT_INFO
Optional. Remove all objects for a particular object type.
HTSetStructure MPLS_OBJECT_DELETE
Chapter 21: Dynamic MPLSSet Up Dynamic MPLS
SmartLibrary Overview and Procedures | 493
Applicable Commands
What the Commands Do Original Function Message Function iType1/Notes
Optional. Use an existing LSP as the prototype to create additional LSPs.
HTSetStructure MPLS_LSP_COPY_DELTA
Optional. Get the number of LSPs on a Routing Domain.
HTGetStructure MPLS_LSP_COUNT_INFO
Optional. Delete all LSPs. HTSetStructure MPLS_LSP_DELETE_ALL
Delete all Routing Domains. HTSetStructure MPLS_ROUTING_DOMAIN_DELETE_ALL
Destroy the subprocess. HTSetStructure NS_DESTROY_SUBPROCESS
Table 21-1. Applicable Commands for Dynamic MPLS (continued)
Chapter 21: Dynamic MPLSSet Up Dynamic MPLS
494 | SmartLibrary Overview and Procedures
Example of Setup Steps
Here is an example of how to set up your test. It assumes no previous configuration. It shows selected commands, not all possible commands or actions.
Step 1 Create a Subprocess
Use HTSetStructure with NS_CREATE_SUBPROCESS to create the subprocess on the module. This command is global for the module.
Step 2 Create Routing Domains
Use HTSetStructure with MPLS_ROUTING_DOMAIN_CREATE to create one or more Routing Domains for the port and specify addresses and attributes.
Step 3 Create ObjectsOptional. Use HTSetStructure with the commands listed below to create objects.
Optional/RelatedOptional or related commands and actions (if applicable) are shown in a shaded box. These actions are not required for a basic test setup.
Original Function Message Function iType1 Related Structure
HTSetStructure NS_CREATE_SUBPROCESS NSCreateSubprocess
Original Function Message Function iType1 Related Structure
HTSetStructure MPLS_ROUTING_DOMAIN_CREATE MPLSRoutingDomain
Original Function Message Function iType1 Related Structure
HTSetStructure MPLS_SERVICE_OBJECT_CREATE MPLSServiceObject
MPLS_ATTRIBUTE_OBJECT_CREATE MPLSAttributeObject
MPLS_EXPLICIT_ROUTE_OBJECT_CREATE MPLSExplicitObject
Chapter 21: Dynamic MPLSSet Up Dynamic MPLS
SmartLibrary Overview and Procedures | 495
Step 4 Create LSPs
Use HTSetCommand with MPLS_LSP_CREATE to create one or more LSPs per Routing Domain.
Step 5 Start the MPLS Control Plane Signaling
Use HTSetStructure with MPLS_START to start the MPLS control plane signaling, including specified packet rate.
Step 6 Check that All LSPs Are Established
Optional. Use HTGetStructure with MPLS_LSP_NOT_COMPLETE to verify that all LSPs have been established.
Step 7 Get LSP Status
Optional. Use HTGetStructure with MPLS_LSP_INFO to get the status of LSPs.
Step 8 Optional. Get LSP Indexes and Labels
You can use HTGetStructure with MPLS_LABEL_DATA_INFO to get LSP indexes and labels on a Routing Domain.
Original Function Message Function iType1 Related Structure
HTSetStructure MPLS_LSP_CREATE MPLSLSP
Original Function Message Function iType1 Related Structure
HTSetStructure MPLS_START MPLSStart
Original Function Message Function iType1 Related Structure
HTGetStructure MPLS_LSP_NOT_COMPLETE MPLSStart
Original Function Message Function iType1 Related Structure
HTGetStructure MPLS_LSP_INFO MPLSLSPInfo
Original Function Message Function iType1 Related Structure
HTGetStructure MPLS_LABEL_DATA_INFO MPLSLSPInfo
Chapter 21: Dynamic MPLSSet Up Dynamic MPLS
496 | SmartLibrary Overview and Procedures
Step 9 Optional. Get the Configuration of a Routing Domain
You can use HTGetStructure with MPLS_RSVP_COUNT_INFO to get the status and counters for a Routing Domain.
Step 10 Optional. Remove Objects
You can use HTSetStructure with MPLS_OBJECT_DELETE to remove all objects of a specified type.
Step 11 Optional. Create LSPs by Using a Prototype
You can use HTSetStructure with MPLS_LSP_COPY_DELTA to add LSPs based on a prototype LSP, with modifications. This command lets you increment selected configuration values, including the Egress IP, Extended Tunnel ID, and Tunnel ID.
Step 12 Optional. Get the LSP Count for a Routing Domain
You can use HTGetStructure with MPLS_LSP_COUNT_INFO to get the number of LSPs on a Routing Domain.
Step 13 Optional. Delete LSPs
You can use HTSetStructure with MPLS_LSP_DELETE_ALL to delete all LSPs, specifying the teardown rate.
Original Function Message Function iType1 Related Structure
HTGetStructure MPLS_RSVP_COUNT_INFO MPLSRSVPCountInfo
Original Function Message Function iType1 Related Structure
HTSetStructure MPLS_OBJECT_DELETE MPLSObjectDelete
Original Function Message Function iType1 Related Structure
HTSetStructure MPLS_LSP_COPY_DELTA MPLSLSPCopyDelta
Original Function Message Function iType1 Related Structure
HTGetStructure MPLS_LSP_COUNT_INFO MPLSCountInfo
Original Function Message Function iType1 Related Structure
HTSetStructure MPLS_LSP_DELETE_ALL MPLSLSPDeleteAll
Chapter 21: Dynamic MPLSSet Up Dynamic MPLS
SmartLibrary Overview and Procedures | 497
Step 14 Delete Routing Domains
You can use HTSetStructure with MPLS_ROUTING_DOMAIN_DELETE_ALL to delete all Routing Domains, specifying the teardown rate and whether LSPs should also be deleted or left set up.
Step 15 Destroy the Subprocess
Required. Use HTSetStructure with NS_DESTROY_SUBPROCESS to destroy the subprocess on the module.
Original Function Message Function iType1 Related Structure
HTSetStructure MPLS_ROUTING_DOMAIN_DELETE_ALL MPLSRoutingDomainDeleteAll
Original Function Message Function iType1 Related Structure
HTSetStructure NS_DESTROY_SUBPROCESS ULong
498 | SmartLibrary Overview and Procedures
SmartLibrary Overview and Procedures | 499
Chapter 22
Fibre Channel Testing
This chapter provides step-by-step procedures you can use to set up tests using theFBC-3601A and FBC-3602A Fibre Channel modules.
In this chapter...
• Set Up Fibre Channel Tests . . . . 500
• Set Up Custom Frames . . . . 512
Chapter 22: Fibre Channel TestingSet Up Fibre Channel Tests
500 | SmartLibrary Overview and Procedures
Set Up Fibre Channel TestsThis section explains how to set up your test.
Applicable Commands
Table 22-1 is a summary of commands you can use. Not all commands are required. This list is an overview.
A basic setup See “Example of Setup Steps” on page 501 for a basic setup procedure, as well as optional commands and actions.
Table 22-1. Applicable Commands to Set Up Fibre Channel Tests
Applicable Commands
What the Commands Do Original Function Message Function iType1/Notes
Reset card to the default state. HTResetPort See “Example of Setup Steps” on page 501.
Configure the ports. HTSetStructure FC_PORT_CONFIG
Configure the World Wide Names (WWNs).
HTSetStructure FC_WWN
Set up the streams. HTSetStructure FC_DEFINE_STREAM
Optional. Set up HBA emulation and enable HBA emulation mode.
HTSetCommand See Step 4 through Step 6 for information.
Link the ports. HTSetCommand FC_LINKUP
Get Fibre Channel status. HTGetStructure FC_STATUS_INFO
Perform WWN login. HTSetCommand FC_WWN_LOGIN
Perform discovery. HTSetCommand FC_PUBLIC_DISCOVERY
–or–
FC_PRIVATE_DISCOVERY
Set Ready to Test. HTSetCommand FC_COMMIT
Set burst mode and number of bursts. HTTransmitMode
HTBurstCount
See “Example of Setup Steps” on page 501.
Get port status to see if ready. HTGetStructure FC_STATUS_INFO
(Optional) Set up port groups. HGSetGroupHGAddtoGroup
See “Example of Setup Steps” on page 501.
Chapter 22: Fibre Channel TestingSet Up Fibre Channel Tests
SmartLibrary Overview and Procedures | 501
Example of Setup Steps
Here is an example of how to set up your test. It assumes no previous configuration. It shows selected commands, not all possible commands or actions.
Step 1 Configure the ports.Use HTSetStructure with FC_PORT_CONFIG(FCPortConfig) to set up the port configuration, defining parameters such as topology, port speed, and BB-Credit.Your setting for the fabric topology (point-to-point, public loop, or private loop) determines which commands need to be used to bring the port to the Ready to Test state. See Step 9 and Step 10 below.
Step 2 Configure the World Wide Names (WWNs).Use HTSetStructure with FC_WWN(FCWWN) to define the WWNs for emulated Fibre Channel nodes and devices.This structure enables you set Public or Private mode for Loop topologies (ucPublic field: 1 = Public, 0 = Private). This setting, in turn, has a bearing on what Discovery command should be used (see Step 9 and Step 10 below).
Applicable Commands
What the Commands Do Original Function Message Function iType1/Notes
Start test traffic, then stop the test. HTRun/HGRun See “Example of Setup Steps” on page 501.
HTStop
Get test counters. HTGetStructure FC_COUNTER_INFO
Table 22-1. Applicable Commands to Set Up Fibre Channel Tests (continued)
Optional/RelatedOptional or related commands and actions (if applicable) are shown in a shaded box. These actions are not required for a basic test setup.
Original Function Message Function iType1 Related Structure
HTSetStructure FC_PORT_CONFIG FCPortConfig
Original Function Message Function iType1 Related Structure
HTSetStructure FC_WWN FCWWN
Chapter 22: Fibre Channel TestingSet Up Fibre Channel Tests
502 | SmartLibrary Overview and Procedures
Step 3 Set up the streams.
Use HTSetStructure with FC_DEFINE_STREAM (StreamFC) to add a 64-byte stream configuration. This function specifies the stream template (structure of frames to be sent).
You can also set up 128-byte streams. Use HTSetStructure with FC_DEFINE_STREAM_128 (StreamFC128). With these, the header length is the same as with 64-byte streams (24 bytes), but the payload length increases from 40 bytes to 92 bytes.
Step 4 Optional. Set the module into HBA emulation mode.
Use HTSetStructure with FC_SET_TX_MODE (FCTransmitMode) to enable the HBA emulation mode. Set ucTxMode to HBA_EMULATION_MODE.
Step 5 Optional. Set up the HBA timers and counts.
Use HTSetStructure with FC_HBA_CONFIG (FCHBAConfig) to set up the timers and retry counts for the HBA state machine. All timer values are in milliseconds.
You can set a delay between the states (ulInterStateTimer). You can also define counts and timers for both normal polling and error conditions.
Original Function Message Function iType1 Related Structure
HTSetStructure FC_DEFINE_STREAM StreamFC
HTSetStructure FC_DEFINE_STREAM_128 StreamFC128
OptionalStep 4 through Step 6 cover optional steps to set up Host Bus Adapter emulation on the Fibre Channel port. When you do this, you need not send commands for Linkup, Login, Discovery, and Commit, as these are performed as part of the HBA state machine. You do need to start traffic (this normally is done by the HBA as well). See below for details, or continue with Step 7 if you do not wish to enable HBA emulation.
Original Function Message Function iType1 Related Structure
HTSetStructure FC_SET_TX_MODE FCTransmitMode
Original Function Message Function iType1 Related Structure
HTSetStructure FC_HBA_CONFIG FCHBAConfig
Chapter 22: Fibre Channel TestingSet Up Fibre Channel Tests
SmartLibrary Overview and Procedures | 503
Step 6 Optional. Start the HBA mode.
Use HTSetCommand with FC_HBA_START to start the HBA emulation state machine.
Once the state machine has been started, the four “steps” to achieve Ready to Test are handled by the state machine. (The four steps are Linkup, Login, Discovery, and Commit.) For this reason, you do not need to send the related commands individually.
In addition, you do not (necessarily) need to use FC_STATUS_INFO to find whether each step completed successfully, since the state machine moves to the next step only when ready.
Important: The HBA emulation machine does not start sending traffic, as an HBA would do in most cases. Use HTRun or HGRun to start test traffic (see Step 15 on page 505).
Step 7 Link up the ports.
Use HTSetCommand with FC_LINKUP to link the ports to the fiber.
Step 8 Get port link status.
Use FC_STATUS_INFO(FCStatus) to get port status.
Step 9 Perform Fabric Login
When the test uses Public Loop topology, use FC_WWN_LOGIN to perform Fabric Login. Then perform Public Discovery (see Step 10). This step is required only when the topology is Public Loop. You specify Public Loop topology by setting ucTopology = TOPOLOGY_LOOP in the FCPortConfig structure and ucPublic = 1 in the FCWWN structure.
This step is not required when the topology is Private Loop or Point-to-Point.
Original Function Message Function iType1 Related Structure
HTSetCommand FC_HBA_START —
Original Function Message Function iType1 Description
HTSetCommand FC_LINKUP Perform Link Initialization.
Original Function Message Function iType1 Related Structure
HTGetStructure FC_STATUS_INFO FCStatus
Original Function Message Function iType1 Description
HTSetCommand FC_WWN_LOGIN Perform Fabric login.
Chapter 22: Fibre Channel TestingSet Up Fibre Channel Tests
504 | SmartLibrary Overview and Procedures
Step 10 Perform Public or Private Discovery
This action follows the completion of Fabric Login (Step 9). (Fabric Login is required only for Public Loop topology, not for Private Loop or Point-to-Point topologies.)
For this step:
• When the topology is Public Loop, use FC_PUBLIC_DISCOVERY.
• When the topology is Private Loop, use FC_PRIVATE_DISCOVERY.
• When the topology is Point-to-Point, a Discovery command is not required. Go directly to Step 11 to commit the configuration.
Step 11 Commit the configuration.
Complete the initialization and configuration process.
Step 12 Set the burst mode and number of bursts.
Use the Original Functions listed below to set the burst mode and number.
Original Function Message Function iType1 Description
HTSetCommand FC_PUBLIC_DISCOVERY With public loop topology.
FC_PRIVATE_DISCOVERY With private loop topology.
Original Function Message Function iType1 Description
HTSetCommand FC_COMMIT Complete initialization and configuration. Ready to test.
Original Function Description
HTTransmitMode Set the transmit mode. Options include continuous, multi-burst, single burst, and continuous multi-burst.
HTBurstCount/HTBurstGap Define number of packets per burst and the gap between bursts.
Chapter 22: Fibre Channel TestingSet Up Fibre Channel Tests
SmartLibrary Overview and Procedures | 505
Step 13 Check port status.
Use HTGetStructure with FC_STATUS_INFO(FCStatus) to check the port status.
Step 14 Set Up Port Groups
Use HGSetGroup and HGAddtoGroup to define the port group and to add ports to a group.
Step 15 Send Test Traffic, Stop Test Traffic
Use the HTRun or HGRun command to run the test. (See the SmartLibrary Command Reference for descriptions of these Original Functions.)
Use HTStop or HGStop to stop the test when run with continuous traffic.
Original Function Message Function iType1 Related Structure
HTGetStructure FC_STATUS_INFO FCStatus
Original Function Description
HGSetGroup Define a group of SmartBits ports.
HGAddtoGroup Add ports to the group. You control grouped ports by using the HG commands.
Original Function Description
HTRun Send test traffic.
HGStop/HGRun (HGStep) For a group start, first initialize the timestamps on all cards using the “Timestamp-Initialization Sequence.” Then send test traffic using HGRun or HGStep.
HTStop/HGStop Stop the test traffic, if running continuous traffic as opposed to step or burst.
Chapter 22: Fibre Channel TestingSet Up Fibre Channel Tests
506 | SmartLibrary Overview and Procedures
Step 16 Get counters.
Use HTGetStructure with FC_COUNTER_INFO(FCPortCounts) to get the port counters from the test. These results do not show latencies.
End of Required Steps for Basic Setup
This completes the basic steps needed to transmit test traffic. The usefulness of your test, however, depends on getting test results. See “Getting Test Results” on page 507 for the steps to use counters, capture, or histograms to measure test traffic.
Original Function Message Function iType1 Related Structure
HTGetStructure FC_COUNTER_INFO FCPortCounts
Chapter 22: Fibre Channel TestingSet Up Fibre Channel Tests
SmartLibrary Overview and Procedures | 507
Getting Test Results
Your test can provide three types of results. These are:– Counters– Captured data — or —– Histograms
Counters Counters are always available. You need not enable them or set them up explicitly. You can get counter information during the test or after it stops.
Captured data and histograms
You can also retrieve captured data or histograms, but not both in the same test. For these, you must specify the type of results desired, and you must enable the function. You set up data capture or histogram results before you start your test. You obtain either type of results after you run the test.
How to Get Counter Information
Use HTGetStructure with FC_COUNTER_INFO to get generic counters and Fibre Channel counters for your test.
Note: Other counters commands also may apply for the card or module in use. Refer to the compatibility tables in the SmartLibrary Command Reference (Volumes 1 and 2), to determine what other commands might be used.
How to Set Up Data Capture
Use the following steps to set up data capture. You can enable either data capture or SmartMetrics histogram results (see “How to Set Up SmartMetrics Histograms” on page 510.)
Step 1 Set up the capture parameters.
Use HTSetStructure with NS_CAPTURE_SETUP(NSCaptureSetup) to specify the capture mode, length, and event.
Original Function Message Function iType1 Structure
HTGetStructure FC_COUNTER_INFO FCCounterInfo
Original Function Message Function iType1 Related Structure
HTSetStructure NS_CAPTURE_SETUP NSCaptureSetup
Chapter 22: Fibre Channel TestingSet Up Fibre Channel Tests
508 | SmartLibrary Overview and Procedures
Capture Mode. Valid options for NSCaptureSetup(ulCaptureMode) include:
Capture Length. Valid options for NSCaptureSetup(ulCaptureLength) include:
Capture Event. The CAPTURE_EVENTS element in NSCaptureSetup defines what frame types should be captured. Valid options for NSCaptureSetup(ulCaptureEvents) include:
Capture Mode Description
CAPTURE_MODE_FILTER_ON_EVENTS Capture only packets with the specified event, such as CRC errors, undersize packets, or oversize packets.
CAPTURE_MODE_START_ON_EVENTS Capture all packets following the specified event. For example, begin capture when the first packet with a CRC error is received, then capture all packets.
CAPTURE_MODE_STOP_ON_EVENTS Capture all packets until the specified event. For example, capture all packets until the first packet with a CRC error is received, then stop the capture.
Capture Length Description
CAPTURE_LENGTH_ENTIRE_FRAME Capture complete frame.
CAPTURE_LENGTH_1ST_64_BYTES Capture only the first 64 bytes in the frame.
CAPTURE_LENGTH_LAST_64_BYTES Capture only the last 64 bytes in the frame.
Capture Event Description
CRC_ERRORS Capture all frames with CRC errors.
DATA_INTEGRITY_ERROR Capture all frames in which the payload contents have become corrupted.
RX_TRIGGER Capture all frames that contain receive trigger patterns.
Chapter 22: Fibre Channel TestingSet Up Fibre Channel Tests
SmartLibrary Overview and Procedures | 509
Step 2 Start the capture, then stop it.
Step 3 Get the captured data.
Use HTGetStructure with NS_CAPTURE_COUNT_INFO to find the number of frames in the buffer.
Use HTGetStructure with NS_CAPTURE_DATA_INFO to get the captured frames.
Original Function Message Function iType1 Description
HTSetCommand NS_CAPTURE_START Clear the buffer and start the capture.
NS_CAPTURE_STOP Stop capture.
Original Function Message Function iType1 Related Structure
HTGetStructure NS_CAPTURE_COUNT_INFO NSCaptureCountInfo
NS_CAPTURE_DATA_INFO NSCaptureDataInfo
Chapter 22: Fibre Channel TestingSet Up Fibre Channel Tests
510 | SmartLibrary Overview and Procedures
How to Set Up SmartMetrics Histograms
Histograms provide in-depth test results, including sequence and latency information.
Histogram information is gathered on the receiving card.
Step 1 Enable the histogram type.
For SmartMetrics histograms results, specify the histogram type. You can specify one of the following histogram types.
Continues –>
Original Function Message Function iType1 Related Structure/Description
HTSetStructure NS_HIST_V2_LATENCY_PER_STREAM Layer3V2HistDistribution
Gives an overall picture of latency per stream. Provides the following results:
Latency per Stream. Shows minimum, maximum, and average latency values over the course of the test.
Latency Distribution. Shows the occurrence of specific latency values per stream.
Sequence Tracking. Reports whether or not frames were received in sequence per stream.
NS_HIST_V2_LATENCY Layer3HistV2Latency
Provides Latency over Time histogram on the receive module.
NS_HIST_RAW_TAGS Signature information only, showing transmit time, receive time, and delta in microseconds.
NS_HIST_SEQUENCE Sequence information only. Reports whether or not frames were received in sequence per stream.
NS_HIST_LATENCY_DISTRIBUTION Layer3HistDistribution
Latency distribution information only. Shows the occurrence of specific latency values per stream.
Chapter 22: Fibre Channel TestingSet Up Fibre Channel Tests
SmartLibrary Overview and Procedures | 511
Step 2 Set up port groups.
For SmartMetrics histogram results, you must set up a port group. Histogram results require a group start.
Use HGSetGroup and HGAddtoGroup to define the port group and to add ports to a group.
Step 3 Gather histogram information.
After the test runs, gather the results for the SmartMetrics histogram you specified in Step 1. Use HTGetStructure with the appropriate iType1, as shown below.
Original Function Description
HGSetGroup Define a group of SmartBits ports.
HGAddtoGroup Add ports to the group. You control grouped ports by using the HG commands.
Original Function Message Function iType1 Related Structure/Description
HTGetStructure NS_HIST_LATENCY_PER_STREAM_INFO Layer3StreamDistributionInfo
Latency Distribution histogram results.
NS_HIST_V2_LATENCY_INFO Layer3HistV2Latency
Latency over Time histogram results.
NS_HIST_RAW_TAGS_INFO Layer3HistTagInfo
Signature information only.
NS_HIST_SEQUENCE_INFO Layer3SequenceInfo
Sequence Tracking histogram results.
NS_HIST_LATENCY_DISTRIBUTION_INFO Layer3StreamDistributionInfo
Latency Distribution histogram results.
Chapter 22: Fibre Channel TestingSet Up Custom Frames
512 | SmartLibrary Overview and Procedures
Set Up Custom FramesThe architecture of SmartBits TeraMetrics modules includes a cut-through channel, which may be used to send and receive control-plane messages apart from test traffic. The cut-through channel is independent of the input/output channels used to generate and receive the frames in test streams. It operates at a comparatively slower rate than do the transmit/receive channels (the actual rate varies, depending on module type).You can use the FC_SEND_CUSTOM and FC_RCV_CUSTOM commands to set up the contents of custom frames to be sent and received using the cut-through channel. The FCCustomFrame structure enables you to specify frame contents byte-by-byte. You can also set a timer on the response from the switch, get the response time, and specify a return code in case of error.
Note: Refer to “Set Up Fibre Channel Tests” on page 500 for the procedure to set up Fibre Channel tests in general.
For Fibre Channel tests, you can use the FC_SEND_CUSTOM and FC_RCV_CUSTOM commands to send control plane messages individually, step through network states, and test individual steps (for example, in the Login or Discovery process).
Message types by phase
For reference, the Fibre Channel messages that are sent in each phase are as follows.
Table 22-2. Applicable Commands: Send and Receive Custom Frames
Message
Phase Type Description
Link up None Just bring up the physical link.
Login FLOGI
PLOGI
RPN_ID
LOGO
Fabric Login
Port Login
Register Port Name
Log Out
Discovery PLOGI
GID_PN
LOGO
Port Login
Get ID based on Port Name
Log Out
Commit PLOGI Port Login
Chapter 22: Fibre Channel TestingSet Up Custom Frames
SmartLibrary Overview and Procedures | 513
Applicable CommandsTable 22-3 is a summary of commands. See “Example of Setup Steps” for more details.
Example of Setup Steps
Here are the steps in more detail.
Step 1 Set the transmit mode to Cut Through.Use HTSetStructure with FC_SET_TX_MODE(FCTransmitMode) to set the transmit mode to cut through.Set ucTxMode to CUT_THROUGH_MODE.
Step 2 Set up the custom frame.
Use HTSetStructure with FC_SEND_CUSTOM to define the contents of the custom frame and to set other values for the message exchange.
Structure elements
Table 22-4 on page 514 defines the elements in the FCCustomFrame structure.
Table 22-3. Applicable Commands: Send and Receive Custom Frames
Applicable Commands
What the Commands Do Original Function Message Function iType1
Set the transmit mode to cut-through. HTSetStructure FC_SET_TX_MODE
Set up the custom frame. HTSetStructure FC_SEND_CUSTOM
Get a custom frame. HTGetStructure FC_RCV_CUSTOM
Original Function Message Function iType1 Related Structure
HTSetStructure FC_SET_TX_MODE FCTransmitMode
Original Function Message Function iType1 Related Structure
HTSetStructure FC_SEND_CUSTOM FCCustomFrame
Chapter 22: Fibre Channel TestingSet Up Custom Frames
514 | SmartLibrary Overview and Procedures
Important: Remember that the order of elements in your structure must reflect byte ordering within each Fibre Channel word. See the example below.
Step 3 Get the response frame.
Your custom frame normally will be a control packet, and there will be a response from the DUT. You can use HTGetStructure with FC_RCV_CUSTOM to retrieve the response packet and get values that reflect the success of the message exchange. See Table 22-4 for definitions of these fields: ulResponseTime and ucMessageType.
Example of setting up the custom frame
Here is an example of setting up a PLOGI frame. The ulLength element in the FCCustomFrame structure lets you specify the total length of the frame (up to 256 bytes). In this example, the frame length is 148 bytes.
Exclusive of payload data, the Fibre Channel frame includes the following fields:
Table 22-4. Structure Elements: FCCustomFrame
Structure Element Description
FCCustomFrame ulLength Total length of the custom frame, including SOF, header, user data, CRC, and EOF.
ulTimeToWait This specifies how long the SmartBits port will wait for the expected response from the DUT.
ulResponseTime Used with HTGetStructure: Contains the time it took for the response from the DUT to reach the SmartBits port.
ucMessageType Used with HTGetStructure: Identifies the type of message received from the DUT in response to the custom frame.
ucErrorCodeReturned Specified what error code to return if there is an error in the message exchange.
ucPayload The user-defined frame contents. Bytes must be defined in network order—that is, in sequence for each Fibre Channel word. See “Example of setting up the custom frame” below and page 514 for an illustration of this requirement.
Original Function Message Function iType1 Related Structure
HTSetStructure FC_SEND_CUSTOM FCCustomFrame
4 bytes 24 bytes 4 bytes 4 bytes
Start of Frame FC2 Protocol Header CRC End of
Frame
Chapter 22: Fibre Channel TestingSet Up Custom Frames
SmartLibrary Overview and Procedures | 515
struct_new myFrame FCCustomFrame
set myFrame(ulLength)148
set myFrame(ulTimeToWait)50
set myFrame(ucPayLoad.0)0x57
set myFrame(ucPayLoad.1)0x57
set myFrame(ucPayLoad.2)0xB5
set myFrame(ucPayLoad.3)0xBC
set myFrame(ucPayLoad.4)0x22
set myFrame(ucPayLoad.5)0xFF
set myFrame(ucPayLoad.6)0xFF
set myFrame(ucPayLoad.7)0xFC
set myFrame(ucPayLoad.12)0x1
set myFrame(ucPayLoad.13)0x29
set myFrame(ucPayLoad.14)0x00
set myFrame(ucPayLoad.15)0x00
set myFrame(ucPayLoad.20)0xFF
set myFrame(ucPayLoad.21)0xFF
set myFrame(ucPayLoad.22)0x39
set myFrame(ucPayLoad.28)0x03
set myFrame(ucPayLoad.32)0x20
set myFrame(ucPayLoad.33)0x00
set myFrame(ucPayLoad.34)0x20
set myFrame(ucPayLoad.35)0x20
set myFrame(ucPayLoad.36)0x40
set myFrame(ucPayLoad.37)0x08
set myFrame(ucPayLoad.52)0x64
set myFrame(ucPayLoad.60)0x64
set myFrame(ucPayLoad.144)0xBC
set myFrame(ucPayLoad.145)0xB5
set myFrame(ucPayLoad.146)0x75
set myFrame(ucPayLoad.147)0x75Example continues –>
The ulLength element sets the total length of the custom frame (up to 256 bytes).The ulTimeToWait element sets a timer on a response from the DUT/SUT.
Start of Frame (SOF) characters.Note: Here is an example of how structure elements must reflect byte order in the FC word.Be sure to define the least-significant byte first in your structure, then succeeding bytes.
The FC header. The value 0x03 identifies the message type as a PLOGI frame.
Byte 0Byte 1Byte 2Byte 3
0x570x570xB50xBC
Chapter 22: Fibre Channel TestingSet Up Custom Frames
516 | SmartLibrary Overview and Procedures
LIBCMD HTSetStructure $::FC_SEND_CUSTOM 0 0 0 myFrame 0 $TxHub $TxSlot $TxPort
after 1000
LIBCMD HTGetStructure $::FC_RECV_CUSTOM 0 0 0 myFrame 0 $TxHub $TxSlot $TxPort
puts "-->$myFrame(ulLength)"
puts "-->$myFrame(ulResponseTime)"
puts "-->$myFrame(ucErrorCodeReturned)"
puts " ##########################"
for {set byte 0} {$byte < $myFrame(ulLength)} {} {
puts -nonewline " Byte $byte is [format %x $myFrame(ucPayLoad.[expr $byte +
3])] [format %x $myFrame(ucPayLoad.[expr $byte + 2])] [format %x
$myFrame(ucPayLoad.[expr $byte + 1])]"
puts " [format %x $myFrame(ucPayLoad.$byte)]"
set byte [ expr $byte + 4 ]
}
puts " ##########################"
This for statement prints the bytes in the frame retrieved by the FC_RCV_CUSTOM command in network order for each Fibre Channel word.
SmartLibrary Overview and Procedures | 517
Chapter 23
Using NTP
This chapter provides guidelines on how to use the NTP Original Functions to set up tests that use NTP for synchronization.
In this chapter...
• What is NTP? . . . . 518
• Procedure to Use NTP . . . . 520
Chapter 23: Using NTPWhat is NTP?
518 | SmartLibrary Overview and Procedures
What is NTP?The Network Time Protocol (NTP) is used to synchronize the clocks on computers or other devices that are connected through a network. It is accurate to within one millisecond. NTP achieves this synchronization by distributing time information in UTC (Universal Time Coordinate) across the network. The computers or devices on the network receive the UTC time information, then make the necessary adjustments to account for factors such as time zone and daylight savings time.
Note: For detailed background information on NTP, refer to Application Note #33, “NTP Operation.”
Summary of Procedure
Here is an outline of the procedure:1 Load the required SmartLibrary files.2 Connect to controllers and reserve ports.3 Switch to a controller that you want to configure as NTP client.4 (Optional) Configure the controller’s netmask and gateway address to work with your
network.5 Once in NTP Mode, you can perform the following actions:
• Add/Delete NTP peers.• (Optional) Configure the NTP client's FFOM, TFOM. This is only necessary if/
when the user wishes to use the NTP provided time in either a less restrictive or more restrictive mode of accuracy. Otherwise, these values should not be changed from their default.
• Enable the NTP client.• Wait for ready by polling the NTP FOM status or sleep.
6 Exit NTP Mode.7 (Optional) Save current configuration.8 Set up data-plane traffic.9 Set up SmartLibrary to do SYNC_ops (HTSeparateHubCommand
HUB_GROUP_SYNC_ACTION).10 Start transmitting (HGStart or HGRun).11 Stop transmitting (HGStop).12 Analyze results.
Chapter 23: Using NTPWhat is NTP?
SmartLibrary Overview and Procedures | 519
Switching between Connected Controllers
All NTP-related functions and structures are executed relatively to the currently active controller only. Using the SmartLibrary interface, an application can connect to more than one SmartBits controller, but only one connected controller can interact with the application at any time. This controller is termed the current active controller.
To to configure different controllers, applications need to switch explicitly among the connected controllers. You can use the following functions to switch between controllers (also see the command descriptions in the Command Reference Manual).
ETSetCurrentLink(int iCommPort);ETSetCurrentSockLink(char* IPAddress);
Note: All NTP-related functions work only on SmartBits 600x/6000x chassis. Executing these functions on a SmartBits 200/2000 will result in error −1001 (UNSUPPORTED_COMMAND).
Entering and Exiting the NTP Super User Mode
NTP-related user commands may be used only under an NTP-specific Super User Mode. Applications need to enter the NTP Super User mode before executing any NTP-related function and, typically, exit the mode when done. Attempts to execute NTP-related commands outside the NTP Super User mode result in an error response.
The NTP Super User mode is like the existing SmartBits Super User mode, but knowledge of it and its password is restricted to qualified users only. All other NTP commands are accessible only under this special mode, as a means to limit unauthorized access to embedded NTP resources.
Chapter 23: Using NTPProcedure to Use NTP
520 | SmartLibrary Overview and Procedures
Procedure to Use NTPHere are details on the procedure and commands to use with NTP.
Enter and Exit Super User Mode
Use the following commands to enter and exit the NTP-specific Super User mode.Step 1 Enter the NTP Super User Mode
Purpose Enter the NTP Super User mode.
Syntax int NSNTPEnterMode(void)
Function NSNTPEnterMode
Parameters None
Return value None
Step 2 Exit the NTP Super User Mode
Purpose Exit the NTP Super User mode.
Syntax int NSNTPExitMode(void)
Function NSNTPExitMode
Parameters None
Return value None
Enable and Disable NTP Clients
Use the following commands to enable or disable NTP clients.
Step 3 Set NTP Client Mode
Purpose Enable or disable an NTP client in a SmartBits 600x/6000x controller. An argument value of 1 enables the client, 0 disables client. Multiple consecutive disables or disables are not considered errors: If a controller already enables the NTP client, then forcing it to enable the NTP client will not cause any error.
After enabling NTP client in a controller, applications should allow the NTP client sufficient time to stabilize its time references before executing any synchronized operation. The waiting time varies, depending on the setup (peers, network condition). It may take at least 15 minutes to stabilize the time references. The application an sleep and wait or poll the client's status for indication of readiness.
An NTP client time is ready for use with synchronized operations if the client’s FOM indicates OK.
Chapter 23: Using NTPProcedure to Use NTP
SmartLibrary Overview and Procedures | 521
If saved, the NTP Client’s enabled mode persists until specifically disabled. A hardware reset will not change the NTP Client enable/disable mode unless a GPS receiver is attached.The firmware will automatically disable the NTP client if it detects the presence of a GPS receiver during boot time.
Syntax int NSNTPSetClientMode(unsigned long ulMode)
Function NSNTPSetClientMode
Parameters unsigned long ulMode
Values 1=Enable, 0=Disable
Return value None if success. Error code if failure. Refer to the SmartLibrary Command Reference manual for error codes.
Configure NTP CLients
Use the following steps to configure the NTP client.
Step 4 Set FFOM Limit
! Caution: You should never change this value from its default (0) value for any testing where timing accuracy is of concern. Doing so could allow the NTP Client to report that its time reference is OK for use with chassis synchronization operations, even if the time is invalid or unstable. This mode is provided only to allow a method of performing func-tional operation without timing accuracy.
Purpose This command sets the acceptable limit for the Frequency Figure Of Merit (FFOM). Valid argument values must be in the range 0 to 3. This command sets the FFOM limit only for NTP operation; it does not affect the GPS-related FFOM limit.
If the NTP’s FFOM becomes larger than the designated limit, the composite FOM for the NTP client will indicate that it is not ready for use in SyncOps. The definition of these FFOM values is intended to be similar to those defined for the HP-58503A GPS Receiver. Essentially, these values are representative of being frequency- and phase-locked to the NTP Server’s time (0), in transition (1), in hold-over mode (2), or unlocked (3). Any changes to this FFOM limit will not be persistent through a reset operation.
Syntax int NSNTPSetFFOMLimit(unsigned long ulFFOMLimit)
Function NSNTPSetFFOMLimit
Parameters unsigned long ulFFOMLimit
Range 0 to 3
Return value None if success. Error code if failure. Refer to the SmartLibrary Command Reference manual for error codes.
Chapter 23: Using NTPProcedure to Use NTP
522 | SmartLibrary Overview and Procedures
Step 5 Set TFOM Limit
! Caution: You should never change this value to be higher than its default value for any testing where timing accuracy is of any concern. Doing so can allow the NTP Client to report that its time reference is OK for use with chassis synchronization operations, even if the time does not meet published accuracy requirements. This mode is provided for two reasons: to allow the user to constrain the timing accuracy of the Client more closely, and to provide a method of performing specialized testing with reduced timing accuracy.
Purpose This command sets the acceptable limit for the Time Figure of Merit (TFOM). Valid argument values MUST be in the range (0:9). This command ONLY sets the TFOM limit for the NTP operation, and DOES NOT AFFECT the GPS related TFOM limit. If the NTP's TFOM becomes larger than the designated limit, the composite FOM for the NTP client will indicate that it is not ready for use in SyncOps.
Any changes to this TFOM limit will not be persistent through a reset operation.
Syntax int NSNTPSetTFOMLimit(unsigned long ulTFOMLimit);
Function NSNTPSetTFOMLimit
Parameters unsigned long ulTFOMLimit
Range Time Figure of Merit, 0 − 9
Return value None if success. Error code if failure. Refer to the SmartLibrary Command Reference manual for error codes.
Step 6 Add an NTP Peer
Purpose This command adds a new peer to the NTP client. The IP address of the peer is provided as an argument of the command. The user may add up to five (5) NTP peers. Any attempt to add more than the maximum number of peers will result in an error response, and will not change the previously defined peers.
Syntax int NSNTPAddPeer(NSIPAddress IPAddress);
Function NSNTPAddPeer
Parameters typedef struct tagNSIPAddress{
unsigned char ucIPAddress[4];
} NSIPAddress;
Return value None if success. Error code if failure. Refer to the SmartLibrary Command Reference manual for error codes.
Chapter 23: Using NTPProcedure to Use NTP
SmartLibrary Overview and Procedures | 523
Step 7 Delete an NTP Peer
Purpose This command causes the client to delete a specific peer, as indicated by the IP address provided as an argument to the command. If this command deletes the last remaining peer, the NTP client will no longer be able to poll for or provide accurate time.
Syntax int NSNTPDeletePeer(NSIPAddress IPAddress);
Function NSNTPDeletePeer
Parameters typedef struct tagNSIPAddress{
unsigned char ucIPAddress[4];
} NSIPAddress;
Return value None if success. Error code if failure. Refer to the SmartLibrary Command Reference manual for error codes.
Note: If all peers are deleted, the NTP Client will degrade into a hold-over mode of operation, relying only on its internal oscillator to retain the NTP time. If peers are later added back, this hold-over time can allow the NTP Client to more quickly synchronize.
Step 8 Delete all NTP Peers
Purpose This command causes the client to delete ALL of its currently defined peers. As a result of executing this command, the client will no longer be able to poll for or provide accurate time.
Syntax int NSNTPDeleteAllPeers(void);
Function NSNTPDeleteAllPeers
Parameters None.
Return value None if success. Error code if failure. Refer to the SmartLibrary Command Reference manual for error codes.
Note: If all peers are deleted, the NTP Client will degrade into a holdover mode of operation, relying only on its internal oscillator to retain the NTP time. If peers are later added back, this holdover time can allow the NTP Client to more quickly synchronize.
Chapter 23: Using NTPProcedure to Use NTP
524 | SmartLibrary Overview and Procedures
Query NTP Clients’ Status
Use the following commands to get NTP Client status information.
Step 9 Get NTP Client's Mode
Purpose This command queries the operational mode of the NTP client. The returned data (ulMode) is a value of 1, if the NTP client is enabled, or a value of 0, if the NTP client is disabled. Note that the NTP client could be disabled because of either by user requests or a present of a GPS receiver.
Syntax int NSNTPGetClientMode(unsigned long* ulMode);
Function NSNTPGetClientMode
Parameters An address of a variable to which the returned mode will be stored. 1=enabled, 0=disabled.
Values 1=enabled, 0=disabled.
Return value None if success. Error code if failure. Refer to the SmartLibrary Command Reference manual for error codes.
Step 10 Get NTP Client's FOM
Purpose This command retrieves all of the Figure of Merit (FOM) status values from the NTP client.
Syntax int NSNTPGetFOM(NSNTPFOMInfo* pNTPFOMInfo);
Function NSNTPGetTFOM
Parameters An address of an NSNTPFOMInfo variable to which the returned value will be stored.
typedef struct tagNSNTPFOMInfo {
unsigned long ulCompositeFOM;/* 1=ready, 0=not_ready */
unsigned long ulCurrentFFOM; /* range 0-3 */
unsigned long ulFFOMLimit; /* range 0-3 */
unsigned long ulCurrentTFOM; /* range 0-9 */
unsigned long ulTFOMLimit; /* range 0-9 */
} NSNTPFOMInfo;
Return value None if success. Error code if failure. Refer to the SmartLibrary Command Reference manual for error codes.
Chapter 23: Using NTPProcedure to Use NTP
SmartLibrary Overview and Procedures | 525
Step 11 Get number of statuses of an NTP client
Purpose This command returns the number of status variables of the NTP client. Applications use this number to request the actual status information and pre-allocate memory for holding the status info.
Syntax int NSNTPGetClientStatusCount unsigned long* ulStatusCount);
Function NSNTPGetClientStatusCount
Parameters A pointer to a variable that will hold the returned number of status variables.
Return value None if success. Error code if failure. Refer to the SmartLibrary Command Reference manual for error codes.
Example (TCL):#
# get status count
#
set status_count 0
CheckError NSNTPGetClientStatusCount status_count
OutMessage "status_count = $status_count"
Step 12 Get statuses of an NTP Client
Purpose This command returns the operational status of an NTP client.
Syntax int NSNTPGetClientStatus(unsigned long ulStatusCount, NSNTPStatusInfo* pStatus);
Function NSNTPGetClientStatus
Parameters A number of status variables which applications are interested in and a pointer to a memory location to which the status information will be copied.
unsigned long ulStatusCount;
NSNTPStatusInfo* pStatus
Return value None if success. Error code if failure. Refer to the SmartLibrary Command Reference manual for error codes.
Example (TCL):#
# get status count
#
set status_count 0
CheckError NSNTPGetClientStatusCount status_count
OutMessage "status_count = $status_count"
#
# get status
#
if {$status_count > 0} {
Chapter 23: Using NTPProcedure to Use NTP
526 | SmartLibrary Overview and Procedures
struct_new z NSNTPStatusInfo*$status_count
CheckError NSNTPGetClientStatus $status_count z
for {set i 0} {$i < $status_count} {incr i} {
puts "$z($i.szName)=$z($i.szValue)"
}
unset z
}
Step 13 Get number of statuses of an NTP Peer.
Purpose This command returns the number of status variables of the requested NTP peer. Applications use this number to request the actual status information and pre-allocate memory for holding the status info.
Syntax int NSNTPGetPeerStatusCount(NSIPAddress* pIPAddress, unsigned long* ulNumStatusVariables);
Function NSNTPGetPeerStatusCount
Parameters The address of a peer and a pointer to a variable which will hold the number of status variables.
Return value None if success. Error code if failure. Refer to the SmartLibrary Command Reference manual for error codes.
Example (TCL):struct_new peer_addr NSIPAddress
set peer_addr(ucIPAddress) {10 2 1 8}
set status_count 0
CheckError NSNTPGetPeerStatusCount peer_addr status_count
OutMessage "status_count = $status_count"
unset peer_addr
Step 14 Get statuses of an NTP Peer.
Purpose This command returns the operational status of an NTP peer.
Syntax int NSNTPGetPeerStatus(NSIPAddress* pIPAddress, unsigned long ulNumStatusVariables, NSNTPStatusInfo* pStatus);
Function NSNTPGetPeerStatus
Parameters The address of an NTP peer, a number of status variables which applications are interested in and a pointer to a memory location to which the status information will be copied.
NSIPAddress* pIPAddress;
unsigned long ulNumStatusVariables;
NSNTPStatusInfo* pStatus
Return value None if success. Error code if failure. Refer to the SmartLibrary Command Reference manual for error codes.
Chapter 23: Using NTPProcedure to Use NTP
SmartLibrary Overview and Procedures | 527
Example (TCL)struct_new peer_addr NSIPAddress
set peer_addr(ucIPAddress) {10 2 1 8}
set status_count 0
CheckError NSNTPGetPeerStatusCount peer_addr status_count
OutMessage "status_count = $status_count"
#
# get status
#
if {$status_count > 0} {
struct_new z NSNTPStatusInfo*$status_count
CheckError NSNTPGetPeerStatus peer_addr $status_count z
for {set i 0} {$i < $status_count} {incr i} {
puts "$z($i.szName)=$z($i.szValue)"
}
unset z
}
unset peer_addr
Step 15 Get Peer List
Purpose The command returns a list of currently active NTP peers, by IP address. The order of the IP address has no significance to their importance to the NTP client.
Syntax int NSNTPGetPeerList(NSNTPPeerList* pNTPPeerList);
Function NSNTPGetPeerList
Parameters An address of a NSNTPPeerList variable to which the returned data will be copied.
#define MAX_NTP_PEERS 8
typedef struct tagNSIPAddress
{
unsigned char ucIPAddress[4];
} NSIPAddress;
typedef struct tagNSNTPPeerList {
unsigned long ulCount; /* number of peers */
NSIPAddress addrs[MAX_NTP_PEERS];
} NSNTPPeerList;
Return value None if success. Error code if failure. Refer to the SmartLibrary Command Reference manual for error codes.
#define MAX_NTP_PEERS 8
typedef struct tagNSIPAddress
{
Chapter 23: Using NTPProcedure to Use NTP
528 | SmartLibrary Overview and Procedures
unsigned char ucIPAddress[4];
} NSIPAddress;
typedef struct tagNSNTPPeerList {
unsigned long ulCount; /* number of peers */
NSIPAddress addrs[MAX_NTP_PEERS];
} NSNTPPeerList;
SmartLibrary Overview and Procedures | 529
Chapter 24
802.1x Supplicant Emulation
This chapter provides step-by-step procedures for setting up tests of 802.1x port-based network access control supplicant emulation.
In this chapter...
• Overview . . . . 530
• Set Up 802.1x Supplicant Emulation . . . . 533
Chapter 24: 802.1x Supplicant EmulationOverview
530 | SmartLibrary Overview and Procedures
OverviewThe 802.1x port-based network access control capability on SmartBits emulates up to 256 supplicant devices attempting authentication per physical port. The DUT is an authenticator switch or WLAN access point. A RADIUS server provides authentication approval. No authenticator or authentication server support is provided.
You can use 802.1x emulation to test any device that supports 802.1x authenticator protocols and the EAP authentication methods. This is usually a router, a switch, or a WLAN access point. The EAP protocol is terminated either at the device or at a RADIUS authentication server, when the device supports the RADIUS client protocol.
Figure 24-1 shows an example of the packet exchange and test scenario.
Figure 24-1. Typical 802.1x Protocol Exchange
Supplicant/Client Authenticator(DUT)
Port not authorizedEAP-Request/Identity
Time
EAP-Response/Identity
EAP-Request/MD5-Challenge
EAP-Response/MD5-Challenge
EAP-Success
EAP-Logoff
Port authorized
Port not authorized
RADIUS Server(Authentication Server)
RADIUS Access-Request
RADIUS Access-Challenge
RADIUS Access-Request
RADIUS Access-Accept
Chapter 24: 802.1x Supplicant EmulationOverview
SmartLibrary Overview and Procedures | 531
Module Support
802.1x port-based network access control supplicant emulation is supported on the following LAN TeraMetrics modules for the SmartBits 600/6000B/6000C chassis.
Applicable Commands
Table 24-1 is a summary of commands you can use in 802.1x supplicant emulation tests.
A basic setup See “Set Up 802.1x Supplicant Emulation” on page 533 for a basic setup procedure, as well as optional commands and actions, and how to retrieve results.
SmartBits Module Description
LAN-3306A 10/100Base-T Ethernet, Copper, 4-port, TeraMetrics XD
LAN-3320A 10/100/1000 Mbps and Gigabit Ethernet Fiber, 2-port, SmartMetrics XD
LAN-3321A 10/100/1000 Mbps and Gigabit Ethernet Fiber, 2-port, TeraMetrics XD
LAN-3324A 10/100/1000 Mbps and Gigabit Ethernet Fiber, 4-port, SmartMetrics XD
LAN-3325A 10/100/1000 Mbps and Gigabit Ethernet Fiber, 4-port, TeraMetrics XD
LAN-3327A 10/100/1000 Mbps and Gigabit Ethernet Fiber, 1-port, TeraMetrics XD
XLW-3720A 10GBase Ethernet XENPAK MSA, 1port, 2-slot, SmartMetrics
XLW-3721A 10GBase Ethernet XENPAK MSA, 1 port, 2-slot, TeraMetrics
XFP-3730A 10GBase Ethernet XFP MSA, 1port, 1-slot, SmartMetrics
XFP-3731A 10GBase Ethernet XFP MSA, 1 port, 1-slot, TeraMetrics
Table 24-1. Applicable Commands for 802.1x Supplicant Emulation Testing
Applicable Commands
What the Commands Do Original Function Message Function iType1/Notes
Reset module to the default state. HTResetPort —
Start the supplicant subprocess on the SmartBits module.
HTSetStructure NS_CREATE_SUBPROCESS
Delete all 802.1x supplicants and clear all supplicant and session statistics on the port.
HTSetCommand NS_DOT1X_SUPPLICANT_RESET
Port configuration for 802.1x supplicants.
HTSetStructure NS_DOT1X_SUPPLICANT_PORT_CONFIG
Chapter 24: 802.1x Supplicant EmulationOverview
532 | SmartLibrary Overview and Procedures
Retrieve port configuration for 802.1x supplicants.
HTGetStructure NS_DOT1X_SUPPLICANT_PORT_CONFIG_INFO
Configure one or more 802.1x supplicants.
HTSetStructure NS_DOT1X_SUPPLICANT_CONFIG
Retrieve the configuration of one or more supplicants. Use DOT1X_RETRIEVE_ALL as the iType3 (count) argument to retrieve the configurations of all the supplicants on the port.
HTGetStructure NS_DOT1X_SUPPLICANT_CONFIG_INFO
Copy the configuration of one 802.1x supplicant to other supplicants.
HTSetStructure NS_DOT1X_SUPPLICANT_COPY
Modify one or more 802.1x supplicants.
HTSetStructure NS_DOT1X_SUPPLICANT_MODIFY
Increment a single configuration parameter for one or more 802.1x supplicants.
HTSetStructure NS_DOT1X_SUPPLICANT_FILL
Perform an action on one or more 802.1x supplicants.
HTSetStructure NS_DOT1X_SUPPLICANT_CONTROL
Retrieve global supplicant statistics for a port.
HTGetStructure NS_DOT1X_SUPPLICANT_SESSION_STATS_INFO
Retrieve status information for one or more supplicants, including the following: 802.1x supplicant state, supplicant session state, failure code, session setup time, and number of retries.
HTGetStructure NS_DOT1X_SUPPLICANT_SUPPLICANT_STATUS_INFO
Retrieve statistics for one or more 802.1x supplicants.
HTGetStructure NS_DOT1X_SUPPLICANT_SUPPLICANT_STATS_INFO
Retrieve a particular field in the 802.1x supplicant status structure.
HTGetStructure NS_DOT1X_SUPPLICANT_SUPPLICANT_STATUS_SEARCH_INFO
Destroy the supplicant subprocess on the SmartBits module.
HTSetStructure NS_DESTROY_SUBPROCESS
Table 24-1. Applicable Commands for 802.1x Supplicant Emulation Testing (continued)
Applicable Commands
What the Commands Do Original Function Message Function iType1/Notes
Chapter 24: 802.1x Supplicant EmulationSet Up 802.1x Supplicant Emulation
SmartLibrary Overview and Procedures | 533
Set Up 802.1x Supplicant EmulationThe following steps give an example of how to set up a test with the SmartLibrary 802.1x message functions. Selected commands are shown, not all possible commands or actions.
Note: To run 802.1x supplicant emulation tests, the 802.1x stack daemon RPM must be on the SmartBits module.
Step 1 Reserve the port.
Step 1 Reset the port.
Step 2 Start the supplicant subprocess on the SmartBits module.
Tcl Example
The following Tcl example uses a configuration in the NSCreateSubprocess structure to create a supplicant subprocess.
struct_new subProcess NSCreateSubprocess struct_new ulSubHandle Ulong
set subProcess(ulUserID) 0 set subProcess(ulGroupID) 0 set subProcess(uiModuleID) 51968 set subProcess(ulSharedMemKey) 1684108910 set subProcess(ucCommand.0) [ConvertCtoI "d"] set subProcess(ucCommand.1) [ConvertCtoI "o"] set subProcess(ucCommand.2) [ConvertCtoI "t"] set subProcess(ucCommand.3) [ConvertCtoI "1"] set subProcess(ucCommand.4) [ConvertCtoI "x"] set subProcess(ucCommand.5) [ConvertCtoI "d"]
Use: with Message Function iType1 Description
HTSlotReserve — Reserve the module for use.
Use: with Message Function iType1 Description
HTResetPort — Reset the port.
Use: with Message Function iType1 Related Structure
HTSetStructure NS_CREATE_SUBPROCESS NSCreateSubprocess
Chapter 24: 802.1x Supplicant EmulationSet Up 802.1x Supplicant Emulation
534 | SmartLibrary Overview and Procedures
NS_CREATE_SUBPROCESS returns a handle for the created supplicant subprocess. Save the subprocess handle and use it to destroy the subprocess at the end of your test (see Step 16).
HTSetStructure $::NS_CREATE_SUBPROCESS 0 0 0 subProcess\ 0 $Hub $Slot $Port set ulSubHandle(ul) $subProcess(ulSubprocessHandle)
Step 3 Delete all supplicants and clear all supplicant and session statistics on the port.
Step 4 Configure the port for supplicant configuration.
For a port with the following configuration, supplicants are started as shown below:ulSessionSetupDelay = 12 msulSessionBurstSize = 3ucSessionControlMode = DOT1X_SESSION_CONTROL_EVEN_BURST
The total number of supplicants configured depends on the configuration you specify with NS_DOT1X_SUPPLICANT_CONFIG. In the example below the number of configured supplicants is 12.
Use: with Message Function iType1 Related Structure
HTSetCommand NS_DOT1X_SUPPLICANT_RESET None
Use: with Message Function iType1 Related Structure
HTSetStructure NS_DOT1X_SUPPLICANT_PORT_CONFIG NSDOT1XSupplicantPortConfig
3 supplicantsstarted
3 supplicantsstarted
3 supplicantsstarted
3 supplicantsstarted
0 12 ms 24 ms 36 ms 48 ms
Chapter 24: 802.1x Supplicant EmulationSet Up 802.1x Supplicant Emulation
SmartLibrary Overview and Procedures | 535
In the following example, 8 Supplicants are configured using NS_DOT1X_SUPPLICANT_CONFIG.
ulSessionSetupDelay = 12 msulSessionBurstSize = 0 (N/A)ucSessionControlMode = DOT1X_SESSION_CONTROL_VARIED_BURSTucSessionBurstNumSlots = 3uiSessionBurstSlots = 2, 5, 1
In the following example, 23 Supplicants are configured using NS_DOT1X_SUPPLICANT_CONFIG.
ulSessionSetupDelay = 6 msulSessionBurstSize = 0 (N/A)ucSessionControlMode = DOT1X_SESSION_CONTROL_VARIED_BURSTucSessionBurstNumSlots = 3uiSessionBurstSlots = 2, 5, 1,7
Step 5 (Optional) Retrieve supplicant port configuration.
Step 6 Configure supplicant.
Use ulIndex to indicate the starting index of the supplicant, and ulCount as the number of supplicants to create.
2 supplicantsstarted
5 supplicantsstarted
1 supplicantstarted
0 12 ms 24 ms 36 ms
2 supplicantsstarted
0 12 ms 30 ms 36 ms 42 ms
5 supplicantsstarted
1 supplicantstarted
7 supplicantsstarted
2 supplicantsstarted
5 supplicantsstarted
1 supplicantstarted
6 ms 12 ms 24 ms
Use: with Message Function iType1 Related Structure
HTGetStructure NS_DOT1X_SUPPLICANT_PORT_CONFIG_INFO NSDOT1XSupplicantPortConfig
Use: with Message Function iType1 Related Structure
HTSetStructure NS_DOT1X_SUPPLICANT_CONFIG NSDOT1XSupplicantConfig
Chapter 24: 802.1x Supplicant EmulationSet Up 802.1x Supplicant Emulation
536 | SmartLibrary Overview and Procedures
If ulIndex is 0 and ulCount is 5, 5 Supplicants will be created with the following indexes: 0, 1, 2, 3, and 4. The created supplicants will all have the same configuration. The supplicant index range is 0 – 255, and gaps in the supplicant index sequence are allowed.
Step 7 (Optional) Retrieve Supplicant Configuration.
Use the iType2 parameter as the starting index of the created supplicants, and the iType3 parameter as the count of supplicants for which to retrieve configurations. See the following Tcl example.
This example specifies that the index starts at 1, and that 5 supplicant configurations will be retrieved.
Step 8 (Optional) Copy from an existing supplicant and create additional supplicants.
Step 9 (Optional) Modify one or more supplicants.
Step 10 (Optional) Increment and change the configuration for one or more supplicants.
Use: with Message Function iType1 Related Structure
HTGetStructure NS_DOT1X_SUPPLICANT_CONFIG_INFO NSDOT1XSupplicantConfig
HTGetStructure $::NS_DOT1X_SUPPLICANT_CONFIG_INFO 1 5 0\ myNSDOT1XSupplicantConfig 0 $iHub $iSlot $iPort
iType2 iType3
Use: with Message Function iType1 Related Structure
HTSetStructure NS_DOT1X_SUPPLICANT_COPY NSDOT1XSupplicantCopy
Use: with Message Function iType1 Related Structure
HTSetStructure NS_DOT1X_SUPPLICANT_MODIFY NSDOT1XSupplicantModify
Use: with Message Function iType1 Related Structure
HTSetStructure NS_DOT1X_SUPPLICANT_FILL NSDOT1XSupplicantFill
Chapter 24: 802.1x Supplicant EmulationSet Up 802.1x Supplicant Emulation
SmartLibrary Overview and Procedures | 537
Step 11 Start supplicant.
Use DOT1X_SUPPLICANT_START as the value for the ulAction field.
Step 12 (Optional) Retrieve statistics from one or more supplicants.
Use the iType2 parameter as the starting index of supplicants and the iType3 parameter as the count of supplicants for which to retrieve statistics.
Step 13 (Optional) Retrieve supplicant status information.
Use the iType2 parameter as the starting index of supplicants, and the iType3 parameter as the count of supplicants for which to receive status information.
Step 14 (Optional) Retrieve global supplicant statistics for a port.
Step 15 (Optional) Return information for matching status information.
This command retrieves information for supplicants matching specified criteria.
Use: with Message Function iType1 Related Structure
HTSetStructure NS_DOT1X_SUPPLICANT_CONTROL NSDOT1XSupplicantControl
Use: with Message Function iType1 Related Structure
HTGetStructure NS_DOT1X_SUPPLICANT_STATS_INFO NSDOT1XSupplicantStatsInfo
Use: with Message Function iType1 Related Structure
HTGetStructure NS_DOT1X_SUPPLICANT_STATUS_INFO NSDOT1XSupplicantStatusInfo
Use: with Message Function iType1 Related Structure
HTGetStructure NS_DOT1X_SUPPLICANT_SESSION_STATS_INFO
NSDOT1XSupplicantSessionStatsInfo
Use: with Message Function iType1 Related Structure
HTGetStructure NS_DOT1X_SUPPLICANT_STATUS_SEARCH_INFO
NSDOT1XSupplicantStatusSearchInfo
Chapter 24: 802.1x Supplicant EmulationSet Up 802.1x Supplicant Emulation
538 | SmartLibrary Overview and Procedures
Step 16 Destroy supplicant subprocess on the module.
Use the returned handle of the supplicant subprocess (see Step 2) to identify the subprocess. See the following Tcl example.
HTSetStructure $::NS_DESTROY_SUBPROCESS 0 0 0 $ulSubHandle\ 0 $Hub $Slot $Port
Using Index and Count
All supplicants are referred to using an index whose range is 0 to 255. You usually specify a starting index, and then a count of how many consecutive supplicants from that starting index the command will apply to.
If there are gaps in the specified supplicant index range (from the starting index to the starting index + (count-1)), the command applies only to the existing supplicants with indexes in that range.
If count is too large, only supplicants with indexes up to 255 will have the command applied.
The description above applies to the following message functions:
• NS_DOT1X_SUPPLICANT_MODIFY
• NS_DOT1X_SUPPLICANT_FILL
• NS_DOT1X_SUPPLICANT_COPY
• NS_DOT1X_SUPPLICANT_CONTROL
• NS_DOT1X_SUPPLICANT_CONFIG_INFO
• NS_DOT1X_SUPPLICANT_STATS_INFO
• NS_DOT1X_SUPPLICANT_STATUS_INFO
• NS_DOT1X_SUPPLICANT_STATUS_SEARCH_INFO
For the following message functions, the index (including base and destination index) is checked. An error is returned if a supplicant with the specified index does not exist.
• NS_DOT1X_SUPPLICANT_MODIFY
• NS_DOT1X_SUPPLICANT_FILL
• NS_DOT1X_SUPPLICANT_COPY
For the following message functions, the index is not checked. An error is returned if no supplicant exists within range from the starting index to the starting index + (count-1).
Use: with Message Function iType1 Related Structure
HTSetStructure NS_DESTROY_SUBPROCESS ULong
Chapter 24: 802.1x Supplicant EmulationSet Up 802.1x Supplicant Emulation
SmartLibrary Overview and Procedures | 539
• NS_DOT1X_SUPPLICANT_CONFIG_INFO
• NS_DOT1X_SUPPLICANT_STATS_INFO
• NS_DOT1X_SUPPLICANT_STATUS_INFO
• NS_DOT1X_SUPPLICANT_STATUS_SEARCH_INFO
The message function NS_DOT1X_SUPPLICANT_CONTROL works on all supplicants within the range specified by the starting index to the starting index + (count-1). No error is returned if no supplicant exists within that range.
The same behavior applies to DOT1X_ALL. DOT1X_ALL can only be used for the following commands.
• NS_DOT1X_SUPPLICANT_CONTROL
• NS_DOT1X_SUPPLICANT_CONFIG_INFO
• NS_DOT1X_SUPPLICANT_STATS_INFO
• NS_DOT1X_SUPPLICANT_STATUS_INFO
• NS_DOT1X_SUPPLICANT_STATUS_SEARCH_INFO
Example 1Index = 0Count = 3
Supplicant Configuration:S0 S2 S3 S4
The command applies to the following supplicants:S0, S2
Example 2Index = 254Count = 50
Supplicant Configuration: S254 S255
The command applies to the following supplicants:S254, S255
Example 3Index = 1Count = 3
Supplicant Configuration:S0 S2 S252 S254 S255
Chapter 24: 802.1x Supplicant EmulationSet Up 802.1x Supplicant Emulation
540 | SmartLibrary Overview and Procedures
For the following messages, an error will be returned because there is no supplicant with starting index 1:
• NS_DOT1X_SUPPLICANT_MODIFY
• NS_DOT1X_SUPPLICANT_FILL
• NS_DOT1X_SUPPLICANT_COPY
For the following message functions, the message applies only on S2.
• NS_DOT1X_SUPPLICANT_CONTROL
• NS_DOT1X_SUPPLICANT_CONFIG_INFO
• NS_DOT1X_SUPPLICANT_STATS_INFO
• NS_DOT1X_SUPPLICANT_STATUS_INFO
• NS_DOT1X_SUPPLICANT_STATUS_SEARCH_INFO
Example 4Index = 1Count = 3
Supplicant Configuration:S0 S252 S254 S255
For the following message functions, an error will be returned because there is no supplicant with starting index 1.
• NS_DOT1X_SUPPLICANT_MODIFY
• NS_DOT1X_SUPPLICANT_FILL
• NS_DOT1X_SUPPLICANT_COPY
For NS_DOT1X_SUPPLICANT_CONTROL, no supplicant is applied and no error is returned.
For the following message functions, an error will be returned because there is no supplicant in the specified range:
• NS_DOT1X_SUPPLICANT_CONFIG_INFO
• NS_DOT1X_SUPPLICANT_STATS_INFO
• NS_DOT1X_SUPPLICANT_STATUS_INFO
• NS_DOT1X_SUPPLICANT_STATUS_SEARCH_INFO
Example 5Index = 300Count = 50
In this example, an error is returned because the starting index is out of range.
SmartLibrary Overview and Procedures | 541
Appendix A
Error Codes
When a function is not successful, an error code is returned instead of data. Error code values are always less than zero. They may be signed integers or signed long integers.
Error Value Definition Description
−1 UNSPECIFIED_ERROR An error condition was encountered but could not be identified. This will occur if the system experienced an error that does not fit into any of the above categories.
−2 PORT_NOT_LINKED An attempt to use a Programming Library function was made without an active link to the SmartBits.
−3 UNLINK_FAILED An attempt to unlink the SmartBits from the serial port failed. This could occur if the SmartBits is already unlinked from the port before the ETUnLink command is called.
−4 INCORRECT_MODE The attached SmartBits was put into a mode of operation where the attempted call to the library function was not applicable. For instance, you cannot access packet data unless the capture mode has been enabled.
−5 PARAMETER_RANGE An incorrect or invalid range was specified for a library function parameter. This may include ranges within structures whose pointers are passed as a parameter to the function.
−6 PACKET_NOT_AVAILABLE An attempt was made to access information from an indexed packet not currently in the capture buffer of the attached SmartBits.
−7 SERIAL_PORT_DATA No errors were detected on the serial port, but the data returned from it doesn't appear to be correct. This indicates a serial port with interference. Try reducing the baud rate by modifying the ETSetBaud() parameter.
Appendix A: Error Codes
542 | SmartLibrary Overview and Procedures
−8 ET1000_OUT_OF_SYNC The attached SmartBits is operating in a mode different from what was expected. Perform an ETUnLink command followed by Link.
−9 PACKET_NOT_FOUND An attempt was made to locate a packet within the SmartBits's capture buffer, but the packet contents could not be found and/or verified.
−10 FUNCTION_ABORT The user aborted a function before it could run to completion.
−11 ACTIVE_HUB_NOT_INITIALIZED An attempt to execute a command that requires a card was unsuccessful because the library failed to properly initialize the board. The library will always try to initialize the board if it hasn't been done so already, but for some reason, the initialization failed. This could indicate a failed card.
−12 ACTIVE_HUB_NOT_PRESENT An attempt to execute a command that requires a card was unsuccessful because the addressed port had no board installed in it.
−13 WRONG_HUB_CARD_TYPE An attempt to execute a command that requires a card was unsuccessful because the addressed port contained a Passive Hub board.
−14 MEMORY_ALLOCATION_ERROR An attempt to execute a command that requires a card was unsuccessful because the addressed port contained a Passive Hub board.
−15 UNSUPPORTED_INTERLEAVE Not currently implemented.
−16 PORT_ALREADY_LINKED The Programming Library supports one connection at a time to a SmartBits. An ETLink command was issued when an active link already exists.
−17 HUB_SLOT_PORT_UNAVAILBLE A request was made to perform an operation on a Hub/Slot/Port that does not exist in the current configuration.
−18 GROUP_HUB_SLOT_PORT_ERROR A request was made to create or perform an operation on a group with a Hub/Slot/Port that does not exist in the current configuration.
−19 REENTRANT_ERROR An attempt was made to call a Programming Library function while BackgroundProcessing was enabled, and the Programming Library was already performing a function.
Error Value Definition Description
Appendix A: Error Codes
SmartLibrary Overview and Procedures | 543
−20 DEVICE_NOT_FOUND_ERROR An attempt was made to address an attached device that could not be found [e.g. an MII transceiver].
−21 PORT_RELINK_REQUIRED The connection is down, but no disconnect action was taken by either side.
−22 DEVICE_NOT_READY Current use: Token Ring is down.
−23 GROUP_NOT_HOMOGENEOUS Not currently implemented. (Used only by undocumented commands).
−24 INVALID_GROUP_COMMAND Not currently implemented. (Used only by undocumented commands).
−25 ERROR_SMARTCARD_INIT_FAILED Unable to initialize card.
−26 SOCKET_FAILED Error in the socket connection for an Ethernet Link (PC to SmartBits).
−27 SOCKET_TIMEOUT Timeout on the socket connection for an Ethernet Link (PC to SmartBits).
−28 COMMAND_RESPONSE_ERROR Invalid command response received from SmartBits.
−29 CRC_ERROR CRC error in the data transfer.
−30 INVALID_LINK_PORT_TYPE An attempt was made to link a PC to a SmartBits chassis over a connection that is recognized as neither a normal Serial Comm Port nor a proper TCP/IP Socket Link. (This error message should not occur.)
−31 INVALID_SYNC_CONFIGURATION User attempted to perform a GPS sync action when the SmartBits is not set for GPS. Could indicate that GPS is not ready or that GPS is connected to Slave instead of Master.
−32 HIGH_DENSITY_CONTROLLER_ERROR The SmartBits chassis is reporting ar error. It has rejected the command.
−33 HIGH_DENSITY_CARD_ERROR A module is reporting an error and has rejected the command. Possible causes include: Invalid parameter values or a command that is not appropriate for the card’s current state.
−34 DATA_NOT_AVAILABLE An attempt was made to retrieve data from a card when no data of the intended type was available. An example would be when you attempt to retrieve histogram results from a Layer3 card when no histogram information has been accumulated yet.
Error Value Definition Description
Appendix A: Error Codes
544 | SmartLibrary Overview and Procedures
−35 UNSUPPORTED_PLATFORM The function is not available on the current platform. Currently this is used for HTDefaultStructure and related functions that are not available on 16-bit Windows platforms.
−36 FILE_IO_ERROR An error occurred in accessing a file. Currently this will occur when HTDefaultStructure or a related function is called and the defaults file is not found.
−37 MULTI_USER_CONFLICT The attempted action conflicted with another user of the same SmartBits. This will occur when a GPS sync start or stop is attempted shortly after another user also attempts a GPS sync action.
−38 INVALID_STRUCT_SIZE The size of the data structure being used with the Message Function call does not match the expected size of the corresponding library data structure for this Message Function.
−40 BANDWIDTH_EXCEEDED_ERROR The specified rate exceeds the port’s available bandwidth. This error can occur when using NSCalculateGap.
−41 NOT_MULTI_USER_CHASSIS The current chassis is not a multi-user chassis.
−42 NON_BLOCKING_RESPONSE_ERROR An error response was received for a non-blocking call. Call NSReportError or NSReportFirstError to get more detailed information about the error.
−43 GPS_NOT_CONNECTED No GPS unit is connected to the SmartBits chassis.
−44 GPS_NOT_READY The connected GPS unit is not ready.
−98 SERIAL_PORT_TIMEOUT The serial port timed out while waiting for a response from the SmartBits. This usually indicates a problem with the physical serial link.
−501 NSTCL_PARAMETER_TYPE This error will occur when a given parameter is not of the expected type, for example if a non-numeric argument is given when an integer is expected. This error often occurs when a "$" is missing in front of a variable name.
Error Value Definition Description
Appendix A: Error Codes
SmartLibrary Overview and Procedures | 545
−502 NSTCL_INVALID_MSG_FUNC An attempt to unlink the SmartBits from the serial port failed. The Tcl interface is unable to process a message function because it doesn’t recognize the given iType parameters as matching the accompanying data structure for the card at the specified location.
−503 NSTCL_PARAMETER_RANGE An invalid parameter was given, especially regarding the Tcl interface.
−504 NSTCL_STRUCT_NOT_DEFINED An improper structure type was used with a message function in the Tcl interface.
−505 NSTCL_INVALID_STRUCT_COUNT An invalid number of structures have been passed down to the library by the user from the TCL interface. This means that there is not sufficient space to fit the data returned from the card in the user structure.
−506 NSTCL_INVALID_STRUCT_SIZE The size of the structure that the user has passed to the library from the TCL interface is invalid. This means that there is not sufficient space to fit the data returned from the card into the user structure.
−1001 UNSUPPORTED_COMMAND The command is not supported by the card.
−1003 INVALID_TYPE1 The Message Function iType1 command passed to the Original Function (HTSetStructure, HTGetStructure or HTSetCommand) is invalid.
−1002 UPDATED_FIRMWARE_NEEDED The command requires a newer version of firmware than is currently installed in the card.
−1100 AN_LINK_NOT_NEGOTIATED The card has not negotiated a link with its link partner.
−1101 AN_NO_EXTENDED_CAPABILITY MII extended capability not supported.
−1102 AN_LINK_PARTNER_INCAPABLE Link partner incapable of autonegotiation.
−1103 AN_INVALID_MII_ADDRESS Invalid MII address.
−1104 AN_SETTINGS_NOT_VERIFIED Negotiation settings do not match intended.
Error Value Definition Description
546 | SmartLibrary Overview and Procedures
SmartLibrary Overview and Procedures | 547
Appendix B
Transmit Calculations for ATM-345xA(s) Modules
This appendix provides additional information on transmit calculations for ATM-345xA(s) TeraMetrics modules for the SmartBits 600x/6000x chassis.
Sizes, Encapsulations, Utilization1 Frame size includes all encapsulations, but not the 8-byte AAL5 trailer. This is similar
to trailing CRC in Ethernet.2 AT_ENCAP_TYPE_LLC_ROUTED, AT_ENCAP_TYPE_LLC_BRIDGED, and
AT_ENCAP_TYPE_VCMUX_ROUTED encapsulations produce 8, 10, and 2 bytes of header respectively. AT_ENCAP_TYPE_VCMUX_ROUTED encapsulation has no header overhead. These encapsulations are specified by ucEncapType in the ATVC structure.ATM Terametrics modules also support customized headers of all VC encapsulation types. When a custom header is enabled, the header length is the custom header length in the VC configuration (ucCustomHeaderLength in the ATVC structure).
3 Frame sizes that are not integral multiples of 48 will incur additional pad overhead.
For example, a frame size of 136 is split into 3 cells: 48 bytes in the 1st cell, 48 bytes in the 2nd cell, 40 bytes + 8 bytes trailer in the 3rd cell. In this case, there is no addi-tional overhead.
In contrast, a frame size of 100 is also split into 3 cells: 48 bytes in the 1st cell, 48 bytes in the 2nd cell, 4 bytes of data + 8 bytes of trailer + 36 bytes of pad in the 3rd cell.
4 A speed of OC3 represents a maximum cell rate of 353,207 cells per second:
OC3 link rate: 155,520,000 bits/s
After SONET overhead: 260 / 270 –> 155,520,000 * 260/270 = 149,760,000 bits/sConverting to bits per cell: 1/(8 * 53) –> 149,760,000/(8*53) = 353,207 cells per sec-ond.
5 Similarly, OC12 is about 1,412,830 cells per second.6 Comparing to Ethernet, this is the line rate for ATM. This is not the actual user data
bit rate, since we still have to transmit the AAL5 trailer, encapsulations, and the actual cell headers. This is analogous to having to transmit the checksum and MAC header in Ethernet frames, in addition to other Ethernet overhead such as preamble bits.
548 | SmartLibrary Overview and Procedures
Appendix B: Transmit Calculations for ATM-345xA(s) ModulesTransmit Modes, Burst Counts, Burst Gaps
In ATM, a 64-byte frame has eight bytes of trailer and eight bytes of encapsulation (for LLC/SNAP). Since this frame involves two cells, there are also 2*5=10 bytes of cell header overhead as well.
Transmit Modes, Burst Counts, Burst GapsATM-345xA(s) modules support the following transmit modes:
• Continuous (CONTINUOUS_PACKET_MODE)
• Single Burst (SINGLE_BURST_MODE)
• Multi Burst (MULTI_BURST_MODE)
• Continuous Multi Burst (CONTINUOUS_BURST_MODE)
The usual concept of “gap” is different with ATM-345xA(s) modules. Whereas gap is configured in units of milliseconds in SmartLibrary, in the hardware it is set up in number of cells. So gap is not “inter-frame gap,” but rather “inter-cell gap.”
Continuous transmit mode keeps transmitting with constant gap. The gap is determined by the frame rates of the streams. Burst count, multi-burst count, burst gap have no effect in this mode.
Single Burst transmit mode sends a burst of frames with constant gap. The gap is determined by the frame rates of the streams. Multi-burst count and burst gap have no effect in this mode.
Multi Burst transmit mode sends multiple bursts of frames. A burst gap (milliseconds) delay is inserted between the bursts (after converting into number of cells). Within each burst, the frames are transmitted according to the stream frame rate.
Continuous multi-burst transmit mode is the continuous version of multi-burst mode.
Transmit Calculations
The following factors affect utilization and transmit characteristics.
• Port – Speed (OC3 or OC12), number of VCs, VC interleave depth.
• VC – PCR, transmit mode, burst size, multi-burst size, burst gap, number of streams, VC/stream mapping.
• Stream – Frame size (this implicitly takes into account encapsulation), frame rate.
Appendix B: Transmit Calculations for ATM-345xA(s) ModulesTransmit Modes, Burst Counts, Burst Gaps
SmartLibrary Overview and Procedures | 549
Transmit Scenarios
Example 1 (Single Burst)
Port Speed : 0 (OC3)Number of VCs : 1Interleave Depth : 8191PCR : 100000Transmit Mode : SINGLE BURSTBurst Size : 10Stream 1 Frame Size : 88Stream 1 Frame Rate : 100
Sum of all VC PCRs (100000) is less than max cell rate of port (353207) = good.
Frame size 88 –> 96 bytes including trailer –> 2 cells –> @ 100 frames/s; this is 200 cells per second –> stream cell rate (200) is less than PCR of VC = good.
This configuration will transmit ten 88-byte frames at 100 frames per second, as seen below. Notice that the gap between the frames is roughly 10 ms.
Cnt: Len High, Low Tmstmp Delta ns StrID 0: 88 41, 2088260364 0 0 1: 88 41, 2098260164 9999800 0 2: 88 41, 2108259964 9999800 0 3: 88 41, 2118259764 9999800 0 4: 88 41, 2128259664 9999900 0 5: 88 41, 2138259464 9999800 0 6: 88 41, 2148259264 9999800 0 7: 88 41, 2158259064 9999800 0 8: 88 41, 2168258964 9999900 0 9: 88 41, 2178258764 9999800 0 89998400
If the test is repeated with speed set to OC12, similar results are obtained (see below). The “jitter” is because of the higher cell speeds and low frame rate (compared to the above case). If a higher frame rate is used, this jitter will be reduced.
Cnt: Len High, Low Tmstmp Delta ns StrID 0: 88 76, 3749743504 0 0 1: 88 76, 3759743204 9999700 0 2: 88 76, 3769743104 9999900 0 3: 88 76, 3779742904 9999800 0 4: 88 76, 3789743404 10000500 0 5: 88 76, 3799743204 9999800 0 6: 88 76, 3809743004 9999800 0 7: 88 76, 3825120704 15377700 0 8: 88 76, 3830121304 5000600 0 9: 88 76, 3840121104 9999800 0 90377600
550 | SmartLibrary Overview and Procedures
Appendix B: Transmit Calculations for ATM-345xA(s) ModulesTransmit Modes, Burst Counts, Burst Gaps
Example 2 (Multi Burst)
Port Speed : 0 (OC3)Number of VCs : 1Interleave Depth : 8191PCR : 100000Transmit Mode : MULTI BURSTMultiburst Count : 2Burst Size : 10Burst Gap : 10Stream 1 Frame Size : 88Stream 1 Frame Rate : 100
The resulting capture is shown below. Notice the extra 10ms gap after the 10th frame (first burst).
Cnt: Len High, Low Tmstmp Delta ns StrID 0: 88 18, 1269086372 0 0 1: 88 18, 1279086272 9999900 0 2: 88 18, 1289086072 9999800 0 3: 88 18, 1299085872 9999800 0 4: 88 18, 1309085672 9999800 0 5: 88 18, 1319085572 9999900 0 6: 88 18, 1329085372 9999800 0 7: 88 18, 1339085172 9999800 0 8: 88 18, 1349084972 9999800 0 9: 88 18, 1359084772 9999800 0 10: 88 18, 1379084472 19999700 0 11: 88 18, 1389084272 9999800 0 12: 88 18, 1399084072 9999800 0 13: 88 18, 1409083972 9999900 0 14: 88 18, 1419083772 9999800 0 15: 88 18, 1429083572 9999800 0 16: 88 18, 1439086172 10002600 0 17: 88 18, 1449085972 9999800 0 18: 88 18, 1459085772 9999800 0 19: 88 18, 1469085572 9999800 0 199999200
Appendix B: Transmit Calculations for ATM-345xA(s) ModulesTransmit Modes, Burst Counts, Burst Gaps
SmartLibrary Overview and Procedures | 551
Example 3 (Two Streams on One VC)
Port Speed : 0 (OC3)Number of VCs : 1Interleave Depth : 8191PCR : 100000Transmit Mode : SINGLE BURSTBurst Size : 10Stream 1 Frame Size : 88Stream 1 Frame Rate : 100Stream 2+ Frame Size: 88Stream 2+ Frame Rate: 100
In this case, the two streams both will have a frame rate of 100, effectively reducing the gap between frames to 5ms. Note the alternating stream IDs.
Cnt: Len High, Low Tmstmp Delta ns StrID 0: 88 57, 3732522828 0 0 1: 88 57, 3737522728 4999900 1 2: 88 57, 3742522628 4999900 0 3: 88 57, 3747522528 4999900 1 4: 88 57, 3752522428 4999900 0 5: 88 57, 3757522428 5000000 1 6: 88 57, 3762522328 4999900 0 7: 88 57, 3767522228 4999900 1 8: 88 57, 3772522128 4999900 0 9: 88 57, 3777522028 4999900 1 44999200
Example 4 (Two VCs, One Stream each)
Port Speed : 0 (OC3)Number of VCs : 2Interleave Depth : 8191VC 1 PCR : 100000VC 2+ PCR : 100000Transmit Mode : SINGLE BURSTBurst Size : 10Stream 1 Frame Size : 88Stream 1 Frame Rate : 100
See the capture below. The stream on the 2nd VC has a stream ID of 1000. Note that each VC has a burst size of 10 resulting in 20 frames. Also, each VC has its own independent gap, resulting in the port transmitting two frames back-to-back at a time.
552 | SmartLibrary Overview and Procedures
Appendix B: Transmit Calculations for ATM-345xA(s) ModulesTransmit Modes, Burst Counts, Burst Gaps
Cnt: Len High, Low Tmstmp Delta ns StrID 0: 88 62, 2943043648 0 0 1: 88 62, 2943049148 5500 1000 2: 88 62, 2953043448 9994300 0 3: 88 62, 2953046248 2800 1000 4: 88 62, 2963043348 9997100 0 5: 88 62, 2963046048 2700 1000 6: 88 62, 2973043148 9997100 0 7: 88 62, 2973045848 2700 1000 8: 88 62, 2983042948 9997100 0 9: 88 62, 2983045648 2700 1000 10: 88 62, 2993042748 9997100 0 11: 88 62, 2993045548 2800 1000 12: 88 62, 3003042548 9997000 0 13: 88 62, 3003045348 2800 1000 14: 88 62, 3013042448 9997100 0 15: 88 62, 3013045148 2700 1000 16: 88 62, 3023042248 9997100 0 17: 88 62, 3023044948 2700 1000 18: 88 62, 3033042048 9997100 0 19: 88 62, 3033044748 2700 1000 90001100
Continues –>
Appendix B: Transmit Calculations for ATM-345xA(s) ModulesTransmit Modes, Burst Counts, Burst Gaps
SmartLibrary Overview and Procedures | 553
Example 5 (Two Streams with Different Frame Sizes)
Port Speed : 0 (OC3)Number of VCs : 1Interleave Depth : 8191VC 1 PCR : 100000Transmit Mode : SINGLE BURSTBurst Size : 10Stream 1 Frame Size : 88Stream 1 Frame Rate : 100Stream 2+ Frame Size: 1000Stream 2+ Frame Rate: 100
See the capture below. Note the gap between the different size frames.
Cnt: Len High, Low Tmstmp Delta ns StrID 0: 88 42, 3170374068 0 0 1: 1000 42, 3179502168 9128100 1 2: 88 42, 3180373868 871700 0 3: 1000 42, 3189501968 9128100 1 4: 88 42, 3190373668 871700 0 5: 1000 42, 3199501868 9128200 1 6: 88 42, 3200373468 871600 0 7: 1000 42, 3209501668 9128200 1 8: 88 42, 3210373268 871600 0 9: 1000 42, 3219504168 9130900 1 49130100
554 | SmartLibrary Overview and Procedures
SmartLibrary Overview and Procedures | 555
Appendix C
Scheduler Technical Calculations
This appendix describes the method used to calculate the bandwidth utilization in the POS-35xx and LAN-3201B/C modules. Its intent is to provide readers with an understanding of how accurately these modules behave under certain load conditions. This description does not include the details of how the hardware operates.
In this appendix...
• About POS Wire Speed . . . . 556
• POS Frame Rate Calculation . . . . 557
• LAN-3201B/C Frame Rate Calculation . . . . 565
• Optimizing Utilization . . . . 571
Appendix C: Scheduler Technical CalculationsAbout POS Wire Speed
556 | SmartLibrary Overview and Procedures
About POS Wire SpeedWire speed for POS can best be defined as the ability to transmit frames onto the physical media with a single HDLC flag between each frame. In POS, a flag is the signalling device (Hex 7E; Binary 0111110) that denotes the end of a frame. If only one flag occurs between two PPP frames, then true wire rate is achieved.1 To better visualize this, look at Figure C-1, which uses larger than legal frame size to illustrate the case of an OC-12c SONET payload.
Figure C-1. Theoretical Calculation of Wire Speed
Stream #1
Wire speed = ( BytesPerSecond – NumberOfFlags )= ( 74,880,000 – 1)= 74,879,999 Bps
Stream #2
Actual payload capacity = ( 20,000,000 + 20,000,000 + 34,880,000 – 3) = 74,879,996 Bps
Therefore, wire rate varies according to frame size. For a stream with 3,000 frames, theoretical wire speed would be:
Wire speed = ( 74,880,000 – 3000)= 74,877,000 Bps
In practice, the number of actual flags that occur between two frames is a function of how the transmit byte clock is synchronized to the SONET clock. See “Optimizing Utilization” on page 571 for hints on optimizing.
1. See Table C-2, “Computing Requested Rate,” on page 559 for the wire speed values according to selected bandwidth.
Stream #1Flag 74,880,000 Byte payload
Stream #2Flag34,880,000 Bytes20,000,000 Bytes20,000,000 Bytes FlagFlag
Frame 2
Frame 1
Frame 1 Frame 3
Appendix C: Scheduler Technical CalculationsPOS Frame Rate Calculation
SmartLibrary Overview and Procedures | 557
POS Frame Rate CalculationThe POS-3500B/BS and POS-3502A/AS Modules operate at two speeds OC-3c and OC-12c. Each speed has been described independently for clarity. The OC-3c speed is 155.52 Mbps (Megabits per second) and likewise OC-12c speed is 622.08 Mbps.
POS OC-12 Payload Capacity Calculation
The OC-12c SONET framing structure consists of 1080 bytes–9 rows of 120 octets each. 40 of these octets are allocated to SONET overhead carrying SONET physical layer and error information. The OC-12c bit rate is 622.08 Mbps. Thus, the available payload capacity is:
Available payload capacity = ( ( 1040 / 1080 ) * 622.08 Mbps )= 599.04 Mbps= 74.88 MBps (MegaBytes per second)
The actual payload capacity is then calculated from the available payload capacity by factoring in the tolerance of the clock carrying the SONET data. The worst case tolerance allowed by the SONET specification occurs with Stratum-4 clock, with a minimum accuracy of 32 ppm. The actual payload capacity ranges using this value are:
Max. Actual payload capacity = ( 1 + 0.000032 ) * 74.88 MBps= 74.88239616 MBps
Min. Actual payload capacity = ( 1 – 0.000032 ) * 74.88 MBps= 74.87760384 MBps
POS OC-3c Payload Capacity Calculation
Similarly, the OC-3c payload capacity values are calculated here. The OC-3c bit rate is 155.52 Mbps. Thus, the available payload capacity is:
Available payload capacity = ( ( 1040 / 1080 ) * 155.52 Mbps )= 149.76 Mbps = 18.72 MBps
And, the range of actual payload capacity values are:
Max. Actual payload capacity = ( 1 + 0.000032 ) * 18.72 MBps= 18.72059904 MBps
Min. Actual payload capacity = ( 1 – 0.000032 ) * 18.72 MBps= 18.71940096 MBps
Appendix C: Scheduler Technical CalculationsPOS Frame Rate Calculation
558 | SmartLibrary Overview and Procedures
Payload Capacity Utilization
The payload capacity utilization is calculated on how frequently frames are generated. In other words, the higher the frame rate, the higher the payload capacity utilization. The maximum frame rate is achieved with the minimum inter-frame gap. In SONET, the minimum gap allowed is one byte. Thus, the maximum payload capacity utilization, measured in bytes per second for a given frame size is:
Max. Payload Capacity Utilization (Bps) = (max. frame rate) * (frame size + 1 (inter-frame gap) + CRC1)
Conversely, you can calculate the frame rate from the Payload Capacity Utilization as follows:
(Max. frame rate) = Max. Payload Capacity Utilization (Bps) / (frame size + 1 (inter-frame gap) + CRC)
Note: This calculation does not account for octet stuffing performed by the HDLC protocol layer. Octet stuffing is data dependent and the worst-case scenario may almost double the number of bytes sent, thereby reducing the capacity by half.
Capacity Utilization by Streams
In the POS-35xx modules, the frames are generated by individual streams. Each stream has its own frame generation definition and each stream utilizes part of the total payload capacity available. So, capacity utilization by any stream is:
Stream Capacity Utilization (Bps) = (stream frame rate) * (stream frame size + 1 (inter-frame gap) + CRC)
and
Aggregate Stream Capacity Utilization = sum of individual Stream Capacity Utilization
Even though streams are independent of each other, the Stream Capacity Utilization of one stream may affect the Stream Capacity Utilization of another stream, especially if the frames rates are different.
1. 2-byte or 4-byte CRC, depending on frame type.
Appendix C: Scheduler Technical CalculationsPOS Frame Rate Calculation
SmartLibrary Overview and Procedures | 559
Formula for Requested Rate
Formula: Requested Rate
Examples of Requested Rate
Table C-1. Bandwidth by Transmission Bit Rate*
* CRC either 4 bytes or 2 bytes.
BW_OC12 = 599.04x106 Bandwidth for OC-12 speed
BW_OC3 = 149.76x106 Bandwidth for OC-3 speed
Table C-2. Computing Requested Rate
Frame Length
Percent Utilization (%)
Bandwidth (Payload)
CRC(Bytes) Rate
60 100 OC-12c 4 1,152,000
60 100 OC-12c 2 1,188,571
60 100 OC-3c 4 288,000
60 100 OC-3c 2 297,142
RequestedRate
PercentUtilization( ) BandWidthOCx8
---------------------------------------------⎝ ⎠⎛ ⎞×
100---------------------------------------------------------------------------------------FrameLength CRC 1+ +
---------------------------------------------------------------------------------------------------------------------=
Appendix C: Scheduler Technical CalculationsPOS Frame Rate Calculation
560 | SmartLibrary Overview and Procedures
Algorithm for Calculated Rate (POS-35xx Modules)
The frame rates for the POS-35xx modules fall into four categories, each with an independent clock source. Table C-3 list s the frame rates and the corresponding clock source.1 Identify lowest Frame Rate for all streams.2 Identify Clock Rate based on lowest Frame Rate.
3 For each stream, calculate InterFrame Time:If decimal value > 0.5InterFrame Time = Truncate (LowestClockRate / ReqFrameRate)+1;ElseInterFrame Time = Truncate (LowestClockRate / ReqFrameRate);
4 For each stream, compute Calculated Rate:CalculatedRate = Truncate (LowestClockRate / InterFrame Time)
Table C-3. Frame Rate Related to Clock
Frame Rate (fps) Clock Rate (Hz)
>=239 31,250,000
>=120 15,625,000
>=60 7,812,500
>=31 3,906,250
Appendix C: Scheduler Technical CalculationsPOS Frame Rate Calculation
SmartLibrary Overview and Procedures | 561
Example of Calculated Rate
1 Identify lowest Frame Rate for all streams.
2 Identify Clock Rate based on lowest Frame Rate (Stream #6).lowest rate = 40 fps selected clock = 3,906,250
3 For each stream, compute InterFrame Time.Clock = Lowest Rate;Clock = 3,906,250
Stream 1 InterFrameTime = 3,906,250 / 100,000= 39.0625 Truncate= 39
Stream 5 InterFrameTime = 3,906,250 / 119= 32,825.63 Truncate= 32,825 + 1= 32,826
4 For each stream, compute Calculated Rate:
Stream 1 Req. Rate: 100,000 fps
CalculatedRate = 3,906,250 / 39= 100,160.25 Truncate
CalculatedRate = 100,160 fps
Stream 5 Req. Rate: 119 fps
CalculatedRate = 3,906,250 / 32,826= 118.99865 Truncate
CalculatedRate = 118 fps
Table C-4. Step 1: Identifying Lowest Frame Rate
Stream Requested Rate Calculated Rate Clock Assigned
1 100,000 / 31,250,000
2 50,000 / 31,250,000
3 25,000 / 31,250,000
4 239 / 15,625,000
5 119 / 7,812,500
6 40 / 3,906,250
7 60 / 7,812,500
Appendix C: Scheduler Technical CalculationsPOS Frame Rate Calculation
562 | SmartLibrary Overview and Procedures
More examples of Calculated Rates
As streams are disabled, the lowest available clock changes.
Table C-5. Step 4: For Each Stream, Compute Calculated Rate
Stream Enable Requested Rate Calculated Rate
1 ON 100,000 100,160
2 ON 50,000 50,080
3 ON 25,000 25,040
4 ON 239 239
5 ON 119 118
6*
* Selected clock based on Table C-4, “Step 1: Identifying Lowest Frame Rate,” on page 561.
ON 40 40
7 ON 60 60
Table C-6. One Stream Disabled
Stream Enable Requested Rate Calculated Rate
1 ON 100,000 100,160
2 ON 50,000 50,080
3 ON 25,000 25,040
4 ON 239 239
5 ON 119 118
6 OFF 40 –
7*
* Selected clock
ON 60 60
Appendix C: Scheduler Technical CalculationsPOS Frame Rate Calculation
SmartLibrary Overview and Procedures | 563
Table C-7. Two Streams Disabled
Stream Enable Requested Rate Calculated Rate
1 ON 100,000 100,160
2 ON 50,000 50,080
3 ON 25,000 25,040
4 ON 239 239
5*
* Selected clock
ON 119 119
6 OFF 40 –
7 OFF 60 –
Table C-8. Three Streams Disabled
Stream Enable Requested Rate Calculated Rate
1 ON 100,000 100,160
2 ON 50,000 50,000
3 ON 25,000 25,000
4*
* Selected clock
ON 239 239
5 OFF 119 –
6 OFF 40 –
7 OFF 60 –
Appendix C: Scheduler Technical CalculationsPOS Frame Rate Calculation
564 | SmartLibrary Overview and Procedures
Table C-9. Five Streams Disabled
Stream Enable Requested Rate Calculated Rate
1 ON 100,000 100,160
2*
* Selected clock
ON 50,000 50,000
3 OFF 25,000 –
4 OFF 239 –
5 OFF 119 –
6 OFF 40 –
7 OFF 60 –
Appendix C: Scheduler Technical CalculationsLAN-3201B/C Frame Rate Calculation
SmartLibrary Overview and Procedures | 565
LAN-3201B/C Frame Rate CalculationThe LAN-3201B/C module operates at 1000Mbps.
Payload Capacity Utilization
The payload capacity utilization is calculated on how frequently frames are generated. In other words, the higher the frame rate, the higher the payload capacity utilization. The maximum frame rate is achieved with the minimum inter-frame gap. In SmartMetrics Gigabit, the minimum gap allowed is 12-bytes and the preamble minimum is 8-bytes.
Thus, the maximum payload capacity utilization, measured in bytes per second for a given frame size is:
Max. Payload Capacity Utilization (Bps) = (max. frame rate) * (frame size + 12 (inter-frame gap) + 8 (minimum preamble) + 4 (CRC) )
Conversely, you can calculate the frame rate from the Payload Capacity Utilization as follows:
(Max. frame rate) = Max. Payload Capacity Utilization (Bps) / (frame size + 12 (inter-frame gap) + 8 (minimum preamble) + 4 (CRC) )
Capacity Utilization by Streams
In the LAN-3201B/C modules, the frames are generated by individual streams. Each stream has its own frame generation definition and each stream utilizes part of the total payload capacity available. So, capacity utilization by any stream is:
Stream Capacity Utilization (Bps) = (stream frame rate) * (frame size + 12 (inter-frame gap) + 8 (minimum preamble) + 4 (CRC) )
and
Aggregate Stream Capacity Utilization = sum of individual Stream Capacity Utilization
Even though streams are independent of each other, the Stream Capacity Utilization of one stream may affect the Stream Capacity Utilization of another stream, especially if the frames rates are different.
The frame rates for the LAN-3201B/C modules fall into four categories, each with an independent clock source. Table C-11 on page 567 lists the frame rates and the corresponding clock source.
Appendix C: Scheduler Technical CalculationsLAN-3201B/C Frame Rate Calculation
566 | SmartLibrary Overview and Procedures
Formula for Requested Rate
Formula: Requested Rate
Example of Requested Rate
Table C-10. Computing Maximum Allowed Rate*
* Calculated with the formula “Formula for Requested Rate” on page 566.
Frame Length
Percent Utilization (%)
Bandwidth (Payload)
CRC (Bytes) Rate
60 100 1000Mb 4 1,488,095
RequestedRate
PercentUtilization( ) BandWidth1000Mb8
------------------------------------------------------⎝ ⎠⎛ ⎞×
100----------------------------------------------------------------------------------------------FrameLength 4 CRC( ) 8 Preamble( ) 12 Gap( )+ + +---------------------------------------------------------------------------------------------------------------------------------------------=
Appendix C: Scheduler Technical CalculationsLAN-3201B/C Frame Rate Calculation
SmartLibrary Overview and Procedures | 567
Algorithm for Calculated Rate (LAN-3201B/C Module)
The frame rates for the LAN-3201B/C module fall into four categories, each with an independent clock source. Table C-11 list s the frame rates and the corresponding clock source.1 Identify lowest Frame Rate for all streams.2 Identify Clock Rate based on lowest Frame Rate.
3 For each stream, calculate InterFrame Time:If decimal value > 0.5InterFrame Time = Truncate (LowestClockRate / ReqFrameRate)+1;ElseInterFrame Time = Truncate (LowestClockRate / ReqFrameRate);
4 For each stream, compute Calculated Rate:CalculatedRate = Truncate (LowestClockRate / InterFrame Time)
Table C-11. Frame Rate Related to Clock
Frame Rate (fps) Clock Rate (Hz)
>=239 31,250,000
>=120 15,625,000
>=60 7,812,500
>=31 3,906,250
Appendix C: Scheduler Technical CalculationsLAN-3201B/C Frame Rate Calculation
568 | SmartLibrary Overview and Procedures
Example of Calculated Rate
1 Identify lowest Frame Rate for all streams.
2 Identify Clock Rate based on lowest Frame Rate (Stream #6).lowest rate = 40 fps selected clock = 3,906,250
3 For each stream, compute InterFrame Time.Clock = Lowest Rate;Clock = 3,906,250
Stream 1 InterFrameTime = 3,906,250 / 100,000= 39.0625 Truncate= 39
Stream 5 InterFrameTime = 3,906,250 / 119= 32,825.63 Truncate= 32,825 + 1= 32,826
4 For each stream, compute Calculated Rate:
Stream 1 Req. Rate: 100,000 fps
CalculatedRate = 3,906,250 / 39= 100,160.25 Truncate
CalculatedRate = 100,160 fps
Stream 5 Req. Rate: 119 fps
CalculatedRate = 3,906,250 / 32,826= 118.99865 Truncate
CalculatedRate = 118 fps
Table C-12. Step 1: Identifying Lowest Frame Rate
Stream Requested Rate Calculated Rate Clock Assigned
1 100,000 / 31,250,000
2 50,000 / 31,250,000
3 25,000 / 31,250,000
4 239 / 15,625,000
5 119 / 7,812,500
6 40 / 3,906,250
7 60 / 7,812,500
Appendix C: Scheduler Technical CalculationsLAN-3201B/C Frame Rate Calculation
SmartLibrary Overview and Procedures | 569
More Examples of Calculated Rates
As streams are disabled, the lowest available clock changes.
Table C-13. Step 4: For Each Stream, Calculate Requested Rate
Stream Enable Requested Rate Calculated Rate
1 ON 100,000 100,160
2 ON 50,000 50,080
3 ON 25,000 25,040
4 ON 239 239
5 ON 119 119
6*
* Selected clock based on Table C-12, “Step 1: Identifying Lowest Frame Rate,” on page 568.
ON 40 40
7 ON 60 60
Table C-14. One Stream Disabled
Stream Enable Requested Rate Calculated Rate
1 ON 100,000 100,160
2 ON 50,000 50,080
3 ON 25,000 25,040
4 ON 239 239
5 ON 119 119
6 OFF 40 –
7*
* Selected clock.
ON 60 60
Appendix C: Scheduler Technical CalculationsLAN-3201B/C Frame Rate Calculation
570 | SmartLibrary Overview and Procedures
Table C-15. Two Streams Disabled
Stream Enable Requested Rate Calculated Rate
1 ON 100,000 100,160
2 ON 50,000 50,080
3 ON 25,000 25,040
4 ON 239 239
5*
* Selected clock.
ON 119 119
6 OFF 40 –
7 OFF 60 –
Table C-16. Three Streams Disabled
Stream Enable Requested Rate Calculated Rate
1 ON 100,000 100,160
2 ON 50,000 50,000
3 ON 25,000 25,000
4*
* Selected clock.
ON 239 239
5 OFF 119 –
6 OFF 40 –
7 OFF 60 –
Appendix C: Scheduler Technical CalculationsOptimizing Utilization
SmartLibrary Overview and Procedures | 571
Optimizing Utilization• If you request full 100% utilization for one stream and this results in lower utilization
rate (e.g., 98.43751%), try using 10 streams each set to 10% utilization.
• Try changing the frame size. Some frame sizes allow for a higher utilization when using only a single stream.
Table C-17. Five Streams Disabled
Stream Enable Requested Rate Calculated Rate
1 ON 100,000 100,160
2*
* Selected clock.
ON 50,000 50,000
3 OFF 25,000 –
4 OFF 239 –
5 OFF 119 –
6 OFF 40 –
7 OFF 60 –
Table C-18. Calculated Rate
Frame Length (bytes) Requested Rate Calculated rate
40 100% 99.6965%
124 100% 98.1507%
1000 100% 99.9008%
572 | SmartLibrary Overview and Procedures
SmartLibrary Overview and Procedures | 573
Appendix D
Inhibit Clearing Latency Counters
The HGSetGroupBehavior command provides a way to inhibit the clearing of latencycounters. Latency counters normally are cleared whenever a Group start (HGStart), step (HGStep),or stop (HGStop) command is issued. In some cases it is recommended not to clear the counters during a Group command. In these situations, the clearing function is implemented by calling the “Timestamp-Initialization Sequence” commands just before HGStart. A Group start, step, or stop command then leaves the counter values intact and they are not cleared.
Note: To inhibit clearing of latency counters, call Timestamp-Initialization Sequence just before HGStart. A description of this sequence is given in the SmartLibrary Command Reference Volume 1.
Inhibit Clearing Latency Counters Procedure
Step 1 Load the required SmartLibrary files.
Step 2 Connect to the SmartBits chassis.
Step 3 Reserve ports
Step 4 Clear all counters
Step 5 Clear the group
Step 6 Add the transmitting and the receiving card to a group.
Use Description
HTResetPort Reset the card or module to a default state.
Use Description
HGClearGroup Clears group settings.
Use Description
HGAddtoGroup Add ports to the group.
Appendix D: Inhibit Clearing Latency Counters
574 | SmartLibrary Overview and Procedures
Step 7 Set up the transmit mode on the transmitting port.
Step 8 Set up the burst count on the transmitting port.
Step 9 With a POS module, set the gap on transmitting port.
Step 10 Set up duplex mode and speed, if necessary.
Step 11 Set up on the transmitting card as the Latency Transmitter and Receiver using
Step 12 HT_LATENCY_RXTX
Step 13 Set the receiving card as the Latency Receiver card using HT_LATENCY_RX
Step 14 Initialize the timestamp on all ports in the group using “Timestamp-Initialization Sequence” commands.
Use Description
HTTransmitMode Set the transmit mode: Single burst, multi-burst, or continuous.
Use Description
HTBurstCount Define number of packets per burst.
Use Description
HTGap Define the interpacket gap.
Use Description
HTDuplexMode Set half or full duplex mode.
HTSetSpeed Set the port speed.
Use Description
HTLatency Tests latency using SmartBits.
Use Description
HTLatency Tests latency using SmartBits.
Appendix D: Inhibit Clearing Latency Counters
SmartLibrary Overview and Procedures | 575
Note: Whenever the test involves latency-related measurements and the test involves a group, the timestamps on all ports in the group must be simultaneously initialized with Timestamp-Initialization Sequence. A description of this sequence is given in the SmartLibrary Command Reference Volume 1.
Step 15 Start transmitting
Step 16 Get latency counter information by using HT_LATENCY_REPORT
Step 17 Remove the latency measurement by using HT_LATENCY_OFF on thetransmitting and receiving card.
Step 18 Analyze the latency counters.
Use Description
HGStart Transmit test frames.
HGRun Run the test.
Use Description
HTLatency Tests latency using SmartBits.
Use Description
HTLatency Tests latency using SmartBits.
576 | SmartLibrary Overview and Procedures
SmartLibrary Overview and Procedures | 577
Symbols"documented/not documented" guidelines 14
Numerics10 Gigabit Ethernet
using the LAN-3710A 369802.1x
setting up supplicant emulation 529
Aalgorithm for calculated rate
LAN-3201B 567POS 560
Alternate Key 379alternate stream 63API 19ATM
card types 208connections 209enchanced stream indexes 209setting up PPP/ATM tests 224setting up PVC tests 213, 218setting up SVC tests 217setting up tests with TeraMetrics modules 237streams 209
Bburst 62burst counts 548burst gaps 548
CC/C++
code samples 157SmartLibrary interface 21
C/C++ developmentMS Windows 114UNIX 131
capacity utilization by streams (Gigabit) 565channelized WAN
setting up tests 260coding examples
C/C++ 157Tcl 134
controls 61custom frames
setting up in Fibre Channel 512
Ddefault values 89DHCP
setting up tests 397directory contents
MS Windows programming 110UNIX programming 130
document revision history 24
Eencapsulations 547error codes 541ET prefix 24Ethernet 10/100 Mbps
setting up tests 254extension (stream) 50
FFibre Channel
sending and receiving custom frames 512setting up tests 499
formula for requested rateLAN-3201B 566POS 559
fractional WANsetting up tests 283
frame rates 68frame size 62frame sizes 547
Ggap 61Gigabit Ethernet (GIG)
setting up tests 300using the LAN-3201B 385
HHDLC flag (hex 7E) 556header files 86HG prefix 24histograms 75how to
set up 10/100 Mbps Ethernet tests 254set up Alternate Key and Hashing
Algorithm 379set up ATM TeraMetrics tests 237set up basic 802.1x tests 529
Index
Index
578 | SmartLibrary Overview and Procedures
set up basic PVC tests 213, 218set up basic SVC tests 217set up Channelized WAN cards 260set up DHCP streams 397set up dynamic MPLS 491, 517set up Fibre Channel cards 499set up Fibre Channel custom frames 512set up fractional WAN cards 283set up Gigabit Ethernet 300set up IGMP 467set up IGMPv2 468set up IGMPv3 474set up IPv6 stream tests 343set up IPv6-over-IPv4 tunneling 363set up Multicast Listener Discovery 480, 485set up Neighbor Discovery for IPv6
streams 357set up POS 432, 441, 531set up PPP over Ethernet 408set up PPP over Frame Relay 290set up PPP over HDLC 280set up PPP/ATM tests 224set up SmartMetrics streams 310set up SmartMetrics tests with IPv6
streams 343set up SmartMetrics tests with TeraMetrics
modules 329set up SmartMetrics tests with the LAN-
3201B 385set up streams 319set up TeraMetrics tests 329set up the LAN-3710A 369set up the ML-5710A 393work with stream indexes 209
HT prefix 24hub/slot/port identification 94
Iidentifying hub/slot/port 94IGMP
setting up tests 467IGMP Version 2 (IGMPv2)
setting up tests 468IGMP Version 3 (IGMPv3)
setting up tests 474installation
MS Windows 108Tcl 36UNIX 127
Interframe Gap (IFG) valuessetting for the ML-5710A 395
IP socket connection to SmartBits 87IPv6-over-IPv4 tunneling
how to set up 363
LLayer 3 SmartMetrics (L3)
setting up streams 310
using the ML-5710A 393library files 86LibX 177
card numbering 181cards supported 178command format 181loading 179procedure defaults 188streams 199summary of procedures 204writing output to a file 189
link timeoutsavoiding 87SmartLibrary response 88
linking to SmartBits 87load 60load calculation 66loading library files 165
MML-5710A
setting Interframe Gap (IFG) values 395test setup 393
MLDv1 480MLDv2 485MPLS
setting up tests 491, 517MS Windows programming
directory contents 110installation 108
Multicast Listener Discovery version 1setting up tests 480
Multicast Listener Discovery version 2setting up tests 485
multi-user accessdefined 103functions 103
Nnative mode 97Neighbor Discovery 357NS prefix 24
PPacket Over Sonet (POS)
setting up tests 432, 441, 531port mapping modes
library functions 98native mode 97
POSalgorithm for calculated rate 560calculating OC-12 payload capacity 557calculating OC-3c payload capacity 557capacity utilization of streams 558formula for requested rate 559wire speed 556
PPP over Ethernet 408setting up tests 408
Index
SmartLibrary Overview and Procedures | 579
PPP over Frame Relaysetting up tests 290
PPP over HDLCsetting up tests 280
prefixes (in function names) 24programming
C/C++ in MS Windows 114C/C++ in UNIX 131general guidelines 86header files 86library files 86linking to SmartBits 87MS Windows, general notes 109Tcl in MS Windows 111Tcl in UNIX 131Visual Basic in MS Windows 112
Rrate 60, 68rate calculation 65ratio (in test traffic) 60readme.pdf file 24related documentation 14return values (error codes) 541RNDIS Mode 395
Ssample scripts
VB 159scheduler 64sequence tracking 76serial port
link timeouts 87link to SmartBits 87
setting up Layer 3 SmartMetrics streams 310setting up tests
802.1x 529ATM PVC 213, 218ATM SVC 217ATM TeraMetrics 237channelized WAN 260DHCP 397Ethernet 10/100 Mbps 254Fibre Channel 499for IPv6 streams 343for TeraMetrics modules 329for the LAN-3201B 385for the LAN-3710A 369fractional WAN 283Gigabit Ethernet (GIG) 300IGMP 467IGMPv2 468IGMPv3 474MPLS 491, 517Multicast Listener Discovery version 1 480Multicast Listener Discovery version 2 485Packet Over Sonet (POS) 432, 441, 531PPP over Ethernet 408
PPP over Frame Relay 290PPP over HDLC 280PPP/ATM 224
SmartLibrarydescribed 18firmware requirements 86key features 18library interfaces 21related documentation 14supported technologies 18Tcl setup 37
speed 62Spirent Communications
company address 15technical support 15
Spirent Connect 19start offset 73stream configuration commands
setting up streams 319stream extension 50stream order 63subscription (of card resources) 71synchronizing chassis or stacks 100
TTcl
how to use with SmartLibrary 163installing 36setting up SmartLibrary 37SmartLibrary interface 21Tcl shell 40
Tcl demo scripts 134all cards 135ATM 137, 147ATM TeraMetrics 148ET-1000 139Ethernet 140Fast Ethernet 140Gigabit 150Gigabit (GIG) 141Layer 3 142, 151LibX 145POS 145, 154SmartBits 600x/6000x 156Token Ring 145
Tcl developmentMS Windows 111UNIX 131
technical support 15test API 19traffic controls 61
burst 62frame size 62gap 61scheduler 64speed 62stream order 63VFD 63
Index
580 | SmartLibrary Overview and Procedures
transmit calculations 547encapsulations 547frame sizes 547utilization 547
transmit modes 548
UUNIX programming
directory contents 130installation 128versions tested 108, 128
Using the LAN-3201Btest setup 385
utilization 547
VVFD 63Visual Basic
development in MS Windows 112samples 159SmartLibrary interface 21