Teledyne Automation API User Manual

Protocol Solutions Group

3385 Scott Blvd., Santa Clara, CA 95054

Tel: [phone]

Fax: [phone]

Automation API

for

Teledyne LeCroy PETracer/PETrainer™

Reference Manual

For PETracer/Trainer Software Version 7.x

January 2014

Teledyne LeCroy Automation API for PETracer/PETrainer

ii

Document Disclaim er

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

Teledyne LeCroy, CATC, PETracer EML, PETracer M L, PETr ac er, PETr a iner E ML, PETr ai ner
ML, and PETracer Autom at ion are trademarks of Teledyne LeCroy.

Microsoft and Windows are registered trademarks of Microsoft Inc.

All other trademarks are property of their respective companies.

Copyright

© 2012 Teledyne LeCroy, Inc. All Rights Reserved.
This document may be printed and reproduced without additional permission, but all copies

should contain this copyright notice.

Teledyne LeCroy Automation API for PETracer/PETrainer

iii

Table of Contents

1 Introduction .......................................................................................................................................... 1

1.1 System Requirements .................................................................................................................... 1

1.2 Support Resources ......................................................................................................................... 1

1.3 Setting Up Automation for Local Use ............................................................................................. 1

1.4 Setting Up Automation for Remote Use ......................................................................................... 1

2 PETracer Object Model........................................................................................................................ 2

3 PEAnalyzer Object ............................................................................................................................... 4

3.1 IAnalyzer interface .......................................................................................................................... 5

3.1.1 IAnalyzer::GetVersion ............................................................................................................. 6

3.1.2 IAnalyzer::OpenFile ................................................................................................................. 7

3.1.3 IAnalyzer::StartGeneration ...................................................................................................... 8

3.1.4 IAnalyzer::StopGeneration ...................................................................................................... 9

3.1.5 IAnalyzer::StartRecording ..................................................................................................... 10

3.1.6 IAnalyzer::StopRecording ...................................................................................................... 12

3.1.7 IAnalyzer::MakeRecording .................................................................................................... 13

3.1.8 IAnalyzer::LoadDisplayOptions ............................................................................................. 14

3.1.9 IAnalyzer::GetRecordingOptions ........................................................................................... 15

3.1.10 IAnalyzer::GetSerialNumber .................................................................................................. 16

3.2 IPEAnalyzer interface ................................................................................................................... 17

3.2.1 IPEAnalyzer::GetGenerationOptions .................................................................................... 18

3.2.2 IPEAnalyzer::ResumeGeneration ......................................................................................... 19

3.2.3 IPEAnalyzer::GetLinkStatus .................................................................................................. 20

3.3 IPEAnalyzer2 interface ................................................................................................................. 21

3.3.1 IPEAnalyzer2::GetHardwareInfo ........................................................................................... 22

3.3.2 IPEAnalyzer2::ResetHardware .............................................................................................. 24

3.4 IPEAnalyzer3 interface ................................................................................................................. 25

3.4.1 IPEAnalyzer3::StartImportFile ............................................................................................... 26

4 PETrace Object .................................................................................................................................. 27

4.1 ITrace interface ............................................................................................................................. 28

4.1.1 ITrace::GetName ................................................................................................................... 29

4.1.2 ITrace::ApplyDisplayOptions ................................................................................................. 30

4.1.3 ITrace::Save .......................................................................................................................... 31

4.1.4 ITrace::ExportToText ............................................................................................................. 32

4.1.5 ITrace::Close ......................................................................................................................... 35

4.1.6 ITrace::ReportFileInfo ............................................................................................................ 36

4.1.7 ITrace::ReportErrorSummary ................................................................................................ 37

4.1.8 ITrace::GetPacket ................................................................................................................. 40

4.1.9 ITrace::GetPacketsCount ...................................................................................................... 43

4.1.10 ITrace::GetTriggerPacketNum .............................................................................................. 44

4.1.11 ITrace::AnalyzerErrors .......................................................................................................... 45

4.2 IPETrace interface ........................................................................................................................ 47

4.2.1 IPETrace::GetBusPacket ...................................................................................................... 47

4.3 IPEVerificationScript interface ...................................................................................................... 48

4.3.1 IPEVerificationScript::RunVerificationScript .......................................................................... 49

4.3.2 IPEVerificationScript::GetVScriptEngine ............................................................................... 51

5 PERecOptions Object ........................................................................................................................ 53

5.1 IRecOptions interface ................................................................................................................... 54

5.1.1 IRecOptions::Load ................................................................................................................. 54

5.1.2 IRecOptions::Save ................................................................................................................ 55

5.1.3 IRecOptions::SetRecMode .................................................................................................... 56

5.1.4 IRecOptions::SetBufferSize ................................................................................................... 57

Teledyne LeCroy Automation API for PETracer/PETrainer

iv

5.1.5 IRecOptions::SetPostTriggerPercentage .............................................................................. 58

5.1.6 IRecOptions::SetTriggerBeep ............................................................................................... 59

5.1.7 IRecOptions::SetSaveExternalSignals .................................................................................. 60

5.1.8 IRecOptions::SetTraceFileName ........................................................................................... 61

5.1.9 IRecOptions::Reset ............................................................................................................... 62

5.2 IPERecOptions interface .............................................................................................................. 63

5.3 IPERecOptions2 interf ac e ............................................................................................................ 63

5.3.1 IPERecOptions2::SetTargetAnalyzer .................................................................................... 64

5.3.2 IPERecOptions2::SetLinkWidth ............................................................................................. 65

5.3.3 IPERecOptions2::SetBase10Spec ........................................................................................ 66

5.3.4 IPERecOptions2::SetExternalRefClock ................................................................................ 67

5.3.5 IPERecOptions2::SetDisableDescrambling .......................................................................... 68

5.3.6 IPERecOptions2::SetDisableDeskew ................................................................................... 69

5.3.7 IPERecOptions2::SetAutoConfigPolarity .............................................................................. 70

5.3.8 IPERecOptions2::SetInhibit ................................................................................................... 71

5.3.9 IPERecOptions2::SetReverseLanes ..................................................................................... 72

5.3.10 IPERecOptions2::SetInvertPolarity ....................................................................................... 73

5.4 IPERecOptions3 interf ac e ............................................................................................................ 74

5.4.1 IPERecOptions3::SetLinkSpeed ........................................................................................... 74

5.4.2 IPERecOptions3::GetSimpleTrigger...................................................................................... 75

5.4.3 IPERecOptions3::GetSimpleFilter ......................................................................................... 77

5.4.4 IPERecOptions3:: RestoreDefaultFactorySettings ................................................................ 78

5.5 SimpleTrigger ............................................................................................................................... 79

5.5.1 SimpleTrigger::SetEnabled ................................................................................................... 79

5.5.2 SimpleTrigger::IsEnabled ...................................................................................................... 79

Retrieves trigger's state. ...................................................................................................................... 79

5.5.3 SimpleTrigger::SetDirection .................................................................................................. 79

5.5.4 SimpleTrigger::GetDirection .................................................................................................. 80

5.6 SimpleFilter ................................................................................................................................... 81

5.6.1 SimpleFilter::SetEnabled ....................................................................................................... 81

5.6.2 SimpleFilter::IsEnabled ......................................................................................................... 81

Retrieves filter's state. .......................................................................................................................... 81

5.6.3 SimpleFilter::SetDirection ...................................................................................................... 81

5.6.4 SimpleFilter::GetDirection ..................................................................................................... 82

6 PEGenOptions Object ....................................................................................................................... 83

6.1 IGenOptions interface ................................................................................................................... 84

6.1.1 IGenOptions::Load ................................................................................................................ 85

6.1.2 IGenOptions::Save ................................................................................................................ 86

6.1.3 IGenOptions::Reset ............................................................................................................... 87

6.2 IPEGenOptions interf ac e .............................................................................................................. 88

6.3 IPEGenOptions2 interface ............................................................................................................ 88

6.3.1 IPEGenOptions2::SetTargetGenerator ................................................................................. 89

6.3.2 IPEGenOptions2::SetWorkAsRoot ........................................................................................ 90

6.3.3 IPEGenOptions2::SetLinkWidth ............................................................................................ 91

6.3.4 IPEGenOptions2::SetBase10Spec ....................................................................................... 92

6.3.5 IPEGenOptions2::SetExternalRefClock ................................................................................ 93

6.3.6 IPEGenOptions2::SetDisableDescrambling .......................................................................... 94

6.3.7 IPEGenOptions2::SetDisableScrambling .............................................................................. 95

6.3.8 IPEGenOptions2::SetAutoConfig .......................................................................................... 96

6.3.9 IPEGenOptions2::SetReverseLanes ..................................................................................... 97

6.3.10 IPEGenOptions2::SetInvertPolarity ....................................................................................... 98

6.3.11 IPEGenOptions2::SetSkew ................................................................................................... 99

7 PEPacket Object .............................................................................................................................. 100

7.1 IPacket interface ......................................................................................................................... 101

Teledyne LeCroy Automation API for PETracer/PETrainer

v

7.1.1 IPacket::GetTimestamp ....................................................................................................... 101

7.2 IPEPacket interface .................................................................................................................... 102

7.2.1 IPEPacket::GetPacketData ................................................................................................. 103

7.2.2 IPEPacket::GetLinkWidth .................................................................................................... 106

7.2.3 IPEPacket::GetStartLane .................................................................................................... 107

7.2.4 IPEPacket::GetLFSR ........................................................................................................... 108

7.2.5 IPEPacket::GetDirection ...................................................................................................... 109

7.2.6 IPEPacket::GetErrors .......................................................................................................... 110

8 PETraceErrors Object...................................................................................................................... 111

8.1 IAnalyzerErrors dispinterface ..................................................................................................... 111

8.1.1 IAnalyzerErrors::get_Item .................................................................................................... 112

8.1.2 IAnalyzerErrors::get_Count ................................................................................................. 113

9 PEVScriptEngine Object ................................................................................................................. 115

9.1 IVScriptEngine interf ace ............................................................................................................. 116

9.1.1 IVScriptEngine::VScriptName ............................................................................................. 117

9.1.2 IVScriptEngine::Tag ............................................................................................................ 118

9.1.3 IVScriptEngine::RunVScript ................................................................................................ 119

9.1.4 IVScriptEngine::RunVScriptEx ............................................................................................ 120

9.1.5 IVScriptEngine::LaunchVScript ........................................................................................... 122

9.1.6 IVScriptEngine::Stop ........................................................................................................... 123

9.1.7 IVScriptEngine::GetScriptVar .............................................................................................. 124

9.1.8 IVScriptEngine::SetScriptVar .............................................................................................. 126

10 PEVScriptEngine Object Events ................................................................................................. 128

10.1 _IVScriptEngineEvents interface ............................................................................................ 128

10.1.1 _IVScriptEngineEvents::OnVScriptReportUpdated............................................................. 131

10.1.2 _IVScriptEngineEvents::OnVScriptFinished ....................................................................... 132

10.1.3 _IVScriptEngineEvents::OnNotifyClient .............................................................................. 133

11 PEAnalyzer Object Events .......................................................................................................... 134

11.1 _IAnalyzerEvents dispinterface ............................................................................................... 134

11.1.1 _IAnalyzerEvents::OnTraceCreated.................................................................................... 135

11.1.2 _IAnalyzerEvents::OnStatusReport .................................................................................... 136

12 CATCAnalyzerAdapter ................................................................................................................. 139

12.1 IAnalyzerAdapter Interface ..................................................................................................... 140

12.1.1 IAnalyzerAdapter::CreateObject.......................................................................................... 140

12.1.2 IAnalyzerAdapter::Attach ..................................................................................................... 142

12.1.3 IAnalyzerAdapter::Detach ................................................................................................... 143

12.1.4 IAnalyzerAdapter::IsValidObject.......................................................................................... 145

13 Teledyne LeCroy Internal Interfaces .......................................................................................... 146

How to Contact Teledyne LeCroy .......................................................................................................... 147

Teledyne LeCroy Automation API for PETracer/PETrainer

1

1 Introduction

Teledyne LeCroy’s PETracer™ software provides a rich, functional COM/Automation API to the most
important functionalities of the Teledyne LeCroy PETracer Protocol Analyzer and Teledyne LeCroy PETrainer™
Exerciser. This makes it a great tool for implementation of automated programs for complicated testing,
development, and debugging. The "dual" nature of the interfaces provided makes it easy to use the PETracer
COM API in different IDEs (Integrated Development Environment) supporting the COM architecture.

A special support for typeless script languages, like VB and JavaScript, while overriding some restrictions
imposed by script engines (remote access, dynamic object creation, and handling events), gives the opportunity
to write client applications very quickly and easily. One does not require significant programming skills nor
installing expensive and powerful programming language systems. All these features, along with the ability to
set up all necessary DCOM permissions during the installation process, make the Teledyne LeCroy PETracer
an attractive tool in automating and speeding up many engineering processes.

1.1 System Requirements

The Automation API was introduced with the following release: PETracer software 4.10. This document

covers the functionality available in PETracer 4.00

1.2 Support Resources

As new functionalities are added to the API, not all of them are supported by older versions of the
PETracer software. For newer releases of PETracer software, please refer to the Teledyne LeCroy web site:

www.teledynelecroy.com

1.3 Setting Up Automation for Local Use

If you intend to run Automation on the PETracer/PETrainer Host Controller (i.e., the PC attached to the
PETracer/PETrainer), 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. In order to use the PETracer COM API, the application
should be registered as a COM server in a system registry. This is done during the installation process.

1.4 Setting Up Automation for Remote Use

If you would like to access PETracer remotely over a network, you should install the PETracer application
on both server and client machine and accept enabling remote access option during the installation. You can
also perform a manual DCOM configuration.

Teledyne LeCroy Automation API for PETracer/PETrainer

2

2 PETracer Object Model

Teledyne LeCroy’s PETracer™ API programmatically exposes its functionality through objects. You work with
an object by using its properties and methods. Objects are named according to the portion of an application they
represent, and they are ordered in a hierarchy.

A single object occupies the topmost tier of Teledyne LeCroy PETracer object hierarchy: PEAnalyzer.
The following object model diagram shows how the objects in an object model fit together:

PEAnalyzer

Only the
C/C++ client), instantiation of an object of other classes requires API calls.

The Class ID and App ID for the PEAnalyzer object are the following.
Class ID: 297CD804-08F5-4A4F-B3BA-779B2654B27C

App ID: CATC.PETracer
All interfaces are dual interfaces that allow simple use from typeless languages, like VBScript, as well as from

C/C++.

PEAnalyzer object is creatable at the top level (for instance, via the CoCreateInstance call from a

PETrace

PETraceErrors

PEVScriptEngine

PERecOptions

PEGenOptions

PEPacket

Teledyne LeCroy Automation API for PETracer/PETrainer

3

Objects

Interfaces

Description

PEAnalyzer

IAnalyzer

Represents the PETracer

IPEAnalyzer

IPEAnalyzer2
IPEAnalyzer3*

_IAnalyzerEvents

PETrace

ITrace

Represents recorded trace

IPETrace*

IPEVerificationScript*

PERecOptions

IRecOptions

Represents recording options

IPERecOptions

IPERecOptions2*

PEGenOptions

IGenOptions

Represents generation options

IPEGenOptions

IPEGenOptions2*

PEPacket

IPacket

Represents single packet of the

IPEPacket*

PETraceErrors

IAnalyzerErrors*

Represents the collection of
trace

All objects implement ISupportErrorInfo interface for easy error handling from the client.

application

recorded trace

errors occurred in the recorded

* Primary interfaces

The examples of C++ code given in this document assume using the “import” technique of creating COM clients;
that means the corresponding include is used:

#import "PEAutomation.tlb" no_namespace named_guids

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

Teledyne LeCroy Automation API for PETracer/PETrainer

4

Interfaces

Description

IAnalyzer

Facilitates recording and traffic generation, opens trace files,
and retrieves recording options,

IPEAnalyzer

Extends the IAnalyzer interface:
options.

IPEAnalyzer2

Extends the IPEAnalyzer interface:

Adds StartImportFile method.

_IAnalyzerEvents

Events from PEAnalyzer object

3 PEAnalyzer Object

The PEAnalyzer
The PEAnalyzer

to the recording and generation options.
The PEAnalyzer

object is a top-level object of PETracer™ API.
object allows user to control the recording and traffic generation, open trace files, and access

object supports the following interfaces:

Adds advanced generator functionality, retrieves generation

IPEAnalyzer3

Adds hardware information and control methods.
Extends the IPEAnalyzer2 interface:

The IPEAnalyzer3 interface is a primary interface for the PEAnalyzer object.
The Class ID and App ID for the PEAnalyzer object are the following.
Class ID: 297CD804-08F5-4A4F-B3BA-779B2654B27C

App ID: CATC.PETracer

Example

WSH:

C++:

CLSID_PEAnalyzer,
NULL, CLSCTX_SERVER,
IID_IPEAnalyzer,
(LPVOID *)&poPEAnalyzer ) )
return;

Set Analyzer = WScript.CreateObject( “CATC.PETracer” )

IPEAnalyzer* poPEAnalyzer;

// create PEAnalyzer object
if ( FAILED( CoCreateInstance(

Teledyne LeCroy Automation API for PETracer/PETrainer

5

3.1 IAnalyzer interfac e

The IAnalyzer interface is a dual interface for the PEAnalyzer object.
IAnalyzer implements the following methods:

GetVersion
OpenFile
StartGeneration
StopGeneration
StartRecording
StopRecording
MakeRecording
LoadDisplayOptions

Note: All methods of the IAnalyzer interface are also available in the IPEAnalyzer (see Page 16), IPEAnalyzer2
(see Page 20), and IPEAnalyzer3 (see Page 25) interfaces.

Teledyne LeCroy Automation API for PETracer/PETrainer

6

version_type

Subsystem being queried for version; EAnalyzerVersionType

ANALYZERVERSION_SOFTWARE ( 0 ) – software

analyzer_version

Version of the subsystem queried

3.1.1 IAnalyzer::GetVersion

HRESULT GetVersion (

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

Retrieves the current version of a specified subsystem.

Parameters

enumerator has the following values:

Return values

ANALYZERCOMERROR_INVALIDVERSIONTYPE Specified version type is invalid

Remarks

Example

WSH:

Set Analyzer = WScript.CreateObject( “CATC.PETracer” )
SwVersion = Analyzer.GetVersion( 0 )
MsgBox "Software " & SwVersion

C++:

HRESULT hr;
IPEAnalyzer* poPEAnalyzer;

// create PEAnalyzer object

if ( FAILED( CoCreateInstance(
CLSID_PEAnalyzer,
NULL, CLSCTX_SERVER,
IID_IPEAnalyzer,
(LPVOID *)&poPEAnalyzer ) )
return;

WORD sw_version;

try

{

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

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

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

else

::MessageBox( NULL, er.ErrorMessage(), _T("PETracer 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 for PETracer/PETrainer

7

file_name

String providing the full pathname to the trace file

trace

Address of a pointer to the PETrace object interface

3.1.2 IAnalyzer::OpenFile

HRESULT OpenFile (

[in] BSTR file_name,

[out, retval] IDispatch** trace )

Opens a trace file, and creates the PETrace object.

Parameters

Return values

ANALYZERCOMERROR_UNABLEOPENFILE Unable to open file

Remarks

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

Example

WSH:

CurrentDir = Left( WScript.ScriptFullName, InstrRev( WScript.ScriptFullName, “\” ) )
Set Analyzer = WScript.CreateObject( “CATC.PETracer” )
Set Trace = Analyzer.OpenFile( CurrentDir & "Input\errors.pex" )

C++:

HRESULT hr;
IPEAnalyzer* poPEAnalyzer;

// create PEAnalyzer object
if ( FAILED( CoCreateInstance(

CLSID_PEAnalyzer,
NULL, CLSCTX_SERVER,
IID_IPEAnalyzer,
(LPVOID *)&poPEAnalyzer ) )
return;

// open trace file
IDispatch* trace;
try
{

trace = poPEAnalyzer->OpenFile( m_szRecFileName ).Detach();
}
catch ( _com_error& er)
{

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

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

else

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

return 1;
}

// query for VTBL interface

IPETrace* pe_trace;

hr = trace->QueryInterface( IID_IPETrace, (LPVOID *)&pe_trace );

trace->Release();

if( FAILED(hr) )
return;

Teledyne LeCroy Automation API for PETracer/PETrainer

8

gen_file_name

String providing the full pathname to the generation file

reserved1

Reserved for future use

reserved2

Reserved for future use

3.1.3 IAnalyzer::StartGeneration

HRESULT StartGeneration (

[in] BSTR gen_file_name,

[in] long reserved1,

[in] long reserved2 )

Starts traffic generation from the file.

Parameters

Return values

ANALYZERCOMERROR_UNABLEOPENFILE Unable to open file

ANALYZERCOMERROR_UNABLESTARTGENERATION

Remarks
Example

WSH:

CurrentDir = Left( WScript.ScriptFullName, InstrRev( WScript.ScriptFullName, “\” ) )
Set Analyzer = WScript.CreateObject( “CATC.PETracer” )
ret = Analyzer.StartGeneration( CurrentDir & "Input\connect.peg", 0, 0 )

C++:

HRESULT hr;
IPEAnalyzer* poPEAnalyzer;
TCHAR m_szGenFileName [_MAX_PATH];

// create PEAnalyzer object
if ( FAILED( CoCreateInstance(

CLSID_PEAnalyzer,
NULL, CLSCTX_SERVER,
IID_IPEAnalyzer,
(LPVOID *)&poPEAnalyzer ) )
return;

. . .

try
{
poAnalyzer->StartGeneration( m_szGenFileName, 0, 0 );
}
catch ( _com_error& er)
{

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

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

else

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

return 1;
}

Unable to start generation (invalid state, etc.)

Teledyne LeCroy Automation API for PETracer/PETrainer

9

3.1.4 IAnalyzer::StopGeneration

HRESULT StopGeneration ( )

Stops any current generation in progress.

Return values

ANALYZERCOMERROR_UNABLESTARTGENERATION Unable to stop generation (invalid state, etc.)

Remarks

Example

C++:

IPEAnalyzer* poAnalyzer;

. . .

try
{
poAnalyzer->StopGeneration();
}
catch ( _com_error& er)
{

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

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

else

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

return 1;

}

Teledyne LeCroy Automation API for PETracer/PETrainer

10

ro_file_name

String providing the full pathname to the recording options file; if the

options

3.1.5 IAnalyzer::StartRecording

HRESULT StartRecording (

[in] BSTR ro_file_name )

Starts recording with the specified recording options.

Parameters

parameter is omitted, then recording starts with default recording

Return values

Remarks

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

create this file when you select “Setup -> Recording Options…” from the PETracer application menu, change
the settings in the “Recording Options” dialog box, and then select the “Save…” button.

Example

VBScript:

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

ANALYZERCOMERROR_UNABLESTARTRECORDING Unable to start recording

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

The recording options file is the file with extension .rec created by the PETracer application. You can

<OBJECT

RUNAT=Server

ID = Analyzer

CLASSID = "clsid: 297CD804-08F5-4A4F-B3BA-779B2654B27C "
>
</OBJECT>

<INPUT TYPE=TEXT VALUE="" NAME="TextRecOptions">

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

End Sub

-->
</SCRIPT>

Teledyne LeCroy Automation API for PETracer/PETrainer

11

C++:

IPEAnalyzer* pe_analyzer;
BSTR ro_file_name;

. . .

try
{

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

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

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

else

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

return 1;
}

Teledyne LeCroy Automation API for PETracer/PETrainer

12

abort_upload

TRUE if the caller wants to abort the upload, no trace file is created;

FALSE if the caller wants to upload the recorded trace

3.1.6 IAnalyzer::StopRecording

HRESULT StopRecording (

[in] BOOL abort_upload )

Stops recording started by the IAnalyzer::StartRecording (see Page 10) method.

Parameters

Return values

Remarks

actually stopped (via the _IAnalizerEvents

Example

VBScript:

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

C++:

ANALYZERCOMERROR_UNABLESTOPRECORDING Error stopping recording

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

interface) if the parameter of this method call was FALSE.

<OBJECT

RUNAT=Server

ID = Analyzer

CLASSID = "clsid: 297CD804-08F5-4A4F-B3BA-779B2654B27C "
>
</OBJECT>

<SCRIPT LANGUAGE="VBScript">
<!-­Sub BtnStopRecording_OnClick

End Sub

-->
</SCRIPT>

IPEAnalyzer* pe_analyzer;

. . .

try
{

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

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

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

else

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

return 1;
}

Teledyne LeCroy Automation API for PETracer/PETrainer

13

ro_file_name

String providing the full pathname to a recording options file;

recording options

trace

Address of a pointer to the PETrace object interface

3.1.7 IAnalyzer::MakeRecording

HRESULT MakeRecording (

[in] BSTR ro_file_name,

[out, retval] IDispatch** trace )

Makes recording with the specified recording options file.

Parameters

if the parameter is omitted, then recording starts with default

Return values

ANALYZERCOMERROR_UNABLESTARTRECORDING

Remarks

This method acts like the StartRecording method but does not return until recording is completed. The

PETrace object is created via this method call if the call was successful.

The recording options file is the file with extension .rec created by the PETracer application. You can

create this file when you select “Setup -> Recording Options…” from the PETracer application menu, change
the settings in the “Recording Options” dialog box, and then select the “Save…” button.

Example

WSH:

CurrentDir = Left( WScript.ScriptFullName, InstrRev( WScript.ScriptFullName, “\” ) )
Set Analyzer = WScript.CreateObject( “CATC.PETracer” )
Set Trace = Analyzer.MakeRecording( CurrentDir & "Input\test_ro.rec" )

C++:

IDispatch* trace;
IPEAnalyzer* pe_analyzer;
BSTR ro_file_name;
HRESULT hr;

. . .

try
{

trace = pe_analyzer->MakeRecording( ro_file_name ).Detach();
}
catch ( _com_error& er)
{

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

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

else

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

return 1;
}

// query for VTBL interface

IPETrace* pe_trace;

hr = trace->QueryInterface( IID_IPETrace, (LPVOID *)&pe_trace );

trace->Release();

Unable to start recording

Teledyne LeCroy Automation API for PETracer/PETrainer

14

do_file_name

String providing the full pathname to a display options file

3.1.8 IAnalyzer::LoadDisplayOptions

HRESULT LoadDisplayOptions (

[in] BSTR do_file_name )

Loads display options that apply to a trace opened or recorded later.

Parameters

Return values

Remarks

apply only on trace file opened or recorded after this call.
this file when you select “Setup -> Display Options…” from the PETracer application menu, change the settings

in the “Display Options” dialog box, and then select the “Save…” button. Example

ANALYZERCOMERROR_UNABLELOADDO Unable to load the display options file

Use this method if you want to filter traffic of some type. The display options loaded by this method call
Display options file is the file with extension .opt created by the PETracer application. You can create

See ITrace::ApplyDisplayOptions, Page 27.

Teledyne LeCroy Automation API for PETracer/PETrainer

15

recording_options

Address of a pointer to the PERecOptions object interface

3.1.9 IAnalyzer::GetRecordingOptions

HRESULT GetRecordingOptions (

[out, retval] IDispatch** recording_options )

Retrieves the interface for access to the recording options.

Parameters

Return values

Remarks

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

Example

WSH:

Set Analyzer = WScript.CreateObject( “CATC.PETracer” )
Set RecOptions = Analyzer.GetRecordingOptions( )

C++:

HRESULT hr;
IPEAnalyzer* poPEAnalyzer;

// create PEAnalyzer object
if ( FAILED( CoCreateInstance(

CLSID_PEAnalyzer,
NULL, CLSCTX_SERVER,
IID_IPEAnalyzer,
(LPVOID *)&poPEAnalyzer ) )
return;

// open trace file
IDispatch* rec_opt;
try
{

rec_opt = poPEAnalyzer->GetRecordingOptions().Detach();
}
catch ( _com_error& er)
{

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

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

else

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

return 1;
}

// query for VTBL interface

IPERecOptions* ib_rec_opt;

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

rec_opt->Release();

if( FAILED(hr) )

return;

Teledyne LeCroy Automation API for PETracer/PETrainer

16

3.1.10 IAnalyzer::GetSerialNumber

HRESULT GetSerialNumber ( [out, retval] WORD* serial_number )

Returns analyzer's serial number.

Parameters

Return values

WORD serial_number

Remarks

Example

Set Analyzer = WScript.CreateObject("CATC.PETracer")
SerialNum = Analyzer.GetSerialNumber()
WScript.Echo "SerialNum= " & CLng(SerialNum)

Teledyne LeCroy Automation API for PETracer/PETrainer

17

3.2 IPEAnalyzer interf ace

The IPEAnalyzer interface is a dual interface for the PEAnalyzer object.
This interface is derived from the IAnalyzer interface.
The IPEAnalyzer

GetGenerationOptions
ResumeGeneration
GetLinkStatus

Note: All methods implemented by the IPEAnalyzer interface are also implemented by the IPEAnalyzer2
interface (see Page 20).

interface implements all methods from IAnalyzer interface plus the following:

Teledyne LeCroy Automation API for PETracer/PETrainer

18

generation_options

Address of a pointer to the PEGenOptions object interface

3.2.1 IPEAnalyzer::GetGenerationOptions

HRESULT GetGenerationOptions (

[out, retval] IDispatch** generation_options )

Retrieves the interface for access to the gen erati on o ptio ns .

Parameters

Return values

Remarks

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

Example

WSH:

Set Analyzer = WScript.CreateObject( “CATC.PETracer” )
Set GenOptions = Analyzer.GetGenerationOptions( )

C++:

HRESULT hr;
IPEAnalyzer* poPEAnalyzer;

// create PEAnalyzer object
if ( FAILED( CoCreateInstance(

CLSID_PEAnalyzer,
NULL, CLSCTX_SERVER,
IID_IPEAnalyzer,
(LPVOID *)&poPEAnalyzer ) )
return;

// open trace file
IDispatch* gen_opt;
try
{

gen_opt = poPEAnalyzer->GetGenerationOptions().Detach();
}
catch ( _com_error& er)
{

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

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

else

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

return 1;
}

// query for VTBL interface

IPEGenOptions* pe_gen_opt;

hr = gen_opt->QueryInterface( IID_IPEGenOptions, (LPVOID *)&pe_gen_opt );

gen_opt->Release();

if( FAILED(hr) )

return;

Teledyne LeCroy Automation API for PETracer/PETrainer

19

3.2.2 IPEAnalyzer::ResumeGeneration

HRESULT ResumeGeneration ( )

Resumes generation if it was previously paused.

Return values

Remarks

Example

C++:

try
{
poAnalyzer->ResumeGeneration();
}
catch ( _com_error& er)
{

}

IPEAnalyzer* poAnalyzer;

. . .

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

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

else

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

return 1;

Teledyne LeCroy Automation API for PETracer/PETrainer

20

fc_status

Flow control status, one of the following values can be returned:

“Pending”, “Complete”, or “Not initialized”

link_status

Link status, one of the following values can be returned: “

“Recovery.Idle”, “Loopback”, “Hot Reset”, or “Disabled”

3.2.3 IPEAnalyzer::GetLinkStatus

HRESULT GetLinkStatus (

[out] VARIANT* fc_status ,

[out, retval] BSTR* link_status )

Returns two text strings with the link and flow control status.

Parameters

“Detect.Active”, “Polling.Active”, “Polling.Compliance”,
“Polling.Configuration”, “Polling.Speed”,
“Configuration.Linkwidth.Start”, “Configuration.Linkwidth.Accept”,
“Configuration.Lanenum.Wait”, “Configuration.Lanenum.Accept”,
“Configuration.Complete”, “Configuration.Idle”, “L0”, “L0s.Idle”,
“L0s.FTS”, “L1”, “L2”, “Recovery.RcvrLock”, “Recovery.RcvrCfg”,

Return values

Remarks

Example

C++:

. . .

{

USES_CONVERSION;
TCHAR str_status[512];
_tcscpy( str_status, "Link Status: ");
_tcscat( str_status, OLE2T( link_status) );
_tcscat( str_status, "; Flow Control: ");
_tcscat( str_status, OLE2T(V_BSTR(&pe_status)) );

SysFreeString( link_status );

IPEAnalyzer* poAnalyzer;

BSTR link_status; // Link Status
VARIANT pe_status; // Flow Control
VariantInit(&pe_status);
try

link_status = poAnalyzer->GetLinkStatus( &pe_status );
}
catch ( _com_error& er)
{

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

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

else

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

return 1;
}

::MessageBox( NULL, str_status, _T("Status"), MB_OK );

Detect.Quiet”,

Teledyne LeCroy Automation API for PETracer/PETrainer

21

3.3 IPEAnalyzer2 interface

The IPEAnalyzer2 interface is a dual interface for the PEAnalyzer object.
This interface is derived from the IPEAnalyzer interface.
The IPEAnalyzer2

GetHardwareInfo
ResetHardware

interface implements all methods from IPEAnalyzer interface plus the following:

Teledyne LeCroy Automation API for PETracer/PETrainer

22

type

Hardware type being queried; the

HARDWARETYPE_PETRAINER ( 1 ) - PETrainer

info

The following values can be returned

3.3.1 IPEAnalyzer2::GetHardwareInfo

HRESULT GetHardwareInfo (

[in] EHardwareType type,

[out, retval] int* info )

Returns information about the hardware (PETracer/PETrainer™) connected.

Parameters

EHardwareType enumerator has the

following valu e s :

HARDWARETYPE_PETRACER ( 0 ) – PETracer

Return values
Remarks
Example

C++:

IPEAnalyzer2* poAnalyzer;

. . .

int tracer_type = 0;
int trainer_type = 0;

try

{
trainer_type = poAnalyzer->GetHardwareInfo( HARDWARETYPE_PETRAINER );
}
catch ( _com_error& er )
{

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

else

When type is HARDWARETYPE_PETRACER:
1 – PETracer ML
2 – PETracer ML (2 units)
3 – PETracer EML

4 – Edge T1-4
5

– (reserved)

6

– PETracer Sum mit / Summit T2-16

7

– Summit T3-16

8

– Summit T3-8

9

– Summit T28

10

– Summit T3-8 (2 units)

11 – Summit T24

When type is HARDWARETYPE_PETRAINER:
0 – PETrainer ML
1 – PETrainer EML

2 – Summit Z2-16

3 – Summit Z3-16

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

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

Teledyne LeCroy Automation API for PETracer/PETrainer

23

}

try
{
tracer_type = poAnalyzer->GetHardwareInfo( HARDWARETYPE_PETRACER );
}
catch ( _com_error& er )
{

}

return 1;

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

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

else

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

return 1;

Teledyne LeCroy Automation API for PETracer/PETrainer

24

type

Hardware type to reset; the EHardwareType enumerator has the

HARDWARETYPE_PETRAINER ( 1 ) - PETrainer

reset_type

Type of the reset; the
values:

RESETTYPE_LINK ( 0 ) – link reset

3.3.2 IPEAnalyzer2::ResetHardware

HRESULT ResetHardware (

[in] EHardwareType type,

[in] EResetType reset_type )

Resets the hardware specified.

Parameters

following values:

HARDWARETYPE_PETRACER ( 0 ) – PETracer

EResetType enumerator has the following

Remarks

Example

C++:

. . .

{
poAnalyzer->ResetHardware( HARDWARETYPE_PETRAINER, RESETTYPE_LINK );
}
catch ( _com_error& er )
{

IPEAnalyzer2* poAnalyzer;

try

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

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

else

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

return 1;
}

Teledyne LeCroy Automation API for PETracer/PETrainer

25

3.4 IPEAnalyzer3 interface

The IPEAnalyzer3 interface is a primary dual interface for the PEAnalyzer object.
This interface is derived from the IPEAnalyzer2 interface.
The IPEAnalyzer3

StartImportFile

interface implements all methods from IPEAnalyzer2 interface plus the following:

Teledyne LeCroy Automation API for PETracer/PETrainer

26

file_name

String providing the full pathname to the import file

3.4.1 IPEAnalyzer3::StartImportFile

HRESULT StartImportFile ( [in] BSTR file_name )

Begins process of importing specified file into a trace file.

Parameters

Return values

Remarks

The format of the import file is defined in a proprietary Teledyne LeCroy specification. Please contact Teledyne
LeCroy PSG for details.

Example

C++:

. . .

HRESULT hr;
try
{
hr = poAnalyzer->StartImportFile( szFileName );
}
catch ( _com_error& er)
{
if (er.Description().length() > 0)
::MessageBox( NULL, er.Description(), _T("PETracer client"), MB_OK );
else
::MessageBox( NULL, er.ErrorMessage(), _T("PETracer client"), MB_OK );
return 1;
}

S_OK Import started successfully
S_FALSE Error starting import

IPEAnalyzer3* poAnalyzer;

Teledyne LeCroy Automation API for PETracer/PETrainer

27

Interfaces

Description

ITrace

Implements trace packets and trace errors access, different
report types, export, and saving.

IPETrace

Extends ITrace interface:
object.

IPEVerificationScript

Exposes the functionality for running verification scripts

4 PETrace Object

PETrace

The PETrace

The PETrace object can be created by:

The PETrace

object represents the recorded trace file.

object allows user to:

• Get trace information

• Access trace packets

• Access trace errors

• Save/export the trace or a portion of the trace

• Using IAnalyzer::OpenFile method (see Page 7)

• Using IAnalyzer::MakeRecording method (see Page 13)

• Handling _IAnalyzerEvents::OnTraceCreated event (see Page 120)

object supports the following interfaces:

Adds the functionality for accessing the PETracePacket

The IPETrace interface is a primary interface for the PETrace object.

Teledyne LeCroy Automation API for PETracer/PETrainer

28

4.1 ITrace interface

The ITrace interface is a dual interface for the PETrace object.
It implements the following methods:

GetName
ApplyDisplayOptions
Save
ExportToText
Close
ReportFileInfo
ReportErrorSummary
GetPacket
GetPacketsCount
GetTriggerPacketNum
AnalyzerErrors

Note: All methods of ITrace interface are also available in IPETrace (see Page 41).

Teledyne LeCroy Automation API for PETracer/PETrainer

29

trace_name

Name of the trace

4.1.1 ITrace::GetName

HRESULT GetName (

[out, retval] BSTR* trace_name )

Retrieves the trace name.

Parameters

Return values

Remarks

This name can be used for presentation purposes.

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

Example

WSH:

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

C++: IPETrace* pe_trace;

. . .

_bstr_t bstr_trace_name;
try

{

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

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

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

else

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

return 1;
}

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

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

Teledyne LeCroy Automation API for PETracer/PETrainer

30

do_file_name

String providing the full pathname to the display options file

4.1.2 ITrace::ApplyDisplayOptions

HRESULT ApplyDisplayOptions (

[in] BSTR do_file_name )

Applies the specified display options to the trace.

Parameters

Return values

Remarks

create this file when you select “Setup -> Display Options…” from the PETracer application menu, change the
settings in the “Display Options” dialog box, and then select the “Save…” button.

Example

WSH:

C++:

IPETrace* pe_trace;

. . .

{

ANALYZERCOMERROR_UNABLELOADDO Unable to load the 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 c r eated b y the PETracer™ application. You can

Note: This does not work on Multisegment traces

Set Analyzer = WScript.CreateObject( “CATC.PETracer” )
CurrentDir = Left( WScript.ScriptFullName, InstrRev( WScript.ScriptFullName, “\” ) )
Set Trace = Analyzer.MakeRecording( CurrentDir & "Input\test_ro.rec" )
Trace.ApplyDisplayOptions CurrentDir & "Input\test_do.opt"
Trace.Save CurrentDir & "Output\saved_file.pex"

TCHAR file_name[_MAX_PATH];

try

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

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

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

else

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

return 1;
}

Teledyne LeCroy Automation API for PETracer/PETrainer

31

file_name

String providing the full pathname to file where the tr a ce is saved

packet_from

beginning packet number

packet of this trace

packet_to

ending packet number

this trace

4.1.3 ITrace::Save

HRESULT Save (

[in] BSTR file_name,

[in, defaultvalue(-1)] long packet_from,

[in, defaultvalue(-1)] long packet_to )

Saves trace into a file while allowing you to specify a range of packets.

Parameters

when you are saving a range of packets;

value –1 means that the first packet of the saved trace is the first

when you are saving a range of packets; value –

1 means that the last packet of the saved trace is the last packet of

Return values

ANALYZERCOMERROR_UNABLESAVE Unable to save the trace file
ANALYZERCOMERROR_INVALIDPACKETNUMBER

Bad packet range

Remarks

applied to this trace (see

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

ITrace::ApplyDisplayOptions on Page 27 or IAnalyzer::LoadDisplayOptions on Page

14), then hidden packets would not be saved.
If the packet range specified is invalid (for example, packet_to is more than the last packet number in
the trace, or packet_from is less than the first packet number in the trace, or packet_from is more than
packet_to), then the packet range is adjusted automatically.

Example

WSH:

C++: IPETrace* pe_trace;

. . .

{

Set Analyzer = WScript.CreateObject( “CATC.PETracer” )
CurrentDir = Left( WScript.ScriptFullName, InstrRev( WScript.ScriptFullName, “\” ) )
Set Trace = Analyzer.MakeRecording (CurrentDir & "Input\test_ro.rec")
Trace.ApplyDisplayOptions CurrentDir & "Input\test_do.opt"
Trace.Save CurrentDir & "Output\saved_file.pex"

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

try

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

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

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

else

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

return 1;
}

Teledyne LeCroy Automation API for PETracer/PETrainer

32

file_name

String providing the full file pathname for the exported trace

packet_from

beginning packet number

packet of this trace

packet_to

ending packet number

packet of this trace

4.1.4 ITrace::ExportToText

HRESULT ExportToText (

[in] BSTR file_name,

[in, defaultvalue(-1)] long packet_from,

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

Exports the trace into a text file while allowing you to specify a range of packets.

Parameters

when you are exporting a range of packets;

value –1 means that the first packet of the exported trace is the first

when you are exporting a range of packets,

value –1 means that the last packet of the exported trace is the last

Return values

ANALYZERCOMERROR_UNABLESAVE Unable to export trace file

Remarks

Use this method if you want to export a recorded or an opened trace into a text file. If the display options
applied to this trace (see

ITrace::ApplyDisplayOptions on Page 27 or IAnalyzer::LoadDisplayOptions on Page

14), then hidden packets would not be exported.
If the packet range is specified and it is invalid (for example, packet_to is more than the last packet
number in the trace, or packet_from is less than the first packet number in the trace, or packet_from is more
than packet_to), then packet range is adjusted automatically.

Teledyne LeCroy Automation API for PETracer/PETrainer

33

Here is a snippet of an exported text file:

File C:\data.pex.
From Packet #1880 to Packet #1890.

Packet#
_______|_______________________________________________________________________
Packet(1880) Downstream DLLP ACK AckNak_Seq_Num(3388) CRC 16(0xBB63)
_______| Time Stamp(0002 . 069 437 652 s)
_______|_______________________________________________________________________
Packet(1881) Upstream SKIP COM(K28.5 ) SKIP Symbols(K28.0 K28.0 K28.0 )
_______| Time Stamp(0002 . 069 437 848 s)
_______|_______________________________________________________________________
Packet(1882) Upstream DLLP UpdateFC-P VC ID(0) HdrFC(1) DataFC(2)
_______| CRC 16(0x6744) Time Stamp(0002 . 069 437 936 s)
_______|_______________________________________________________________________
Packet(1883) Upstream DLLP UpdateFC-NP VC ID(0) HdrFC(1) DataFC(2)
_______| CRC 16(0x8C23) Time Stamp(0002 . 069 437 944 s)
_______|_______________________________________________________________________
Packet(1884) Upstream DLLP UpdateFC-Cpl VC ID(0) HdrFC(6) DataFC(1287)
_______| CRC 16(0x06F2) Time Stamp(0002 . 069 437 952 s)
_______|_______________________________________________________________________
Packet(1885) Downstream Packet Error(CodeErr, DlmtErr, LCRCErr) TLP(1285)
_______| Cpl CplD(10:01010) RequesterID(058:22:1) Tag(177)
_______| CompleterID(000:07:2) Status(UR)-BAD BCM(1) Byte Cnt(2618)-BAD
_______| Lwr Addr(0x31)-BAD LCRC(0xB1000000)-BAD
_______| Time Stamp(0002 . 069 437 956 s)
_______|_______________________________________________________________________
Packet(1886) Upstream TLP(3389) Cfg CfgRd0(00:00100) RequesterID(000:00:0)
_______| Tag(0) DeviceID(000:00:0) Register(0x000) 1st BE(0000) LCRC(0xF1AB6932)
_______| Time Stamp(0002 . 069 437 960 s)
_______|_______________________________________________________________________
Packet(1887) Downstream TS2 COM(K28.5 ) Link Lane N_FTS
_______| Training Control TS2 Time Stamp(0002 . 069 437 976 s)
_______|_______________________________________________________________________
Packet(1888) Upstream DLLP Vendor Data(01 02 03) CRC 16(0x532D)
_______| Time Stamp(0002 . 069 437 984 s)
_______|_______________________________________________________________________
Packet(1889) Downstream TS2 COM(K28.5 ) Link Lane N_FTS
_______| Training Control TS2 Time Stamp(0002 . 069 438 040 s)
_______|_______________________________________________________________________
Packet(1890) Upstream SKIP COM(K28.5 ) SKIP Symbols(K28.0 K28.0 K28.0 )
_______| Time Stamp(0002 . 069 438 072 s)
_______|_______________________________________________________________________

Teledyne LeCroy Automation API for PETracer/PETrainer

34

Example

WSH:

Set Analyzer = WScript.CreateObject( “CATC.PETracer” )
CurrentDir = Left( WScript.ScriptFullName, InstrRev( WScript.ScriptFullName, “\” ) )
Set Trace = Analyzer.MakeRecording (CurrentDir & "Input\test_ro.rec")
Trace.ApplyDisplayOptions CurrentDir & "Input\test_do.opt"
Trace.ExportToText CurrentDir & "Output\text_export.txt"

C++:

IPETrace* pe_trace;

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

. . .

try

{

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

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

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

else

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

return 1;
}

Teledyne LeCroy Automation API for PETracer/PETrainer

35

4.1.5 ITrace::Close

HRESULT Close ( )

Closes the trace.

Parameters

Return values

Remarks

Closes the current trace, but does not release the interface pointer. Call IUnknown::Release method
right after this method call. No ITrace method call succeeds after calling ITrace::Close method
there is no need to call ITrace::Close directly since IUnknown::Release closes the trace.)

Example

. (Currently,

Teledyne LeCroy Automation API for PETracer/PETrainer

36

file_name

String providing the full pathname to a file where the trace information

report is stored

4.1.6 ITrace::ReportFileInfo

HRESULT ReportFileInfo (

[in] BSTR file_name )

Saves trace information into a specified HTML file.

Parameters

Return values

Remarks

Creates a new trace information file if the file specified in the file_name parameter does not exist. Example

WSH:

C++:

IPETrace* pe_trace;

{

ANALYZERCOMERROR_UNABLESAVE Unable to create the trace information report

Set Analyzer = WScript.CreateObject( “CATC.PETracer” )
CurrentDir = Left( WScript.ScriptFullName, InstrRev( WScript.ScriptFullName, “\” ) )
Set Trace = Analyzer.MakeRecording (CurrentDir & "Input\test_ro.rec")
Trace.ReportFileInfo CurrentDir & "Output\file_info.html"

TCHAR file_name[_MAX_PATH];

. . .

try

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

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

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

else

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

return 1;
}

Teledyne LeCroy Automation API for PETracer/PETrainer

37

file_name

String providing the full pathname to a file where the error summary

report is stored.

4.1.7 ITrace::ReportErrorSummary

HRESULT ReportErrorSummary (

[in] BSTR file_name )

Saves trace error summary information into the specified text file.

Parameters

Return values

Remarks

Creates a new error summary file if the file specified in the file_name parameter does not exist. Stores
error summary in the specified file.

ANALYZERCOMERROR_UNABLESAVE Unable to create trace information report

This method doesn’t work on Multisegment traces.

Teledyne LeCroy Automation API for PETracer/PETrainer

38

Error report for ErrorFinding_loop.pex recording file.

_______|_______________________________________________________________________
Bad ECRCs on channel Upstream (0):
_______|_______________________________________________________________________
Bad ECRCs on channel Downstream (0):
_______|_______________________________________________________________________
Bad LCRCs on channel Upstream (12):
_______|_______________________________________________________________________
Bad LCRCs on channel Downstream (0):
_______|_______________________________________________________________________
Bad Packet length on channel Upstream (0):
_______|_______________________________________________________________________
Bad Packet length on channel Downstream (0):
_______|_______________________________________________________________________
Alignment Error on channel Upstream (0):
_______|_______________________________________________________________________
Alignment Error on channel Downstream (0):
_______|_______________________________________________________________________
Invalid 10b Code on channel Upstream (11):
_______|_______________________________________________________________________
Invalid 10b Code on channel Downstream (0):
_______|_______________________________________________________________________
Running Disparity Error on channel Upstream (0):
_______|_______________________________________________________________________
Running Disparity Error on channel Downstream (0):
_______|_______________________________________________________________________
End of Bad Packet on channel Upstream (0):
_______|_______________________________________________________________________
End of Bad Packet on channel Downstream (0):
_______|_______________________________________________________________________
Delimiter Error on channel Upstream (12):
_______|_______________________________________________________________________
Delimiter Error on channel Downstream (0):
_______|_______________________________________________________________________
TS Data Error on channel Upstream (0):
_______|_______________________________________________________________________
TS Data Error on channel Downstream (0):
_______|_______________________________________________________________________
Ordered Set Format Error on channel Upstream (0):
_______|_______________________________________________________________________
Ordered Set Format Error on channel Downstream (0):
_______|_______________________________________________________________________
Idle Error on channel Upstream (0):
_______|_______________________________________________________________________
Idle Error on channel Downstream (11):
_______|_______________________________________________________________________
Skip Late on channel Upstream (0):
_______|_______________________________________________________________________
Skip Late on channel Downstream (0):
_______|_______________________________________________________________________
Skew Error on channel Upstream (0):
_______|_______________________________________________________________________
Skew Error on channel Downstream (0):
_______|_______________________________________________________________________

Here is an example of data stored using this method call:

Teledyne LeCroy Automation API for PETracer/PETrainer

39

Example

WSH:

Set Analyzer = WScript.CreateObject( “CATC.PETracer” )
CurrentDir = Left( WScript.ScriptFullName, InstrRev( WScript.ScriptFullName, “\” ) )
Set Trace = Analyzer.MakeRecording (CurrentDir & "Input\test_ro.rec")
Trace.ReportErrorSummary CurrentDir & "Output\error_summary.txt"

C++:

IPETrace* pe_trace;

TCHAR file_name[_MAX_PATH];

. . .

try

{

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

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

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

else

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

return 1;
}

Teledyne LeCroy Automation API for PETracer/PETrainer

40

packet_number

Zero based number of packet to retrieve

packet

Raw packet representation

number_of_bytes

Number of bytes in the raw packet representation

4.1.8 ITrace::GetPacket

HRESULT GetPacket (

[in] long packet_number,

[in, out] VARIANT* packet,

[out, retval] long* number_of_bytes )

Retrieves a raw packet representation in the PACKETFORMAT_BYTES format (see IPacket interface for
details, Page 85).

Parameters

Return values

Remarks

has the VT_UI1 automation type.

ANALYZERCOMERROR_INVALIDPACKETNUMBER Specified packet number is invalid

packet parameter has VT_ARRAY | VT_VARIANT actual automation type. Each element of this array

Teledyne LeCroy Automation API for PETracer/PETrainer

41

Example

VBScript:

<OBJECT

ID = Analyzer

CLASSID = "clsid: 297CD804-08F5-4A4F-B3BA-779B2654B27C "
>
</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
NumberOfBytes = CurrentTrace.GetPacket (TextPacketNumber.value, Packet)
If Err.Number <> 0 Then

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

Else

For Each PacketByte In Packet

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

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

End If

End Sub

-->
</SCRIPT>

Teledyne LeCroy Automation API for PETracer/PETrainer

42

C++:

IPETrace* pe_trace;
LONG packet_number;

. . .

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

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

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

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

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("PETracer client"), MB_OK );
return 1;
}
if ( var.vt != ( VT_UI1) )
{
::MessageBox( NULL, _T("Array of bytes expected"), _T("PETracer client"), MB_OK );
return 1;
}

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

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

Teledyne LeCroy Automation API for PETracer/PETrainer

43

number_of_packets

Total number of packets in the trace

4.1.9 ITrace::GetPacketsCount

HRESULT GetPacketsCount (

[out, retval] long* number_of_packets )

Retrieves the total number of packets in the trace.

Parameters

Return values

Remarks

Example

WSH:

Set Analyzer = WScript.CreateObject( “CATC.PETracer” )
CurrentDir = Left( WScript.ScriptFullName, InstrRev( WScript.ScriptFullName, “\” ) )
Set Trace = Analyzer.MakeRecording( CurrentDir & "Input\test_ro.rec" )
MsgBox Trace.GetPacketsCount & " packets recorded"

C++:

IPETrace* pe_trace;

. . .

long number_of_packets;
long trigg_packet_num;
try
{

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

}

catch ( _com_error& er)

{

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

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

else

::MessageBox( NULL, er.ErrorMessage(),_T("PETracer 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 );

Teledyne LeCroy Automation API for PETracer/PETrainer

44

packet_number

Zero based number of the packet where the trigger occured

4.1.10 ITrace::GetTriggerPacketNum

HRESULT GetTriggerPacketNum (

[out, retval] long* packet_number )

Retrieves the trigger packet number.

Parameters

Return values

Remarks

Example

WSH:

C++:

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

CInt(ErrorPacket)+5

See an example for ITrace::GetPacketsCount, Page 37.

Teledyne LeCroy Automation API for PETracer/PETrainer

45

error_type

Type of error collection you want to retrieve; the following values are
valid:

analyzer_errors

Address of a pointer to the PETraceErrors object interface

4.1.11 ITrace::AnalyzerErrors

HRESULT AnalyzerErrors (

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

Retrieves trace file errors. Returns an interface pointer to the PETraceErrors object.

Parameters

0x00000001 Invalid Code
0x00000002 Running Disparity Error
0x00000003 Skip Late
0x00000004 Idle Data Error (not D0.0)
0x00000005 Unexpected K/D Code
0x00000006 Bad Packet Length
0x00000007 Alignment Error
0x00000008 Skew Error
0x00000009 Ordered Set Format Error
0x0000000A Delimiter Error
0x0000000B DLLP: Invalid Encoding
0x0000000C DLLP: Bad CRC16
0x0000000D DLLP: Reserved Field not 0
0x0000000E DLLP: FC Initialization Error
0x0000000F TLP: Invalid Encoding
0x00000010 TLP: Bad LCRC
0x00000011 TLP: Bad ECRC
0x00000012 TLP: Reserved Field not 0
0x00000013 TLP: Payload/Length Error
0x00000014 TLP: Length Error (not 1)
0x00000015 TLP: TC Error (not 0)
0x00000016 TLP: Attr Error (not 0)
0x00000017 TLP: Byte Enables Violation
0x00000018 Memory TLP: Address/Length Crosses 4K
0x00000019 Mem64 TLP: Used Incorrectly
0x0000001A Cfg TLP: Register Error
0x0000001B Msg TLP: Invalid Routing
0x0000001C Invalid Packet
0x0000001D FC: Invalid Advertisement
0x0000001E FC: Insufficient Credits
0x0000001F Gen3 TLP: Bad Len CRC/Parity

Return values

ANALYZERCOMERROR_INVALIDERROR Invalid error type specified

Remarks

PETraceErrors object is created via this method call if the call was successful.

Teledyne LeCroy Automation API for PETracer/PETrainer

46

Example

WSH:

CurrentDir = Left( WScript.ScriptFullName, InstrRev( WScript.ScriptFullName, “\” ) )
Set Analyzer = WScript.CreateObject( “CATC.PETracer” )
Set Trace = Analyzer.MakeRecording( CurrentDir & "Input\test_ro.rec" )
Set Errors = Trace.AnalyzerErrors( 8 ) ' Packet Length Error

C++:

IPETrace* pe_trace;

. . .

IAnalyzerErrors* trace_errors;
try
{

trace_errors = pe_trace->AnalyzerErrors(error_type).Detach();
}
catch ( _com_error& er)
{

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

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

else

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

return 1;
}

. . .

analyser_errors->Release();

Teledyne LeCroy Automation API for PETracer/PETrainer

47

packet_number

Zero based number of packet to retrieve

packet

Address of a pointer to the PEPacket object interface

4.2 IPETrace interface

The IPETrace interface is a primary dual interf ace for the PETrace object.
This interface is derived from the ITrace interface.
The IPETrace

GetBusPacket

4.2.1 IPETrace::GetBusPacket

Retrieves the interface for a packet within a trace.

Parameters

interface implements all methods from the ITrace interface plus the following:

HRESULT GetBusPacket (

[in] long packet_number,

[out, retval] IDispatch** packet )

Return values

Remarks

PEPacket object is created via this method call if the call was successful.

Example

WSH:

C++:

IPETrace* pe_trace;

. . .

IDispatch* packet;
try
{
packet = pe_trace->GetBusPacket( GetDlgItemInt(IDC_PACKET_NUMBER) ).Detach();
}
catch ( _com_error& er)
{

}

IPEPacket* custom_packet;
HRESULT hr = packet->QueryInterface( IID_IPEPacket, (void**)&custom_packet );
packet->Release();

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

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

else

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

return 1;

Teledyne LeCroy Automation API for PETracer/PETrainer

48

4.3 IPEVerificationScript interface

The IPEVerificationScript interface is an interface for the
running verification scripts. This interface is not dual – which means that scripting languages cannot use it
directly, though all of its methods described below are exposed to script languages through the primary
automation interface of the PETrace object.

Remarks

Verification scripts are scripts written in a special manner using the CATC Script Language (CSL).

These scripts can be “run” over a 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 PETracer application, i ts
Verification Script Engine.

Please refer to the PETracer Manual, the PETracer Ver ificat io n Scri pt Eng in e Manua l, and the PETracer

File Based Decoding Manual for more details.

Attention:

The functions of this interface may be legally called either for regular traces or multi-segmented traces.

The VSE opens segments of the multi-segmented trace during script execution when it is needed.

PETrace object. It exposes the trace functionality for

Teledyne LeCroy Automation API for PETracer/PETrainer

49

verification_script

Name of the verification script to run

result

result

4.3.1 IPEVerificationScript::RunVerificationScript

HRESULT RunVerificationScript (

[in] BSTR verification_script,

[out, retval] VS_RESULT *result )

Runs a verification script over the recorded trace

Parameters

Address of a variable where to keep the result of verification;
VS_RESULT is an enumeration type that can have 5 possible
meanings:

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

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 (*.pevs). If only the name of

the script, without file extension, is specified, PETracer’s server is going to search for the named script among
the scripts loaded from the \Scripts\VFScripts folder under PETracer installation folder. If the full path to the
script is specified, then the server is going to attempt loading the script from the specified path prior to running it.

Example

For a verification script file named “test.pevs”, the test name would be “test”. Please refer to the PETracer
Verification Script Engine Manu al for more details.

Teledyne LeCroy Automation API for PETracer/PETrainer

50

Example

C++:

// In this example we use wrapper functions provided by #import directive
//
IPETrace* trace;
. . .

IPEVerificationScript* vscript = NULL;

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

try

{

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

::MessageBox( NULL, "Test verification 1 is passed !!!", "PETracer client",

MB_OK );
}
}
catch ( _com_error& er)

{

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

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

else

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

return 1;

}

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

. . .

WSH:

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

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

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

If Result = 1 Then

Msgbox "PASSED"

Else

Msgbox "FAILED"

End If

MsgBox( "Done" )

Teledyne LeCroy Automation API for PETracer/PETrainer

51

script_name

Name of the verification script to initialize the verification script engine

vs_engine

Address of a pointer to the PEVScriptEngine object interfac e

4.3.2 IPEVerificationScript::GetVScriptEngine

HRESULT GetVScriptEngine(

[in] BSTR script_name,
[out, retval] IVScriptEngine** vs_engine )

Retrieves the verification script engine object

Parameters

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

Remarks

The name of the verification script is the name of the verification script file (*.pevs). See remark to

IPEVerificationScript::RunVerificationScript function for details, Page 43.

Teledyne LeCroy Automation API for PETracer/PETrainer

52

Example

C++:

// In this example we use wrapper functions provided by #import directive // IPETrace* pe_trace;

. . .

IPEVerificationScript* pe_vscript = NULL;

pe_trace->QueryInterface( IID_IPEVerificationScript, (void**)&pe_vscript ) )

assert( pe_vscript != NULL );

IVScriptEngine* pe_vsengine = NULL;
pe_vsengine = pe_vscript -> GetVScriptEngine("Test_1");
assert( pe_vsengine != NULL );

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

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

}

. . .

WSH:

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

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

Dim Result

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

If Result = 1 Then

Msgbox "PASSED"

Else

Msgbox "FAILED"

End If

MsgBox( "Done" )

Teledyne LeCroy Automation API for PETracer/PETrainer

53

Interfaces

Description

IRecOptions

Allows you to load/save recording options from/to the file,
buffer size, trigger position, and the trace file name

IPERecOptions

Identical to IRecOptions interface

IPERecOptions2

Extends the IPERecOptions interface. Adds a set up for link
algorithm, skew, lane reversal, and polarity inversion

5 PERecOptions Object

The PERecOptions object represents the options for the PETracer™ (x1, ML, EML) hardware and is used to
specify the recording parameters.

The PERecOptions object allows user to:

• Load/save the recording options from/to the file

• Set up recording mode and recording buffer size

• Set up custom recording parameters such as link width, descrambling mode, deskew, etc.

The PERecOptions object can be created by using the IAnalyzer::GetRecordingOptions method (see Page 15)
The PERecOptions object supports the following interfaces:

reset recording options, set up recording mode, recording

width, spec mode, external reference clock, descrambling

The IPERecOptions2 interface is a primary interface for PERecOptions object.

Teledyne LeCroy Automation API for PETracer/PETrainer

54

ro_file_name

String that provides the full pathname to the recording options file

5.1 IRecOptions interf ace

The IRecOptions
IRecOptions implements the following methods:

Load
Save
SetRecMode
SetBufferSize
SetPostTriggerPercentage
SetTriggerBeep
SetSaveExternalSignals
SetTraceFileName
Reset

Note: All methods of the IRecOptions interface are also available in the IPERecOptions (see Page 57) and the
IPERecOptions2 (see Page 57) interfaces.

5.1.1 IRecOptions::Load

interface is a dual interface for PERecOptions object.

HRESULT Load (

[in] BSTR ro_file_name )

Loads recording options from the specified file. The load options are:

• Loads the whole Recording Options (.rec)

• Loads only the Recording Rules portions of the recording options (.rr)

• Loads only the Probe Settings portions of the recording options (.ps). This option only applies to the

Summit T3-16, T3-8, T28 and T24 Protocol Analyzers.

Parameters

Return values

ANALYZERCOMERROR_UNABLEOPENFILE Unable to open file

Remarks

Example

WSH:

C++:

CurrentDir = Left( WScript.ScriptFullName, InstrRev( WScript.ScriptFullName, “\” ) )
Set Analyzer = WScript.CreateObject( “CATC.PETracer” )
Set RecOptions = Analyzer.GetRecordingOptions( )
RecOptions.Load( CurrentDir & "Input\rec_options.rec" )

Teledyne LeCroy Automation API for PETracer/PETrainer

55

ro_file_name

String that provides the full pathname to the recording options file

5.1.2 IRecOptions::Save

HRESULT Save (

[in] BSTR ro_file_name )

Saves recording options into the specified file. The Save options are:

• Saves the whole Recording Options (.rec)

• Saves only the Recording Rules portions of the recording options (.rr)

• Saves only the Probe Settings portions of the recording options (.ps). This option only applies to the

Summit T3-16, T3-8, T28 and T24 Protocol An alyzers.

Parameters

Return values

Remarks

Example

WSH:

C++:

ANALYZERCOMERROR_UNABLEOPENFILE Unable to open file

If the specified file does not exist, it is created; if it exists, it is overwritten.

CurrentDir = Left( WScript.ScriptFullName, InstrRev( WScript.ScriptFullName, “\” ) )
Set Analyzer = WScript.CreateObject( “CATC.PETracer” )
Set RecOptions = Analyzer.GetRecordingOptions( )
' do the changes of recording options here
RecOptions.Save( CurrentDir & "Input\rec_options.rec" )

Teledyne LeCroy Automation API for PETracer/PETrainer

56

rec_mode

Enumerated value providing the mode to set; ERecModes enumerator

RMODE_USE_TRG ( 2 ) – event trigger

5.1.3 IRecOptions::SetRecMode

HRESULT SetRecMode (

[in] ERecModes rec_mode )

Sets the recording mode.

Parameters

has the following values:

RMODE_SNAPSHOT ( 0 ) – snapshot recording mode
RMODE_MANUAL ( 1 ) – manual trigger

Return values

Remarks

Example

WSH:

C++:

E_INVALIDARG Invalid recording mode was specified

The default setting of recording options is a “snapshot” recording mode.

Set Analyzer = WScript.CreateObject( “CATC.PETracer” )
Set RecOptions = Analyzer.GetRecordingOptions( )
RecOptions.SetRecMode 2 ' Event trigger

Teledyne LeCroy Automation API for PETracer/PETrainer

57

buffer_size

Size of the recording buffer in bytes

5.1.4 IRecOptions::SetBufferSize

HRESULT SetBufferSize (

[in] long buffer_size )

Sets the size of buffer to record.

Parameters

Return values

Remarks

Example

WSH:

C++:

E_INVALIDARG Invalid buffer size was specified

The default setting is 1MB for PETracer x1, 16MB for PETracer ML, and 32MB for PETracer EML.

Set Analyzer = WScript.CreateObject( “CATC.PETracer” )
Set RecOptions = Analyzer.GetRecordingOptions( )
RecOptions.SetBufferSize 2*1024*1024 ' 2Mb

Teledyne LeCroy Automation API for PETracer/PETrainer

58

posttrigger_percentage

Size of the post trigger buffer in percent of the whole recording buffer

(see IRecOptions::SetBufferSize, Page 51)

5.1.5 IRecOptions::SetPostTriggerPercentage

HRESULT SetPostTriggerPercentage (

[in] short posttrigger_percentage )

Sets the post trigger buffer size.

Parameters

Return values

Remarks

IRecOptions::SetRecMode, Page 50). The default setting is 50%.

Example

WSH:

C++:

E_INVALIDARG Invalid percentage was specified

This method call has no effect if recording mode was set to

Set Analyzer = WScript.CreateObject( “CATC.PETracer” )
Set RecOptions = Analyzer.GetRecordingOptions( )
RecOptions.SetPostTriggerPercentage 60 ' 60%

RMODE_SNAPSHOT (see

Teledyne LeCroy Automation API for PETracer/PETrainer

59

beep

TRUE – Beep when a trigger occurs,
FALSE – Do not beep when a trigger occ ur s.

B

5.1.6 IRecOptions::SetTriggerBeep

HRESULT SetTriggerBeep (

[in] BOOL beep )

Sets a flag to make a sound when a trigger occurs.

Parameters

Return values

Remarks

Example

WSH:

C++:

The default state of the beeper is FALSE.

Set Analyzer = WScript.CreateObject( “CATC.PETracer” )
Set RecOptions = Analyzer.GetRecordingOptions( )
RecOptions.SetTriggerBeep TRUE

Teledyne LeCroy Automation API for PETracer/PETrainer

60

save

TRUE – save external signals,
FALSE – do not save external signals

5.1.7 IRecOptions::SetSaveExternalSignals

HRESULT SetSaveExternalSignals (

[in] BOOL save )

Sets a flag to save external signals.

Parameters

Return values

Remarks

Example

WSH:

C++:

By default, external signals are not saved.

Set Analyzer = WScript.CreateObject( “CATC.PETracer” )
Set RecOptions = Analyzer.GetRecordingOptions( )
RecOptions.SetSaveExternalSignals TRUE

Teledyne LeCroy Automation API for PETracer/PETrainer

61

file_name

String that provides the full file pathname to where the recording is

stored

5.1.8 IRecOptions::SetTraceFileName

HRESULT SetTraceFileName (

[in] BSTR file_name )

Sets the file path to where the trace is stored after recording.

Parameters

Return values

Remarks

Example

WSH:

C++:

If the specified file does not exist, it is created; if it exists, it is overwritten.

CurrentDir = Left( WScript.ScriptFullName, InstrRev( WScript.ScriptFullName, “\” ) )
Set Analyzer = WScript.CreateObject( “CATC.PETracer” )
Set RecOptions = Analyzer.GetRecordingOptions( )
' do the changes of recording options here
RecOptions.Save( CurrentDir & "Input\trace.pex" )

Teledyne LeCroy Automation API for PETracer/PETrainer

62

5.1.9 IRecOptions::Reset

HRESULT Reset ( )

Resets the recording options to the initial state.

Parameters

Return values

Remarks

For default values of recording options, see the remarks sections of all IRecOptions, IPERecOptions,

and IPERecOptions2 methods.

Example

WSH:

Set Analyzer = WScript.CreateObject( “CATC.PETracer” )
Set RecOptions = Analyzer.GetRecordingOptions
RecOptions.SetRecMode 2 ' Event trigger
RecOptions.SetBufferSize 1024*1024 ' 1Mb
RecOptions.SetPostTriggerPercentage 60 ' 60%
. . .
RecOptions.Reset

C++:

Teledyne LeCroy Automation API for PETracer/PETrainer

63

5.2 IPERecOptions in t er f ace

This interface is identical to the IRecOptions interface (see Page 48).

5.3 IPERecOptions2 in t er f ace

The IPERecOptions2
This interface is derived from the IPERecOptions interface.
The IPERecOptions2

SetTargetAnalyzer
SetLinkWidth
SetBase10Spec
SetExternalRefClock
SetDisableDescrambling
SetDisableDeskew
SetAutoConfigPolarity
SetInhibit
SetReverseLanes
SetInvertPolarity

interface is a primary dual interface for the PERecOptions object.

interface implements all methods from the IPERecOptions interface, plus the following:

Teledyne LeCroy Automation API for PETracer/PETrainer

64

target_analyzer

Enumerated value that provides the platform to set; ETargetAnalyzer

TARGETANALZYER_X1
TARGETANALZYER_ML
TARGETANALZYER_ML2
TARGETANALZYER_EML
TARGETANALZYER_SML (4)
TARGETANALZYER_RDWD (6)
TARGETANALZYER_MP (7)
TARGETANALZYER_MPX8 (8
TARGETANALZYER_MPSP (9)
TARGETANALZYER_MPx8_2 (10)
TARGETANALZYER_MPHR (11) – Summit T24

5.3.1 IPERecOptions2::SetTargetAnalyzer

HRESULT SetTargetAnalyzer(

[in] ETargetAnalyzer target_analyzer )

Sets the hardware configuration for the recording options.

Parameters

has the following values:

(0) - PETracer x1
(1) - PETracer ML

(2) - PETracer ML (2 boxes)
(3) - PETracer EML

– Edge T1-4
– Summit T2
– Summit T3-16

) – Summit T3-8

– Summit T28

– Summit T3-8 (2 boxes)

Teledyne LeCroy Automation API for PETracer/PETrainer

65

link_width

Link width to set; Allowed values are

PETracer EML - 1, 2, 4, 8, 16

5.3.2 IPERecOptions2::SetLinkWidth

HRESULT SetLinkWidth (

[in] int link_width )

Sets the link width.

Parameters

PETracer x1 - 1
PETracer ML - 1, 2, 4, 8

Teledyne LeCroy Automation API for PETracer/PETrainer

66

base_10_spec

When TRUE, the PETracer hardware uses Base Spec 1.0 com patibil ity
mode

5.3.3 IPERecOptions2::SetBase10Spec

HRESULT SetBase10Spec (

[in] BOOL base_10_spec )

Sets PCI Express Base Specification 1.0 compatibility mode.

Parameters

Remarks

Implemented for PETracer ML and PETracer EML. Not implemented for PETracer x1.

Teledyne LeCroy Automation API for PETracer/PETrainer

67

ext_ref_clock

When TRUE, the external reference clock is used

5.3.4 IPERecOptions2::SetExternalRefClock

HRESULT SetExternalRefClock(

[in] BOOL ext_ref_clock )

Specifies whether to use the external or internal reference clock

Parameters

Teledyne LeCroy Automation API for PETracer/PETrainer

68

disable_descrambling

When TRUE, the descrambling is disabled

5.3.5 IPERecOptions2::SetDisableDescrambling

HRESULT SetDisableDescrambling (

[in] BOOL disable_descrambling )

Disables/enables descrambling of incoming traffic.

Parameters

Remarks

Implemented for PETracer ML and PETracer EML. Not implemented for PETracer x1.

Teledyne LeCroy Automation API for PETracer/PETrainer

69

disable_deskew

When TRUE, the deskew is disabled

5.3.6 IPERecOptions2::SetDisableDeskew

HRESULT SetDisableDeskew(

[in] BOOL disable_deskew )

Disables/enables deskew of incoming traffic.

Parameters:

Remarks

Implemented for PETracer ML and PETracer EML. Not implemented for PETracer x1.

Teledyne LeCroy Automation API for PETracer/PETrainer

70

auto_config

When TRUE, lane polarity is detected automatically for all lanes.

5.3.7 IPERecOptions2::SetAutoConfigPolarity

HRESULT SetAutoConfigPolarity(

[in] BOOL auto_config )

Enables/disables automatic polarity detection.

Parameters:

Remarks

Implemented for PETracer ML and PETracer EML. Not implemented for PETracer x1.

Teledyne LeCroy Automation API for PETracer/PETrainer

71

direction

Enumerated value that provides traffic direction to inhibit; EDirection has

DIRECTION_DOWNSTREAM (1) - downstream traffic

inhibit

Specifies whether to inhibit traffic specified in the direction parameter

5.3.8 IPERecOptions2::SetInhibit

HRESULT SetInhibit(

[in] EDirection direction,
[in] BOOL inhibit )

Inhibits one of the traffic directions.

Parameters:

the following values:

DIRECTION_UPSTREAM (0) - upstream traffic

Remarks

Implemented for PETracer ML and PETracer EML. Not implemented for PETracer x1.

Teledyne LeCroy Automation API for PETracer/PETrainer

72

direction

Enumerated value that provides traffic direction for lane reversal;

DIRECTION_DOWNSTREAM (1) - downstream traffic

reverse

Specifies whether to reverse the lanes in the direction selected.

5.3.9 IPERecOptions2::SetReverseLanes

HRESULT SetReverseLanes(

[in] EDirection direction,
[in] BOOL reverse )

Allows lane reversal on the specified traffic direction.

Parameters:

EDirection has the following values:

DIRECTION_UPSTREAM (0) - upstream traffic

Remarks

Implemented for PETracer ML and PETracer EML. Not implemented for PETracer x1.

Teledyne LeCroy Automation API for PETracer/PETrainer

73

direction

Enumerated value that provides traffic direction for polarity inversion;

DIRECTION_DOWNSTREAM (1) - downstream traffic

lane

Specifies the lane for polarity inversion

invert

Sets polarity inversion on the specified lane and specified link direction

5.3.10 IPERecOptions2::SetInvertPolarity

HRESULT SetInvertPolarity (

[in] EDirection direction,
[in] int lane,
[in] BOOL invert )

Allows polarity inversion of the specified lane and specified traffic direction.

Parameters:

EDirection has the following values:

DIRECTION_UPSTREAM (0) - upstream traffic

Remarks

Implemented for PETracer ML and PETracer EML. Not implemented for PETracer x1. This call fails if
automatic polarity detection is enabled (see IPERecOptions2::SetAutoConfigPolarity, Page 64)

Teledyne LeCroy Automation API for PETracer/PETrainer

74

link_speed

- enum that can have following values:

SPD_G3 ( 3 )

5.4 IPERecOptions3 in t er f ace

The IPERecOptions3
This interface is derived from the IPERecOptions interface.
The IPERecOptions3

SetLinkSpeed
GetSimpleTrigger
GetSimpleFilter
RestoreDefaultFactorySettings

5.4.1 IPERecOptions3::SetLinkSpeed

HRESULT SetLinkSpeed ( [in] ERecOptSpeed e_link_speed )

Sets the link speed for the recording options.

Parameters:

interface is a primary dual interface for the PERecOptions object.

interface implements all methods from the IPERecOptions interface, plus the following:

SPD_AUTO_DETECT ( 0 )
SPD_G1 ( 1 )
SPD_G2 ( 2 )

Teledyne LeCroy Automation API for PETracer/PETrainer

75

retval] IDispatch** ppISimpleTrigger)

e_trig_type

enum that can have following values:

b_force
advanced trigger already exists. In this case the trigger will be
converted to the simple type);

5.4.2 IPERecOptions3::GetSimpleTrigger

HRESULT GetSimpleTrigger ( [in] ETriggerType e_trig_type, [in] BOOL b_force, [out,

Returns simple trigger interface of the given trigger type.

Parameters:

RIGGER_EVENTTYPE_ERROR_ANY ( 1 )

IGGER_EVENTTYPE_LINKSTATE ( 2 )

( 3 )

ENTTYPE_TLP_CONFIG_RD ( 4 )

( 5 )

( 6 )

( 7 )

( 8 )

_EVENTTYPE_TLP_MEM_WR ( 9 )

( 10 )

( 11 )

( 12 )

( 101 )
( 102 )

( 103 )

( 104 )

( 105 )

VENTTYPE_DLLP_NAK ( 106 )

POWER_MANAGEMENT ( 107 )

( 200 )

( 201 )

( 202 )

( 203 )

( 204 )

_SPEEDCHANGE_G2 ( 206 )

( 209 )

( 208 )

( 210 )

R_EVENTTYPE_ERROR_TOKEN ( 211 )

( 212 )

- boolean that can be 1 or 0 (1 is for enforcing even if the

Return values

SimpleTrigger object

Remarks

Teledyne LeCroy Automation API for PETracer/PETrainer

76

Example

Set Analyzer = WScript.CreateObject("CATC.PETracer")
Set recOpt = Analyzer.GetRecordingOptions()
recOpt.SetRecMode(2)
ENFORCE = 1
TRIGGER_EVENTTYPE_TS2 = 102
Set simpleTrigger = recOpt.GetSimpleTrigger(TRIGGER_EVENTTYPE_TS2, ENFORCE)

See SimpleTrigger for more information.

Teledyne LeCroy Automation API for PETracer/PETrainer

77

retval] IDispatch** ppISimpleFilter)

e_filter_type

enum that can have following values:

b_force
advanced trigger already exists. In this case the trigger will be converted
to the simple type);

5.4.3 IPERecOptions3::GetSimpleFilter

HRESULT GetSimpleFilter ( [in] EFilterType e_filter_type, [in] BOOL b_force, [out,

Returns simple filter interface of the given filter type. Parameters:

( 1 )

FILTER_DLLP_UPDATE_FC ( 2 )

- boolean that can be 1 or 0 (1 is for enforcing even if the

Return values

SimpleFilter object

Remarks

Example

Set Analyzer = WScript.CreateObject("CATC.PETracer")
Set recOpt = Analyzer.GetRecordingOptions()
recOpt.SetRecMode(2)
ENFORCE = 1
FILTER_PERRET_OS_SKIP = 1
Set simpleFilter = recOpt.GetSimplefilter(FILTER_PERRET_OS_SKIP, ENFORCE)

See SimpleFilter for more information.

Teledyne LeCroy Automation API for PETracer/PETrainer

78

e_filter_type

enum that can have following values:

b_force
advanced trigger already exists. In this case the trigger will be converted
to the simple type);

5.4.4 IPERecOptions3:: RestoreDefaultFactorySettings

HRESULT RestoreDefaultFactorySettings ()

Restores factory default settings. Parameters:

( 1 )

FILTER_DLLP_UPDATE_FC ( 2 )

- boolean that can be 1 or 0 (1 is for enforcing even if the

Return values

SimpleFilter object

Remarks

Example

Set Analyzer = WScript.CreateObject("CATC.PETracer")
Set recOpt = Analyzer.GetRecordingOptions()
recOpt.SetRecMode(2)
ENFORCE = 1
FILTER_PERRET_OS_SKIP = 1
Set simpleFilter = recOpt.GetSimplefilter(FILTER_PERRET_OS_SKIP, ENFORCE)

Teledyne LeCroy Automation API for PETracer/PETrainer

79

5.5 SimpleTrigger

SimpleTrigger allows enabling /disabling the trigger and setting data stream direction.
The SimpleTrigger interface implements following methods:

SetEnabled
IsEnabled
SetDirection
GetDirection

5.5.1 SimpleTrigger::SetEnabled

HRESULT SetEnabled ( [in] BOOL b_enabled )

Puts the trigger into enabled or disabled state.

5.5.2 SimpleTrigger::IsEnabled

HRESULT IsEnabled ( [out, retval] BOOL* pb_enabled )

Retrieves trigger's state.

5.5.3 SimpleTrigger::SetDirection

HRESULT SetDirection ( [in] EDirection e_dir )

Sets the trigger's direction.

Parameters:

e_dir - enum that can have following values:
DIRECTION_UPSTREAM ( 0 )
DIRECTION_DOWNSTREAM ( 1 )
DIRECTION_BOTH ( 2 )
DIRECTION_NONE ( 4 )

Example

ENFORCE = 1
TRIGGER_EVENTTYPE_TS2 = 102
DIRECTION_UPSTREAM = 0
STATE_ENABLED = 1

Set Analyzer = WScript.CreateObject("CATC.PETracer")
Set recOpt = Analyzer.GetRecordingOptions()
recOpt.SetRecMode(2)
Set simpleTrigger = recOpt.GetSimpleTrigger(TRIGGER_EVENTTYPE_TS2, ENFORCE)
simpleTrigger.SetEnabled(STATE_ENABLED)
simpleTrigger.SetDirection(DIRECTION_UPSTREAM)

Teledyne LeCroy Automation API for PETracer/PETrainer

80

5.5.4 SimpleTrigger::GetDirection

HRESULT GetDirection ( [out, retval] EDirection* pe_dir )

Gets the trigger's direction.

Teledyne LeCroy Automation API for PETracer/PETrainer

81

5.6 SimpleFilter

SimpleFilter allows enabling /disabling the filter and setting data stream direction..
The SimpleFilter interface implements following methods SetEnabled

SetEnabled
IsEnabled
SetDirection
GetDirection

5.6.1 SimpleFilter::SetEnabled

HRESULT SetEnabled ( [in] BOOL b_enabled )

Puts the filter into enabled or disabled state.

5.6.2 SimpleFilter::IsEnabled

HRESULT IsEnabled ( [out, retval] BOOL* pb_enabled )

Retrieves filter's state.

5.6.3 SimpleFilter::SetDirection

HRESULT SetDirection ( [in] EDirection e_dir )

Sets the filter's direction.

Parameters:

e_dir - enum that can have following values:
DIRECTION_UPSTREAM ( 0 )
DIRECTION_DOWNSTREAM ( 1 )
DIRECTION_BOTH ( 2 )
DIRECTION_NONE ( 4 )

Example

ENFORCE = 1
FILTER_PERRET_OS_SKIP = 1
DIRECTION_DOWNSTREAM = 1
STATE_ENABLED = 1

Set Analyzer = WScript.CreateObject("CATC.PETracer")
Set recOpt = Analyzer.GetRecordingOptions()
recOpt.SetRecMode(2)
Set simplefilter = recOpt.GetSimpleFilter(FILTER_PERRET_OS_SKIP, ENFORCE)
simpleFilter.SetEnabled(STATE_ENABLED)
simpleFilter.SetDirection(DIRECTION_DOWNSTREAM)

Teledyne LeCroy Automation API for PETracer/PETrainer

82

5.6.4 SimpleFilter::GetDirection

HRESULT GetDirection ( [out, retval] EDirection* pe_dir )

Gets the filter's direction.

Teledyne LeCroy Automation API for PETracer/PETrainer

83

Interfaces

Description

IGenOptions

Allows you to load/save recording options from/to the file and
reset generation options

IPEGenOptions

Identical to IGenOptions interface

IPEGenOptions2

Extends the IPEGenOptions interface. Adds set up for link
algorithm, skew, lane reversal, and polarity inversion

6 PEGenOptions Object

The PEGenOptions object represents the options for the PETrainer™ (ML and EML) hardware. Also used to
specify the traffic generation parameters.

The PEGenOptions object allows user to:

• Load/save the generation options from/to the file

• Set up custom generation parameters, such as link width, etc.

The PEGenOptions object can be created by using IPEAnalyzer::GetGenerationOptions method (see Page 18)
The PEGenOptions object supports the following interfaces:

width, spec mode, external reference clock, descrambling

The IPERecOptions2 interface is a primary interface for PERecOptions object.

Teledyne LeCroy Automation API for PETracer/PETrainer

84

6.1 IGenOptions interface

The IgenOptions interface is a dual interface for the PEGenOptions object.
IGenOptions implements the following methods:

Load
Save
Reset

Note: All methods of the IGenOptions interface are also available in the IPEGenOptions (see Page 73) and the
IPEGenOptions2 (see Page 73) interfaces.

Teledyne LeCroy Automation API for PETracer/PETrainer

85

file_name

String that provides the full pathname to the generation options file

6.1.1 IGenOptions::Load

HRESULT Load (

[in] BSTR file_name )

Loads generation options from the specified file.

Parameters

Return values

ANALYZERCOMERROR_UNABLEOPENFILE Unable to open file

Remarks

Example

WSH:

CurrentDir = Left( WScript.ScriptFullName, InstrRev( WScript.ScriptFullName, “\” ) )
Set Analyzer = WScript.CreateObject( “CATC.PETracer” )
Set GenOptions = Analyzer. GetGenerationOptions
GenOptions.Load( CurrentDir & "Input\gen_options.gen" )

C++:

Teledyne LeCroy Automation API for PETracer/PETrainer

86

file_name

String that provides the full pathname to the generation options file

6.1.2 IGenOptions::Save

HRESULT Save (

[in] BSTR file_name )

Saves generation options into the specified file.

Parameters

Return values

Remarks

Example

WSH:

C++:

ANALYZERCOMERROR_UNABLEOPENFILE Unable to open file

If the specified file does not exist, it is created; if it exists, it is overwritten.

CurrentDir = Left( WScript.ScriptFullName, InstrRev( WScript.ScriptFullName, “\” ) )
Set Analyzer = WScript.CreateObject( “CATC.PETracer” )
Set GenOptions = Analyzer. GetGenerationOptions
GenOptions.Save( CurrentDir & "Input\gen_options.gen" )

Teledyne LeCroy Automation API for PETracer/PETrainer

87

6.1.3 IGenOptions::Reset

HRESULT Reset ( )

Resets the generation options to its initial state.

Parameters

Return values

Remarks

Example

WSH:

Set Analyzer = WScript.CreateObject( “CATC.PETracer” )
Set GenOptions = Analyzer.GetGenerationOptions( )
GenOptions.Reset( )

C++:

Teledyne LeCroy Automation API for PETracer/PETrainer

88

6.2 IPEGenOptions interface

This interface is identical to the IGenOptions interface (see Page 69).

6.3 IPEGenOptions2 interface

The IPEGenOptions2 interface is a primary dual interface for the PEGenOptions object.
This interface is derived from the IPEGenOptions interface.
The IPEGenOptions2

SetTargetGenerator
SetWorkAsRoot
SetLinkWidth
SetBase10Spec

SetExternalRefClock

SetDisableDescrambling
SetDisableScrambling
SetAutoConfig
SetReverseLanes
SetInvertPolarity
SetSkew

interface implements all methods from the IPEGenOptions interface, plus the following:

Teledyne LeCroy Automation API for PETracer/PETrainer

89

target_generator

Enumerated value that provides the platform to set; ETargetGenerator

TARGETGENERATOR_ML
TARGETGENERATOR_EML
TARGETGENERATOR_SMT
TARGETGENERATOR_Z3 (3) – Summit Z3

6.3.1 IPEGenOptions2::SetTargetGenerator

HRESULT SetTargetGenerator (

[in] ETargetGenerator target_generator )

Sets the hardware configuration for the generation options.

Parameters:

has the following values:

(0) – PETrainer ML

(1) – PETrainer EML
(2) – Summit Z2

Return values

Remarks

Example

WSH:

Set Analyzer = WScript.CreateObject( “CATC.PETracer” )
Set GenOptions = Analyzer.GetGenerationOptions( )
GenOptions.SetTargetGenerator( 1 )

C++:

Teledyne LeCroy Automation API for PETracer/PETrainer

90

root

If TRUE, then the PETrainer emulates a Root Complex,
If FALSE, it emulates an endpoint device.

6.3.2 IPEGenOptions2::SetWorkAsRoot

HRESULT SetWorkAsRoot

( [in] BOOL root )

Parameters

Return values

Remarks

Example

WSH:

Set Analyzer = WScript.CreateObject( “CATC.PETracer” )
Set GenOptions = Analyzer.GetGenerationOptions( )
GenOptions.SetWorkAsRoot( 0 )

C++:

Teledyne LeCroy Automation API for PETracer/PETrainer

91

link_width

Link width to set; allowed values are
PETrainer EML - 1, 4, 8, 16

6.3.3 IPEGenOptions2::SetLinkWidth

HRESULT SetLinkWidth (

[in] int link_width )

Sets the link width.

Parameters:

PETrainer ML - 1, 4, 8

Return values

Remarks

Example

WSH:

Set Analyzer = WScript.CreateObject( “CATC.PETracer” )
Set GenOptions = Analyzer. GetGenerationOptions
GenOptions.SetLinkWidth( 1 )

C++:

Teledyne LeCroy Automation API for PETracer/PETrainer

92

base_10_spec

When TRUE, the PETrainer hardware uses Base Spec 1.0 compatibility
mode

6.3.4 IPEGenOptions2::SetBase10Spec

HRESULT SetBase10Spec (

[in] BOOL base_10_spec )

Sets the PCI Express Base Specification 1.0 compatibility mode.

Parameters

Return values

Remarks

Example

WSH:

Set Analyzer = WScript.CreateObject( “CATC.PETracer” )
Set GenOptions = Analyzer. GetGenerationOptions
GenOptions.SetBase10Spec( 0 )

C++:

Teledyne LeCroy Automation API for PETracer/PETrainer

93

ext_ref_clock

When TRUE, the external reference clock is used

6.3.5 IPEGenOptions2::SetExternalRefClock

HRESULT SetExternalRefClock(

[in] BOOL ext_ref_clock )

Specifies whether to use the external or the internal reference clock

Parameters

Remarks

Implemented for PETrainer ML. Not implemented for PETrainer EML.

Teledyne LeCroy Automation API for PETracer/PETrainer

94

disable_descrambling

When TRUE, descrambling is disabled

6.3.6 IPEGenOptions2::SetDisableDescrambling

HRESULT SetDisableDescrambling (

[in] BOOL disable_descrambling )

Disables/enables descrambling of incoming traffic.

Parameters

Return values

Remarks

Example

WSH:

Set Analyzer = WScript.CreateObject( “CATC.PETracer” )
Set GenOptions = Analyzer.GetGenerationOptions( )
GenOptions.SetDisableDescrambling( 0 )

C++:

Teledyne LeCroy Automation API for PETracer/PETrainer

95

disable_scrambling

When TRUE, scrambling is disabled

6.3.7 IPEGenOptions2::SetDisableScrambling

HRESULT SetDisableScrambling (

[in] BOOL disable_scrambling )

Disables/enables scrambling of outgoing traffic.

Parameters

Return values

Remarks

Example

WSH:

Set Analyzer = WScript.CreateObject( “CATC.PETracer” )
Set GenOptions = Analyzer. GetGenerationOptions
GenOptions.SetDisableScrambling( 0 )

C++: