Teledyne USB Analyzer Automation User Manual

Download

Protocol Solutions Group

3385 Scott Blvd., Santa Clara, CA 95054 Tel: +1/408.653.1260 Fax: +1/408.727.6622

Automation API

Reference Manual

for

Teledyne LeCroy USBTracer™, Advisor

T3™, USB Advisor™, Mercury T2, and

Voyager M3/M3i/M3x™

USB Protocol Suite Software Version 4.70 and above

Manual Version 4.71

September, 2013

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol Suite

Document Disclaimer

The information contained in this document has been carefully checked and is believed to be reliable. However, no responsibility can be assumed for inaccuracies that may not have been detected.

Teledyne LeCroy reserves the right to revise the information presented in this document without notice or penalty.

Trademarks and Servicemarks

CATC Trace, USBTracer, USBTrainer, USB Advisor, and Voyager are trademarks of Teledyne LeCroy

Microsoft and Windows are registered trademarks of Microsoft Inc. All other trademarks are property of their respective companies.

should contain this copyright notice.

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol Suite

Contents

1 Introduction ................................................................................................ 6

1.1 ...... System Requirements ........................................................... 6

1.2 ...... Setting Up Automation for Local Use .................................... 6

1.3 ...... Setting Up Automation for Remote Use ................................ 7

2 Primary Dual Interface for Analyzer ......................................................... 8

2.1 ...... IUsbAnalyzer Dual Interface.................................................. 8

2.1.1 IAnalyzer::GetVersion ......................................................................... 8

2.1.2 IAnalyzer::GetSerialNumber ............................................................. 10

2.1.3 IAnalyzer::OpenFile........................................................................... 11

2.1.4 IAnalyzer::StartGeneration ................................................................ 13

2.1.5 IAnalyzer::StopGeneration ................................................................ 14

2.1.6 IAnalyzer::StartRecording ................................................................. 15

2.1.7 IAnalyzer::StopRecording ................................................................. 17

2.1.8 IAnalyzer::MakeRecording ................................................................ 18

2.1.9 IAnalyzer::LoadDisplayOptions ......................................................... 19

2.1.10 IAnalyzer::GetRecordingOptions ....................................................... 20

2.1.11 IUsbAnalyzer::StopRecordingAndWaitForTrace ............................... 21

2.1.12 IUsbAnalyzer::get_ApplicationFolder (property) ................................ 25

2.1.13 IUsbAnalyzer::get_ApplicationDataFolder (property) ........................ 26

2.1.14 IUsbAnalyzer::StartUsb3Generation ................................................. 27

2.1.15 IUsbAnalyzer::StopUsb3Generation ................................................. 30

2.1.16 IUsbAnalyzer::PauseUsb3Generation............................................... 32

2.1.17 IUsbAnalyzer::ResumeUsb3Generation ........................................... 34

2.1.18 IUsbAnalyzer::UsbUnplugPlug .......................................................... 35

2.2 ...... IUsbAnalyzer3 interface ...................................................... 36

2.2.1 IUsbAnalyzer3:: IssueManualTrig ..................................................... 36

2.3 ...... IUsbAnalyzer4 interface ...................................................... 37

2.3.1 IUsbAnalyzer4::GetRecordingStatus ................................................ 37

2.3.2 IUsbAnalyzer4::ResetUsb3Trainer .................................................... 37

2.3.3 IUsbAnalyzer4::IsUsb3GenerationIdle .............................................. 38

2.3.4 IUsbAnalyzer4::SwitchVBus .............................................................. 38

2.4 ...... IUsbAnalyzer5 interface ...................................................... 39

2.4.1 IUsbAnalyzer5::BindUnit ................................................................... 39

2.4.2 IUsbAnalyzer5::MergeTraceFiles ...................................................... 39

2.5 ...... IUsbAnalyzer6 interface ...................................................... 40

2.5.1 IUsbAnalyzer6::WaitForUsb3GenerationIdle .................................... 40

2.5.2 IUsbAnalyzer6::WaitForRecordingStatus .......................................... 40

3 Primary Dual Interface for Trace ............................................................. 42

3.1 ...... IUsbTrace Dual Interface .................................................... 42

3.1.1 ITrace::GetName .............................................................................. 43

3.1.2 ITrace::ApplyDisplayOptions ............................................................. 44

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol Suite

3.1.3 ITrace::Save ..................................................................................... 45

3.1.4 ITrace::ExportToText ........................................................................ 46

3.1.5 ITrace::Close .................................................................................... 48

3.1.6 ITrace::ReportFileInfo ....................................................................... 49

3.1.7 ITrace::ReportErrorSummary ........................................................... 51

3.1.8 ITrace::ReportTrafficSummary ......................................................... 53

3.1.9 ITrace::GetPacket ............................................................................ 54

3.1.10 ITrace::GetPacketsCount ................................................................. 57

3.1.11 ITrace::GetTriggerPacketNum .......................................................... 58

3.1.12 ITrace::AnalyzerErrors...................................................................... 59

3.2 ....... IUsbTrace2 interface ........................................................... 60

3.2.1 IUsbTrace2::GotoTime ..................................................................... 61

3.2.2 IUsbTrace2::GotoUnit ....................................................................... 62

3.2.3 IUsbTrace2::ExportToCsv ................................................................ 63

3.2.4 IUsbTrace2::SaveAs ........................................................................ 65

3.3 ....... IUsbTrace3 interface ........................................................... 66

3.3.1 IUsbTrace3:: GetPowerInfoByTime .................................................. 66

3.3.2 IUsbTrace3:: GetPowerInfoByPacket ............................................... 66

3.4 ....... IUsbTrace4 interface ........................................................... 68

3.4.1 IUsbTrace4:: GetFullName ............................................................... 68

3.5 ....... IUsbTrace5 interface ........................................................... 69

3.5.1 IUsbTrace5::GetUsbPacket .............................................................. 69

3.6 ....... IUsbVerificationScript Interface ........................................... 70

3.6.1 IUsbVerificationScript::RunVerificationScript .................................... 71

3.6.2 IUsbVerificationScript::GetVScriptEngine ......................................... 73

4 Primary Dual Interface for Packet .......................................................... 74

4.1 ....... IUsbPacket Interface ........................................................... 74

4.1.1 IUsbPacket::GetTimestamp .............................................................. 74

4.1.2 IUsbPacket::GetDuration .................................................................. 74

4.1.3 IUsbPacket::GetSpeed ..................................................................... 74

4.1.4 IUsbPacket::GetChannel .................................................................. 75

4.1.5 IUsbPacket::GetType ....................................................................... 75

4.1.6 IUsbPacket::GetFieldValue .............................................................. 77

4.1.7 IUsbPacket::GetAllFieldsValues ....................................................... 77

4.1.8 IUsbPacket::GetMarker .................................................................... 78

4.1.9 IUsbPacket::GetErrorsBitmap .......................................................... 78

4.1.10 IUsbPacket::GetRawData ................................................................ . 80

4.1.11 IUsbPacket::GetUsb3ScrambledData .............................................. 80

4.1.12 IUsbPacket::GetUsb3TenBitData ..................................................... 81

5 Primary Dual Interface for USB Verification Script Engine.................. 82

5.1 ....... IVScriptEngine interface ...................................................... 82

5.1.1 IVScriptEngine::VscriptName ........................................................... 83

5.1.2 IVScriptEngine::Tag ......................................................................... 84

5.1.3 IVScriptEngine::RunVScript .............................................................. 85

5.1.4 IVScriptEngine::RunVScriptEx ......................................................... 86

5.1.5 IVScriptEngine::LaunchVScript ........................................................ 87

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol Suite

5.1.6 IVScriptEngine::Stop ......................................................................... 88

5.1.7 IVScriptEngine::GetScriptVar ............................................................ 89

5.1.8 IVScriptEngine::SetScriptVar ............................................................ 91

6 Verification Script Engine Events Callback Interface ........................... 93

6.1 ...... _IVScriptEngineEvents dispinterface .................................. 93

6.1.1 _IVScriptEngineEvents::OnVScriptReportUpdated ........................... 96

6.1.2 _IVScriptEngineEvents::OnVScriptFinished ...................................... 97

6.1.3 _IVScriptEngineEvents::OnNotifyClient ............................................ 98

7 Primary Dual Interface for Recording Options .................................... 100

7.1 ...... IUsbRecOptions Dual Interface ......................................... 100

7.1.1 IRecOptions::Load .......................................................................... 101

7.1.2 IRecOptions::Save .......................................................................... 102

7.1.3 IRecOptions::SetRecMode .............................................................. 103

7.1.4 IRecOptions::SetBufferSize ............................................................ 104

7.1.5 IRecOptions::SetPostTriggerPercentage ........................................ 105

7.1.6 IRecOptions::SetTriggerBeep ......................................................... 106

7.1.7 IRecOptions::SetDataTruncate ....................................................... 107

7.1.8 IRecOptions::SetAutoMerge ........................................................... 107

7.1.9 IRecOptions::SetSaveExternalSignals ............................................ 109

7.1.10 IRecOptions::SetTraceFileName .................................................... 110

7.1.11 IRecOptions:: SetFilterPolarity ........................................................ 111

7.1.12 IRecOptions::Reset ......................................................................... 112

8 Errors Collection Interface .................................................................... 113

8.1 ...... IAnalyzerErrors dispinterface ............................................ 113

8.1.1 IAnalyzerErrors::get_Item ............................................................... 114

8.1.2 IAnalyzerErrors::get_Count ............................................................. 115

9 Analyzer Events Callback Interface ...................................................... 117

9.1 ...... _IAnalyzerEvents dispinterface ......................................... 117

9.1.1 _IAnalyzerEvents::OnTraceCreated................................................ 117

9.1.2 _IAnalyzerEvents::OnStatusReport ................................................ 118

10 CATCAnalyzerAdapter .......................................................................... 122

10.1 ... IAnalyzerAdapter Interface ................................................ 123

10.1.1 IAnalyzerAdapter::CreateObject ..................................................... 124

10.1.2 IAnalyzerAdapter::Attach ................................................................ 126

10.1.3 IAnalyzerAdapter::Detach ............................................................... 127

10.1.4 IAnalyzerAdapter::IsValidObject ..................................................... 129

Appendix A. DCOM Configuration ................................................................. 130

Appendix B. How to Contact Teledyne LeCroy ............................................ 144

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol Suite

1 Introduction

USBTracer™, USB Advisor™, and Voyager™ USB Protocol Suite Automation is an Application Program Interface (API) that allows users to create scripts or programs of commands and run these scripts or programs locally or remotely over a network. The name Automation is derived from the goal of allowing engineers to automate test procedures.

The USBTracer, USB Advisor, and Voyager USB Protocol Suite Automation API is composed of a command set that duplicates most of the functionality of the USBTracer, USB Advisor, and Voyager Graphical User Interfaces. Automation is implemented through the use of scripts or programs that the user can write using late binding scripting languages such as VBScript and WSH or early binding languages such as C++. Teledyne LeCroy provides examples of scripts written in WSH, VBScript, and C++.

Once an Automation script or program has been created, it can be run on the PC attached to or transmitted to the PC over a network from a remote location. Automation uses the Distributed Component Object Model (DCOM) protocol to transmit automation commands over a network. When run over a network, the Host Controller is configured as a DCOM server and the remote PC is configured as a DCOM client.

Note:

If you are using any application that uses the Automation Interface to the USB Protocol Suite, and the system prompts you that it cannot write a trace file to disk:

1. Make sure that the trace-file destination folder has write/create permissions. (For example, the target directory might be the netwrok file system, which typically does not have write/create permissions.)

2. Make sure that the Windows (or other) Firewall Settings for USB Protocol Suite are set to Public.

1.1 System Requirements

Automation is supported with USBTracer/Trainer and USB Advisor software version 1.7 or higher and Voyager USB Protocol Suite software version 3.0 or higher. If you have an older version of the software, you must upgrade. You can get a new version of software from the Teledyne LeCroy web site, www.teledynelecroy.com/support. You also need a copy of the USBTracer, USB Advisor, and Voyager USB Protocol Suite Automation software package. This is available from Teledyne LeCroy.

IMPORTANT! To compile with the correct linkage to the USB Automation API code, you must move the USBAutomation.tlb file from the application's installed directory into a directory from which your

compiler can access the file. For example, for Visual Studio, this typically is the directory that contains your project file and sources.

1.2 Setting Up Automation for Local Use

If you intend to run Automation on the Analyzer Host Controller (the PC attached to the Analyzer), you do not need to perform any special configuration. You can simply execute the scripts or programs you have created, and they run the Analyzer.

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

Objects

Interfaces

Description

UsbAnalyzer

IUsbAnalyzer IUsbAnalyzer3

Primary Analyzer interface

_IAnalyzerEvents

Analyzer event source

UsbTrace

IUsbTrace

Trace file interfaces

IUsbTrace2

UsbRecOptions

IUsbRecOptions

Recording options interface

UsbDevice

IUsbDevice

USB device interface

AnalyzerErrors

IAnalyzerErrors

Error collection interface

UsbAnalyzer

UsbRecOptions

UsbTrace

UsbDevice

AnalyzerErrors

Suite

1.3 Setting Up Automation for Remote Use

If you intend to run automation remotely over a network, you must perform DCOM configuration. These steps are described in the Appendix.

The USB Protocol Suite API exposes the following objects and interfaces:

Only the UsbAnalyzer object is creatable at the top level (that is, via the CoCreateInstance call), instantiation of an object of other classes requires API calls. The following diagram represents the object dependencies:

All interfaces are dual interfaces, which allow simple use from typeless languages as well as from C++. All objects implement the ISupportErrorInfo interface for easy error handling from the client. The examples of C++ code given in this document assume using the “import” technique of creating COM

clients, using the corresponding include statement: #import "UsbAutomation.tlb" no_namespace named_guids

and creating appropriate wrapper classes in .tli and .tlh files by the compiler. Samples of WSH, VBScript, and C++ client applications are provided.

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

HRESULT GetVersion (

[in] EAnalyzerVersionType version_type, [out, retval] WORD* analyzer_version );

Suite

2 Primary Dual Interface for Analyzer

2.1 IUsbAnalyzer Dual Interface

IUsbAnalyzer interface is the primary interface for the UsbAnalyzer object. It derives from the IAnalyzer interface that implements the common functionality for all Teledyne LeCroy Analyzers.

Class ID: 136D64A4-3CD5-4b41-974A-C7039E3FC292 App ID: CATC.USBTracer COM server: UsbSuite.exe IUsbAnalyzer IID: C37E7603-E3E5-48b4-8F79-080DBB543F0C

2.1.1 IAnalyzer::GetVersion

Retrieves the current version of the specified subsystem.

Parameters

version_type Subsystem whose version is requested;

EAnalyzerVersionType enumerator has the following values: ANALYZERVERSION_SOFTWARE ( 0 ) Software ANALYZERVERSION_BUSENGINE ( 1 ) Bus engine ANALYZERVERSION_FIRMWARE ( 2 ) Firmware

analyzer_version Current version of subsystem requested

Return values

ANALYZERCOMERROR_INVALIDVERSIONTYPE Specified version type is invalid. ANALYZERCOMERROR_ANALYZERNOTCONNECTED Analyzer device is not connected.

Remarks

Example

WSH:

CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\")) Set Analyzer = WScript.CreateObject("CATC.USBTracer") SwVersion = Analyzer.GetVersion(0) BEVersion = Analyzer.GetVersion(1) FwVersion = Analyzer.GetVersion(2) MsgBox "Software" & SwVersion & "BusEngine" & BEVersion & "Firmware" & FwVersion

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol Suite

C++:

CLSID_UsbAdvisor, NULL, CLSCTX_SERVER, IID_IUsbAnalyzer, (LPVOID *)&poUsbAnalyzer ) ) return;

HRESULT hr; IUsbAnalyzer* poUsbAnalyzer;

// create UsbAnalyzer object if ( FAILED( CoCreateInstance(

WORD sw_version; try {

sw_version = poUsbAnalyzer ->GetVersion( ANALYZERVERSION_SOFTWARE ); } catch ( _com_error& er) {

if (er.Description().length() > 0)

::MessageBox( NULL, er.Description(), _T("UsbAnalyzer client"), MB_OK );

else

::MessageBox( NULL, er.ErrorMessage(), _T("UsbAnalyzer client"), MB_OK );

return 1; }

TCHAR buffer[20]; _stprintf( buffer, _T("Software version:%X.%X"),

HIBYTE(sw_version), LOBYTE(sw_version) );

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

HRESULT GetSerialNumber (

[out, retval] WORD* serial_number );

Suite

2.1.2 IAnalyzer::GetSerialNumber

Retrieves the serial number of the Analyzer device.

Parameters

Return values

ANALYZERCOMERROR_INVALIDVERSIONTYPE Specified version type is invalid. ANALYZERCOMERROR_ANALYZERNOTCONNECTED Analyzer device is not connected.

Remarks

Example

WSH:

C++:

CLSID_UsbAdvisor, NULL, CLSCTX_SERVER, IID_IUsbAnalyzer, (LPVOID *)&poUsbAnalyzer ) ) return;

CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\")) Set Analyzer = WScript.CreateObject("CATC.USBTracer") MsgBox "Serial number: " & Analyzer.GetSerialNumber()

HRESULT hr; IUsbAnalyzer* poUsbAnalyzer;

// create UsbAnalyzer object if ( FAILED( CoCreateInstance(

WORD serial_number; try {

serial_number = poUsbAnalyzer ->GetSerialNumber(); } catch ( _com_error& er) {

if (er.Description().length() > 0)

::MessageBox( NULL, er.Description(), _T("UsbAnalyzer client"), MB_OK );

else

::MessageBox( NULL, er.ErrorMessage(), _T("UsbAnalyzer client"), MB_OK );

return 1; }

TCHAR buffer[20]; _stprintf( buffer, _T("Serial number: %X"),

HIBYTE(serial_number), LOBYTE(serial_number) );

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

HRESULT OpenFile (

[in] BSTR file_name, [out, retval] IDispatch** trace );

Suite

2.1.3 IAnalyzer::OpenFile

Opens a trace file.

Parameters

file_name String providing the full pathname to the trace file trace Address of a pointer to the UsbTrace object primary interface

Return values

ANALYZERCOMERROR_UNABLEOPENFILE Unable to open file. ANALYZERCOMERROR_WRONGCALL Error when trying to access the

opened trace when it is being

Remarks UsbTrace object is created via this method call, if call was successful.

In rare cases, the method may return ANALYZERCOMERROR_WRONGCALL error. This may happen when client code is trying to open an already opened trace file, while it is being released and destroyed. Subsequent method calls will reopen the trace file.

released and destroyed.

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol Suite

Example

WSH:

C++:

CLSID_UsbAdvisor, NULL, CLSCTX_SERVER, IID_IUsbAnalyzer, (LPVOID *)&poUsbAnalyzer ) ) return;

// query for VTBL interface

hr = trace->QueryInterface( IID_IUsbTrace, (LPVOID *)&usb_trace );

CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\")) Set Analyzer = WScript.CreateObject("CATC.USBTracer") Set Trace = Analyzer.OpenFile (CurrentDir & "Input\errors.usb")

HRESULT hr; IUsbAnalyzer* poUsbAnalyzer;

// create UsbAnalyzer object if ( FAILED( CoCreateInstance(

// open trace file IDispatch* trace; try {

trace = poUsbAnalyzer->OpenFile( m_szRecFileName ); } catch ( _com_error& er) {

if (er.Description().length() > 0)

::MessageBox( NULL, er.Description(), _T("UsbAnalyzer client"), MB_OK );

else

::MessageBox( NULL, er.ErrorMessage(), _T("UsbAnalyzer client"), MB_OK );

return 1; }

IUsbTrace* usb_trace;

trace->Release();

if( FAILED(hr) ) return;

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

HRESULT StartGeneration (

[in] BSTR gen_file_name, [in] long gen_mode, [in] long loop_count );

Suite

2.1.4 IAnalyzer::StartGeneration

Starts USB 2.0 traffic generation from the file.

Parameters

gen_file_name String providing the full pathname to the generation file.

If a valid name, the file is opened after any pre-existing Generation File is closed in accordance with the behavior set forth by Bit 31 in the gen_mode parameter. If NULL string, it just closes any existing Generation File.

gen_mode Generation mode:

Bit 0: 0 = bitstream; 1 = IntelliFrame Bit 31: 0 = Load gen_file_name only if:

1. Different than pre-existing Generation Filename OR

2. The gen_file_name file is already loaded but has been changed since the time it was loaded OR

3. The generation mode (bit 0) is different than the previous invocation. Leaving this bit set to 0 allows a file to be generated repeatedly without having to be re-parsed or downloaded to the Analyzer hardware, saving time.

loop_count Number of times to repeat:

-1 = loop forever 1 through 16381 executes generation file that number of times.

Return values

ANALYZERCOMERROR_UNABLEOPENFILE Unable to open file ANALYZERCOMERROR_UNABLESTARTGENERATION Unable to start generation

E_INVALIDARG

Remarks

Used to load a .utg file and begin generating traffic.

Example

1 = Reload gen_file_name unconditionally.

(USB 3.0 generation is running, invalid state, or other)

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

HRESULT StopGeneration ( );

Suite

2.1.5 IAnalyzer::StopGeneration

Stops any current USB 2.0 generation in progress.

Return values

ANALYZERCOMERROR_UNABLESTARTGENERATION Unable to stop generation

(invalid state, etc.).

Remarks

Stop any current traffic generation.

Example

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

HRESULT StartRecording (

[in] BSTR ro_file_name );

Suite

2.1.6 IAnalyzer::StartRecording

Starts recording with specified recording options.

Parameters

ro_file_name String providing the full pathname to recording options file.

If the parameter is omitted, then recording starts with the default

Return values

ANALYZERCOMERROR_EVENTSINKNOTINSTANTIATED Event sink was not instantiated. ANALYZERCOMERROR_UNABLESTARTRECORDING Unable to start recording.

Remarks

After recording starts, this function returns. The Analyzer continues recording until it is finished

or until a StopRecording method call is performed. During the recording, the events are sent to the event sink (see the _IAnalyzerEvents interface).

The recording options file is the file with extension .rec created by the USB Protocol Suite application. You can create such a file by selecting Setup – Recording Options… from the USB Protocol Suite application menu, changing the recording options in the dialog, and selecting the

Save button. Example

VBScript:

<OBJECT

RUNAT=Server ID = Analyzer

CLASSID = "clsid:0B179BB3-DC61-11d4-9B71-000102566088" > </OBJECT>

<SCRIPT LANGUAGE="VBScript"> <!-Sub BtnStartRecording_OnClick

On Error Resume Next Analyzer.StartRecording TextRecOptions.value If Err.Number <> 0 Then MsgBox Err.Number & ":" & Err.Description End If

End Sub

--> </SCRIPT>

recording options.

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol Suite

C++:

IUsbAnalyzer* usb_analyzer; BSTR ro_file_name;

. . .

try {

usb_analyzer->StartRecording( ro_file_name ) } catch ( _com_error& er) {

if (er.Description().length() > 0)

::MessageBox( NULL, er.Description(), _T("UsbAnalyzer client"), MB_OK );

else

::MessageBox( NULL, er.ErrorMessage(), _T("UsbAnalyzer client"), MB_OK );

return 1; }

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

HRESULT StopRecording (

[in] BOOL abort_upload );

Suite

2.1.7 IAnalyzer::StopRecording

Stops a recording started by the StartRecording method. Parameters

abort_upload TRUE, if caller wants to abort upload,

no trace file is created.

Return values

ANALYZERCOMERROR_EVENTSINKNOTINSTANTIATED Event sink was not instantiated. ANALYZERCOMERROR_UNABLESTOPRECORDING Error stopping recording

Remarks

Stops recording started by the StartRecording method. The event is issued when recording is

actually stopped (via _IAnalizerEvents interface), if the parameter of method call was FALSE.

Example

VBScript:

<OBJECT

RUNAT=Server ID = Analyzer

CLASSID = "clsid:0B179BB3-DC61-11d4-9B71-000102566088" > </OBJECT> <SCRIPT LANGUAGE="VBScript"> <!-Sub BtnStopRecording_OnClick

On Error Resume Next Analyzer.StopRecording True If Err.Number <> 0 Then MsgBox Err.Number & ":" & Err.Description End If

End Sub

--> </SCRIPT>

C++:

IUsbAnalyzer* usb_analyzer; . . . try {

usb_analyzer->StopRecording( FALSE ) } catch ( _com_error& er) {

if (er.Description().length() > 0)

::MessageBox( NULL, er.Description(), _T("UsbAnalyzer client"), MB_OK );

else

::MessageBox( NULL, er.ErrorMessage(), _T("UsbAnalyzer client"), MB_OK );

return 1; }

FALSE, if you want to upload the recorded trace

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

HRESULT MakeRecording (

[in] BSTR ro_file_name, [out, retval] IDispatch** trace );

Suite

2.1.8 IAnalyzer::MakeRecording

Makes a recording with the specified recording options file.

Parameters

trace Address of a pointer to the UsbTrace object primary interface

Return values Remarks

application. You can create such a file by selecting Setup – Recording Options… from the USB Protocol Suite application menu, changing the recording options in the dialog, and selecting the

Save button. Example

WSH:

C++:

// query for VTBL interface

hr = trace->QueryInterface( IID_IUsbTrace, (LPVOID *)&usb_trace );

ro_file_name String providing the full pathname to recording options file;

If the parameter is omitted, then recording starts with the default recording options.

This method acts like StartRecording method but does not return until recording is completed. UsbTrace object is created via this method call, if call was successful. The recording options file is the file with extension .rec created by the USB Protocol Suite

IDispatch* trace; IUsbAnalyzer* usb_analyzer; BSTR ro_file_name; HRESULT hr;

. . .

try {

trace = usb_analyzer->MakeRecording( ro_file_name ) } catch ( _com_error& er) {

if (er.Description().length() > 0)

::MessageBox( NULL, er.Description(), _T("UsbAnalyzer client"), MB_OK );

else

::MessageBox( NULL, er.ErrorMessage(), _T("UsbAnalyzer client"), MB_OK );

return 1; }

IUsbTrace* usb_trace;

trace->Release();

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

HRESULT LoadDisplayOptions (

[in] BSTR do_file_name );

Suite

2.1.9 IAnalyzer::LoadDisplayOptions

Loads display options that apply for traces opened or recorded later.

Parameters

do_file_name String providing the full pathname to display options file

Return values

Remarks

method call apply only on trace files opened or recorded after this call. You can create such a file by selecting Setup – Display Options… from the USB Protocol Suite

application menu, changing the display options in the dialog, and selecting the Save button. Example

See ITrace::ApplyDisplayOptions.

ANALYZERCOMERROR_UNABLELOADDO Unable to load display options file.

Use this method if you want to filter traffic of some type. The display options loaded by this Display options file is the file with extension .opt created by the USB Protocol Suite application.

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

HRESULT GetRecordingOptions (

[out, retval] IDispatch** recording_options );

Suite

2.1.10 IAnalyzer::GetRecordingOptions

Retrieves the primary interface for access to recording options.

Parameters

recording_options Address of a pointer to the UsbRecOptions object

primary interface

Return values

Remarks

UsbRecOptions object is created via this method call, if call was successful.

Example

WSH:

C++:

CLSID_UsbAdvisor, NULL, CLSCTX_SERVER, IID_IUsbAnalyzer, (LPVOID *)&poUsbAnalyzer ) ) return;

// Query for VTBL interface.

hr = rec_opt->QueryInterface( IID_IUsbRecOptions, (LPVOID *)&ib_rec_opt );

Set Analyzer = WScript.CreateObject("CATC.USBTracer") Set RecOptions = Analyzer.GetRecordingOptions

HRESULT hr; IUsbAnalyzer* poUsbAnalyzer;

// Create UsbAnalyzer object. if ( FAILED( CoCreateInstance(

// Open trace file. IDispatch* rec_opt; try {

rec_opt = poUsbAnalyzer->GetRecordingOptions(); } catch (_com_error& er) {

if (er.Description().length() > 0)

::MessageBox( NULL, er.Description(), _T("UsbAnalyzer client"), MB_OK );

else

::MessageBox( NULL, er.ErrorMessage(), _T("UsbAnalyzer client"), MB_OK );

return 1; }

IUsbRecOptions* ib_rec_opt;

rec_opt->Release();

if( FAILED(hr) )

return;

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

HRESULT StopRecordingAndWaitForTrace ( [out, retval] IDispatch** trace );

Suite

2.1.11 IUsbAnalyzer::StopRecordingAndWaitForTrace

Stops recording started by the StartRecording method and returns the pointer to the trace object created.

Parameters

Return values

Remarks

This method stops recording started by the StartRecording method and does not return until the recording is uploaded and a trace object related to this recording is created. In contrast, for StopRecording, no event is issued when recording is stopped by this method.

In rare cases, the method may return ANALYZERCOMERROR_WRONGCALL error. This may happen when recording stopped by itself (for example, because buffer is full), and the method call occurs when the recorded trace is being released and destroyed. Subsequent method calls will reopen the recorded trace. To avoid this issue, use a recording-buffer size that is big enough, so that the method call will occur when recording is still in progress and recording buffer is not full.

trace Address of a pointer to the UsbTrace object primary interface

ANALYZERCOMERROR_UNABLESTOPRECORDING Error when stopping recording ANALYZERCOMERROR_WRONGCALL Error when trying to access

trace when it is being destroyed.

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol Suite

Example

WSH:

' Extract the script name. ScriptName = Right(WScript.ScriptFullName, Len(WScript.ScriptFullName) - InstrRev(WScript.ScriptFullName, "\") )

Set Analyzer = WScript.CreateObject( "CATC.UsbTracer" )

CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\"))

' In the code below, we perform four sequential recordings and ' save the traces recorded in the current folder.

For I = 1 To 4

'Tell the CATC UWB analyzer to start recording. Analyzer.StartRecording ( CurrentDir & "Input\test_ro.rec" )

' Imitation of some activity - just sleep for 3 seconds. ' Some real traffic generation code might be put here. WScript.Sleep 3000

' Tell the analyzer to stop recording and give the trace acquired. Set Trace = Analyzer.StopRecordingAndWaitForTrace

' Save the trace in the current folder. Trace.Save CurrentDir & "Output\usb_seqrec_data" & CStr(I) & ".usb" Next

Set Trace = Nothing

'Release the analyzer. Set Analyzer = Nothing

MsgBox "Sequential recordings are completed." & String(2, 13) & "Look for recorded traces in the folder : " & CurrentDir & "Output", 64, ScriptName

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol Suite

C++: (Raw code without using type library. All error handling is omitted for simplicity)

return;

IUsbAnalyzer* pAnalyzer = NULL;

// Create UsbAnalyzer object. if ( FAILED( CoCreateInstance( CLSID_UsbAdvisor, NULL, CLSCTX_SERVER,

IID_IUsbAnalyzer, (LPVOID *)&pAnalyzer ) )

BSTR ro_file_name = SysAllocString( L"test_ro.rec" ); BSTR bstr_trace_name;

IDispatch* trace = NULL;

for( int i = 0; i < 4; i++ ) {

if( FAILED( pAnalyzer ->StartRecording( ro_file_name ) )

return; // Error handling and resources releasing should be done.

// Fake generation. Sleep(3000);

if( FAILED( Analyzer->StopRecordingAndWaitForTrace( &trace ) ) )

return; // Error handling and resources releasing should be done.

IUsbTrace2* usbTrace = NULL;

// Query for IUsbTrace2 interface.

if( FAILED( trace->QueryInterface( IID_IUsbTrace2, (LPVOID*)usbTrace ) ) )

return; // Error handling and resources releasing should be done.

OLECHAR trace_name[_MAX_PATH]; swprintf ( trace_name, "test_data%u.usb", i ); SysAllocString( bstr_trace_name );

// Save the trace recorded to the current folder usbTrace->Save( bstr_trace_name );

// Release the trace object. trace->Release(); usbTrace->Release();

SysFreeString( bstr_trace_name ); // Free BSTR. }

pAnalyzer->Release(); // Release the analyzer object. SysFreeString( ro_file_name ); // Free BSTR.

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol Suite

C++: (Microsoft® C++ specific, using type library. All error handling is omitted for simplicity.)

pAnalyzer->StartRecording( _bstr_t("test_ro.rec") );

// Fake generation: just sleep for 3 seconds. Sleep(3000);

trace = pAnalyzer->StopRecordingAndWaitForTrace();

TCHAR trace_name[_MAX_PATH]; sprintf( trace_name, "test_data%u.uwb", i );

// Save the trace recorded in the current folder. trace->Save( _bstr_t(trace_name) );

// Release the trace object. trace = NULL; }

IUsbAnalyzerPtr pAnalyzer = NULL; pAnalyzer.CreateInstance( __uuidof(UsbAdvisor) );

if( !pAnalyzer ) return;

IUsbTrace2Ptr trace = NULL;

for( int i = 0; i < 4; i++ ) { // Start recording using recording options file 'test_ro.rec' located in

// the current folder.

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

HRESULT get_ApplicationFolder( [out, retval] BSTR *app_folder );

Suite

2.1.12 IUsbAnalyzer::get_ApplicationFolder (property)

Retrieves the full local path to the folder where the USB Protocol Suite application was installed and registered as a COM server.

Parameters

Return values Remarks

This property allows client applications to access some important files used by the USB Protocol Suite application, such as recording options, display options, and trace files, in places relative to the USB Protocol Suite application folder. If later the USB Protocol Suite application is re-installed to another location, the client code does not have to be changed to reflect this event.

Example

WSH:

C++:

return;

app_folder Pointer to string variable indicating USB Protocol Suite application folder

Set Analyzer = WScript.CreateObject("CATC.UsbTracer")

' Open trace file 'some_trace.usb' in the USB Suite folder. Set Trace = Analyzer.OpenFile( Analyzer.ApplicationFolder & "some_trace.usb" )

' Save opened trace as 'some_trace1.usb' in the USB Suite folder. Trace.Save Analyzer.ApplicationFolder & "some_trace1.usb" ...

HRESULT hr; IUsbAnalyzer* poUsbAnalyzer;

// Create UsbAnalyzer object. if ( FAILED( CoCreateInstance( CLSID_UsbAdvisor, NULL, CLSCTX_SERVER,

IID_IUsbAnalyzer, (LPVOID *)&poUsbAnalyzer ) )

BSTR app_folder; hr = poUsbAnalyzer->get_ApplicationFolder( &app_folder );

// . . . Do something with app_folder.

SysFreeString( app_folder ); // Free BSTR resources. poUsbAnalyzer->Release(); // Release analyzer object.

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

HRESULT get_ApplicationDataFolder( [out, retval] BSTR *app_folder );

Suite

2.1.13 IUsbAnalyzer::get_ApplicationDataFolder (property)

Retrieves the full local path to the folder for user-alterable data, such as scripts, traces, and default options files.

Parameters

app_folder Pointer to string variable indicating the

Return values Remarks

This property allows client applications to access some important files used by the USB Protocol Suite application, such as recording options, display options, and trace files, in places relative to the USB Protocol Suite application folder, Windows XP Documents and Settings\All Users folder, and Windows Vista Users\Public folder. If later the USB Protocol Suite application is re-installed to another location, the client code does not have to be changed to reflect this event.

Example

WSH:

Set Analyzer = WScript.CreateObject("CATC.UsbTracer")

' Open trace file 'some_trace.usb' in a user-modiable folder. Set Trace = Analyzer.OpenFile(Analyzer. ApplicationDataFolder & "some_trace.usb")

' Save opened trace as 'some_trace1.usb' in a user-modiable folder. Trace.Save Analyzer. ApplicationDataFolder & "some_trace1.usb" ...

C++:

HRESULT hr; IUsbAnalyzer* poUsbAnalyzer;

// Create UsbAnalyzer object. if ( FAILED( CoCreateInstance( CLSID_UsbAdvisor, NULL, CLSCTX_SERVER,

IID_IUsbAnalyzer, (LPVOID *)&poUsbAnalyzer ) )

return;

BSTR app_folder; hr = poUsbAnalyzer->get_ApplicationDataFolder( &app_folder );

// . . . Do something with app_folder.

SysFreeString( app_folder ); // Free BSTR resources. poUsbAnalyzer->Release(); // Release analyzer object.

USB Protocol Suite user-modifiable data folder

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

HRESULT StartUsb3Generation([in,defaultvalue("")] BSTR gen_file_name);

Suite

2.1.14 IUsbAnalyzer::StartUsb3Generation

Starts generating USB traffic.

Parameters

gen_file_name USB 3.0 Exerciser script file name to execute.

If this parameter is an empty string, the last executed

Return values

ANALYZERCOMERROR_ANALYZERNOTCONNECTED No Analyzer connected ANALYZERCOMERROR_UNABLESTARTGENERATION Analyzer cannot start for one of

the following reasons:

Remarks

This function returns after generation starts. Analyzer continues generating until it finishes or until the StopUsb3Generation or PauseUsb3Generation method call is performed.

During generation, events are sent to the event sink (see the _IAnalyzerEvents interface section). The script file should have the file extension “.usb3g”. It can be created by either the USB Protocol Suite

text editor or any plain-text editor.

script is repeated.

- Script has compiling error.

- Analyzer is currently running or paused.

- Analyzer is currently used by another client.

- License for trainer device was not purchased.

- USB 2.0 generation is running.

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol Suite

Example

WSH (1):

See Automation\wsh\Usb3Exerciser.vbs

WSH(2):

Set Analyzer = WScript.CreateObject("CATC.UsbTracer", "Analyzer_")

' Tell the USB 3.0 Voyager Exerciser to start generation. Analyzer. StartUsb3Generation CurrentDir & " \Input\Usb3ScriptExample.usb3g"

Dim doneGeneration doneGeneration = 0

' Repeat Generation 49 more times. For RepeatCount = 1 To 49

WScript.Sleep 100

' Release the analyzer. WScript.DisconnectObject Analyzer

' WScript.Echo "USBAnalyzer object has been disconnected." Set Analyzer = Nothing

' WScript.Echo "Quitting WScript..." WScript.Quit

' Handler of the event fired when recorded trace is created ' (after recording and uploading). ' Sub Analyzer_OnStatusReport(ByVal subsystem, ByVal state, ByVal percent_done ) On Error Resume Next if state = 400 Then doneGeneration = 1 WScript.Echo "Generation finished" End If End Sub

VBScript:

On Error Resume Next Analyzer.StartUsb3Generation PathToScript.value If Err.Number <> 0 Then MsgBox Err.Number & ":" & Err.Description End If

Do While doneGeneration = 0

Loop Analyzer.StartUsb3Generation DoneGeneration = 0

<OBJECT

RUNAT=Server

ID = Analyzer

CLASSID = "clsid:136D64A4-3CD5-4b41-974A-C7039E3FC292" > </OBJECT>

...<INPUT TYPE=TEXT VALUE="" NAME="PathToScript"> ... ...<INPUT TYPE=BUTTON VALUE="" NAME="BtnStartUSB3Generaion"> ...

<SCRIPT LANGUAGE="VBScript"> <!-Sub BtnStartUSB3Generaion_OnClick

End Sub

--> </SCRIPT>

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol Suite

C++:

IUsbAnalyzerPtr usb_analyzer;

. . .

try { const char* gen_script_name = "C:\\Usb3ScriptExample.usb3g";

Usb_analyzer->StartUsb3Generation(_bstr_t( gen_script_name ) ); } catch (_com_error& er) {

if (er.Description().length() > 0)

::MessageBox( NULL, er.Description(), _T("USBAnalyzer client"), MB_OK );

else

::MessageBox( NULL, er.ErrorMessage(), _T("USBAnalyzer client"), MB_OK );

return 1; }

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

HRESULT StopUsb3Generation ();

Suite

2.1.15 IUsbAnalyzer::StopUsb3Generation

Stops USB 3.0 generation started by the StartUsb3Generation method. Parameters

Return values

Remarks

Stops generation started by the StartUsb3Generation method. Generation stops if the analyzer is either running or paused, and the analyzer then returns to the idle state.

Example

WSH:

Set Analyzer = WScript.CreateObject("CATC.UsbTracer", "Analyzer_")

' Tell the CATC USB analyzer to start generation.

Analyzer.StartUsb3Generation "example.usb3g"

WScript.Sleep 3000

' Tell the analyzer to stop recording.

Analyzer.StopUsb3Generation()

VBScript:

On Error Resume Next Analyzer.StopUsb3Generation If Err.Number <> 0 Then MsgBox Err.Number & ":" & Err.Description End If

ANALYZERCOMERROR_ANALYZERNOTCONNECTED Analyzer is not connected

<OBJECT

RUNAT=Server ID = Analyzer

CLASSID = "clsid:136D64A4-3CD5-4b41-974A-C7039E3FC292" > </OBJECT>

<SCRIPT LANGUAGE="VBScript"> <!-Sub BtnStopUsb3Generation_OnClick

End Sub

--> </SCRIPT>

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol Suite

C++:

IUsbAnalyzerPtr usb_analyzer;

. . .

try {

usb_analyzer ->StopUsb3Generation(); } catch (_com_error& er) {

if (er.Description().length() > 0)

::MessageBox( NULL, er.Description(), _T("UsbAnalyzer client"), MB_OK );

else

::MessageBox( NULL, er.ErrorMessage(), _T("UsbAnalyzer client"), MB_OK );

return 1; }

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

HRESULT PauseUsb3Generation ();

Suite

2.1.16 IUsbAnalyzer::PauseUsb3Generation

Pauses the currently running USB 3.0 generation.

Parameters

Return values

Remarks

Pauses the generation started by the StartUsb3Generation method. Generation pauses if the Exerciser is running. However, the pause command cannot immediately pause traffic generation in all cases. During execution of a generation script (.usb3g) file, some Send Packet instructions might be queued in an output FIFO, and then pausing only takes effect after this buffer empties.

Example

WSH:

Set Analyzer = WScript.CreateObject("CATC.UsbTracer", "Analyzer_")

' Tell the CATC USB analyzer to start generation.

Analyzer.StartUsb3Generation "some_example.usb3g"

WScript.Sleep 3000

' Tell the analyzer to stop recording.

Analyzer.PauseUsb3Generation

VBScript:

On Error Resume Next Analyzer.PauseUsb3Generation If Err.Number <> 0 Then MsgBox Err.Number & ":" & Err.Description End If

ANALYZERCOMERROR_ANALYZERNOTCONNECTED Analyzer is not connected ANALYZERCOMERROR_WRONGCALL Analyzer is not running

<OBJECT

RUNAT=Server ID = Analyzer

CLASSID = "clsid:136D64A4-3CD5-4b41-974A-C7039E3FC292" > </OBJECT>

<SCRIPT LANGUAGE="VBScript"> <!-Sub BtnPauseUsb3Generation_OnClick

End Sub

--> </SCRIPT>

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol Suite

C++:

IUsbAnalyzerPtr usb_analyzer;

. . .

try {

usb_analyzer->PauseUsb3Generation(); } catch (_com_error& er) {

if (er.Description().length() > 0)

::MessageBox( NULL, er.Description(), _T("UsbAnalyzer client"), MB_OK );

else

::MessageBox( NULL, er.ErrorMessage(), _T("UsbAnalyzer client"), MB_OK );

return 1; }

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

HRESULT ResumeUsb3Generation ();

Suite

2.1.17 IUsbAnalyzer::ResumeUsb3Generation

Resumes the USB 3.0 generation paused by the PauseUsb3Generation command. Parameters

Return values

Remarks

Resumes the generation paused by the PauseUsb3Generation method. The generation returns to the running state from the paused state.

Example

WSH:

Set Analyzer = WScript.CreateObject("CATC.UsbTracer", "Analyzer_")

' Tell the CATC USB analyzer to start generation.

Analyzer.StartUsb3Generation "example.Usbg"

WScript.Sleep 3000

' Tell the analyzer to stop recording.

Analyzer.PauseUsb3Generation() WScript.Sleep 3000 Analyzer.ResumeUsb3Generation()

VBScript:

On Error Resume Next Analyzer.ResumeUsb3Generation If Err.Number <> 0 Then MsgBox Err.Number & ":" & Err.Description End If

ANALYZERCOMERROR_ANALYZERNOTCONNECTED Analyzer is not connected

<OBJECT

RUNAT=Server ID = Analyzer

CLASSID = "clsid:136D64A4-3CD5-4b41-974A-C7039E3FC292" > </OBJECT>

<SCRIPT LANGUAGE="VBScript"> <!-Sub BtnResumeUsb3Generation_OnClick

End Sub

--> </SCRIPT>

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

HRESULT UsbUnplugPlug();

Suite

C++:

IUsb3AnalyzerPtr usb_analyzer;

. . .

try {

usb_analyzer->ResumeUsb3Generation(); } catch (_com_error& er) {

if (er.Description().length() > 0)

::MessageBox( NULL, er.Description(), _T("UsbAnalyzer client"), MB_OK );

else

::MessageBox( NULL, er.ErrorMessage(), _T("UsbAnalyzer client"), MB_OK );

return 1; }

2.1.18 IUsbAnalyzer::UsbUnplugPlug

Calling this method causes the VBus power between the Host and the Device connected through the Analyzer A and B USB ports to be broken for 1 second, simulating a unplug-plugin cycle. This is the recommended method of creating plug-in scenarios.

Parameters

Return values

Remarks

Example

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

HRESULT IssueManualTrig ();

Suite

2.2 IUsbAnalyzer3 interface

The IUsbAnalyzer3 interface is the third interface for the UsbAnalyzer object. It inherits and extends some analyzer-related functionality exposed via the IUsbAnalyzer interface.

IID : 1D96A60E-AA3A-45e1-B6D5-C6AA27E65910

2.2.1 IUsbAnalyzer3:: IssueManualTrig

Issues manual trigger event to cause force trigger in analyzer engine.

Parameters

Return values

Remarks Note that this method works with recording options that trigger mode is defined as manual trigger.

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

HRESULT GetRecordingStatus ( [out] VARIANT* is_trigged, [out] VARIANT* is_done);

HRESULT ResetUsb3Trainer ([in] int is_device_mode);

Suite

2.3 IUsbAnalyzer4 interface

The IUsbAnalyzer4 interface is the forth interface for the UsbAnalyzer object. It inherits and extends some analyzer-related functionality exposed via the IUsbAnalyzer interface.

IID : D793E9EE-58EE-4237-9D2A-41DBB61DCDF8

2.3.1 IUsbAnalyzer4::GetRecordingStatus

This method could be used to poll recording state of analyzer after recording start. The method returns useful running state information like happening trigger condition and recording finish. User may use this method to poll status of recording and go to next step according to polling result.

Parameters

is_trigged Pointer to boolean variable indicating analyzer triggered or not. is_done Pointer to boolean variable indicating recording process is finished or not

Return values

Remarks A new method named as WaitForRecordingStatus is added to Anlyzer interface that could be used

instead of this method. The new method doesn’t block software normal operation and recommended to

use new method.

ANALYZERCOMERROR_ANALYZERNOTCONNECTED Analyzer is not connected

2.3.2 IUsbAnalyzer4::ResetUsb3Trainer

This method reset and initialize analyzer unit in “Host” trainer or “Device” trainer modes without runnig any script.

Parameters

is_device_mode Specify desired mode.

“1” for “Device” mode, “0” for “Host” mode

Return values

Remarks

ANALYZERCOMERROR_ANALYZERNOTCONNECTED Analyzer is not connected

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

HRESULT IsUsb3GenerationIdle ([out] VARIANT* gen_idle);

HRESULT SwitchVBus ( [in] long switch_off);

Suite

2.3.3 IUsbAnalyzer4::IsUsb3GenerationIdle

This method could be used to poll generation state after starting generation. The method returns status of generation process. User may use this method to poll status of generation and go to next step according to polling result.

Parameters

gen_idle Pointer to boolean variable indicating generation is done or not.

Return values

ANALYZERCOMERROR_ANALYZERNOTCONNECTED Analyzer is not connected

Remarks

A new method named as WaitForUsb3GenerationIdle is added to Anlyzer interface that could be used instead of this method. The new method doesn’t block software normal operation and recommended to use new method.

2.3.4 IUsbAnalyzer4::SwitchVBus

This method provides facilty to switch on/off VBus in USB3 trainer without running any script.

Parameters

switch_off if “1” switch off VBus, other switch on VBus.

Return values

ANALYZERCOMERROR_ANALYZERNOTCONNECTED Analyzer is not connected

Remarks

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

HRESULT BindUnit ([in] WORD box_sn);

HRESULT MergeTraceFiles ( [in] BSTR file_name_1, [in] BSTR file_name_2, [in] BSTR output_file_name)

Suite

2.4 IUsbAnalyzer5 interface

The IUsbAnalyzer5 interface is the fifth interface for the UsbAnalyzer object. It inherits and extends some analyzer-related functionality exposed via the IUsbAnalyzer interface.

IID : 47CCA8A8-C4AC-4b90-ABD1-16DC2A5351FE

2.4.1 IUsbAnalyzer5::BindUnit

The method should be called when the API is used to control multiple anlayzer units. After creating any analyzer object (for each unit), it is required to bind analyzer object to desired unit by calling this method.

Parameters

box_sn Specifies target UNIT serial number.

Return values

ANALYZERCOMERROR_ANALYZERNOTCONNECTED Analyzer is not connected

ANALYZERCOMERROR_UNABLESTARTRECORDING Multiple Unit Autopmation

License is not available

Remarks

Activation of this feature requires specific license.

2.4.2 IUsbAnalyzer5::MergeTraceFiles

The method is used for merging two trace file in one trace.

Parameters

file_name_1 String parameter specifies first input file path file_name_2 String parameter specifies second input file path output_file_name String parameter specifies output file path

Return values

ANALYZERCOMERROR_UNABLETOMERGEFILES Unable to merge files, check files path and make sure they are not open

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

HRESULT WaitForUsb3GenerationIdle ( [in] long wait_time_milisec, [out] VARIANT* spent_time_milisec, [out] VARIANT* is_done);

HRESULT WaitForUsb3GenerationIdle ( [in] long wait_time_milisec, [in] long desired_status, [out] VARIANT* spent_time_milisec, [out] VARIANT* is_done);

Suite

2.5 IUsbAnalyzer6 interface

The IUsbAnalyzer6 interface is the sixth interface for the UsbAnalyzer object. It inherits and extends some analyzer-related functionality exposed via the IUsbAnalyzer interface.

IID : 866DA1BD-9AD4-4627-A32A-C0F229684300

2.5.1 IUsbAnalyzer6::WaitForUsb3GenerationIdle

The method is introduced as replacement for legacy method “IsUsb3GenerationIdle”. The method polls internally for generation running and returns when generation finishes. Method will return if specified timeout is passed and generation is still running to prevent hangs/block conditions.

Parameters

wait_time_milisec Specifies time-out for waiting before return in milliseconds spent_time_milisec Pointer to long value which returns spent time in this method is_done Pointer to boolean value indicating Generation done or time-out

happened

Return values

Remarks

ANALYZERCOMERROR_ANALYZERNOTCONNECTED Analyzer is not connected

2.5.2 IUsbAnalyzer6::WaitForRecordingStatus

The method is introduced as replacement for legacy method “GetRecordingStatus”. The method polls internally for analyzer running and returns when analyzer reaches to desired state(s). Method will return if specified timeout is passed and analyzer has not reached to desired state(s).

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol Suite

Parameters

wait_time_milisec Specifies time-out for waiting before return in milliseconds desired_state Specify desired analyzer state(s) [see remarks] to return from

method

spent_time_milisec Pointer to long value which returns spent time in this method is_done Pointer to boolean value indicating desired state has been

reached or time-out happened

Return values

ANALYZERCOMERROR_ANALYZERNOTCONNECTED Analyzer is not connected

Remarks

State value could be combination of following values:

RSTAT_DONE 0x4000

RSTAT_TRIGGERED 0x2000

RSTAT_WAITING_FOR_SYNC_REC 0x1000

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol Suite

3 Primary Dual Interface for Trace

3.1 IUsbTrace Dual Interface

IUsbTrace interface is the primary interface for the UsbTrace object. It derives from the ITrace

interface that implements the common functionality for all Teledyne LeCroy Analyzers.

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

HRESULT GetName (

[out, retval] BSTR* trace_name );

Suite

3.1.1 ITrace::GetName

Retrieves the trace name.

Parameters

trace_name Name of the trace

Return values

Remarks

This name can be used for presentation purposes.

Example

WSH:

C++: IUsbTrace* usb_trace;

. . .

{

TCHAR str_trace_name[256]; _tcscpy( str_trace_name, (TCHAR*)( bstr_trace_name) ); SysFreeString( bstr_trace_name );

Do not forget to free the string returned by this method call.

Set Analyzer = WScript.CreateObject("CATC.USBTracer") CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\")) Set Trace = Analyzer.MakeRecording (CurrentDir & "Input\test_ro.rec") MsgBox "Trace name " & Trace.GetName

_bstr_t bstr_trace_name; try

bstr_trace_name = usb_trace->GetName(); } catch ( _com_error& er) {

if (er.Description().length() > 0)

::MessageBox( NULL, er.Description(), _T("UsbAnalyzer client"), MB_OK );

else

::MessageBox( NULL, er.ErrorMessage(), _T("UsbAnalyzer client"), MB_OK );

return 1; }

::MessageBox( NULL, str_trace_name, _T("Trace name"), MB_OK );

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

HRESULT ApplyDisplayOptions (

[in] BSTR do_file_name );

Suite

3.1.2 ITrace::ApplyDisplayOptions

Applies the specified display options to the trace.

Parameters

do_file_name String providing the full pathname to display options file

Return values

Remarks

application. You can create such a file by selecting Setup – Display Options… from the USB Protocol Suite application menu, changing the display options in the dialog, and selecting the Save button.

Example

WSH:

C++:

IUsbTrace* usb_trace;

. . .

{

ANALYZERCOMERROR_UNABLELOADDO Unable to load display options file.

Use this method if you want to filter traffic of some type in the recorded or opened trace. The display options file is the file with extension .opt created by the USB Protocol Suite

TCHAR file_name[_MAX_PATH];

try

usb_trace->ApplyDisplayOptions( file_name ); } catch ( _com_error& er) {

if (er.Description().length() > 0)

::MessageBox( NULL, er.Description(), _T("UsbAnalyzer client"), MB_OK );

else

::MessageBox( NULL, er.ErrorMessage(), _T("UsbAnalyzer client"), MB_OK );

return 1; }

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

HRESULT Save (

[in] BSTR file_name, [in, defaultvalue(-1)] long packet_from, [in, defaultvalue(-1)] long packet_to );

Suite

3.1.3 ITrace::Save

Saves the trace into a file and allows you to save a range of packets.

Parameters

file_name String providing the full pathname to file where trace is saved packet_from Beginning packet number when you are saving a range of packets.

Value –1 means that the first packet of saved trace would be the first packet of this trace.

packet_to Ending packet number when you are saving a range of packets.

Value –1 means that the last packet of saved trace would be the last packet of this trace.

Return values

ANALYZERCOMERROR_UNABLESAVE Unable to save trace file.

Remarks

Use this method if you want to save a recorded or opened trace into a file. If display options

apply to this trace (see ITrace::ApplyDisplayOptions or IAnalyzer::LoadDisplayOptions), then hidden packets are not saved. If packet range is specified and it is invalid (for example packet_to is more then last packet number in the trace, or packet_from is less than first packet number in the trace, or packet_from is more then packet_to), then packet range adjusts automatically.

Example

WSH:

C++: IUsbTrace* usb_trace;

. . .

{

TCHAR file_name[_MAX_PATH]; LONG packet_from; LONG packet_to;

try

usb_trace->Save( file_name, packet_from, packet_to ); } catch (_com_error& er) {

if (er.Description().length() > 0)

::MessageBox( NULL, er.Description(), _T("UsbAnalyzer client"), MB_OK );

else

::MessageBox( NULL, er.ErrorMessage(), _T("UsbAnalyzer client"), MB_OK );

return 1; }

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

HRESULT ExportToText (

[in] BSTR file_name, [in, defaultvalue(-1)] long packet_from, [in, defaultvalue(-1)] long packet_to );

Suite

3.1.4 ITrace::ExportToText

Exports the trace into a text file and allows you to export a range of packets.

Parameters

Return values

Remarks

Use this method if you want to export a recorded or opened trace into a text file. If display options apply to this trace (see ITrace::ApplyDisplayOptions or IAnalyzer::LoadDisplayOptions), then hidden packets are not exported. If packet range is specified and it is invalid (for example, packet_to is more than last packet number in the trace, or packet_from is less than first packet number in the trace, or packet_from is more than packet_to), then packet range adjusts automatically.

file_name String providing the full pathname to file where trace is exported packet_from Beginning packet number when you are exporting a range of packets.

Value –1 means that the first packet of exported trace would be the first packet of this trace.

packet_to Ending packet number when you are exporting a range of packets.

Value –1 means that the last packet of exported trace would be the last packet of this trace.

ANALYZERCOMERROR_UNABLESAVE Unable to export trace file.

Here is a snippet of an export file for a Bluetooth Trace. A USB Trace file would look similar:

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol Suite

File E:\AnalyzerSw\Chief20\OfficialUTGFiles\SRP.usb. From Packet #13 to Packet #24.

Packet# _______|_______________________________________________________________________ 13_____| Dir(-->) Suspend( 37.000 ms) Time-stamp(00016.0097 3086) _______|_______________________________________________________________________ 14_____| Dir(-->) Reset( 3.017 µs) Time-stamp(00016.0393 3090) _______|_______________________________________________________________________ 15_____| Dir(-->) F(S) Sync(00000001) SOF(0xA5) Frame #(6) CRC5(0x09) _______| EOP(266 ns) Time-stamp(00016.0393 3336) _______|_______________________________________________________________________ 16_____| Dir(-->) F(S) Sync(00000001) SOF(0xA5) Frame #(7) CRC5(0x16) _______| EOP(266 ns) Time-stamp(00016.0401 3336) _______|_______________________________________________________________________ 17_____| Dir(-->) F(S) Sync(00000001) SOF(0xA5) Frame #(8) CRC5(0x06) _______| EOP(266 ns) Time-stamp(00016.0409 3336) _______|_______________________________________________________________________ 18_____| Dir(-->) F(S) Sync(00000001) SOF(0xA5) Frame #(9) CRC5(0x19) _______| EOP(266 ns) Time-stamp(00016.0417 3336) _______|_______________________________________________________________________ 19_____| Dir(-->) F(S) Sync(00000001) OUT(0x87) ADDR(2) ENDP(3) CRC5(0x0C) _______| EOP(266 ns) Time-stamp(00016.0417 3536) _______|_______________________________________________________________________ 20_____| Dir(-->) F(S) Sync(00000001) DATA0(0xC3)-BAD Data(8 bytes) _______| CRC16(0xBB29) EOP(266 ns) Time-stamp(00016.0417 3726) _______|_______________________________________________________________________ 21_____| Dir(<--) F(S) Sync(00000001) ACK(0x4B) EOP(266 ns) _______| Time-stamp(00016.0417 4256) _______|_______________________________________________________________________ 22_____| Dir(-->) F(S) Sync(00000001) SOF(0xA5) Frame #(10) CRC5(0x1B) _______| EOP(266 ns) Time-stamp(00016.0425 3336) _______|_______________________________________________________________________ 23_____| Dir(-->) F(S) Sync(00000001) SOF(0xA5) Frame #(11) CRC5(0x04) _______| EOP(266 ns) Time-stamp(00016.0433 3336) _______|_______________________________________________________________________ 24_____| Dir(-->) Suspend(0 ns) Time-stamp(00016.0457 3466) _______|_______________________________________________________________________

Example

WSH:

C++:

IUsbTrace* usb_trace;

. . .

{

TCHAR file_name[_MAX_PATH]; LONG packet_from; LONG packet_to;

try

usb_trace->ExportToText( file_name, packet_from, packet_to ); } catch (_com_error& er) {

if (er.Description().length() > 0)

::MessageBox( NULL, er.Description(), _T("UsbAnalyzer client"), MB_OK );

else

::MessageBox( NULL, er.ErrorMessage(), _T("UsbAnalyzer client"), MB_OK );

return 1; }

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

HRESULT Close ( );

Suite

3.1.5 ITrace::Close

Closes the trace.

Parameters

Return values

Remarks

Closes current trace but does not releases interface pointer. Call the IUnknown::Release method right after this method call. No ITrace method call succeeds after calling the ITrace::Close method.

(Currently there is no need to call ITrace::Close directly since IUnknown::Release closes the

trace.) Example

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

HRESULT ReportFileInfo (

[in] BSTR file_name );

Suite

3.1.6 ITrace::ReportFileInfo

Saves trace information into the specified text file.

Parameters

Return values

ANALYZERCOMERROR_UNABLESAVE Unable to create trace information report.

Remarks

Creates trace information file if necessary. Stores trace information in specified file. Here is an example of data stored using this method call:

File name : data.usb Comment : Recorded on Channel number : 0 Number of packets : 22514 Trigger packet number : 0 Recorded with application version 1.70 ( Build 102 ) Analyzer Serial Number 00213 Traffic Generation enabled Firmware version 1.06 ( ROM 1.02 ) BusEngine version 1.90 BusEngine type 1 UPAS Slot 1 Part# US005MA PlugIn ID: 0x01 Version 0x4 UPAS Slot 2 Part# US005MG PlugIn ID: 0x04 Version 0x4

Number of markers : 1

Recording Options: Options Name: Default Recording Mode: Snapshot Buffer Size: 2.000 MB Post-trigger position: 50% Base filename & path: E:\AnalyzerSw\Chief20\Debug_UPA\data.usb Save External Signals No Auto-Merge No Truncate Data No Devices setup for On-the-Go operation 2 DRD's: A device is named Camera, B device is named Printer Assumes first trace data is captured when A-Device is Host

Channel 0 Trace Speed Recording Mode: Full Speed Only Channel 0 Recording Events:

Channel 1 Trace Speed Recording Mode: Full Speed Only Channel 1 Recording Events:

Channel 0 is Full Speed. Recorded on product: USBTracer License information for the USBTracer unit, Serial Number 00213, used to record this trace file :

Software maintenance hasn't been enabled.

file_name String with full pathname to file where trace information report is created

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol Suite

Example

WSH:

C++: IUsbTrace* usb_trace;

{

TCHAR file_name[_MAX_PATH];

. . .

try

usb_trace->ReportFileInfo( file_name ); } catch ( _com_error& er) {

if (er.Description().length() > 0)

::MessageBox( NULL, er.Description(), _T("UsbAnalyzer client"), MB_OK );

else

::MessageBox( NULL, er.ErrorMessage(), _T("UsbAnalyzer client"), MB_OK );

return 1; }

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

HRESULT ReportErrorSummary (

[in] BSTR file_name );

Suite

3.1.7 ITrace::ReportErrorSummary

Saves trace error summary information into the specified text file.

Parameters

Return values

ANALYZERCOMERROR_UNABLESAVE Unable to create trace information report.

Remarks

Creates error summary file if necessary. Stores error summary in specified file. Here is an example of data stored using this method call:

Error report for SRP.usb recording file.

_______|_______________________________________________________________________ Bad PID (0): _______|_______________________________________________________________________ Bad CRC5 (0): _______|_______________________________________________________________________ Bad CRC16 (0): _______|_______________________________________________________________________ Bad Packet Length (0): _______|_______________________________________________________________________ Bad Stuff Bits (0): _______|_______________________________________________________________________ Bad EOP (0): _______|_______________________________________________________________________ Babble Start (0): _______|_______________________________________________________________________ Babble End (LOA) (0): _______|_______________________________________________________________________ Bad Frame Length (0): _______|_______________________________________________________________________ Bad Turnaround/Timeout (0): _______|_______________________________________________________________________ Bad Data Toggle (1): _______| 0.20; _______|_______________________________________________________________________ Bad Frame/uFrame Number (0): _______|_______________________________________________________________________ Analyzer Internal Error (0): _______|_______________________________________________________________________ Last Byte Incomplete (0): _______|_______________________________________________________________________

file_name String providing the full pathname to file where error summary report is created

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol Suite

Example

WSH:

C++: IUsbTrace* usb_trace;

{

TCHAR file_name[_MAX_PATH];

. . .

try

usb_trace->ReportErrorSummary( file_name ); } catch ( _com_error& er) {

if (er.Description().length() > 0)

::MessageBox( NULL, er.Description(), _T("UsbAnalyzer client"), MB_OK );

else

::MessageBox( NULL, er.ErrorMessage(), _T("UsbAnalyzer client"), MB_OK );

return 1; }

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

HRESULT ReportTrafficSummary(

[in] BSTR file_name );

Suite

3.1.8 ITrace::ReportTrafficSummary

Saves trace traffic summary information into the specified text file.

Parameters

file_name String providing the full pathname to file where traffic summary report is

Return values

ANALYZERCOMERROR_UNABLESAVE Unable to create or save traffic summary report.

Remarks

Creates traffic summary report file, if necessary. Stores traffic summary in the specified file. Here is an example of data stored using this method call:

Example

WSH:

C++: IUsbTrace* usb_trace;

TCHAR file_name[_MAX_PATH];

. . .

try

{

usb_trace->ReportTrafficSummary( file_name ); } catch ( _com_error& er) {

if (er.Description().length() > 0)

::MessageBox( NULL, er.Description(), _T("UsbAnalyzer client"), MB_OK );

else

::MessageBox( NULL, er.ErrorMessage(), _T("UsbAnalyzer client"), MB_OK );

return 1; }

created

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

HRESULT GetPacket (

[in] long packet_number, [in, out] VARIANT* packet, [out, retval] long* number_of_bits );

Suite

3.1.9 ITrace::GetPacket

Retrieves the raw packet representation.

Parameters

packet_number Number of packet to retrieve packet Raw packet representation number_of_bits Number of bits in raw packet representation

Return values

ANALYZERCOMERROR_INVALIDPACKETNUMBER Specified packet number is invalid

Remarks

The packet parameter has VT_ARRAY | VT_VARIANT actual automation type. Each element

of this array has VT_UI1 automation type. Since the last element of the array may contain extra data, you need to use the number_of_bits parameter to determine the actual packet data.

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol Suite

Example

VBScript:

Else

<OBJECT

ID = Analyzer

CLASSID = "clsid:0B179BB3-DC61-11d4-9B71-000102566088" > </OBJECT> <INPUT TYPE=TEXT NAME="TextPacketNumber"> <P ALIGN=LEFT ID=StatusText></P>

<SCRIPT LANGUAGE="VBScript"> <!-Function DecToBin(Param, NeedLen)

While Param > 0

Param = Param/2 If Param - Int(Param) > 0 Then

Res = CStr(1) + Res

Else

Res = CStr(0) + Res End If Param = Int(Param)

Wend DecToBin = Replace( Space(NeedLen - Len(Res)), " ", "0") & Res

End Function

Sub BtnGetPacket_OnClick

On Error Resume Next Dim Packet NumberOfBits = CurrentTrace.GetPacket (TextPacketNumber.value, Packet) If Err.Number <> 0 Then

MsgBox "GetPacket:" & Err.Number & ":" & Err.Description

For Each PacketByte In Packet

PacketStr = PacketStr & DecToBin(PacketByte, 8) & " "

NBytes = NBytes + 1 Next PacketStr = Left( PacketStr, NumberOfBits ) StatusText.innerText = "Packet ( " & NumberOfBits & " bits ): " & PacketStr

End If

End Sub

--> </SCRIPT>

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol Suite

C++: IUsbTrace* usb_trace; LONG packet_number;

. . .

VARIANT packet; VariantInit( &packet ); long number_of_bits; try { number_of_bits = usb_trace->GetPacket( packet_number, &packet ); } catch ( _com_error& er) { if (er.Description().length() > 0) ::MessageBox( NULL, er.Description(), _T("UsbAnalyzer client"), MB_OK ); else ::MessageBox( NULL, er.ErrorMessage(),_T("UsbAnalyzer client"), MB_OK ); return 1; }

if ( packet.vt == ( VT_ARRAY | VT_VARIANT) ) { SAFEARRAY* packet_safearray = packet.parray;

TCHAR packet_message[256]; TCHAR elem[64];

for ( long i=0; i<(long)packet_safearray->rgsabound[0].cElements; i++) { VARIANT var; HRESULT hr = SafeArrayGetElement(packet_safearray, &i, &var); if (FAILED(hr)) { ::MessageBox( NULL, _T("Error accessing array"), _T("UsbAnalyzer client"), MB_OK ); return 1; } if ( var.vt != ( VT_UI1) ) { ::MessageBox( NULL, _T("Array of bytes expected"), _T("UsbAnalyzer client"), MB_OK ); return 1; }

_stprintf( elem, _T("%02X "), V_UI1(&var) ); _tcscat( packet_message, elem ); } _stprintf( elem, _T("%d bits"), number_of_bits ); _tcscat( packet_message, elem );

::MessageBox( NULL, packet_message, _T("Raw packet bits"), MB_OK ); } else { ::MessageBox( NULL, _T("Invalid argument"), _T("UsbAnalyzer client"), MB_OK ); }

_stprintf( packet_message, _T("packet #%ld: "), packet_number );

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

HRESULT GetPacketsCount (

[out, retval] long* number_of_packets );

Suite

3.1.10 ITrace::GetPacketsCount

Retrieves total number of packets in the trace.

Parameters

number_of_packets Points to long value where number of packets in the

Return values Remarks Example

WSH:

C++: IUsbTrace* usb_trace;

. . .

long number_of_packets; long trigg_packet_num; try {

bstr_trace_name = usb_trace->GetName(); number_of_packets = usb_trace->GetPacketsCount(); trigg_packet_num = usb_trace->GetTriggerPacketNum();

}

catch ( _com_error& er)

{

if (er.Description().length() > 0) ::MessageBox( NULL, er.Description(), _T("UsbAnalyzer client"), MB_OK ); else ::MessageBox( NULL, er.ErrorMessage(),_T("UsbAnalyzer client"), MB_OK ); return 1;

}

TCHAR str_trace_name[256]; _tcscpy( str_trace_name, (TCHAR*)( bstr_trace_name) ); SysFreeString( bstr_trace_name );

TCHAR trace_info[256]; _stprintf( trace_info, _T("Trace:'%s', total packets:%ld, trigger packet:%ld"),

str_trace_name, number_of_packets, trigg_packet_num );

::SetWindowText( m_hwndStatus, trace_info );

trace is retrieved.

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

HRESULT GetTriggerPacketNum (

[out, retval] long* packet_number );

Suite

3.1.11 ITrace::GetTriggerPacketNum

Retrieves trigger packet number.

Parameters

Return values

Remarks

Example

WSH:

C++:

See an example for ITrace::GetPacketsCount.

packet_number Points to long value where trigger packet number is retrieved.

CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\")) Set Analyzer = WScript.CreateObject("CATC.USBTracer") Set Trace = Analyzer.MakeRecording (CurrentDir & "Input\test_ro.rec") TriggerPacket = Trace.GetTriggerPacketNum Trace.Save CurrentDir & "Output\trigger_portion.usb", CInt(ErrorPacket)-5,

CInt(ErrorPacket)+5

Trace.ExportToText CurrentDir & "Output\trigger_portion.txt", CInt(ErrorPacket)-5,

CInt(ErrorPacket)+5

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

HRESULT AnalyzerErrors (

[in] long error_type, [out, retval] IAnalyzerErrors** analyzer_errors );

Suite

3.1.12 ITrace::AnalyzerErrors

Retrieves trace file errors.

Parameters

long error_type Type of error collection you want to retrieve; the following values

are valid:

0x00000001 - Pid Error

0x00000002 - CRC5 Error

0x00000004 - CRC16 Error

0x00000008 - Packet Length Error

0x00000010 - Stuff Bit Error

0x00000020 – EOP Error

0x00000040 – Babble Start Error

0x00000080 – Babble End Error (LOA)

0x00000100 – Frame Length Error

0x00000200 – Handshake Timeout Error

0x00000400 – Analyzer Internal Error

0x00000800 – Data Toggle Error

0x00001000 – Microframe Error

analyzer_errors Address of a pointer to the AnalyzerErrors object primary

Return values

ANALYZERCOMERROR_INVALIDERROR Invalid error type specified

Remarks

AnalyzerErrors object is created via this method call, if call was successful.

0x00002000 – Short Byte Error (bits missing)

interface

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol Suite

3.2 IUsbTrace2 interface

The IUsbTrace2 interface is the second interface for the UsbTrace object. It inherits and extends some trace-related functionality exposed via the IUsbTrace interface.

IID : 149B95E9-C17D-43b3-AC0D-30419A485058

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

HRESULT GotoTime ( [in] double time );

Suite

3.2.1 IUsbTrace2::GotoTime

Instructs the trace view to jump to the specified timestamp.

Parameters

time Time (in nanoseconds) to jump

Example

WSH:

C++:

IUsbTrace2* Usb_trace;

. . .

{ double t = 1000000.0;

Set Analyzer = WScript.CreateObject("CATC.UsbTracer") CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\"))

Analyzer.StartRecording (CurrentDir & "test_ro.rec") '... Do something. Set Trace = Analyzer.StopRecordingAndWaitForTrace

Trace.GotoTime( 1000000 ) ' Go to 1 millisecond timestamp.

try

Usb_trace ->GotoTime( t ); } catch (_com_error& er) {

if (er.Description().length() > 0)

::MessageBox( NULL, er.Description(), _T("UsbAnalyzer client"), MB_OK );

else

::MessageBox( NULL, er.ErrorMessage(), _T("UsbAnalyzer client"), MB_OK );

return 1; }

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

HRESULT GotoUnit ([in] long level, [in] long index );

Suite

3.2.2 IUsbTrace2::GotoUnit

Instructs the trace view to jump to the specified transaction unit.

Parameters

level Transaction level

Possible values are: 0 = USB Packets 1 = USB Transactions 2 = USB Split Transactions 3 = USB Transfers 4 = Host WireAdapter Segments 5 = Host WireAdapter Transfers 6 = Device WireAdapter Segments 7 = Device WireAdapter Transfers 8 = PTP Transactions 9 = PTP Objects 10 = PTP Sessions

index Index of unit inside transaction level

Return values

ANALYZERCOMERROR_INVALIDPACKETNUMBER Unable to jump to specified transaction

unit: Either transaction level or

Example

WSH:

Set Analyzer = WScript.CreateObject("CATC.UsbTracer") CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\")) Analyzer.StartRecording (CurrentDir & "test_ro.rec") '... do something. Set Trace = Analyzer.StopRecordingAndWaitForTrace

Trace.GotoUnit( 3, 2 ) ' jumps to USB transfer #2

C++: IUsbTrace3* Usb_trace; . . .

try

{ int level = 3; // USB Transfers int index = 2;

Usb_trace ->GotoUnit( 3, 2 ); } catch (_com_error& er) {

if (er.Description().length() > 0)

::MessageBox( NULL, er.Description(), _T("UsbAnalyzer client"), MB_OK );

else

::MessageBox( NULL, er.ErrorMessage(), _T("UsbAnalyzer client"), MB_OK );

return 1; }

transaction index is invalid.

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

HRESULT ExportToCsv(

[in] BSTR file_name, [in] long level, [in, defaultvalue(-1)] long unit_from, [in, defaultvalue(-1)] long unit_to );

Suite

3.2.3 IUsbTrace2::ExportToCsv

Exports a trace into a text file in CSV format and allows exporting a range of packets.

Parameters

file_name String providing the full pathname of the trace export file level Transaction level

0 – Packets 1 – USB Transactions (Currently only these are supported.)

unit_from Beginning packet number when you are exporting a range of packets. Value –1

makes the first packet of the exported trace be the first packet of the trace.

unit_to Ending packet number when you are exporting a range of packets.

Value –1 makes the last packet of the exported trace be the last packet of the

Return values

ANALYZERCOMERROR_UNABLESAVE Unable to export trace file

Remarks

Use this method if you want to export a recorded or opened trace into a text file in CSV format. If display options apply to this trace (see ITrace::ApplyDisplayOptions or

IAnalyzer::LoadDisplayOptions), then hidden units would not be exported.

If a unit range is specified and it is invalid (for example, unit_to is more than the last unit number in the trace, or unit_from is less than first unit number in the trace, or unit_from is more then unit_to) then unit range adjusts automatically.

trace.

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol Suite

Example

WSH:

C++:

. . .

Set Analyzer = WScript.CreateObject("CATC.UsbTracer") CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\"))

' Please specify the real path to the trace file instead of 'C:\test.usb'. Set Trace = Analyzer.OpenFile ( "C:\test.usb" )

' Instructs the USB Protocol Suite application to locate packet # 15 ' (transaction level 0) in the trace viewer. Trace.GotoUnit 0, 15

' Instructs the USB Protocol Suite trace viewer to jump to the trace unit ' with the timestamp close to 6000 ns (6 microsecond). Trace.GotoTime 6000

' Exports USB transactions (from #0 to #10 ) into CSV format. ' 1st parameter - file name of the export file ' 2nd parameter - transaction level ( 0 - packets, 1 - transactions ) ' 3rd parameter - unit number to start with ' 4th parameter - unit number to end by Trace.ExportToCsv CurrentDir & "Output\text_csv_export.csv", 1, 0, 10

MsgBox "Done"

IUsbTrace2* usb_trace;

IAnalyzerErrors* analyser_errors; try {

analyser_errors = usb_trace-> ExportToCsv (_bstr_t( “c:\\test.csv” ),

1, 0 , 10 ) ; } catch (_com_error& er) {

if (er.Description().length() > 0) ::MessageBox( NULL, er.Description(), _T("UsbAnalyzer client"), MB_OK ); else ::MessageBox( NULL, er.ErrorMessage(),_T("UsbAnalyzer client"), MB_OK ); return 1;

}

. . .

analyser_errors->Release();

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

HRESULT SaveAs ( [in] BSTR file_name );

Suite

3.2.4 IUsbTrace2::SaveAs

Saves trace into a file and makes current IUsbTrace2 pointer refer to this file.

Parameters

Return values

Remarks

Use this method if you want to move a recorded or opened trace into a file. Example

WSH:

C++:

IUsbTrace2* USB_trace;

...

{

file_name String providing the full pathname to file in which trace is saved

ANALYZERCOMERROR_UNABLESAVE Unable to save trace file

Set Analyzer = WScript.CreateObject("CATC.UsbTracer") CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\")) Analyzer.StartRecording (CurrentDir & "Input\test_ro.rec")

'... Do something.

Set Trace = Analyzer.StopRecordingAndWaitForTrace Trace.SaveAs CurrentDir & "Output\saved_file.usb"

TCHAR file_name[_MAX_PATH]; LONG packet_from; LONG packet_to;

try

USB_trace->SaveAs( file_name ); } catch (_com_error& er) {

if (er.Description().length() > 0)

::MessageBox(NULL, er.Description(), _T("UsbAnalyzer client"), MB_OK);

else

::MessageBox(NULL, er.ErrorMessage(), _T("UsbAnalyzer client"), MB_OK);

return 1; }

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

HRESULT GetPowerInfoByTime ( [in] double time, [out] VARIANT* voltage, [out] VARIANT* current, [out] VARIANT* power, [out,retval] BOOL* power_info_is_valid );

HRESULT GetPowerInfoByPacket ( [in] long packet_number, [out] VARIANT* voltage, [out] VARIANT* current, [out] VARIANT* power, [out,retval] BOOL* power_info_is_valid );

Suite

3.3 IUsbTrace3 interface

The IUsbTrace3 interface is the third interface for the UsbTrace object. It inherits and extends some trace-related functionality exposed via the IUsbTrace3 interface.

IID : 4DA2A987-47B3-4384-BFA8-2052326FBE0E

3.3.1 IUsbTrace3:: GetPowerInfoByTime

Returns voltage, current, and power values based on a time in nanoseconds.

Parameters

time timestamp in nanoseconds voltage voltage in microvolts current current in microamps

Return values

Remarks

power power in microwatts.

BOOL TRUE if power values were recorded at the time.

3.3.2 IUsbTrace3:: GetPowerInfoByPacket

Returns voltage, current, and power values based on a packet number..

Parameters

packet_number Packet number in the trace file

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol Suite

voltage voltage in microvolts current current in microamps power power in microwatts.

Return values

BOOL TRUE if power values were recorded at that packet_number.

Remarks

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

HRESULT GetFullName( [out, retval] BSTR* trace_name )

Suite

3.4 IUsbTrace4 interface

The IUsbTrace4 interface is the forth interface for the UsbTrace object. It inherits and extends some trace-related functionality exposed via the IUsbTrace3 interface.

IID : C7D741F6-D425-417f-B7FC-4DB0FB01804B

3.4.1 IUsbTrace4:: GetFullName

Returns full path/name of trace file.

Parameters

trace_name Pointer to string to retrieve trace file full path

Return values

Remarks

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

HRESULT GetUsbPacket(

[in] long packet_number,

[out, retval] IDispatch** usb_packet )

Suite

3.5 IUsbTrace5 interface

The IUsbTrace5 interface is the fifth interface for the UsbTrace object. It inherits and extends some trace-related functionality exposed via the IUsbTrace4 interface.

IID : CAC0F43F-322E-4165-9BB6-E0DBDD95B682

3.5.1 IUsbTrace5::GetUsbPacket

Retrieves a pointer to the specified packet.

Parameters

Packet_number Number of packet to retrieve.

Return values

Remarks

Usb_packet Address of a pointer to the UsbPacket object primary interface.

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol Suite

3.6 IUsbVerificationScript Interface

The IUsbVerificationScript interface is the fourth interface for the UsbTrace object. It exposes the trace functionality for running verification scripts. It derives from the IVerificationScript interface, which implements the common functionality for running Teledyne LeCroy PSG verification scripts over recorded traces. This interface is not dual, so scripting languages cannot use it directly, though some or all of its methods are exposed to script languages through the primary UsbTrace automation interface.

IID : F1ED8DB5-2EC6-4fa0-8F8B-D645A1FA4A85 Remarks Verification scripts are special scripts written using Teledyne LeCroy PSG Script Language (CSL), which

can be “run” over the recorded trace to “verify” the trace for some verification conditions or to extract more advanced information from the trace. Such scripts utilize a special feature of the USB Protocol Suite application called the “Verification Script Engine”. This feature must be enabled for you to run verification scripts.

(For more information, refer to the USB Protocol Suite User Manual and the USB Protocol Suite VSEngine Manual.)

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

HRESULT RunVerificationScript ( [in] BSTR verification_script, [out, retval] VS_RESULT *pResult);

Suite

3.6.1 IUsbVerificationScript::RunVerificationScript

Runs verification script over the recorded trace.

Parameters

verification_script Name or full path of the verification script to run pResult Address of a variable in which to keep the result of

verification

VS_RESULT is an enumeration type that can have these possible meanings:

enum VS_RESULT { SCRIPT_RUNNING = -2, // Verification script is running. SCRIPT_NOT_FOUND = -1, // Verification script with the specified name was // not found. FAILED = 0, // Verification failed. PASSED = 1, // Verification passed. DONE = 2 // Verification is done, don’t care about result.

};

Return values S_OK If the verification script executed successfully. Remarks

The name of the verification script is the name of the verification script file (*.vse) without the file extension. For example, for verification script file test.vse, the test name is test. Please refer to the Teledyne LeCroy UWB Script Verification Engine Manual for details.

If a full path is specified (such as C:\test.vse), VSE uses it, instead of searching for the script by name in the \Scripts\VFScripts application subfolder.

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol Suite

Example

C++:

// In this example, use wrapper functions provided by #import directive.

IUsbTrace* trace; . . .

IUsbVerificationScript* vscript = NULL;

{

::MessageBox( NULL, "Test verification 1 is passed !!!", "UsbAnalyzer client", MB_OK );

. . .

WSH:

Set Analyzer = WScript.CreateObject("CATC.USBTracer")

Msgbox "PASSED"

Msgbox "FAILED"

if (SUCCEEDED (trace->QueryInterface( IID_IUsbVerificationScript, (void**)&vscript)) {

try

VS_RESULT result = vscript ->RunVerificationScript("Test1"); if(result == PASSED) {

} } catch (_com_error& er)

{

if (er.Description().length() > 0) ::MessageBox(NULL, er.Description(), "UsbAnalyzer client", MB_OK); else ::MessageBox(NULL, er.ErrorMessage(), "UsbAnalyzer client", MB_OK); return 1;

}

} else { ::MessageBox(NULL, "Unable to get IUsbVerificationScript interface !!!", _T("UsbAnalyzer client"), MB_OK); return 1 ; }

Set Trace = Analyzer.OpenFile("C:\Some trace files\some_trace.usb")

Dim Result Result = Trace.RunVerificationScript("Test1")

If Result = 1 Then

Else

End If

MsgBox("Done")

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

HRESULT GetVScriptEngine( [in] BSTR script_name, [out, retval] IVScriptEngine** pVSEngine );

Suite

3.6.2 IUsbVerificationScript::GetVScriptEngine

Retrieves a verification script engine object.

Parameters

script_name Name or full path of the verification script to initialize the script

verification engine

pVSEngine Address of a pointer to the VScriptEngine object primary interface

Return values S_OK If verification script engine object was successfully retrieved. Remarks

The name of the verification script is the name of the verification script file (*.vse) without the file extension. See remark to RunVerificationScript(…) for details.

Example

C++: // In this example, use wrapper functions provided by #import directive.

IusbTrace* Usb_trace; . . . IUsbVerificationScript* Usb_vscript = NULL;

assert(Usb_vscript != NULL);

::MessageBox( NULL, "Test verification 1 is passed !!!", "UsbAnalyzer client", MB_OK );

. . .

WSH:

Set Analyzer = WScript.CreateObject("CATC.USBTracer")

Set VSEngine = Trace.GetVScriptEngine("Test1") Result = VSEngine.RunVScript

Msgbox "PASSED"

Msgbox "FAILED"

Usb_trace->QueryInterface(IID_ IUsbVerificationScript, (void**)&Usb_vscript))

IVScriptEngine* Usb_vsengine = NULL; Usb_vsengine = Usb_vscript -> GetVScriptEngine("Test_1"); assert(Usb_vsengine != NULL);

VS_RESULT result = Usb_vsengine ->RunVScript(); if(result == PASSED) {

}

Set Trace = Analyzer.OpenFile("C:\Some trace files\some_trace.usb")

Dim Result

If Result = 1 Then

Else

End If MsgBox( "Done" )

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

HRESULT GetTimestamp ( [out, retval] double* timestamp )

HRESULT GetDuration( [out, retval] double* duration )

Suite

4 Primary Dual Interface for Packet

4.1 IUsbPacket Interface

The IUsbPacket interface is the primary dual interface for the UsbPacket object.

IID : C7D7C98D-6AB2-4a25-8235-CE2E1E7A5428

4.1.1 IUsbPacket::GetTimestamp

Gets the timestamp of packet in nanosecond.

Parameters

timestamp Points to double value where timestamp is retrieved

Return values Remarks

4.1.2 IUsbPacket::GetDuration

Gets the duration of packet in nanosecond.

Parameters

duration Points to double value where duration is retrieved

Return values Remarks

4.1.3 IUsbPacket::GetSpeed

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

HRESULT GetSpeed( [out, retval] int* speed )

HRESULT GetChannel( [out, retval] int* channel )

HRESULT GetType( [out] VARIANT* is_usb3, [out] VARIANT* is_bus_condition, [out, retval] int* type )

Suite

Gets the speed of packet.

Parameters

speed Points to integer value where speed is retrieved

Return values

Remarks

Speeds has following values: 0 : High Speed 1 : Full Speed 2 : Low Speed 3 : Unknown 4 : Super Speed

4.1.4 IUsbPacket::GetChannel

Gets the channel number of packet.

Parameters

Channel Points to integer value where channel is retrieved.

Return values Remarks

Channel has following values:

0 : Usb2 Channel 0

1 : Usb2 Channel 1

2 : Usb2 Channel 2 3 : Usb2 Channel 3 4 : Usb3 Rx Channel 0

5 : Usb3 Tx Channel 0

6 : Usb3 Rx Channel 1

7 : Usb3 Tx Channel 1

4.1.5 IUsbPacket::GetType

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol Suite

Gets the type of packet.

Parameters

is_usb3 Pointer to boolean variable indicating packet is usb3 or not.

is_bus_condition Pointer to boolean variable indicating packet is event or not. type Pointer to integer variable where type of packet is retrieved.

Return values Remarks

Type of packet has following values: USB3 Packets and Events:

0 : Unknown

1 : TSEQ 2 : TSX 3 : LFPS 4 : Electrical Idle 5 : IPS 6 : LC 7 : SKP 8 : HP 9 : DPP 10 : Logical Idle 11 : TS1 12 : TS2 13 : DP 14 : BRST 15 : BERC 16 : BCNT 17 : TERM 18 : Deferred Packet 19 : CP

USB2 Packets:

-1 : Unknown 0 : MDATA 1 : DATA2 2 : DATA1 3 : DATA0 4 : SETUP 5 : SOF 6 : IN 7 : OUT 8 : STALL 9 : NYET 10 : NAK 11 : ACK 12 : PRE & ERR 13 : PING 14 : SPLIT 15 : EXT 19 : LPM

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

HRESULT GetFieldValue( [in] BSTR field_name, [out] VARIANT* field_value ) [out, retval] VARIANT* field_value_bit_size )

HRESULT GetAllFieldsValues( [out] VARIANT* fields_names, [out] VARIANT* fields_values, [out] VARIANT* fields_values_bit_size,

Suite

USB2 Events:

-1 : Unknown 0 : Chirp K 1 : Chirp J

2 : Full Speed K On High Speed 3 : Full Speed J On High Speed 4 : Suspend 5 : Resume 6 : SE1 7 : SE0 27 : Connect 28 : VBUS Voltage Change 30 : Keep Alive 31 : Reset

4.1.6 IUsbPacket::GetFieldValue

Retrieves the value of specified field.

Parameters

field_name String providing the field name that its value is retrieved. field_value Pointer to DWORD or bytes array where field value is retrieved.

If the size of returned value is less than or equal to 4 bytes, the type is DWORD otherwise it is byte stream

field_value_bit_size Pointer to Integer variable where size of field value in bit is

retrived.

Return values Remarks

To retrieve available fields names in this packet call GetAllFieldsValues() function.

4.1.7 IUsbPacket::GetAllFieldsValues

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

[out, retval] int* fields_count ) HRESULT GetMarker( [out, retval] BSTR* marker )

HRESULT GetErrorsBitmap( [out, retval] VARIANT* errors_bitmap )

Suite

Retrieves the values of all available fields. It returns three arrays that contain name, value and size of fields.

Parameters

fields_names Array of strings containing fields names.

fields_values Array of DWORDs or bytes arrays containing fields values. If

size of field value is less than or equal to 4 bytes it is DWORD otherwise bytes array.

fields_values_bit_size Array of integers containing size of fields in bit. fields_count Pointer to integer variable containing count of fields.

Return values Remarks

The bit order and byte order are little-Endian for all fields always.

4.1.8 IUsbPacket::GetMarker

Retrieves the marker text of current packet.

Parameters

marker Pointer to string variable where marker text is retrieved.

Return values Remarks

4.1.9 IUsbPacket::GetErrorsBitmap

Retrieves the errors of packet.

Parameters

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol Suite

errors_bitmap Pointer to unsigned 64 bits integer variable where errors are retrieved.

Return values Remarks

Format of returned errors bitmap is as below: Bit 0 : Reserved

Bit 1 : USB2 PID Error Bit 2 : USB2 CRC5 Error Bit 3 : USB2 CRC16 Error Bit 4 : USB2 Packet Length Error Bit 5 : USB2 Bit Stuff Error Bit 6 : USB2 EOP Error Bit 7 : USB2 Babble Start Error Bit 8 : USB2 Babble End Error Bit 9 : USB2 Frame Length Error Bit 10 : USB2 Turnaround/Timeout Error Bit 11 : USB2 Analyzer Internal Error Bit 12 : USB2 Data Toggle Error Bit 13 : USB2 Frame/uFrame Number Error Bit 14 : USB2 Last Byte Incomplete Error Bit 15 : USB2 OTG Signal Error

Bit 16 : USB3 CRC5 Error Bit 17 : USB3 CRC16 Error Bit 18 : USB3 CRC32 Error Bit 19 : USB3 Disparity Error Bit 20 : USB3 10 Bit Symbol Error Bit 21 : USB3 Unknown Packet(IPS) Error Bit 22 : USB3 Framing Symbol Error Bit 23 : USB3 LC Data Symbol Error Bit 24 : USB3 Bad Header Packet Length Error Bit 25 : USB3 Bad Data Length Field Error Bit 26 : USB3 SKP Symbol Error Bit 27 : USB3 Control Endpoint Direction Error Bit 28 : USB3 Missed DPH Error Bit 29 : USB3 Missed DPP Error Bit 30 : USB3 Setup DP Error Bit 31 : USB3 Sequence Number Error

Bit 32 – 44 : Reserved Bit 45 : USB3 TP Non-Zero Reserved Error

Bit 46 : USB3 Missed ITP Error Bit 47 : USB3 Late/Early ITP Error

Bit 48 – 63 : Reserved

Note that below errors bits are valid after transaction level decoding: Bit 4 : USB2 Packet Length Error Bit 10 : USB2 Turnaround/Timeout Error Bit 12 : USB2 Data Toggle Error Bit 27 : USB3 Control Endpoint Direction Error Bit 46 : USB3 Missed ITP Error

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

HRESULT GetRawData( [out] VARIANT* raw_data_array, [out, retval] int* array_size )

HRESULT GetUsb3ScrambledData( [out] VARIANT* scrambled_data_array, [out, retval] int* array_size )

Suite

Bit 47 : USB3 Late/Early ITP Error

4.1.10 IUsbPacket::GetRawData

Retrieves the marker text of current packet.

Parameters

raw_data_array Array of bytes where raw data of packet is retrieved. array_size Pointer to integer variable containing returned bytes count.

Return values Remarks

For bus conditions returned array is empty.

4.1.11 IUsbPacket::GetUsb3ScrambledData

Retrieves the scrambled raw packet representation of USB3 packets.

Parameters

scrambled_data_array Bytes array variable where scrambled bytes of packet are

retrieved.

array_size Pointer to integer variable containing count of returned bytes.

Return values Remarks

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

HRESULT GetUsb3TenBitData( [out] VARIANT* symbles_array, [out, retval] int* array_size )

Ten Bit Symbol

Running Disparity

Invalid

Symbol

Error

Suite

4.1.12 IUsbPacket::GetUsb3TenBitData

Retrieves the ten bit symbols of USB3 packets. Parameters

symbles_array Array of DWORDs containing returned symbols. array_size Pointer to integer variable containing count of returned symbols.

Return values Remarks

Format of returned symbols are as below:

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol Suite

5 Primary Dual Interface for USB Verification Script

Engine

5.1 IVScriptEngine interface

The IVScriptEngine interface is the primary dual interface for the UsbVScriptEngine object. It implements the common functionality for the Teledyne LeCroy PSG verification script engine (VSE). The main advantage of the IVScriptEngine interface is that it allows clients to implement the _IVScriptEngineEvents callback interface to receive notifications when a verification script is running.

IID : 67FC41C6-0FEE-4b95-8EE0-A5724661FE98

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

[propget] HRESULT VScriptName([out, retval] BSTR *pVal);

[propput] HRESULT VScriptName([in] BSTR newVal);

Suite

5.1.1 IVScriptEngine::VscriptName

Property putting and getting current verification script name.

Parameters

*pVal Address of variable in which to store current verification script name newVal Name of the verification script to initialize script verification engine

Return values

Remarks

The name of the verification script is the name of the verification script file (*.vse) without the file extension.

Example

C++:

// In this example, use wrapper functions provided by #import directive.

IUsbTrace* usb_trace;

. . .

IUsbVerificationScript* usb_vscript = NULL;

assert( usb_vscript != NULL );

}

. . .

usb_trace->QueryInterface( IID_ IUsbVerificationScript, (void**)&usb_vscript ) )

IVScriptEngine* usb_vsengine = NULL; usb_vsengine = usb_vscript -> GetVScriptEngine("Blah"); assert( usb_vsengine != NULL );

usb_vsengine -> put_VScriptName("Test_1"); assert( usb_vsengine -> GetVScriptName() == "Test_1" );

VS_RESULT result = usb_vsengine ->RunVScript(); if( result == PASSED ) { ::MessageBox( NULL, "Test 1 passed !!!", "UsbAnalyzer client", MB_OK );

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

[propget] HRESULT Tag([out, retval] int* pVal);

[propput] HRESULT Tag([in] int newVal);

Suite

5.1.2 IVScriptEngine::Tag

Property assigning and getting a tag to the VSE object. This tag is used in event notifications, allowing a client event handler to determine which VSE object sent the event.

Parameters

*pVal Address of variable in which to store current VSE tag newVal New tag for VSE

Return values

Remarks

Example

C++:

// In this example, use wrapper functions provided by #import directive.

IUsbTrace* usb_trace;

. . .

IUsbVerificationScript* usb_vscript = NULL;

assert( usb_vscript != NULL );

}

. . .

usb_trace->QueryInterface( IID_ IUsbVerificationScript, (void**)&usb_vscript ) )

IVScriptEngine* usb_vsengine = NULL; usb_vsengine = usb_vscript -> GetVScriptEngine("Test_1"); assert( usb_vsengine != NULL );

usb_vsengine ->put_Tag( 0xDDAADDAA ); assert( usb_vsengine -> GetTag() == 0xDDAADDAA );

VS_RESULT result = usb_vsengine ->RunVScript(); if( result == PASSED ) { ::MessageBox( NULL, "Test 1 passed !!!", "UsbAnalyzer client", MB_OK );

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

HRESULT RunVScript([out, retval] int* pResult);

Suite

5.1.3 IVScriptEngine::RunVScript

Runs verification script.

Parameters

pResult Address of variable in which to store the result of verification.

Return values

Remarks

This method makes a “synchronous” call, so this method does not return until the script stops running.

Example

See C++ example to VScriptName.

See IUsbVerificationScript::RunVerificationScript method for details.

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

HRESULT RunVScriptEx([in] BSTR script_name, [out, retval] int* pResult);

Suite

5.1.4 IVScriptEngine::RunVScriptEx

Changes the current verification script name and runs verification script.

Parameters

script_name Name of the verification script to initialize script verification engine. PResult Address of variable in which to store the result of verification.

Return values

Remarks

This method makes a “synchronous” call, so this method does not return until the script stops running.

Example

C++:

// In this example, use wrapper functions provided by #import directive.

IUwbTrace* usb_trace;

. . .

IUsbVerificationScript* usb_vscript = NULL;

usb_trace->QueryInterface( IID_ IUsbVerificationScript, (void**)&usb_vscript ) )

assert( usb_vscript != NULL );

IVScriptEngine* usb_vsengine = NULL; usb_vsengine = usb_vscript -> GetVScriptEngine("Test_1"); assert( usb_vsengine != NULL );

VS_RESULT result = usb_vsengine ->RunVScript(); if( result == PASSED ) {

::MessageBox( NULL, "Test 1 passed !!!", "UsbAnalyzer client", MB_OK );

}

result = usb_vsengine ->RunVScriptEx("Test_2"); if( result == PASSED ) {

::MessageBox( NULL, "Test 2 passed !!!", "UsbAnalyzer client", MB_OK );

}

result = usb_vsengine ->RunVScriptEx("Test_3"); if( result == PASSED ) {

::MessageBox( NULL, "Test 3 passed !!!", "UsbAnalyzer client", MB_OK );

}

. . .

See IUsbVerificationScript::RunVerificationScript method for details.

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

HRESULT LaunchVScript();

Suite

5.1.5 IVScriptEngine::LaunchVScript

Launches verification script.

Parameters

Return values

S_FALSE If VS Engine was not successfully launched

Remarks

This method makes an “asynchronous” call, so this method immediately returns after the script starts

running. When the verification script stops running, the VSE object sends a special event notification

“OnVScriptFinished” to the client event handler. You can also terminate script running using the method “Stop”.

Example

C++:

// In this example, use wrapper functions provided by #import directive.

IUsbTrace* usb_trace;

. . .

IUsbVerificationScript* usb_vscript = NULL;

usb_trace->QueryInterface( IID_ IUsbVerificationScript, (void**)&usb_vscript ) )

assert( usb_vscript != NULL );

IVScriptEngine* usb_vsengine = NULL; usb_vsengine = usb_vscript -> GetVScriptEngine("Test_1"); assert( usb_vsengine != NULL );

VS_RESULT result = usb_vsengine ->LaunchVScript();

// You can go further without waiting for the result from the VSE object. // If you are interested in the result, implement the client event handler for // OnVScriptFinished() notification.

. . .

(either it is already running or verification script was not found).

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

HRESULT Stop();

Suite

5.1.6 IVScriptEngine::Stop

Stops verification script previously launched by the IVScriptEngine::LaunchVScript method.

Parameters

Return values

Remarks

Example

C++:

// In this example, use wrapper functions provided by #import directive.

IUsbTrace* usb_trace;

. . .

IUsbVerificationScript* usb_vscript = NULL;

assert( usb_vscript != NULL );

. . .

if( NotEnoughResourcesToProcessVS ) usb_vsengine ->Stop();

. . .

usb_trace->QueryInterface( IID_ IUsbVerificationScript, (void**)&usb_vscript ) )

IVScriptEngine* usb_vsengine = NULL; usb_vsengine = usb_vscript -> GetVScriptEngine("Test_1"); assert( usb_vsengine != NULL );

VS_RESULT result = usb_vsengine ->LaunchVScript();

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

HRESULT GetScriptVar ( [in] BSTR var_name, [out, retval] VARIANT* var_value )

Suite

5.1.7 IVScriptEngine::GetScriptVar

Returns the value of some verification script variable before/after executing the script. The resulting value may contain an integer, a string, or an array of VARIANTs (if the requested script variable is a list object – see the CSL Manual for more details about list objects).

Parameters

var_name String providing the name of the global variable or constant

var_value Address of a VARIANT variable in which result will be stored.

Return values

E_PENDING If this method is called when script running is in progress

Remarks

If there is no such global variable or constant with the name 'var_name', the resulting value contains an empty VARIANT.

used in the running verification script.

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol Suite

Example

C++:

// In this example, use wrapper functions provided by #import directive.

IUsbTrace* usb_trace;

. . .

IUsbVerificationScript* usb_vscript = NULL;

assert( usb_vscript != NULL );

. . .

VARIANT my_var; VariantInit( &my_var );

usb_vsengine->GetScriptVar( _bstr_t("MyVar"), &my_var );

if( my_var.vt == VT_BSTR ) ProcessString( my_var.bstrVal );

. . .

WSH:

. . .

Set Trace = Analyzer.OpenFile( TraceName ) ' Open the trace.

Result = VSEngine.RunVScript

MyIntVar = VSEngine.GetScriptVar( "MyIntVar" ) ' Suppose MyVar contains an integer MyStrVar = VSEngine.GetScriptVar( "MyStrVar" ) ' Suppose MyVar contains a string.

MsgBox " MyIntVar = " & CStr(MyIntVar) & ", MyStrVar = " & MyStrVar

usb_trace->QueryInterface( IID_ IUsbVerificationScript, (void**)&usb_vscript ) )

IVScriptEngine* usb_vsengine = NULL; usb_vsengine = usb_vscript -> GetVScriptEngine("Test_1"); assert( usb_vsengine != NULL );

VS_RESULT result = usb_vsengine ->RunVScript();

Set VSEngine = Trace.GetVScriptEngine( VScript ) ' Get VS Engine object.

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

HRESULT SetScriptVar ( [in] BSTR var_name, [in] VARIANT var_value )

Suite

5.1.8 IVScriptEngine::SetScriptVar

Allows you to set the value of some verification script variable before/after executing the script. Only integers, strings, or arrays of VARIANTs are allowed. Arrays of VARIANTs are converted into list values inside of scripts – see the CSL Manual for more details about list objects.

Parameters

var_name String providing the name of the global variable used in the

var_value VARIANT value containing new variable value.

Return values

E_PENDING If this method is called when script running is in progress.

Remarks

This function allows you to set internal script variables before/after script run, so you can make run-time customizations from COM/Automation client applications.

If there is no such global variable with the name 'var_name', a new variable with that name is created.

running verification script.

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol Suite

Example

C++:

// In this example, use wrapper functions provided by #import directive.

IUsbTrace* usb_trace;

. . .

IUsbVerificationScript* usb_vscript = NULL;

assert( usb_vscript != NULL );

. . .

WSH:

. . . Set Trace = Analyzer.OpenFile( TraceName ) ' Open the trace.

VSEngine.SetScriptVar( "MyIntVar" , 100 ) VSEngine.SetScriptVar( "MyStrVar" , "Hello !!!" ) Result = VSEngine.RunVScript

usb_trace->QueryInterface( IID_ IUsbVerificationScript, (void**)&usb_vscript ) )

IVScriptEngine* usb_vsengine = NULL; usb_vsengine = usb_vscript -> GetVScriptEngine("Test_1"); assert( usb_vsengine != NULL );

VARIANT my_var; VariantInit( &my_var );

my_var.vt = VT_I4; // Integer my_var.lVal = 100;

// Set internal script variable 'MyVar' to 100. usb_vsengine->SetScriptVar( _bstr_t("MyVar"), my_var );

VS_RESULT result = usb_vsengine ->RunVScript();

Set VSEngine = Trace.GetVScriptEngine( VScript ) ' Get VS Engine object.

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol Suite

6 Verification Script Engine Events Callback

Interface

6.1 _IVScriptEngineEvents dispinterface

To retrieve the event notifications from the UsbAnalyzer application when a verification script engine object is running a script, you must implement the _IVScriptEngineEvents callback interface.

Because this interface is a default source interface for the IVScriptEngine object, there is a very simple implementation from such languages as Visual Basic, VBA, VBScript, and WSH.

Remarks

Some script engines impose restrictions on handling events from “indirect” automation objects in

typeless script languages (when the automation interface to the object is obtained from a call of some method, rather than from a creation function – like CreateObject() in VBScript). Teledyne LeCroy PSG USB Protocol Suite™ provides a special COM class that allows receiving and handling notifications from VSE objects, even in script languages not supporting event handling from "indirect" objects. (Please refer to CATCAnalyzerAdapter for details.)

Example The C++ implementation used in the examples below implements an event sink object by deriving from

IDispEventImpl but not specifying the type library as a template argument. Instead, the type library and default source interface for the object are determined using AtlGetObjectSourceInterface(). A SINK_ENTRY() macro is used for each event from each source interface to be handled:

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol Suite

C++:

class CVSEngineSink : public IDispEventImpl<IDC_SRCOBJ_VSE, CVSEngineSink > { public: . . .

BEGIN_SINK_MAP(CVSEngineSink) // Make sure the Event Handlers have __stdcall calling convention. SINK_ENTRY( IDC_SRCOBJ_VSE, 1, OnVScriptReportUpdated ) SINK_ENTRY( IDC_SRCOBJ_VSE, 2, OnVScriptFinished )

END_SINK_MAP()

HRESULT __stdcall OnVScriptReportUpdated ( BSTR newLine, int TAG ); HRESULT __stdcall OnVScriptFinished( BSTR script_name, VS_RESULT result, int TAG ); HRESULT __stdcall OnNotifyClient ( int eventId, VARIANT eventBody, int TAG );

HRESULT Advise(IUnknown* pUnk) { AtlGetObjectSourceInterface(pUnk, &m_libid, &m_iid, &m_wMajorVerNum, &m_wMinorVerNum); return DispEventAdvise(pUnk, &m_iid); }

HRESULT Unadvise(IUnknown* pUnk) { AtlGetObjectSourceInterface(pUnk, &m_libid, &m_iid, &m_wMajorVerNum, &m_wMinorVerNum); return DispEventUnadvise(pUnk, &m_iid); } ...

};

SINK_ENTRY( IDC_SRCOBJ_VSE, 3, OnNotifyClient )

Then, after you establish the connection with the server, you need to advise your implementation of the event interface:

IVScriptEngine vscript_engine = NULL;

try { vscript_engine = vscript ->GetVScriptEngine( "Test_1" ); } catch ( _com_error& er ) { SetStatusError( er ); }

if( vscript_engine == NULL ) { vscript = NULL; return E_FAIL; }

CVSEngineSink vse_sink; HRESULT hr = vse_sink . Advise( vscript_engine ); // “Subscribe” for receiving events ... VS_RESULT res = SCRIPT_NOT_FOUND; try { res = (VS_RESULT)vscript_engine ->RunVScript(); } catch ( _com_error& er) { SetStatusError( er ); }

// Tear connection with the test case. vse_sink. Unadvise( vscript_engine ); ...

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol Suite

VBA: ( MS Excel )

Public USBTracer As UsbAnalyzer Public Trace As UsbTrace Public GVSEngine As VScriptEngine

' ' VSEngineEventsModule is a special class implementing VSE event handlers. ' It should have, in global declaration section, a line like this: ' Public WithEvents VSEEvents As VScriptEngine ' Dim X As New VSEngineEventsModule

Private Sub RunVScritButton_Click() Dim VSEngine As VScriptEngine Dim IVScript As IUsbVerificationScript Dim ScriptName, fileToOpen As String

ScriptName = ThisWorkbook.Sheets("Sheet1").Cells(2, 2)

Set VSEngine = IVScript.GetVScriptEngine( ScriptName )

Set X.VSEEvents = VSEngine ...

VSEngine.Tag = 12 ' Assign a tag for VSE object. VSEngine.RunVScript ' Run verification script.

Set X.VSEEvents = Nothing ' "Unsubscribe" for receiving VSE events. Set VSEngine = Nothing ' Release external Set IVScript = Nothing ' objects.

End Sub

If USBTracer Is Nothing Then

Set USBTracer = New UsbAnalyzer

If USBTracer Is Nothing Then

MsgBox "Unable to connect to USB Protocol Suite", vbExclamation

Exit Sub

End If

fileToOpen = ThisWorkbook.Sheets("Sheet1").Cells(1, 2) Set Trace = USBTracer.OpenFile( fileToOpen )

Set IVScript = Trace 'Get the IUsbVerificationScript interface.

' "Subscribe" for receiving VSE events. ' the X variable ( an instance of VSEngineEventsModule class ) will handle them.

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

[id(1)] HRESULT OnVScriptReportUpdated([in] BSTR newLine,

[in] int TAG );

Suite

6.1.1 _IVScriptEngineEvents::OnVScriptReportUpdated

Fires when running verification script calls ReportText( newLine ) function. Parameters

newLine New portion of text reported by verification script

Return values

Remarks

Example

C++:

}

VBA (MS Excel):

(ByVal newLine As String, ByVal Tag As Long)

TAG VSE object's tag

Make sure that C++ event handlers have __stdcall calling convention.

HRESULT __stdcall OnVScriptReportUpdated (BSTR newLine, int TAG ) { TRACE( "Line: %s, TAG: %d\n", newLine, TAG ); . . .

return S_OK;

Public WithEvents VSEEvents As VScriptEngine Public LineIndex As Integer

. . .

Private Sub VSEEvents_OnVScriptReportUpdated

ThisWorkbook.Sheets("Sheet1").Cells(LineIndex, 1) = newLine LineIndex = LineIndex + 1

End Sub

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

[id(2)] HRESULT OnVScriptFinished ( [in] BSTR script_name, [in] VS_RESULT result, [in] int TAG );

Suite

6.1.2 _IVScriptEngineEvents::OnVScriptFinished

Fires when the verification script stops running.

Parameters

script_name Name of the verification script result Result of the "verification"

(See IUsbVerificationScript::RunVerificationScript for details.)

Return values

Remarks

Example

C++:

( BSTR script_name, VS_RESULT result, int TAG )

USES_CONVERSION;

TCHAR tmp[220]; sprintf( tmp, "Script completed, name : %s, result = %d, TAG = %d", W2A(script_name), result, TAG ); . . . return S_OK;

VBA (MS Excel):

ByVal result As UWBAutomationLib.VS_RESULT, ByVal Tag As Long )

", TAG = " & CStr(Tag)

TAG VSE object's tag

Make sure that C++ event handlers have __stdcall calling convention.

HRESULT __stdcall CComplTestSink::OnVScriptFinished

{

}

Public WithEvents VSEEvents As VScriptEngine . . .

Private Sub VSEEvents_OnVScriptFinished( ByVal script_name As String,

Dim ResString As String ResString = "Script name : " & script_name & ", result = " & CStr(result) &

ThisWorkbook.Sheets("Sheet1").Cells(7, 2) = ResString

End Sub

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol

[id(3)] HRESULT OnNotifyClient( [in] int eventId, [in] VARIANT eventBody, [in] int TAG );

Suite

6.1.3 _IVScriptEngineEvents::OnNotifyClient

Fires when running verification script calls NotifyClient() function. Parameters

EventId Event Id eventBody Body of event packed in a VARIANT object

Return values

Remarks

The information packed in the event body is opaque for VSE, which only packs the information given to NotifyClient() function inside of a verification script into a VARIANT object and sends it to client applications. (See Teledyne LeCroy PSG USB Verification Script Engine Manual for details about the NotifyClient() script function.)

Example

Teledyne LeCroy PSG USB Verification script:

. . .

TAG VSE object's tag

ProcessEvent() {

NotifyClient( 2, [in.Index, in.Level, GetChannelName(), GetEventName(), TimeToText( in.Time )] ); . . . }

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol Suite

VBA (MS Excel):

ByVal eventBody As Variant, ByVal Tag As Long )

Public WithEvents VSEEvents As VScriptEngine . . .

Private Sub VSEEvents_OnNotifyClient( ByVal eventId As Long,

Dim Col As Integer Dim Item As Variant

ThisWorkbook.Sheets("Sheet1").Cells(LineIndex, 1) = eventId

If IsArray(eventBody) Then Col = 3

For Each Item In eventBody ThisWorkbook.Sheets("Sheet1").Cells(LineIndex, Col) = Item Col = Col + 1 Next Else ThisWorkbook.Sheets("Sheet1").Cells(LineIndex, 2) = eventBody End If

LineIndex = LineIndex + 1

End Sub

Teledyne LeCroy Automation API Reference Manual for USBTracer, USB Advisor, and Voyager USB Protocol Suite

7 Primary Dual Interface for Recording

Options

7.1 IUsbRecOptions Dual Interface

The IUsbRecOptions interface is the primary interface for the IBRecOption object. It derives from the IRecOptions interface that implements the common functionality for all Teledyne LeCroy Analyzers.

100

Teledyne USB Analyzer Automation User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual

1 Introduction

1.1 System Requirements

1.2 Setting Up Automation for Local Use

1.3 Setting Up Automation for Remote Use

2 Primary Dual Interface for Analyzer

2.1 IUsbAnalyzer Dual Interface

2.1.1 IAnalyzer::GetVersion

2.1.2 IAnalyzer::GetSerialNumber

2.1.3 IAnalyzer::OpenFile

2.1.4 IAnalyzer::StartGeneration

2.1.5 IAnalyzer::StopGeneration

2.1.6 IAnalyzer::StartRecording

2.1.7 IAnalyzer::StopRecording

2.1.8 IAnalyzer::MakeRecording

2.1.9 IAnalyzer::LoadDisplayOptions

2.1.10 IAnalyzer::GetRecordingOptions

2.1.11 IUsbAnalyzer::StopRecordingAndWaitForTrace

2.1.12 IUsbAnalyzer::get_ApplicationFolder (property)

2.1.13 IUsbAnalyzer::get_ApplicationDataFolder (property)

2.1.14 IUsbAnalyzer::StartUsb3Generation

2.1.15 IUsbAnalyzer::StopUsb3Generation

2.1.16 IUsbAnalyzer::PauseUsb3Generation

2.1.17 IUsbAnalyzer::ResumeUsb3Generation

2.1.18 IUsbAnalyzer::UsbUnplugPlug

2.2 IUsbAnalyzer3 interface

2.2.1 IUsbAnalyzer3:: IssueManualTrig

2.3 IUsbAnalyzer4 interface

2.3.1 IUsbAnalyzer4::GetRecordingStatus

2.3.2 IUsbAnalyzer4::ResetUsb3Trainer

2.3.3 IUsbAnalyzer4::IsUsb3GenerationIdle

2.3.4 IUsbAnalyzer4::SwitchVBus

2.4 IUsbAnalyzer5 interface

2.4.1 IUsbAnalyzer5::BindUnit

2.4.2 IUsbAnalyzer5::MergeTraceFiles

2.5 IUsbAnalyzer6 interface

2.5.1 IUsbAnalyzer6::WaitForUsb3GenerationIdle

2.5.2 IUsbAnalyzer6::WaitForRecordingStatus

3 Primary Dual Interface for Trace

3.1 IUsbTrace Dual Interface

3.1.1 ITrace::GetName

3.1.2 ITrace::ApplyDisplayOptions

3.1.3 ITrace::Save

3.1.4 ITrace::ExportToText

3.1.5 ITrace::Close

3.1.6 ITrace::ReportFileInfo

3.1.7 ITrace::ReportErrorSummary

3.1.8 ITrace::ReportTrafficSummary

3.1.9 ITrace::GetPacket

3.1.10 ITrace::GetPacketsCount

3.1.11 ITrace::GetTriggerPacketNum

3.1.12 ITrace::AnalyzerErrors

3.2 IUsbTrace2 interface

3.2.1 IUsbTrace2::GotoTime

3.2.2 IUsbTrace2::GotoUnit

3.2.3 IUsbTrace2::ExportToCsv

3.2.4 IUsbTrace2::SaveAs

3.3 IUsbTrace3 interface

3.3.1 IUsbTrace3:: GetPowerInfoByTime

3.3.2 IUsbTrace3:: GetPowerInfoByPacket

3.4 IUsbTrace4 interface

3.4.1 IUsbTrace4:: GetFullName

3.5 IUsbTrace5 interface

3.5.1 IUsbTrace5::GetUsbPacket

3.6 IUsbVerificationScript Interface

3.6.1 IUsbVerificationScript::RunVerificationScript

3.6.2 IUsbVerificationScript::GetVScriptEngine

4 Primary Dual Interface for Packet

4.1 IUsbPacket Interface

4.1.1 IUsbPacket::GetTimestamp

4.1.2 IUsbPacket::GetDuration

4.1.3 IUsbPacket::GetSpeed

4.1.4 IUsbPacket::GetChannel

4.1.5 IUsbPacket::GetType

4.1.6 IUsbPacket::GetFieldValue

4.1.7 IUsbPacket::GetAllFieldsValues

4.1.8 IUsbPacket::GetMarker