Teledyne Sierra SAS-SATA User Manual

Sierra SAS/SATA Protocol

Analyzer

SAS/SATA Protocol Suite

STX Software

API Reference Manual

Software Version 5.10

Document Version 3.94

November 2012

Teledyne LeCroy Protocol Solutions Group

Trademarks and Servicemarks:

Teledyne LeCroy, Sierra M6-4, Sierra M6-2, STX A6-4, Sierra M6-1.

Microsoft and Windows are registered trademarks of Microsoft Corporation.

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 LeCroy FOR A COPY.

Teledyne LeCroy © 2012. All rights reserved.

This document may be printed and reporduced without additional permission, but all copies
should contain this copyright notice.

WEEE Program

Teledyne LeCroy

3385 Scott Blvd.

Santa Clara, CA 95054

TEL: [phone] (USA and Canada)

TEL: [phone]

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

API Description 2

Contents

Introduction ................................................................................................................ 29

API Description ................................................................................................ 29

COM Interfaces Supported ....................................................................... 31

Constants .................................................................................................. 32

Parameters ................................................................................................ 35

API Errors .................................................................................................. 35

How to Use the API .............................................................................................................. 36

Setup your API Application ............................................................................. 36

Initialize Your Application ............................................................................... 37

Set a valid path for the output file of your application ............................ 38

Declare two required objects in main class of your application .............. 38

Create Instances of the two objects just declared in the

main class of your application .................................................................. 39

Finalize initialization by calling “InitializeSystem ()”................................. 40

Connecting to the Board ................................................................................. 40

How to Set/Initialize Connection Points ......................................................... 44

Using Analyzer API .......................................................................................... 46

Initialize a Capture Project Object ............................................................ 47

Create a New Analyzer Capture Project ................................................... 47

Run an Analyzer Capture Project .............................................................. 49

Stop an Analyzer Capture Project ............................................................. 51

Upload and create sample file .................................................................. 52

Open a Saved Capture Project .................................................................. 55

Modifying an Existing Analyzer Project .................................................... 56

Set Trigger Mode/Strategy ...................................................................................................... 56

Add a Trigger Pattern............................................................................................................... 57

Remove a Trigger Pattern ........................................................................................................ 61

Set Capture Mode/ Strategy .................................................................................................... 62

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

API Description 3

Add a Capture Pattern ............................................................................................................. 63

Remove a Capture Pattern ...................................................................................................... 66

Exclude/Include Specific Pattern Items ................................................................................... 66

Set Memory Usage Parameters ............................................................................................... 68

Set Output Sample File Path .................................................................................................... 70

Set Port Configuration ............................................................................................................. 71

Summary ................................................................................................... 72

Using Initiator/Host Emulator API Functions .................................................. 73

Initialize an Initiator Capture Project Object ............................................ 74

Create a New Initiator Capture Project .................................................... 74

Run, Stop and Create-Sample for an Initiator Capture Project ................ 75

Open a Saved Initiator Capture Project .................................................... 77

Modify an Initiator Capture Project .......................................................... 78

Add/ Insert a packet in Initiator ............................................................................................... 79

Add/ Insert Events in Initiator.................................................................................................. 81

Add/ Insert an Instruction in Initiator ...................................................................................... 83

Remove/Delete an Inserted Packet ......................................................................................... 84

Remove/Delete an Inserted Event/Instruction ........................................................................ 84

Error Injection on Packets in Initiator ...................................................................................... 85

Summary ................................................................................................... 97

Using Target/Device Emulator API Functions ............................................... 100

Initialize and Create a New Target Emulator Object .............................. 100

Open a Saved Target Emulator ............................................................... 101

Modify an Existing Target Emulator Project ........................................... 101

Modify Pages ......................................................................................................................... 101

Error Injection on Packets of Target Emulator....................................................................... 103

Summary ................................................................................................. 133

Using Trainer ................................................................................................. 139

Create and Setup your API Application................................................... 139

Initialize your API Application ................................................................. 140

Set a valid path for the output file of your application .......................................................... 140

Declare required objects in main class of your application ................................................... 141

Create Instances of the two objects just declared in the main class of your application ...... 141

Finalize the Initialization by calling “InitializeSystem ()”........................................................ 142

Connecting to the Board ......................................................................... 143

Start Trainer ............................................................................................ 144

Stop/ Resume Trainer ............................................................................. 146

Summary ................................................................................................. 147

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

API Description 4

How to Navigate through Trace File ............................................................. 148

Load a Trace File and Build View ............................................................ 148

Load a Trace File .................................................................................................................... 148

Build View for Packet Navigation ........................................................................................... 148

Navigate through Trace File .................................................................... 149

Extraction of Packet Information ........................................................................................... 149

Navigate through Packets ...................................................................................................... 152

Filter Packets ........................................................................................... 153

Set Filter Data ........................................................................................................................ 153

Apply Filter ............................................................................................................................ 157

Search/ Find Packets ............................................................................... 157

Summary ................................................................................................. 158

Using CATC API .............................................................................................. 160

Create an SASAnalyzer Object ................................................................ 160

Call the Attach Function .......................................................................... 160

Using Infusion API ......................................................................................... 161

Initialize Sierra Infusion and Connect to Board ...................................... 161

Create a Callback class which inherits from CINFAPINotificationCallback class ........................ 161

Create an object from Callback class and initialize it ............................................................. 162

Initialize the Infusion Library ................................................................................................. 162

Get main objects from Infusion library to work with them ................................................... 162

Get connected devices list ..................................................................................................... 163

Call ConnectFromAPI function to connect to a specified board ............................................ 164

Disconnect from the board .................................................................................................... 168

Run and Stop Scenario ............................................................................ 168

Set port configuration in Infusion .......................................................................................... 168

Specify scenario ..................................................................................................................... 170

StartSession ........................................................................................................................... 170

StopSession ............................................................................................................................ 170

SATA Protocol Suite Device Emulator API Functions ............................... 171

Enabling smart feature set ...................................................................... 171

Enabling Smart Self Test ......................................................................... 171

Enabling Error Logging ............................................................................ 172

Enabling READ DATA returns user data ................................................................................. 172

STCompliance API ......................................................................................... 172

VB Script ................................................................................................................................ 172

STCompliance API Methods .................................................................... 173

Attach .................................................................................................................................... 173

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

API Description 5

Detach ................................................................................................................................... 173

Initialize ................................................................................................................................. 174

AddTest .................................................................................................................................. 175

RunCompliance ...................................................................................................................... 175

ChangeGTR03Params ............................................................................................................ 175

ChangeNCQ01Params ............................................................................................................ 176

ChangeNCQ03Params ............................................................................................................ 176

ComplianceTestsEnum ............................................................................ 176

ATAPIMediaTypeEnum ........................................................................... 178

PIO OUT Commands List ......................................................................... 178

DMA IN Commands List .......................................................................... 179

Register DLLs and Setup ..................................................................................................... 180

Visual C++ ...................................................................................................... 180

Import 1 .................................................................................................. 180

Import 2 .................................................................................................. 181

APIHeader.h ............................................................................................ 181

Visual Basic .................................................................................................... 181

Import ..................................................................................................... 181

Project ..................................................................................................... 181

Creating SAS Objects .......................................................................................................... 182

Creating SAS Objects in Trainer Mode .......................................................... 182

Interfaces .............................................................................................................. 183

ISASAPISrvs.................................................................................................... 183

Methods .................................................................................................. 183

HelloAutomation ................................................................................................................... 184

GetSASGeneralServicePtr ...................................................................................................... 184

GetSerialSCSICaptureProjectPtr ............................................................................................ 185

GetSerialSCSIExtractionPtr .................................................................................................... 185

GetTargetEmulEnginePtr ....................................................................................................... 186

GetExerciserEnginePtr ........................................................................................................... 186

StartGeneration ..................................................................................................................... 187

StopGeneration ..................................................................................................................... 188

ResumeGeneration ................................................................................................................ 189

GetGenerationStatus ............................................................................................................. 190

ISerialSCSICaptureProject ............................................................................. 191

Methods .................................................................................................. 191

AddCapturePattern ................................................................................................................ 208

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

API Description 6

AddConditionExprPattern ...................................................................................................... 209

AddConditionExprtimerToken ............................................................................................... 211

AddState ................................................................................................................................ 212

CopyState .............................................................................................................................. 212

CopyPasteState ...................................................................................................................... 213

GetProjectType ...................................................................................................................... 214

GetATACommandCapturePatternLBAMode .......................................................................... 214

GetATACommandConditionExprPatternLBAMode ................................................................ 215

GetAvailableHWResource ...................................................................................................... 216

GetCaptureFISType ................................................................................................................ 217

GetCapturePatternCommandSpecType ................................................................................ 218

GetCapturePatternDataOffset ............................................................................................... 219

GetCapturePatternDirection ................................................................................................. 220

GetCapturePatternFilter ........................................................................................................ 221

GetCapturePatternFISDataOffset .......................................................................................... 222

GetCapturePatternId ............................................................................................................. 223

GetCapturePatternIndex ....................................................................................................... 224

GetCapturePatternName ....................................................................................................... 225

GetCapturePatternParameterOptionId ................................................................................. 226

GetCapturePatternParameterOptionName ........................................................................... 227

GetCapturePatternParameterValue ...................................................................................... 228

GetCapturePatternPrimitiveType .......................................................................................... 229

GetCapturePatternProtocolTypeProtocolType ...................................................................... 230

GetCapturePatternSCSICommandType ................................................................................. 231

GetCapturePatternSMPFunctionType ................................................................................... 232

GetCapturePatternSSPFrameType ......................................................................................... 233

GetCapturePatternType ........................................................................................................ 234

GetCaptureStrategy ............................................................................................................... 235

GetConditionCounter ............................................................................................................ 236

GetConditionExpressionTokenType ....................................................................................... 237

GetConditionExpressionType ................................................................................................ 238

GetConditionExprFISType ...................................................................................................... 239

GetConditionExprPatternATAPICommandType..................................................................... 240

GetConditionExprPatternATAPISpecType ............................................................................. 241

GetConditionExprPatternCommandSpecType....................................................................... 242

GetConditionExprPatternDataOffset ..................................................................................... 243

GetConditionExprPatternDirection ........................................................................................ 244

GetConditionExprPatternFISDataOffset ................................................................................ 245

GetConditionExprPatternId ................................................................................................... 246

GetConditionExprPatternIndex ............................................................................................. 247

GetConditionExprPatternName ............................................................................................. 248

GetConditionExprPatternParameterOptionId ....................................................................... 249

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

API Description 7

GetConditionExprPatternParameterOptionName ................................................................. 250

GetConditionExprPatternParameterValue ............................................................................ 251

GetConditionExprPatternPrimitiveType ................................................................................ 252

GetConditionExprPatternProtocolTypeProtocolType ............................................................ 253

GetConditionExprPatternSCSICommandType ....................................................................... 254

GetConditionExprPatternSMPFunctionType ......................................................................... 255

GetConditionExprPatternSSPFrameType ............................................................................... 256

GetConditionExprpatternType............................................................................................... 257

GetConditionExprTimerId ...................................................................................................... 258

GetConditionExternalSignalAction ........................................................................................ 259

GetConditionGotoActionStateIndex ...................................................................................... 260

GetConditionTriggerAction .................................................................................................... 261

GetDataCapturePatternProtocolType ................................................................................... 262

GetDataConditionExprPatternProtocolType ......................................................................... 263

GetEntireMemory .................................................................................................................. 263

GetExcludeALIGN ................................................................................................................... 264

GetExcludeCONT ................................................................................................................... 264

GetExcludeIdle ....................................................................................................................... 265

GetExcludeNOTIFY ................................................................................................................. 265

GetExcludeOOBSignals .......................................................................................................... 266

GetExcludePayloadOffset ...................................................................................................... 266

GetExcludeRRDY .................................................................................................................... 267

GetExcludeSYNC .................................................................................................................... 267

GetExcludeXXXX .................................................................................................................... 268

GetExerciserInterface ............................................................................................................ 268

GetExistStateId ...................................................................................................................... 269

GetLastErrorStateId ............................................................................................................... 269

GetNumberOfCapturePatterns .............................................................................................. 270

GetNumberOfCondition ........................................................................................................ 270

GetNumberOfConditionExprToken ....................................................................................... 271

GetNumberOfState ................................................................................................................ 271

GetPermittedPatternDirection .............................................................................................. 272

GetStateActionType ............................................................................................................... 273

GetStateId .............................................................................................................................. 274

GetStateIndex ........................................................................................................................ 274

GetSymbolPatternType ......................................................................................................... 275

GetTimerResolutionMode ..................................................................................................... 276

GetTimerValue ....................................................................................................................... 277

GetTriggerPatternNumOfMatch ............................................................................................ 278

GetTriggerStrategy ................................................................................................................ 278

GetTrunDataPayload ............................................................................................................. 279

GetVendorFISCapturePatternLength ..................................................................................... 280

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

API Description 8

GetVendorFISConditionExprPatternLength ........................................................................... 281

HasCapturePatternParameter ............................................................................................... 282

HasConditionExprPatternParameter ..................................................................................... 283

HasSameCaptureingAsState0 ................................................................................................ 284

InsertConditionExprPatternTokenAt ..................................................................................... 284

InsertConditionExprTimerTokenAt ........................................................................................ 286

IsProgrammedTimer .............................................................................................................. 287

IsTriggerSequentialMode....................................................................................................... 287

MoveTriggerPattern .............................................................................................................. 288

New ....................................................................................................................................... 288

Open ...................................................................................................................................... 289

PasteSpecialState .................................................................................................................. 290

PasteState .............................................................................................................................. 291

SetProjectType....................................................................................................................... 292

RemoveAssignedResource ..................................................................................................... 292

RemoveCapturePattern ......................................................................................................... 294

RemoveConditionExprPattern ............................................................................................... 295

RemoveState ......................................................................................................................... 296

Run ........................................................................................................................................ 296

Save ....................................................................................................................................... 297

SetAddressFrameCapturePattern .......................................................................................... 298

SetAddressFrameConditionExprPattern ................................................................................ 299

SetATACommandCapturePattern .......................................................................................... 300

SetATACommandCapturePatternLBAMode .......................................................................... 301

SetATACommandConditionExprPattern ................................................................................ 302

SetATACommandConditionExprPatternLBAMode ................................................................ 303

SetCapturePatternDataOffset................................................................................................ 304

SetCapturePatternDirection .................................................................................................. 305

SetCapturePatternFilter ......................................................................................................... 306

SetCapturePatternFISDataOffset ........................................................................................... 307

SetCapturePatternParameterValue ....................................................................................... 308

SetCapturePatternParameterValueByOptionId ..................................................................... 309

SetCapturePatternSCSICommandType .................................................................................. 310

SetCaptureStrategy................................................................................................................ 311

SetConditionCounter ............................................................................................................. 312

SetConditionExprPatternATAPICommandType ..................................................................... 313

SetConditionExprPatternATAPISpecType .............................................................................. 314

SetConditionExprPatternDataOffset ...................................................................................... 315

SetConditionExprPatternDirection ........................................................................................ 316

SetConditionExprPatternFISDataOffset ................................................................................. 317

SetConditionExprPatternParameterLength ........................................................................... 318

SetConditionExprPatternParameterValue ............................................................................. 319

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

API Description 9

SetConditionExprPatternParameterValueByOptionId ........................................................... 320

SetConditionExprPatternSCSICommandType ........................................................................ 321

SetConditionExprTimerId ....................................................................................................... 322

SetConditionExternalSignalAction ......................................................................................... 323

SetConditionGotoActionStateIndex ....................................................................................... 324

SetConditionTriggerAction .................................................................................................... 325

SetDataCapturePattern ......................................................................................................... 326

SetDataConditionExprPattern ............................................................................................... 327

SetExcludeALIGN ................................................................................................................... 328

SetExcludeCONT .................................................................................................................... 329

SetExcludeIdle ....................................................................................................................... 330

SetExcludeNOTIFY.................................................................................................................. 331

SetExcludeOOBSignals ........................................................................................................... 332

SetExcludeRRDY ..................................................................................................................... 333

SetExcludeSYNC ..................................................................................................................... 334

SetExcludeXXXX ..................................................................................................................... 335

SetFISCapturePattern ............................................................................................................ 336

SetFISConditionExprPattern .................................................................................................. 337

SetPrimitiveTypeCapturePattern ........................................................................................... 338

SetPrimitiveTypeConditionExprPattern ................................................................................. 339

SetProgrammedTimer ........................................................................................................... 340

SetProtocolErrorCapturePattern ........................................................................................... 341

SetProtocolErrorConditionExprPattern ................................................................................. 342

SetSameCaptureingAsState0 ................................................................................................. 343

SetSCSICommandCapturePattern .......................................................................................... 344

SetSCSICommandConditionExprPattern ................................................................................ 345

SetSMPFrameCapturePattern ............................................................................................... 346

SetSMPFrameConditionExprPattern...................................................................................... 347

SetSSPFrameCapturePattern ................................................................................................. 348

SetSSPFrameConditionExprPattern ....................................................................................... 349

SetStateActionType ............................................................................................................... 350

SetSymbolPatternType .......................................................................................................... 351

SetTimerResolutionMode ...................................................................................................... 352

SetTimerValue ....................................................................................................................... 353

SetTriggerPatternNumOfMatch............................................................................................. 354

SetTriggerSequentialMode .................................................................................................... 355

SetTriggerStrategy ................................................................................................................. 356

SetTrunDataPayload .............................................................................................................. 357

SetVendorFISCapturePatternLength ..................................................................................... 358

SetVendorFISConditionExprPatternLength ............................................................................ 359

UpdateHardwareResource .................................................................................................... 360

SetDeviceType ....................................................................................................................... 361

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

API Description 10

GetDeviceType....................................................................................................................... 362

SetTahoeExternalTrigInType .................................................................................................. 362

GetTahoeExternalTrigInType ................................................................................................. 363

SetTahoeExternalTrigOutSetting ........................................................................................... 363

GetTahoeExternalTrigOutSetting ........................................................................................... 364

Properties ................................................................................................ 365

ISASGeneralService ....................................................................................... 367

Methods .................................................................................................. 367

Attach .................................................................................................................................... 369

Detach ................................................................................................................................... 370

GetLayerIndex........................................................................................................................ 370

GetLayerName ....................................................................................................................... 371

HalAnalyzerStop .................................................................................................................... 371

InitializeSystem ...................................................................................................................... 372

IsHWRunning ......................................................................................................................... 372

IsExerciserRunning ................................................................................................................. 373

IsHWTrigged .......................................................................................................................... 373

ShutdownSystem ................................................................................................................... 373

GetNumberOfAvailableATACommands ................................................................................. 374

GetATACommandAttribute ................................................................................................... 374

GetNumberOfAvailableBusCondition .................................................................................... 375

GetNumberOfAvailableFIS ..................................................................................................... 375

GetFISAttribute ...................................................................................................................... 376

GetNumberOfSupportedHWProtocolErrors .......................................................................... 376

GetSupportedHWProtocolError ............................................................................................ 377

GetSampleFileProperties ....................................................................................................... 378

GetPErrorAttribute ................................................................................................................ 379

GetNumberOfAvailableSCSICommandStatus ........................................................................ 379

GetSCSICommandStatusAttribute ......................................................................................... 380

GetNumberOfAvailablePErrors .............................................................................................. 380

GetNumberOfSupportedPortConfiguration .......................................................................... 381

GetSupportedPortConfiguration ........................................................................................... 382

SelectNetworkAdapter .......................................................................................................... 383

IExerciserEngine ............................................................................................ 384

Default Interface Methods ..................................................................... 384

AddProtocolErrorToPacket .................................................................................................... 395

AssignLable ............................................................................................................................ 396

ChangeLable .......................................................................................................................... 396

DeleteAll ................................................................................................................................ 397

DeleteInstruction ................................................................................................................... 397

DeletePacket .......................................................................................................................... 398

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

API Description 11

ExpandSATASelfTestInstructionField ..................................................................................... 399

GetEnablePatternGenerator .................................................................................................. 399

GetAffiliationType .................................................................................................................. 400

GetAutomaticAction .............................................................................................................. 401

GetAutoUpdateProperties ..................................................................................................... 402

GetDataInProperties .............................................................................................................. 403

GetDelayInstructionTime ....................................................................................................... 404

GetDelayInstructionTimeUnit ................................................................................................ 405

GetDestinationAddress .......................................................................................................... 406

GetEnableFirstBurst ............................................................................................................... 407

GetEnableRateMatching ........................................................................................................ 408

GetExternalTrig ...................................................................................................................... 409

GetFieldData .......................................................................................................................... 410

GetFieldDescription ............................................................................................................... 411

GetFieldID .............................................................................................................................. 412

GetFieldLength ...................................................................................................................... 413

GetFieldName ........................................................................................................................ 414

GetFieldOptionDescription .................................................................................................... 415

GetFieldStream ...................................................................................................................... 416

GetGoToInstructionLableId ................................................................................................... 417

GetIdentifyFrameTypeError ................................................................................................... 417

GetIfDeviceTypeInstrType ..................................................................................................... 418

GetIfInstructionCheckConditionAttr ...................................................................................... 419

GetIfInstructionCondition ...................................................................................................... 420

GetIfInstructionConditionDes ................................................................................................ 420

GetIfInstructionConditionProperties ..................................................................................... 421

GetIfInstructionLableId .......................................................................................................... 421

GetIfInstructionNumberOfCondition ..................................................................................... 422

GetIfLastFrameInstrDeviceType ............................................................................................ 422

GetIfLastFrameInstrFrameType ............................................................................................. 423

GetIfLastFrameInstrProtocolType .......................................................................................... 423

GetIfLastHandshakeInstrType ................................................................................................ 424

GetIfPayloadInstrData ........................................................................................................... 425

GetIfPayloadInstrLength ........................................................................................................ 426

GetIfPayloadInstrMatch......................................................................................................... 427

GetInstructionProerties ......................................................................................................... 428

GetInstructionType ................................................................................................................ 428

GetLableNote ......................................................................................................................... 429

GetLableProperties ................................................................................................................ 429

GetLogicalUnitNumber .......................................................................................................... 430

GetLoopInstructionCounter ................................................................................................... 431

GetLoopInstructionType ........................................................................................................ 431

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

API Description 12

GetNumberOfLables .............................................................................................................. 432

GetOOBInstrBurstTime .......................................................................................................... 432

GetOOBInstrCount ................................................................................................................. 433

GetOOBInstrIdleTime ............................................................................................................ 434

GetOOBInstrIgnore ................................................................................................................ 435

GetOOBInstrNegationTime .................................................................................................... 436

GetOOBInstrSATAPortSelectionT1 ......................................................................................... 436

GetOOBInstrSATAPortSelectionT2 ......................................................................................... 437

GetOOBInstructionSyncState................................................................................................. 437

GetOOBInstructionType ........................................................................................................ 438

GetPacketData ....................................................................................................................... 439

GetPacketIndex...................................................................................................................... 440

GetPacketLableProperties ..................................................................................................... 441

GetPacketProperties .............................................................................................................. 442

GetPacketRetryNumber......................................................................................................... 443

GetPrimitiveInstructionCount ................................................................................................ 444

GetPrimitiveInstructionType ................................................................................................. 444

GetPrimitiveInstructionValue ................................................................................................ 445

GetProtocolErrorNumberOfPacket ........................................................................................ 445

GetProtocolErrorOfPacket ..................................................................................................... 446

GetSATAPowMngInstructionType ......................................................................................... 446

GetSATASelfTestFieldDataToDBId ......................................................................................... 447

GetSATASelfTestInstructionFieldAbbr ................................................................................... 448

GetSATASelfTestInstructionFieldData ................................................................................... 449

GetSATASelfTestInstructionFieldDescription ......................................................................... 450

GetSATASelfTestInstructionFieldID........................................................................................ 450

GetSATASelfTestInstructionFieldLength ................................................................................ 451

GetSATASelfTestInstructionFieldName ................................................................................. 451

GetSATASelfTestInstructionFieldOptionDescription.............................................................. 452

GetSATASelfTestInstructionFieldStream ............................................................................... 453

GetSATASelfTestInstructionMaxFieldLength ......................................................................... 454

GetSATASelfTestInstructionMinFieldLength .......................................................................... 454

GetSATASelfTestInstructionProperties .................................................................................. 455

GetSATASoftResetInstructionPort ......................................................................................... 456

GetSATAWakeupInstructionOOBType ................................................................................... 456

GetSyntaxErrorLineNumber .................................................................................................. 457

GetTaskAttribute ................................................................................................................... 457

GetTotalPacketCount............................................................................................................. 458

GetTotalPacketInLayer .......................................................................................................... 458

GetTransportPacketProtocolType ......................................................................................... 459

GetTriggerSource ................................................................................................................... 459

GetWaitForHandshake .......................................................................................................... 460

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

API Description 13

GetWaitForInstructionLableId ............................................................................................... 460

GetWaitForInstructionTimeExpiration .................................................................................. 461

HasSpecifiedProtocolError ..................................................................................................... 462

InsertInstruction .................................................................................................................... 462

InsertPacket ........................................................................................................................... 463

InsertPacketByData ............................................................................................................... 464

IsReadCommand .................................................................................................................... 465

IsSATASelfTestDataPayloadField ........................................................................................... 465

IsSATASelfTestInstructionFieldExpandable ............................................................................ 466

IsSATASelfTestInstructionFieldExpanded .............................................................................. 466

IsWriteCommand ................................................................................................................... 467

SetEnablePatternGenerator .................................................................................................. 467

RemoveAllProtocolErrorOfPacket ......................................................................................... 468

RemoveLable ......................................................................................................................... 468

Reset ...................................................................................................................................... 469

SetAffiliationType .................................................................................................................. 469

SetAutomaticAction ............................................................................................................... 470

SetAutoUpdateProperties ..................................................................................................... 471

SetDataBlock .......................................................................................................................... 472

SetDataInProperties .............................................................................................................. 473

SetDelayInstructionTime ....................................................................................................... 474

SetDelayInstructionTimeUnit ................................................................................................ 474

SetDestinationAddress .......................................................................................................... 475

SetEnableFirstBurst ............................................................................................................... 476

SetEnableRateMatching ........................................................................................................ 477

SetExternalTrig ...................................................................................................................... 478

SetField .................................................................................................................................. 479

SetFieldByOption ................................................................................................................... 480

SetFieldData .......................................................................................................................... 481

SetFieldDataToDBId ............................................................................................................... 482

SetGoToInstructionLableId .................................................................................................... 483

SetIdentifyFrameTypeError ................................................................................................... 483

SetIfDeviceTypeInstrType ...................................................................................................... 484

SetIfInstructionCheckConditionAttr....................................................................................... 485

SetIfInstructionCondition ...................................................................................................... 486

SetIfInstructionLableId .......................................................................................................... 486

SetIfInstructionCondition ...................................................................................................... 487

SetIfLastFrameInstrDeviceType ............................................................................................. 488

SetIfLastFrameInstrFrameType .............................................................................................. 488

SetIfLastFrameInstrProtocolType .......................................................................................... 489

SetIfLastHandshakeInstrType ................................................................................................ 489

SetIfPayloadInstrData ............................................................................................................ 490

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

API Description 14

SetIfPayloadInstrLength ......................................................................................................... 491

SetIfPayloadInstrMatch ......................................................................................................... 492

SetLogicalUnitNumber ........................................................................................................... 493

SetLoopInstructionCounter ................................................................................................... 494

SetLoopInstructionType ......................................................................................................... 494

SetOOBInstrBurstTime ........................................................................................................... 495

SetOOBInstrCount ................................................................................................................. 496

SetOOBInstrIdleTime ............................................................................................................. 497

SetOOBInstrIgnore ................................................................................................................. 498

SetOOBInstrNegationTime .................................................................................................... 499

SetOOBInstrSATAPortSelectionT1 ......................................................................................... 499

SetOOBInstrSATAPortSelectionT2 ......................................................................................... 500

SetOOBInstructionSyncState ................................................................................................. 500

SetOOBInstructionType ......................................................................................................... 501

SetPacketRetryNumber ......................................................................................................... 502

SetPrimitiveInstructionCount ................................................................................................ 503

SetPrimitiveInstructionType .................................................................................................. 503

SetPrimitiveInstructionValue ................................................................................................. 504

SetSATAPowMngInstructionType .......................................................................................... 504

SetSATASelfTestFieldDataToDBId .......................................................................................... 505

SetSATASelfTestInstructionField ............................................................................................ 506

SetSATASelfTestInstructionFieldByOption ............................................................................. 506

SetSATASelfTestInstructionFieldData .................................................................................... 507

SetSATASoftResetInstructionPort .......................................................................................... 508

SetSATAWakeupInstructionOOBType ................................................................................... 509

SetTaskAttribute .................................................................................................................... 510

SetTriggerSource ................................................................................................................... 511

SetWaitForHandshake ........................................................................................................... 512

SetWaitForInstructionLableId ................................................................................................ 513

SetWaitForInstructionTimeExpiration ................................................................................... 514

SetCurrentProgramId............................................................................................................. 515

GetCurrentProgramId ............................................................................................................ 516

Properties ................................................................................................ 517

Error Injection Interface Methods .......................................................... 522

ErInjGetCodeViolationAndDisparityErrorAttribute ................................................................ 531

ErInjGetCodeViolationError ................................................................................................... 532

ErInjGetCodeViolationOnSATAPrimitive ................................................................................ 533

ErInjGetCRCError ................................................................................................................... 534

ErInjGetDelayResponseToHold .............................................................................................. 535

ErInjGetDisparityError ........................................................................................................... 536

ErInjGetDisparityErrorOnSATAPrimitive ................................................................................ 537

ErInjGetDonotCheckCredit .................................................................................................... 538

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

API Description 15

ErInjGetEOFError ................................................................................................................... 539

ErInjGetFillByteForReservedField .......................................................................................... 540

ErInjGetFrameErrorType ........................................................................................................ 541

ErInjGetFrameInvalidField ..................................................................................................... 542

ErInjGetFrameLengthError .................................................................................................... 543

ErInjGetHandshakeError ........................................................................................................ 544

ErInjGetIgnoreXRDYorRRDY ................................................................................................... 545

ErInjGetInsertedFrameAttribute............................................................................................ 546

ErInjGetInsertPrimitive .......................................................................................................... 547

ErInjGetInvalidFieldOfFrameAttribute ................................................................................... 548

ErInjGetNoWTRM .................................................................................................................. 549

ErInjGetNumberOfFieldsOfFrame ......................................................................................... 550

ErInjGetOmitFrameFromSequence ....................................................................................... 551

ErInjGetSendDelayToSendHandshake ................................................................................... 552

ErInjGetSendingFrameDelay .................................................................................................. 553

ErInjGetSOFError ................................................................................................................... 554

ErInjSetCodeViolationAndDisparityErrorAttribute ................................................................ 555

ErInjSetCodeViolationError .................................................................................................... 556

ErInjSetCodeViolationOnSATAPrimitive ................................................................................ 557

ErInjSetCRCError .................................................................................................................... 558

ErInjSetDelayResponseToHold .............................................................................................. 559

ErInjSetDisparityError ............................................................................................................ 560

ErInjSetDisparityErrorOnSATAPrimitive ................................................................................. 561

ErInjSetDonotCheckCredit ..................................................................................................... 562

ErInjSetEOFError .................................................................................................................... 563

ErInjSetFillByteForReservedField ........................................................................................... 564

ErInjSetFrameErrorType ........................................................................................................ 565

ErInjSetFrameInvalidField ...................................................................................................... 566

ErInjSetFrameLengthError ..................................................................................................... 567

ErInjSetHandshakeError ........................................................................................................ 568

ErInjSetIgnoreXRDYorRRDY ................................................................................................... 569

ErInjSetInsertedFrameAttribute ............................................................................................ 570

ErInjSetInsertPrimitive ........................................................................................................... 571

ErInjSetNoWTRM ................................................................................................................... 572

ErInjSetOmitFrameFromSequence ........................................................................................ 573

ErInjSetSendDelayToSendHandshake .................................................................................... 574

ErInjSetSendingFrameDelay .................................................................................................. 575

ErInjSetSOFError .................................................................................................................... 576

GetCloseBreakCount .............................................................................................................. 577

GetCloseDoneType ................................................................................................................ 578

GetCloseSequenseType ......................................................................................................... 579

GetIdentifyFrameCodeViolationAndDisparityErrorAttribute ................................................ 580

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

API Description 16

GetIdentifyFrameCodeViolationError .................................................................................... 581

GetIdentifyFrameCRCError .................................................................................................... 582

GetIdentifyFrameDisparityError ............................................................................................ 583

GetIdentifyFrameEOAFError .................................................................................................. 584

GetIdentifyFrameFrameLengthError ..................................................................................... 585

GetIdentifyFrameSOAFError .................................................................................................. 586

GetIncomingErrorAttribute ................................................................................................... 587

GetIncomingOpenResponse .................................................................................................. 588

GetOutGoingErrorAttribute ................................................................................................... 589

GetOutGoingErrorSMPFunction ............................................................................................ 590

GetOutGoingOpenFrameCodeVioaltionError ........................................................................ 591

GetOutGoingOpenFrameCodeViolationAndDisparityErrorAttribute ..................................... 592

GetOutGoingOpenFrameCRCError ........................................................................................ 593

GetOutGoingOpenFrameDisparityError ................................................................................ 594

GetOutGoingOpenFrameEOAFError ...................................................................................... 595

GetOutGoingOpenFrameFarmeLengthError ......................................................................... 596

GetOutGoingOpenFrameInvalidFields ................................................................................... 597

GetOutGoingOpenFrameSOAFError ...................................................................................... 598

GetOutGoingOpenFrameTypeError ....................................................................................... 599

GetRespondingCloseConnection ........................................................................................... 600

IsDefineCloseConnection ....................................................................................................... 601

IsDefineOutgoingOpenResponse ........................................................................................... 602

SetCloseBreakCount .............................................................................................................. 603

SetCloseDoneType ................................................................................................................. 604

SetCloseSequenseType .......................................................................................................... 605

SetDefineCloseConnection .................................................................................................... 606

SetDefineOutgoingOpenResponse ........................................................................................ 607

SetIdentifyFrameCodeViolationAndDisparityErrorAttribute ................................................. 608

SetIdentifyFrameCodeViolationError .................................................................................... 609

SetIdentifyFrameCRCError ..................................................................................................... 610

SetIdentifyFrameDisparityError ............................................................................................. 611

SetIdentifyFrameEOAFError .................................................................................................. 612

SetIdentifyFrameFrameLengthError ...................................................................................... 613

SetIdentifyFrameSOAFError .................................................................................................. 614

SetIncomingErrorAttribute .................................................................................................... 615

SetIncomingOpenResponse ................................................................................................... 616

SetOutGoingErrorAttribute ................................................................................................... 617

SetOutGoingErrorSMPFunction ............................................................................................. 618

SetOutGoingOpenFrameCodeVioaltionError ......................................................................... 619

SetOutGoingOpenFrameCodeViolationAndDisparityErrorAttribute ..................................... 620

SetOutGoingOpenFrameCRCError ......................................................................................... 621

SetOutGoingOpenFrameDisparityError ................................................................................. 622

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

API Description 17

SetOutGoingOpenFrameEOAFError....................................................................................... 623

SetOutGoingOpenFrameFarmeLengthError .......................................................................... 624

SetOutGoingOpenFrameInvalidFields.................................................................................... 625

SetOutGoingOpenFrameSOAFError ....................................................................................... 626

SetOutGoingOpenFrameTypeError ....................................................................................... 627

SetRespondingCloseConnection ............................................................................................ 628

ITargetEmulEngine ........................................................................................ 629

Methods .................................................................................................. 629

SetIdentifyDeviceFieldStream ............................................................................................... 632

GetIdentifyDeviceFieldStream ............................................................................................... 633

SetFieldStream....................................................................................................................... 634

GetFieldStream ...................................................................................................................... 635

SetFieldData .......................................................................................................................... 636

GetFieldData .......................................................................................................................... 637

ActiveDevice .......................................................................................................................... 637

GetATACapacity ..................................................................................................................... 638

GetCapacity ........................................................................................................................... 639

SetAsDefault .......................................................................................................................... 639

Save ....................................................................................................................................... 640

Load ....................................................................................................................................... 640

SetCOMINITNegationTime..................................................................................................... 641

GetCOMINITNegationTime .................................................................................................... 641

SetCOMINITBurstCount ......................................................................................................... 642

GetCOMINITBurstCount ........................................................................................................ 642

SetCOMINITBurstTime ........................................................................................................... 643

GetCOMINITBurstTime .......................................................................................................... 643

SetCOMINITIdleTime ............................................................................................................. 644

GetCOMINITIdleTime ............................................................................................................. 644

SetCOMSASBurstTime ........................................................................................................... 645

GetCOMSASBurstTime ........................................................................................................... 645

SetCOMSASIdleTime .............................................................................................................. 646

GetCOMSASIdleTime ............................................................................................................. 646

SetCOMSASNegationTime ..................................................................................................... 647

GetCOMSASNegationTime .................................................................................................... 647

SetCOMSASBurstCount .......................................................................................................... 648

GetCOMSASBurstCount ......................................................................................................... 648

SetCOMWAKEBurstTime ....................................................................................................... 649

GetCOMWAKEBurstTime ....................................................................................................... 649

SetCOMWAKEIdleTime .......................................................................................................... 650

GetCOMWAKEIdleTime ......................................................................................................... 650

SetCOMWAKENegationTime ................................................................................................. 651

GetCOMWAKENegationTime................................................................................................. 651

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

API Description 18

SetCOMWAKEBurstCount ...................................................................................................... 652

GetCOMWAKEBurstCount ..................................................................................................... 652

SetIgnoreIncomingCOMWAKE ............................................................................................... 653

GetIgnoreIncomingCOMWAKE .............................................................................................. 653

SetIgnoreIncomingCOMINIT .................................................................................................. 654

GetIgnoreIncomingCOMINT .................................................................................................. 654

SetIgnoreIncomingCOMSAS................................................................................................... 655

GetIgnoreIncomingCOMSAS .................................................................................................. 655

SetNumberOfWritableAreas .................................................................................................. 656

GetNumberOfWritableAreas ................................................................................................. 656

SetAddressOfWritableArea.................................................................................................... 657

GetAddressOfWritableArea ................................................................................................... 658

AddUserDefineCommand ...................................................................................................... 659

DeleteUserDefineCommand .................................................................................................. 660

SetUserDefineCommand ....................................................................................................... 661

SetMuxingEnabled ................................................................................................................. 662

GetMuxingEnabled ................................................................................................................ 662

GetDeviceType....................................................................................................................... 663

SetDeviceType ....................................................................................................................... 663

SetPortSpeedByIndex ............................................................................................................ 664

GetPortSpeedByIndex............................................................................................................ 665

Properties ................................................................................................ 666

Error Injection Interface Methods .......................................................... 670

ErInjGetCodeViolationAndDisparityErrorAttribute ................................................................ 687

ErInjGetCodeViolationError ................................................................................................... 688

ErInjGetCodeViolationOnSATAPrimitive ................................................................................ 689

ErInjGetCRCError ................................................................................................................... 690

ErInjGetDelayResponseToHold .............................................................................................. 691

ErInjGetDisparityError ........................................................................................................... 692

ErInjGetDisparityErrorOnSATAPrimitive ................................................................................ 693

ErInjGetDonotCheckCredit .................................................................................................... 694

ErInjGetEOFError ................................................................................................................... 695

ErInjGetFillByteForReservedField .......................................................................................... 696

ErInjGetFrameErrorType ........................................................................................................ 697

ErInjGetFrameInvalidField ..................................................................................................... 698

ErInjGetFrameLengthError .................................................................................................... 699

ErInjGetHandshakeError ........................................................................................................ 700

ErInjGetIgnoreXRDYorRRDY ................................................................................................... 701

ErInjGetInsertedFrameAttribute............................................................................................ 702

ErInjGetInsertPrimitive .......................................................................................................... 703

ErInjGetInvalidFieldOfFrameAttribute ................................................................................... 704

ErInjGetNoWTRM .................................................................................................................. 705

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

API Description 19

ErInjGetNumberOfFieldsOfFrame ......................................................................................... 706

ErInjGetOmitFrameFromSequence ....................................................................................... 707

ErInjGetSendDelayToSendHandshake ................................................................................... 708

ErInjGetSendingFrameDelay .................................................................................................. 709

ErInjGetTerminateRecievingFrameAttribute ......................................................................... 710

ErInjGetSOFError ................................................................................................................... 711

ErInjSetCodeViolationAndDisparityErrorAttribute ................................................................ 712

ErInjSetCodeViolationError .................................................................................................... 713

ErInjSetCodeViolationOnSATAPrimitive ................................................................................ 714

ErInjSetCRCError .................................................................................................................... 715

ErInjSetDelayResponseToHold .............................................................................................. 716

ErInjSetDisparityError ............................................................................................................ 717

ErInjSetDisparityErrorOnSATAPrimitive ................................................................................. 718

ErInjSetDonotCheckCredit ..................................................................................................... 719

ErInjSetEOFError .................................................................................................................... 720

ErInjSetFillByteForReservedField ........................................................................................... 721

ErInjSetFrameErrorType ........................................................................................................ 722

ErInjSetFrameInvalidField ...................................................................................................... 723

ErInjSetFrameLengthError ..................................................................................................... 724

ErInjSetHandshakeError ........................................................................................................ 725

ErInjSetIgnoreXRDYorRRDY ................................................................................................... 726

ErInjSetInsertedFrameAttribute ............................................................................................ 727

ErInjSetInsertPrimitive ........................................................................................................... 728

ErInjSetNoWTRM ................................................................................................................... 729

ErInjSetOmitFrameFromSequence ........................................................................................ 730

ErInjSetSendDelayToSendHandshake .................................................................................... 731

ErInjSetSendingFrameDelay .................................................................................................. 732

ErInjSetSOFError .................................................................................................................... 733

ErInjSetTerminateRecievingFrameAttribute .......................................................................... 734

ErInjCmnSetErrorGenerationRate ......................................................................................... 735

ErInjCmnGetErrorGenerationRate ......................................................................................... 736

ErInjCmnSetSpeedNegotiationFailureAttrbiute ..................................................................... 737

ErInjCmnGetSpeedNegotiationFailureAttrbiute .................................................................... 738

ErInjCmnSetBufferStarvation ................................................................................................. 738

ErInjCmnGetBufferStarvation ................................................................................................ 739

ErInjCmnSetNonReleaseOfLink .............................................................................................. 739

ErInjCmnGetNonReleaseOfLink ............................................................................................. 740

ErInjCmnSetLinkResetTimerAfterLinkEnable ......................................................................... 740

ErInjCmnGetLinkResetTimerAfterLinkEnable ........................................................................ 741

ErInjCmnSetHardResetCounterAfterPHYReady ..................................................................... 741

ErInjCmnGetHardResetCounterAfterPHYReady .................................................................... 742

ErInjCmnSetDonotCheckCredit .............................................................................................. 742

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

API Description 20

ErInjCmnGetDonotCheckCredit ............................................................................................. 743

ErInjCmnSetCRCError............................................................................................................. 743

ErInjCmnGetCRCError ............................................................................................................ 744

ErInjCmnSetCodeViolationError ............................................................................................ 744

ErInjCmnGetCodeViolationError ............................................................................................ 745

ErInjCmnSetDisparityError ..................................................................................................... 745

ErInjCmnGetDisparityError .................................................................................................... 746

ErInjCmnSetCodeViolationAndDisparityErrorAttribute ......................................................... 746

ErInjCmnGetCodeViolationAndDisparityErrorAttribute ........................................................ 747

ErInjCmnSetEOFError............................................................................................................. 748

ErInjCmnGetEOFError ............................................................................................................ 748

ErInjCmnSetSOFError ............................................................................................................. 749

ErInjCmnGetSOFError ............................................................................................................ 749

ErInjCmnSetNoWTRM ........................................................................................................... 750

ErInjCmnGetNoWTRM ........................................................................................................... 750

ErInjCmnSetIgnoreXRDYorRRDY ............................................................................................ 751

ErInjCmnGetIgnoreXRDYorRRDY ........................................................................................... 751

ErInjCmnSetDelayResponseToHold ....................................................................................... 752

ErInjCmnGetDelayResponseToHold ...................................................................................... 752

ErInjCmnSetInsertPrimitive ................................................................................................... 753

ErInjCmnGetInsertPrimitive ................................................................................................... 754

ErInjCmnSetFillByteForReservedField.................................................................................... 755

ErInjCmnGetFillByteForReservedField ................................................................................... 755

ErInjCmnSetFrameLengthError .............................................................................................. 756

ErInjCmnGetFrameLengthError ............................................................................................. 757

ErInjIdefSetCRCError .............................................................................................................. 758

ErInjIdefGetCRCError ............................................................................................................. 758

ErInjIdefSetCodeViolationError ............................................................................................. 759

ErInjIdefGetCodeViolationError ............................................................................................. 759

ErInjIdefSetDisparityError ...................................................................................................... 760

ErInjIdefGetDisparityError ..................................................................................................... 760

ErInjIdefSetCodeViolationAndDisparityErrorAttribute .......................................................... 761

ErInjIdefGetCodeViolationAndDisparityErrorAttribute ......................................................... 761

ErInjIdefSetEOAFError ........................................................................................................... 762

ErInjIdefGetEOAFError ........................................................................................................... 762

ErInjIdefSetSOAFError ........................................................................................................... 763

ErInjIdefGetSOAFError ........................................................................................................... 763

ErInjIdefSetSendIdentify ........................................................................................................ 764

ErInjIdefGetSendIdentify ....................................................................................................... 764

ErInjIdefSetNumberOfSendingIDENTIFYAfterPHYEnable ...................................................... 765

ErInjIdefGetNumberOfSendingIDENTIFYAfterPHYEnable ...................................................... 765

ErInjIdefSetDelayFromPHYEnableToStartIdentification ........................................................ 766

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

API Description 21

ErInjIdefGetDelayFromPHYEnableToStartIdentification ........................................................ 766

ErInjIdefSetFrameTypeError .................................................................................................. 767

ErInjIdefGetFrameTypeError ................................................................................................. 767

ErInjConMgnSetErrorOnCloseConnection ............................................................................. 768

ErInjConMgnGetErrorOnCloseConnection ............................................................................ 768

ErInjConMgnSetErrorOnRespondingToCloseConnection ...................................................... 769

ErInjConMgnGetErrorOnRespondingToCloseConnection ...................................................... 770

ErInjConMgnSetErrorOnCloseSequence ................................................................................ 771

ErInjConMgnGetErrorOnCloseSequence ............................................................................... 772

ErInjConMgnSetIncomingOpenFrameErrorAttribute ............................................................ 773

ErInjConMgnGetIncomingOpenFrameErrorAttribute ............................................................ 773

ErInjConMgnSetOutgoingOpenFrameErrorAttribute ............................................................ 774

ErInjConMgnGetOutgoingOpenFrameErrorAttribute ............................................................ 774

ErInjConMgnSetOutGoingOpenFrameInvalidFields ............................................................... 775

ErInjConMgnGetOutGoingOpenFrameInvalidFields .............................................................. 775

ErInjConMgnSetDelayResponseToIncomingOpenFrame ....................................................... 776

ErInjConMgnGetDelayResponseToIncomingOpenFrame ...................................................... 776

ErInjConMgnSetResponseTypeToIncomingOpenFrame ........................................................ 777

ErInjConMgnGetResponseTypeToIncomingOpenFrame ....................................................... 777

ErInjConMgnSetCRCError ...................................................................................................... 778

ErInjConMgnGetCRCError ...................................................................................................... 778

ErInjConMgnSetSOAFError .................................................................................................... 779

ErInjConMgnGetSOAFError ................................................................................................... 779

ErInjConMgnSetEOAFError .................................................................................................... 780

ErInjConMgnGetEOAFError ................................................................................................... 780

ErInjConMgnSetFarmeLengthError ....................................................................................... 781

ErInjConMgnGetFarmeLengthError ....................................................................................... 781

ErInjConMgnSetDisparityError .............................................................................................. 782

ErInjConMgnGetDisparityError .............................................................................................. 782

ErInjConMgnSetCodeVioaltionError ...................................................................................... 783

ErInjConMgnGetCodeVioaltionError ..................................................................................... 783

ErInjConMgnSetCodeViolationAndDisparityErrorAttribute ................................................... 784

ErInjConMgnGetCodeViolationAndDisparityErrorAttribute .................................................. 784

ErInjConMgnSetFrameTypeError ........................................................................................... 785

ErInjConMgnGetFrameTypeError .......................................................................................... 785

ErInjSetSCSICommandGenerateError .................................................................................... 786

ErInjGetSCSICommandGenerateError ................................................................................... 787

ErInjSetSCSICommandCheckConditionErrorAttribute ........................................................... 788

ErInjGetSCSICommandCheckConditionErrorAttribute .......................................................... 789

ErInjSetSCSICommandFrameOutGoingErrorAttribute ........................................................... 790

ErInjGetSCSICommandFrameOutGoingErrorAttribute .......................................................... 791

ErInjSetSCSICommandFrameInComingErrorAttribute ........................................................... 792

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

API Description 22

ErInjGetSCSICommandFrameInComingErrorAttribute .......................................................... 793

ErInjSetSMPCommandGenerateError ................................................................................... 794

ErInjGetSMPCommandGenerateError ................................................................................... 795

ErInjSetSMPCommandFunctionResultErrorType ................................................................... 796

ErInjGetSMPCommandFunctionResultErrorType .................................................................. 797

ErInjSetSMPCommandFrameOutGoingErrorAttribute .......................................................... 798

ErInjGetSMPCommandFrameOutGoingErrorAttribute.......................................................... 799

ErInjSetSMPCommandFrameInComingErrorAttribute .......................................................... 800

ErInjGetSMPCommandFrameInComingErrorAttribute .......................................................... 801

ErInjSetTskMgnCommandGenerateError .............................................................................. 802

ErInjGetTskMgnCommandGenerateError ............................................................................. 803

ErInjSetTskMgnCommandErrorResponseType ...................................................................... 804

ErInjGetTskMgnCommandErrorResponseType ..................................................................... 805

ErInjSetTskMgnCommandFrameOutGoingErrorAttribute ..................................................... 806

ErInjGetTskMgnCommandFrameOutGoingErrorAttribute .................................................... 807

ErInjSetTskMgnCommandFrameInComingErrorAttribute ..................................................... 808

ErInjGetTskMgnCommandFrameInComingErrorAttribute .................................................... 809

ErInjSetSTPCommandGenerateError ..................................................................................... 810

ErInjGetSTPCommandGenerateError .................................................................................... 811

ErInjSetSTPCommandErrorResponseType ............................................................................. 812

ErInjGetSTPCommandErrorResponseType ............................................................................ 813

ErInjSetSTPCommandFrameOutGoingErrorAttribute ............................................................ 814

ErInjGetSTPCommandFrameOutGoingErrorAttribute ........................................................... 815

ErInjSetSTPCommandFrameInComingErrorAttribute ............................................................ 816

ErInjGetSTPCommandFrameInComingErrorAttribute ........................................................... 817

ErInjSetATAPICommandCheckConditionErrorAttribute ........................................................ 818

ErInjGetATAPICommandCheckConditionErrorAttribute ........................................................ 819

ISerialSCSIExtraction ..................................................................................... 820

Methods .................................................................................................. 820

Open ...................................................................................................................................... 822

Close ...................................................................................................................................... 822

SetAssociateLayers ................................................................................................................ 823

ExpandAllPackets ................................................................................................................... 823

GetTotalPacketCount............................................................................................................. 824

GetPacketProperties .............................................................................................................. 825

GetLinkPacketType ................................................................................................................ 826

GetFieldStream ...................................................................................................................... 827

GetFieldData .......................................................................................................................... 828

GetFieldName ........................................................................................................................ 829

GetFieldId .............................................................................................................................. 829

GetFieldDescription ............................................................................................................... 830

ExpandPacket ........................................................................................................................ 831

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

API Description 23

ExpandField ........................................................................................................................... 832

Save ....................................................................................................................................... 832

SaveAsText ............................................................................................................................. 833

FindPacket ............................................................................................................................. 834

GetSearchObject .................................................................................................................... 835

DumpAndExtract ................................................................................................................... 835

SetAnalyzerLinkEnable ........................................................................................................... 836

SetAssociateChannels ............................................................................................................ 837

GetPacketData ....................................................................................................................... 838

AddAssignedElement ............................................................................................................. 838

RemoveAllAssigendElements ................................................................................................ 839

UpdateAssignedSCSICommand ............................................................................................. 839

SetSecondAnalyzerId ............................................................................................................. 840

SetWidePort .......................................................................................................................... 840

SetBoardType ........................................................................................................................ 841

GetBoardType ........................................................................................................................ 841

SetBoardTypeToSample ......................................................................................................... 842

OpenDefaultAliasingManager ............................................................................................... 842

GetExistHashAddress ............................................................................................................. 843

GetExistSCSICommandStatus ................................................................................................ 843

GetPErrorExist ....................................................................................................................... 844

GetNumberOfSamplePorts .................................................................................................... 844

Properties ................................................................................................ 845

ISearchInfo .................................................................................................... 846

Methods .................................................................................................. 846

Properties ................................................................................................ 849

Appendices .................................................................................................... 851

API Constants .............................................................................................................. 852

Address Frame type definition ..................................................................... 852

Addressing Type definition ........................................................................... 852

Affiliation Setting definition .......................................................................... 852

ATA Capacity Type definition ........................................................................ 852

ATA Command Timeout Recovery definition ............................................... 853

ATA Device Emul Error and Status Register definition ................................. 853

Block Descriptor Type definition ................................................................... 853

Bus Condition definition ............................................................................... 854

Capacity Unit Definition ................................................................................ 854

Capture ID definition ..................................................................................... 854

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

API Description 24

Capture Project Mode definition .................................................................. 854

Capture strategy definition ........................................................................... 855

CCEI Data Type definition ............................................................................. 855

Close Sequence Type definition .................................................................... 855

Command type definition ............................................................................. 856

Condition type definition .............................................................................. 860

Correction Type definition ............................................................................ 864

CRC Error Type definition.............................................................................. 864

Delay on Responding to Close definition ...................................................... 864

Device Types definition ................................................................................. 864

Dp Direct definition ....................................................................................... 864

EOF Error Type definition.............................................................................. 865

Error Injection Frame Protocol Type definition ............................................ 865

Exerciser Transport Frame Type definition................................................... 865

Expression Token Type definition ................................................................. 866

Expression Type definition ............................................................................ 866

FIS Type definition ........................................................................................ 866

Frame Length Error Type definition .............................................................. 867

Handshake Error Type definition .................................................................. 867

Handshake Type definition ........................................................................... 867

Inserted Frame Status definition .................................................................. 868

Instruction Memory Status definition .......................................................... 868

Instruction type definition ............................................................................ 868

SAS Layer definition ...................................................................................... 869

Link mode packet definition ......................................................................... 869

Loop type definition ...................................................................................... 870

Option ID definition ...................................................................................... 870

Pattern Types definition ............................................................................... 876

Pattern Using Type definition ....................................................................... 876

Port Type definition ...................................................................................... 877

Power Management Instruction Type definition ......................................... 877

Power Mng Instr definition ........................................................................... 877

PrimitivesEnum ............................................................................................. 878

Primitive type definition ............................................................................... 881

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

API Description 25

Product Type definition ................................................................................ 881

Project Type definition .................................................................................. 881

Protocol Type definition ............................................................................... 881

Radix definition ............................................................................................. 882

Resolution definition ..................................................................................... 882

SAS Speed Negotiation Failure Type definition ............................................ 882

SATA Speed Negotiation Failure Type definition .......................................... 882

SCSI Command type definition ..................................................................... 883

SCSI Spec definition ....................................................................................... 890

Search direction definition ........................................................................... 890

Sending Frame Type For Terminate Reception Frame definition ................ 891

Sense Data definition .................................................................................... 891

SMP Frame Function definition .................................................................... 892

SMP Frame type definition ........................................................................... 892

SMP Function Result definition .................................................................... 893

SOF Error Type definition .............................................................................. 893

Speed definition ............................................................................................ 893

Speed Negotiation Failure By definition ....................................................... 894

Speed Negotiation Failure definition ............................................................ 894

SSP Frame type definition ............................................................................. 894

SSP Task Management Response definition ................................................. 895

Target Element Type definition .................................................................... 895

Target Emul Device Type definition .............................................................. 895

Target Emulator ATA PE definition ............................................................... 896

Target Emulator ATA Protocol Command Type definition ........................... 896

Target Emulator ATAPI Command Type definition ....................................... 896

Target Emulator ATAPI Error Status Reg definition ...................................... 896

Target emulator CmnEr Interval Type definition .......................................... 897

Target Emulator Device Type definition ....................................................... 897

Target Emulator Error Injection Type On Command definition ................... 897

Target Emulator PE definition ....................................................................... 898

Target Emulator SCSI Command Error Type definition ................................ 898

Target Emulator SCSI Page definition ........................................................... 898

Target Emulator STP Command Error Type definition ................................. 899

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

API Description 26

Target Emulator Task Mangment Error Type definition ............................... 899

Target Emulator User-defined Command Protocol Type definition ............ 899

Target Emulator User-defined Command Type definition ........................... 899

Task Attribute definition ............................................................................... 900

Task Management Type definition ............................................................... 900

Time Unit definition ...................................................................................... 900

Trig strategy definition .................................................................................. 901

Trigger Source definition .............................................................................. 901

TX Frame Error on Field definition ................................................................ 901

Wake Up Instr Type definition ...................................................................... 901

Wake Up Instruction Type definition ............................................................ 901

Wide Port Type definition ............................................................................. 902

DeviceTypeConfigurationTypeEnum ............................................................ 902

Pattern Parameters ............................................................................................................ 904

Timer Pattern parameters ............................................................................ 904

External Trigs Pattern parameters ................................................................ 904

BUS Condition Pattern parameters .............................................................. 904

Symbol Pattern parameter ........................................................................... 904

Primitive Pattern parameter ......................................................................... 904

FIS Pattern parameters ................................................................................. 905

ATA Command Pattern parameters.............................................................. 908

ATA Command Pattern parameters.............................................................. 912

Address Frame Pattern parameters ............................................................. 912

SMP, STP and SMP Pattern parameters ....................................................... 914

Data Pattern parameters .............................................................................. 923

Protocol Errors Pattern parameters ............................................................. 924

Soft Reset Pattern parameters ..................................................................... 924

SCSI Command Pattern parameters ............................................................. 925

API Examples .............................................................................................................. 959

Test Capture Project ..................................................................................... 959

General .................................................................................................... 959

Specification ............................................................................................ 959

Limitation ................................................................................................ 960

Multi Run Project .......................................................................................... 960

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

API Description 27

General .................................................................................................... 960

Specification ............................................................................................ 960

Limitation ................................................................................................ 960

Sample Viewer .............................................................................................. 961

General .................................................................................................... 961

Specification ............................................................................................ 961

Limitation ................................................................................................ 961

ATAPI Sample ................................................................................................ 961

General .................................................................................................... 961

Specification ............................................................................................ 961

Limitation ................................................................................................ 962

Read Write Verify .......................................................................................... 962

General .................................................................................................... 962

Specification ............................................................................................ 962

Limitation ................................................................................................ 962

TestTrainer API .............................................................................................. 963

General .................................................................................................... 963

Specification ............................................................................................ 963

Limitation ................................................................................................ 963

China Restriction of Hazardous Substances Table ............................................................... 964

How to Contact LeCroy....................................................................................................... 965

Index .............................................................................................................. 966

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

API Description 28

Introduction

The SAS/SATA API has three types of API:

• STX API: For analyzer, emulators, and Trainer

• CATC API: For analyzer and Trainer

• Infusion API: Only for Infusion

SASEngine is a COM-based library that enables programmers to use some SAS software
functionality in their programs. This library manages all hardware functions. The library includes
some internal Interfaces to detect and set device options and to program SAS hardware.

The software is for use with applications developed under COM-supported platforms, such as
Microsoft® Visual C++™, Borland® Delphi™, and Microsoft Visual Basic™.

First, you must use a COM-supported platform.

Second, you must follow some instructions in programs.

To use API functions, you initialize your application and attach to a board. After initializing your
application and attaching to a board, create an instance of the COM Object. Then use the API
functions.

The most important sections of the SAS/SATA Protocol Suite, STX software are Analyzer and
Emulators.

API Description

The following is the Object Model:

GeneralSrv

This COM class can initialize, shut down the system, and attach to and detach from board.

SerialSCSICaptureProject

This COM Object can trigger, capture, and run a project.

ExerciserEngine

This COM Object can set up an initiator/host emulator and run it.

InitiatorErrorInjection

This COM Object can inject errors on commands or frames in host emulator.

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

API Description 29

TargetEmulatorEngine

This COM Object can set up a target/device emulator and activate it.

TargetErrorInjection

This COM Object can inject errors on commands or frames in device emulator.

Extraction

This COM Object can create and open sample files and get information about packets.

Search

This COM Object can search inside sample files.

APISrv

This object comes from merging Trainer API functionality and analyzer API functionality.

This object can create all other API objects. You can get other objects from this object and then
use them.

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

API Description 30

GeneralSrv

SerialSCSICaptureProject

TargetErrorInjection

Extraction

APISrv

TargetEmulatorEngine

ExerciserEngine

InitiatorErrorInjection

The API supports Interfaces, Constants, and Parameters. You can also view API errors.

COM Interfaces Supported

The SAS/SATA Protocol Suite, STX software supports the following COM Interfaces:

• ISASAPISrvs
o Methods

• ISerialSCSICaptureProject

o Methods
o Properties

• ISASGeneralService

Methods

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

API Description 31

• IExerciserEngine

o Default Interface Methods
o Properties
o Error Injection Interface Methods

• ITargetEmulEngine

o Default Interface Methods
o Properties
o Error Injection Interface Methods

• ISerialSCSIExtraction

o Methods
o Properties

• ISearchInfo

o Methods
o Properties

Constants

The SAS/SATA Protocol Suite, STX software supports the following Constants, which are typically
used by several methods:

• Address Frame type definition

• Addressing Type definition

• Affiliation Setting definition

• ATA Capacity Type definition

• ATA Command Timeout Recovery definition

• ATA Device Emul Error and Status Register definition

• Block Descriptor Type definition

• Bus Condition definition

• Capacity Unit Definition

• Capture ID definition

• Capture Project Mode definition

• Capture strategy definition

• CCEI Data Type definition

• Close Sequence Type definition

• Command type definition

• Condition type definition

• Correction Type definition

• CRC Error Type definition

• Delay on Responding to Close definition

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

API Description 32

• Device Types definition

• Dp Direct definition

• EOF Error Type definition

• Error Injection Frame Protocol Type definition

• Exerciser Transport Frame Type definition

• Expression Token Type definition

• Expression Type definition

• FIS Type definition

• Frame Length Error Type definition

• Handshake Error Type definition

• Handshake Type definition

• Inserted Frame Status definition

• Instruction Memory Status definition

• Instruction type definition

• SAS Layer definition

• Link mode packet definition

• Loop type definition

• Option ID definition

• Pattern Types definition

• Pattern Using Type definition

• Port Type definition

• Power Management Instruction Type definition

• Power Mng Instr definition

• PrimitivesEnum

• Primitive type definition

• Product Type definition

• Project Type definition

• Protocol Type definition

• Radix definition

• Resolution definition

• SAS Speed Negotiation Failure Type definition

• SATA Speed Negotiation Failure Type definition

• SCSI Command type definition

• SCSI Spec definition

• Search direction definition

• Sending Frame Type For Terminate Reception Frame definition

• Sense Data definition

• SMP Frame Function definition

• SMP Frame type definition

• SMP Function Result definition

• SOF Error Type definition

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

API Description 33

• Speed definition

• Speed Negotiation Failure By definition

• Speed Negotiation Failure definition

• SSP Frame type definition

• SSP Task Management Response definition

• Target Element Type definition

• Target Emul Device Type definition

• Target Emulator ATA PE definition

• Target Emulator ATA Protocol Command Type definition

• Target Emulator ATAPI Command Type definition

• Target Emulator ATAPI Error Status Reg definition

• Target Emulator CmnEr Interval Type definition

• Target Emulator Device Type definition

• Target Emulator Error Injection Type On Command definition

• Target Emulator PE definition

• Target Emulator SCSI Command Error Type definition

• Target Emulator SCSI Page definition

• Target Emulator STP Command Error Type definition

• Target Emulator Task Mangment Error Type definition

• Target Emulator User-defined Command Protocol Type definition

• Target Emulator User-defined Command Type definition

• Task Attribute definition

• Task Management Type definition

• Time Unit definition

• Trig strategy definition

• Trigger Source definition

• TX Frame Error on Field definition

• Wake Up Instr Type definition

• Wake Up Instruction Type definition

• Wide Port Type definition

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

API Description 34

Parameters

The SAS/SATA Protocol Suite, STX software supports the following Parameters, which are useds
by several methods and are in different pattern groups:

• External Trigs Pattern parameters

• BUS Condition Pattern parameters

• Symbol Pattern parameter

• Primitive Pattern parameter

• FIS Pattern parameters

• ATA Command Pattern parameters

• ATA Command Pattern parameters

• Address Frame Pattern parameters

• SMP,STP and SMP Pattern parameters

• Data Pattern parameters

• Protocol Errors Pattern parameters

• Soft Reset Pattern parameters

• SCSI Command Pattern parameters

API Errors

Error description files are:

• (Release folder) …/system/CEIMsg.cem

• (Release folder) …/system/SAS.cem

To get an error description, if error code is less than 15000, see the SAS.cem file in the System
folder of the release. Otherwise, see the CEIMsg.cem file in the System folder of the release.

In these files, you can find the error code and description, for example:
error code 1029 in CEIMsg.cem file :

[#1029]The Root Directory Path is invalid.

NOTE: You can open these files with a text editor.

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

API Description 35

How to Use the API

To use the API, first create your application, then consider the following steps:

• Setup API application.

• Initialize your application.

• Connect to the board.

• How to Set/ Initialize Connection Points

• Use Analyzer API.

• Use Initiator/Host Emulator API.

• Use Target/Device Emulator API.

• Use Trainer API.

• Navigate through trace file.

• Use CATC API.

• Use Infusion API.

• SATA Protocol Suite Device Emulator API

NOTE: Document images are examples only. Use the actual project files listed in the Refer

heading of each section or subsection. Do not use the project files listed in the images.

Setup your API Application

First create your new API application project.
(If using VC++, create MFC Application as Single Document Type and check

Document–View Architecture support.)

NOTE: Browse the project creation path to the \APIExamples\Analyzer_Emulator_API\VC

folder of the SAS/SATA Installed directory or STX Software directory.

Then import required DLLs into your application. (Refer to Test CaptureProject -> stdafx.h.)

NOTE: Before importing, confirm that the location of the DLLs is the EXE folder inside your

software installation directory. If not, use the complete path of the folder containing the
DLLs.
For example:

#import "C:\Program Files\Common Files\LeCroy

Shared\CEIEnums.dll"

Open the stdafx.h file of your project and add the following lines at the end of the file.

#import "..\..\..\..\EXE\CEIEnums.dll"
using namespace CEIENUMSLib;

#import "..\..\..\..\EXE\CEIStorageEnum.dll"
using namespace CEISTORAGEENUMLib;

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Setup your API Application 36

#import "..\..\..\..\EXE\DBE.dll"
using namespace DBELib;

#import "..\..\..\..\EXE\SASEngine.dll"
using namespace SASENGINELib;

Add the APITestSink class (APITestSink.cpp + APITestSink.h) from a current API example to
your application, for uploading and creating the sample.

Add the APIHeader.h file into your application by including the same in stdafx.h, to include all
required class/ library dependencies.

Visual C++: Copy and paste the APITestSink.h, APITestSink.cpp, and APIHeader.h files from any
of the API Examples (for example, Test Capture Project) into your project folder. Then include
these files into your project by using File -> Add Existing Item.

Initialize Your Application

To initialize your API application, do the following:

• Set a valid path for the output file in the settings of your application.

• Declare two required objects in main class of your application.

• Create instances of the two objects declared in the main class of your application.

• Finalize initialization by calling InitializeSystem function.

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Initialize Your Application 37

Set a valid path for the output file of your application

Set output file location to the \API folder of your installed SAS/SATA Protocol Suite or STX
Software (for example, C:\\Program Files\...\SAS_XX\API). For reference, check the project
settings page (ProjectMenu -> Properties -> OutputDirectory) of any current API Example.

Declare two required objects in main class of your application

Declare two smart pointers) for Data Block and SAS General Service) in the main class of your
program.

IDataBlocksPtr m_pDataBlocks;
ISASGeneralServicePtr m_pIGeneralSrvPtr;

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Initialize Your Application 38

Create Instances of the two objects just declared in the main class of your application

Create instances of the two declared objects in the Init instance function of the main class in
your application.

(Refer to TestCaptureProject -> TestCaptureProject.cpp -> InitInstance ().)

m_pDataBlocks.CreateInstance(__uuidof(DataBlocks));
m_pIGeneralSrvPtr.CreateInstance(__uuidof(SASGeneralService));

CreateInstance ()

Prototype HRESULT CreateInstance (CLSID &rclsid, IUnknown * pOuter = 0,

DWORD dwClsContext = CLSCTX_ALL);

Usage HRESULT hr = <class object> DOT CreateInstance (__uuidof (<class name>));

Inputs CLSID is ID of the class object for which an instance needs to be created.

(Use the __uuidof() method to retrieve CLSID of any class.)
** sets default values for the remaining parameters.

Return Value HRESULT (Success/Failure in terms of instance creation)

Description Call the CreateInstance() method to create an instance of any class object.

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Initialize Your Application 39

Finalize initialization by calling “InitializeSystem ()”.

Call the InitializeSystem function of the SAS General Service object in the main class. Set the
parameter to the path of your SAS/SATA Protocol Suite or STX software.

(Refer to TestCaptureProject -> TestCaptureProject.cpp -> InitInstance ().)

m_pIGeneralSrvPtr->InitializeSystem (bstrCurrentDir)
[can be a NULL string also]

CSASGeneralService::InitializeSystem ()

Prototype BOOL InitializeSystem (BSTR bstrCurrentDirectory);

Usage BOOL bIsInitialized = <SAS General Service object> -> InitializeSystem

(<Current Directory String in BSTR form>);

Inputs Current Directory String in BSTR format

Return Value BOOL (Success/Failure in terms of system initialization)

Description Call the InitializeSystem() method to initialize the system at the specified

location.

Connecting to the Board

To connect to the board, you must know three parameters:

• Connection Type (yConnectionType): Connection type can be either USB or TCP. The

values for this parameter can be specified using pre-defined constants
(APIHeader.h), such as CEI_CONNECTION_USB or CEI_CONNECTION_TCP.

• Device Id (vDeviceId): Device Identification Number of the Board found on the label

of the Teledyne LeCroy hardware. This parameter is Variant, and so it needs a
conversion from string form of Device Id to Variant. This conversion can be done
using:

AfxConvertStringArrayToVariant (&vDeviceId,
astrDeviceId);

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Connecting to the Board 40

Refer to any API Example to find the declaration, implementation, and usage of this
function and then duplicate the same in your project files.

NOTE: If you are providing a static value for the device ID in the source code itself

(instead of using a dialog-based input entry), append “0020” for
CEI_CONNECTION_USB or “0040” for CEI_CONNECTION_TCP at the beginning of
the Device ID string.
For example, if the device Id is “000E850001BD”:
For USB: CString strDevId = “0020000E850001BD”
For TCP: CString strDevId = “0040000E850001BD”

• Product Type (eProductType): An enumeration specifies PROJECT_TYPE_SAS for SAS

and PROJECT_TYPE_SATA for SATA. These enumerations are imported from
CEIStorageEnum.Dll.

Connect to the board using the function Attach () of the SAS General Service Object. Call this
function with the above set of parameters in the InitInstance () function of the main class of
your application.

(Refer to TestCaptureProject -> TestCaptureProject.cpp ->
InitInstance ().)

m_pIGeneralSrvPtr->Attach (yConnectionType, vDeviceId,
eProductType);

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Connecting to the Board 41

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Connecting to the Board 42

CSASGeneralService::Attach ()

Prototype int Attach (BYTE yConnectionType, VARIANT vDeviceId, ProductTypeEnum

eProductType);

Usage int nErrorCode = <SAS General Service Object> ->

Attach (<Connection Type USB/TCP>,
<Device ID of the Board>, <Product Type SAS/SATA>);

Inputs Connection Type: CEI_CONNECTION_USB (or) CEI_CONNECTION_TCP

Device ID: Identification Number of the Hardware Board

Product Type: PROJECT_TYPE_SAS and PROJECT_TYPE_SATA

Return Value Integer error code (Success/Failure in terms of connecting to board)

Description Call the Attach () method to programmatically connect to any of the physically

attached hardware board.

Rather than use static values for the Attach function, you can use dynamic values by creating a
common dialog box.

(Refer to the Port Select Dialogof any API Example, which takes the input as these three
parameters and passes their corresponding values onto the attach function.)

If any of the above mentioned functions are unsuccessful, they return an Error Code. (They
return Zero if successful.). The error description is in one of the following files:

CEIMsg.cem: In System folder of the installed software path.
SAS.cem: In System folder of the installed software path.

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Connecting to the Board 43

How t o Set/Initia liz e Conne c t ion Points

To use the APIs of SAS/ SATA, you must set and initialize required connection points for the
Interface needed in your test project. And to perform the same, you need to create Sink objects
and set correct IIDs (Interface Identifiers) specific to the product (SAS/ SATA) and also to the
Interface (Ex: SerialSCSIExtraction or so).

To declare the Interface Identifiers, you need to create a Sink implementation class (Can be
generated automatically using MS Visual Studio) and set the relevant Interface Identifiers as
shown below in the example images

This figure demonstrates IID declaration for Extraction’s Event Interface.

This figure demonstrates IID declaration for FindDevice’s Event Interface.

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

How to Set/Initialize Connection Points 44

This figure demonstrates IID declaration for CaptureProject’s Event Interface

Once the sink object and its corresponding identifiers are set, you can proceed with setting up
the connection points for the same. But before that one need to make sure regarding the
necessary functions to be overwritten in order to validate the connection.

For example, for SerialSCSIExtraction interface, you need to overwrite ExtractionInProgress().
Refer to APITestSink.h and APITestSink.cpp of any API Examples provided for declaration &
implementation of the same. Similarly for other interfaces, we need to set both the IIDs and
also implementations of the functions to be overwritten. Refer to SASFindDeviceCPSink.h and
SASFindDeviceCPSink.cpp of FindDeviceAPI location in APIExamples folder.

Next step is to create and initialize connection points with respect to the interface of
requirement and to do so, you need to include set of lines of code as shown below in the image
provided.

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

How to Set/Initialize Connection Points 45

Using Analyzer API

To use analyzer APIs, you must create an instance of a capture project object, then you can
create a new capture project or open a saved one. After these steps, the capture project is
ready for modifying and running. After running the project, you can stop the project and upload
and create the sample.

• Initialize a capture project object

• Create a new Analyzer capture project

• Run an Analyzer capture project

• Stop an Analyzer capture project

• Upload and create the sample file

• Open a saved Analyzer capture project

• Modify an existing Analyzer capture project

o Set trigger mode/strategy

o Add trigger pattern

o Remove trigger pattern
o Set capture mode/strategy

o Add capture pattern

o Remove capture pattern
o Exclude/include pattern items
o Set memory usage parameters

 Put entire memory
 Put segmented memory
 Put partial memory
 Set trigger position in memory

o Set output sample file path

o Set port configuration

• Summary

• Set a timer to check status of the hardware after run

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Using Analyzer API 46

Initialize a Capture Project Object

Define a smart pointer to SerialSCSICaptureProject and create its instance using the
CreateInstance () function.

(Refer to TestCaptureProject -> TestCaptureProjectView.h -> CTestCaptureProjectView.)

(Refer to TestCaptureProject -> TestCaptureProjectView.cpp -> OnInitialUpdate ().)

ISerialSCSICaptureProjectPtr m_pICaptureProject

m_pICaptureProject.CreateInstance(__uuidof(SerialSCSICaptureProje
ct))

For Function Prototypes and Descriptions:

(Refer to Create Instances of the two objects just declared in the main class of your application
for prototype and description of CreateInstance ().)

Create a New Analyzer Capture Project

Call the New() function of the capture project object with project type as its only parameter.

(Refer to

TestCaptureProject -> TestCaptureProjectView.cpp ->
OnInitialUpdate ().)

ProjectTypeEnum eProjectType = ID_PROJECT_TYPE_ANALYZER_ONLY;
or

ID_PROJECT_TYPE_ANALYZER_EXERCISER

m_pICaptureProject->New (eProjectType);

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Using Analyzer API 47

CSerialSCSICaptureProject::New ()

Prototype HRESULT New (CEIEENUMSLib::ProjectTypeEnum eProjectType);

Usage <Capture Project Object> -> New (<Project Type Enum>);

Inputs Project Type Enum: Type of Project (Analyzer-only or Analyzer-with-Exerciser)

Return Value None

Description Call the New () method to create a new capture project of type Analyzer or

Analyzer-with-Exerciser.

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Using Analyzer API 48

Run an Analyzer Capture Project

To run the newly created capture project, call the Run () function of the Capture Project object
and use the SetTimer () function to check the running status of the hardware in regular
intervals.

(Refer to TestCaptureProject -> TestCaptureProjectView.cpp ->
OnRunButton ().)

m_pICaptureProject->Run ();

SetTimer (IDT_RUN, 1000, NULL);

To manage the running status conditions, declare and implement an OnTimer () function that
includes the hardware status checking functions of the SAS General Service Object, such as

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Using Analyzer API 49

IsHWRunning () and IsHWTriggered ().
(Refer to TestCaptureProject -> TestCaptureProjectView.cpp ->

OnTimer ().)
afx_msg void OnTimer(UINT nIDEvent);

CSerialSCSICaptureProject::Run ()

Prototype long Run (void)

Usage long lErrorCode = <Capture Project Object> -> Run ();

Inputs None

Return Value If method succeeds, return value equals CEI_OK. Otherwise, returns an error

code.

Description Call the Run () method to start running the new Analyzer capture project.

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Using Analyzer API 50

CWnd::SetTimer ()

Prototype UINT_PTR SetTimer (UINT_PTR nIDEvent, UINT nElapse,

Void (*) (HWND, UINT, UINT_PTR, DWORD) lpfnTimer );

Usage SetTimer (<Event ID>, <Elapse time in milliseconds>, NULL);

Inputs UINT nIDEvent: Event index

UINT nElapse: Elapse/sleep time for Timer check-up
(Gap time between each interval)

Return Value None

Description Call the SetTimer () method to set a timer to check the running status of the

hardware at regular intervals based on the elapse time specified.

<THIS>::OnTimer ()

Prototype void OnTimer (UINT nIDEvent);

Usage Automatic method call with the use of SetTimer () function. No need to call

explicitly.

Inputs UINT nIDEvent: Event Index

Return Value None

Description Declare and implement this routine to handle the hardware running status

conditions.

Stop an Analyzer Capture Project

To stop running hardware, kill the timer first by calling the KillTimer () function with the same
event index, and then call the HalAnalyzerStop () function of the SAS General Service Object to
finally bring the hardware to a halt.

(Refer to TestCaptureProject -> TestCaptureProjectView.cpp ->
OnTimer ().)

KillTimer (IDT_RUN);

theApp.m_pIGeneralService->HalAnalyzerStop ();

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Using Analyzer API 51

CSASGeneralService::HalAnalyzerStop ()

Prototype HRESULT HalAnalyzerStop (void);

Usage theApp.m_pIGeneralService->HalAnalyzerStop ();

Inputs None

Return Value None

Description Call HalAnalyzerStop () method to stop a running Analyzer capture project.

You can use it after stopping the hardware or during running status.

CWnd::KillTimer ()

Prototype BOOL KillTimer (UINT nIDEvent);

Usage KillTimer (<Event Index>);

Inputs UINT nIDEvent: Event Index constant

Return Value Returns a Boolean value specifying the timer killing success status.

Description Call KillTimer () to kill the timer object before even stopping the capture process

and bringing the hardware to halt position.

Upload and create sample file

To upload and create the sample, first create an instance of SerialSCSIExtraction.
(Refer to TestCaptureProject -> TestCaptureProjectView.cpp ->

OnTimer ().)

ISerialSCSIExtractionPtr IExtraction;
IExtraction.CreateInstance (__uuidof (SerialSCSIExtraction));

Next, set some extraction features such as Speed and Links. To set the analyzer speed, use
get_AnalyzerSpeed () of Capture Project, put_AnalyzerSpeed () of Extraction.

m_pICaptureProject->get_AnalyzerSpeed (nIndex,

&eAnalyzerSpeed);
IExtraction->put_AnalyzerSpeed (nIndex, eAnalyzerSpeed);

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Using Analyzer API 52

To set the Analyzer link enable status, use GetLinkIsEnable () of Capture project and
SetAnalyzerLinkEnable () of Extraction

m_pICaptureProject->GetLinkIsEnable (nIndex);
IExtraction->SetAnalyzerLinkEnable (nIndex/2,
m_pICatureProject -> GetProjectType (), abLinkIsEnable [0],

abLinkIsEnable [1]);

After that, upload and create the sample, by calling the DumpAndExtract () function of the
Extraction object with sample file path string as its only parameter.

IExtraction->DumpAndExtract (m_pICaptureProject->GetOutputFile
());

For Function Prototypes and Descriptions
(Refer to Create Instances of the two objects just declared in the main class of your application
for prototype and description of CreateInstance ().)

CSerialSCSICaptureProject::get_AnalyzerSpeed ()

Prototype HRESULT get_AnalyzerSpeed (int nIndex, AnalyzerSpeedEnum *pVal);

Usage <Capture Project object> -> get_AnalyzerSpeed

(<Board Index>, &<AnalyzerSpeedEnum>);

Inputs int nIndex: Board Index

AnalyzerSpeedEnum *eAnalyzerSpeed: Speed of the analyzer in terms of Gbps

Return Value None

Description Call get_AnalyzerSpeed () method to retrieve the current speed of the

Analyzer capture project

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Using Analyzer API 53

CSerialSCSIExtraction::put_AnalyzerSpeed ()

Prototype HRESULT put_AnalyzerSpeed (unsigned char yPort, AnalyzerSpeedEnum pVal);

Usage <SCSI Extraction object> -> put_AnalyzerSpeed

(<Board Index>, <AnalyzerSpeedEnum>);

Inputs int nIndex: Board Index

AnalyzerSpeedEnum eAnalyzerSpeed: Speed of the analyzer in terms of Gbps

Return Value None

Description Call put_AnalyzerSpeed () method to set the current speed of the Analyzer

capture project

CSerialSCSICaptureProject::GetLinkIsEnable ()

Prototype long GetLinkIsEnable (int nIndex);

Usage long lLinkIsEnable = <Capture Project Object> -> GetLinkIsEnable (<Board Index>);

Inputs int nIndex: Board Index

Return Value Returns enable status of the link

Description Call GetLinkIsEnable () method to check the enable status of the link.

CSerialSCSIExtraction::SetAnalyzerLinkEnable ()

Prototype HRESULT SetAnalyzerLinkEnable (unsigned char yBoardIndex,

ProjectTypeEnum eProjectType, long bLink1IsEnable, long bLink2IsEnable);

Usage <SCSI Extraction Object> -> SetAnalyzerLinkEnable

(<Board Index>, <Project Type>, <Link1 Enable status>, <Link2 Enable Status>);

Inputs unsigned char yBoardIndex: Index of the Board

ProjectTypeEnum eProjectType: Current running project type

Long bLink1IsEnable: Specifies whether first link in this board is enabled

Long bLink2IsEnable: Specifies whether second link in this board is enabled

Return Value None

Description Call the SetAnalyzerLinkEnable () method to set the enable status of both the

links of each connection board according to its board index. If you want to use
the entire memory of one board for a link, you should enable one link and
disable another link.

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Using Analyzer API 54

CSerialSCSIExtraction::DumpAndExtract ()

Prototype int DumpAndExtract (_bstr_t bstrSampleFileName);

Usage <SCSI Extraction Object> -> DumpAndExtract (<Sample Filepath in BSTR format>);

Inputs BSTR bstrSampleFileName: BSTR format of the sample file path and name

Return Value Returns zero if success, otherwise an error code.

Description Call the DumpAndExtract () method to upload and create the sample data from

an Analyzer into the specified sample file name.

Open a Saved Capture Project

To open a saved capture project, call the Open () function of the capture project object with File
path and Error code as IN and OUT parameters, respectively.

(Refer to TestCaptureProject -> TestCaptureProjectView.cpp ->
OnFileOpen ().)

m_pICaptureProject->Open (bstrFileName, NULL, FALSE);

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Using Analyzer API 55

CSerialSCSICaptureProject::Open ()

Prototype long Open (BSTR bstrFileName, IDataBlocks *pIDB, long bDoneConvertIfNeeded);

Usage <Capture Project object> -> Open (<BSTR form of Project File name>, NULL,

FALSE);

Inputs BSTR bstrFileName: Path of the project file

IDataBlocks *pIDB: Pointer of DataBlocks that must be correct in Analyzer/
Exerciser Project

Long bDoneConvertIfNeeded: If saved project is in X1, X2 or X4 and you want to
open in another type, sometimes you must delete some pattern or direction of a
pattern. If bDoneConvertIfNeeded is TRUE, this item will get deleted. Otherwise,
an error code is returned by the Open function.

Return Value If this method succeeds, the return value equals to CEI_OK.

Otherwise, the return value equals to the status error code

Description Call the Open () method to open a saved analyzer project.

Modifying an Existing Analyzer Project

Modifying an Analyzer Project involves modifying pattern strategies of Trigger/ Condition
Expression Items, Capture Items, and settings of Trigger Position, Memory Mode and Output
sample file path.

Set Trigger Mode/Strategy

To set the trigger strategy (Don’t Care [Snapshot] / Manual / Pattern), call the SetTrigStrategy ()
function of the Capture Project object with TrigStrategyEnum as its only parameter.

(Refer to TestCaptureProject -> TestCaptureProjectView.cpp ->
OnRunButton ().)

m_pICaptureProject->SetTrigStrategy(ID_TRIG_SNAPSHOT);
(or)
m_pICaptureProject->SetTrigStrategy(ID_TRIG_PATTERN);

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Using Analyzer API 56

CSerialSCSICaptureProject::SetTrigStrategy ()

Prototype HRESULT SetTrigStrategy (TrigStrategyEnum eTrigStrategy);

Usage <Capture Project object> -> SetTrigStrategy (<Trigger Strategy Option Index>);

Inputs TrigStrategyEnum eTrigStrategy: Strategy Option of the Trigger

Return Value None

Description Call the SetTrigStrategy () method to set the mode or strategy for trigger

pattern.

Add a Trigger Pattern

To add a capture pattern, call the AddConditionExprPattern () function of the Capture Project
object with the order of its parameters below.

(Refer to TestCaptureProject -> ATACommandDialog.cpp -> OnOk ().)

m_pICaptureProject->AddConditionExprPattern (
0, 0, ID_PATTERN_TYPE_ATA_COMMAND_PATTERN,
&vtDirection, &vtSubChannelDirection, &lErrorCode);

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Using Analyzer API 57

CSerialSCSICaptureProject::AddConditionExprPattern ()

Prototype long AddConditionExprPattern (int nStateIndex, int nConditionIndex,

PatternTypeEnum ePatternType, VARIANT *vtDirection,
VARIANT *vtSubChannelDirection, long *pErrorCode);

Usage long lPatternIndex = <Capture Project object> -> AddConditionExprPattern

( <State Index>, <Condition Index>, <Pattern Type>,
<Pattern Direction>, <Sub-channel direction of the pattern>,
<Pointer to the Error code>);

Inputs Int nStateIndex: ID for a state in advanced mode. (“Don’t care” in Easy mode)

Int nConditionIndex: Index for a condition in advanced mode
(“Don’t care in easy mode”)

PatternTypeEnum ePatternType: Pattern Type Option Index

VARIANT *vtDirection: Direction of the Pattern
This variant comes from a ByteArray Type
This Byte Array contains direction of all boards as byte

VARIANT * vtSubChannelDirection: Sub channel direction of the pattern
This variant comes from a byte array type. This byte array contains Sub channel
direction of all boards as byte. This parameter is for the muxing feature. If the
muxing feature is disabled, insert zero for the byte array for the sub channel
directions. Size of this array is equal to the size of the Direction array.

Long *pErrorCode: Saves the error code if any error occurs.

Return Value None

Description Call the AddConditionExprPattern () method to add a trigger pattern in

easy mode or a state condition expression in advanced mode.
Once after adding a pattern, you can change its parameters by using some
other set of functions. Then call UpdateHardwareResource () function to assign
the related pattern to the added pattern.

List of Pattern Types for PatternTypeEnum Option (for Trigger / Condition Expression) and their
corresponding functions to set the required parameters:

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Using Analyzer API 58

PatternTypeEnum Index Functions to set parameters

ID_PATTERN_TYPE_ATA_COMMA

SetConditionExprPatternParamet

ID_PATTERN_TYPE_TIMER

(Timer)

ID_PATTERN_TYPE_TIMEOUT

(Timeout)

ID_PATTERN_TYPE_OTHER_TRIGS

(External Trigger)

ID_PATTERN_TYPE_BUS_CONDITI
ON

(Bus Condition)

ID_PATTERN_TYPE_SYMBOL

(Symbol)

SetTimerResolutionMode ()

SetConditionExprPatternParamet
erValue ()

SetTimeoutValue ()

SetTimeoutResolutionMode ()

SetTimeoutTriggerMode ()

SetConditionExprPatternParamet
erValueBy
OptionId ()

SetConditionExprPatternDirection
()

SetConditionExprPatternParamet
erValue ()

SetConditionExprPatternDirection
()

SetConditionExprPatternParamet
erValue ()

ID_PATTERN_TYPE_PRIMITIVE

(Primitive)

ID_PATTERN_TYPE_FIS

ID_PATTERN_TYPE_FIS_PATTERN

(STP Frame)

ID_PATTERN_TYPE_ATA_COMMA
ND

SetSymbolPatternType ()

SetPrimitiveTypeConditionExprPa
ttern ()

SetConditionExprPatternParamet
erValueBy
OptionId ()

SetConditionExprPatternDirection
()

SetConditionExprPatternIsNot ()

SetFISConditionExprPattern ()

SetConditionExprPatternParamet
erValueBy
OptionId ()

SetConditionExprPatternDirection
()

SetATACommandConditionExprPa
ttern ()

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Using Analyzer API 59

ND

_PATTERN

erValue ()

SetConditionExprPatternSCSICDB

(ATA Command)

SetConditionExprPatternDirection
()

ID_PATTERN_TYPE_ATAPI

(ATAPI)

ID_PATTERN_TYPE_ADDRESS_FRA
ME

(Address Frame)

ID_PATTERN_TYPE_SMP_FRAME

(SMP Frame)

SetConditionExprPatternATAPICo
mmand
Type ()

SetConditionExprPatternATAPI ()

SetConditionExprPatternDirection
()

SetConditionExprPatternATAPICD
BType ()

SetAddressFrameConditionExprP
attern ()

SetConditionExprPatternDirection
()

SetSMPFrameConditionExprPatte
rn ()

SetConditionExprPatternDirection
()

ID_PATTERN_TYPE_SSP_FRAME

(SSP Frame)

ID_PATTERN_TYPE_SCSI_COMMA
ND

(SCSI Command)

SetSSPFrameConditionExprPatter
n ()

SetConditionExprPatternDirection
()

SetConditionExprPatternSSPCDBT
ype ()

SetConditionExprPatternSSPData
Pres ()

SetConditionExprPatternSSPUseH
ash
Address ()

SetSCSICommandConditionExprP
attern ()

SetConditionExprPatternDirection
()

SetConditionExprPatternSCSICom
mand
Type ()

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Using Analyzer API 60

Type ()

SetConditionExprPatternSCSIUse
Hash
Address ()

ID_PATTERN_TYPE_DATA_PATTER
N

(Data Pattern)

ID_PATTERN_TYPE_PROTOCOL_ER
RORS

(Protocol Errors)

ID_PATTERN_TYPE_USER_DEFINE

(User Defined)

SetDataConditionExprPattern ()

SetConditionExprPatternDataOffs
et ()

SetConditionExprPatternDirection
()

SetConditionExprPatternIsNot ()

SetConditionExprPatternParamet
erValue ()

SetProtocolErrorConditionExprPat
tern ()

SetConditionExprPatternDirection
()
SetConditionExprPatternParamet
erValue ()

SetConditionExprPatternDirection
()

SetConditionExprPatternParamet
erValue ()

ID_PATTERN_TYPE_SOFT_RESET

(Soft Reset)

SetConditionExprPatternDirection
()

SetConditionExprPatternParamet
erValue ()

Remove a Trigger Pattern

To remove a trigger pattern/state condition, call the RemoveConditionExprPattern () function
of the Capture Project object with State Index, Condition Index, Expression Token Index, and
Update Resource status-check as its set of parameters, in the same order.

m_pICaptureProject->RemoveConditionExprPattern (nStateIndex,
nConditionIndex, nExprTokenIndex, FALSE);

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Using Analyzer API 61

CSerialSCSICaptureProject::RemoveConditionExprPattern ()

Prototype BOOL RemoveConditionExprPattern (int nStateIndex, int nConditionIndex,

int nExprTokenIndex, BOOL bUpdateResource);

Usage BOOL bIsPatternRemoved = <Capture Project object> ->

RemoveConditionExprPattern (<State Index>, <Condition Index>,
<Expression Token Index>, <Boolean for Update Resource>);

Inputs Int nStateIndex: ID for state in advanced mode (“Don’t care in easy mode”)

Int nConditionIndex: Index for a condition in advanced mode
(“Don’t care” in easy mode)

Int nExprTokenIndex: Trigger pattern index in easy mode or index for a token
added
for this condition in advanced mode

BOOL bUpdateResource: TRUE if you want to update resource, Otherwise FALSE

Return Value Returns TRUE if remove was successful. Otherwise, FALSE

Description Call the RemoveConditionExprPattern () method to remove the added trigger

pattern or condition expression in either easy mode or advanced mode,
respectively.

Set Capture Mode/ Strategy

To set the Capture strategy (Everything / Pattern), call the SetCaptureStrategy () function of the
Capture Project object.

(Refer to TestCaptureProject -> TestCaptureProjectView.cpp ->
OnRunButton ().)

m_pICaptureProject->SetCaptureStrategy (ID_CAPTURE_PRE_TRIG,
ID_CAPTURE_EVERYTHING);

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Using Analyzer API 62

Function Prototypes and Descriptions:

CSerialSCSICaptureProject::SetCaptureStrategy ()

Prototype HRESULT SetCaptureStrategy (int nStateIndex,

CaptureStrategyEnum eCaptureStrategy);

Usage <Capture Project object> -> SetCaptureStrategy

(<State Index for Advanced mode>, <Capture Strategy option Index>);

Inputs int nStateIndex: Index of a state in Advanced Mode, (or) of a Capture in easy

mode

CaptureStrategyEnum eCaptureStrategy: Strategy Option of the Capture

Return Value None

Description Call the SetCaptureStrategy () method to set the mode or strategy for

Capture (Everything or Pattern) for a state based in StateId.

Add a Capture Pattern

To add a capture pattern, call the AddCapturePattern () function of the Capture Project object
with the order of its parameters below.

(Refer to TestCaptureProject -> ATACommandDialog.cpp -> OnOk ().)

m_pICaptureProject->AddCapturePattern (ID_CAPTURE_PATTERN_TRIG,
ID_PATTERN_TYPE_FIS, &vtDirection, &vtSubChannelDirection,
&lErrorCode);

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Using Analyzer API 63

CSerialSCSICaptureProject::AddCapturePattern ()

Prototype long AddCapturePattern (int nStateID, PatternTypeEnum ePatternType,

VARIANT *vtDirection, VARIANT *vtSubChannelDirection,
long* pErrorCode);

Usage long <Pattern Index> = <Capture Project Object> ->

AddCapturePattern (<State Index>, <Pattern Type Enum>, <Direction of
Pattern>,
<Sub channel direction of pattern>, <Pointer to Error Code>);

Inputs int nStateId: ID for a state in advanced mode and Capture ID

PatternTypeEnum ePatternType: Pattern Type Index

VARIANT *vtDirection: Direction of Pattern
(This variant comes from a ByteArray type. This ByteArray Type contains
direction of all Boards as byte)

VARIANT *vtSubChannelDirection: Sub Channel Direction of the pattern
(This variant comes from a ByteArray type. This byte array contains sub channel
directions of all boards as bytes.
This parameter is for the Muxing feature. If the Muxing feature is disabled, then
insert zero to the byte array for the subchannel directions. Size of this array is
equal to the size of Direction array.)

Long *lErrorCode: Saves the error code if any error occurs.

Return Value Returns the index of Added pattern.

Description Adds a pattern to Capture (Pre or Post) in easy mode or a state in advanced

mode, specified by its ID, and returns the new added pattern index and error
code if error occurs. If you want to change default strategy of capturing
(Everything), use this function to add a pattern to capturing items. You can
change the parameter value after adding a pattern by other functions, and then
call UpdateHardwareResource to assign related resources to the added pattern.

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Using Analyzer API 64

The following table lists the Patttern Types for the PatternTypeEnum Option (for Capture
Pattern) and their corresponding functions to set the required parameters:

PatternTypeEnum Index Functions to set parameters

ID_PATTERN_TYPE_FIS

ID_PATTERN_TYPE_FIS_PATTERN

(STP Frame)

ID_PATTERN_TYPE_ADDRESS_FRA
ME

(Address Frame)

ID_PATTERN_TYPE_SMP_FRAME

(SMP Frame)

ID_PATTERN_TYPE_SSP_FRAME

(SSP Frame)

SetFISCapturePattern ()

SetCapturePatternParameterValu
eBy
OptionId ()

SetCapturePatternDirection ()

SetAddressFrameCapturePattern
()

SetCapturePatternDirection ()

SetSMPFrameCapturePattern ()

SetCapturePatternDirection ()

SetSSPFrameCapturePattern ()

SetCapturePatternDirection ()

SetCapturePatternSSPCDBType ()

SetCapturePatternSSPDataPres ()

SetCapturePatternSSPUseHashAdr
ess ()

ID_PATTERN_TYPE_DATA_PATTER
N

(Data Pattern)

ID_PATTERN_TYPE_PROTOCOL_ER
RORS

(Protocol Errors)

SetDataCapturePattern ()

SetCapturePatternDataOffset ()

SetCapturePatternDirection ()

SetCapturePatternIsNot ()

SetCapturePatternParameterValu
e ()

SetProtocolErrorCapturePattern ()

SetCapturePatternDirection ()
SetCapturePatternParameterValu
e ()

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Using Analyzer API 65

Remove a Capture Pattern

To remove an added capture pattern, call the RemoveCapturePattern () function of the
Capture Project object with the order of its parameters as below.

m_pICaptureProject->RemoveCapturePattern (nStateId,

lPatternIndex, bUpdateResource);

CSerialSCSICaptureProject::RemoveCapturePattern ()

Prototype BOOL RemoveCapturePattern (int nStateId, long lPatternIndex,

BOOL bUpdateResource);

Usage BOOL <Pattern Remove Status> = <Capture Project Object> ->

RemoveCapturePattern (<State Index>, <Pattern Index>,
<Update Resource Status>);

Inputs int nStateId: ID for a state in advanced mode and Capture ID

long lPatternIndex: Pattern Type Index

BOOL bUpdateResource: To set the status for Update Resource

Return Value Returns the success/ failure status of the pattern removal.

Description Removes a pattern from its capture items, by using its index and returns the

result.

NOTE: After adding any packet, if you do not call UpdateHardwareResource to assign a

resource, then to remove it bUpdateResource should be set to TRUE. Otherwise, FALSE.

Exclude/Include Specific Pattern Items

To exclude any specific pattern items, their respective method calls need to be made with their
corresponding parameters:

Pattern Item Function Name

Exclude SATA_CONT SetExcludeCONT ()

Exclude SATA_SYNC SetExcludeSYNC ()

Exclude OOB Signals SetExcludeOOBSignals ()

Exclude XXXX SetExcludeXXXX ()

Exclude ALIGN SetExcludeALIGN ()

Exclude RRDY SetExcludeRRDY ()

Exclude NOTIFY SetExcludeNOTIFY ()

Exclude Idle SetExcludeIdle ()

Exclude Payload Except SetExcludePayloadOffset ()

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Using Analyzer API 66

Example:

m_pICaptureProject->SetExcludeCONT (nStateId, bIsExclude);

CSerialSCSICaptureProject::SetExcludeCONT ()
SetExcludeSYNC ()
SetExludeOOBSignals ()
SetExcludeXXXX ()
SetExludeALIGN ()
SetExcludeRRDY ()
SetExcludeNOTIFY ()
SetExcludeIdle ()

Prototype HRESULT <Function Name> (int nStateId, BOOL bIsExclude);

Usage <Capture Project Object> -> <Function Name> (<State Index>,

<Is Exclude Checked>);

Inputs int nStateId: ID for a state in advanced mode and Capture ID in easy mode

BOOL bIsExclude: Specifies whether Exclude check for a particular pattern
is set or not

Return Value None

Description Call the respective functions to set whether a particular pattern must be

excluded from the sample or not.

NOTE: Function prototype and usage for all the abovef functions are the same, except for the

Payload Offset pattern:

CSerialSCSICaptureProject::SetExcludePayloadOffset

Prototype HRESULT SetExcludePayloadOffset (int nStateId, WORD wExcludePayloadOffset);

Usage <Capture Project Object> -> SetExcludePayloadOffset (<State Index>,

<Offset to exclude>);

Inputs int nStateId: ID for a state in advanced mode and Capture ID in easy mode

WORD wExcludePayloadOffset: Offset that defines data payload to exclude
frdata packet

Return Value None

Description Call the SetExcludePayloadOffset () function to set the offset to

exclude from the data packet.

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Using Analyzer API 67

Set Memory Usage Parameters

Memory usage parameters can be categorized into four sub sections:

• Put Entire Memory

• Put Partial Memory

• Put Segmented memory

• Set Trigger position in memory

Put Entire Memory

To put entire memory for sample collection, use put_IsEntireMemory () function of the SCSI
capture project with set-status (TRUE/ FALSE) as its parameter

m_ISASCaptureProject->put_IsEntireMemory (TRUE);

CSerialSCSICaptureProject::Put_IsEntireMemory ()

Prototype HRESULT put_IsEntireMemory (BOOL bNewVal);

Usage <Capture Project Object> -> put_IsEntireMemory (<Is Entire memory

Checked>);

Inputs BOOL bNewVal: Specifies the request status for Entire memory

Return Value None

Description Call the put_IsEntireMemory () function with TRUE to set entire memory,

and FALSE for not to set entire memory.

Put Segmented Memory

To divide entire memory into individual segments of specified size, first set number of segments
for memory division and then set each segment’s buffer size.

m_ISASCaptureProject->put_NumberOfSegment (lNumberOfSegments)
m_ISASCaptureProject->put_SegmentBufferSize

(lSegmentBufferSize);

CSerialSCSICaptureProject::Put_NumberOfSegment ()

Prototype HRESULT put_NumberOfSegment (long lNewVal);

Usage <Capture Project Object> -> put_NumberOfSegment (<Number of Segments>);

Inputs long lNewVal: Number of segments that entire memory to be divided

Return Value None

Description Call the put_NumberOfSegment () function to set number of segments for

dividing
entire memory into individual segmented memory buffers.

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Using Analyzer API 68

CSerialSCSICaptureProject::Put_SegmentBufferSize ()

Prototype HRESULT put_SegmentBufferSize (long lNewVal);

Usage <Capture Project Object> -> put_SegmentBufferSize (<Segment buffer size in

long>);

Inputs long lNewVal: Size of each segment’s buffer in KBs

Return Value None

Description Call the put_SegmentBufferSize () function to set size of individual segment

buffer

Put Partial Memory

To set partial memory for sample collection, use the put_PartialMemory () function of SCSI
capture project with an Integer value of memory size as its parameter.

(Refer to TestCaptureProject -> TestCaptureProjectView.cpp ->
OnRunButton ().)

m_pICaptureProject->put_PartialMemory (m_nMemorySize);

CSerialSCSICaptureProject::put_PartialMemory ()

Prototype HRESULT put_PartialMemory (long lNewVal);

Usage <Capture Project Object> -> put_PartialMemory (<long value of memory size>);

Inputs long lNewVal: Size of partial memory to be considered for sample extraction

Return Value None

Description Call the put_PartialMemory () function to set size of memory for sample

extraction.

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Using Analyzer API 69

Set Trigger Position in Memory

To set the trigger position in memory, call the put_TrigPosition () function of SCSI capture
project with percentage of pre-memory size as its parameter.

(Refer to TestCaptureProject -> TestCaptureProjectView.cpp ->
OnRunButton ().)

m_pICaptureProject->put_TrigPosition
(m_nPercentOfPreMemorySize);

CSerialSCSICaptureProject::put_TrigPosition ()

Prototype HRESULT put_TrigPosition (short sNewVal);

Usage <Capture Project Object> -> put_TrigPosition (<Percentage of Memory Size>);

Inputs short sNewVal: Percentage of pre-memory size in short integer terms

Return Value None

Description Call the put_TrigPosition () function to set the position of the trigger in memory

as per the input of percentage of pre-memory size.

Set Output Sample File Path

To set path of a sample file, call the put_OutputFile () function of the SCSI Capture Project.
(Refer to TestCaptureProject -> TestCaptureProjectView.cpp ->

OnRunButton ().)

m_pICaptureProject->put_OutputFile (bstrFileName);

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Using Analyzer API 70

CSerialSCSICaptureProject::put_OutputFile ()

Prototype HRESULT put_OutputFile (BSTR bstrVal);

Usage <Capture Project Object> -> put_OutputFile (<BSTR form of sample file path>);

Inputs BSTR bstrVal: Output sample file path in BSTR format

Return Value None

Description Call the put_OutputFile () function to set the file path of the output sample.

Set Port Configuration

To set port configuration for an Analyzer capture project, call the SetDeviceType () function of
the SCSI capture project with Device Index and Device Type as its two required parameters, in
that order. An optional third parameter accommodates an Integer pointer for returning Error
codes in case of any failures.

m_ISASCaptureProject->SetDeviceType (nDeviceIndex, eDeviceType);

CSerialSCSICaptureProject::SetDeviceType ()

Prototype HRESULT SetDeviceType (int nDeviceIndex,

DeviceConfigurationTypeEnum eDeviceType, int* pErrorCode);

Usage <Capture Project Object> -> SetDeviceType (<Selected Device Index>,

<Selected Device Type>, <Pointer to Error Code>);

Inputs int nDeviceIndex: Index of the attached device

DeviceConfigurationTypeEnum eDeviceType: Specifies that each port
has a kind of functionality.
For example with device type DEVICE_CONFIG_A_A_HE_HE, it specifies that first
& second ports are of Analyzer and Third & Fourth ports belong to Host/
Initiator Emulator.

Return Value Returns CEI_OK in case of method success. Otherwise, an error code.

Description Call the SetDeviceType () function to set/ modify port functionality for each

attached unit before running the project.

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Using Analyzer API 71

Summary

Using an Analyzer API involves a stage-by-stage process of Create, Run, Open, and Modify of an
Analyzer capture project, which can be summarized into a tabular form as given below.

Stages involved in using
Analyzer API

Create a NEW Analyzer
Capture Project

Initialize a Capture Project
Object

Create a New Analyzer Capture
Project

Run, Stop and Extract Sample

Run the Capture Project

Corresponding Function calls

CSerialSCSICaptureProject::CreateInstance ()

CSerialSCSICaptureProject::New ()

CSerialSCSICaptureProject::Run ()

CWnd::SetTimer ()

OnTimer ()

Stop the Analyzer Capture
Project

Upload and Create Sample File

Open a Saved Analyzer
Capture Project

Open an Analyzer Capture
Project

Modify an Existing Analyzer
Capture Project

Modify Trigger / Condition

CSASGeneralService::HalAnalyzerStop ()

CSerialSCSIExtraction::put_AnalyzerSpeed ()

CSerialSCSIExtraction::SetAnalyzerLinkEnable ()

CSerialSCSIExtraction::DumpAndExtract ()

CSerialSCSICaptureProject::Open ()

CSerialSCSICaptureProject::SetTrigStrategy ()

CSerialSCSICaptureProject::AddConditionExprPattern
()

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Using Analyzer API 72

Expression

CSerialSCSICaptureProject::RemoveConditionExpr

Modify Capture

Set Trigger Position in memory

Set Partial Memory

Set Segmented Memory

Set Output File Name

Set Port Configuration

Pattern ()

CSerialSCSICaptureProject::SetCaptureStrategy ()

CSerialSCSICaptureProject::AddCapturePattern ()

CSerialSCSICaptureProject::RemoveCapturePattern ()

CSerialSCSICaptureProject::put_TrigPosition ()

CSerialSCSICaptureProject::put_PartialMemory ()

CSerialSCSICaptureProject::put_NumberOfSegment ()

CSerialSCSICaptureProject::put_SegmentBufferSize ()

CSerialSCSICaptureProject::put_OutputFile ()

CSerialSCSICaptureProject::SetDeviceType ()

Using Initiator/Host Em ula t or API Functions

Two emulators are in the SAS/SATA Protocol Suite or STX software: Initiator Emulator and
Target Emulator.

To use APIs of initiator, you must create an instance of Exerciser Capture Project and then you
can create a new Exerciser Capture project or open a saved one. After these steps it can be
modified and run like an Analyzer Capture Project.

• Initialize an Initiator capture project object

• Create a new Initiator capture project

• Run, stop, and create sample for an Initiator capture project

• Open a saved Initiator capture project

• Modify an existing Initiator capture project

o Add/insert a packet in Initiator

 Add/insert ATA Command Packet
 Add/insert SCSI Command Packet
 Add/insert TASK Command Packet
 Add/insert SMP Command Packet

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

73

 Add/insert Frame Packet

o Add/insert events in Initiator

o Add/insert an instruction in Initiator

o Remove/delete an inserted packet
o Remove/delete an inserted instruction

o Error injection on packets in Initiator

 Protocol errors and command settings
 Error injection on outgoing frame
 Error injection on incoming frame
 Error injection on outgoing open error

• Summary

Initialize an Initiator Capture Project Object

Because Host Emulator is embedded in the capture project, to initialize an Initiator capture
project, declare a smart pointer to the SerialSCSICaptureProject and create its instance using
the CreateInstance () function.

(Refer to: ATAPISample -> ATAPISampleDoc.cpp -> OnNewDocument ().)

m_pICaptureProject.CreateInstance(__uuidof(SerialSCSICaptureProje
ct))

Function Prototypes and Descriptions

(Refer to Create Instances of the two objects just declared in the main class of your application
for prototype and description of CreateInstance ().)

Create a New Initiator Capture Project

To create a new capture project, call the “New ()” function of capture project object with
project type (ANALYZER_EXERCISER) as its only parameter.

(Refer to ATAPISample -> ATAPISampleDoc.cpp -> OnNewDocument ().)

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Using Initiator/Host Emulator API Functions 74

m_pICaptureProject->New (ID_PROJECT_TYPE_ANALYZER_EXERCISER);

Function Prototypes and Descriptions

(Refer to Create a New Analyzer Capture Project for prototype and description of
CSerialSCSICaptureProject::New ().)

Run, Stop and Create-Sample for an Initiator Capture Project

To run the newly created capture project, call the Run () function of the Capture Project object
and use the SetTimer () function to check the running status of the hardware in regular
intervals.

(Refer to ATAPISample -> ATAPISampleView.cpp -> OnRunButton ().)

m_pICaptureProject->Run ();

SetTimer (IDT_RUN, 1000, NULL);

To manage the running status conditions, declare and implement an OnTimer () function that
includes hardware status checking functions of the SAS General Service Object, such as
IsHWRunning () and IsHWTriggered ().

(Refer to ATAPISample -> ATAPISampleView.cpp -> OnTimer ().)

To stop the running hardware, kill the timer by calling the KillTimer () function with the same
event index, and then call the HalAnalyzerStop () function of the SAS General Service Object to
finally bring the hardware to halt.

(Refer to ATAPISample -> ATAPISampleView.cpp -> OnTimer () /
OnStopButton ().)

KillTimer (IDT_RUN);

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Using Initiator/Host Emulator API Functions 75

theApp.m_pIGeneralService->HalAnalyzerStop ();

To upload and create the sample, first create an instance of SerialSCSIExtraction.
(Refer to ATAPISample -> ATAPISampleView.cpp -> OnTimer ().)

ISerialSCSIExtractionPtr IExtraction;
IExtraction.CreateInstance (__uuidof (SerialSCSIExtraction));

Next, set some extraction features, such as Speed and Links. To set the analyzer speed, use
get_AnalyzerSpeed () of Capture Project, put_AnalyzerSpeed () of Extraction.

m_pICaptureProject->get_AnalyzerSpeed (nIndex,

&eAnalyzerSpeed);
IExtraction->put_AnalyzerSpeed (nIndex, eAnalyzerSpeed);

To set the Analyzer link enable status, use GetLinkIsEnable () of Capture project and
SetAnalyzerLinkEnable () of Extraction.

m_pICaptureProject->GetLinkIsEnable (nIndex);
IExtraction->SetAnalyzerLinkEnable (nIndex/2,
m_pICatureProject -> GetProjectType (),

abLinkIsEnable [0], abLinkIsEnable [1]);

After that, upload and create the sample, by calling the DumpAndExtract () function of the
Extraction object with the sample file path string as its only parameter.

IExtraction->DumpAndExtract (m_pICaptureProject->GetOutputFile

());

Function Prototypes and Descriptions:

(Refer to Run an Analyzer Capture Project , Stop an Analyzer Capture Project, and Upload and

create sample file for prototypes and descriptions of all the methods involved in Run, Stop, and

Create-Sample functionalities.)

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Using Initiator/Host Emulator API Functions 76

Open a Saved Initiator Capture Project

To open a saved capture project, call the Open () function of the capture project object with File
path and Error code as IN and OUT parameters, respectively.

(Refer to ATAPISample -> ATAPISampleView.cpp -> OnFileOpen ().)
m_pICaptureProject->Open (bstrFileName, NULL, FALSE);

CSerialSCSICaptureProject::Open ()

Prototype long Open (BSTR bstrFileName, IDataBlocks *pIDB, long bDoneConvertIfNeeded);

Usage <Capture Project object> -> Open (<BSTR form of Project File name>, NULL,

FALSE);

Inputs BSTR bstrFileName: Path of the project file

IDataBlocks *pIDB: Pointer of DataBlocks that must be correct in
Analyzer/ Exerciser Project

Long bDoneConvertIfNeeded: If saved project is in X1, X2 or X4, and you want to
open in another type, sometimes you must delete some pattern or direction of a
pattern. If bDoneConvertIfNeeded is TRUE, this item will be deleted. Otherwise,
an error code is returned by the Open function.

Return Value If this method succeeds, the return value equals CEI_OK.

Otherwise, the return value equals to the status error code.

Description Call the Open () method to open a saved analyzer project.

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Using Initiator/Host Emulator API Functions 77

Modify an Initiator Capture Project

To use special functions of the host exerciser, get the Exerciser interface from the capture
project. To use APIs of Initiator, you need an interface of the exerciser engine. First define an
object of the Exerciser engine interface and then call GetExerciserInterface ().

To use the exerciser engine, you must set the Data Block object to the exerciser engine by
calling SetDataBlock ().

(Refer to ATAPISample -> ATAPISampleDoc.h -> CATAPISampleDoc ().)
(Refer to ATAPISample -> ATAPISampleDoc.cpp -> OnNewDocument ().)

IExerciserEnginePtr m_pExerciserEngine;
m_pExerciserEngine = m_pICaptureProject->GetExerciserInterface

();
m_pExerciserEngine -> SetDataBlock (theApp.m_pDataBlocks);

CSerialSCSICaptureProject::GetExerciserInterface ()

Prototype IDispatchPtr GetExerciserInterface (void);

Usage <Exerciser Engine Object> = <Capture Project Object> -> GetExerciserInterface ();

Inputs None

Return Value Returns a pointer to exerciser engine interface to use all of its special functions

meant for Host Emulator

Description Call the GetExerciserInterface () method of SCSI Capture Object to get the

interface of exerciser engine.

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Using Initiator/Host Emulator API Functions 78

CExerciserEngine::SetDataBlock ()

Prototype long SetDataBlock (IDataBlocks *pIDB);

Usage <Exerciser Engine object> -> SetDataBlock

(<Pointer to an interface of CDataBlocks of DBELib>);

Inputs IDataBlocks* pIDB: Pointer to an Interface of CDataBlocks of DBELib

Return Value None

Description Call the SetDataBlock () method to set a DataBlocks interface for engine.

Add/ Insert a packet in Initiator

To add in initiator packet, call the InsertPacket () function of Exerciser Engine.

Types of the packets include ATA Packets, SCSI Packets, TASK Packets, SMP Packets, and
Frames.

(Refer to ATAPISample -> AddATAPIDlg.cpp -> OnOK ().)

int nRetVal = m_pExerciserEngine ->InsertPacket(nIndex, iLayerId,
iFormatId, bstrName);

CExerciserEngine::InsertPacket ()

Prototype HRESULT InsertPacket (int nIndex, short iLayerId, short iFormatID,

BSTR bstrName int* pRetVal);

Usage int nRetVal = <Exerciser Engine Object> -> InsertPacket

(< Packet Index>, <Layer Index of a packet>,
<Current Selected Command Format>, <Name of the Packet Type>);

Inputs Int nIndex: Object Index to insert packet in that position

Z
Short iLayerId: Layer Index of the current command packet
(Refer to SASLayerEnum.)

Short iFormatID: Format or Type of the packet
For SCSI Commands, refer to SCSICommandsEnum
For SMP Commands, refer to SMPFrameFunctionsEnum
For Task Commands, refer to SSPTaskManagementEnum

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Using Initiator/Host Emulator API Functions 79

For ATA Commands, refer to CommandTypeEnum
For ATAPI packets, use PACKET Command type of
CommandTypeEnum
combined with SCSI Command type of SCSICommandEnum
To insert a Transport Frame, refer to ExrTransportFrameTypeEnum
To insert an Identify Frame, use
ID_ADDRESS_FRAME_TYPE_IDENTIFY

BSTR bstrName: Name of the packet

Return Value Returns success/ failure status of the method with verification parameters as

Index and LayerID of the packet.

Description Call the InsertPacket () method of Exerciser Engine to add/ insert any packet in

an index with default value in a layer.

Examples of InsertPacket () functionality for each packet type (ATA/ SCSI/ SMP/ Task/ Frame)
are below.

Add/ Insert ATA Command Packet

Usage int nRetVal = <Exerciser Engine Object> -> InsertPacket

(<Packet Index>, LAYER_ATA_COMMAND, <Current Selected Command Format>,
<Name of the Packet Type>);

Example: int nRetVal = m_pExerciserEngine->InsertPacket (

nIndex, LAYER_ATA_COMMAND, READ_DMA_EXT, "PACKET");

Add/ Insert SCSI Command Packet

Usage int nRetVal = <Exerciser Engine Object> -> InsertPacket

(<Packet Index>, LAYER_SCSI_COMMAND, <Current Selected Command Format>,
<Name of the Packet Type>);

Example: int nRetVal = m_pExerciserEngine->InsertPacket (

nIndex, LAYER_SCSI_COMMAND,SPC3_INQUIRY,"PACKET");

Add/ Insert TASK Command Packet

Usage int nRetVal = <Exerciser Engine Object> -> InsertPacket

(<Packet Index>, LAYER_TASK_COMMAND,
<Current Selected Command Format>, <Name of the Packet Type>);

Example: int nRetVal = m_pExerciserEngine->InsertPacket (

nIndex, LAYER_TASK_COMMAND,
ID_SSP_FRAME_TASK_MANAGEMENT_FUNCTION_ABORT_TASK,
"PACKET");

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Using Initiator/Host Emulator API Functions 80

Add/ Insert SMP Command Packet

Usage int nRetVal = <Exerciser Engine Object> -> InsertPacket

(<Packet Index>, LAYER_SMP_COMMAND,
<Current Selected Command Format>, <Name of the Packet Type>);

Example: int nRetVal = m_pExerciserEngine->InsertPacket (

nIndex, LAYER_SMP_COMMAND,
ID_SMP_FRAME_TYPE_FUNCTION_REPORT_GENERAL,
"PACKET");

Add/ Insert Frame Packet

Usage: int nRetVal = <Exerciser Engine Object> -> InsertPacket

(<Packet Index>, LAYER_TRANSPORT,
<Current Selected Command Format>, <Name of the Packet Type>);

Example: int nRetVal = m_pExerciserEngine->InsertPacket (

nIndex, LAYER_TRANSPORT,
EXR_TRANSPORT_FRAME_TYPE_STP_DMA_ACTIVE,
"PACKET");

Add/ Insert Events in Initiator

To add/ insert events in initiator, call the InsertInstruction () function of Exerciser Engine with
Packet Index and Event/Instruction type as parameters.

int nRetVal = m_pExerciserEngine­>InsertInstruction(nIndex,nEventType);

CExerciserEngine::InsertInstruction ()

Prototype HRESULT InsertInstruction (int nIndex, int nInstructionType, int* pRetVal);

Usage int nRetVal = <Exerciser Engine Object> -> InsertInstruction

(<Packet Index>, <Event/ Instruction Type ID>);

Inputs Int nIndex: Object Index to insert packet in that position

Int nInstructionType: Index of the exerciser event/ instruction type to be
added or inserted at the specified index

Return Value Returns success/ failure status of the method with verification parameters as

Index and Event/Instruction type.

Description Call the InsertInstruction () of Exerciser Engine to add/insert any

event/ instruction at the index specified as the first parameter of the function.

List of Event types include:

PS Request (SAS Only), PS Response (SAS Only), Wake Up, OOB Signal, Primitive, Attach, Detach,
Power On, Power Off, Self Test Exit (SATA Only), PM Response (SATA Only), PM Request (SATA
Only), Soft Reset (SATA Only).

(Refer to CEIStorageConstants.h to view their respective IDs.)

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Using Initiator/Host Emulator API Functions 81

Example

To use InsertInstruction functionality according to the above mentioned Event types:

int nEventType = INSTRUCTION_TYPE_PRIMITIVE // For Primitive
int nRetVal = m_pExerciserEngine-

>InsertInstruction(nIndex,nEventType);

FOR SAS

// PS Request - INSTRUCTION_TYPE_SATA_POW_MNG
// PS Response - INSTRUCTION_TYPE_SATA_PM_RESPONSE
// Wake Up - INSTRUCTION_TYPE_SATA_WAKE_UP
// OOB Signal - INSTRUCTION_TYPE_OOB_SIGNAL
// Primitive - INSTRUCTION_TYPE_PRIMITIVE
// Attach - INSTRUCTION_TYPE_ATTACH
// Detach - INSTRUCTION_TYPE_DETACH
// Power ON - INSTRUCTION_TYPE_POWER_ON

// Power OFF - INSTRUCTION_TYPE_POWER_OFF

FOR SATA
// Self Test Exit - INSTRUCTION_TYPE_SATA_EXIT_SELF_TEST
// PM Request - INSTRUCTION_TYPE_SATA_POW_MNG
// PM Response - INSTRUCTION_TYPE_SATA_PM_RESPONSE
// Wake Up - INSTRUCTION_TYPE_SATA_WAKE_UP
// Soft Reset - INSTRUCTION_TYPE_SATA_SOFT_RESET
// OOB Signal - INSTRUCTION_TYPE_OOB_SIGNAL

// Primitive - INSTRUCTION_TYPE_PRIMITIVE
// Attach - INSTRUCTION_TYPE_ATTACH

// Detach - INSTRUCTION_TYPE_DETACH

// Power ON - INSTRUCTION_TYPE_POWER_ON

// Power OFF - INSTRUCTION_TYPE_POWER_OFF

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Using Initiator/Host Emulator API Functions 82

Add/ Insert an Instruction in Initiator

To add/insert instructions (for Control Structures) in initiator, call the InsertInstruction ()
function of Exerciser Engine with Packet Index and Event/Instruction type as parameters.

int nRetVal = m_pExerciserEngine­>InsertInstruction(nIndex,nEventType);

Function Prototypes and Descriptions:

(Refer to Section 2.5.5.1 for prototype, usage, and description of InsertInstruction method.)

List of Instruction types include:

Loop Start, Loop End, Go To, IF Last Received Frame, IF Last Handshake, IF Device Type, IF
Payload, IF Last Command Status, IF Aborted NCQ Command, IF Host Queue Count, IF PS
Request (SAS Only), IF PM Request (SATA Only), Wait For any Frame, Delay, Stop.

(Refer to CEIStorageConstants.h, CEIEngineLibConstants.h to view their respective IDs.)

Example

To use InsertInstruction functionality according to the above mentioned Instruction types:

int nEventType = INSTRUCTION_TYPE_END_LOOP // For End Loop

int nRetVal = m_pExerciserEngine->InsertInstruction(nIndex,nEventType);

// Loop Start - INSTRUCTION_TYPE_SATRT_LOOP
// Loop End - INSTRUCTION_TYPE_END_LOOP
// Go To - INSTRUCTION_TYPE_GO_TO
// IF - INSTRUCTION_TYPE_IF
// Last Received Frame - INSTRUCTION_TYPE_IF_LAST_FRMAE
// Last Handshake - INSTRUCTION_TYPE_IF_LAST_HANDSHAKE
// Device Type - INSTRUCTION_TYPE_IF_DEVICE_TYPE
// Payload - INSTRUCTION_TYPE_IF_PAYLOAD_BUFFER
// Last Command Status - INSTRUCTION_TYPE_IF
// Aborted NCQ Command - INSTRUCTION_TYPE_IF_ABORT_NCQ_COMMAND
// Host Queue Count - INSTRUCTION_TYPE_IF_HOST_QUEUE_COUNT
// PS Request (SAS) - INSTRUCTION_TYPE_SATA_IF_PM_REQUEST
// PM Request (SATA) - INSTRUCTION_TYPE_SATA_IF_PM_REQUEST
// Wait For Any Frame - INSTRUCTION_TYPE_WAIT_FOR_FRAME
// Delay - INSTRUCTION_TYPE_DELAY
// Stop - INSTRUCTION_TYPE_STOP

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Using Initiator/Host Emulator API Functions 83

Remove/Delete an Inserted Packet

To remove/delete an inserted packet from initiator, call the DeletePacket () function of
Exerciser Engine with Packet layer type and Packet Index in Layer as parameters, in the same
order as below.

int nRetVal = m_pExerciserEngine -> DeletePacket(iLayerType,
nPacketIndexInLayer);

CExerciserEngine::DeletePacket ()

Prototype HRESULT DeletePacket (short iLayerType, int nPacketIndexInLayer, int* pRetVal);

Usage int nRetVal = <Exerciser Engine Object> -> DeletePacket

(<Packet Layer Type>, <Index of insertion of packet in the layer>);

Inputs Short iLayerType: Layer ID of the packet (Refer to SASLayerEnum.)

Int nPacketIndexInLayer: Index of a packet corresponding to layer ID

Return Value Returns success/ failure status of the method with verification parameters as

Layer ID and Packet-Index-in-layer.

Description Call the DeletePacket () of Exerciser Engine to remove/delete any inserted

packet at the index specified as the second parameter of the function.

Remove/Delete an Inserted Event/Instruction

To remove/ delete an inserted Event/Instruction from initiator, call the DeleteInstruction ()
function of Exerciser Engine with Index of insertion as its only parameter.

int nRetVal = m_pExerciserEngine -> DeleteInstruction(nIndex);

CExerciserEngine::DeleteInstruction ()

Prototype HRESULT DeleteInstruction (int nIndex, int* pRetVal);

Usage int nRetVal = <Exerciser Engine Object> ->

DeleteInstruction (<Index of insertion of packet in the layer>);

Inputs Int nIndex: Index of a packet corresponding to layer ID

Return Value Returns success/failure status of the method in the form of an error code.

Description Call the DeleteInstruction () of Exerciser Engine to remove/ delete any inserted

event/ instruction at the index specified as the parameter of the function.

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Using Initiator/Host Emulator API Functions 84

Error Injection on Packets in Initiator

To set an Error Injection on packets in Initiator, get an Instance of Initiator Error Injection
Interface. First, declare an Instance variable for the initiator Error Injection, and then Query it
using the QueryInterface () function of the Exerciser Engine.

(Refer to ATAPISample -> ATAPISampleDoc.h -> CATAPISampleDoc ().)
(Refer to ATAPISample -> ATAPISampleDoc.cpp -> OnNewDocument ().)

IInitiatorExerciserErrorInjection
*m_pIInitiatorExerciserErrorInjection;
m_pExerciserEngine-> QueryInterface (
__uuidof(IInitiatorExerciserErrorInjection),
&m_pIInitiatorExerciserErrorInjection);

After obtaining a hold to the Error Injection interface, use its methods to set Error Injection on
Outgoing frames, on Incoming frames, and on Outgoing Open Error.

QueryInterface ()

Prototype HRESULT QueryInterface (REFIID riid, void** ppv);

Usage <Exerciser Engine Object> -> QueryInterface (__uuidof (<Interface Name>),

<Reference to the Interface variable>);

Inputs REFIID riid: ID of a reference object of an Interface

Void** ppv: Void reference to hold the instantiated address of the interface

Return Value None

Description Call QueryInterface () to query the Initiator Error Injection Interface.

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Using Initiator/Host Emulator API Functions 85

Protocol Errors and Command Settings

To set protocol errors and command settings for an Initiator Packet, build a dialog with basic
required fields, such as Connection Rate, Trigger Source, External Trigger Out, Retry Count,
Random Error Injection Percentage, Close Connection Settings, Outgoing Frame Error Injection
Settings, Incoming Frame Error Injection Settings, and Outgoing Open Error Settings.

(Refer to ATAPISample -> ErrorInjectionDlg.h ().)
(Refer to ATAPISample -> ErrorInjectionDlg.cpp ().)

To popup and use the Error Injection Dialog, create an object of the CErrorInjectionDlg class.
Using that object, display the dialog with the help of DoModal function of CDialog class.

(Refer to ATAPISample -> ATAPISampleView.cpp -> OnInitialUpdate ().)
(Refer to ATAPISample -> ATAPISampleView.cpp ->

OnErrorInjectionButtonClick ().)
CErrorInjectionDlg *pErrorInjectionDialog = new

CErrorInjectionDlg ();
pErrorInjectionDialog ->DoModal();

A general Error Injection Dialog looks like this:

Error Injection Dialog specific from ATAPISample is shown here below:

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Using Initiator/Host Emulator API Functions 86

Out of all the required fields for an Error Injection Dialog, the three most-required features are
Error Injection on Outgoing Frame, Error Injection on Incoming Frame, and Error Injection on
Outgoing Open Error.

Error Injection on Outgoing Frame

To set Error Injection on an Outgoing frame, first set its corresponding attributes using the
SetOutgoingErrorAttribute () function of the Initiator Error Injection interface.

(Refer to ATAPISample -> ErrorInjectionDlg.cpp -> OnOKErrorInjection

().)
m_pIInitiatorExerciserErrorInjection -> SetOutGoingErrorAttribute

(
iLayerID, nPacketIndexInLayer, m_OutgoingCheck,
m_nOutgoingFrameType,
m_OutgoingFrameNumber);

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Using Initiator/Host Emulator API Functions 87

After setting the Outgoing error attributes, start with setting Error Injection on each of the
Outgoing frame options, such as Frame Type error, Frame Length Error, SOF Error, EOF Error,
CRC Error, Remove Frame From Sequence, Code Violation Error, Disparity Error, Insert Primitive,
Delay in Sending Frame, No WTRM, Code Violation on SATA Primitive, Disparity Error on SATA
Primitive, Ignore XRDY/RRDY sequence, Delay in HOLD Response, and Fill Byte for Reserved
Fields.

Each of the above options has a respective method call for Error Injection:

Outgoing Frame Error

Function Name

Injection Options

Frame Type Error ErInjSetFrameErrorType ()

Frame Length Error ErInjSetFrameLengthError ()

SOF Error ErInjSetSOFError ()

EOF Error ErInjSetEOFError ()

CRC Error ErInjSetCRCError ()

Remove Frame From Sequence ErInjSetOmitFrameFromSequence ()

Code Violation Error ErInjSetCodeViolationError ()

Disparity Error ErInjSetDisparityError ()

Delay in Sending Frame ErInjSetSendingFrameDelay ()

No WTRM ErInjSetNoWTRM ()

Code Violation on SATA
Primitive

Disparity Error on SATA
Primitive

ErInjSetCodeViolationOnSATAPrimitive
()

ErInjSetDisparityErrorOnSATAPrimitive
()

Ignore XRDY/RRDY sequence ErInjSetIgnoreXRDYorRRDY ()

Delay in HOLD Response ErInjSetDelayResponseToHold ()

Fill Byte for Reserved Fields ErInjSetFillByteForReservedField ()

Insert Primitive ErInjSetInsertPrimitive ()

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Using Initiator/Host Emulator API Functions 88

Example

m_pIInitiatorExerciserErrorInjection-> ErInjSetFrameErrorType (
iLayerID, nCommandIndex,
m_bFrameType, &nErrorCode);

CExerciserEngine::SetOutGoingErrorAttribute ()

Prototype HRESULT SetOutGoingErrorAttribute (short iLayerId, int nPacketIndexInLayer,

BOOL bEnable, int nFrameType, short iFrameNumberInCommand,
int *pnErrorCode);

Usage <Initiator Error Injection Interface Object> -> SetOutGoingErrorAttribute

(<layer ID of the packet>, <Index of the packet n layer>,
<Boolean to set error injection or not>, <Frame Type>,
<Frame Number in the command list>);

Inputs Short iLayerId: layer ID of the packet

Int nPacketIndexInLayer: Index of the packet in layer

BOOL bEnable: Specifies whether to enable error injection on outgoing frame or
not

Int nFrameType: Type of the frame to set error injection

Short iFrameNumberInCommand: Number of the frame in command list

Return Value Returns success/ failure status of the method in the form of an error code.

Description Call SetOutGoingErrorAttribute () of Exerciser Engine to set all required

parameters before setting Error Injection for individual out going frame options.

Below are the function prototypes corresponding to every option of Error Injection on an
Outgoing Frame:

STDMETHOD (ErInjSetDelayResponseToHold) (

/*[in]*/short iLayerId, /*[in]*/int

nPacketIndexInLayer, /*[in]*/BOOL bEnable,

/*[out]*/int* pnRetVal);

STDMETHOD (ErInjSetNoWTRM) (

/*[in]*/short iLayerId, /*[in]*/int

nPacketIndexInLayer, /*[in]*/BOOL bEnable,

/*[out]*/int* pnRetVal);

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Using Initiator/Host Emulator API Functions 89

STDMETHOD (ErInjSetIgnoreXRDYorRRDY) (

/*[in]*/short iLayerId, /*[in]*/int

nPacketIndexInLayer, /*[in]*/BOOL bEnable,

/*[out]*/int* pnRetVal);

STDMETHOD (ErInjSetFrameErrorType) (

/*[in]*/short iLayerId, /*[in]*/int

nPacketIndexInLayer, /*[in]*/BOOL bEnable,

/*[out]*/int* pnRetVal);

STDMETHOD (ErInjSetSendingFrameDelay) (

/*[in]*/short iLayerId, /*[in]*/int

nPacketIndexInLayer, /*[in]*/BOOL bEnable, /*[in]*/int
nDelayTime,

/*[out]*/ int* pnRetVal);

STDMETHOD (ErInjSetOmitFrameFromSequence) (

/*[in]*/short iLayerId, /*[in]*/int

nPacketIndexInLayer, /*[in]*/BOOL bOmitFrame,

/*[out]*/int* pnRetVal);

STDMETHOD (ErInjSetEOFError) (

/*[in]*/short iLayerId, /*[in]*/int

nPacketIndexInLayer, /*[in]*/EOFErrorTypeEnum
eEOFError,

/*[out]*/int* pnRetVal);

STDMETHOD (ErInjSetSOFError) (

/*[in]*/short iLayerId, /*[in]*/int

nPacketIndexInLayer, /*[in]*/SOFErrorTypeEnum
eSOFError,

/*[out]*/int* pnRetVal);

STDMETHOD (ErInjSetCRCError) (

/*[in]*/short iLayerId, /*[in]*/int

nPacketIndexInLayer, /*[in]*/CRCErrorTypeEnum
eCRCError,

/*[out]*/int* pnRetVal);

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Using Initiator/Host Emulator API Functions 90

STDMETHOD (ErInjSetCodeViolationError) (

/*[in]*/short iLayerId, /*[in]*/int

nPacketIndexInLayer, /*[in]*/BOOL bEnable,

/*[out]*/int* pnRetVal);

STDMETHOD (ErInjSetDisparityError) (

/*[in]*/short iLayerId, /*[in]*/int

nPacketIndexInLayer, /*[in]*/BOOL bEnable,

/*[out]*/int* pnRetVal);

STDMETHOD (ErInjSetInsertPrimitive) (

/*[in]*/short iLayerId, /*[in]*/int

nPacketIndexInLayer, /*[in]*/BOOL bEnable, /*[in]*/int
nPrimitiveType, /*[in]*/PrimitiveTypeEnum
ePrimitiveGroupType, /*[in]*/short
iOffsetFromFrameStart,

/*[in]*/short iRepeatCount, /*[out]*/int*

pnRetVal);

STDMETHOD (ErInjSetFillByteForReservedField) (

/*[in]*/short iLayerId, /*[in]*/int

nPacketIndexInLayer, /*[in]*/ BYTE yFillByte,

/*[out]*/int* pnRetVal);

STDMETHOD (ErInjSetFrameLengthError) (

/*[in]*/short iLayerId, /*[in]*/int

nPacketIndexInLayer, /*[in]*/BOOL bEnable,

FrameLengthErrorTypeEnum eFrameLengthError,

/*[in]*/int nFrameLength,/*[out]*/ int*

pnRetVal);

STDMETHOD (ErInjSetHandshakeError) (

/*[in]*/short iLayerId, /*[in]*/int

nPacketIndexInLayer, /*[in]*/HandshakeErrorTypeEnum
eHandshakeError, /*[in]*/PrimitiveTypeEnum
ePrimitveTypeGroup,

/*[in]*/int nUserDefineHanshakePrimitiveType,

/*[out]*/ int* pnRetVal);

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Using Initiator/Host Emulator API Functions 91

STDMETHOD (ErInjSetSendDelayToSendHandshake) (

/*[in]*/short iLayerId, /*[in]*/int

nPacketIndexInLayer, /*[in]*/BOOL bEnable,

/*[in]*/short iDelayValue,

/*[out]*/ int* pnRetVal);

STDMETHOD (ErInjSetDisparityErrorOnSATAPrimitive) (

/*[in]*/short iLayerId, /*[in]*/int

nPacketIndexInLayer, /*[in]*/BOOL bEnable, /*[out]*/

int* pnRetVal);

STDMETHOD (ErInjSetCodeViolationOnSATAPrimitive) (

/*[in]*/short iLayerId, /*[in]*/int

nPacketIndexInLayer, /*[in]*/BOOL bEnable, /*[out]*/

int* pnRetVal);

Usage <Initiator Error Injection Interface Object> -> <Function Name>

(<Layer ID>, <Packet Index in Layer>, <Option Specific Parameter>,
<Pointer to Integer for return value>);

Return Value None

Description Call the respective functions to set error injection on any particular Outgoing

frame options.

Error Injection on Incoming Frame

To set Error Injection on an InComing frame, first set its corresponding attributes using the
SetInComingErrorAttribute () function of Initiator Error Injection interface.

(Refer to ATAPISample -> ErrorInjectionDlg.cpp -> OnOKErrorInjection

().)
m_pIInitiatorExerciserErrorInjection -> SetIncomingErrorAttribute

(
iLayerID, nPacketIndexInLayer, m_InComingCheck,
m_nIncomingFrameType, m_IncomingFrameNumber);

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Using Initiator/Host Emulator API Functions 92

After setting the Incoming error attributes, start setting Error Injection on each of the InComing
frame options, such as Handshake Errors and Defer Handshake After.

Both of the options have their respective method calls for Error Injection:

InComing Frame Error Injection

Function Name

Options

Handshake Errors ErInjSetHandshakeError ()

Defer handshake After ErInjSetSendDelayToSendHandshake

()

Example

m_pIInitiatorExerciserErrorInjection->ErInjSetHandshakeError (
iLayerID, nCommandIndex, eHandshakeTypeError,
m_ePrimitveTypeGroup, NULL, &nErrorCode);

CExerciserEngine::SetInComingErrorAttribute ()

Prototype HRESULT SetInComingErrorAttribute (short iLayerId, int nPacketIndexInLayer,

BOOL bEnable, int nFrameType, short iFrameNumberInCommand,
int *pnErrorCode);

Usage <Initiator Error Injection Interface Object> -> SetInComingErrorAttribute

(<layer ID of the packet>, <Index of the packet n layer>,
<Boolean to set error injection or not>, <Frame Type>,
<Frame Number in the command list>);

Inputs Short iLayerId: layer ID of the packet

Int nPacketIndexInLayer: Index of the packet in layer

BOOL bEnable: Specifies whether to enable error injection on incoming frame
or not

Int nFrameType: Type of the frame to set error injection

Short iFrameNumberInCommand: Number of the frame in command list

Return Value Returns success/ failure status of the method in the form of an error code

Description Call SetInComingErrorAttribute () of Exerciser Engine to set all required

parameters before setting Error Injection for individual InComing frame
options.

Below are the prototypes for each of the function corresponding to every option of Error
Injection on an InComing Frame

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Using Initiator/Host Emulator API Functions 93

STDMETHOD (ErInjSetHandshakeError) (

/*[in]*/short iLayerId, /*[in]*/int nPacketIndexInLayer,
/*[in]*/HandshakeErrorTypeEnum eHandshakeError,

/*[in]*/PrimitiveTypeEnum ePrimitveTypeGroup,
/*[in]*/int nUserDefineHanshakePrimitiveType,
/*[out]*/int* pnRetVal);

STDMETHOD (ErInjSetSendDelayToSendHandshake) (

/*[in]*/short iLayerId, /*[in]*/int nPacketIndexInLayer,
/*[in]*/BOOL bEnable, /*[in]*/short iDelayValue,

/*[out]*/int* pnRetVal);

Usage <Initiator Error Injection Interface Object> -> <Function Name> (

<Layer ID>, <Packet Index in Layer>, <Option Specific Parameter>,
<Pointer to Integer for return value>);

Return Value None

Description Call the respective functions to set error injection on any particular

InComing frame options.

Error Injection on Outgoing Open Error

To set Error Injection on an Outgoing Open Error frame, call the respective functions of each
option of the Outgoing open error frame dialog.

m_pIInitiatorExerciserErrorInjection ->
SetOutGoingOpenFrameDisparityError (iLayerId,
nPacketIndexInLayer,
bEnable);

Options of Outgoing Open Error Frame include Frame Type Error, SOAF Error, EOAF Error, CRC
Error, Frame Length Error, Code Violation Error, and Disparity Error.

Corresponding function sets for each of the options mentioned above are:

Outgoing Open Error Frame

Function Name

Options

Frame Type Error SetOutGoingOpenFrameTypeError ()

SOAF Error SetOutGoingOpenFrameSOAFError ()

EOAF Error SetOutGoingOpenFrameEOAFError ()

CRC Error SetOutGoingOpenFrameCRCError ()

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Using Initiator/Host Emulator API Functions 94

Frame Length Error SetOutGoingOpenFrameFrameLengthError

()

Code Violation Error SetOutGoingOpenFrameCodeViolationError

()

Disparity Error SetOutGoingOpenFrameDisparityError ()

Code Violation and Disparity
Error

SetOutGoingOpenFrameCodeViolation

AndDisparityErrorAttribute ()

Invalid Fields SetOutGoingOpenFrameInvalidFields ()

Example

m_pIInitiatorExerciserErrorInjection­>SetOutGoingOpenFrameSOAFError (
iLayerId, nCommand,
eSOAFError);

Below are the function prototypes corresponding to every option of Error Injection on an

OutGoing Open Error Frame:

STDMETHOD (SetOutGoingOpenFrameTypeError) (

/*[in]*/ short iLayerID, /*[in]*/ int

nPacketIndexInLayer, /*[in]*/ BOOL bEnable);

STDMETHOD

(SetOutGoingOpenFrameCodeViolationAndDisparityErrorAttribute) (

/*[in]*/ short iLayerId, /*[in]*/ int

nPacketIndexInLayer, /*[in]*/ short
iOffsetFromStartFrame,

/*[in]*/ short iCountOfError);

STDMETHOD (SetOutGoingOpenFrameCodeVioaltionError) (

/*[in]*/ short iLayerId, /*[in]*/ int

nPacketIndexInLayer, /*[in]*/ BOOL bEnable);

STDMETHOD (SetOutGoingOpenFrameDisparityError) (

/*[in]*/ short iLayerId, /*[in]*/ int

nPacketIndexInLayer, /*[in]*/ BOOL bEnable);

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Using Initiator/Host Emulator API Functions 95

STDMETHOD (SetOutGoingOpenFrameFarmeLengthError) (

/*[in]*/ short iLayerId, /*[in]*/ int

nPacketIndexInLayer, /*[in]*/ BOOL bEnable, /*[in]*/

short iFrameLength);

STDMETHOD (SetOutGoingOpenFrameEOAFError) (

/*[in]*/ short iLayerId, /*[in]*/ int

nPacketIndexInLayer, /*[in]*/ EOFErrorTypeEnum
eEOAFError);

STDMETHOD (SetOutGoingOpenFrameSOAFError) (

/*[in]*/ short iLayerId, /*[in]*/ int

nPacketIndexInLayer, /*[in]*/ SOFErrorTypeEnum
eSOAFError);

STDMETHOD (SetOutGoingOpenFrameCRCError) (

/*[in]*/ short iLayerId, /*[in]*/ int

nPacketIndexInLayer, /*[in]*/ CRCErrorTypeEnum
eCRCError);

STDMETHOD (SetOutGoingOpenFrameInvalidFields) (

/*[in]*/ short iLayerId, /*[in]*/ int

nPacketIndexInLayer, /*[in]*/ int nFieldId, /*[in]*/
BOOL bInvalid);

Usage <Initiator Error Injection Interface Object> -> <Function Name> (

<Layer ID>, <Packet Index in Layer>, <Option Specific Parameter 1>,
<Option Specific Parameter 2 – If Any>);

Return Value None

Description Call the respective functions to set error injection on any particular

OutGoing Open Error frame options.

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Using Initiator/Host Emulator API Functions 96

Summary

Using an Initiator Emulator API involves a stage-by-stage process of Create, Run, Open, and
Modify of an Exerciser capture project, as given below.

Stages involved in using

Host Emulator API

Create a NEW Initiator/Host Exerciser

Capture Project

Initialize an Initiator Project Object

Create a New Initiator Capture Project

Run, Stop and Extract Sample

Run the Capture Project

Stop the Capture Project

Corresponding Function Calls

CSerialSCSICaptureProject::CreateInstance ()

CSerialSCSICaptureProject::New ()

CSerialSCSICaptureProject::Run ()

CWnd::SetTimer ()

OnTimer ()

CSASGeneralService::HalAnalyzerStop ()

Upload and Create Sample file

Open a Saved Host Emulator

Capture Project

Open an Initiator Capture Project

Modify an Existing Initiator

Capture Project

Get Exerciser Engine Interface

Set Data Block

Add/ Insert a Packet in Initiator

CSerialSCSIExtraction::put_AnalyzerSpeed ()

CSerialSCSIExtraction::SetAnalyzerLinkEnable ()

CSerialSCSIExtraction::DumpAndExtract ()

CSerialSCSICaptureProject::Open ()

CSerialSCSICaptureProject::GetExerciserInterface

()

CExerciserEngine::SetDataBlock ()

CExerciserEngine::InsertPacket ()

Add/ Insert an Event in Initiator

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

CExerciserEngine::InsertInstruction()

Using Initiator/Host Emulator API Functions 97

Add/ Insert an Instruction in Initiator

CExerciserEngine::InsertInstruction()

Remove a Packet from Initiator

Remove an event/ Instruction from

initiator

Error Injection on Packets in Initiator

Query Error Injection Interface

Error Injection on OutGoing Frame

CExerciserEngine::DeletePacket()

CExerciserEngine::DeleteInstruction()

QueryInterface () – (using ExerciserEngine

object)

CExerciserEngine::SetOutGoingErrorAttribute ()

CExerciserEngine::ErInjSetFrameErrorType ()

CExerciserEngine::ErInjSetFrameLengthError ()

CExerciserEngine::ErInjSetSOFError ()

CExerciserEngine::ErInjSetEOFError ()

CExerciserEngine::ErInjSetCRCError ()

CExerciserEngine::ErInjSetOmitFrameFromSequen

ce ()

CExerciserEngine::ErInjSetCodeViolationError ()

CExerciserEngine::ErInjSetDisparityError ()

CExerciserEngine::ErInjSetSendingFrameDelay ()

CExerciserEngine::ErInjSetNoWTRM ()

CExerciserEngine::ErInjSetCodeViolationOnSATAP

rimitive ()

CExerciserEngine::ErInjSetDisparityErrorOnSATAP

rimitive ()

CExerciserEngine::ErInjSetIgnoreXRDYorRRDY ()

CExerciserEngine::ErInjSetDelayResponseToHold

()

CExerciserEngine::ErInjSetFillByteForReservedFiel

d ()

CExerciserEngine::ErInjSetInsertPrimitive ()

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Using Initiator/Host Emulator API Functions 98

CExerciserEngine::SetInComingErrorAttribute ()

CExerciserEngine::ErInjSetHandshakeError ()

Error Injection on
Incoming Frame

Error Injection on OutGoing
Open Error Frame

CExerciserEngine::ErInjSetSendDelayToSendHand

shake ()

CExerciserEngine::SetOutGoingOpenFrameTypeEr

ror ()

CExerciserEngine::SetOutGoingOpenFrameSOAFE

rror ()

CExerciserEngine::SetOutGoingOpenFrameEOAFE

rror ()

CExerciserEngine::SetOutGoingOpenFrameCRCErr

or ()

CExerciserEngine::SetOutGoingOpenFrame

FrameLengthError ()

CExerciserEngine::SetOutGoingOpenFrameCode

ViolationError ()

CExerciserEngine::SetOutGoingOpenFrameDispari

tyError ()

CExerciserEngine::SetOutGoingOpenFrameCodeVi

olation

AndDisparityErrorAttribute ()

CExerciserEngine::SetOutGoingOpenFrameInvalid

Fields ()

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Using Initiator/Host Emulator API Functions 99

Using Target/Device E m ulat or API Functions

To use APIs of Target/Device Emulator, you must create an instance of Target Emulator engine
and then you can create a new Target Emulator project or open a saved one. Using this object
of Target Emulator engine, you can modify settings of an existing project, such as Modifying
Pages, Error Injection, Modifying User-defined commands section, and Modifying Settings Page.

• Initialize and create a new target emulator object

• Open a saved target emulator

• Modify an existing target emulator project

o Modify pages
o Error injection on packets of target emulator

 General Settings
 Identification Settings
 Connection management
 Error injection on commands

 Error injection on SAS commands

 Error injection on SATA commands

o Modify settings

 Modify SAS-specific configuration settings
 Modify SATA-specific configuration settings
 Modify settings common to both SAS and SATA configurations

• Summary

Initialize and Create a New Target Emulator Object

To initialize and create a New Target Emulator project, first define a smart pointer to the
Target Emulator Engine, and then create an Instance.

(Refer to

TestCaptureProject -> TestCaptureProjectView.h ->
CTestCaptureProjectView.)

(Refer to

TestCaptureProject -> TestCaptureProjectView.cpp ->
OnInitialUpdate ().)

ITargetEmulEnginePtr m_pITargetEmulator;
m_pITargetEmulator.CreateInstance (__uuidof (TargetEmulEngine));

Sierra SAS/SATA Protocol Suite, STX Software API Reference Manual

Using Target/Device Emulator API Functions 100