smartlibrary overview and procedures - oracle … overview and procedures | 9 procedures in this...

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

mailto:[email protected]

http://support.spirentcom.com


http://support.spirentcom.com.cn



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


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


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


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 –>



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



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”


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


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


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









http://www.spirentcom.com

http://www.spirentcom.com.cn


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?


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


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



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 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.



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


Application (API) Application (API)Application EngineApplication (API)

Firmware

C/C++ and Tcl – Spirent Connect

Chapter 1: Introducing SmartLibraryFrequently Asked Questions


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


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


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


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.”

http://www.netcomsystems.com


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


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


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


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


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



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”



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.



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 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.



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.



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).



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) • •



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



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.



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>.



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.



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


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.



• 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



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 /



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.



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.



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


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.


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


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


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


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


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



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.



• 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.


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


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)


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.



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.



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



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


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


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


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


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



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.*/



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.



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.



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 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 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



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


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?


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.



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



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).



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


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 ( )



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



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”


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”


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)


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


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).

http://www.netcomsystems.com

Chapter 6: General Programming InformationEstablishing a Link from the PC to SmartBits


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


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


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.



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.



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



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.



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


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


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



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



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



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);



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


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.



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



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.



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


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.



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)



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.


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


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


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


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


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


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


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


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++


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.


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++


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.


Chapter 7: Programming in MS WindowsCreating a Program with Microsoft Visual C++


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.



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.



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.



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.



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.



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.



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;



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);



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 {



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


txPackets = cs.TmtPkt;




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;

}


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


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


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


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++


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.


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


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.



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



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)




et1000_tcl/ATMCardThese scripts work with the ATM SmartCards.

Table 9-2. Example Scripts in the et1000_tcl/ATMCard Directory


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



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)




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


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



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


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


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



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)


Table 9-6. Example Scripts in the et1000_tcl/GIG Directory


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



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


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


HTGetStructure withNS_CAPTURE_COUNT_INFONS_CAPTURE_DATA_INFO



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.


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.




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



Table 9-7. Example Scripts in the et1000_tcl/Layer3 Directory (continued)




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.


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




Table 9-7. Example Scripts in the et1000_tcl/Layer3 Directory (continued)




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


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


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



Table 9-10. Example Scripts in the libx Directory


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.



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


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



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)


Table 9-12. Example Scripts in the smartlib_tcl/ATMTM Directory


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



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)




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)


Table 9-13. Example Scripts in the smartlib_tcl/GIG Directory


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



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


l2-l3.tcl Demonstrates the process of switching from Layer 2 to Layer 3 on an ML-7710 card.

HTGetStructure withNS_CAPTURE_DATA_INFO



l3_gw_mod_stream_array.tcl Sets up IP streams on a Layer 3 card, then modifies the 3rd gateway octet.



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.


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




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



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


l3_tcp.tcl Sets up a single stream on each of two cards.

HTSetCommand withNS_CAPTURE_STARTNS_CAPTURE_STOPL3_START_ARPS


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.


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)




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.




l3min.tcl Basic streams setup, transmit, and capture.


HTSetCommand withL3_START_ARPSNS_CAPTURE_STARTNS_CAPTURE_STOP


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.


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




smartlib_tcl/POSThese scripts illustrate how to work with selected Packet Over SONET (POS) modules, the POS-3500B and POS-3500BS.


l3trigger.tcl Demonstrates the use of triggers on Layer 3 cards.



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-15. Example Scripts in the smartlib_tcl/POS Directory


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



posbasic.tcl Sets up multiple IP streams. HTSetCommand withNS_CAPTURE_STARTNS_CAPTURE_STOP


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)




smartlib_tcl/SMB6000This script works with SmartBits 600x/6000x and 200/2000 systems.

Table 9-16. Example Scripts in the smartlib_tcl/SMB6000 Directory


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


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


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


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.



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.




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)




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)


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


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



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.



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.



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


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.”



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


Specify values without specifying a structure. Yes No

Tcl Interface


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.



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


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


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


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



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)

}}

}



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}}



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.


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


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.


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


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


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


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


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


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


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


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.



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).



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.



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


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]"



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



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


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:



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).



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.



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.



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


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


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


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.



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



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).



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


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


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


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


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


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


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



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 ""}



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


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_LINE

Check the line state. HTGetStructure Depending on card type:

ATM_DS1_E1_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



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


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



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


HTSetStructure ATM_FRAME_DEF ATMFrameDefinition


HTSetStructure ATM_STREAM_CONTROL ATMStreamControl


HTSetStructure ATM_STREAM_DETAIL_INFO ATMStreamDetailedStatus



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


HGSetGroupHGAddtoGroup

Define a group of SmartBits ports. Add ports to the group. You can control group ports by using the HG commands.




HGStart Transmit test frames.




HGStop Stop the test (if running continuous traffic rather than step or burst mode).



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.


HTGetStructure ATM_STREAM_VCC_INFO ATMStreamVCCInfo and

ATMStreamVCCIStatus


HTGetStructure ATM_STREAM_TRIGGER_INFO

ATMTriggerInfo

Chapter 12: ATM Testing – SmartBits 200/2000Set Up Basic SVC Tests – SmartBits 200/2000


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.


Table 12-3. Applicable Commands for ATM SVC Tests

Applicable Commands


Reset all streams. HTSetStructure ATM_STREAM_CONTROL

Set up line parameters. HTSetStructure Depending on card type:



ATM_LINE

Check the line state. HTGetStructure Depending on card type:



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 –>




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





HTSetStructure ATM_STREAM_CONTROL None


ATM CardUseOriginal Function


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



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)


HTSetStructure ATM_ILMI ATMILMIParams


HTSetStructure ATM_ILMI_REGISTER ATMILMIStaticParams


HTGetStructure ATM_ILMI_INFO ATMILMIInfo


HTSetStructure ATM_SSCOP ATMSSCOPParams



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.


HTSetStructure ATM_UNI ATMUNIParams


HTSetCommand ATM_SAAL_ESTABLISH None


HTGetStructure ATM_SAAL_INFO ATMSAALInfo


HTSetStructure ATM_STREAM ATMStream


HTSetStructure ATM_FRAME_DEF ATMFrameDefinition





Step 14 Confirm that a connection has been established.

Step 15 (Optional) Set triggers to filter for patterns in the payload.




For group start, use HGStart.


HTSetStructure ATM_STREAM_DETAIL_INFO ATMStreamDetailedStatus


HTSetStructure ATM_STREAM_TRIGGER_PARAMS

ATMConnTriggerParams











For group stop, use HGStop.


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.


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.




HGStop Stop the test (if running continuous traffic rather than step or burst mode).






HTSetCommand ATM_SAAL_RELEASE None



Step 4 Deregister the ATM address.


HTSetCommand ATM_ILMI_DEREGISTER None

Chapter 12: ATM Testing – SmartBits 200/2000Set Up Tests for PPP over ATM – SmartBits 200/2000


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



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 →



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.


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.


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


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.


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


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


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.



• 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;


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



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;


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


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


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



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




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


Applicable Commands




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


Applicable Commands





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.


WithMessage Function iType1 Description

HTSlotReserve N/A Reserve the module for use.


WithMessage Function iType1 Description

HTResetPort N/A Reset the port.



HTSetStructure AT_PORT_CONFIG ATPortConfig



HTSetStructure AT_VC_CREATE ATVC



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.


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



• 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.


HTSetStructure L3_DEFINE_STREAM_EXTENSION L3StreamExtension


HTSetStructure L3_DEFINE_MPLSL3_MOD_MPLS

NSMPLSListNSMPLSList


HTSetStructure L3_DEFINE_STREAM_BINDINGL3_MOD_STREAM_BINDING

L3StreamBinding



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.


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.


HTRunHGRun

N/A Transmit test frames.


HTSetCommand NS_CAPTURE_STOP Stop capture.



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


• STREAM_PROTOCOL_IP• STREAM_PROTOCOL_UDP• STREAM_PROTOCOL_TCP• STREAM_PROTOCOL_ICMP

ATM + ETH + IPv4

ucEncapTypeAT_ENCAP_TYPE_LLC_BRIDGED

ucProtocolTypeSTREAM_PROTOCOL_LLC_BRIDGED



ATM + MPLS + IPv4

ucEncapTypeAT_ENCAP_TYPE_VCMUX_MPLS

ucProtocolType


• STREAM_PROTOCOL_IP• STREAM_PROTOCOL_UDP• STREAM_PROTOCOL_TCP• STREAM_PROTOCOL_ICMP

iType1 Call to Insert MPLS Labels


• L3_DEFINE_MPLS• L3_MOD_MPLS

ATM + IPv6 ucEncapType


• AT_ENCAP_TYPE_VCMUX_ROUTED• AT_ENCAP_TYPE_LLC_ROUTED

ucProtocolType


• 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


• STREAM_PROTOCOL_IPV6• STREAM_PROTOCOL_UDP_IPV6• STREAM_PROTOCOL_TCP_IPV6• STREAM_PROTOCOL_ICMP_IPV6



iType1 call to insert MPLS labels


• 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


• 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.



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.


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


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



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.


HTGetStructure AT_VC_COUNTER_INFO ATVCCounterInfo

HTGetStructure AT_VC_CLIP_COUNTER_INFO ATVCCLIPCounterInfo


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


HTGetStructure L2_READ_COUNTERS L2StatsInfo

HTGetStructure L2_READ_RATES L2RateInfo

HTGetStructure ETH_EXTENDED_COUNTER_INFO ETHExtendedCounterInfo


HTSetStructure NS_CAPTURE_SETUP NSCaptureSetup



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_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).



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.


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.



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.



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.


HGSetGroup Define a group of SmartBits ports.

HGAddtoGroup Add ports to the group. You control grouped ports by using the HG commands.


HTSetCommand NS_HIST_START N/A


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.



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.


Chapter 13: ATM Testing – SmartBits 600x/6000xLatency Measurement Limitations


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


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.


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


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.


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 –>




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 –>


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)


Use: with Message Function iType1 Related Structure

HTSetCommand ETH_RESET_PORT None

ETH_CLEAR_PORT None



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


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




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.


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.”


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.


ETHEnhancedCounterInfo Get additional counter information.

ETH_LATENCY_INFO ETHLatencyInfo Get latency measurements.


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


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)


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).



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



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




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_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





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


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



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


HTSetStructure WN_DS3_LINE_CFG WNDS3LineCfg


HTSetStructure WN_T1E1_LINE_CFG WNT1E1LineCfg

WN-3441A and WN-3442A


HTSetStructure WN_T1E1_LINE_CFG WNT1E1LineCfg



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


HTSetStructure WN_CHANNEL_PHYS_CFG WNChannelPhysCfg


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


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.



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


HTSetStructure WN_LMI_CFG WNLMICfg

OptionalRelated commands include:HTSetStructure with WN_LMI_DEL(WNLMIDel) to delete an LMI.



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


HTSetStructure L3_MOD_IP_STREAM StreamIP

L3_MOD_UDP_STREAM StreamUDP

L3_MOD_SMARTBITS_STREAM StreamSmartBits

All Cards


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


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.



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


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


HTSetStructure WN_T1E1_LINE_CTRL WNT1E1LineCtrl


HTSetStructure WN_DS3_LINE_CTRL WNDS3LineCtrl



WN-3441A and WN-3442A: Enable the T1 or E1 line.


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


HTSetStructure WN_T1E1_LINE_CTRL WNT1E1LineCtrl

All Cards


HTSetCommand WN_COMMIT_CFG None

WN-3445A


HTGetStructure WN_DS3_LINE_STATUS WNDS3LineStatus

All Cards


HTGetStructure WN_T1E1_LINE_STATUS WNT1E1LineStatus



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.


Use the HTRun command to transmit test traffic from an individual card.

Use HGRun to start test traffic from a group of cards.


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


HTGetStructure WN_CHANNEL_STATUS WNChannelStatus

All Cards


HTClearPort None None



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


HTGetStructure WN_DS3_LINE_STATUS WNDS3LineStatus

WN_DS3_LINE_INFO WNDS3LineInfo

All Cards


HTGetStructure WN_T1E1_LINE_STATUS WNT1E1LineStatus


WNT1E1AlarmCounterInfo

All Cards


HTGetStructure WN_CHANNEL_STATUS WNChannelStatus

All Cards


HTGetStructure WN_PVC_STATUS WNPVCStatus

All Cards


HTGetStructure WN_LMI_INFO WNLMIInfo




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.


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.


Use the following commands to get counters from the test.

Port counters

DS3 alarms counters

T1/E1 alarms counters

All Cards


HTGetStructure WN_PORT_INFO WNPortInfo

WN-3445A


HTGetStructure WN_DS3_LINE_INFO WNDS3LineInfo

All Cards


HTGetStructure WN_T1E1_ALARM_COUNTER_INFO

WNT1E1AlarmCounterInfo



Channel counters

PVC counters

LMI counters

All Cards


HTGetStructure WN_CHANNEL_INFO WNChannelInfo

All Cards


HTGetStructure WN_PVC_INFO WNPVCInfo

All Cards


HTGetStructure WN_LMI_INFO WNLMIInfo




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




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

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_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.




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


HTGetStructure NS_CAPTURE_COUNT_INFO NSCaptureCountInfo

All Cards


HTGetStructure NS_CAPTURE_DATA_INFO NSCaptureDataInfo

All Cards


HTGetStructure L3_CAPTURE_DETAIL_INFO Layer3CaptureDetailinfo




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.



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.



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.


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


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




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.


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


HTSetStructure PPP_CONFIG PPPParamCfg

All Cards


HTSetStructure PPP_SET_CTRL PPPControlCfg

All Cards


HTGetStructure PPP_STATUS_INFO PPPStatusInfo



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


HTGetStructure PPP_STATS_INFO PPPStatsInfo

Chapter 15: WAN (Frame Relay) TestingSet Up Tests with Fractional WAN Cards


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)


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



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 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.


HTSetStructure FR_CARD_CFG FRCardCfg

FR_LINE FRLineCfg

FR_T1E1LINE FRT1E1LineCfg


HTSetStructure FR_SET_PROTO_STACK FRCardProtoCfgParmType

FR_LMI FRLMICfg



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:


HTSetCommand FR_PVC_DELETE_ALL None

FR_PVC FRPvcTableEntry

UNI Mode PVC Appears As

DCE New, Inactive

DTE Active

Disabled Configured


HTSetCommand FR_STREAM_DELETE_ALL None

HTSetStructure FR_DEFINE_<n>_STREAMS FRPvcStrmMapCfg



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



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.



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.


Chapter 15: WAN (Frame Relay) TestingSet Up Tests for PPP over Frame Relay


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


Table 15-4. Summary: How to Set Up PPP over Frame Relay Tests


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


HTSetStructure FR_SET_PROTO_STACK FRCardProtocolCfg



Chapter 15: WAN (Frame Relay) TestingSet Up Tests for PPP over Frame Relay


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.




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.


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


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.


Table 16-1. Applicable Commands for Fast Ethernet Tests

Applicable Commands


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


See “Example of Setup Steps” on page 295

Continues –>




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


Transmit test frames, then stop the test. HTRunHTStop


HGRunHGStepHGStop


Get test results. HTGetStructure ETH_COUNTER_INFO

ETH_FIND_MII_ADDR_INFO


ETH_LATENCY_INFO

FST_CAPTURE_COUNT_INFO

FST_CAPTURE_DATA_INFO

FST_CAPTURE_INFO

Table 16-1. Applicable Commands for Fast Ethernet Tests



HTSetCommand ETH_RESET_PORT None

ETH_CLEAR_PORT None



Step 2 Set up the test parameters

Use HTSetStructure with the iTypes below to specify the test parameters.



Step 4 Send test traffic, then stop the test




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.






HGRun/HGStep/HGStop




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.


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.


HTSetStructure ETH_COUNTER_INFO ETHCounterInfo Get counter information.


ETHEnhancedCounterInfo Get additional counter information.

ETH_LATENCY_INFO ETHLatencyInfo Get latency measurements.




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.



HTSetStructure FST_CAPTURE_PARAMS FSTCaptureParams


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.


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


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



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.



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


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



Transmit test frames, then stop the test.

HTRunHTStop


HGRunHGStepHGStop


Continues –>






Use HTResetPort to set the card to a known, default state.

Use HTClearPort to clear all counters.

Applicable Commands


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)



HTResetPort Reset the card or module to a default state.

HTClearPort Clear the port counters.



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.


Optionally, set up a port group.

Use HGSetGroup to define a port group.

Use HGAddtoGroup to add ports to a group.


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.


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.







Use HTRun or HGRun to run the test.



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.


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.


HTRun/HTStop Transmit test frames. Stop the test, if running continuous traffic rather than step or burst mode.

HGRun/HGStep/HGStop


HTGetStructure


GIG_COUNTER_INFO GIGCounterInfo Get counter information for the card or module.

GIG_STRUC_RATE _INFO GIGRateInfo Get rate information.




Use the following steps to set up data capture.


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.


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.)


HTSetStructure GIG_STRUC_CAPTURE _SETUP GIGCaptureSetup


HTSetStructure GIG_STRUC_CAPTURE _SETUP GIGCaptureSetup


HTGetStructure


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.



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.


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.


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


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.


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



Table 18-1. Applicable Commands: Ethernet SmartMetrics Streams

Applicable Commands


Reset card to the default state.

HTResetPort 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 port groups. HGSetGroupHGAddtoGroup


Specify other transmit parameters.

HTTransmitModeHTGapHTFillPatternHTBurstCountHTBurstGap



HTRunHTStop


HGRunHGStepHGStop


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





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.


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.







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)


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.


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>


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





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.



Step 6 Send Test Traffic, Stop Test Traffic


Use HTStop or HGStop to stop the test when run with continuous traffic.









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.


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.




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).






HTGetCounters Retrieve basic test counters, including frame counts and errors.














Capture Event. The CAPTURE_EVENTS element in NSCaptureSetup defines what frame types should be captured. Valid options for NSCaptureSetup(ulCaptureEvents) include:



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).













For SmartMetrics histograms results, specify the histogram type. All SmartMetrics cards and modules support the same histogram types.



NS_CAPTURE_DATA_INFO NSCaptureDataInfo

NS_CAPTURE_STATS_INFO NSCaptureStatsInfo


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.



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.


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.





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)


Chapter 18: SmartMetrics/TeraMetrics TestingUsing the New Stream Configuration Commands


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


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 —

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)





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 —



Modify a field for a block of streams.

HTSetStructure L3_MOD_STREAMS_ARRAY


— or —




—

Specify port transmit parameters.

HTSetStructure NS_PORT_TRANSMIT






Transmit test frames and then stop the test.

HTRunHTStop

HGStartHGStepHGStop




— 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






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



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.



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


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.



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.



HTSetStructure NS_HIST_LATENCY_DIST_PER_STREAM NSHistComboPerStream




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


HTSetCommand NS_CAPTURE_STOP None




Table 0-1.


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


HTGetStructure NS_HIST_SEQUENCE_PER_STREAM_INFO NSSequenceInfo

Sequence tracking histogram results.



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.


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


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


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



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. Applicable Commands: SmartMetrics Tests with LAN-33xxA Modules

Applicable Commands

What the Commands Do Use Original Function With Message Function iType1 / Comments



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.


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 –>



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


—or—

HTSetStructureHTSetStructureHTSetCommandHTSetCommandHTSetStructure

NS_HIST_COMBO_PER_STREAMNS_HIST_LATENCY_OVER_TIMENS_HIST_RAW_SIGNATURENS_HIST_SEQUENCE_PER_STREAMNS_HIST_LATENCY_DIST_PER_STREAM




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



Get histogram information.

—or—


Get captured data. HTGetStructure NS_CAPTURE_COUNT_INFONS_CAPTURE_DATA_INFO

Table 18-5. Applicable Commands: SmartMetrics Tests with LAN-33xxA Modules




Here is a more detailed description of the steps summarized above.


See the following:





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 – 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.


HTSetStructure NS_PHY_CONFIG NSPhyConfig


HTGetStructure NS_PHY_CONFIG_INFO NSPhyConfig



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.


HTGetLEDs Get the state of HTLED_LINKED, to ensure that the link is ready.





L3_DEFINE_MULTI_STREAM_EXTENSION

StreamExtension



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 –>


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



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).


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).



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.


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:



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 — —



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.



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.”


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.


HTSetCommand NS_CAPTURE_STOPNS_CAPTURE_START

Clear the buffer and start the capture.



HGRun/HGStep/HGStop



Step 13 Stop the capture, if selected.




HTSetCommand NS_CAPTURE_STOP Stop capture.










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.





Original Function Message Function iType1 Structure/Description

HTGetCounters — Retrieve basic test counters, including frame counts and errors.



















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.

















NS_HIST_LATENCY_OVER_TIME_INFO NSHistLatencyOverTimeInfo


NS_HIST_RAW_SIGNATURE_INFO NSHistRawSignatureInfo


NS_HIST_SEQUENCE_PER_STREAM_INFO NSSequenceInfo


NS_HIST_LATENCY_DIST_PER_STREAM_INFO NSHistLatencyDistPerStreamInfo


Chapter 18: SmartMetrics/TeraMetrics TestingTest with IPv6 Streams on TeraMetrics Modules


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


v



Applicable Commands



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


Applicable Commands

Use Original Function With Message Function iType1



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


HTSetStructure

—or—

HTScheduleMode

NS_PORT_TRANSMIT

—



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


—or—





Perform Neighbor Discovery. L3_START_ARPS See “Set Up IPv6 Neighbor Discovery” on page 357 for detailed information.


HGRunHGStep

For group start.





Get IPv6 counters and rates. HTGetStructure NS_IPV6_COUNTER_INFONS_IPV6_RATE_INFO


—or—



Table 18-7. Applicable Commands: SmartMetrics Tests with IPv6 Streams (continued)


Applicable Commands

Use Original Function With Message Function iType1




Here is a more detailed description of the steps summarized above.Step 1 Reset the Card and 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).







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



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.


HTSetStructure L3_DEFINE_MULTI_TCP_IPV6_STREAM StreamTCPIPv6

L3_DEFINE_MULTI_TCP_IPV6_STREAM_VLAN

StreamTCPIPv6VLAN


HTSetStructure L3_MOD_TCP_IPV6_STREAM StreamTCPIPv6

L3_MOD_TCP_IPV6_STREAM_VLAN StreamTCPIPv6VLAN


HTSetStructure L3_TX_IPV6_ADDRESS Layer3IPv6Address

HTGetStructure L3_TX_IPV6_ADDRESS_INFO Same




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.




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





HTSetStructure L3_TX_IPV6_PROTOCOL Layer3IPv6Protocol



Rate-based Traffic




















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.












HTSetStructure ETH_SET_SPEED ULong

HTSetSpeed — —



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.


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.


HTSetCommand L3_START_ARPS N/A











HGRun/HGStep/HGStop









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.






HTGetStructure NS_IPV6_COUNTER_INFO NSIPv6CounterInfo

HTGetStructure NS_IPV6_RATE_INFO NSIPv6RateInfo






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.

















Chapter 18: SmartMetrics/TeraMetrics TestingSet Up IPv6 Neighbor Discovery


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


A basic setup See “Example of Setup Steps” on page 358 for a setup procedure.

Table 18-8. Applicable Commands: Neighbor Discovery

Applicable Commands




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


Start data capture. HTSetCommand NS_CAPTURE_START




Here is a complete summary of the steps to set up Neighbor Discovery on TeraMetrics-based modules with IPv6 streams.


See the following:



Step 2 Reset the card


Applicable Commands



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)





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 –>


HTSetStructure NS_ARP_CONFIG NSARPConfig



L3_DEFINE_<n>_STREAM_EXTENSION StreamExtension


L3_DEFINE_MULTI_<n>_STREAM_EXTENSION

StreamExtension



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.



L3_DEFINE_IPV6_STREAM_VLAN StreamIPv6VLAN


L3_DEFINE_TCP_IPV6_STREAM_VLAN StreamTCPIPv6VLAN


L3_DEFINE_UDP_IPV6_STREAM_VLAN StreamUDPIPv6VLAN


HTSetStructure L3_SET_ARP_GAP ULong





Step 8 Start capture on the transmitting and receiving ports.

Use NS_CAPTURE_START to start the capture.

Step 9 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 –>


HTSetCommand NS_CAPTURE_START —




HTSetCommand L3_START_ARPS —


HTGetStructure NS_ARP_STATUS_INFO NSARPStatusInfo


HTSetCommand NS_CAPTURE_STOP —



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.


HTGetStructure NS_CAPTURE_COUNT_INFO NSCaptureCountInfo Find the number of frames in the capture buffer.


HTGetStructure NS_CAPTURE_DATA_INFO NSCaptureDataInfo Retrieve a captured frame from the capture buffer.




HTGetStructure NS_ARP_STATUS_INFO NSARPStatusInfo


HTSetCommand L3_ARP_UNRESOLVED —

Chapter 18: SmartMetrics/TeraMetrics TestingTest with IPv6 Over IPv4 Tunneled Streams


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. Applicable Commands: IPv6-over-IPv4 Tunneling

Applicable Commands

What the Commands DoUse Original Function With Message Function iType1




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






Here is a more detailed description of the steps summarized above.Step 1 Reset the Card


Step 2 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 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)







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.


HTSetStructure NS_DEFINE_IPV6_OVER_IPV4_TUNNELING NSIPv6OverIPv4Tunneling


HTSetStructure NS_MOD_IPV6_OVER_IPV4_TUNNELING NSIPv6OverIPv4Tunneling


HTSetStructure NS_DEFINE_MULTI_IPV6_OVER_IPV4_TUNNELING

NSIPv6OverIPv4Tunneling



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.


Use HTRun to run 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 –>


HTSetStructure

HTSetCommand

NS_CAPTURE_SETUP

NS_CAPTURE_START

NSCaptureSetup

—









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.


This completes the basic steps needed to transmit test traffic.


This section provides additional information about setting up capture.


Use the following steps to set up data capture.Step 1 Set up the capture parameters.
















Start the capture, then transmit test traffic. When appropriate, stop the capture.



















Chapter 18: SmartMetrics/TeraMetrics TestingSet Up Tests for LAN-3710A 10GbE Modules


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.


Table 18-10.Applicable Commands: 10Gb Ethernet (LAN-3710A)

Applicable Commands




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


(Optional) Set up triggers. HTSetStructure GIG_STRUC_TRIGGER





HGRunHGStep

For group start.







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





Get captured data. HTGetStructure NS_CAPTURE_COUNT_INFONS_CAPTURE_DATA_INFONS_CAPTURE_STATS_INFO

Table 18-10.Applicable Commands: 10Gb Ethernet (LAN-3710A)







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:


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



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


HTSetStructure NS_STREAM_SCHEDULE NSStreamScheduleEntry


HTSetStructure GIG_STRUC_TRIGGER GIGTrigger Define trigger data and mask on the receiving port.



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.


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.


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





HGRun/HGStep/HGStop



Step 8 Stop the Test


Step 9 Stop capture (if selected).

Use NS_CAPTURE_STOP to stop data capture, if enabled.




HTStop/HGStop Stop the test, if running continuous traffic rather than step or burst mode.






You can specify data capture in place of histogram results.

Step 1 Set up the capture mode, length, and event.



Capture Events. The CAPTURE_EVENTS element in NSCaptureSetup defines what frame types should be captured. Valid options include the following:

















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.


After the test completes, use the following commands to get your capture results.



NS_CAPTURE_STOP —


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.









When SmartMetrics results are desired, you must set up a port group, since histogram results require a group start.





HTSetStructure NS_HIST_RAW_SIGNATURE Signature information only, showing transmit time, receive time, and delta in microseconds.





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


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


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




Configure the ARP mode. HTSetStructure NS_ARP_CONFIG



How to Set Up Alternate Key

Here is a complete summary of the steps to set up Alternate Key and Hashing Algorithm.


See the following:



Applicable Commands


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




Start Neighbor Discovery and ARPs.

HTSetCommand L3_START_ARPS


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)





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 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.




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.






StreamExtension



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.


HTSetStructure L3_DEFINE_<n>_STREAM_EXTENSION StreamExtension


HTDuplexMode Set half or full duplex mode.

HTSpeed Set the port speed.


HTSetStructure L3_DEFINE_VFD NSVFD




HTSetStructure NS_HIST_LATENCY_OPTION NSHistLatencyOption



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.


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.


HTSetStructure NS_TRIGGER_CONFIG NSTrigger


HTSetStructure NS_ALTERNATE_KEY_CONFIG NSAlternateKeyConfig


HTSetStructure NS_ALTERNATE_KEY_HASH_CONFIG NSAlternateKeyHashConfig



HGAddtoGroup Add ports to the group. Control grouped ports by using the HG commands.



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.


HTRun/HGRun Transmit test frames.


HTGetStructure L3_HIST_ACTIVE_TEST_INFO Layer3HistActiveTest

OriginalFunction Message Function iType1 Related Structure


Chapter 18: SmartMetrics/TeraMetrics TestingSet Up SmartMetrics Tests with the LAN-3201B/C


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.


Table 18-13.Applicable Commands: SmartMetrics Tests with LAN-3201B/C

Applicable Commands




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.



—or—






HGRunHGStep

For group start.







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


Start data capture (if selected). HTSetCommand NS_CAPTURE_STOPNS_CAPTURE_STARTNS_CAPTURE_STOP


See “Example of Setup Steps” below.


—or—



Table 18-13.Applicable Commands: SmartMetrics Tests with LAN-3201B/C (continued)







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.


Use HGSetGroup to define the port group and HGAddtoGroup to add ports to a group.


Use HTRun or HGRun (or HGStep) to send test traffic.


Step 5 Stop Test Traffic

Use HTStop or HGStop to stop the test (if run with continuous traffic).






StreamExtension

















NS_HIST_LATENCY_OVER_TIME NSHistLatencyOverTime


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


Chapter 18: SmartMetrics/TeraMetrics TestingSet Up Tests with the ML-5710A


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.



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] "

}



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








10000 1.0 millisecond

20000 2.0 millisecond

50000 5.0 milliseconds

100000 10.0 milliseconds



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


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



Applicable Commands

Table 18-14 is a summary of commands that may be used. Not all commands are required. This list is an overview.


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


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 –>





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


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)


HTSetStructure L3_DHCP_CONFIG Layer3DHCPConfig



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.


HTGetStructure L3_DHCP_CONFIG_INFO Layer3DHCPConfig


HTSetCommand L3_DHCP_GET_ADDRESS

L3_DHCP_GET_ADDRESS_ALL

None


HTGetStructure L3_DHCP_STREAM_COUNT_INFO ULong


HTGetStructure L3_DHCP_STATS_INFO Layer3DHCPStatsInfo

HTGetStructure L3_DHCP_HOST_INFO Layer3DHCPHostInfo

HTGetStructure L3_DHCP_EXTENDED_HOST_INFO Layer3DHCPExtendedHostInfo



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


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


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.



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.



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.



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.


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



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:




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.


Chapter 18: SmartMetrics/TeraMetrics TestingSet Up PPP Over Ethernet (PPPoE)


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


Configure streams. 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)


Tear down the PPP sessions. HTSetStructure PPP_SET_CTRL





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.


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.




OptionalYou can use HTGetStructure with PPP_CONFIG_INFO to review the PPP configuration.





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 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.


HTGetStructure PPP_STATUS_INFO PPPStatusInfo

HTGetStructure PPP_STATS_INFO PPPStatsInfo

HTSetCommand PPP_STATS_RESET —



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.



HTSetStructure PPP_STATS_INFO PPPStatsInfo

HTSetCommand PPP_STATS_RESET —

Chapter 18: SmartMetrics/TeraMetrics TestingGetting Real-Time Statistics with LAN TeraMetrics


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





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



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




HTResetPort —







NSCreateStream —


NSCopyStream —




















NSCopyTxConfig —




NSUpdateVFD —








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)





Clear previous histogram records and restart the histogram test.

HTSetCommand NS_HIST_START


—




HTRunHTStop

HGStartHGStepHGStop



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)






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.






Use Description



Use Description


Use Description


Use Description


Use Description





Step 7 (optional) Configure VFD1 and VFD2 settings.






Use Description


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


Use Description






Use Description





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 16 Retrieve the stream IDs being tracked on the receiving port.

Step 17 Retrieve the jumbo histogram results.




HTSetStructure NS_HIST_LATENCY_OPTION NSHistLatencyOption


HTSetCommand NS_HIST_START —

Use Description

HGStart Start transmission of packets


HTGetStructure NS_STREAM_ID_TABLE_INFO NSStreamIDTableInfo






Step 19 (optional) Delete all streams in the stream configuration object.




This completes the steps needed to run a simple test where real-time statistics are retrieved.

Use Description


Use Description


Use Description


Use Description



Chapter 18: SmartMetrics/TeraMetrics TestingGetting Enhanced Real-Time Statistics with TeraMetrics XD/XFP/XLW Modules


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.



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.







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



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




HTResetPort —







NSCreateStream —


NSCopyStream —




















NSCopyTxConfig —




NSUpdateVFD —








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)





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)






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.




This is an Enhanced Real-time Statistics Command (Required)



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


(Required)




HTRunHTStop

HGStartHGStepHGStop

For single-port start/stop. (Required)

For group start/stop. (Required)




This is an Enhanced Real-time Statistics Command (Optional)




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)








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.







Use Description



Use Description


Use Description


Use Description


Use Description


Use Description


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.



Step 7 (optional) Configure VFD1 and VFD2 settings.






Step 12 Set up a jumbo histogram test.

Step 13 (Optional) Set up Alternate Key.

Use Description


Use Description






Use Description






HTSetStructure NS_ALTERNATE_KEY_COMFIG NSAlternateKey Config



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 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..


HTSetStructure NS_ALTERNATE_KEY_HASH_CONFIG

NSAlternateKeyHashConfig


HTSetCommand NS_HIST_START —


HTSetStructure NS_RUNTIME_HIST_STATS_CONFIG

NSRunTimeHistStatsConfig


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.




Step 21 (Optional) Retrieve the jumbo histogram results.

Step 22 (optional) Delete all streams in the stream configuration object.




This completes the steps needed to run a simple test where real-time statistics are retrieved.

Use Description



HTGetStructure NS_HIST_COMBO_PER_STREAM_INFO

NSHistComboPerStreamInfo

Use Description


Use Description


Use Description




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


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.


Table 19-1. Applicable Commands for POS Tests using the POS-3500B/BS Module

Applicable Commands


Reset card to the default state. HTResetPort —

Clear counters. HTClearPort —


Configure the POS port. HTSetStructure POS_CARD_LINE_CONFIGPOS_CARD_PORT_ENCAPPOS_CONFIG

HTSetCommand POS_SET_SPEED


—

Set up SmartMetrics histogram results.

HTSetStructure NS_HIST_COMBO_PER_STREAM



—or— —or—



HTRunHTStop


HGRunHGStepHGStop


Get test counters. HTGetStructure L2_READ_COUNTERSL2_READ_RATES


—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





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.






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.



HTResetPort — None







StreamExtension



Step 3 Configure the POS Port

Configure the POS line parameters, encapsulation type, and port speed.






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


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.










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.



L2_READ_RATES L2RateInfo




Use the following steps to set up data capture.Step 1 Set up the capture parameters.


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:


















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.





HTSetCommand NS_HIST_COMBO_PER_STREAM NSHistComboPerStream











After the test runs, gather the latency-per-stream histogram information. Use HTGetStructure with NS_HIST_COMBO_PER_STREAM_INFO.




Chapter 19: Packet Over SONET TestingSet Up Tests with POS-3519As/Ar and 3518As/Ar Modules


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.


Table 19-2. Applicable Commands: POS Tests Using POS-3519As/3518As Modules

Applicable Commands



Clear counters. HTClearPort See“Example of Setup Steps” on page 443.



HTSetStructure

—or—

HTScheduleMode

NS_PORT_TRANSMIT

—

Configure the POS port. HTSetStructure POS_CARD_LINE_CONFIGPOS_CARD_PORT_ENCAPPOS_CONFIGNS_HW_CONFIG



—or—




Continues –>



Applicable Commands






HGRunHGStep

For group start.




Get counters and rates. HTGetStructure L2_READ_COUNTERSL2_READ_RATES


— or —

HTGetStructure

— or —



Table 19-2. Applicable Commands: POS Tests Using POS-3519As/3518As Modules




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.




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).










StreamExtension




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.




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.


Gap-based Traffic




Rate-based Traffic







Option 2: Use HTScheduleModeOption 1 Use NS_PORT_TRANSMIT (Message Function)




Continues –>



























NS_HW_CONFIG Set up other port characteristics (timestamp, laser enable).












HGRun/HGStep/HGStop









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.



L2_READ_RATES L2RateInfo








Capture Events. The CAPTURE_EVENTS element in Layer3CaptureSetup defines what frame types should be captured. Valid options include the following:














Capture Length. Valid options for Layer3CaptureSetup(ulCaptureLength) include:


Use NS_CAPTURE_START and NS_CAPTURE_STOP to start and stop the capture.


Use the following commands to get your capture results.







NS_CAPTURE_STOP —







Histograms provide in-depth test results, including sequence and latency information. This information is gathered on the receiving card.































NS_HIST_SEQUENCE_PER_STREAM_INFO Sequence Tracking histogram results.



Chapter 19: Packet Over SONET TestingTest with IPv6 Streams on POS TeraMetrics Modules


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



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.


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



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)


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


HTSetStructure

—or—

HTScheduleMode

NS_PORT_TRANSMIT

—

Continued-->



Applicable Commands


Configure the POS port. HTSetStructure POS_CARD_LINE_CONFIGPOS_CARD_PORT_ENCAPPOS_CONFIGNS_HW_CONFIG



—or—








HGRunHGStep

For group start.




Get IPv6 counters. HTGetStructure NS_IPV6_COUNTER_INFONS_IPV6_RATE_INFO


— or —

HTGetStructure

— or —



Table 19-3. Applicable Commands: POS Tests with IPv6 Streams (continued)




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 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).












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 –>


HTSetStructure L3_DEFINE_MULTI_IPV6_STREAM StreamIPv6

L3_DEFINE_MULTI_TCP_IPV6_STREAM StreamIPv6VLAN


HTSetStructure L3_MOD_IPV6_STREAM StreamIPv6



HTGetStructure L3_TX_IPV6_ADDRESS_INFO Same


HTSetStructure L3_TX_IPV6_PROTOCOL Layer3IPv6Protocol




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.




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.


Gap-based Traffic




Rate-based Traffic












Continues –>



























NS_HW_CONFIG Set up other port characteristics (timestamp, laser enable).




Step 4 Start capture, if selected.

Use NS_CAPTURE_START to start data capture, when desired.



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.”



Step 6 Stop capture (if selected).

Use NS_CAPTURE_STOP to stop data capture, if enabled.







HGRun/HGStep/HGStop











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.


HTGetStructure NS_IPV6_COUNTER_INFO NSIPv6CounterInfo

HTGetStructure NS_IPV6_RATE_INFO NSIPv6RateInfo








Capture Events. The CAPTURE_EVENTS element in Layer3CaptureSetup defines what frame types should be captured. Valid options include the following:














Capture Length. Valid options for Layer3CaptureSetup(ulCaptureLength) include:


Before sending test traffic, use NS_CAPTURE_START to start capture.

When the test is done, use NS_CAPTURE_STOP to stop the capture.


Use the following commands to get your capture results.







NS_CAPTURE_STOP —












When SmartMetrics results are desired, you must set up a port group, since histogram results require a group start.




























NS_HIST_SEQUENCE_PER_STREAM_INFO Sequence Tracking histogram results.




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


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





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 –>



Applicable Commands


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.






Step 1 Reset the Card





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.









L3_DEFINE_MULTI_STREAM_EXTENSION StreamExtension


HTSetCommand NS_IGMP_RESET None



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.


HTSetLayer3SetAddress — Layer3Address


HTSetStructure NS_IGMP_CONFIG NSIGMPConfig



HTSetCommand NS_CAPTURE_START None



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 –>


HTSetStructure NS_IGMPV2_JOIN

Earlier form: NS_IGMP_JOIN

NSIGMPv2GroupID

NSIGMPAddress

VLAN Ethernet Only: NS_IGMP_JOIN_VLAN NSIGMPAddressVLAN


HTSetCommand NS_CAPTURE_START None




HTSetStructure NS_IGMPV2_LEAVE

Earlier form: NS_IGMP_LEAVE

NSIGMPv2GroupID

NSIGMPAddress



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.


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.


HTGetStructure NS_IGMPV2_INFO NSIGMPv2Info


HTGetStructure NS_IGMPV2_ALL_INFO NSIGMPv2Info



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 Commands






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.











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.









L3_DEFINE_MULTI_<n>_STREAM_EXTENSION StreamExtension


HTSetCommand NS_IGMP_RESET None



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.


HTSetStructure NS_IGMPV3_CONFIG NSIGMPv3Config


HTSetStructure NS_IGMPV3_GROUP_MOD NSIGMPv3GroupMod


HTGetStructure NS_IGMPV3_GROUP_INFO NSIGMPv3GroupInfo


HTGetStructure NS_IGMPV3_STATS_INFO NSIGMPv3StatsInfo


HTGetStructure NS_IGMPV3_ALL_GROUP_INFO NSIGMPv3GroupInfo



Step 10 Leave Groups

Use HTSetCommand with NS_IGMPV3_LEAVE_ALL to leave all multicast groups.


This completes the basic steps needed to test with IGMPv3 groups. The usefulness of your test, however, depends on getting test results.


HTSetCommand NS_IGMPV3_LEAVE_ALL —

Chapter 20: IGMP TestingGetting Test Results


Getting Test ResultsYour test can provide three types of results:– Counters– Captured data — or —– Histograms





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.


HTGetStructure NS_IGMP_COUNTER_INFO NSIGMPCounterInfo

HTGetStructure NS_IGMP_TIMESTAMP_INFO NSIGMPTimestampInfo


HTGetStructure NS_IGMPV3_GROUP_INFO NSIGMPv3GroupInfo

NS_IGMPV3_ALL_GROUP_INFO NSIGMPv3GroupInfo

NS_IGMPV3_STATS_INFO NSIGMPv3StatsInfo

Chapter 20: IGMP TestingGetting Test Results



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”


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)


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






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).


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 –>









Continues –>

Applicable Commands


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)









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.





L3_DEFINE_MULTI_<n>_STREAM_EXTENSION StreamExtension


HTSetCommand NS_MLD_RESET None




HTSetStructure NS_MLD_CONFIG NSMLDConfig



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:



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 –>


HTSetStructure

HTSetCommand

NS_CAPTURE_SETUP

NS_CAPTURE_START

NSCaptureSetup

—


HTSetStructure NS_MLDV1_LISTEN NSMLDv1Listen







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.




HTSetStructure NS_MLDV1_LISTEN NSMLDv1Listen


HTGetStructure NS_MLD_COUNTER_INFO NSMLDCounterInfo


HTGetStructure NS_MLD_TIMESTAMP_INFO NSMLDTimestampInfo



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




Reset the MLD stack on the transmit and receive ports.

HTSetCommand NS_MLD_RESET

Optional.

Set the MAC and IPv6 addresses (Ethernet only).


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 –>









Applicable Commands


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)





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.




HTSetCommand NS_MLD_RESET None




HTSetStructure NS_MLD_CONFIG NSMLDConfig


HTSetStructure NS_MLDV2_LISTENER_REPORT_CONFIG

NSMLDv2ListenerReportConfig



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:



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.


HTSetStructure

HTSetCommand

NS_CAPTURE_SETUP

NS_CAPTURE_START

NSCaptureSetup

—


HTSetStructure NS_MLDV2_GROUP_CONFIG NSMLDv2GroupConfig


HTSetStructure NS_MLDV2_GROUP_MOD NSMLDv2GroupMod





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 –>




HTSetCommand NS_MLD_STOP_LISTEN —


HTGetStructure NS_MLDV2_STATS_INFO NSMLDv2StatsInfo


HTGetStructure NS_MLD_GROUP_INFO NSMLDGroupInfo



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.


HTGetStructure NS_MLD_GROUP_COUNT_INFO ULong


HTGetStructure NS_MLD_ALL_GROUP_INFO NSMLDGroupInfo


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


Set Up Dynamic MPLSUse the following steps to set up test ports with dynamic MPLS.


Table 21-1. Applicable Commands for Dynamic MPLS

Applicable Commands


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



Applicable Commands


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)





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.



HTSetStructure NS_CREATE_SUBPROCESS NSCreateSubprocess


HTSetStructure MPLS_ROUTING_DOMAIN_CREATE MPLSRoutingDomain


HTSetStructure MPLS_SERVICE_OBJECT_CREATE MPLSServiceObject

MPLS_ATTRIBUTE_OBJECT_CREATE MPLSAttributeObject

MPLS_EXPLICIT_ROUTE_OBJECT_CREATE MPLSExplicitObject



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.


HTSetStructure MPLS_LSP_CREATE MPLSLSP


HTSetStructure MPLS_START MPLSStart


HTGetStructure MPLS_LSP_NOT_COMPLETE MPLSStart


HTGetStructure MPLS_LSP_INFO MPLSLSPInfo


HTGetStructure MPLS_LABEL_DATA_INFO MPLSLSPInfo



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.


HTGetStructure MPLS_RSVP_COUNT_INFO MPLSRSVPCountInfo


HTSetStructure MPLS_OBJECT_DELETE MPLSObjectDelete


HTSetStructure MPLS_LSP_COPY_DELTA MPLSLSPCopyDelta


HTGetStructure MPLS_LSP_COUNT_INFO MPLSCountInfo


HTSetStructure MPLS_LSP_DELETE_ALL MPLSLSPDeleteAll



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.


HTSetStructure MPLS_ROUTING_DOMAIN_DELETE_ALL MPLSRoutingDomainDeleteAll


HTSetStructure NS_DESTROY_SUBPROCESS ULong


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


Set Up Fibre Channel TestsThis section explains how to set up your test.

Applicable Commands



Table 22-1. Applicable Commands to Set Up Fibre Channel Tests

Applicable Commands



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


Get port status to see if ready. HTGetStructure FC_STATUS_INFO







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


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)



HTSetStructure FC_PORT_CONFIG FCPortConfig


HTSetStructure FC_WWN FCWWN



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.


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.


HTSetStructure FC_SET_TX_MODE FCTransmitMode


HTSetStructure FC_HBA_CONFIG FCHBAConfig



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.


HTSetCommand FC_HBA_START —


HTSetCommand FC_LINKUP Perform Link Initialization.


HTGetStructure FC_STATUS_INFO FCStatus


HTSetCommand FC_WWN_LOGIN Perform Fabric login.



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.


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.


HTSetCommand FC_PUBLIC_DISCOVERY With public loop topology.

FC_PRIVATE_DISCOVERY With private loop topology.


HTSetCommand FC_COMMIT Complete initialization and configuration. Ready to test.


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.



Step 13 Check port status.

Use HTGetStructure with FC_STATUS_INFO(FCStatus) to check the port status.




Use the HTRun or HGRun command to run the test. (See the SmartLibrary Command Reference for descriptions of these Original Functions.)



HTGetStructure FC_STATUS_INFO FCStatus






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.




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.




HTGetStructure FC_COUNTER_INFO FCPortCounts









Use HTGetStructure with FC_COUNTER_INFO to get generic counters and Fibre Channel counters for your test.



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.)



Original Function Message Function iType1 Structure

HTGetStructure FC_COUNTER_INFO FCCounterInfo









For SmartMetrics histograms results, specify the histogram type. You can specify one of the following histogram types.

Continues –>


HTSetStructure NS_HIST_V2_LATENCY_PER_STREAM Layer3V2HistDistribution





NS_HIST_V2_LATENCY Layer3HistV2Latency


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













HTGetStructure NS_HIST_LATENCY_PER_STREAM_INFO Layer3StreamDistributionInfo


NS_HIST_V2_LATENCY_INFO Layer3HistV2Latency


NS_HIST_RAW_TAGS_INFO Layer3HistTagInfo


NS_HIST_SEQUENCE_INFO Layer3SequenceInfo


NS_HIST_LATENCY_DISTRIBUTION_INFO Layer3StreamDistributionInfo


Chapter 22: Fibre Channel TestingSet Up Custom Frames


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



Applicable CommandsTable 22-3 is a summary of commands. See “Example of Setup Steps” for more details.


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


HTSetStructure FC_SET_TX_MODE FCTransmitMode


HTSetStructure FC_SEND_CUSTOM FCCustomFrame



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.


HTSetStructure FC_SEND_CUSTOM FCCustomFrame

4 bytes 24 bytes 4 bytes 4 bytes

Start of Frame FC2 Protocol Header CRC End of

Frame



struct_new myFrame FCCustomFrame

set myFrame(ulLength)148

set myFrame(ulTimeToWait)50

set myFrame(ucPayLoad.0)0x57


set myFrame(ucPayLoad.2)0xB5

set myFrame(ucPayLoad.3)0xBC


set myFrame(ucPayLoad.5)0xFF


set myFrame(ucPayLoad.7)0xFC

















set myFrame(ucPayLoad.144)0xBC

set myFrame(ucPayLoad.145)0xB5


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



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.


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?


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?


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


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.



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




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


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;




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{


} NSIPAddress;


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.


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.



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.


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;




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.


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


Example (TCL):#

# get status count

#

set status_count 0

CheckError NSNTPGetClientStatusCount status_count


#

# get status

#

if {$status_count > 0} {



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.


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


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




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


#

# 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

{


} NSIPAddress;

typedef struct tagNSNTPPeerList {

unsigned long ulCount; /* number of peers */

NSIPAddress addrs[MAX_NTP_PEERS];

} NSNTPPeerList;


#define MAX_NTP_PEERS 8

typedef struct tagNSIPAddress

{




} NSIPAddress;

typedef struct tagNSNTPPeerList {

unsigned long ulCount; /* number of peers */

NSIPAddress addrs[MAX_NTP_PEERS];

} NSNTPPeerList;


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


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



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.


LAN-3306A 10/100Base-T Ethernet, Copper, 4-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


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



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


Chapter 24: 802.1x Supplicant EmulationSet Up 802.1x Supplicant Emulation


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"]


HTSlotReserve — Reserve the module for use.


HTResetPort — Reset the port.


HTSetStructure NS_CREATE_SUBPROCESS NSCreateSubprocess



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.


HTSetCommand NS_DOT1X_SUPPLICANT_RESET None


HTSetStructure NS_DOT1X_SUPPLICANT_PORT_CONFIG NSDOT1XSupplicantPortConfig

3 supplicantsstarted




0 12 ms 24 ms 36 ms 48 ms



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.



1 supplicantstarted

0 12 ms 24 ms 36 ms


0 12 ms 30 ms 36 ms 42 ms


1 supplicantstarted




1 supplicantstarted

6 ms 12 ms 24 ms


HTGetStructure NS_DOT1X_SUPPLICANT_PORT_CONFIG_INFO NSDOT1XSupplicantPortConfig


HTSetStructure NS_DOT1X_SUPPLICANT_CONFIG NSDOT1XSupplicantConfig



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.


HTGetStructure NS_DOT1X_SUPPLICANT_CONFIG_INFO NSDOT1XSupplicantConfig

HTGetStructure $::NS_DOT1X_SUPPLICANT_CONFIG_INFO 1 5 0\ myNSDOT1XSupplicantConfig 0 $iHub $iSlot $iPort

iType2 iType3


HTSetStructure NS_DOT1X_SUPPLICANT_COPY NSDOT1XSupplicantCopy


HTSetStructure NS_DOT1X_SUPPLICANT_MODIFY NSDOT1XSupplicantModify


HTSetStructure NS_DOT1X_SUPPLICANT_FILL NSDOT1XSupplicantFill



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.


HTSetStructure NS_DOT1X_SUPPLICANT_CONTROL NSDOT1XSupplicantControl


HTGetStructure NS_DOT1X_SUPPLICANT_STATS_INFO NSDOT1XSupplicantStatsInfo


HTGetStructure NS_DOT1X_SUPPLICANT_STATUS_INFO NSDOT1XSupplicantStatusInfo


HTGetStructure NS_DOT1X_SUPPLICANT_SESSION_STATS_INFO

NSDOT1XSupplicantSessionStatsInfo


HTGetStructure NS_DOT1X_SUPPLICANT_STATUS_SEARCH_INFO

NSDOT1XSupplicantStatusSearchInfo



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.




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).


HTSetStructure NS_DESTROY_SUBPROCESS ULong







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.






Example 1Index = 0Count = 3

Supplicant Configuration:S0 S2 S3 S4

The command applies to the following supplicants:S0, S2


Supplicant Configuration: S254 S255

The command applies to the following supplicants:S254, S255


Supplicant Configuration:S0 S2 S252 S254 S255



For the following messages, an error will be returned because there is no supplicant with starting index 1:




For the following message functions, the message applies only on S2.







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.




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:






In this example, an error is returned because the starting index is out of range.


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


−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.




−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.




−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.




−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.



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.


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.



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.




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



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.


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.



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 –>



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.



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


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


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



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.



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+ +

---------------------------------------------------------------------------------------------------------------------=



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



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



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


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



Table C-7. Two Streams Disabled


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


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 –



Table C-9. Five Streams Disabled


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


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.



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( )+ + +---------------------------------------------------------------------------------------------------------------------------------------------=



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



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



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


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


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



Table C-15. Two Streams Disabled


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


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


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


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%


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 5 Clear the group

Step 6 Add the transmitting and the receiving card to a group.

Use Description


Use Description

HGClearGroup Clears group settings.

Use Description

HGAddtoGroup Add ports to the group.

Appendix D: Inhibit Clearing Latency Counters


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


Appendix D: Inhibit Clearing Latency Counters


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


HGRun Run the test.

Use Description


Use Description



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


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


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


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

smartlibrary overview and procedures - oracle … overview and procedures | 9 procedures in this...

Documents