Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Reference Manual
SAS/SATA Protocol Suite software version 5.97
Generated: December 9, 2015, 08:27
Teledyne LeCroy Protocol Solutions Group
Trademarks and Servicemarks:
Teledyne LeCroy, Teledyne LeCroy Protocol Solutions Group, CATC, SASSuite, SATASuite, SASTracer, SATracer, SASTrainer, SATrainer, SASTracker and Avalanche are trademarks of Teledyne LeCroy. Microsoft, Windows, Windows 2000, and Win‐dows XP are registered trademarks of Microsoft Inc.
Intel and Pentium are registered trademarks of Intel Corporation.
All other trademarks and registered trademarks are property of their respective owners.
THE SPECIFICATIONS AND INFORMATION REGARDING THE PRODUCTS IN THIS MANUAL ARE SUBJECT TO CHANGE WITHOUT NOTICE. ALL INFORMATION, EXAMPLES AND RECOMMENDATIONS IN THIS MANUAL ARE BELIEVED TO BE ACCURATE BUT ARE REPRESENTED WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. USERS ARE FULLY RESPONSIBLE FOR THEIR APPLICATION OF ANY PRODUCTS.
THE SOFTWARE LICENSE AND LIMITED WARRANTY FOR THE ACCOMPANYING PRODUCT ARE SET FORTH IN INFORMATION THAT SHIPPED WITH THE PRODUCT AND ARE INCORPORATED HEREIN BY THIS REFERENCE. IF YOU ARE UNABLE TO LOCATE THE SOFTWARE LICENSE OR LIMITED WARRANTY, CONTACT Teledyne LeCroy FOR A COPY.
© 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.
WEEE Program
Teledyne LeCroy
3385 Scott Blvd.
Santa Clara, CA 95054
TEL: 800‐909‐7112 (USA and Canada)
TEL: 408‐653‐1260 (worldwide)
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite ii
Contents
Introduction................................................................................................................................... 1
System Requirements.....................................................................................................................................1
Support Resources .........................................................................................................................................1
Setting Up Automation for Local Use............................................................................................................2
Setting Up Automation for Remote Use ........................................................................................................2
Teledyne LeCroy SAS/SATA Protocol Suite COM API Object Model ...................................... 2
SASAnalyzer Object ..................................................................................................................... 4
ISASAnalyzer Interface ...................................................................................................................................5
ISASAnalyzer::GetBoardPlatform .......................................................................................................6
ISASAnalyzer::GetVersion ...................................................................................................................7
ISASAnalyzer::OpenFile .......................................................................................................................9
ISASAnalyzer::StartGeneration .........................................................................................................10
ISASAnalyzer::StopGeneration .........................................................................................................11
ISASAnalyzer:: StartGenerationByPort ............................................................................................12
ISASAnalyzer:: StopGenerationByPort .............................................................................................13
ISASAnalyzer:: GetTrainerExitCode ..................................................................................................13
ISASAnalyzer::StartRecording ..........................................................................................................14
ISASAnalyzer::StopRecording ...........................................................................................................16
ISASAnalyzer::MakeRecording ..........................................................................................................18
ISASAnalyzer::IsRunning ...................................................................................................................20
ISASAnalyzer::LoadDisplayOptions .................................................................................................22
ISASAnalyzer::LoadGlobalGenOptions ............................................................................................23
ISASAnalyzer::GetRecordingOptions ...............................................................................................24
ISASAnalyzer::ResumeGeneration ...................................................................................................26
ISASAnalyzer::ActivateDevice ...........................................................................................................27
ISASAnalyzer::ActivateDeviceByBoard ............................................................................................28
ISASAnalyzer::DeactivateDevice .......................................................................................................29
ISASAnalyzer::SetScenarioToPort ....................................................................................................30
ISASAnalyzer:: StartScenario ............................................................................................................32
ISASAnalyzer:: StopScenario ............................................................................................................34
ISASAnalyzer:: SetPortConfiguration ...............................................................................................36
ISASAnalyzer:: LoadPreEmphasisSignalFile ...................................................................................40
ISASAnalyzer::SetTracefileName ......................................................................................................40
ISASAnalyzer::DoSelfTest ..................................................................................................................41
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite iii
Teledyne LeCroy Contents
ISASAnalyzer ::SetVSELogToSaveAutomatically ............................................................................42
ISASAnalyzer ::SetVSELogModeToMultipleFile ..............................................................................43
ISASAnalyzer ::SetVSELogModeToSingleFile .................................................................................44
ISASAnalyzer ::SetVSELogModeToTraceRelativePath ...................................................................45
ISASAnalyzer:: SetDecodingAssignment .........................................................................................46
SierraSASAnalyzer Object ......................................................................................................... 47
SierraSTAnalyzer Object............................................................................................................ 48
STXSASAnalyzer Object ............................................................................................................ 49
STXSTAnalyzer Object ............................................................................................................... 50
SASTrace Object......................................................................................................................... 51
ITrace Interface ..............................................................................................................................................52
ITrace::GetName .................................................................................................................................53
ITrace::ApplyDisplayOptions .............................................................................................................55
ITrace::Save .........................................................................................................................................57
ITrace::GetPacketRow ........................................................................................................................59
ITrace::ExportToText ..........................................................................................................................60
ITrace::ExportToExcel ........................................................................................................................65
ITrace::Close .......................................................................................................................................66
ITrace::ReportFileInfo .........................................................................................................................67
ITrace::ReportErrorSummary ............................................................................................................68
ITrace::GetPacket ................................................................................................................................71
ITrace::GetPacketsCount ...................................................................................................................74
ITrace::GetTriggerPacketNum ...........................................................................................................76
ITrace::AnalyzerErrors .......................................................................................................................77
ISASTrace Interface.......................................................................................................................................79
ISASTrace::GetBusPacket .................................................................................................................80
ISASVerificationScript Interface ..................................................................................................................81
ISASVerificationScript::RunVerificationScript .................................................................................82
ISASVerificationScript:: GetVScriptEngine ......................................................................................85
SASRecOptions Object .............................................................................................................. 87
IRecOptions Interface ...................................................................................................................................87
IRecOptions::Load ..............................................................................................................................88
IRecOptions::Save ..............................................................................................................................89
IRecOptions::SetRecMode .................................................................................................................90
IRecOptions::SetBufferSize ...............................................................................................................91
IRecOptions::SetPostTriggerPercentage .........................................................................................92
IRecOptions::SetTriggerBeep ............................................................................................................93
IRecOptions::SetSaveExternalSignals ..............................................................................................94
IRecOptions::SetTraceFileName .......................................................................................................95
IRecOptions::Reset ............................................................................................................................96
iv Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Contents Teledyne LeCroy
ISASRecOptions Interface ............................................................................................................................96
SASPacket Object....................................................................................................................... 97
IPacket Interface ............................................................................................................................................97
IPacket::GetTimestamp ......................................................................................................................98
ISASPacket Interface.....................................................................................................................................99
IPacket::GetPacketData ....................................................................................................................100
IPacket::GetDirection ........................................................................................................................104
IPacket::GetErrors ............................................................................................................................105
IPacket:: GetLinkNumber .................................................................................................................106
IPacket:: GetFrameType ...................................................................................................................107
IPacket:: GetTotalDwords ................................................................................................................108
SASTraceErrors Object............................................................................................................ 109
ISASAnalyzerErrors Dispinterface.............................................................................................................109
ISASAnalyzerErrors::get_Item .........................................................................................................110
ISASAnalyzerErrors::get_Count ......................................................................................................111
SASVScriptEngine Object........................................................................................................ 113
IVScriptEngine Interface .............................................................................................................................114
IVScriptEngine::RunVScript .............................................................................................................115
IVScriptEngine::RunVScriptEx ........................................................................................................116
IVScriptEngine::LaunchVScript .......................................................................................................118
IVScriptEngine::Stop ........................................................................................................................119
SASVScriptEngine Object Events........................................................................................... 120
_IVScriptEngineEvents Interface ...............................................................................................................120
IVScriptEngineEvents::OnVScriptReportUpdated .........................................................................124
IVScriptEngineEvents::OnVScriptFinished ....................................................................................125
IVScriptEngineEvents::OnNotifyCount ...........................................................................................127
SASAnalyzer Object Events .................................................................................................... 129
_ISASAnalyzerEvents Dispinterface..........................................................................................................129
_ISASAnalyzerEvents::OnTraceCreated .........................................................................................131
_ISASAnalyzerEvents::OnStatusReport .........................................................................................133
SASVerification API.................................................................................................................. 137
Steps.............................................................................................................................................................137
SASVerification API methods.................................................................................................. 138
Attach( BYTE yDefaultPort, BSTR bstrDeviceId)......................................................................................138
Detach( int* pnErrorCode) ..........................................................................................................................138
Initialize ( BSTR bstrRTFName, BSTR bstrDeviceName, BSTR bstrTracesPath, BOOL bSaveOnlyFailed).................................................................................................138
AddTest( int nTestID) ..................................................................................................................................139
RunSASVerification() ..................................................................................................................................139
SASVerification Test Ids .............................................................................................................................139
STCompliance API.................................................................................................................... 142
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite v
Teledyne LeCroy Contents
VB Script ......................................................................................................................................................142
STCompliance API Methods.................................................................................................... 143
Attach ...........................................................................................................................................................143
Detach...........................................................................................................................................................143
Initialize ........................................................................................................................................................143
AddTest ........................................................................................................................................................145
RunCompliance ...........................................................................................................................................145
ChangeGTR03Params.................................................................................................................................145
ChangeNCQ01Params ................................................................................................................................146
ChangeNCQ03Params ................................................................................................................................146
ComplianceTestsEnum...............................................................................................................................147
ATAPIMediaTypeEnum ...............................................................................................................................149
PIO OUT Commands List............................................................................................................................149
DMA IN Commands List..............................................................................................................................150
How to Contact Teledyne LeCroy .......................................................................................... 151
vi Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Introduction
Introduction
The Teledyne LeCroy SAS/SATA Protocol Suite software provides a rich COM/Automation API to the most important functionalities of the Teledyne LeCroy Sierra/STX Protocol Analyzers and Teledyne LeCroy Sierra/STX Exercisers for implementation of automated programs for complicated testing, development, and debugging. The "dual" nature of the interfaces provided makes it easy to use the Teledyne LeCroy SAS/SATA Protocol Suite COM API in the different Integrated Development Environments (IDE) that support the COM architecture.
Special support for typeless script languages (such as VB and JavaScript), while overriding some restrictions imposed by script engines (remote access, dynamic object creation, and handling events), allows you to write client applications quickly and easily. You do not need significant programming skills or installation of 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 SAS/SATA Protocol Suite an attractive tool for automating and speeding many engineering processes.
System Requirements
The Automation API was introduced with the following release:
Teledyne LeCroy SAS/SATA Protocol Suite software 2.60/4.60. This document covers the functionality available in
Teledyne LeCroy SAS/SATA Protocol Suite 4.0 and above.
Support Resources
As new functionalities are added to the API, not all of them are supported by older versions of the analyzer software. For newer releases of analyzer software, please refer to the Teledyne LeCroy web site: www.teledynelecroy.com
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 1
Teledyne LeCroy Teledyne LeCroy SAS/SATA Protocol Suite COM API Object Model
Setting Up Automation for Local Use
To run Automation on the Sierra/STX Host Controller (the host machine attached to the Sierra/STX), you do not need to perform any special configuration. You can simply execute the scripts or programs that you have created, and they will run the analyzer. To use the Teledyne LeCroy SAS/SATA Protocol Suite COM API, the application should be registered during the installation process as a COM server in a system registry.
Setting Up Automation for Remote Use
To access Teledyne LeCroy SAS/SATA Protocol Suite COM API remotely over a network, install the application on both server and client systems and accept the Enabling Remote Access option during installation. You can also perform a manual DCOM configuration.
Teledyne LeCroy SAS/SATA Protocol Suite COM API Object Model
The Teledyne LeCroy SAS/SATA 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 SAS/SATA API object hierarchy: SASAnalyzer.
The following object model diagram shows how the objects in the object model fit together:
2 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
Teledyne LeCroy SAS/SATA Protocol Suite COM API Object Model Teledyne LeCroy
Only the SASAnalyzer object is creatable at the top level (for instance, via the CoCreateInstance call from a C/C++ client). Instantiation of an object of other classes requires API calls.
The Class ID and App ID for the SASAnalyzer object are the following.
Class ID: SASAnalyzer 12A4B62B‐107A‐42AE‐9C56‐08C5EC3C26E2
AppID: SASAnalyzer Lecroy.SASAnalyzer
All interfaces are dual interfaces that allow simple use from typeless languages (like VBScript), as well as from C/C++.
All objects implement the ISupportErrorInfo interface for easy error handling from the client.
* 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 "SASAutomation.tlb" no_namespace named_guids
Appropriate wrapper classes are created in .tli and .tlh files by the compiler.
Examples of WSH, VBScript, and C++ client applications are provided.
Object Interface Description
SASAnalyzer ISASAnalyzer
_ISASAnalyzerEvents
Represents the Teledyne LeCroy SAS/SATA Protocol Suite COM API application.
SASTrace ITrace
ISASTrace*
ISASVerificationScript*
Represents the recorded trace.
SASRecOptions IRecOptions
ISASRecOptions
Represents recording options.
SASPacket IPacket
ISASPacket*
Represents a single packet of the recorded trace.
SASTraceErrors ISASAnalyzerErrors* Represents the collection of errors that occurred in the recorded trace.
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 3
Teledyne LeCroy SASAnalyzer Object
SASAnalyzer Object
The SASAnalyzer object is the top‐level object of the SAS API. The SASAnalyzer object allows you to control recording and traffic generation, open trace files, and access recording and generation options. The SASAnalyzer object supports the following interfaces:
The ISASAnalyzer interface is the primary interface for the SASAnalyzer object.
The Class ID and App ID for the SASAnalyzer object are the following:
Class ID SASAnalyzer 12A4B62B‐107A‐42AE‐9C56‐08C5EC3C26E2
App ID SASAnalyzer Lecroy.SASAnalyzer
Example
WSH:Set Analyzer = WScript.CreateObject(
“Lecroy.SASAnalyzer” )
C++:ISASAnalyzer* poSASAnalyzer;
// create SASAnalyzer objectif ( FAILED( CoCreateInstance(
CLSID_SASAnalyzer,NULL, CLSCTX_SERVER,IID_ISASAnalyzer,(LPVOID *)&poSASAnalyzer ) )
return;
Interfaces Description
ISASAnalyzer Facilitates recording and traffic generation, opens trace files, and retrieves recording options. Adds advanced generator functionality and retrieves generation options.
_ISASAnalyzerEvents Events from SASAnalyzer object.
4 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASAnalyzer Object Teledyne LeCroy
ISASAnalyzer Interface
The ISASAnalyzer interface is a dual interface for the SASAnalyzer object.
ISASAnalyzer implements the following methods:
GetBoardPlatform GetVersion OpenFile StartGeneration StopGeneration StartGenerationByPort StopGenerationByPort StartRecording StopRecording MakeRecording IsRunning LoadDisplayOptions LoadGlobalGenOptions GetRecordingsOption ResumeGeneration ActivateDevice ActivateDeviceByBoard DeactivateDevice SetScenarioToPort StartScenario StopScenario SetPortConfiguration GetTrainerExitCode LoadPreEmphasisSignalFile SetTracefileName SetVSELogToSaveAutomatically SetVSELogModeToMultipleFile SetVSELogModeToSingleFile SetVSELogModeToTraceRelativePath SetDecodingAssignment
Note:All API functions work in real mode. They do not work in simulation mode.
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 5
Teledyne LeCroy SASAnalyzer Object
ISASAnalyzer::GetBoardPlatform
HRESULT GetBoardPlatform([out, retval]int* pnBoardPlatform);Retrieves the current version of the specified subsystem.
Retrieves connected board platform.
Parameters
None
Return Value
Returns below values for each platform:
34 : Sierra M124
32 : Sierra M122
14 : Sierra M6‐4
12 : Sierra M6‐2
11 : Sierra M6‐1
24 : STX 460, STX 431
22 : STX 231
6 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASAnalyzer Object Teledyne LeCroy
ISASAnalyzer::GetVersion
HRESULT GetVersion ( [in] EAnalyzerVersionType version_type,[out, retval] WORD* analyzer_version );
Retrieves the current version of the specified subsystem.
Parameters
version_type Subsystem whose version is requested
EAnalyzerVersionType enumerator has the following values:
ANALYZERVERSION_SOFTWARE ( 0 ) Software
analyzer_version Version of the subsystem queried
ANALYZERVERSION_SOFTWARE: Upper Byte = Software Major Version, Lower Byte = Software Minor Version
Return Value
ANALYZERCOMERROR_INVALIDVERSIONTYPE Specified version type is invalid.
Example
WSH:Set Analyzer = WScript.CreateObject("Lecroy.SASAnalyzer")SwVersion = Analyzer.GetVersion(0)MsgBox "Software" & SwVersion
C++:HRESULT hr;ISASAnalyzer* poSASAnalyzer;
// Create SASAnalyzer object.if ( FAILED( CoCreateInstance ( CLSID_SASAnalyzer, NULL, CLSCTX_SERVER, IID_ISASAnalyzer, (LPVOID *)&poSASAnalyzer ) )
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("SASTracer client"), MB_OK ); else ::MessageBox( NULL, er.ErrorMessage(), _T("SASTracer client"), MB_OK ); return 1;}
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 7
Teledyne LeCroy SASAnalyzer Object
TCHAR buffer[20];_stprintf( buffer, _T("Software version:%d.%d"), HIBYTE(sw_version), LOBYTE(sw_version) );
8 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASAnalyzer Object Teledyne LeCroy
ISASAnalyzer::OpenFile
HRESULT OpenFile ( [in] BSTR file_name, [out, retval] IDispatch** trace );
Opens trace file and creates the SASTrace object.
Parameters
file_name String providing the full pathname to the trace file
trace Address of a pointer to the SASTrace object interface
Return Values
ANALYZERCOMERROR_UNABLEOPENFILE Unable to open file
Remarks
SASTrace object is created via this method call, if call was successful.
Example
WSH:CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\"))Set Analyzer = WScript.CreateObject("Lecroy.SASAnalyzer ")Set Trace = Analyzer.OpenFile (CurrentDir & "Input\errors.scs")
C++:HRESULT hr;ISASAnalyzer* poSASAnalyzer;// Create SASAnalyzer object.if ( FAILED( CoCreateInstance( CLSID_SASAnalyzer, NULL, CLSCTX_SERVER, IID_ISASAnalyzer, (LPVOID *)&poSASAnalyzer ) )
return;// Open trace file.IDispatch* trace;try{trace = poSASAnalyzer->OpenFile( m_szRecFileName );}catch (_com_error& er){ if (er.Description().length() > 0) ::MessageBox( NULL, er.Description(), _T("SASTracer client"), MB_OK ); else ::MessageBox( NULL, er.ErrorMessage(), _T("SASTracer client"), MB_OK ); return 1;}// Query for VTBL interfaceISASTrace* SAS_trace;hr = trace->QueryInterface( IID_ISASTrace, (LPVOID *)&SAS_trace );trace->Release();if( FAILED(hr) )return;
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 9
Teledyne LeCroy SASAnalyzer Object
ISASAnalyzer::StartGenerationHRESULT StartGeneration (
[in] BSTR gen_file_name);
Starts traffic generation from the file.
Parameters
gen_file_nameString providing the full pathname to the generation file
Return Values
ANALYZERCOMERROR_UNABLEOPENFILE Unable to open file
ANALYZERCOMERROR_UNABLESTARTGENERATION Unable to start generation (invalid state, etc.)
Remarks
Example
WSH:CurrentDir = Left( WScript.ScriptFullName, InstrRev( WScript.ScriptFullName, “\”))Set Analyzer = WScript.CreateObject( “Lecroy.SASAnalyzer” ) ret = Analyzer.StartGeneration( CurrentDir & "Input\connect.ssg")
C++:
HRESULT hr; ISASAnalyzer* poSASAnalyzer; TCHAR m_szGenFileName [_MAX_PATH];
// Create SASAnalyzer object.if ( FAILED( CoCreateInstance( CLSID_SASAnalyzer, NULL, CLSCTX_SERVER, IID_ISASAnalyzer, (LPVOID *)&poSASAnalyzer ) ) return;
. . .
try{poAnalyzer->StartGeneration( m_szGenFileName); }catch (_com_error& er){ if (er.Description().length() > 0) ::MessageBox( NULL, er.Description(), _T("SASTracer client"), MB_OK ); else ::MessageBox( NULL, er.ErrorMessage(), _T("SASTracer client"), MB_OK ); return 1; }
10 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASAnalyzer Object Teledyne LeCroy
ISASAnalyzer::StopGenerationHRESULT StopGeneration ( );
Stops any generation in progress.
Parameters
Return Values
ANALYZERCOMERROR_UNABLESTARTGENERATION Unable to stop generation(invalid state, etc.)
Remarks
Example
C++: ISASAnalyzer* poAnalyzer;
. . .
try{ poAnalyzer->StopGeneration(); } catch (_com_error& er) { if (er.Description().length() > 0) ::MessageBox( NULL, er.Description(), _T("SASTracer client"), MB_OK ); else ::MessageBox( NULL, er.ErrorMessage(), _T("SASTracer client"), MB_OK ); return 1; }
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 11
Teledyne LeCroy SASAnalyzer Object
ISASAnalyzer:: StartGenerationByPort
HRESULT StartGenerationByPort (
[in] BSTR gen_file_name,
[in] int nBoardIndex,
[in] int nPortIndex);
This function runs generation on specified ports.
Parameters
gen_file_name Specifies the SAS/SATA Protocol Suite file name to load.
nBoardIndex Zero based index of board. If you have only one board, this parameter should be set to zero.
nPortIndex Port index where generation should start.
Remarks
You can run generation files on specific ports on the connected board. The difference between this function and the StartGeneration function is that this one starts generation on only specified ports while the StartGeneration function starts generation on all ports.
12 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASAnalyzer Object Teledyne LeCroy
ISASAnalyzer:: StopGenerationByPortHRESULT StopGenerationByPort (
[in] int nBoardIndex,[in] int nPortIndex);
This function stops generation on specified ports.
Parameters
nBoardIndex Zero based index of board. If you have only one board, this parameter should be set to zero.
nPortIndex Port index where generation should stop.
Remarks
You can stop generation files on specific ports on the connected board. The difference between this function and the StopGeneration function is that this one stops generation on only specified ports while the StopGeneration function stops generation on all ports.
ISASAnalyzer:: GetTrainerExitCodeHRESULT GetTrainerExitCode (
[in] int nBoardIndex,[in] int nPortIndex,[out, retval] BYTE*pyTrainerExitCode);
This function returns SAS/SATA Protocol Suite exit code by board and port index.
Parameters
nBoardIndex Zero based index of board. If you have only one board, this parameter should be set to zero.
nPortIndex Specifies the port index.
Remarks
Receives the board and port index and retrieves the exit code of the last running generation. This function is normally called after generation is stopped to examine the exit code of generation execution.
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 13
Teledyne LeCroy SASAnalyzer Object
ISASAnalyzer::StartRecordingHRESULT StartRecording ( [in] BSTR ro_file_name );
Starts recording with specified recording options.
Parameters
ro_file_name String providing the full pathname to the recording options file. If the parameter is omitted, then recording starts with default recording options.
Return Values
ANALYZERCOMERROR_UNABLESTARTRECORDING Unable to start recording
Remarks
After recording starts, this function will return. The Analyzer continues recording until it is finished or until the StopRecording method call is performed. During recording, events are sent to the event sink (see the ISASAnalyzer Interface).
The recording options file is the file with extension .sac created by the SAS/SATA Protocol Suite application. You can create this file when you select File –> Protocol Analyzer… from the SAS Protocol Suite application menu, change the recording options in the Protocol Analyzer project, and select the Save… button.
Example
VBScript:
<OBJECTRUNAT=ServerID = AnalyzerCLASSID = " clsid: 297CD804-08F5-4A4F-B3BA-779B2654B27C "></OBJECT>
<INPUT TYPE=TEXT VALUE="" NAME="TextRecOptions">
<SCRIPT LANGUAGE="VBScript"><!--Sub BtnStartRecording_OnClickOn Error Resume Next Analyzer.StartRecording TextRecOptions.value If Err.Number <> 0 Then MsgBox Err.Number & ":" & Err.Description End IfEnd Sub--></SCRIPT>C++:
14 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASAnalyzer Object Teledyne LeCroy
ISASAnalyzer* sas_analyzer;BSTR ro_file_name;
. . .
try{sas_analyzer->StartRecording( ro_file_name )}catch (_com_error& er){ if (er.Description().length() > 0) ::MessageBox( NULL, er.Description(), _T("SASTracer client"), MB_OK ); else ::MessageBox( NULL, er.ErrorMessage(), _T("SASTracer client"), MB_OK ); return 1;}
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 15
Teledyne LeCroy SASAnalyzer Object
ISASAnalyzer::StopRecordingHRESULT StopRecording (
[in] BOOL abort_upload );
Stops recording started by the ISASAnalyzer::StartRecording method.
Parameters
abort_upload TRUE If the caller wants to abort the upload. No trace file is created.
FALSEIf the caller wants to upload the recorded trace.
Return Values
ANALYZERCOMERROR_UNABLESTOPRECORDING Error stopping recording
Remarks
Stops recording started by the StartRecording method. The event is issued when recording is actually stopped (by the ISASAnalyzer Interface), if the parameter of method call was FALSE.
16 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASAnalyzer Object Teledyne LeCroy
Example (for SAS/SATA Protocol Suite application)
VBScript:
<OBJECT RUNAT=ServerID = Analyzer CLASSID = "clsid: 0B179BB7-DC61-11d4-9B71-000102566088"></OBJECT>
<SCRIPT LANGUAGE="VBScript"><!--Sub BtnStopRecording_OnClickOn Error Resume NextAnalyzer.StopRecording TrueIf Err.Number <> 0 ThenMsgBox Err.Number & ":" & Err.DescriptionEnd If End Sub--></SCRIPT>
C++:ISASAnalyzer* sas_analyzer;
. . .
try{sas_analyzer->StopRecording( FALSE )}catch (_com_error& er){ if (er.Description().length() > 0) ::MessageBox( NULL, er.Description(), _T("SASTracer client"), MB_OK ); else ::MessageBox( NULL, er.ErrorMessage(), _T("SASTracer client"), MB_OK ); return 1;}
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 17
Teledyne LeCroy SASAnalyzer Object
ISASAnalyzer::MakeRecordingHRESULT MakeRecording (
[in] BSTR ro_file_name, [out, retval] IDispatch** trace );
Makes recording with the specified recording options file.
Parameters
ro_file_name String providing the full pathname to a recording options file.
trace Address of a pointer to the SASTrace object interface
Return Values
ANALYZERCOMERROR_UNABLESTARTRECORDING Unable to start recording
Remarks
This method acts like the StartRecording method but will not return until recording is completed. The SASTrace object is created via this method call, if the call was successful.
The recording options file is the file with extension .sac created by the SAS/SATA Protocol Suite application. You can create this file when you select File –> Protocol Analyzer… from the SAS Protocol Suite application menu, change the recording options in the Protocol Analyzer project, and select the Save… button.
Example
WSH:
CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\"))Set Analyzer = WScript.CreateObject("Lecroy.SASAnalyzer")Set Trace = Analyzer.MakeRecording (CurrentDir & "Input\test_ro.sac")C++:IDispatch* trace;ISASAnalyzer* sas_analyzer;BSTR ro_file_name;HRESULT hr;. . .
18 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASAnalyzer Object Teledyne LeCroy
try{trace = sas_analyzer->MakeRecording( ro_file_name )}catch (_com_error& er){ if (er.Description().length() > 0) ::MessageBox( NULL, er.Description(), _T("SASTracer client"), MB_OK ); else ::MessageBox( NULL, er.ErrorMessage(), _T("SASTracer client"), MB_OK ); return 1;}// Query for VTBL interfaceISASTrace* sas_trace; hr = trace->QueryInterface( IID_ISASTrace, (LPVOID *)&sas_trace );trace->Release();
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 19
Teledyne LeCroy SASAnalyzer Object
ISASAnalyzer::IsRunningHRESULT IsRunning (
[in] int nFunctionality,[out, retval] BOOL* pbIsRunning)
This function returns the running status of projects.
Parameters
nFunctionality This parameter specifies the functionality of the project that you want to check its running status. You should set this parameter as below:
0 : to check all available functionalities status at once
1 : to check Analyzer running status
2 : to check Infusion running status
3 : to check Sierra/STX running status
4 : to check whether Target/Device emulator is active or not
5 : to check Initiator emulator running status
Return Value
pbIsRunning This parameter returns the running status
Remarks
By calling this function, you will be able to check whether the Analyzer, Infusion, Sierra/STX, Target/Device Emulator and Initiator Emulator are running or not. If you want to check all these functionalities at once, you have to set the first parameter (nFunctionality) to zero.
Example
VBScript:
Dim bIsRunning Dim TimerDim TimeOut
Timer = 0bIsRunning = TRUE
'Set waiting time out to 60 SecondsTimeOut= 60 'seconds
'Wait for project to stop or timeout happenWhile bIsRunning <> FALSE And Timer < TimeOut
20 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASAnalyzer Object Teledyne LeCroy
'bIsRunning = Analyzer.IsRunning(0)'Checks all bIsRunning = Analyzer.IsRunning(1)'checks Analyzer 'bIsRunning = Analyzer.IsRunning(2)'Checks Infusion'bIsRunning = Analyzer.IsRunning(3)'Checks Trainer'bIsRunning = Analyzer.IsRunning(4)'Checks Target'bIsRunning = Analyzer.IsRunning(5)'checks Initiator
WScript.Sleep(1000)'Sleep 1 SecondTimer = Timer + 1
MySTATS.ReportText ("Project is running, Time = " & CSTR(Timer) & "second(s)")Wend
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 21
Teledyne LeCroy SASAnalyzer Object
ISASAnalyzer::LoadDisplayOptionsHRESULT LoadDisplayOptions (
[in] BSTR do_file_name[in] short do_layers );
Loads display options that will apply to a trace opened or recorded later.
Parameters
do_file_name String providing the full pathname to display options file
do_layers Specifies the mask layer of packet view, which can be a combination of these values:
LAYER_LINK (0x0001) //00000000 00000001
LAYER_IDLE (0x0002) //00000000 00000010
LAYER_TRANSPORT (0x0004) //00000000 00000100
LAYER_ATA_COMMAND (0x0008) //00000000 00001000
LAYER_SCSI_COMMAND (0x0010) //00000000 00010000
LAYER_SMP_COMMAND (0x0020) //00000000 00100000
LAYER_TASK_COMMAND (0x0040) //00000000 01000000
LAYER_DATA_REPORT (0x0080) //00000000 10000000
LAYER_QUEUE_COMMAND (0x0100) //00000001 00000000
LAYER_OOB_SEQUENCE (0x0200) //00000010 00000000
Return Values
ANALYZERCOMERROR_UNABLELOADDO Unable to load the display options file
Remarks
Use this method to filter traffic of some type. The display options loaded by this method call apply only on trace files opened or recorded after this call.
The display options file is the file with extension .sfl created by the SAS/SATA Protocol Suite application by the filter dialog.
Example
See ITrace::ApplyDisplayOptions.
22 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASAnalyzer Object Teledyne LeCroy
ISASAnalyzer::LoadGlobalGenOptions HRESULT LoadGlobalGenOptions (
[in] BSTR bstrGenOptionsFile,[out, retval] BOOL* pbRetval)
This function loads the global generator options.
Parameters
bstrGenOptionsFile String providing the full pathname to a generator options file;
Return Value
pbRetval This function returns a BOOL value. This value shows whether the load is done successfully or not.
Remarks
If any SAS/SATA Protocol Suite file has its own generator options, calling this function will not change its options otherwise, it will load the specified options file and will set it as its generator options.
Example
VBScript:
On Error Resume NextAnalyzer.LoadGlobalGenOptions("E:\MyGenOptions.gen")If Err.Number <> 0 ThenMsgBox Err.Number & ":" & Err.DescriptionEnd If
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 23
Teledyne LeCroy SASAnalyzer Object
ISASAnalyzer::GetRecordingOptionsHRESULT GetRecordingOptions (
[out, retval] IDispatch** recording_options );
Retrieves the interface for access to the recording options.
Parameters
recording_options Address of a pointer to the SASRecOptions Object interface
Return Values
Remarks
The SASRecOptions object is created via this method call, if the call was successful.
Example
WSH:Set Analyzer = WScript.CreateObject("Lecroy.SASAnalyzer")Set RecOptions = Analyzer.GetRecordingOptions
C++:HRESULT hr;ISASAnalyzer* poSASAnalyzer;// Create SASAnalyzer object.if ( FAILED( CoCreateInstance( CLSID_SASAnalyzer, NULL, CLSCTX_SERVER, IID_ISASAnalyzer, (LPVOID *)&poSASAnalyzer ) )return;
// Open trace file.IDispatch* rec_opt;try{rec_opt = poSASAnalyzer->GetRecordingOptions();}catch (_com_error& er){ if (er.Description().length() > 0) ::MessageBox( NULL, er.Description(), _T("SASTracer client"), MB_OK ); else ::MessageBox( NULL, er.ErrorMessage(), _T("SASTracer client"), MB_OK ); return 1;}
24 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASAnalyzer Object Teledyne LeCroy
// Query for VTBL interfaceISASRecOptions* ib_rec_opt;hr = rec_opt->QueryInterface(IID_ISASRecOptions, (LPVOID *)&ib_rec_opt);rec_opt->Release();if( FAILED(hr) )return;
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 25
Teledyne LeCroy SASAnalyzer Object
ISASAnalyzer::ResumeGenerationHRESULT ResumeGeneration ( )
Resumes generation if it was previously paused.
Return Value
Remarks
Example
C++:ISASAnalyzer* poAnalyzer;
. . .
try{ poAnalyzer->ResumeGeneration();} catch (_com_error& er) { if (er.Description().length() > 0) ::MessageBox(NULL, er.Description(), _T("SASTracer client"), MB_OK); else ::MessageBox(NULL, er.ErrorMessage(), _T("SASTracer client"), MB_OK); return 1;}
26 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASAnalyzer Object Teledyne LeCroy
ISASAnalyzer::ActivateDeviceHRESULT ActivateDevice ( [in] BSTR bstrFileName)
This function activates the target/device emulator.
Parameters
bstrFileName Specifies the path of the target/device emulator project file.
Remarks
Activates the specified project. If device is already activated, an error will be returned. Note that the port configuration will be set by the SetPortConfiguration function.
If no port configuration is set, the default value is the running configuration.
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 27
Teledyne LeCroy SASAnalyzer Object
ISASAnalyzer::ActivateDeviceByBoardHRESULT ActivateDeviceByBoard ( [in] BSTR bstrFileName, [in] nBoardIndex)
This function activates the target/device emulator.
Parameters
bstrFileNameBoardIndex (zero base)
Remarks
This activates the target/device emulator on the given board index using the give target/device project. If the device is already activated on the given board, an error will be returned.
Notes
1. You should set the port configuration by the SetPortConfiguration function before calling ActivateDeviceByBoard.
If no port configuration is set, the default value is the running configuration.
2. This function is applicable when you want to activate the target/device emulator when you cascade Seirra (or STX) boards. When using only one Sierra (or STX) board, you can call the ActivateDevice function.
28 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASAnalyzer Object Teledyne LeCroy
ISASAnalyzer::DeactivateDeviceHRESULT DeactivateDevice ()
This function deactivates the already activated target/device emulator.
Remarks
Deactivates the specified project. If device is not already activated, no action will be done, and nothing will be affected.
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 29
Teledyne LeCroy SASAnalyzer Object
ISASAnalyzer::SetScenarioToPortHRESULT SetScenarioToPort (
[in] int nBoardIndex[in]int nPortIndex,[in] BSTR bstrLibraryName,[in] BSTR bstrScenarioName,[out, retval] int* pnErrorCode);
This function assigns a scenario from mentioned library to a specific port of the board.
Parameters
nBoardIndex Zero based index of board. If you have only one board, this parameter should be set to zero.
nPortIndex Port index that the scenario should assign
bstrLibraryName Specifies the name of the library
bstrScenarioName Name of the scenario that will assigned to the specified port.
pnErrorCode Pointer to an integer which contains an error code if one or more error(s) has occurred.
Return Values
ANALYZERCOMERROR_UNABLE_TO_START_JAMMER Software is in simulation mode
ANALYZERCOMERROR_UNABLESTARTRECORDING
Failed to get LeCroy Scenario Manager
Failed to open LeCroy script local file database
Failed to get LeCroy Configure Manager
Failed to create LeCroy script local file database
Failed to load local file scenario
Failed to load local file scenario because invalid scenario
There is no scenario in local file.
Failed to upload the scenario to InFusion device
Failed to upload the scenario to InFusion device
Failed to upload the scenario to InFusion device
Failed to set selected the scenario from InFusion device
Can not find scenario in local file database
Remarks
Before a scenario is started, you must assign it to the available ports using this function.
30 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASAnalyzer Object Teledyne LeCroy
Example
C++:
HRESULT hr;IFCAnalyzer* poFCAnalyzer;
// Create FCAnalyzer object.if ( FAILED( CoCreateInstance( CLSID_FCAnalyzer, NULL, CLSCTX_SERVER, IID_IFCAnalyzer, (LPVOID *)&poFCAnalyzer ) )return;
// Open trace file.IDispatch* rec_opt;
try{poFCAnalyzer-> SetScenarioToPort(m_yUnitIndex, m_yPortIndex, m_strLibPath.AllocSysString(), m_strScenarioName.AllocSysString()); }catch (_com_error& er){ if (er.Description().length() > 0) ::MessageBox( NULL, er.Description(), _T("FCSuite client"), MB_OK ); else ::MessageBox( NULL, er.ErrorMessage(), _T("FCSuite client"), MB_OK ); return 1;}
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 31
Teledyne LeCroy SASAnalyzer Object
ISASAnalyzer:: StartScenarioHRESULT StartScenario (
[in] int nBoardIndex[in]int nPortIndex);
This function runs the assigned scenario of the port.
Parameters
nBoardIndex Zero based index of board. If you have only one board, this parameter should be set to zero.
nPortIndex Port index where the scenario should start.
Return Values
ANALYZERCOMERROR_UNABLE_TO_START_JAMMER
Software is in simulation mode
Device does not have sufficient license to run InFusion
Failed to start the Jammer session
Remarks
Starts scenarios on ports. You must call this function for every port of any board on which you want to run scenarios. The port configuration is set by the SetPortConfiguration function.
32 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASAnalyzer Object Teledyne LeCroy
Example
C++:HRESULT hr;IFCAnalyzer* poFCAnalyzer;
// Create FCAnalyzer object.if ( FAILED( CoCreateInstance( CLSID_FCAnalyzer, NULL, CLSCTX_SERVER, IID_IFCAnalyzer, (LPVOID *)&poFCAnalyzer ) )return;
// Open trace file.IDispatch* rec_opt;
try{poFCAnalyzer->StartScenario(m_yUnitIndex, m_yPortIndex); }catch (_com_error& er){ if (er.Description().length() > 0) ::MessageBox( NULL, er.Description(), _T("FCSuite client"), MB_OK ); else ::MessageBox( NULL, er.ErrorMessage(), _T("FCSuite client"), MB_OK ); return 1;}
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 33
Teledyne LeCroy SASAnalyzer Object
ISASAnalyzer:: StopScenarioHRESULT StopScenario (
[in] int nBoardIndex[in]int nPortIndex);
This function stops the scenario of the specified port.
Parameters
nBoardIndex Zero based index of board. If you have only one board, this parameter should be set to zero.
nPortIndex Port index where scenario should start.
Return Values
ANALYZERCOMERROR_UNABLE_TO_STOP_JAMMER
Software is in simulation modeFailed to stop the Jammer session
Remarks
Stops scenarios. You must call this function for every port of any board on which you want to stop scenarios.
Example
C++:
HRESULT hr;IFCAnalyzer* poFCAnalyzer;
// Create FCAnalyzer object.if ( FAILED( CoCreateInstance( CLSID_FCAnalyzer, NULL, CLSCTX_SERVER, IID_IFCAnalyzer, (LPVOID *)&poFCAnalyzer ) )return;
34 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASAnalyzer Object Teledyne LeCroy
// Open trace file.IDispatch* rec_opt;try{poFCAnalyzer->StopScenario(m_yUnitIndex, m_yPortIndex); }catch (_com_error& er){ if (er.Description().length() > 0) ::MessageBox( NULL, er.Description(), _T("FCSuite client"), MB_OK ); else ::MessageBox( NULL, er.ErrorMessage(), _T("FCSuite client"), MB_OK ); return 1;}
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 35
Teledyne LeCroy SASAnalyzer Object
ISASAnalyzer:: SetPortConfigurationHRESULT SetPortConfiguration (
[in] int nBoardIndex[in]int nPortConfiguration);
This function specifies port configuration by board index.
Parameters
nBoardIndex Zero based index of board. If you have only one board, this parameter should be set to zero.
nPortConfiguration DeviceConfigurationTypeEnum enumeration specifies functionality of ports for connected board:
DeviceConfigurationTypeEnum enumeration:
//‐‐‐‐‐‐‐‐‐Sierra M6‐4‐‐‐‐‐‐‐‐‐‐‐‐‐
DEVICE_CONFIG_A_A_A_A = 1,
DEVICE_CONFIG_T_T_T_T = 2,
DEVICE_CONFIG_HE_HE_HE_HE = 3,
DEVICE_CONFIG_DE_DE_DE_DE = 4,
DEVICE_CONFIG_A_A_HE_HE = 5,
DEVICE_CONFIG_A_A_DE_DE = 6,
DEVICE_CONFIG_HE_HE_A_A = 7,
DEVICE_CONFIG_DE_DE_A_A = 8,
DEVICE_CONFIG_AHE_AHE_0_0 = 9,
DEVICE_CONFIG_ADE_ADE_0_0 = 10,
DEVICE_CONFIG_J_0_A_A = 11,
DEVICE_CONFIG_0_J_A_A = 12,
DEVICE_CONFIG_AHE_0_AHE_0 = 13,
DEVICE_CONFIG_ADE_0_ADE_0 = 14,
DEVICE_CONFIG_AHE_0_0_0 = 15,
DEVICE_CONFIG_ADE_0_0_0 = 16,
DEVICE_CONFIG_AHE_0_A_A = 17,
DEVICE_CONFIG_ADE_0_A_A = 18,
DEVICE_CONFIG_A_0_0_0 = 19,
DEVICE_CONFIG_A_A_0_0 = 20,
DEVICE_CONFIG_0_0_HE_HE = 21,
DEVICE_CONFIG_HE_HE_0_0 = 22,
DEVICE_CONFIG_0_0_DE_DE = 23,
36 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASAnalyzer Object Teledyne LeCroy
DEVICE_CONFIG_DE_DE_0_0 = 24,
DEVICE_CONFIG_0_0_AJA_0 = 25,
DEVICE_CONFIG_0_0_0_AJA = 26,
DEVICE_CONFIG_0_0_JA_0 = 27,
DEVICE_CONFIG_0_0_0_JA = 28,
DEVICE_CONFIG_J_0_HE_HE = 29,
DEVICE_CONFIG_0_J_HE_HE = 30,
DEVICE_CONFIG_HE_HE_J_0 = 31,
DEVICE_CONFIG_HE_HE_0_J = 32,
DEVICE_CONFIG_J_0_AHE_0 = 33,
DEVICE_CONFIG_J_0_DE_DE = 34,
DEVICE_CONFIG_0_J_DE_DE = 35,
DEVICE_CONFIG_DE_DE_J_0 = 36,
DEVICE_CONFIG_DE_DE_0_J = 37,
DEVICE_CONFIG_J_0_ADE_0 = 38,
DEVICE_CONFIG_AHE_0_J_0 = 39,
DEVICE_CONFIG_ADE_0_J_0 = 40,
DEVICE_CONFIG_HE_0_0_0 = 41,
DEVICE_CONFIG_DE_0_0_0 = 42,
DEVICE_CONFIG_HE_0_J_0 = 43,
DEVICE_CONFIG_DE_0_J_0 = 44,
DEVICE_CONFIG_J_J_A_A = 45,
DEVICE_CONFIG_AJA_0_0_0 = 46,
DEVICE_CONFIG_0_AJA_0_0 = 47,
DEVICE_CONFIG_JA_0_0_0 = 48,
DEVICE_CONFIG_0_JA_0_0 = 49,
DEVICE_CONFIG_A_A_J_0 = 50,
DEVICE_CONFIG_A_A_0_J = 51,
DEVICE_CONFIG_J_J_J_J = 52,
DEVICE_CONFIG_A_A_J_J = 53,
DEVICE_CONFIG_JA_JA_0_0 = 54,
DEVICE_CONFIG_0_0_JA_JA = 55,
DEVICE_CONFIG_J_J_HE_HE = 56,
DEVICE_CONFIG_HE_HE_J_J = 57,
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 37
Teledyne LeCroy SASAnalyzer Object
DEVICE_CONFIG_J_J_DE_DE = 58,
DEVICE_CONFIG_DE_DE_J_J = 59,
DEVICE_CONFIG_AHE_0_J_J = 60,
DEVICE_CONFIG_J_J_AHE_0 = 61,
DEVICE_CONFIG_ADE_0_J_J = 62,
DEVICE_CONFIG_J_J_ADE_0 = 63,
DEVICE_CONFIG_J_0_0_0 = 64,
DEVICE_CONFIG_0_J_0_0 = 65,
DEVICE_CONFIG_0_0_J_0 = 66,
DEVICE_CONFIG_0_0_0_J = 67,
DEVICE_CONFIG_J_J_0_0 = 68,
DEVICE_CONFIG_0_0_J_J = 69,
DEVICE_CONFIG_T_0_T_0 = 70,
DEVICE_CONFIG_0_T_0_T = 71,
DEVICE_CONFIG_AT_0_0_0 = 72,
DEVICE_CONFIG_0_AT_0_0 = 73,
DEVICE_CONFIG_0_0_AT_0 = 74,
DEVICE_CONFIG_0_0_0_AT = 75,
DEVICE_CONFIG_T_0_A_A = 76,
DEVICE_CONFIG_0_T_A_A = 77,
DEVICE_CONFIG_A_A_T_0 = 78,
DEVICE_CONFIG_A_A_0_T = 79,
DEVICE_CONFIG_TJ_0_0_0 = 80,
DEVICE_CONFIG_0_TJ_0_0 = 81,
DEVICE_CONFIG_0_0_TJ_0 = 82,
DEVICE_CONFIG_0_0_0_TJ = 83,
DEVICE_CONFIG_0_0_AHE_AHE = 84,
DEVICE_CONFIG_PA_PA_PA_PA = 85,
DEVICE_CONFIG_T_T_A_A = 86,
DEVICE_CONFIG_A_A_T_T = 87,
DEVICE_CONFIG_AT_AT_0_0 = 88,
DEVICE_CONFIG_0_0_AT_AT = 89,
DEVICE_CONFIG_AHJ_0_0_0 = 90, // Host Side Jammer (M6‐2 only)
38 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASAnalyzer Object Teledyne LeCroy
DEVICE_CONFIG_0_AHJ_0_0 = 91,
DEVICE_CONFIG_ADJ_0_0_0 = 92, // Device Side Jammer (M6‐2 only)
DEVICE_CONFIG_0_ADJ_0_0 = 93,
DEVICE_CONFIG_TPA_0_0_0 = 94,
DEVICE_CONFIG_0_TPA_0_0 = 95,
DEVICE_CONFIG_0_0_TPA_0 = 96,
DEVICE_CONFIG_0_0_0_TPA = 97,
DEVICE_CONFIG_TPA_TPA_0_0 = 98,
DEVICE_CONFIG_0_0_TPA_TPA = 99,
DEVICE_CONFIG_AHE_0_ADE_0 = 100,
DEVICE_CONFIG_ADE_0_AHE_0 = 101,
DEVICE_CONFIG_DE_DE_HE_HE = 102,
DEVICE_CONFIG_HE_HE_DE_DE = 103,
DEVICE_CONFIG_HE_DE_HE_DE = 104,
DEVICE_CONFIG_HE_DE_0_0 = 105,
DEVICE_CONFIG_HE_DE_A_A = 106,
DEVICE_CONFIG_0_0_0_0 = 107,
DEVICE_CONFIG_AT_0_AT_0 = 108, // M124A
DEVICE_CONFIG_T_0_JA_0 = 109, // M6‐4
DEVICE_CONFIG_AJA_0_AJA_0 = 110, // M124A
DEVICE_CONFIG_0_AHE_0_0 = 111, // M6‐2
DEVICE_CONFIG_0_AJA_0_AJA = 112, // M124A
DEVICE_CONFIG_0_AT_0_AT = 113, // M124A
// If you want to add a Type , Add before DEVICE_CONFIG_0_0_0_0.
A : Analyzer, J = Jammer, P= Passthrough, T = Trainer
HE : Initiator Emulator, DE : Device Emulator
0 = No Connection
Remarks
Before you run any function on your board, you must specify its port configuration before running Analyzer, Exerciser, Sierra/STX, or InFusion. Port configuration specifies what functionality should be considered for each port of the specified board.
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 39
Teledyne LeCroy SASAnalyzer Object
ISASAnalyzer:: LoadPreEmphasisSignalFileHRESULT LoadPreEmphasisSignalFile(
[in] BSTR bstrPreEmphasisSignalFile,[out, retval] pbRetval);
This function gets the file of pre emphasis signal and loads it to the board.
Parameters
bstrPreEmphasisSignalFile Specifies the file name of pre emphasis signal.
Return Values
True if it loads the file successfully. False if it fails.
Remarks
The Pre emphasis dialog in the SAS/SATA software gives the probability of saving the signal settings into a file. By calling this function, you can load that file into the board without running the SAS/SATA software.
ISASAnalyzer::SetTracefileNameHRESULT SetTracefileName ([in] BSTR bstrTraceFileName)
This function sets the name of next running generated trace file.
Parameters
bstrTraceFileName String providing the name of the trace file
Remarks
Calling this function sets the next running generated trace file name. If you do not call this function, then the trace file name will be the same as the Analyzer project file name.
This function helps you create different trace files when you want to run a project several times with different settings (such as connection speed). Before any run, call this function to change the trace file name.
Note:This is used to change the trace‐file‐name, (if user wants to). In case it is not set, the trace‐file‐name would be the same as the analyzer‐project‐file‐name. Use/Example: In case the user wants to capture different trace(s) using the same Analyzer object (say running more than one generation‐script in a loop ). In this case he/she can set the different names using this API in each iterations (otherwise they will be overwritten with the same filename).
Example
VBScript:
Analyzer.SetTracefileName("MyTrace")If Err.Number <> 0 ThenMsgBox Err.Number & ":" & Err.DescriptionEnd If
40 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASAnalyzer Object Teledyne LeCroy
ISASAnalyzer::DoSelfTestHRESULT DoSelfTest (
[in] int SelfTestType,[out, retval] int* pnResult)
This function is used to run the self test on the currently connected board and report its faults and defects.
Parameters
SelfTestType : This parameter specifies the type of the self test. This type can be one of these numbers:
1 : SELF_TEST_MEMORY
2 : SELF_TEST_CLOCK
3 : SELF_TEST_BUZZER_LED
4 : SELF_TEST_VIRTEX_VIRTEX_BUS_TEST
5 : SELF_TEST_MARVELL
6 :SELF_TEST_VITESSE_VIRTESSE_BUS_TEST
7 : SELF_TEST_VITESSE_EXTERNAL_LOOP_BACK
8 : SELF_TEST_VITESSE_EXPANTION_CARD
0 value for SelfTestType means doing the following tests:
SELF_TEST_MEMORY
SELF_TEST_CLOCK
SELF_TEST_VIRTEX_VIRTEX_BUS_TEST
SELF_TEST_MARVELL
SELF_TEST_VITESSE_VIRTESSE_BUS_TEST
SELF_TEST_VITESSE_EXTERNAL_LOOP_BACK
SELF_TEST_VITESSE_EXPANTION_CARD
Return Value
pnResult A zero value for this parameter shows that the self test has passed and a non‐zero value shows that the self test failed. When the self test fails it means that an error or problem has been detected. To get more information on the detected problem you can view the Self Test Log file. It is in the User folder of the software.
Remarks
Doing a self test on SELF_TEST_BUZZER_LED and SELF_TEST_VITESSE_EXPANTION_CARD needs user interaction during test..
Example
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 41
Teledyne LeCroy SASAnalyzer Object
ISASAnalyzer ::SetVSELogToSaveAutomaticallyHRESULT SetVSELogToSaveAutomatically (
[in] BOOL bSaveAutomatically,[out,retval] BOOL *pResult);
This function sets the flag for automatically saving, or not saving, VSE log files.
Parameters
bSaveAutomatically TRUE = Saves the log file automatically after a VSE script run.FALSE = Does not save the log file after a VSE script run.
Return Values
pResult TRUE = Flag set successfully.FALSE = Could not set the flag.
Remarks
Default value is retrieved from the VSE settings. Note that, after installation, the VSE settings have no value for the flag. To have a default value, you must enter the value manually in the VSE settings.
Before using this command to automatically save log files, you must make sure that the VSE settings have the path to the folder in which to save log files. Note that, after installation, the VSE settings have no value for the path. To set the path, you can enter the value manually in the VSE settings. Alternatively, before calling this function, you can run the SetVSELogModeToMultipleFile command to set the folder path.
If the SetVSELogToSaveAutomatically function parameter is set to FALSE, the system does not save any log files, regardless of any other method settings.
Example
VBScript:
Analyzer.SetVSELogToSaveAutomatically(1)Analyzer.SetVSELogToSaveAutomatically(0)
42 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASAnalyzer Object Teledyne LeCroy
ISASAnalyzer ::SetVSELogModeToMultipleFileHRESULT SetVSELogModeToMultipleFile (
[in] BSTR bstrLogFolderPath, [out,retval] BOOL *pResult);
This function sets the folder path for saving log files from VSE script runs.
Parameters
bstrLogFolderPath String providing the folder path for the saved log file
Return Values
pResult TRUE = Folder path set successfully.FALSE = Could not set the folder path.
Remarks
Default value is retrieved from the VSE settings. Note that, after installation, the VSE settings have no value for the path. To have a default value, you must enter the value manually in the VSE settings.
If a value is set in the ATS script before this method is called, the method will override that setting. The folder path must exist. If the folder path does not exist, the method returns FALSE and shows the error in the ATS output.
Note: This function saves all log files into the directory specified by the function parameter.
Example
VBScript:
Analyzer.SetVSELogModeToMultipleFile("D:\AvailableFolderPath\")
If Err.Number <> 0 ThenMsgBox Err.Number & ":" & Err.DescriptionEnd If
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 43
Teledyne LeCroy SASAnalyzer Object
ISASAnalyzer ::SetVSELogModeToSingleFileHRESULT SetVSELogModeToSingleFile (
[in] BSTR bstrLogFilePath, [out,retval] BOOL *pResult);
This function set mode to save all logs for VSE scripts in single file and set the file log path.
Parameters
bstrLogFolderPath String providing the folder path for the save log file
Return Values
pResult TRUE = file path set successfully.FALSE = could not set the file path.
Remarks
Default value is retrieve from VSE setting. It will over ride any other log setting if there is any on the ATS script before this method. The folder path must exist, and the file name should be valid otherwise the method return false and show the error in the ATS output.
Example
VBScript:
Analyzer.SetVSELogModeToSingleFile("D:\VSELogFileName.log")
If Err.Number <> 0 ThenMsgBox Err.Number & ":" & Err.DescriptionEnd If
44 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASAnalyzer Object Teledyne LeCroy
ISASAnalyzer ::SetVSELogModeToTraceRelativePathHRESULT SetVSELogModeToTraceRelativePath ([out,retval] BOOL *pResult);
This function set mode to save all logs for VSE scripts in separate files and set the folder path to the corresponding Trace file Path.
Return Values
pResult TRUE = set successfully.FALSE = could not set path.
Remarks
Default value is retrieve from VSE setting. It will over ride any other log setting if there is any on the ATS script before this method.
Example
VBScript:
Analyzer.SetVSELogModeToTraceRelativePath()
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 45
Teledyne LeCroy SASAnalyzer Object
ISASAnalyzer:: SetDecodingAssignmentHRESULT SetDecodingAssignment (
[in] ESpecType eSpecType,[in] ESCSISpec eSCSISpec,[out, retval] BOOL* pbRetval);
This function assigns a default spec for the ATAPI and SCSI decoding.
Parameters
eSpecType Specifies the Spec Type to which the assignment has to be apply. ESpecType has the following values
ESpecType_SCSI ( 0 )ESpecType_ATAPI ( 1 )
eSCSISpec Specifies the spec Id that has to be assigned with. ESCSISpec has the following values
ESCSISpec_MMC ( 0 )ESCSISpec_SBC ( 1 )ESCSISpec_SMC ( 2 )ESCSISpec_SPC ( 3 )ESCSISpec_SSC ( 4 )ESCSISpec_SCC ( 5 )ESCSISpec_OSD ( 6 )ESCSISpec_ADC ( 7 )
Return Value
pbRetval This function returns a BOOL value. This value shows whether the assignments has been done successfully or not.
Remarks
For the eSpecType “ESpecType_ATAPI”, the only allowed ESCSISpec values are “ESCSISpec_MMC” and “ESCSISpec_SSC”
This interface sets the default specs of the application. Hence, one must revert/set the old spec to the application, so that the standalone application doesn’t get affected later.
Spec assignment would be applied for a newly captured trace. Hence, you may apply it before StartRecording else it will be applied for the next run.
46 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SierraSASAnalyzer Object Teledyne LeCroy
SierraSASAnalyzer Object
The SierraSASAnalyzer object is the Sierra version for SAS of the SASAnalyzer object. All functionality is the same as the SASAnalyzer object. Using this object is similar to using the SAS Project in the GUI, and will result in SAS specific details, such as *.scs trace extension and I/T port terminology.
The Class ID and App ID for the SierraSASAnalyzer object are the following:
Class ID: SierraSASAnalyzer 8EBF31F8‐8861‐435c‐8305‐51EAFD4F5BCE
AppID: SierraSASAnalyzer Lecroy.SierraSASAnalyzer
Example
WSH:Set Analyzer = WScript.CreateObject( “Lecroy.SierraSASAnalyzer” )
C++:ISierraSASAnalyzer* poSierraSASAnalyzer;
// create SierraSASAnalyzer objectif ( FAILED( CoCreateInstance(CLSID_SierraSASAnalyzer,NULL, CLSCTX_SERVER,IID_ISeirraSASAnalyzer,(LPVOID *)&poSierraSASAnalyzer ) )
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 47
Teledyne LeCroy SierraSTAnalyzer Object
SierraSTAnalyzer Object
The SierraSTAnalyzer object is the Sierra version for SATA of the SASAnalyzer object. All functionality is the same as the SASAnalyzer object. Using this object is similar to using the SATA Project in the GUI, and will result in SATA specific details, such as *.sts trace extension and H/D port terminology.
The Class ID and App ID for the SierraSTAnalyzer object are the following:
Class ID: SierraSTAnalyzer AF294105‐9BA9‐4a90‐943D‐8162E29635FF
AppID: SierraSTAnalyzer Lecroy.SierraSTAnalyzer
Example
WSH:Set Analyzer = WScript.CreateObject( “Lecroy.SierraSTAnalyzer” )
C++:ISierraSTAnalyzer* poSierraSTAnalyzer;
// create SierraSTAnalyzer objectif ( FAILED( CoCreateInstance(CLSID_SierraSTAnalyzer,NULL, CLSCTX_SERVER,IID_ISeirraSTAnalyzer,(LPVOID *)&poSierraSTAnalyzer ) )
48 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
STXSASAnalyzer Object Teledyne LeCroy
STXSASAnalyzer Object
The STXSASAnalyzer object is the Sierra version of the SASAnalyzer object in the SAS software. This object is delivered by the STX SAS software automation API. All functionality is the same as the SASAnalyzer object.
The Class ID and App ID for the STXSASAnalyzer object are the following:
Class ID: STXSASAnalyzer 4E677701‐FD40‐4152‐8B11‐4406F87BB4FF
AppID: STXSASAnalyzer Lecroy.STXSASAnalyzer
Example
WSH:Set Analyzer = WScript.CreateObject( “Lecroy.STXSASAnalyzer” )
C++:ISTXSASAnalyzer* poSTXSASAnalyzer;
// create STXSASAnalyzer objectif ( FAILED( CoCreateInstance(CLSID_STXSASAnalyzer,NULL, CLSCTX_SERVER,IID_ISTXSASAnalyzer,(LPVOID *)&poSTXSASAnalyzer ) )
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 49
Teledyne LeCroy STXSTAnalyzer Object
50 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
STXSTAnalyzer Object
The STXSTAnalyzer object is the Sierra version of the SASAnalyzer object in the SATA software. This object is delivered by the STX SATA software automation API. All functionality is the same as the SASAnalyzer object.
The Class ID and App ID for the STXSTAnalyzer object are the following:
Class ID: STXSTAnalyzer 9A94D6AA‐9A86‐439d‐9FBB‐970FABA36888
AppID: STXSTAnalyzer Lecroy.STXSTAnalyzer
Example
WSH:Set Analyzer = WScript.CreateObject( “Lecroy.STXSTAnalyzer” )
C++:ISTXSTAnalyzer* poSTXSTAnalyzer;
// create STXSTAnalyzer objectif ( FAILED( CoCreateInstance(CLSID_STXSTAnalyzer,NULL, CLSCTX_SERVER,IID_ISTXTAnalyzer,(LPVOID *)&poSTXSTAnalyzer ) )
SASTrace Object Teledyne LeCroy
SASTrace Object
The SASTrace object represents the recorded trace file.
The SASTrace object allows users to:
Get trace information. Access trace packets. Access trace errors. Save/export the trace or a portion of the trace.
The SASTrace object can be created by:
Using the ISASAnalyzer::OpenFile method Using the ISASAnalyzer::MakeRecording method Handling the _ISASAnalyzerEvents::OnTraceCreated event
The SASTrace object supports the following interfaces:
The ISASTrace interface is a primary interface for the SASTrace object.
Interfaces Description
Itrace Implements trace packets and trace errors access, different report types, exporting, and saving.
ISASTrace Extends ITrace interface:
Adds functionality for accessing the SASTracePacket object.
ISASVerificationScript Exposes functionality for running verification scripts.
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 51
Teledyne LeCroy SASTrace Object
ITrace Interface
The ITrace interface is a dual interface for the SASTrace object.
It implements the following methods:
GetName ApplyDisplayOptions Save ExportToText Close ReportFileInfo ReportErrorSummary GetPacket GetPacketsCount GetTriggerPacketNum AnalyzerErrors
Note:All methods of the ITrace interface are also available in the ISASTrace Interface.
52 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASTrace Object Teledyne LeCroy
ITrace::GetNameHRESULT GetName (
[out, retval] BSTR* trace_name );
Retrieves the trace name.
Parameters
trace_name Name of the trace
Return Values
Remarks
This name can be used for presentation purposes.
Do not forget to free the string returned by this method call.
Example
WSH:Set Analyzer = WScript.CreateObject("Lecroy.SASAnalyzer ")CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\"))Set Trace = Analyzer.MakeRecording (CurrentDir & "Input\test_ro.sac")MsgBox “Trace name “ & Trace.GetName
C++:ISASTrace* sas_trace;
. . .
_bstr_t bstr_trace_name;
try {bstr_trace_name = sas_trace->GetName();}catch (_com_error& er){ if (er.Description().length() > 0) ::MessageBox( NULL, er.Description(), _T("SASTracer client"), MB_OK); else ::MessageBox( NULL, er.ErrorMessage(), _T("SASTracer client"), MB_OK); return 1;} TCHAR str_trace_name[256];
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 53
Teledyne LeCroy SASTrace Object
_tcscpy( str_trace_name, (TCHAR*)( bstr_trace_name) ); SysFreeString( bstr_trace_name );
::MessageBox( NULL, str_trace_name, _T("Trace name"), MB_OK );
54 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASTrace Object Teledyne LeCroy
ITrace::ApplyDisplayOptionsHRESULT ApplyDisplayOptions (
[in] BSTR do_file_name );
Applies the specified display options to the trace.
Parameters
do_file_name String providing the full pathname to the display options file
Return values
ANALYZERCOMERROR_UNABLELOADDO Unable to load the display options file
Remarks
Use this method to filter traffic of some type in the recorded or opened trace.
The display options file is the file with extension .sfl created by the filter dialog.
Note:This does not work on Multisegment traces.
Example
WSH:Set Analyzer = WScript.CreateObject("LeCroy.SASAnalyzer")CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\"))Set Trace = Analyzer.MakeRecording (CurrentDir & "Input\test_ro.sac ")Trace.ApplyDisplayOptions CurrentDir & "Input\test_do.slf"Trace.Save CurrentDir & "Output\saved_file.scs"
C++:
ISASTrace* sas_trace;TCHAR file_name[_MAX_PATH];
. . .
try {sas_trace->ApplyDisplayOptions( file_name );}
catch (_com_error& er){ if (er.Description().length() > 0)
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 55
Teledyne LeCroy SASTrace Object
::MessageBox( NULL, er.Description(), _T("SASTracer client"), MB_OK ); else ::MessageBox( NULL, er.ErrorMessage(), _T("SASTracer client"), MB_OK ); return 1;}
56 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASTrace Object Teledyne LeCroy
ITrace::SaveHRESULT 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
file_name String providing the full pathname to the file where the trace is saved
packet_from Beginning packet number when you are saving a range of packets,.
–1 = first packet of the saved trace is the first packet of this trace.
packet_to Ending packet number when you are saving a range of packets.
–1 = last packet of the saved trace is the last packet of this trace.
Return Values
ANALYZERCOMERROR_UNABLESAVE Unable to save the trace file
ANALYZERCOMERROR_INVALIDPACKETNUMBER Bad packet range
Remarks
Use this method to save a recorded or opened trace into a file. If the display
options apply to this trace (see ITrace::ApplyDisplayOptions or
ISASAnalyzer::LoadDisplayOptions, 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:Set Analyzer = WScript.CreateObject("LeCroy.SASAnalyzer")CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\"))Set Trace = Analyzer.MakeRecording (CurrentDir & "Input\test_ro.sac")Trace.ApplyDisplayOptions CurrentDir & "Input\test_do.slf"Trace.Save CurrentDir & "Output\saved_file.scs"
C++:
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 57
Teledyne LeCroy SASTrace Object
ISASTrace* sas_trace;TCHAR file_name[_MAX_PATH];LONG packet_from;LONG packet_to;. . . try {sas_trace->Save( file_name, packet_from, packet_to );}catch (_com_error& er){ if (er.Description().length() > 0) ::MessageBox( NULL, er.Description(), _T("SASTRacer client"), MB_OK ); else ::MessageBox( NULL, er.ErrorMessage(), _T("SASTracer client"), MB_OK ); return 1;}
58 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASTrace Object Teledyne LeCroy
ITrace::GetPacketRowHRESULT GetPacketRow (
[in] long packet_number, [in] VIEW_TYPE view_type,[out] long* packet_row);
Changes packet number to row number.
Parameters
packet_number Integer for packet number
view_type VIEW_TYPE can be: COLUMN_VIEW (0), FRAME_TEXT_VIEW (1) [valid parameter for this method], PACKET_VIEW (2), WAVEFORM_VIEW (3), ST_REPORT_VIEW (4), SPREAD_SHEET_VIEW (5) [valid parameter for this method], HISTOGRAM_VIEW (6), BUS_UTILIZATION_VIEW (7).
packet_row Integer of packet row.
Remarks
Use this function before ExportToText and ExportToExcel to change packet numbers to row numbers.
Example
See ExportToText examples.
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 59
Teledyne LeCroy SASTrace Object
ITrace::ExportToTextHRESULT ExportToText (
[in] BSTR file_name, [in] VIEW_TYPE export_view_type,[in] long from_row, [in] long to_row);
Exports Spreadsheet View and Frame View into a text file, while allowing you to specify a range of packets.
Parameters
file_name String providing the full file pathname for the exported trace
export_view_type VIEW_TYPE can be: COLUMN_VIEW (0), FRAME_TEXT_VIEW (1) [valid parameter for this method], PACKET_VIEW (2), WAVEFORM_VIEW (3), ST_REPORT_VIEW (4), SPREAD_SHEET_VIEW (5) [valid parameter for this method], HISTOGRAM_VIEW (6), BUS_UTILIZATION_VIEW (7).
from_row Beginning packet number when you are exporting a range of packets. 0 = first packet of the exported trace is the first packet of this trace.
to_row Ending packet number when you are exporting a range of packets.–1 = last packet of the exported trace is the last packet of this trace.
Return Value
ANALYZERCOMERROR_UNABLESAVE Unable to export trace file
Remarks
Use this method if you want to export a recorded or opened trace into a text file. If the
display options apply to this trace (see ITrace::ApplyDisplayOptions or
ISASAnalyzer::LoadDisplayOptions), then hidden packets would not be exported.
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.
Here is a snippet of an exported text file:
File c:\analyzersw\traces\sas\allsata.sas.From Frame #1 to Frame #20. Frame# _______|_______________________________________________________________________T2Frame(1) 1.5(G) SATA RCV Time Stamp(29.196 501 432) _______|_______________________________________________________________________T2Frame(2) 1.5(G) SATA XMT SATA_SOF FIS Type(DMA Activate) Port(0x0) _______| Data(4 bytes) CRC(0x8FA86FC5) SATA_EOF Time Stamp(29.196 513 752) _______|_______________________________________________________________________I2Frame(3) 1.5(G) SATA RCV Time Stamp(29.196 514 177) _______|_______________________________________________________________________I2
60 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASTrace Object Teledyne LeCroy
Frame(4) 1.5(G) SATA XMT SATA_SOF FIS Type(Data) Port(0x0) _______| Data(8196 bytes) CRC(0x7BFAA709) SATA_EOF Time Stamp(29.196 518 682) _______|_______________________________________________________________________T2Frame(5) 1.5(G) SATA RCV Time Stamp(29.196 518 952) _______|_______________________________________________________________________T2Frame(6) 1.5(G) SATA XMT SATA_SOF FIS Type(DMA Activate) Port(0x0) _______| Data(4 bytes) CRC(0x8FA86FC5) SATA_EOF Time Stamp(29.196 632 872) _______|_______________________________________________________________________I2Frame(7) 1.5(G) SATA RCV Time Stamp(29.196 633 167)_______|_______________________________________________________________________I2Frame(8) 1.5(G) SATA XMT SATA_SOF FIS Type(Data) Port(0x0) _______| Data(8196 bytes) CRC(0x7919EFB6) SATA_EOF Time Stamp(29.196 634 687) _______|_______________________________________________________________________T2Frame(9) 1.5(G) SATA RCV Time Stamp(29.196 634 950)_______|_______________________________________________________________________T2Frame(10) 1.5(G) SATA XMT SATA_SOF FIS Type(DMA Activate) Port(0x0) _______| Data(4 bytes) CRC(0x8FA86FC5) SATA_EOF Time Stamp(29.196 748 927) _______|_______________________________________________________________________I2Frame(11) 1.5(G) SATA RCV Time Stamp(29.196 749 220) _______|_______________________________________________________________________I2Frame(12) 1.5(G) SATA XMT SATA_SOF FIS Type(Data) Port(0x0) _______| Data(8196 bytes) CRC(0x38CA16DA) SATA_EOF Time Stamp(29.196 750 740) _______|_______________________________________________________________________T2Frame(14) 1.5(G) SATA XMT SATA_SOF FIS Type(DMA Activate) Port(0x0) _______| Data(4 bytes) CRC(0x8FA86FC5) SATA_EOF Time Stamp(29.196 864 980) _______|_______________________________________________________________________I2Frame(15) 1.5(G) SATA RCV Time Stamp(29.196 865 272) _______|_______________________________________________________________________I2
Example
WSH:Set Analyzer = WScript.CreateObject("LeCroy.SASAnalyzer")CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\"))Set Trace = Analyzer.MakeRecording (CurrentDir & "Input\test_ro.sac")Trace.ApplyDisplayOptions CurrentDir & "Input\test_do.slf"Trace.ExportToText CurrentDir & "Output\text_export.txt"
C++:ISASTrace* sas_trace;TCHAR file_name[_MAX_PATH];LONG packet_from;LONG packet_to;. . .
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 61
Teledyne LeCroy SASTrace Object
try {sas_trace->ExportToText( file_name, packet_from, packet_to );}catch (_com_error& er){ if (er.Description().length() > 0) ::MessageBox( NULL, er.Description(), _T("SASTracer client"), MB_OK ); else ::MessageBox( NULL, er.ErrorMessage(), _T("SASTracer client"), MB_OK ); return 1;}
Example 2TestFileName = "MultiOpenClose"On Error Resume Nextresult = 1 ' pass'###########################################'Create STATS to report the results.Set MySTATS = WScript.CreateObject("LECROY.STATS")If Err.Number <> 0 Then
WScript.Echo "STATS Creation Failed"WScript.Quit
ELSEMySTATS.ReportText (TestFileName & " Started...")MySTATS.ReportText("STATS Automation object is created")
End If'############################################'Create Analyzer object.Set Analyzer = WScript.CreateObject("LECROY.SASAnalyzer")If Err.Number <> 0 Then
MySTATS.ReportError Err.number, Err.Descriptionresult = 2 ' fail
End IfMySTATS.ReportText ("Analyzer is created successfully")
'#############################################' First' Trace file pathProjectPath = MySTATS.GetProjectPathSet SASTracer =
Analyzer.OpenFile(ProjectPath & "Cascading-3 Board.scs")If Err.Number <> 0 Then
MySTATS.ReportError Err.number, Err.Descriptionresult = 2 ' fail
62 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASTrace Object Teledyne LeCroy
ElseMySTATS.ReportText ("Sample file is opened")
End IfMySTATS.ReportText ("Number of packets in trace file : " & CSTR(SASTracer.GetPacketsCount()))
'Get specific row of spread sheet view.start_row = SASTracer.GetPacketRow (0, 5)If Err.Number <> 0 Then
MySTATS.ReportError Err.number, Err.Descriptionresult = 2 ' fail
End Ifend_row = SASTracer.GetPacketRow (100, 5)If Err.Number <> 0 Then
MySTATS.ReportError Err.number, Err.Descriptionresult = 2 ' fail
End IfMySTATS.ReportText ("Star export row: " & CSTR(start_row))MySTATS.ReportText ("End export row: " & CSTR(end_row))SASTracer.ExportToText ProjectPath & "SpreadSheet.txt", 5, start_row, end_rowSASTracer.ExportToText ProjectPath & "FrameView.txt", 1 ' entire sample If Err.Number <> 0 Then
MySTATS.ReportError Err.number, Err.Descriptionresult = 2 ' fail
ElseMySTATS.ReportText ("Export to text has been done.")
End IfSASTracer.ExportToExcel
ProjectPath & "SpreadSheet.csv", 5 ' entire sampleSASTracer.ExportToExcel
ProjectPath & "FrameView.csv", 1, 1, 100 ' from row 1 to 100If Err.Number <> 0 Then
MySTATS.ReportError Err.number, Err.Descriptionresult = 2 ' fail
ElseMySTATS.ReportText ("Export to Excel has been done.")
End IfSASTracer.Close()If Err.Number <> 0 Then
MySTATS.ReportError Err.number, Err.Descriptionresult = 2 ' fail
ElseMySTATS.ReportText ("Trace file is closed")
End If'#########################################
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 63
Teledyne LeCroy SASTrace Object
'Report the result.MySTATS.ReportResult(result)MySTATS.ReportText ("Finished")'#########################################'Remove the object.WScript.DisconnectObject Analyzer '#########################################'Quit from the script.WScript.Quit
64 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASTrace Object Teledyne LeCroy
ITrace::ExportToExcelHRESULT ExportToExcel (
[in] BSTR file_name, [in] VIEW_TYPE export_view_type,[in] long from_row, [in] long to_row);
Exports Spreadsheet View and Frame View to an Excel file, while allowing you to specify a range of packets.
Parameters
file_name String providing the full file pathname for the exported trace
export_view_type VIEW_TYPE can be: COLUMN_VIEW (0), FRAME_TEXT_VIEW (1) [valid parameter for this method], PACKET_VIEW (2), WAVEFORM_VIEW (3), ST_REPORT_VIEW (4), SPREAD_SHEET_VIEW (5) [valid parameter for this method], HISTOGRAM_VIEW (6), BUS_UTILIZATION_VIEW (7).
from_row Beginning packet number when you are exporting a range of packets. 1 = first packet of the exported trace is the first packet of this trace.
to_row Ending packet number when you are exporting a range of packets.1 = last packet of the exported trace is the last packet of this trace.
Return Value
ANALYZERCOMERROR_UNABLESAVE Unable to export trace file
Remarks
Use this method if you want to export a recorded or opened trace into an Excel file. If the
display options apply to this trace, then hidden packets are not exported.
If the packet range specified is invalid, then the packet range is adjusted automatically.
Example
See ExportToText example.
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 65
Teledyne LeCroy SASTrace Object
ITrace::CloseHRESULT Close ( );
Closes the trace.
Parameters
Return Value
Remarks
Closes the current trace but does not release the interface pointer. Call the
IUnknown::Release method right after this method call. No ITrace method call will succeed after calling the ITrace::Close method.
Note:Currently there is no need to call ITrace::Close directly, since IUnknown::Release will close the trace.
66 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASTrace Object Teledyne LeCroy
ITrace::ReportFileInfoHRESULT ReportFileInfo (
[in] BSTR file_name )
Saves trace information into a specified text file.
Parameters
file_name String providing the full pathname to file where the trace information report is stored
Return Value
ANALYZERCOMERROR_UNABLESAVE Unable to create trace information report
Remarks
Creates a new trace information file if the file specified in the file_name parameter does not exist.
Example
WSH:Set Analyzer = WScript.CreateObject("LeCroy.SASAnalyzer")CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\"))Set Trace = Analyzer.MakeRecording (CurrentDir & "Input\test_ro.sac")Trace.ReportFileInfo CurrentDir & "Output\file_info.txt"
C++:ISASTrace* sas_trace;TCHAR file_name[_MAX_PATH];
. . . try {sas_trace->ReportFileInfo( file_name );}catch (_com_error& er){ if (er.Description().length() > 0) ::MessageBox( NULL, er.Description(), _T("SASTracer client"), MB_OK ); else ::MessageBox( NULL, er.ErrorMessage(), _T("SASTracer client"), MB_OK ); return 1;}
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 67
Teledyne LeCroy SASTrace Object
ITrace::ReportErrorSummaryHRESULT ReportErrorSummary (
[in] BSTR file_name );
Saves trace error summary information into the specified text file.
Parameters
file_name String providing the full pathname to a file where the error summary report is stored
Return Value
ANALYZERCOMERROR_UNABLESAVE Unable to create trace information report
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.
Note:This method does not work on Multisegment traces.
Here is an example of data stored using this method call:
Error report for allsata.sas recording file. _______|_______________________________________________________________________Packet Error: Idle Error on channel I1 (0): _______|_______________________________________________________________________Packet Error: Idle Error on channel T1 (0): _______|_______________________________________________________________________Packet Error: Bad CRC on channel I1 (0): _______|_______________________________________________________________________Packet Error: Bad CRC on channel T1 (0): _______|_______________________________________________________________________Packet Error: Disparity Error on channel I1 (0): _______|_______________________________________________________________________Packet Error: Disparity Error on channel T1 (0): _______|_______________________________________________________________________Packet Error: Bad Code on channel I1 (0): _______|_______________________________________________________________________Packet Error: Bad Code on channel T1 (0): _______|_______________________________________________________________________Packet Error: Alignment Error on channel I1 (0): _______|_______________________________________________________________________Packet Error: Alignment Error on channel T1 (0): _______|_______________________________________________________________________Packet Error: Delimiter Error on channel I1 (0): _______|_______________________________________________________________________Packet Error: Delimiter Error on channel T1 (0): _______|_______________________________________________________________________Packet Error: Invalid SSP Frame Type on channel I1 (0):
68 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASTrace Object Teledyne LeCroy
_______|_______________________________________________________________________Packet Error: Invalid SSP Frame Type on channel T1 (0): _______|_______________________________________________________________________Packet Error: Invalid SMP Frame Type on channel I1 (0): _______|_______________________________________________________________________Packet Error: Invalid SMP Frame Type on channel T1 (0): _______|_______________________________________________________________________Transaction Error: Timed Out SSP on channel I1 (0):_______|_______________________________________________________________________Transaction Error: Timed Out SSP on channel T1 (0): _______|_______________________________________________________________________SCSI Error: Incomplete Command on channel I1 (0): _______|_______________________________________________________________________SCSI Error: Incomplete Command on channel T1 (0): _______|_______________________________________________________________________MGMT Error: Incomplete Command on channel I1 (0): _______|_______________________________________________________________________MGMT Error: Incomplete Command on channel T1 (0): _______|_______________________________________________________________________
Example
WSH:Set Analyzer = WScript.CreateObject("LeCroy.SASnalyzer")CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\"))Set Trace = Analyzer.MakeRecording (CurrentDir & "Input\test_ro.sac")Trace.ReportErrorSummary CurrentDir & "Output\error_summary.txt"C++:ISASTrace* sas_trace;TCHAR file_name[_MAX_PATH];
. . .
try {sata_trace->ReportErrorSummary( file_name );}catch (_com_error& er){ if (er.Description().length() > 0) ::MessageBox( NULL, er.Description(), _T("SASTracer client"), MB_OK ); else ::MessageBox( NULL, er.ErrorMessage(), _T("SASTracer client"), MB_OK ); return 1;}
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 69
SASTrace Object Teledyne LeCroy
ITrace::GetPacketHRESULT GetPacket (
[in] long packet_number, [in, out] VARIANT* packet, [out, retval] long* number_of_bits );
Retrieves a raw packet representation in the PACKETFORMAT_BYTES format
(see IPacket Interface for details).
Parameters
packet_number Zero based number of packet to retrieve
packet Raw packet representation
number_of_bits Number of bits in the raw packet representation
Return Value
ANALYZERCOMERROR_INVALIDPACKETNUMBER Specified packet number is invalid
Remarks
The packet parameter has VT_ARRAY | VT_VARIANT actual automation type.
Each element of this array has the VT_UI1 automation type.
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 > 0Param = Param/2If Param - Int(Param) > 0 ThenRes = CStr(1) + ResElseRes = CStr(0) + ResEnd IfParam = Int(Param)WendDecToBin = Replace( Space(NeedLen - Len(Res)), " ", "0") & ResEnd Function
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 71
Teledyne LeCroy SASTrace Object
Sub BtnGetPacket_OnClickOn Error Resume NextDim PacketNumberOfBits = CurrentTrace.GetPacket (TextPacketNumber.value, Packet)If Err.Number <> 0 ThenMsgBox "GetPacket:" & Err.Number & ":" & Err.DescriptionElseFor Each PacketByte In PacketPacketStr = PacketStr & DecToBin(PacketByte, 8) & " "NBytes = NBytes + 1NextPacketStr = Left( PacketStr, NumberOfBits )StatusText.innerText = "Packet ( " & NumberOfBits & " bits ): " & PacketStrEnd IfEnd Sub--></SCRIPT>
C++: ISASTrace* sas_trace; LONG packet_number;
. . .
VARIANT packet; VariantInit( &packet ); long number_of_bits; try { number_of_bits = sata_trace->GetPacket( packet_number, &packet ); } catch (_com_error& er) { if (er.Description().length() > 0) ::MessageBox( NULL, er.Description(), _T("SASTracer client"), MB_OK ); else ::MessageBox( NULL, er.ErrorMessage(),_T("SASTracer client"), MB_OK ); return 1; }
72 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASTrace Object Teledyne LeCroy
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("SASTracer client"), MB_OK); return 1; } if ( var.vt != ( VT_UI1) ) { ::MessageBox(NULL, _T("Array of bytes expected"), _T("SASTracer client"), MB_OK); return 1; }
_stprintf( elem, _T("%02X "), V_UI1(&var) ); _tcscat( packet_message, elem ); } _stprintf( elem, _T("%d bits"), number_of_bits ); _tcscat( packet_message, elem );
::MessageBox( NULL, packet_message, _T("Raw packet bits"), MB_OK ); } else { ::MessageBox(NULL, _T("Invalid argument"), _T("SASTracer client"), MB_OK); }
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 73
Teledyne LeCroy SASTrace Object
ITrace::GetPacketsCountHRESULT GetPacketsCount (
[out, retval] long* number_of_packets );
Retrieves the total number of packets in the trace.
Parameters
number_of_packets Total number of packets in the trace
Return Value
Remarks
Example
WSH:Set Analyzer = WScript.CreateObject("LeCroy.SASAnalyzer")CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\"))Set Trace = Analyzer.MakeRecording (CurrentDir & "Input\test_ro.sac")MsgBox Trace.GetPacketsCount & " packets recorded"
C++:ISASTrace* sas_trace;
. . .
long number_of_packets;long trigg_packet_num;try{bstr_trace_name = sas_trace->GetName();number_of_packets = sas_trace->GetPacketsCount();trigg_packet_num = sas_trace->GetTriggerPacketNum();}catch (_com_error& er){ if (er.Description().length() > 0) ::MessageBox( NULL, er.Description(), _T("SASTracer client"), MB_OK ); else ::MessageBox( NULL, er.ErrorMessage(),_T("SASTracer client"), MB_OK ); return 1; }
74 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASTrace Object Teledyne LeCroy
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 75
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 SASTrace Object
ITrace::GetTriggerPacketNumHRESULT GetTriggerPacketNum (
[out, retval] long* packet_number );
Retrieves the trigger packet number.
Parameters
packet_number Zero based number of the packet where the trigger occurred
Return Value
Remarks
Example
WSH:CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\"))Set Analyzer = WScript.CreateObject("LeCroy.SASAnalyzer")Set Trace = Analyzer.MakeRecording (CurrentDir & "Input\test_ro.sac")TriggerPacket = Trace.GetTriggerPacketNumTrace.Save CurrentDir & "Output\trigger_portion.sas", CInt(ErrorPacket)-5, CInt(ErrorPacket)+5Trace.ExportToText CurrentDir & "Output\trigger_portion.txt", CInt(ErrorPacket)-5, CInt(ErrorPacket)+5
C++:
See example for ITrace::GetPacketsCount.
76 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASTrace Object Teledyne LeCroy
ITrace::AnalyzerErrorsHRESULT AnalyzerErrors (
[in] long error_type, [out, retval] ISASAnalyzerErrors**
analyzer_errors );
Retrieves trace file errors. Returns an interface pointer to the SASTraceErrors object
Parameters
error_type Type of error collection you want to retrieve;
The following values are valid:
0 = OOB Sequence Error 1 = Symbol violation 2 = Disparity Error 3 = Alignment Error 4 = Signaling Latency Error 5 = Invalid State Transition unexpected primitive 6 = Invalid State Transition Primitive Response Time‐out 7 = FIS Type Error 8 = FIS Length Error 9 = FIS Direction Error 10 = CRC Error
analyzer_errors Address of a pointer to the SASTraceErrors Object interface
Return Value
ANALYZERCOMERROR_INVALIDERROR Invalid error type specified
Remarks
The SASTraceErrors object is created by this method call, if the call was successful.
Example
WSH:CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\"))Set Analyzer = WScript.CreateObject("LeCroy.SASAnalyzer")Set Trace = Analyzer.MakeRecording (CurrentDir & "Input\test_ro.sac")Set Errors = Trace.AnalyzerErrors (16) 'Bad CRC16
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 77
Teledyne LeCroy SASTrace Object
78 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
C++:ISASTrace* sas_trace;. . . ISASAnalyzerErrors* analyser_errors;try{analyser_errors = sas_trace->AnalyzerErrors(error_type).Detach();}catch (_com_error& er){ if (er.Description().length() > 0) ::MessageBox( NULL, er.Description(), _T("SASTracer client"), MB_OK ); else ::MessageBox( NULL, er.ErrorMessage(),_T("SASTracer client"), MB_OK ); return 1;}. . . analyser_errors->Release();
SASTrace Object Teledyne LeCroy
ISASTrace Interface
The ISASTrace interface is a primary dual interface for the SASTrace object.
This interface is derived from the ITrace interface.
The ISASTrace interface implements all methods from the ITrace interface plus the
following: GetBusPacket
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 79
Teledyne LeCroy SASTrace Object
ISASTrace::GetBusPacketHRESULT GetBusPacket (
[in] long packet_number, [out, retval] IDispatch** packet )
Retrieves the interface for a packet within a trace.
Parameters
packet_number Zero based number of packet to retrieve
packet Address of a pointer to the SASPacket Object interface
Return Value
Remarks
The SASPacket object is created by this method call, if the call was successful.
Example
WSH:
C++: ISASTrace* sas_trace; . . . IDispatch* packet; try{ packet = sas_trace->GetBusPacket( GetDlgItemInt(IDC_PACKET_NUMBER) ).Detach();} catch ( _com_error& er) { if (er.Description().length() > 0) ::MessageBox( NULL, er.Description(), _T("SASTracer client"), MB_OK ); else ::MessageBox( NULL, er.ErrorMessage(),_T("SASTracer client"), MB_OK ); return 1; }ISASPacket* custom_packet; HRESULT hr = packet->QueryInterface(IID_ISASPacket, (void**)&custom_packet); packet->Release();
80 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASTrace Object Teledyne LeCroy
ISASVerificationScript Interface
The ISASVerificationScript interface is an interface for the SASTrace object. It exposes the trace functionality for running verification scripts. This interface is not dua, 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 SASTrace 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 use a special feature of the Teledyne LeCroy SAS/SATA Protocol Suite application, its Verification Script Engine.
Please refer to the SASTracer Manual, SASTracer Verification Script Engine Manual, and 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 will open segments of the multi‐segmented trace during script execution when needed.
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 81
Teledyne LeCroy SASTrace Object
ISASVerificationScript::RunVerificationScriptHRESULT RunVerificationScript (
[in] BSTR verification_script, [out, retval] VSResult *result )
Runs a verification script over the recorded trace.
Parameters
verification_script Name of the verification script to run
result Address of a variable in which to keep the verification result
VS_RESULT is an enumeration type that can have five meanings:
SCRIPT_RUNNING (-2) Verification script is running
SCRIPT_NOT_FOUND (-1) Verification script with the specified name not found
FAILED ( 0) Verification failed
PASSED ( 1) Verification passed
DONE ( 2) Verification is done, do not care about result
Return Value
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 script name, without file extension, is specified, the Sierra/STX server searches for the named script among the scripts loaded from the \Scripts\VFScripts folder under the SAS/SATA Protocol Suite installation folder. If the full path to the script is specified, then the server attempts to load the script from the specified path prior to running it.
Example
For a verification script file named test.pevs, the test name is “test”. Please refer to the SASTracer Verification Script Engine Manual for more details.
Example
C++:// This example uses wrapper functions provided by the #import directive.
ISASTrace* trace;
. . .
ISASVerificationScript* vscript = NULL;
82 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASTrace Object Teledyne LeCroy
if ( SUCCEEDED ( trace->QueryInterface( IID_ISASVerificationScript, (void**)&vscript ) ) { try { VS_RESULT result = vscript ->RunVerificationScript("Test1"); if( result == PASSED ) { ::MessageBox( NULL, "Test verification 1 is passed !!!", "SASTracer client", MB_OK ); } } catch (_com_error& er) { if (er.Description().length() > 0) ::MessageBox( NULL, er.Description(), "SASTracer client", MB_OK ); else ::MessageBox( NULL, er.ErrorMessage(), "SASTracer client", MB_OK ); return 1; } }
else { ::MessageBox( NULL, "Unable to get ISASVerificationScript interface !!!", _T("SASTracer client"), MB_OK ); return 1 ; }
. . .
WSH:
Set Analyzer = WScript.CreateObject("LeCroy.SASTracer")
Set Trace = Analyzer.OpenFile( "C:\Some trace files\some_trace.sas" )
Dim Result
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 83
Teledyne LeCroy SASTrace Object
Result = Trace.RunVerificationScript( "Test1" )
If Result = 1 Then Msgbox "PASSED" Else Msgbox "FAILED" End If
MsgBox( "Done" )
84 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASTrace Object Teledyne LeCroy
ISASVerificationScript:: GetVScriptEngineHRESULT GetVScriptEngine (
[in] BSTR script_name, [out, retval] IVScriptEngine** vs_engine )
Retrieves the verification script engine object.
Parameters
script_name Name of the verification script to initialize the verification script engine
vs_engine Address of a pointer to the SASVScriptEngine Object interface
Return Value
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 ISASVerificationScript::RunVerificationScript for details.
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 85
Teledyne LeCroy SASTrace Object
Example
C++:// This example uses wrapper functions provided by the #import directive.
ISASTrace* sas_trace; . . . ISASVerificationScript* sas_vscript = NULL;
sas_trace->QueryInterface(IID_ISASVerificationScript, (void**)&sas_vscript))assert( sas_vscript != NULL ); IVScriptEngine* sas_vsengine = NULL; sas_vsengine = sas_vscript -> GetVScriptEngine("Test_1"); assert( sas_vsengine != NULL ); VS_RESULT result = sas_vsengine ->RunVScript();
if( result == PASSED ) { ::MessageBox( NULL, "Test verification 1 is passed !!!", "SASTracer client", MB_OK ); }
. . .
WSH:Set Analyzer = WScript.CreateObject("LeCroy.SASTracer")
Set Trace = Analyzer.OpenFile( "C:\Some trace files\some_trace.sas" ) Dim Result Set VSEngine = Trace.GetVScriptEngine( "Test1" ) Result = VSEngine.RunVScript If Result = 1 Then Msgbox "PASSED" ElseMsgbox "FAILED" End If MsgBox( "Done" )
86 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASRecOptions Object Teledyne LeCroy
SASRecOptions Object
The SASRecOptions object represents the options for the Sierra/STX hardware and specifies the recording parameters.
The SASRecOptions object allows you 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 ChannelSettings, DataTruncate,
MultiSegment mode, and SpoolMode.
The SASRecOptions object can be created by using the ISASAnalyzer::GetRecordingOptions method.
The SASRecOptions object supports the following interfaces:
The ISASRecOptions interface is a primary interface for the SASRecOptions object.
IRecOptions Interface
The IRecOptions interface is a dual interface for the SASRecOptions object.
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 ISASRecOptions Interface.
Interfaces Description
IRecOptions Allows you to load/save recording options from/to the file, reset recording options, and set recording mode, recording buffer size, trigger position, and trace file name.
ISASRecOptions Identical to the IRecOptions interface
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 87
Teledyne LeCroy SASRecOptions Object
IRecOptions::LoadHRESULT Load (
[in] BSTR ro_file_name );
Loads recording options from the specified file.
Parameters
ro_file_name String that provides the full pathname to the recording options file
Return Value
ANALYZERCOMERROR_UNABLEOPENFILE Unable to open file
Remarks
Example
WSH:
CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\"))Set Analyzer = WScript.CreateObject("LeCroy.SASAnalyzer")Set RecOptions = Analyzer.GetRecordingOptionsRecOptions.Load( CurrentDir & "Input\rec_options.sac" )
C++:
88 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASRecOptions Object Teledyne LeCroy
IRecOptions::SaveHRESULT Save (
[in] BSTR ro_file_name );
Saves recording options into the specified file.
Parameters
ro_file_name String that provides the full pathname to the recording options file
Return Value
ANALYZERCOMERROR_UNABLEOPENFILE Unable to open file
Remarks
If the specified file does not exist, it will be created. If it exists, it will be overwritten.
Example
WSH:
CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\"))Set Analyzer = WScript.CreateObject("LeCroy.SASAnalyzer")Set RecOptions = Analyzer.GetRecordingOptions' Do the changes of recording options here.RecOptions.Save( CurrentDir & "Input\rec_options.sac" )
C++:
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 89
Teledyne LeCroy SASRecOptions Object
IRecOptions::SetRecModeHRESULT SetRecMode (
[in] ERecModes rec_mode );
Sets the recording mode.
Parameters
rec_mode Enumerated value providing the mode to set.
ErecModes enumerator has the following values:
RMODE_SNAPSHOT ( 0 ) = snapshot recording mode
RMODE_MANUAL ( 1 ) = manual trigger
RMODE_USE_TRG ( 2 ) = event trigger
Return Value
E_INVALIDARG Invalid recording mode specified
Remarks
The default setting of recording options is "snapshot" recording mode.
Example
WSH:
Set Analyzer = WScript.CreateObject("LeCroy.SASAnalyzer")Set RecOptions = Analyzer.GetRecordingOptionsRecOptions.SetRecMode 2 ' Event trigger
C++:
90 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASRecOptions Object Teledyne LeCroy
IRecOptions::SetBufferSizeHRESULT SetBufferSize (
[in] long buffer_size );
Sets the size of the recording buffer.
Parameters
buffer_size Size of the recording buffer in bytes
Return Value
E_INVALIDARG Invalid buffer size specified
Remarks
The default setting is 16 MB for Conventional Recording mode and 120 GB or 12.5 hours for Spooled Recording Mode.
Example
WSH:
Set Analyzer = WScript.CreateObject("LeCroy.SASAnalyzer")Set RecOptions = Analyzer.GetRecordingOptionsRecOptions.SetBufferSize 2*1024*1024 ' 2 MB
C++:
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 91
Teledyne LeCroy SASRecOptions Object
IRecOptions::SetPostTriggerPercentageHRESULT SetPostTriggerPercentage (
[in] short posttrigger_percentage );
Sets the post‐trigger buffer size.
Parameters
posttrigger_percentage Size of the post‐trigger buffer in percent of the whole recording buffer (see IRecOptions::SetBufferSize).
Return Value
E_INVALIDARG Invalid percentage specified
Remarks
This method call has no effect if recording mode is set to RMODE_SNAPSHOT (see IRecOptions::SetRecMode).
The default setting is 50%.
Example
WSH:
Set Analyzer = WScript.CreateObject("LeCroy.SASAnalyzer")Set RecOptions = Analyzer.GetRecordingOptionsRecOptions.SetPostTriggerPercentage 60 ' 60%
C++:
92 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASRecOptions Object Teledyne LeCroy
IRecOptions::SetTriggerBeepHRESULT SetTriggerBeep (
[in] BOOL beep );
Sets a flag to make a sound when a trigger occurs.
Parameters
beep TRUE = Beep when trigger occurs.
FALSE = Do not beep when trigger occurs.
Return Value
Remarks
The default state of the beeper is FALSE.
Example
WSH:
Set Analyzer = WScript.CreateObject("LeCroy.SASAnalyzer")Set RecOptions = Analyzer.GetRecordingOptionsRecOptions.SetTriggerBeep TRUE
C++:
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 93
Teledyne LeCroy SASRecOptions Object
IRecOptions::SetSaveExternalSignalsHRESULT SetSaveExternalSignals (
[in] BOOL save );
Sets a flag to save external signals.
Parameters
save TRUE = Save external signals.
FALSE = Do not save external signals.
Return Value
Remarks
By default, external signals are not saved.
Example
WSH:
Set Analyzer = WScript.CreateObject("LeCroy.SASAnalyzer")Set RecOptions = Analyzer.GetRecordingOptionsRecOptions.SetSaveExternalSignals TRUE
C++:
94 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASRecOptions Object Teledyne LeCroy
IRecOptions::SetTraceFileNameHRESULT SetTraceFileName (
[in] BSTR file_name );
Sets the file path to where the trace will be stored after recording.
Parameters
file_name String that provides the full file pathname to where the recording
will be stored
Return Value
Remarks
If the specified file does not exist, it will be created. If it exists, it will be overwritten.
This is the path that can be set to the Capture project directly, which would be used to save the trace file.
Note:For the ATS user, this pathname is set in the ATS‐setting‐page. But for non‐ATS user (where there is no ATS‐path available) API takes it from the capture‐project directly, which can be set using this API.
Example
WSH:
CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\"))Set Analyzer = WScript.CreateObject("LeCroy.SASAnalyzer")Set RecOptions = Analyzer.GetRecordingOptions' Do the changes of recording options here.RecOptions.Save( CurrentDir & "Input\trace.sas" )
C++:
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 95
Teledyne LeCroy SASRecOptions Object
IRecOptions::ResetHRESULT Reset ( )
Resets the recording options to the initial state.
Parameters
Return Value
Remarks
For default values of recording options, see the remarks sections of the IRecOptions Interface and ISASRecOptions Interface methods.
Example
WSH:
Set Analyzer = WScript.CreateObject("LeCroy.SASAnalyzer")Set RecOptions = Analyzer.GetRecordingOptionsRecOptions.SetRecMode 2 ' Event trigger RecOptions.SetBufferSize 1024*1024 ' 1 MB RecOptions.SetPostTriggerPercentage 60 ' 60% . . .RecOptions.Reset()
C++:
ISASRecOptions Interface
This interface is identical to the IRecOptions Interface.
96 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASPacket Object Teledyne LeCroy
SASPacket Object
The SASPacket object represents a single packet of the recorded trace file.
The SASPacket object allows you to retrieve packet content and packet properties, such as
timestamp, link width, packet start lane, packet direction, and packet errors.
The SASPacket object can be created by calling ISASTrace::GetBusPacket.
The SASPacket object supports the following interfaces:
The ISASPacket interface is a primary interface for the SASPacket object.
IPacket Interface
The IPacket interface is a dual interface for the SASPacket object.
IPacket implements the following method:
GetTimestamp
Note:All methods of the IPacket interface are also available in the ISASPacket Interface.
Interfaces Description
IPacket Allows retrieval of the packet timestamp.
ISASPacket Extends the IPacket interface.
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 97
Teledyne LeCroy SASPacket Object
IPacket::GetTimestampHRESULT GetTimestamp ( [out, retval] double* timestamp
Returns the packet timestamp in nanoseconds.
Parameters
timestamp Timestamp of the beginning symbol of the packet, from the start of recording
Return values
Remarks
Example
WSH:
Set Analyzer = WScript.CreateObject( “LeCroy.SASTracer” ) Set Trace = Analyzer.MakeRecording( CurrentDir & "Input\test_ro.sac" ) TriggerPacket = Trace. GetTriggerPacketNum Set Packet = Trace.GetBusPacket(TriggerPacket) MsgBox "Trigger packet at " & Packet.GetTimestamp & " ns"
C++:
98 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASPacket Object Teledyne LeCroy
ISASPacket Interface
The ISASPacket interface is a primary dual interface for the SASPacket object.
This interface is derived from the IPacket interface.
The ISASPacket interface implements all methods from the IPacket interface, plus the following:
GetPacketData GetLinkNumber GetFrameType GetDirection GetErrors GetTotalDwords
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 99
Teledyne LeCroy SASPacket Object
IPacket::GetPacketDataHRESULT GetPacketData ( [in] EPacketFormat format, [out] VARIANT* packet, [out, retval] long* number_of_bytes )
Retrieves a raw packet representation.
Parameters
format Data representation format
The EPacketFormat enumerator has the following values:
PACKETFORMAT_BYTES ( 0 ) bytes
PACKETFORMAT_SCRAMBLED_BYTES ( 1 ) scrambled bytes
PACKETFORMAT_TEN_BIT ( 2 ) 10‐bit codes
packet Raw packet data
number_of_bytes Number of bytes in the packet
Return Value
ANALYZERCOMERROR_WRONGCALL Unknown packet format specified
Remarks
The packet parameter has VT_ARRAY | VT_VARIANT actual automation type.
For PACKETFORMAT_BYTES and PACKETFORMAT_SCRAMBLED_BYTES, each element of this array has the VT_UI1 automation type.
For PACKETFORMAT_TEN_BIT, each element of this array has the VT_UI2 automation type.
Example
VBScript: <OBJECT ID = Analyzer CLASSID = "clsid: 0B179BB7-DC61-11d4-9B71-000102566088"
> </OBJECT>
<INPUT TYPE=TEXT NAME="TextPacketNumber"> <P ALIGN=LEFT ID=StatusText></P>
<SCRIPT LANGUAGE="VBScript"> <!-- Function DecToBin(Param, NeedLen) While Param > 0 Param = Param/2
100 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASPacket Object Teledyne LeCroy
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_OnClickClearStatus() On Error Resume Next Set Packet = CurrentTrace.GetBusPacket (TextPacketNumber.value)
If Err.Number <> 0 Then MsgBox "GetBusPacket:" & Err.Number & ":" & Err.Description Else Timestamp = Packet.GetTimestamp() If Err.Number <> 0 Then MsgBox "GetTimestamp:" & Err.Number & ":" & Err.Description End If
NumberOfUnits = Packet.GetPacketData ( PACKETFORMAT_BYTES, PacketData)
If Err.Number <> 0 Then MsgBox "GetPacketData:" & Err.Number & ":" & Err.Description Else For Each PacketByte In PacketData PacketStr = PacketStr & DecToBin(PacketByte, 8) & " " NBytes = NBytes + 1 Next
StatusText.innerText = "Packet ( " & NumberOfUnits & " bytes ): " & PacketStrEnd If End If End Sub -->
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 101
Teledyne LeCroy SASPacket Object
</SCRIPT>
C++:
ISASPacket* custom_packet; LONG packet_number; . . . VARIANT packet_data; double timestamp_ns; VariantInit( &packet_data ); long number_of_bytes; try { number_of_bytes = custom_packet->GetPacketData(PACKETFORMAT_BYTES, &packet_data);timestamp_ns = custom_packet->GetTimestamp ( ); } catch (_com_error& er) { if (er.Description().length() > 0) ::MessageBox( NULL, er.Description(), _T("SASTracer client"), MB_OK ); else ::MessageBox( NULL, er.ErrorMessage(),_T("SASTracer client"), MB_OK ); return 1; }if ( packet_data.vt == ( VT_ARRAY | VT_VARIANT) ) { SAFEARRAY* packet_safearray = packet_data.parray; TCHAR* packet_message = new TCHAR [ 3*packet_safearray->rgsabound[0].cElements + 64 ]; TCHAR elem[64]; _stprintf(packet_message, _T("packet #%ld: "), GetDlgItemInt(IDC_PACKET_NUMBER)); _stprintf( elem, _T(" %.0lf ns"), timestamp_ns ); _tcscat( packet_message, elem ); _stprintf( elem, _T(", %d bytes: "), number_of_bytes ); _tcscat( packet_message, elem );
102 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASPacket Object Teledyne LeCroy
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("SASTracer client"), MB_OK);return 1; }
if ( var.vt != ( VT_UI1) ) { ::MessageBox(NULL,_T("Array of bytes expected"),_T("SASTracer client"),MB_OK); return 1; } _stprintf( elem, _T("%02X "), V_UI1(&var) ); _tcscat( packet_message, elem ); } ::MessageBox( NULL, packet_message, _T("packet"), MB_OK ); delete [] packet_message; } else { ::MessageBox(NULL, _T("Invalid argument"), _T("SASTracer client"), MB_OK );
}
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 103
Teledyne LeCroy SASPacket Object
IPacket::GetDirectionHRESULT GetDirection ( [out, retval] long* direction )
Returns direction (host/device for SATA or initiator/target for SAS) of this packet.
Parameters
direction 0 = Host (initiator) packet
1 = Device (target) packet
Return Value
Remarks
Example
WSH:
CurrentDir = Left( WScript.ScriptFullName, InstrRev( WScript.ScriptFullName, “\” ) )Set Analyzer = WScript.CreateObject( “LeCroy.SASTracer” ) Set Trace = Analyzer.OpenFile( CurrentDir & “Input\errors.sas” ) Set Packet = Trace.GetBusPacket( 0 ) MsgBox "Direction: " & Packet.GetDirection
C++:
104 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASPacket Object Teledyne LeCroy
IPacket::GetErrorsHRESULT GetErrors ( [out] VARIANT* error_array, [out, retval] long* number_of_errors )
Returns an array of errors present in this packet.
Parameters
error_array Array of error IDs present in this packet.
See ITrace::AnalyzerErrors for error ID values.
number_of_errors Total number of errors in this packet
Return Value
Remarks
Example
WSH:
C++:
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 105
Teledyne LeCroy SASPacket Object
IPacket:: GetLinkNumberHRESULT GetLinkNumber ([out, retval] long* link_number )
Returns analyzer link number of this packet.
Parameters
Link_number It is the analyzer link number of this packet which starts from 1 (I1 and T1).
Return Value
Remarks
Example
106 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASPacket Object Teledyne LeCroy
IPacket:: GetFrameTypeHRESULT GetFrameType ([out, retval] long* frame_type )
Returns frame type of this packet.
Parameters
frame_type It is the frame type of this packet which can be one of the following values:
SAS_FT_UNKNOWN 0
SAS_FT_PRIMITIVE 1
SAS_FT_AF_OPEN 3
SAS_FT_AF_IDENTIFY 4
SAS_FT_SSP_FRAME 5
SAS_FT_SMP_FRAME 6
SAS_FT_STP_FRAME 7
SAS_FT_IDLE 8
SAS_FT_TRAINING 9
SAS_FT_OOB_SIGNAL 10
SAS_FT_DEV_SLP 11
Return Value
Remarks
Example
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 107
Teledyne LeCroy SASPacket Object
IPacket:: GetTotalDwordsHRESULT GetTotalDwords ([out, retval] long* total_dwords )
Returns DWords’ number of this packet.
Parameters
total_dwords It is total number of DWords of this packet.
Return Value
Remarks
Example
108 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASTraceErrors Object Teledyne LeCroy
SASTraceErrors Object
The SASTraceErrors object represents the collection of errors that occurred in the recorded trace file.
The SASTraceErrors object can be created by calling ITrace::AnalyzerErrors.
The ISASAnalyzerErrors interface is a primary interface for the SASTraceErrors object.
ISASAnalyzerErrors Dispinterface
This is a standard collection interface for collection of packet numbers with errors of a specified type (see ITrace::AnalyzerErrors).
It has the following methods, which are standard for collection interfaces:
get_Item get_Count
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 109
Teledyne LeCroy SASTraceErrors Object
ISASAnalyzerErrors::get_ItemHRESULT get_Item(
[in] long index, [out, retval] long* packet_number );
Get items.
Parameters
index Index of the error in the collection
packet_number Error packet number
110 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASTraceErrors Object Teledyne LeCroy
ISASAnalyzerErrors::get_CountHRESULT get_Count(
[out, retval] long* number_of_errors );
Returns the number of errors in the trace.
Parameters
number_of_errors Number of elements in the collection
Remarks
Example
WSH:
' Makes recording and saves the portions of the recorded trace ' where "Running Disparity" errors occured.CurrentDir = Left(WScript.ScriptFullName, InstrRev( WScript.ScriptFullName, “\” ))Set Analyzer = WScript.CreateObject( “LeCroy.SASTracer” ) Set Trace = Analyzer.MakeRecording( CurrentDir & "Input\test_ro.sac" ) Set Errors = Trace.AnalyzerErrors( 32 ) ' Running Disparity Error For Each ErrorPacketNumber In Errors ErrorFile = CurrentDir & "\Output\PckLen_error_span_" &
CStr(ErrorPacketNumber) & ".sas" Trace.Save ErrorFile, CInt(ErrorPacketNumber)-5, CInt(ErrorPacketNumber)+5 Next
C++:ISASTrace* sas_trace;
. . .
ISASAnalyzerErrors* analyser_errors;try{analyser_errors = sas_trace->AnalyzerErrors(error_type).Detach();}
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 111
Teledyne LeCroy SASTraceErrors Object
catch (_com_error& er){ if (er.Description().length() > 0) ::MessageBox( NULL, er.Description(), _T("SASTracer client"), MB_OK ); else ::MessageBox( NULL, er.ErrorMessage(),_T("SASTracer client"), MB_OK ); return 1;}
TCHAR all_errors[2048];_stprintf( all_errors, _T("Errors: ") );
try{long errors_count = analyser_errors->GetCount();long analyzer_error;if ( !errors_count ){_tcscat( all_errors, _T("none") );}for ( long i=0; i<errors_count && i<2048/32; i++ ){analyzer_error = analyser_errors->GetItem(i);TCHAR cur_error[32];_stprintf( cur_error, _T(" %ld"), analyzer_error );_tcscat( all_errors, cur_error );}if ( i>2048/32 )_tcscat( all_errors, _T(" ...") );}catch (_com_error& er){ if (er.Description().length() > 0) ::MessageBox( NULL, er.Description(), _T("SASTracer client"), MB_OK ); else ::MessageBox( NULL, er.ErrorMessage(),_T("SASTracer client"), MB_OK ); return 1;}
analyser_errors->Release();
::SetWindowText( m_hwndStatus, all_errors );
112 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASVScriptEngine Object Teledyne LeCroy
SASVScriptEngine Object
The SASVScriptEngine object allows you to run verification scripts over the recorded trace.
It extends the functionality of the ISASVerificationScript interface of a SASTrace object. The main advantage of a SASVScriptEngine object is that it allows clients implementing
_IVScriptEngineEvents a callback interface to receive notifications when a verification script is running.
The SASVScriptEngine object can be created by calling
ISASVerificationScript:: GetVScriptEngine.
The SASVScriptEngine object supports the following interfaces:
The IVScriptEngine interface is a primary interface for the SASVScriptEngine 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 use a special feature of the SAS/SATA Protocol Suite application, its Verification Script Engine.
Please refer to the SASTracer Manual, SASTracer Verification Script Engine Manual, and File Based Decoding Manual for more details.
Interfaces Description
IVScriptEngine Provides advanced control over the verification script and allows you to execute the script asynchronously.
_ISASAnalyzerEvents Events from SASVScriptEngine object
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 113
Teledyne LeCroy SASVScriptEngine Object
IVScriptEngine Interface
The IVScriptEngine interface is the primary dual interface for the SASVScriptEngine object. It implements the following properties and methods:
RunVScript RunVScriptEx LaunchVScript Stop
114 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASVScriptEngine Object Teledyne LeCroy
IVScriptEngine::RunVScriptHRESULT RunVScript ( [out, retval] int* pResult )
Runs the verification script currently specified for this engine.
Parameters
pResult Address of the variable where the results of the verification are kept
Return Value
Remarks
The name of the verification script is the name of the verification script file (*.pevs). If only the script name, without a file extension, is specified, the Sierra/STX server searches for the named script among the scripts loaded from the \Scripts\VFScripts folder under the SAS/SATA Protocol Suite installation folder. If the full path to the script is specified, then the server attempts to load the script from the specified path prior to running it.
Example
C++: // This example uses wrapper functions provided by the #import directive.
ISASTrace* sas_trace;
. . .
ISASVerificationScript* sas_vscript = NULL;
sas_trace->QueryInterface(IID_ISASVerificationScript, (void**)&sas_vscript))assert( sas_vscript != NULL ); IVScriptEngine* sas_vsengine = NULL; sas_vsengine = sas_vscript -> GetVScriptEngine("MyVSEngine"); assert( sas_vsengine != NULL );
sas_vsengine -> PutVScriptName("Test_1"); assert( sas_vsengine -> GetVScriptName() == "Test_1" );
VS_RESULT result = sas_vsengine ->RunVScript(); if( result == PASSED ) { ::MessageBox( NULL, "Test 1 passed !!!", "SASTracer client", MB_OK ); } . . .
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 115
Teledyne LeCroy SASVScriptEngine Object
IVScriptEngine::RunVScriptExHRESULT RunVScriptEx ( [in] BSTR script_name, [out, retval] int* pResult )
Changes the current verification script name and runs the verification script.
Parameters
script_name Name of the verification script to initialize the script verification engine
pResult Address of the variable where the results of the verification are kept
Return Value
Remarks
This method makes a “synchronous” call, which means that this method does not return until the script stops running.
The name of the verification script is the name of the verification script file (*.pevs). If only the script name, without a file extension, is specified, the Sierra/STX server searches for the named script among the scripts loaded from the \Scripts\VFScripts folder under the SAS/SATA Protocol Suite installation folder. If the full path to the script is specified, then the server attempts to load the script from the specified path prior to running it.
See the ISASVerificationScript::RunVerificationScript method for details.
116 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASVScriptEngine Object Teledyne LeCroy
Example
C++: // This example uses wrapper functions provided by the #import directive.ISASTrace* sas_trace; . . . ISASVerificationScript* sas_vscript = NULL;
sas_trace->QueryInterface(IID_ISASVerificationScript, (void**)&sas_vscript ) ) assert( sas_vscript != NULL );
IVScriptEngine* sas_vsengine = NULL; sas_vsengine = sas_vscript -> GetVScriptEngine("Test_1"); assert( sas_vsengine != NULL );
VS_RESULT result = sas_vsengine ->RunVScript(); if( result == PASSED ) { ::MessageBox( NULL, "Test 1 passed !!!", "SASTracer client", MB_OK ); } result = sas_vsengine ->RunVScriptEx("Test_2"); if( result == PASSED ) { ::MessageBox( NULL, "Test 2 passed !!!", "SASTracer client", MB_OK ); } result = sas_vsengine ->RunVScriptEx("C:\\MyTests\\Test_3.pevs"); if( result == PASSED ) {::MessageBox( NULL, "Test 3 passed !!!", "SASTracer client", MB_OK ); } . . .
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 117
Teledyne LeCroy SASVScriptEngine Object
IVScriptEngine::LaunchVScriptHRESULT LaunchVScript ( )
Launches the current verification script.
Parameters
Return Value
S_FALSE If VS Engine was not successfully launched
(either it is already running, or the verification script was not found)
Remarks
This method makes an “asynchronous” call, which means that this method immediately returns after the script starts running.
When the verification script stops running, the VSE object sends a special event notification IVScriptEngineEvents::OnVScriptFinished to the client event handler. You can also terminate the running script using the method IVScriptEngine::Stop.
Example
C++:
// This example uses wrapper functions provided by the #import directive.
ISASTrace* sas_trace;
. . .
ISASVerificationScript* sas_vscript = NULL;
sas_trace->QueryInterface( IID_ISASVerificationScript, (void**)&sas_vscript ) ) assert( sas_vscript != NULL );
IVScriptEngine* sas_vsengine = NULL; sas_vsengine = sas_vscript -> GetVScriptEngine("Test_1"); assert( sas_vsengine != NULL );
VS_RESULT result = sas_vsengine ->LaunchVScript();
// You can go further without waiting for the result from the VSE object. // If you are interested in the result, implement the client event handler// for OnVScriptFinished() notification. . . .
118 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASVScriptEngine Object Teledyne LeCroy
IVScriptEngine::StopHRESULT Stop ( )
Stops the verification script previously launched by IVScriptEngine::LaunchVScript.
Parameters
Return Value
Remarks
Example
C++:
// This example uses wrapper functions provided by the #import directive.
ISASTrace* sas_trace;
. . .
ISASVerificationScript* sas_vscript = NULL;
sas_trace->QueryInterface( IID_ISASVerificationScript, (void**)&sas_vscript ) ) assert( sas_vscript != NULL );
IVScriptEngine* sas_vsengine = NULL; sas_vsengine = sas_vscript -> GetVScriptEngine("Test_1"); assert( sas_vsengine != NULL );
VS_RESULT result = sas_vsengine ->LaunchVScript();
. . .
if( NotEnoughResourcesToProcessVS ) sas_vsengine ->Stop();
. . .
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 119
Teledyne LeCroy SASVScriptEngine Object Events
SASVScriptEngine Object Events
_IVScriptEngineEvents Interface
To retrieve event notifications from the Teledyne LeCroy SAS/SATA Protocol Suite application when a verification script engine object is running the script, you must implement the _IVScriptEngineEvents callback interface. Since this interface is a default source interface for the SASVScriptEngine object, there is a very simple implementation from languages such as Visual Basic, VBA, VBScript, and WSH.
Some script engines impose restrictions on handling events from “indirect” automation objects in typeless script languages (when an automation interface to the object is obtained from a call of some method, rather than from creation function, such as CreateObject() in VBScript). The SAS/SATA Protocol Suite application provides a special COM class, allowing receiving and handling of notifications from a VSE object even in script languages not supporting event handling from "indirect" objects.
Example
The C++ implementation used in the examples below implements an event sink object by deriving it from IdispEventImpl, but not specifying the type library as a template argument. Instead, the type library and default source interface for the object are determined using AtlGetObjectSourceInterface().
A SINK_ENTRY() macro is used for each event from each source interface that is to be handled:
Example
C++: class CVSEngineSink : public IDispEventImpl<IDC_SRCOBJ_VSE, CVSEngineSink > { public: ... BEGIN_SINK_MAP(CVSEngineSink) // Make sure the Event Handlers have __stdcall calling convention. SINK_ENTRY( IDC_SRCOBJ_VSE, 1, OnVScriptReportUpdated )
SINK_ENTRY( IDC_SRCOBJ_VSE, 2, OnVScriptFinished ) SINK_ENTRY( IDC_SRCOBJ_VSE, 3, OnNotifyClient ) END_SINK_MAP() HRESULT __stdcall OnVScriptReportUpdated ( BSTR newLine, int TAG ); HRESULT __stdcall OnVScriptFinished( BSTR script_name, VS_RESULT result, int TAG ); HRESULT __stdcall OnNotifyClient (int eventId, VARIANT eventBody, int TAG);
120 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASVScriptEngine Object Events Teledyne LeCroy
HRESULT Advise(IUnknown* pUnk) { AtlGetObjectSourceInterface(pUnk, &m_libid, &m_iid, &m_wMajorVerNum, &m_wMinorVerNum); return DispEventAdvise(pUnk, &m_iid); } HRESULT Unadvise(IUnknown* pUnk) { AtlGetObjectSourceInterface(pUnk, &m_libid, &m_iid, &m_wMajorVerNum, &m_wMinorVerNum); return DispEventUnadvise(pUnk, &m_iid); } ... };
Then, after you have established the connection with the server, you must advise your implementation of the event interface:
IVScriptEngine vscript_engine = NULL;
try { vscript_engine = vscript ->GetVScriptEngine( "Test_1" ); } catch (_com_error& er ) { SetStatusError( er ); }
if ( vscript_engine == NULL ) { vscript = NULL; return E_FAIL; }
CVSEngineSink vse_sink; HRESULT hr = vse_sink . Advise( vscript_engine ); // “Subscribe” for receiving events.
...
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 121
Teledyne LeCroy SASVScriptEngine Object Events
VS_RESULT res = SCRIPT_NOT_FOUND; try { res = (VS_RESULT)vscript_engine ->RunVScript(); } catch (_com_error& er) { SetStatusError( er ); }
// Tear connection with the test case. vse_sink.Unadvise( vscript_engine );
...VBA: ( MS Excel )
Public SASTracer As SASAnalyzer Public Trace As SASTrace Public GVSEngine As VScriptEngine
' VSEngineEventsModule is a special class implementing VSE event ' handlers. ' It should have, in the global declaration section, a line like this: ' Public WithEvents VSEEvents As VScriptEngine
Dim X As New VSEngineEventsModule
Private Sub RunVScritButton_Click()
Dim VSEngine As VScriptEngine Dim IVScript As ISASVerificationScript Dim ScriptName, fileToOpen As String
ScriptName = ThisWorkbook.Sheets("Sheet1").Cells(2, 2)
If SASTracer Is Nothing Then Set SASTracer = New SASAnalyzer
If SASTracer Is Nothing Then MsgBox "Unable to connect to SASTracer", vbExclamation Exit Sub End If End If
122 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASVScriptEngine Object Events Teledyne LeCroy
fileToOpen = ThisWorkbook.Sheets("Sheet1").Cells(1, 2) Set Trace = SASTracer.OpenFile( fileToOpen ) Set IVScript = Trace ' Get the IfcVerificationScript interface. Set VSEngine = IVScript.GetVScriptEngine( ScriptName )
' "Subscribe" for receiving VSE events.' The X variable (an instance of VSEngineEventsModule class) ' handles them.
Set X.VSEEvents = VSEngine
...
VSEngine.Tag = 12 ' Assign a tag for VSE object. VSEngine.RunVScript ' Run verification script.
Set X.VSEEvents = Nothing ' "Unsubscribe" for receiving VSE events.
Set VSEngine = Nothing ' Release external Set IVScript = Nothing ' objects.
End Sub
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 123
Teledyne LeCroy SASVScriptEngine Object Events
IVScriptEngineEvents::OnVScriptReportUpdatedHRESULT OnVScriptReportUpdated ( [in] BSTR newline, [in] int tag )
Fires when running a verification script. Calls the ReportText(newLine) function (refer to the SASTracer Verification Script Engine Manual for details on the ReportText function).
Parameters
newline New portion of text reported by the verification script
tag VSE object tag
Return Value
Remarks
Make sure that C++ event handlers have the __stdcall calling convention.
Example
C++:
HRESULT __stdcall OnVScriptReportUpdated (BSTR newLine, int TAG ) { TRACE( "Line: %s, TAG: %d\n", newLine, TAG );
. . .
return S_OK; }
VBA (MS Excel): Public WithEvents VSEEvents As VScriptEngine Public LineIndex As Integer
. . .
Private Sub VSEEvents_OnVScriptReportUpdated(ByVal newLine As String, ByVal Tag As Long)
ThisWorkbook.Sheets("Sheet1").Cells(LineIndex, 1) = newLine LineIndex = LineIndex + 1 End Sub
124 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASVScriptEngine Object Events Teledyne LeCroy
IVScriptEngineEvents::OnVScriptFinishedHRESULT OnVScriptFinished ( [in] BSTR script_name, [in] VS_RESULT result, [in] int TAG )
Fires when running a verification script. Calls the ReportText(newLine) function (refer to the SASTracer Verification Script Engine Manual for details on the ReportText function).
Parameters
script_name Name of the verification script
result Result of "verification"
See the ISASVerificationScript::RunVerificationScript method for details.
TAG VSE object tag
Return Value
Remarks
Make sure that C++ event handlers have the __stdcall calling convention.
Example
C++:
HRESULT __stdcall CComplTestSink::OnVScriptFinished( BSTR script_name, VS_RESULT result, int TAG ) { USES_CONVERSION; TCHAR tmp[220]; sprintf( tmp, "Script completed, name : %s, result = %d, TAG = %d", W2A(script_name), result, TAG ); . . .
return S_OK; }
VBA (MS Excel): Public WithEvents VSEEvents As VScriptEngine . . .
Private Sub VSEEvents_OnVScriptFinished( ByVal script_name As String, ByVal result As SASAutomationLib.VS_RESULT, ByVal Tag As Long )
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 125
Teledyne LeCroy SASVScriptEngine Object Events
Dim ResString As String ResString = "Script name : " & script_name & ", result = " & CStr(result) & ", TAG = " & CStr(Tag)
ThisWorkbook.Sheets("Sheet1").Cells(7, 2) = ResString End Sub
126 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASVScriptEngine Object Events Teledyne LeCroy
IVScriptEngineEvents::OnNotifyCountHRESULT OnNotifyCount ( [in] int eventId, [in] VARIANT eventBody, [in] int TAG )
Fires when running a verification script. Calls the NotifyClient() function.
Parameters
eventID Event ID
eventBody Body of event packed in a VARIANT object
TAG VSE object tag
Return Value
Remarks
The information packed in the event body is opaque for VSE. It only packs the information given to the NotifyClient() function inside of a verification script into a VARIANT object and sends it to client applications.
See the SASTracer Verification Script Engine Manual for details about the NotifyClient() script function.
Example
SASTracer Verification script:
ProcessEvent() { . . .
NotifyClient( 2, [in.Index, in.Level, GetChannelName(),
GetEventName(), TimeToText( in.Time )] );
. . .
}
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 127
Teledyne LeCroy SASVScriptEngine Object Events
VBA (MS Excel):
Public WithEvents VSEEvents As VScriptEngine
. . . Private Sub VSEEvents_OnNotifyClient( ByVal eventId As Long, ByVal eventBody As Variant, ByVal Tag As Long ) Dim Col As Integer Dim Item As Variant
ThisWorkbook.Sheets("Sheet1").Cells(LineIndex, 1) = eventId
If IsArray(eventBody) Then Col = 3
For Each Item In eventBody ThisWorkbook.Sheets("Sheet1").Cells(LineIndex, Col) = Item Col = Col + 1 Next
Else ThisWorkbook.Sheets("Sheet1").Cells(LineIndex, 2) = eventBody
End If
LineIndex = LineIndex + 1
End Sub
128 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASAnalyzer Object Events Teledyne LeCroy
SASAnalyzer Object Events_ISASAnalyzerEvents Dispinterface
To retrieve the events from a SASAnalyzer object, you must implement the _ISASAnalyzerEvents interface. Since this interface is the default source interface for the SASAnalyzer object, there is a very simple implementation from languages such as Visual Basic, VBA, VBScript, and WSH.
Some script engines impose restrictions on handling events from “indirect” automation objects in typeless script languages (when the automation interface to the object is obtained from a call of some method, rather than from a creation function, such as CreateObject() in VBScript). The Teledyne LeCroy SAS/SATA Protocol Suite application provides a special COM class, allowing receiving and handling notifications from the VSE object even in script languages not supporting event handling from "indirect" objects.
The C++ implementation used in the examples below utilizes a sink object by deriving it from IdispEventImpl, but not specifying the type library as a template argument. Instead, the type library and default source interface for the object are determined using AtlGetObjectSourceInterface().
A SINK_ENTRY() macro is used for each event from each source interface that is to be handled:
class CAnalyzerSink : public IDispEventImpl<IDC_SRCOBJ, CAnalyzerSink>
{
BEGIN_SINK_MAP(CAnalyzerSink)
// Make sure the Event Handlers have __stdcall calling convention.
SINK_ENTRY(IDC_SRCOBJ, 1, OnTraceCreated)
SINK_ENTRY(IDC_SRCOBJ, 2, OnStatusReport)
END_SINK_MAP()
. . .
}
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 129
Teledyne LeCroy SASAnalyzer Object Events
Then, after you establish a connection with the server, you must advise as to your
implementation of the event interface:
hr = CoCreateInstance( CLSID_SASAnalyzer, NULL,
CLSCTX_SERVER, IID_ISASAnalyzer, (LPVOID *)&m_poSASAnalyzer );
poAnalyzerSink = new CAnalyzerSink();
// Make sure the COM object corresponding to pUnk implements
// IProvideClassInfo2 or IPersist*.
// Call this method to extract info about source type library, if you
// specified only two parameters to IDispEventImpl.
hr = AtlGetObjectSourceInterface(m_poSASAnalyzer, &poAnalyzerSink->m_libid,
&poAnalyzerSink->m_iid, &poAnalyzerSink->m_wMajorVerNum,
&poAnalyzerSink->m_wMinorVerNum);
if ( FAILED(hr) )
return 1;
// Connect the sink and source. m_poSASAnalyzer is the source COM object.
hr = poAnalyzerSink->DispEventAdvise(m_poSASAnalyzer, &poAnalyzerSink->m_iid);
if ( FAILED(hr) )
return 1;
130 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASAnalyzer Object Events Teledyne LeCroy
_ISASAnalyzerEvents::OnTraceCreated
HRESULT OnTraceCreated (
[in] IDispatch* trace );
Fires when a trace is created. This event is a result of ISASAnalyzer::StartRecording and ISASAnalyzer::StopRecording method calls.
Parameters
trace Interface pointer to the SASTrace object
Return Value
Remarks
Make sure the event handlers have the __stdcall calling convention.
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 131
Teledyne LeCroy SASAnalyzer Object Events
Example
VBScript:<OBJECT ID = Analyzer CLASSID = " clsid: 297CD804-08F5-4A4F-B3BA-779B2654B27C " ></OBJECT><P ALIGN=LEFT ID=StatusText></P><SCRIPT LANGUAGE="VBScript"><!--Dim CurrentTraceSub Analyzer_OnTraceCreated(ByRef Trace)On Error Resume NextSet CurrentTrace = TraceIf Err.Number <> 0 Then MsgBox Err.Number & ":" & Err.DescriptionEnd If StatusText.innerText = "Trace '" & CurrentTrace.GetName & "' created"End Sub--></SCRIPT>
C++:HRESULT __stdcall OnTraceCreated( IDispatch* trace ){ISASTrace* sas_trace;HRESULT hr;hr = trace->QueryInterface( IID_ISASTrace, (void**)&sas_trace );if (FAILED(hr)) { _com_error er(hr); if (er.Description().length() > 0) ::MessageBox( NULL, er.Description(), _T("SASTracer client"), MB_OK ); else ::MessageBox( NULL, er.ErrorMessage(),_T("SASTracer client"), MB_OK ); return hr; } . . . return hr;}
132 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASAnalyzer Object Events Teledyne LeCroy
_ISASAnalyzerEvents::OnStatusReportHRESULT OnStatusReport (
[in] short subsystem, [in] short state, [in] long percent_done );
Fires when there is a change in analyzer state or there is a change in progress (percent_done) of analyzer state.
Parameters
subsystem Subsystem sending event has the following values
RECORDING_PROGRESS_REPORT ( 1 ) Recording subsystem
GENERATION_PROGRESS_REPORT ( 2 ) Generation subsystem
\state Current analyzer state has the following values:
If the subsystem is RECORDING_PROGRESS_REPORT:
ANALYZERSTATE_IDLE (-1 ) = idle
ANALYZERSTATE_WAITING_TRIGGER ( 0 )= recording in progress, analyzer waiting for trigger
ANALYZERSTATE_RECORDING_TRIGGERED ( 1 ) = recording in progress, analyzer triggered
ANALYZERSTATE_UPLOADING_DATA ( 2 ) = uploading in progress
ANALYZERSTATE_SAVING_DATA ( 3 ) = saving data in progress
If the subsystem is GENERATION_PROGRESS_REPORT:
ANALYZERSTATE_GEN_IDLE ( 400 ) = idle
ANALYZERSTATE_GEN_DOWNLOADING ( 401 ) = generator is downloading object code
ANALYZERSTATE_GEN_GENERATING ( 402 ) = generator is working
ANALYZERSTATE_GEN_PAUSED ( 403 ) = generator is paused
percent_done Shows the progress of currently performing operation:
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 133
Teledyne LeCroy SASAnalyzer Object Events
If the subsystem is RECORDING_PROGRESS_REPORT:
When analyzer state is ANALYZERSTATE_IDLE, is not applicable. When analyzer state is ANALYZERSTATE_WAITING_TRIGGER or ANALYZER‐
STATE_RECORDING_TRIGGERED, shows analyzer memory utilization. When analyzer state is ANALYZERSTATE_UPLOADING_DATA, shows the percent
of data uploaded. When analyzer state is ANALYZERSTATE_SAVING_DATA, shows the percent of
data saved.
If the subsystem is GENERATION_PROGRESS_REPORT, represents current position of script execution.
Return Value
Remarks
Make sure the event handlers have the __stdcall calling convention.
Example
VBScript:
<OBJECT ID = Analyzer CLASSID = "clsid:0B179BB8-DC61-11D4-9B71-000102566088" ></OBJECT><P ALIGN=LEFT ID=StatusText></P>
<SCRIPT LANGUAGE="VBScript"><!--Function GetRecordingStatus(ByVal State, ByVal Percent)
Select Case State Case -1: GetRecordingStatus = "Idle" Case 0: GetRecordingStatus = "Recording - Waiting for trigger" Case 1: GetRecordingStatus = "Recording - Triggered" Case 2: GetRecordingStatus = "Uploading" Case 3: GetRecordingStatus = "Saving Data" Case Else: GetRecordingStatus = "Invalid recording status" End Select GetRecordingStatus = GetRecordingStatus & ", " & Percent & "% done" End Function
134 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASAnalyzer Object Events Teledyne LeCroy
Dim RecordingStatus Sub Analyzer_OnStatusReport(ByVal System, ByVal State, ByVal Percent) Select Case System Case 1 RecordingStatus = GetRecordingStatus( State, Percent ) End Select End Sub--></SCRIPT>
C++:#define RECORDING_PROGRESS_REPORT ( 1 )#define ANALYZERSTATE_IDLE( -1 )#define ANALYZERSTATE_WAITING_TRIGGER( 0 )#define ANALYZERSTATE_RECORDING_TRIGGERED( 1 )#define ANALYZERSTATE_UPLOADING_DATA( 2 )#define ANALYZERSTATE_SAVING_DATA( 3 )
HRESULT __stdcall OnStatusReport(short subsystem, short state, long percent_done){switch ( subsystem ) { case RECORDING_PROGRESS_REPORT: UpdateRecStatus( state, percent_done ); break; }
TCHAR buf[1024]; _stprintf( buf, _T("%s"), m_RecordingStatus ); ::SetWindowText( m_hwndStatus, buf );
return S_OK; }
void UpdateRecStatus( short state, long percent_done ) { TCHAR status_buf[64]; switch ( state ) { case ANALYZERSTATE_IDLE: _tcscpy( status_buf, _T("Idle") ); break; case ANALYZERSTATE_WAITING_TRIGGER:
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 135
Teledyne LeCroy SASAnalyzer Object Events
_tcscpy( status_buf, _T("Recording - Waiting for trigger") ); break; case ANALYZERSTATE_RECORDING_TRIGGERED: _tcscpy( status_buf, _T("Recording - Triggered") ); break; case ANALYZERSTATE_UPLOADING_DATA: _tcscpy( status_buf, _T("Uploading") ); break; case ANALYZERSTATE_SAVING_DATA: _tcscpy( status_buf, _T("Saving data") ); break; default: _tcscpy( status_buf, _T("Unknown") ); break; } _stprintf(m_RecordingStatus, _T("%s, done %ld%%"), status_buf, percent_done);}
136 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASVerification API Teledyne LeCroy
SASVerification API
The SASVerification API allows you to write scripts to automate SASVerification tests and generate the results in a RTF files.
Steps
Following are the steps (example w.r.t vbs) to be followed in order to run SASVerification API:
1. Create a SASVerification object using the CreateObject function.
Set SASVerificationObj = WScript.CreateObject("LECROY.SASVerification")
2. Connect to a board using the Attach method.
SASVerificationObj.Attach( 2, “040000104C00F4DA”)
3. Initialize the SASVerification, using the initialize method.
SASVerificationObj.Initialize( ReportFileName, DeviceName, TracesPath, 0)
4. Add the test(s), using AddTest method.
SASVerificationObj.AddTest( 0 )SASVerificationObj.AddTest( 1 )
5. Finally, Run the SASVerification, using the method RunSASVerification
SASVerificationObj.RunSASVerification()
6. Once done, simply detach the boards using detach method.
SASVerificationObj.Detach()
Note: Note: A complete example can be found in the downloaded example folder. (C:\Users\Public\Documents\LeCroy\SAS SATA Protocol Suite\APIExamples\SAS Verification)
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 137
Teledyne LeCroy SASVerification API methods
SASVerification API methods
Attach( BYTE yDefaultPort, BSTR bstrDeviceId)
This method can be use to connect to the board. It returns the error‐code if there is an error.
Parameters
yDefaultPort
It specifies the port type of the board to be connected to. Possible values are
0x02 : USB
0x04 : TCP
bstrDeviceId
It specifies the full board‐ID. The first four characters specify the port type
and the following characters specify the actual board ID. For example, for the
board‐ID “00104CC47777”, use “020000104CC47777” if connected via USB
and “040000104CC47777” if connected via TCP.
Detach( int* pnErrorCode)
This method simply disconnects all the board(s). It returns the error‐code if there is an error.
Initialize ( BSTR bstrRTFName, BSTR bstrDeviceName, BSTR bstrTracesPath, BOOL bSaveOnlyFailed)
This method must be called in order to initialize the SASVerification before running. It returns the error‐code if there is an error.
Parameters
bstrRTFName
It specifies the RTF file name as a string. This RTF file contains the
results of the tests, which would get saved near the trace files.
bstrDeviceName
It is the name of the device under test.
bstrTracesPath
It specifies the path for all trace files.
bSaveOnlyFailed
It specifies whether to save only the failed traces or not.
138 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASVerification API methods Teledyne LeCroy
TRUE : Save only failed test traces.
FALSE : Save all traces.
AddTest( int nTestID)
This method adds a test to be run. Returns false if the test was not able to add true otherwise.
Parameter
nTestID
It specifies the Id of the test to be added. A list of available tests IDs are
defined at the end of this section.
RunSASVerification()
This function runs all the test(s) that have been added, and generates the results. Returns true if the run was successful, false otherwise.
SASVerification Test Ids
Test 5.7.1.1 = 0
Test 5.7.1.2 = 1
Test 5.7.1.3 = 2
Test 5.7.1.4 = 3
Test 5.7.1.5 = 4
Test 5.7.1.6 = 5
Test 5.7.1.7 = 6
Test 5.7.1.8 = 7
Test 5.7.1.9 = 8
Test 5.7.1.10 = 9
Test 5.7.1.11 = 10
Test 5.7.1.12 = 11
Test 5.7.1.13 = 12
Test 5.7.1.14 = 13
Test 5.7.1.15 = 14
Test 5.7.1.16 = 15
Test 5.7.1.17 = 16
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 139
Teledyne LeCroy SASVerification API methods
Test 5.7.2.1 = 17
Test 5.7.2.2 = 18
Test 5.7.2.3 = 19
Test 5.7.2.4 = 20
Test 6.1.1 = 21
Test 6.1.2 = 22
Test 6.1.3 = 23
Test 6.1.4 = 24
Test 6.1.5 = 25
Test 6.1.6 = 26
Test 6.1.7 = 27
Test 6.1.8 = 28
Test 6.1.10 = 29
Test 6.1.11 = 30
Test 6.1.12 = 31
Test 6.1.13 = 32
Test 6.1.14 = 33
Test 6.1.15 = 34
Test 6.1.16 = 35
Test 6.1.17 = 36
Test 6.1.18 = 37
Test 6.1.19 = 38
Test 6.1.20 = 39
Test 6.1.21 = 40
Test 8.1.1 = 41
Test 8.1.2 = 42
Test 8.1.3 = 43
Test 8.1.4 = 44
Test 8.1.5 = 45
Test 8.1.6 = 46
Test 8.1.7 = 47
Test 8.1.8 = 48
140 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
SASVerification API methods Teledyne LeCroy
Test 8.1.9 = 49
Test 8.1.10 = 50
Test 8.1.11 = 51
Test 8.1.13 = 52
Test 8.1.14 = 53
Test 8.1.15 = 54
Test 8.1.16 = 55
Test 8.1.17 = 56
Test 8.1.18 = 57
Test 8.1.19 = 58
Test 8.1.20 = 59
Test 10.1.1 = 60
Test 10.1.2 = 61
Test 10.1.3 = 62
Test 10.1.4 = 63
Test 10.1.5 = 64
Test 10.1.6 = 65
Test 10.1.7 = 66
Test 10.1.8 = 67
Test 10.1.9 = 68
Test 10.2.1 = 69
NACA Test 1 = 70
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 141
Teledyne LeCroy STCompliance API
STCompliance API
The STCompliance API allows you to write VB scripts to automate compliance tests and generate results as RTF files.
VB Script
To run a test using an STCompliance API VB script:
1. Create an STCompliance object using the CreateObject function:
Set ComplianceObject = CreateObject("LECROY.STCompliance")
2. To attach to the board, use the Attach function to specify connection type, board ID, and installed‐software path:
nErrorCode = ComplianceObject.Attach(2,"020000104CC47777","...\ ATA_Protocol_Suite_3.90.336 \")
For USB connection, use 2 as the first parameter, as in the above example.
For TCP connection, use 4 as the first parameter.
The Board ID (second parameter) combines two numbers. The first four digits
specify USB or TCP connection, and other number specifies the actual Board ID.
For USB connection, use 0200 as the first four digits, as in the above example.
For TCP connection, use 0400 as the first four digits.
The last parameter is the "system" folder of your software.
3. To add tests, use the AddTest command to specify test IDs:
bRetVal = ComplianceObject.AddTest(TEST_GDR_01)bRetVal = ComplianceObject.AddTest(TEST_GDR_02)...
A list of available tests and their IDs is in
ComplianceTestsEnum at the end of this section.
4. To run the tests, call the RunCompliance function:
bRetVal = ComplianceObject.RunCompliance()
5. To detach from board after the STCompliance run finishes, call the Detach function:
nErrorCode = ComplianceObject.Detach()
142 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
STCompliance API Methods Teledyne LeCroy
STCompliance API Methods
Attach
This function connects to the board.
Attach(BYTE yDefaultPort, BSTR bstrDeviceId, BSTR bstrSystemPath, int* pnErrorCode)
yDefaultPort: Specifies the connection mode. Possible values are:
0x02 = USBconnection
0x04 = TCP connection
bstrDeviceId: Specifies the board ID. The first four characters specify the connection type and the following characters specify the actual board ID. For example, for board ID = 00104CC47777, use 020000104CC47777 for USB connection and 040000104CC47777 for TCP connection.
bstrSystemPath: Shows the path of installed software.
pnErrorCode: Returns the error code if there is an error.
Detach
This function disconnects from the board.
Detach (int* pnErrorCode);
pnErrorCode: Returns the error code if there is an error.
Initialize
This function changes STCompliance settings. If this function is not called, the system uses the default settings. To change settings, call this function only after attaching to the board.
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 143
Teledyne LeCroy STCompliance API Methods
Initialize (BOOL bDeviceIsATAPI, BOOL bUTDIs14, BSTR bstrRTFName, BSTR bstrDeviceName, BOOL bIsSSDDrive, BSTR bstrComplianceTracesPath, BOOL bSaveOnlyFailed, BOOL* pbRetVal)
bDeviceIsATAPI: Specifies the device type as a boolean:
TRUE = ATAPA device (default)
FALSE = ATA device
bUTDIs14: Indicates the UTD version:
TRUE = UTD 1.4 specification (default)
FALSE = UTD 1.3 specification
bstrRTFName: Specifies the RTF file name as a string. This RTF file contains the results.
Default is system path.
bstrDeviceName: Is the device name. Default is device ID.
bIsSSDDrive: Specifies whether the device is an SSD drive (default) or not.
bstrComplianceTracesPath: Specifies the path for all trace files and the RTF file.
Default is system path.
144 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
STCompliance API Methods Teledyne LeCroy
bSaveOnlyFailed: Specifes whether to save failed traces or not:
TRUE = save only failed test traces (default)
FALSE = do not save failed traces
pbRetVal: Is the return value of the function.
AddTest
This function adds compliance tests.
AddTest (int nTestID, BOOL* pbRetVal)
nTestID: Is the test ID. A list of available tests and their IDs is in
ComplianceTestsEnum at the end of this section.
pbRetVal: Is the return value of the function.
RunCompliance
This function runs STCompliance and generates results.
RunCompliance (BOOL* pbRetVal);
pbRetVal: Is the return value of the function.
ChangeGTR03Params
This function changes the settings of the GTR‐03 test. If you do not call this function, the system uses the default settings.
ChangeGTR03Params (BSTR bstrGTR03AddressRange, int nATAPIMediaType, DWORD dwTrackSize, int nLogicalBlockSize, BOOL* pbRetVal)
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 145
Teledyne LeCroy STCompliance API Methods
bstrGTR03AddressRange: Specifies the Logical Block Address of the device for WRITE/READ DMA commands. The system issues a pair of WRITE/READ DMA commands with 4 KB payload for five iterations, incrementing the LBA by 4 KB, and another pair of WRITE/READ DMA commands with 16 KB payload for five iterations, incrementing the LBA by 16 KB.
nATAPIMediaType: Applies only to ATAPI devices and specifies the media type that ATAPI devices have inside. Default value is MEDIA_TYPE_READ_ONLY. A list of the possible values for this parameter is at the end of this section in ATAPIMediaTypeEnum.
nLogicalBlockSize: Applies only to ATAPI devices and calculates Transfer Length for Read(10) or Read CD commands. The system executes the test twice, first with minimum transfer length equal to 1 (2 KB) and again with transfer length equal to 16384 / nLogicalBlockSize (16 KB).
pbRetVal: Is the return value of the function.
ChangeNCQ01Params
This function changes the settings of the NCQ‐01 test. If you do not call this function, the system uses the default settings.
ChangeNCQ01AddressRange(BSTR bstrNCQ01AddressRange, BOOL* pbRetVal);
bstrNCQ01AddressRange: Specifies the Logical Block Address of the device for READ/WRITE FPDMA QUEUED commands. The default value is "000000000000".
pbRetVal: Is the return value of the function.
ChangeNCQ03Params
This function changes the settings of the NCQ‐03 test. If you do not call this function, the system uses the default settings.
ChangeNCQ03Params (CommandTypeEnum ePIOCommand, CommandTypeEnum eDMACommand, BOOL* pbRetVal);
146 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
STCompliance API Methods Teledyne LeCroy
ePIOCommand: Specifies the PIO OUT command to issue to the device. The default command is WRITE_SECTOR_S. A list of the available values for this parameter is at the end of this section.
eDMACommand: Specifies the DMA IN command to issue to the device. The default value is READ_DMA. A list of the available values for this parameter is at the end of this section.
pbRetVal: Is the return value of the function.
ComplianceTestsEnum
enum ComplianceTestsEnum{
TEST_GDR_01 = 0,
TEST_GDR_02,
TEST_GDR_03,
TEST_GDR_04,
TEST_GDR_05,
TEST_NCQ_01,
TEST_NCQ_02,
TEST_NCQ_03,
TEST_NCQ_04,
TEST_NCQ_05,
TEST_ASR_01,
TEST_ASR_02,
TEST_ASR_03,
TEST_SSP_01,
TEST_SSP_02,
TEST_SSP_03,
TEST_SSP_04,
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 147
Teledyne LeCroy STCompliance API Methods
TEST_SSP_05,
TEST_SSP_06,
TEST_SSP_07,
TEST_SSP_08,
TEST_SSP_09,
TEST_SSP_10,
TEST_SSP_11,
TEST_SSP_12,
TEST_IPM_01,
TEST_IPM_02,
TEST_IPM_03,
TEST_IPM_04,
TEST_IPM_05,
TEST_IPM_06,
TEST_IPM_07,
TEST_IPM_08,
TEST_IPM_09,
TEST_IPM_10,
TEST_IPM_11,
TEST_DOF_01,
TEST_DOF_02,
TEST_OOB_03,
TEST_OOB_04,
TEST_OOB_05,
TEST_OOB_06,
TEST_OOB_07,
};
148 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
STCompliance API Methods Teledyne LeCroy
ATAPIMediaTypeEnum
enum ATAPIMediaTypeEnum{
MEDIA_TYPE_READ_ONLY = 0 ,
MEDIA_TYPE_RE_WRITABLE,
MEDIA_TYPE_WRITABLE
};
PIO OUT Commands List
The available values for the ePIOCommand parameter are:
CFA_WRITE_MULTIPLE_W_OUT_ERASE = 0xCD00,
CFA_WRITE_SECTORS_W_OUT_ERASE = 0x3800,
DEVICE_CONFIGURATION_SET = 0xB1C3,
DOWNLOAD_MICROCODE = 0x9200,
SECURITY_DISABLE_PASSWORD = 0xF600,
SECURITY_ERASE_UNIT = 0xF400,
SECURITY_SET_PASSWORD = 0xF100,
SECURITY_UNLOCK = 0xF200,
SET_MAX_SET_PASSWORD = 0xF901,
SET_MAX_UNLOCK = 0xF903,
TRUSTED_SEND = 0x5E00,
WRITE_BUFFER = 0xE800,
WRITE_LOG_EXT = 0x3F00,
WRITE_MULTIPLE = 0xC500,
WRITE_MULTIPLE_EXT = 0x3900,
WRITE_MULTIPLE_FUA_EXT = 0xCE00,
WRITE_MULTIPLE_C3 = 0xC300,
WRITE_PORT_MULTIPLIER = 0xE8FF,
WRITE_SECTOR_S = 0x3000,
WRITE_SECTOR_S_EXT = 0x3400,
WRITE_STREAM_PIO = 0x3B00,
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 149
Teledyne LeCroy STCompliance API Methods
DMA IN Commands List
The available values for the eDMACommand parameter are:
READ_DMA = 0xC800,
READ_DMA_EXT = 0x2500,
READ_DMA_QUEUED = 0xC700,
READ_STREAM_DMA = 0x2A00,
150 Automation API for Teledyne LeCroy SAS/SATA Protocol Suite
How to Contact Teledyne LeCroy Teledyne LeCroy
How to Contact Teledyne LeCroy
Type of Service ContractCall for technical support… US and Canada:1 (800) 909‐7112
Worldwide: 1 (408) 653‐1260 Fax your questions… Worldwide:1 (408) 727‐6622Write a letter … Teledyne LeCroy
Protocol Solutions Group
Customer Support
3385 Scott Blvd.
Santa Clara, CA 95054‐3115
USASend e‐mail… [email protected] Teledyne LeCroy’s web site… teledynelecroy.com/
Automation API for Teledyne LeCroy SAS/SATA Protocol Suite 151