PROTOCOL SOLUTIONS GROUP 3385 SCOTT BLVD SANTA CLARA, CA 95054 Conquest Application Program Interface (API) Manual Version 7.40 For Software Version 7.
Document Disclaimer The information in this document has been carefully checked and is believed to be reliable. However, no responsibility can be assumed for inaccuracies that may not have been detected. LeCroy reserves the right to revise the information in this document without notice or penalty. Trademarks LeCroy and Conquest are trademarks of LeCroy Corporation. Universal Serial Bus and On-The-Go are registered trademarks of USB-IF.
Contents Introduction - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 1 Using the Library - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 1 Object Hierarchy - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 1 IUsbGeneral Services Interface - - - - - - - - - - - - - - - - - - - - - - - - - - - 2 SetPort- - - - - - - IsHardwareStoped - SaveOutFiles- - - - EnableProtocolError IsEnableProtocolError
Contents CaptureAndTrigger - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 11 SetTriggerType - - - - - - - GetTriggerType - - - - - - - SetManualTrig - - - - - - - - IsSetManualTrig - - - - - - - SetTriggerDeviceAddress - - GetTriggerDeviceAddress - - SetTriggerEndPoint - - - - - GetTriggerEndPoint - - - - - SetTriggerDataPacket - - - - GetTriggerDataPacket - - - - SetDataCapture1 - - - - - - GetDataCapture1 - - - - - - SetDataCapture2 - - - - - - GetDataCapture2 - - - - - - SetDataCa
Contents IsDeviceHub - - - - - - - - - - - - - - - - - - - - - - - - - - - -27 SetStartExerciserWith - - - - - - - - - - - - - - - - - - - - - - -28 ISetting - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 29 SetAnalyzerSpeed - - - - - - GetAnalyzerSpeed - - - - - - SetExerciserLoopCounter - - Get ExerciserLoopCounter - - SetExternalTriggerType - - - GetExternalTriggerType - - - EnableNonStdClock - - - - - IsEnableNonStdClock - - - - SetNonStdClockRateType - - GetNo
Contents Endpoint Direction Definitions - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 38 Exerciser Start With event definition - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 38 API Errors - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 39 Exerciser Command Parameters - - - - - - - - - - - - - - - - - - - - - - - - - 40 vi
Introduction Introduction The Conquest™ Application Program Interface (API) is a collection (library) of COM objects. The API enables programmers to use most of the Conquest Suite software functionality in their programs for the hardware, to execute a specific project with an event sequence and program selections. The software is for use with applications developed under COM Supported Platforms such as Microsoft® Visual C++™, Borland® Delphi™, and Microsoft Visual Basic™.
IUsbGeneral Services Interface IUsbGeneral Services Interface Method Description SetPort Set hardware attached port. IsHardwareStoped Is hardware stopped? SaveOutFiles Save output file of last run project. EnableProtocolError Enable or disable protocol errors by Type. IsEnableProtocolError Is protocol error type enabled or not. GetMaxMemorySize Get the maximum size of memory. AttachDevice Attach device. DetachDevice Detach device. SaveSmpAsText Save captured data in a text file.
IUsbGeneral Services Interface SaveOutFiles Declaration: longSaveOutFiles() Input(s): None Return Value: Zero if the SaveOutFiles was successful. Otherwise, non-zero. Each non-zero value indicates an error code. Remark: This method saves the output file for Protocol analyzer, Timing analyzer, or both. See Also API Errors EnableProtocolError Declaration: Input(s): long EnableProtocolError(short sProtocolErrorType, BOOL bEnable) sProtocolErrorType specifies type of protocol error.
IUsbGeneral Services Interface AttachToDevice Declaration: long AttachToDevice(LPCTSTR lpctstrMacAddress) Input(s): lpctstrMacAddress specifies hardware MAC address. Return Value: Zero if AttachToDevice was successful. Otherwise, non-zero. Each nonzero value indicates an error code. Remark: This method attaches the software to the requested hardware specified by its MAC address.
IusbEasyDataCapturePrj Interface IusbEasyDataCapturePrj Interface This interface allows you to create an Easy Data Capture project or open and modify an existing Easy Data Project. Method Description GetCaptureAndTrigger Get capture and trigger interface. GetExerciser Get easy exerciser interface. GetSetting Get project setting interface. Open Open easy capture project (.ecp) file. Save Save easy capture project (.ecp) file. Run Run easy capture project. Stop Stop easy capture project.
IusbEasyDataCapturePrj Interface GetCaptureAndTrigger Declaration: ICaptureAndTrigger GetCaptureAndTrigger() Input(s): None Return Value: Capture and Trigger interface. Remark: Returns interface of CaptureAndTrigger object. Do not use CreateDispatch to create CaptureAndTrigger interface. GetExerciser Declaration: IExerciser GetExerciser() Input(s): None Return Value: Exerciser interface Remark: Returns interface of Exerciser object. Do not use CreateDispatch to create Exerciser interface.
IusbEasyDataCapturePrj Interface Save Declaration: long Save(LPCTSTR strFilePath) Input(s): strFilePath points to the fully qualified path to save the file. Return Value: Zero if the save was successful. Otherwise, non-zero. Each non-zero value indicates an error code. Remark: Saves current easy capture project (.ecp) file. See Also API Errors Run Declaration: long Run() Input(s): None Return Value Zero if project can run. Otherwise, non-zero. Each non-zero value indicates an error code.
IusbEasyDataCapturePrj Interface GetAnalyzerType Declaration: short GetAnalyzerType() Input(s): None Return Value: Returns selected Analyzer type. Valid analyzer types are introduced in API Constants. Remark: Identifies type of analyzer. SetPAOutFile Declaration: long SetPAOutputFile(LPCTSTR strPAOutputFile) Input(s): strPAOutputFile specifies protocol analyzer output file name. Return Value: Error code or zero (no error) Remark: Specifies name of protocol analyzer output file.
IusbEasyDataCapturePrj Interface SetPreTrigger Declaration: long SetPreTrigger(short sPreTigger) Input(s): sPreTigger sets pre-trigger percent. It can be between 1 and 99. Return Value: Error code or zero (no error) Remark: Specifies pre-trigger percent. Value of this attribute can be between 1 and 99. See Also API Errors GetPreTrigger Declaration: short GetPreTrigger() Input(s): None Return Value: Pre-trigger value. It is a short value between 1 and 99.
IusbEasyDataCapturePrj Interface GetSamplesNo Declaration: long GetSamplesNo() Input(s): None Output(s) None Return Value Samples number Remark: Returns the number of samples used in the capture. SetRunExerciser Declaration: void SetRunExerciser(BOOL bRun) Input(s): bRun sets the run exerciser flag. Outputs(s): None Remark: If set to TRUE, exerciser also runs. If set to FALSE, only analyzer runs.
CaptureAndTrigger CaptureAndTrigger This interface sets the Easy Capture Project parameters (for example, Trigger point and capture data). (This is equivalent to Data Capture And Trigger page in Easy capture project in the software). When you instantiate the IEsbEasyDataCapturePrj interface, the ICaptureAndTrigger interface instantiates automatically in IEsbEasyDataCapturePrj.
CaptureAndTrigger ExcludeSOFPackets Exclude SOF packets from capturing. IsExcludeSOFPackets Are Keep SOF packets excluded from capturing? SetTimmingPattern Set timing analyzer pattern. GetTimmingPattern Get timing analyzer pattern. SetTriggerType Declaration: long SetTriggerType(short sTriggerType) Input(s): sTriggerType specifies type of USB object on which to trigger the hardware. Valid trigger types are in API Constants. Return Value: Error code or zero (no error) Remark: Sets trigger type.
CaptureAndTrigger SetTriggerDeviceAddress Declaration: long SetTiggerDeviceAddress(LPCTSTR strDeviceAddress) Input(s): strDeviceAddress specifies device address of trigger item. Length of this parameter is 7 characters in binary mode, where each character is one of 0, 1, x, or X (as do not care). Return Value Error code or zero (no error) Remark: Sets the device address on which to trigger.
CaptureAndTrigger SetTriggerDataPacket Declaration: long SetTriggerDataPacket(short sDataPacketType, LPCTSTR strData, BOOL bIsDataBlock) Input(s): sDataPacketType sets data packet type. Valid data packet types are presented in API Constants. strData specifies data payload of data packet. bIsDataBlock specifies strData is data block item name or not. Return Value: Error code or zero (no error) Remark: Sets type and data of data packet on which to trigger.
CaptureAndTrigger SetDataCapture1 Declaration: long SetDataCapture1(short sCaptureType, LPCTSTR strDeviceAddress, LPCTSTR strEndPoint) Input(s): sCaptureType specifies type of capture item 1. Valid capture item types are in API Constants. strDeviceAddress specifies device address of capture item if capture type is one of transaction types. strEndPoint specifies endpoint of capture item if capture type is one of transaction types.
CaptureAndTrigger SetDataCapture2 Declaration: long SetDataCapture2(short sCaptureType, LPCTSTR strDeviceAddress, LPCTSTR strEndPoint) Input(s): sCaptureType specifies type of capture item 2. Valid capture item types are in API Constants. strDeviceAddress specifies device address of capture item if capture type is one of transaction types. strEndPoint specifies endpoint of capture item if capture type is one of transaction types.
CaptureAndTrigger SetDataCapture3 Declaration: long SetDataCapture3(short sCaptureType, LPCTSTR strDeviceAddress, LPCTSTR strEndPoint) Input(s): sCaptureType specifies type of capture item 3. Valid capture item types are in API Constants. strDeviceAddress specifies device address of capture item if capture type is one of transaction types. strEndPoint specifies endpoint of capture item if capture type is one of transaction types.
CaptureAndTrigger IsExcludeNakedTransactions Declaration: BOOL IsExcludeNAKedTransactions() Input(s): None Return Value: Status of exclude NAK’ed transactions flag Remark: Returns TRUE if exclude Nak transactions flag is selected. Returns FALSE if not. ExcludeNYETedTransactions Declaration: void ExcludeNYETedTransactions(BOOL bExclude) Input(s): bExclude sets exclude NYET’ed transactions flag. Return Value None Remark: Excludes NYET transactions if TRUE. Includes NYET transactions if FALSE.
CaptureAndTrigger ExcludeSOFPackets Declaration: void ExcludeSOFPackets(BOOL bExclude) Input(s): bExclude sets exclude SOF packets flag. Return Value: None Remark: Excludes SOF packets if set to TRUE. Includes SOF packets when set to FALSE. IsExcludeSOFPackets Declaration: BOOL IsExcludeSOFPackets() Input(s): None Return Value: Status of exclude SOF Packets flag Remark: TRUE if exclude SOF Packets flag is set. FALSE if not.
IExerciser IExerciser This interface creates an exerciser program for an easy data capture project(This isequivalent to the Exerciser page in an Easy capture project in the software). When you instantiate the IEsbEasyDataCapturePrj interface, the IExerciser interface instantiates automatically in IEsbEasyDataCapturePrj. You can get the IExerciser interface from IEsbEasyDataCapturePrj by calling IEsbEasyDataCapturePrj ::GetExerciser method. Method Description AddCommand Add exerciser command.
IExerciser AddCommand Declaration: long AddCommand(short sCommandType, short sDeviceIndex, const VARIANT& vtParam1, const VARIANT& vtParam2, const VARIANT& vtParam3) Input(s): sCommandType selects the exerciser command type that you want to send to the device. Valid command types are in API Constants. sDeviceIndex sets the found device index. vtParam1 sets the first parameter of exerciser command. vtParam2 sets the second parameter of exerciser command.
IExerciser AddUserDefineCommand Declaration: long AddUserDefineCommand(short sSpeed, short sDeviceAddress, short sEndpointNo, short sEndpointType, short sCommandType, const VARIANT& vtParam1, const VARIANT& vtParam2, const VARIANT& vtParam3) Input(s): sSpeed sets speed of device. Valid speed types are in API Constants. sDeviceAddress sets device address of the device. sEndpointNo sets endpoint number. sEndpointType sets type of the endpoint. Valid endpoint type arein API Constants.
IExerciser InsertCommand Declaration: long InsertCommand(short sInsertAt, short sCommandType, short sDeviceIndex, const VARIANT& vtParam1, const VARIANT& vtParam2, const VARIANT& vtParam3) Input(s): sInsertAt sets index of exerciser command for this command. sCommandType sets exerciser command type that you want to send to the device. Valid types are defined in API Constants. sDeviceIndex sets device index. vtParam1 sets first parameter of the exerciser command.
IExerciser InsertUserDefineCommand Declaration: long InsertUserDefineCommand(short sInsertAt, short sSpeed, short sDeviceAddress, short sEndpointNo, short sEndpointType, short sCommandType, const VARIANT& vtParam1, const VARIANT& vtParam2, const VARIANT& vtParam3) Input(s) sInsertAt sets index of exerciser command fo which this command inserts a replacement. sSpeed sets speed of device. Valid speed types are in API Constants. sDeviceAddress sets device address. sEndpointNo sets endpoint number.
IExerciser DeleteAllCommands Declaration: long DeleteAllCommands() Input(s): None Return Value: Error code or zero (no error) Remark: Deletes all exerciser commands from exerciser program. See Also API Errors SetStartOfLoop Declaration: long SetStartOfLoop(short sCommandIndex, long bSet) Input(s): sCommandIndex sets index of exerciser command. bSet sets status of start of loop flag for exerciser command.
IExerciser FindDevice Declaration: long FindDevice() Inputs: None Return Value: Error code or zero (no error) Remark: This function finds any devices that are attached to the exerciser. See Also: API Errors GetFoundDevicesNo Declaration: short GetFoundDevicesNo() Input(s): None Return Value: Number of devices found Remark: This function returns the number of devices found. Note: Use this function after a call to the FindDevice function.
IExerciser GetEndPointDirection Declaration: long GetEndPointDirection(short sDeviceIndex, short sEndPointIndex, short* sDirection) Input(s): sDeviceIndex specifies the index of found device. sEndPointIndex specifies the index of endpoint of a found device. sDirection specifies direction of specified endpoint. This parameter fills if device index and endpoint index exist. Return Value: Error code or zero (no error) Remark: This function fills sDirection if passed device index and endpoint index exist.
IExerciser SetStartExerciserWith Declaration: long SetStartExerciserWith(short sEventType) Input(s): sEventType specifies type of event with which the exerciser starts. Valid types are in API Constants. Return Value: Error code or zero (no error) Remark: This function sets the type of exerciser start event.
ISetting ISetting This interface sets values of a project. (This is an equivalent to Setting page in Easy (or Advance) capture project in the software). When you instantiate the IEsbEasyDataCapturePrj interface, the ISetting interface instantiates automatically in IEsbEasyDataCapturePrj . You can get the ISetting interface from IEsbEasyDataCapturePrj by calling IEsbEasyDataCapturePrj::GetSetting method. Method Description SetAnalyzerSpeed Set analyzer speed. GetAnalyzerSpeed Get analyzer speed.
ISetting SetAnalyzerSpeed Declaration: long SetAnalyzerSpeed(short sAnalyzerSpeed) Input(s): sAnalyzerSpeed sets the speed of the analyzer. Valid analyzer speed types are defined in API Constants. Return Value: Zero if the SetAnalyzerSpeed was successful. Otherwise, non-zero. Each non-zero value indicates an error code. Remark: This function sets the speed of the analyzer.
ISetting SetExternalTriggerType Declaration: long SetExternalTriggerType(short sTriggerType) Input(s): sTriggerType sets external trigger type. Valid external trigger types are defined in API Constants. Return Value: Zero if the SetExternalTriggerType was successful. Otherwise, non-zero. Each non-zero value indicates an error code. Remark: Sets the external trigger type.
ISetting GetNonStdClockRateType Declaration: short GetNonStdClockRateType() Input(s): None Return Value: Non-standard clock rate type. Valid types are defined in API Constants. Remark: This function returns the type of non-standard clock rate. EnableSecondPort Declaration: void EnableSecondPort(BOOL bEnable) Input(s): bEnable set status of second port. Return Value: None Remark: This function enables (disables) second port.
ISetting EnableHighSpeedTestMode Declaration: void EnableHighSpeedTestMode(BOOL bEnable) Input(s): bEnable sets status of the high-speed test mode flag. Return Value: None Remark: This function enables (disables) the high-speed test mode. IsEnableHighSpeedTestMode Declaration: BOOL IsEnableHighSpeedTestMode() Input(s): None Return Value: Status of high-speed test mode flag Remark: This function returns the status of the high-speed test mode flag.
API Constants API Constants Pre-defined API constants are in the SBAEAPIConstants.h file The following constants are used as parameters by some functions.
API Constants Data Packet Type definitions API_MAX_TRIG_DATA_PACKET_TYPES API_DATA_PACKET_TYPE_ANY API_DATA_PACKET_TYPE_DATA0 API_DATA_PACKET_TYPE_DATA1 API_DATA_PACKET_TYPE_DATA2 API_DATA_PACKET_TYPE_MDATA 5 0 1 2 3 4 Timing Analyzer Pattern Type definitions API_MAX_TA_PATTERN_TYPES API_TA_FLS_TRIG_PATTERN_DP API_TA_FLS_TRIG_PATTERN_DM API_TA_FLS_TRIG_PATTERN_RCV API_TA_HS_TRIG_PATTERN_DP API_TA_HS_TRIG_PATTERN_DM 5 0 //Full/Low Speed D+ Pattern 1 //Full/Low Speed D- Pattern 2 //Full/Low Speed RCV Patt
API Constants Exerciser Command Type definitions API_MAX_EXR_COMMAND_TYPES API_EXR_COMMAND_GET_CONFIGURATION API_EXR_COMMAND_GET_DESCRIPTO API_EXR_COMMAND_GET_INTERFACE API_EXR_COMMAND_GET_DEVICE_STATUS API_EXR_COMMAND_SET_ADDRESS API_EXR_COMMAND_SET_CONFIGURATION API_EXR_COMMAND_CLEAR_HUB_FEATURE API_EXR_COMMAND_CLEARE_HUB_PORT_EATURE API_EXR_COMMAND_GET_HUB_CLASS_DESCRIPTOR API_EXR_COMMAND_GET_HUB_STATUS API_EXR_COMMAND_SET_HUB_FEATURE API_EXR_COMMAND_SET_HUB_PORT_FEATURE API_EXR_COMMAND_CLEAR_HUB_TT_BUF
API Constants Protocol Error Type definitions API_MAX_PROTOCOL_ERROR_TYPES API_PE_BIT_STUFF API_PE_PID_CHECK API_PE_PID_UNKNOWN API_PE_SYNCH API_PE_CRC5 API_PE_CRC16 API_PE_FRAME_LEN API_PE_BABBLE API_PE_DATA_TOGGLE API_PE_FALSE_EOP API_PE_ACT_LOSS API_PE_TIME_OUT API_PE_BUS_ERR 13 0 1 2 3 4 5 6 7 8 9 10 // loss of activity 11 12 //bus error External Trigger Type definitions API_MAX_EXTERNAL_TRIGGER_TYPE API_EXT_TRG_MASK API_EXT_TRG_LEVEL_1 API_EXT_TRG_LEVEL_0 API_EXT_TRG_EDGE_P API_EXT_TRG_EDGE_N 5 0 /
API Constants Endpoint Type definitions API_MAX_ENDPOINT_TYPES API_ENDPOINT_TYPE_CONTROL API_ENDPOINT_TYPE_ISO API_ENDPOINT_TYPE_BULK API_ENDPOINT_TYPE_INT 4 0 1 // Isochronous 2 3 // interrupt Endpoint Direction Definitions API_MAX_ENDPOINT_DIRECTIONS API_DATA_DIRECTION_NONE API_DATA_DIRECTION_IN API_DATA_DIRECTION_OUT 3 0 1 2 Exerciser Start With event definition API_MAX_EXRCISER_START_WITH_EVENTS API_EXR_START_WITH_RESUME API_EXR_START_WITH_RESET 2 0 1 38
API Errors Error codes are in the SBAEAPIErrors.h file. They are returned by some functions upon an error condition.
Exerciser Command Parameters Exerciser Command Parameters The following exerciser commands require no parameters. These commands do not use vtParam1, vtParam2, and vtParam3.
Exerciser Command Parameters The following exerciser commands use vtParam1: API_EXR_COMMAND_GET_DESCRIPTOR - vtParam1 should be a short variable that identifies descriptor type. Valid descriptor types are Device Descriptor and Configuration Descriptor. API_EXR_COMMAND_SET_ADDRESS - vtParam1 should be a short variable that identifies new device address. API_EXR_COMMAND_SET_CONFIGURATION - vtParam1 should be a short variable that identifies configuration value.
Exerciser Command Parameters 42
