Home

AlazarTech SDK Programmer`s Guide

1. 2003 2010 Alazar Technologies Inc 42 SDK Programmer s Guide Issue Start Capture Command No data transfer happens before this AlazarStartCapture h Wait until all required records have been captured while looping 1 Check if one of the AutoDMA buffers has been ES fully populated or not AlazarGetNextAutoDMABuffer h Li Le if Note The synchronous AutoDMA API is deprecated and is maintained for compatibility with existing applications The synchronous AutoDMA API gives poor performance with master slave systems and is not recommended for use with such systems Use the CFlags parameter in the call to AlazarStartAutoDMA to select the AutoDMA mode UserData 0 UserDatal 1 amp WhichOne amp RecsTransferred amp error inl inl amp TriggersOccurred r4 If WhichOne is equal to 0 or 1 that particular buffer has been populated and hardware is DMAing into the other buffer WhichOne 0 WhichO0ne 1 Process Your Data here Note that while you process data new data is still being captured into on board dual port memory and transferred into the other AutoDMA buffer SaveToChannelFiles UserData WhichOne Check if all records have been captured RecsTransferred long RecordCount 1f all records have been captured stop the while loop looping 0 O 2003 2010 Alazar Technologies Inc 43 SDK Programmer s Guid
2. See section 2 4 2 8 AutoDMA Scanning Applications for more information 2 4 Acquiring data AlazarTech digitizers may be configured to acquire in one of the following modes e Single port mode acquires data to on board memory and then after the acquisition is complete transfers data from on board memory to application buffers e Dual port AutoDMA mode acquires to on board memory while at the same time transferring data from on board memory to application buffers 2 4 1 Single port The single port acquisition API allows an application to capture records to on board memory one per trigger event and transfer records from on board to host memory Data acquisition and data transfer are made serially so trigger events that occur while the board is transferring data will be missed The single port acquisition API may be used if e A board has single port or dual port on board memory e An application can miss trigger events that occur while it is transferring data from on board to host memory The singe port acquisition API must be used if e A board does not have dual port or FIFO on board memory e An application acquires data at an average rate that is greater than maximum transfer rate of the board s PCI or PCIe host bus interface Ultrasonic testing OCT radar imaging and similar applications should not use the single port acquisition API rather they should use the dual port acquisition A
3. out RESERVED Return value See Table 1 for a list of error codes Remarks Both Bufferl and Buffer2 will be used in transferring the data from the device back to the user application However if the RecordsPerBuffer is set in conjunction with TransferLength such that all the data will fit in only one Buffer then Only Buffer will be used and the WhichOne variable will equal 0 Only one transaction will take place RecordsTransferred will be modified by the routine and is used to accumulate the number of record that has been transferred Always set the variable to 0 before calling this routine and never modify its contents between repeating calls The user must ensure that Bufferl and Buffer2 are valid buffers Buffer and Buffer2 should be large enough to contain RecordsPerBuffer TransferLength many 16 bit values VB Integer C amp C short If the Record header is selected UseHeader 1 then Buffer and Buffer2 should be large enough to hold RecordsPerBuffer TransferLength sizeof ALAZAR HEADER many 16bit values VB Integer C amp C short AlazarGetNextBuffer and AlazarGetNextAutoDMABuffer are identical See Also AlazarStartAutoDMA AlazarAbortAutoDma AlazarGetNextBuffer Using synchronous AutoDMA 2003 2010 Alazar Technologies Inc 115 SDK Programmer s Guide 3 3 31 AlazarGetNextBuffer THIS FUNCTION IS DEPRECATED DO NOT USE IN NEW DESIGNS AlazarGetNextBuffer and AlazarGetNextAutoDMABuff
4. 2003 2010 Alazar Technologies Inc 6 SDK Programmer s Guide AlazarGetDriverVersion Get the driver version of a board AlazarGetParameter Get a board parameter as a signed 32 bit value AlazarGetParameterUL Get a board parameter as an unsigned 32 bit value AlazarQue pabili Get a board capability as an unsigned 32 bit value The sample program ATS_ SDK DIR Samples AlazarSysInfo demonstrates how get a board handle and use it to obtain board properties The API also exports functions that use a board handle to configure a board arm it to make an acquisition and transfer sample data from the board to application buffers These topics are discussed in the following sections 2 2 Resetting a board The AlazarTech API resets all digitizer boards during its initialization procedure This initialization procedure automatically runs when the API is loaded into memory e Ifan application statically links against the API library the API resets all boards when the application is launched e Ifan application dynamically loads the API library the API resets all boards when the application loads the API into memory Note that when an application using the API is launched all digitizer boards are reset If one application using the API is running when a second application using the API is launched configuration settings written by the first application to a board may be lost If a data transfer between the first application a
5. As Long Parameters BoardHandle in Handle to board Return value The function returns ApiSuccess 512 if it was successful Otherwise the function returns an error code that indicates the reason that it failed See Table 1 for a list of error codes Remarks None See Also AlazarSetExternalTrigger AlazarSetTriggerDelay AlazarSetTriggerOperation AlazarSetTriggerTimeOut 2003 2010 Alazar Technologies Inc SDK Programmer s Guide 3 3 19 AlazarForceTriggerEnable Generate a software trigger enable event Syntax CE RETURN CODE AlazarForceTriggerEnable HANDLE BoardHandle yA VisualBasic AlazarForceTriggerEnable ByVal BoardHandle As Integer As Long Parameters BoardHandle in Handle to board Return value The function returns ApiSuccess 512 if it was successful Otherwise the function returns an error code that indicates the reason that it failed See Table 1 for a list of error codes Remarks If the AUX I O connector has been configured as a trigger enable input an application can call this function to generate a software trigger enable event while the board is waiting for hardware to supply an edge to the the AUX input If the AUX I O connector has been configured as a trigger enable output an application should call this function to generate a trigger enabe event See Also AlazarConfigureAuxIO 2003 2010 Alazar Technologies Inc 98 SDK Programmer s Guide 3
6. ApiDmaNoMoreElements 528 S ApiDmaSglInvalid 529 PO ApiDmaSgiQueueFull 530 ApiNullParam SBP ApilnvalidBusIndex sf 532_ ApiUnsupportedFunction 533 ApilnvalidPciSpace 534 ApilnvalidlopSpace S35 ApilnvalidSize Be o ApilnvalidAddress 537 PO ApilnvalidAccessType 538 ApilnvalidIndex 539 PO ApiMuNotReady O ApiMuFifoEmpty A PO ApiMuFifoFull R ApilnvalidRegister 543 ApiDoorbellClearFailed 544 ApilnvalidUserPin 55s ApilnvalidUserState 546 ApiEepromNotPresent 547 2003 2010 Alazar Technologies Inc 59 SDK Programmer s Guide Identifier ApiEepromTypeNotSupported Ps8 E ApiEepromBlank 549 o ApiConfigAccessFailed EN ApilnvalidDevicelnfo Str ApiNoActiveDriver EXI ApilnsufficientResources 553 fe ApiObjectAlreadyA llocated 554 ApiAlreadyInitialized ee ApiNotlnitialized a i o ApiBadConfigRegEndianMode EXA ApilnvalidPowerState 558 ApiPowerDown SSDP ApiFlybyNotSupported 560 ApiNotSupportThisChannel 56a ApiNoAction 56 i ApiHSNotSupported EA ApiVPDNotSupported ET ApiVpdNotEnabled 565 ApiNoMoreCap EA ApilnvalidOffset EM ApiBadPinDirection 568 ApiPciTimeout SNP ApiDmaChannelClosed po ApiDmaChannelError a ApilnvalidHandle OOOO ApiBufferNotReady ApilnvalidData ApiDoNothing fe ApiDmaSglBuildFailed OA ApiPMNotSupported AAA ApilnvalidDriverVersion A ApiWaitTimeout The operation did not finish during the timeout interval Try the o
7. ByVal S s ourceld2 As Long ByVal ByVal I opeld2 As Long evel2 As Long As Long Parameters BoardHandl e in Handle to board TriggerOperation in Specify how the two independent trigger engines generate a trigger event This parameter can be one of the following values Identifier Value Meaning Generate a trigg ger event when TRIG_ENGINE_OP _J 0 T goes low to high TRIG_ENGINE OP K TRIG ENGINE OP J OR K T goes low to men or Tk goes low to high TRIG ENGINE OP J AND K T AND Ti goes low to high TRIG ENGINE OP J XOR K 4 T XOR Ty goes low to highs TRIG ENGINE OP J AND NOT K T AND NOT TY goes low to 2003 2010 Alazar Technologies Inc 172 SDK Programmer s Guide Oo AAA TRIG ENGINE OP NOT J AND K NOT T AND Ty goes low to high Note that the symbol T represents the output of trigger engine J and T represents the output of trigger engine K TriggerEngineld1 TriggerEngineld2 in Select the trigger engine to configure This parameter can be one of the following values Identifier TRIG ENGINE J 0 Configure trigger engine J TRIG_ENGINE K Sourceld1 Sourceld2 in Select the signal source for the specified trigger engine This parameter can be one of the following values TRIG CHAN A 0 UsesignalsfromCHA Slopeld1 Slopeld2 in Select the sign of the rate of change of the trigger signal with tim
8. Return value The total number of board systems detected Remarks A board system is a group of one or more digitizer boards that share clock and trigger signals A board system may be composed of a single independent board or a group of two or more digitizer boards connected together with a SyncBoard See Also AlazarBoardsInSystemByHandle AlazarBoardsInSystemBySystemID 2003 2010 Alazar Technologies Inc 136 SDK Programmer s Guide 3 3 44 AlazarOEMDownLoadFPGA Download an FPGA image to a digitizer board Syntax CC RE TURN_CODE AlazarOEMDownLoadFPGA HANDLE BoardHandle char FileName USZ Eco De VisualBasic AlazarOEMDownLoadFPGA ByVal BoardHandle As Integer ByRef FileName As Any ByRef Error As Long As Integer Parameters BoardHandle in Handle to a board FileName in FPGA image file path Error out Download result Return value If the function succeeds it returns ApiSuccess 512 If the function fails it returns an error code that indicates the reason that it failed See Table 1 for a list of error codes See Also AlazarParseFPGA Name 2003 2010 Alazar Technologies Inc 137 SDK Programmer s Guide 3 3 45 AlazarOpen THIS FUNCTION IS OBSOLETE DO NOT USE IN NEW DESIGNS Open and initialize a board Syntax CCH HANDLE AlazarOpen char BoardName ya VisualBasic AlazarOpen ByVal BoardName As String As Integer Pa
9. Use the AlazarGetBoardBySystemID API function to get a handle to a board specified by its system identifier and board identifier numbers 2 1 2 1 Single board installations If only one board is installed in a PC the API assigns it system ID 1 and board ID 1 The following code fragment gets a handle to such a board and uses this handle to toggle the LED on the board s PCI PCle mounting bracket Select a board U32 systemld 1 U32 boardld 1 Get a handle to the board HANDLE boardHandle AlazarGetBoardBySystemID systemId boardld Toggle the LED on the board s PCI PCIe mounting bracket AlazarSetLED boardHandle LED ON Sleep 500 AlazarSetLED boardHandle LED OFF 2003 2010 Alazar Technologies Inc SDK Programmer s Guide 2 1 2 2 Multiple board installations If more than one board is installed in a PC the boards are organized into board systems and assigned unique pairs of system and board identifier numbers The following code fragment demonstrates how to obtain a handle to each board in such an installation and use the handle to toggle the LED on the board s PCI PCIe mounting bracket U32 systemCount AlazarNumOfSystems for U32 systemId 1 systemId lt systemCount systemld U32 boardCount AlazarBoardsInSystemBySystemID systemId for U32 boardId 1 boardId lt boardCount boardId printf SystemID u Board ID
10. in Parameter value Return value The function returns ApiSuccess 512 if it was able to retrieve the value of the specified parameter Otherwise the function returns an error code that indicates the reason that it failed See Table 1 for a list of error codes 2003 2010 Alazar Technologies Inc 165 SDK Programmer s Guide Remarks See AlazarApi h for a list of parameter identifiers See Also AlazarGetParameter AlazarGetParameterUL AlazarSetParameter 2003 2010 Alazar Technologies Inc 166 SDK Programmer s Guide 3 3 59 AlazarSetRecordCount Select the number of records to capture to on board memory Syntax CY Car RE TURN_CODE AlazarSetRecordCount HANDLE BoardHandle U32 RecordsPerCapture Ye VisualBasic AlazarSetRecordCount ByVal BoardHandle As Integer ByVal RecordsPerCapture As Long As Long Parameters BoardHandle in Handle to board RecordsPerCapture in The number of records to acquire to on board memory during the acquisition Return value The function returns ApiSuccess 512 if it was successful The function returns 607 if the number of records is greater than greater than the maximum number supported by the firmware revision Otherwise the function returns an error code indicating the reason that it failed See Table 1 for a list of error codes Remarks This function is part of the single port API It cannot be used with the dual port AutoDMA fu
11. AlazarHyperDisp Acquiring to on board memory 2003 2010 Alazar Technologies Inc SDK Programmer s Guide 3 3 4 AlazarAsyncRead Add a buffer to the end of a list of buffers available to be filled by the board When the board receives sufficient trigger events to fill the buffer the event in the OVERLAPPED will be set to the signaled state Syntax O Caras RETURN_CODE AlazarAsyncRead HANDLE BoardHandle void Butter U32 BytesToRead OVERLAPPED Overlapped Wee VisualBasic Not available Parameters BoardHandle in Handle to board Buffer out Pointer to a buffer to receive sample data from the digitizer board BytesToRead in Specifies the number of bytes to read from the board BytesToRead in Pointer to an OVERLAPPED structure The event in the OVERLAPPED structure is set to the signaled state when the read operation completes Return value If the function succeeds in adding the buffer to end of the list of buffers available to be filled by the board it returns ApiDmaPending 585 When the board fills the buffer the event in the OVERLAPPED structure is to the signaled state If the function fails because the board overflowed its on board memory it returns ApiBufferOverflow 582 The board may overflow its on board memory because the rate at which it is acquiring data is faster than the rate at which it is transferring data from on board memory to host memory If this is the ca
12. ByVal BoardHandle As Integer ByVal Boardld as Integer ByVal RecordNumber as Integer As Integer Parameters BoardHandle in Handle to master board in a board system Boardld in Board identifier of a board in the specified board system RecordNumber in Record in acquisition 1 indexed Return value The function returns one of the following values 0 This board did not cause the system to trigger 6 Both CH B and EXT TRIG IN on this board caused the system to trigger A trigger timeout on this board caused the system to trigger Remarks This function is part of the single port data acquisition API It cannot be used with the dual port AutoDMA APIs 2003 2010 Alazar Technologies Inc SDK Programmer s Guide This API routine will not work with ATS850 version 1 2 hardware Version 1 3 and higher version number of ATS850 are fully supported as are all versions of ATS330 and ATS310 See Also AlazarGetWhoTriggeredBySystemlId 2003 2010 Alazar Technologies Inc 129 SDK Programmer s Guide 3 3 40 AlazarGetWhoTriggeredBySystemID Return which event caused a board system to trigger and capture a record to on board memory Syntax C CFF U32 AlazarGetWhoTriggeredBySystemID U32 Systemld WS aes O ta clilicl U32 RecordNumber Ip VisualBasic AlazarGetWhoTriggeredBySystemHandle ByVal SystemId As Integer ByVal BoardiId as Integer ByVal RecordNumber
13. ByVal Decimation As Long As Long Parameters BoardHandle in Handle to board Sourceld in ATS310 ATS330 ATS850 clock source identifiers Identifier INTERNAL CLOCK Use internal sample clock EXTERNAL CLOCK Use external clock signal ATS460 clock source identifiers ATS660 clock source identifiers INTERNAL CLOCK Use internal sample clock SLOW EXTERNAL CLOCK Use 0 10 MHz external clock EXTERNAL CLOCK AC Use 1 K 125 MHz external clock 2003 2010 Alazar Technologies Inc 151 SDK Programmer s Guide EXTERNAL CLOCK DC 16 Use 1 K 125 MHz external clock EXTERNAL CLOCK 10MHz REF 7 Generate 100 130MHz sample clock in 1 MHz steps from 10MHz external clock input ATS860 clock source identifiers ATS9462 clock source identifiers Identifier EXTERNAL CLOCK DC____ 6 Use1lM 180 MHz external clock EXTERNAL CLOCK 10MHz REF 7 Generate 150 180 MHz sample clock in 1 MHz steps from 10MHz external clock input ATS9870 clock source identifiers Value Use 200 M 1 GHz external clock EXTERNAL CLOCK 10MHz REF Generate 1 GHz internal reference from 10MHz external clock Use decimation parameter to generate sample clock from internal reference ATS9350 clock source identifiers Value clock Use decimation to generate the sample clock from reference EXTERNAL CLOCK 10MHz REF Generate 500 MHz reference clock from 10MHz external N N
14. DC coupling and 50Q termination AlazarInputControl boardHandle HANDLE board handle CHANNEL A U8 input channel DC _ COUPLING U32 input coupling id INPUT RANGE PM 800 MV U32 input range id IMPEDANCE 50 OHM U32 input impedance id See AlazarInputControl and the board reference manual for a list of input range coupling and impedance identifiers appropriate for the board 2 3 2 2 Bandwidth filter AlazarTech digitizers have low pass filters that attenuate signals above 20 MHz By default the bandwidth limit filters are disabled Call AlazarSetB WLimit to enable or disable the bandwidth limit filter The following code fragment enables the CH A bandwidth limit filter AlazarSetBWLimit boardHandle HANDLE board handle CHANNEL A U32 channel identifier al U32 0 disable 1 enabl 2 3 2 3 Amplifier bypass Some digitizer models support amplifier bypass mode In this mode signals are injected directly into the ADC converter driver of an input channel bypassing its analog amplifier sections Amplifier bypass mode must be enabled in hardware either through DIP switches on the board or as a factory option Once enabled in hardware the following code fragment shows how to configure this option in software AlazarInputControl handle HANDLE board handle CHANNEL A U8 input channel
15. DC COUPLING U32 not used INPUT RANGE HI FI U32 input range id IMPEDANCE 50 OHM U32 not used 2003 2010 Alazar Technologies Inc 12 SDK Programmer s Guide Note that when amplifier bypass mode option is enabled for an input channel the channel s full scale input range is fixed The following table lists the nominal full scale input range values that may be used to convert sample code values to volts Full scale input range ATS460 525 mV ATS660 550 mV ATS9350 200 mV ATS9462 550 mV ATS9870 256 mV See your board s hardware reference manual for more information about using amplifier bypass 2 3 3 Trigger control AlazarTech digitizer boards have a flexible triggering system with two separate trigger engines that can be used independently or combined together to generate trigger events 2 3 3 1 AlazarSetTriggerOperation Use the AlazarSetTriggerOperation API function to configure each of the two trigger engines and to specify how they should be used to generate trigger events RETURN CODE AlazarSetTriggerOperation HANDLE handle 32 TriggerOperation 32 TriggerEngineldl 32 Sourceldl 32 Slopeldl 32 Levell TriggerEngineld2 32 Sourceld2 32 Slopeld2 32 Level2 RR aa ae Ww N The following paragraphs describe each of the function s parameters and provide examples showing how to use the function 2 3 3 1 1 Trigg
16. Handle to a board Buffer in Reserved set to NULL BufferSize in Number of samples to process ViewBuffer out Pointer to a buffer to receive processed data ViewBufferSize in Size in bytes of processed data buffer NumoOfPixels in Number of HyperDisp points Option in Processing mode Enable HyperDisp processing ChannelSelect in Channel to process 2003 2010 Alazar Technologies Inc 132 SDK Programmer s Guide Record in Record to process 1 indexed TransferOffset in Offset in samples of first sample to process relative to trigger position in record Error out Pointer to value to receive a result code Return values If the function succeeds it returns ApiSuccess 512 If the function fails it returns an error code that indicates the reason that it failed See Table 1 for a list of error codes Remarks AlazarHyperDisp is part of the single port data acquisition API It cannot be used with the dual port AutoDMA APIs HyperDisp processing enables the on board FPGA to divide a record acquired to on board memory into intervals find the minimum and maximum sample values during each interval and transfer an array of minimum and maximum sample values to a buffer in host memory This allows the acquisition of relatively long records to on board memory but the transfer of relatively short processed records to a buffer in host memory For example it would take an AT
17. Internal registered event for up to tms number of milliseconds When the DMA completes the signaling event will wake up the Api Syntax Cy Cars RETURN CODE AlazarWaitForBufferReady HANDLE h U32 tms VisualBasic AlazarWaitForBufferReady ByVal h As Integer ByVal tms As Long As Long Parameters h in Handle to the device tms in time in milliseconds Return values 670 signifies that a NULL was used for the handle 671 signifies that the current device driver does not support events 672 Events were not activated using API AlazarEvents ApiSuccessFul or 512 signifies that the internal wait event was successfully registered and signaled by the ISR ApiFailed or 513 signifies that the internal wait event did not register ApiWaitTimeOut or 579 signifies that the internal wait event was not signaled by the ISR Remarks 2003 2010 Alazar Technologies Inc 186 SDK Programmer s Guide This functionality is only present on the ATS460 ATS660 and ATSS860 devices If AlazarEvents h 1 was not used calling AlazarWaitForBuffer will return ApiFailed and will not disrupt any ongoing signal captures Below is a pseudo code fragment that shows the operations of API AlazarEvents and API AlazarWaitForBufferReady Pseudo code rSetRecordSize rSetCaptureClock rInputControl rInputControl rSetTriggerOperation rEvents h 1 A
18. SDK Programmer s Guide IF error ADMA_Success then the value of the asked Parameter is returned Remarks See Also AlazarGetAutoDMAPtr AlazarGetAutoDMAHeaderTimeStamp 2003 2010 Alazar Technologies Inc 103 SDK Programmer s Guide 3 3 22 AlazarGetAutoDMAPtr THIS FUNCTION IS DEPRECATED DO NOT USE IN NEW DESIGNS This routine is a helper function used to retrieve a pointer to the first data element or first header element of a particular record If DataOrHeader is set to 1 then the resulting pointer must be cast to PALAZAR HEADER type The user can then use the pointer to access any of the header variables Ex PALAZAR HEADER p PALAZAR_ HEADER AlazarGetAutoDMA Ptr Syntax CC OMS AlazarGetAutoDMAPtr HANDLE h U32 DataOrHeader U32 Channel void DataBuffer U32 Record AUTODMA STATUS error eg VisualBasic NOT SUPPORTED Parameters h in Handle to the device DataOrHeader in Instruct the routine to return a pointer for the data or header portion This parameter may be one of the following values O Return the pointer for the data portion Return the pointer for the header portion Channel in This parameter may be one of the following identifiers or values CHANNEL A CHANNEL B DataBuffer in The data buffer as returned from AlazarGetNextAutoDMABuffer Record in Signifies the record number of interest for the given Data Buffer 2003 2010 Al
19. ViewBufferSize pointsPerRecord U32 NumOfPixels ly U32 Option 1 HyperDisp CHANNEL A U32 ChannelSelect dl U32 record 1 indexed long preTriggerSamples long TransferOffset amp error U32 error See AATS_SDK_DIR ASamplesSinglePoriHD for a complete sample program that demonstrates how to use AlazarHyperDisp 2 4 1 5 Record timestamps AlazarTech digitizer boards include a 40 bit counter clocked by the sample clock source scaled by a board specific divider When a board receives a trigger event to capture a record to on board memory it latches and saves the value of this counter The counter value gives the time relative to when the counter was reset when the trigger event for the record occurred By default this counter is reset to zero at the start of each acquisition Use AlazarResetTimeStamp to control when the record timestamp counter is reset 2003 2010 Alazar Technologies Inc 27 SDK Programmer s Guide Use AlazarGetTriggerAddress to retrieve the timestamp in timestamp clock ticks of a record acquired to on board memory This function does not convert the timestamp value to seconds The following code fragment gets the record timestamp of a record acquired to on board memory and converts the timestamp value from clocks ticks to seconds Read the record timestamp U32 triggerAddress U32 timestampHigh U32 timestampLow AlazarGetTr
20. You may not copy the documentation or software except as described in the installation section of this manual You may not distribute rent sub lease or lease the software or documentation including translating decomposing or disassembling or creating derivative works You may not reverse engineer any part of this software or produce any derivative work You may not make telecommunication transmittal of this software Termination This license and your right to use this software automatically terminates if you fail to comply with any provision of this license agreement Rights Alazar Technologies Inc retains all rights not expressly granted Nothing in this agreement constitutes a waiver of Alazar Technologies Inc s rights under the Canadian and U S copyright laws or any other Federal or State law Limited Warranty If you discover physical defects in the media Alazar Technologies Inc will replace the media or documentation at no charge to you provided you return the item to be replaced 2003 2010 Alazar Technologies Inc 11 SDK Programmer s Guide with proof of payment to Alazar Technologies Inc during the 90 day period after having taken delivery of the software Alazar Technologies Inc excludes any and all implied warranties including warranties of merchantability and fitness for a particular purpose and limits your remedy to return the software and documentation to Alazar Technologies Inc for replacement A
21. for a full sample program that demonstrates make an AutoDMA acquisition using ADMA ALLOC BUFFERS An application can get or set the number of DMA buffers allocated by the API by calling AlazarGetParameter or AlazarSetParameter with the parameter SETGET_ASYNC_BUFFCOUNT Note that applications may combine ADMA_ALLOC_BUFFERS with options to perform operations that would be difficult in high level programming languages like LabVIEW They include e Data normalization This option enables the API to process sample data so that the data always has the same arrangement in the application buffer independent of AutoDMA mode See ADMA GET PROCESSED DATA for more information e Disk streaming This option allows the API to use high performance disk I O functions to stream buffer data to files See AlazarCreateStreamFile below for more information 2003 2010 Alazar Technologies Inc 39 SDK Programmer s Gui de 2 4 2 6 3 AlazarAsyncRead Some C C applications under Windows may require waiting for an event to be set to the signaled state to indicate when an AutoDMA buffer is full These applications should use the AlazarAsyncRead API The following code fragment outlines how use AlazarAsyncRead to make an asynchronous AutoDMA acquisition Configure the board to make AlazarBeforeAsynckRead handle channelMask long preTriggerSamples samplesPerBuffer recordsPerBuffer recordsPerAcquisition adm
22. lt lt bitsPerSample 1 0 5 Convert sample code to volts 2003 2010 Alazar Technologies Inc 50 SDK Programmer s Guide double sampleVolts inputRange_volts double sampleCod codeZero codeRange return sampleVolts 2 5 1 2 4 Converting signed 12 bit sample codes to volts A signed code of 0 represents 0V input voltage 2047 0x7FF represents a positive full scale input voltage and 2048 0x800 represents a negative full scale input voltage The following table illustrates how signed 12 bit sample codes map to values in volts according to the full scale input range of the input channel Sample Sample Sample value as a Sample value in Sample value in code in code in percentage of full volts if full scale volts if full decimal hex scale input range input range is scale input 100 mV range is 1 V 2047 0x801 100 100 mV 1024 0xC00 o 0x000 1024 0x400 1024 2047 0x7FF 100 100 mV The following code fragment shows how to convert a 2 byte sample word containing a signed 12 bit sample code to in volts double SampleToVoltsS12 U16 sampleValue double inputRange volts Right shift 16 bit sample value by 4 to get 12 bit sample code int bitShift 4 Ul6 sampleCode sampleValue gt gt bitShift Convert signed code to unsigned sampleCode sampleCode 0x800 OX7FF AlazarTech digitizers are calibrated as follows int b
23. short O 2003 2010 Alazar Technologies Inc 177 SDK Programmer s Guide If the Record header is selected UseHeader 1 then Bufferl1 should be large enough to hold RecordsPerBuffer TransferLength sizeof ALAZAR_ HEADER many 16bit values UseHeader in If equal to 1 then the AUTODMA record header will precede each record in the Buffer ChannelSelect in This parameter may be one of the following identifiers or values CHANNEL A Single channel mode CHANNEL B Single channel mode CHANNEL A CHANNEL B Dual channel mode TransferOffset in Transfer offset relative to the Trigger point for each record TransferLength in The amount to transfer for each record RecordsPerBuffer in The number of records that will be transferred into Bufferl Please note the size information in Buffer description RecordCount in The number of records to be captured during this acquisition Infinite Record Count can be used to create an endless capture for any AutoDMA mode To use Inifinite records set the RecordCount parameter of AlazarStartAutoDMA to Ox7FFFFFFE It is the user s responsibility to set the criteria for stopping an acquisition Note that AlazarStartAutoDMA routine will overwrite any previous settings for this parameter with the value passed in the RecordCount parameter Please note the size information in Bufferl description Error out Error return code This error code may be one of the following va
24. unsigned int InputImpedence 2 bits 26 25 unsigned int ExternalTriggered 1 bit 27 unsigned int ChannelBTriggered 1 bit 28 unsigned int ChannelATriggered 1 Ef Bit 29 unsigned int TimeOutOccurred 1 bit 30 unsigned int ThisChannelTriggered 1 bit 31 y typedef struct ALAZAR HEADER struct HEADERO hdr0 struct HEADER hdrl struct HEADER2 hdr2 struct HEADER3 hdr3 ALAZAR HEADER PALAZAR HEADER A record header contains the following fields Field Width Description in bits SerialNumber Serial number of this board as a signed integer System identifier number of this board system WhichChannel Input channel of this header 0 CH A 1 CHB 2003 2010 Alazar Technologies Inc 34 SDK Programmer s Guide BoardType Board type identifier See AlazarGetBoardKind for a list of board type identifiers 2 4 2 5 2 below Reenter UN eesotan 2 4 2 5 2 below ClockSource Clock source identifier 1 See AlazarSetCaptureClock for a list of sample rate 7 5 2 2 identifiers ClockEdge Clock edge identifier E See AlazarSetCaptureClock for a list of sample rate identifiers SampleRate Sample rate identifier See AlazarSetCaptureClock for a list of sample rate identifiers InputRange Input range identifier for this channel See AlazarInputControl for a list input range identifiers InputCoupling Input coupling identifier for this channel See AlazarInputControl fo
25. void buffer bytesPerSample int bytes per sample long record long record 1 indexed long preTriggerSamples long trigger offset samplesPerRecord U32 samples to transfer 2003 2010 Alazar Technologies Inc 24 SDK Programmer s Guide See ATS SDK_DIR Samples SinglePort AR for a complete sample program that demonstrates how to use AlazarRead to read full records 2 4 1 2 2 Transferring partial records AlazarRead can transfer a segment of a record from on board memory to a buffer in host memory This may be useful if e The number of bytes in a full record in on board memory exceeds the buffer size in bytes that an application can allocate in host memory e An application wishes to reduce the time required for data transfer when it acquires relatively long records to on board memory but is only interested in a relatively small part of the record Use the TransferOffset parameter in the call to AlazarRead to specify the offset in samples from the trigger position in the record of the first sample to transfer from on board memory to the application buffer And use the TransferLength parameter to specify the number of samples to transfer from on board memory to the application buffer where this number of samples may be less than the number of samples per record The following code fragment divides a record into segments and transfers the segments from on board to host memo
26. 2003 2010 Alazar Technologies Inc 139 SDK Programmer s Guide FpgaMinorVersion out Pointer to FPGA minor version number Error out Pointer to an error code Return value If the function succeeds it returns ApiSuccess 512 If the path to the file path was not found the function returns ApiFailed 513 and Error to 626 Remarks See Also AlazarOEMDownLoadFPGA 2003 2010 Alazar Technologies Inc 140 SDK Programmer s Guide 3 3 47 AlazarPostAsyncBuffer Add a buffer to the end of a list of buffers available to be filled by the board Use AlazarWaitAsyncBufferComplete to determine if the board has received sufficient trigger events to fill this buffer Syntax C C RETURN_CODE AlazarPostAsyncBuffer HANDLE BoardHandle void Buffer U32 BufferLength VisualBasic AlazarPostAsyncBuffer ByVal BoardHandle As Integer ByRef Buffer As Any ByVal BufferLength As Long As Long Parameters BoardHandle in Handle to board Buffer out Pointer to a buffer to receive sample data from the digitizer board BufferLength in Specifies the length of the buffer in bytes Return values If the function succeeds in adding the buffer to end of the list of buffers available to be filled by the board it returns ApiSuccess 512 Use AlazarWaitAsyncBufferComplete to determine when the board has received sufficient trigger events to file this buffer If the function fails it returns an e
27. 483 648 or more samples long Syntax C CFF U32 AlazarReadEx HANDLE BoardHandle U32 Channelld void Buffer int ElementSize long Record INT64 TransferOffset U32 TransferLength Ye VisualBasic AlazarReadEx ByVal BoardHandle As Integer ByVal Channelld As Long ByRef Buffer As Any ByVal ElementSize As Integer ByVal Record As Long ByVal TransferOffset As Currency ByVal TransferLength As Long As Long Parameters BoardHandle in Handle to a board Channelld out Channel identifier of record Buffer out Buffer to receive sample data ElementSize in Number of bytes per sample Record in Record in on board memory to transfer to buffer 1 indexed TransferOffset in The offset in samples from the trigger position in the record of the first sample in the record in on board memory to transfer into the buffer TransferLength in The number of samples to transfer from the record in on board memory into the buffer 2003 2010 Alazar Technologies Inc 147 SDK Programmer s Guide Return values If the function succeeds it returns ApiSuccess 512 If the function fails it returns an error code that indicates the reason that it failed See Table 1 for a list of error codes Remarks AlazarReadEx is part of the single port data acquisition API It cannot be used with the dual port AutoDMA APIs AlazarReadEx can transfer segments of a record acquired to on board memory
28. 78 SDK Programmer s Guide ADMA FIFO ONLY STREAMING 0x00000800 ADMA _INTERLEAVE SAMPLES 0x00001000 2003 2010 Alazar Technologies Inc the API manage a list of DMA buffers and to receive a copy of data in an application buffer When this flag is set the application must call AlazarWaitNextAsyncBufferComplete to wait for a buffer to complete and receive a copy of the data The application can specify the number of DMA buffers for the API to allocate by calling AlazarSetParameter_ with the parameter SETGET_ASYNC_BUFFCOUNT before calling AlazarBeforeAsyncRead Enable the board to data from its on FPGA FIFO rather than from on board memory When the flag is set each buffer contains data organized as follows RO ABAB RI ABAB R2 ABAB That is each sample from CH A is followed by a sample from CH B When this flag is not set each record in a buffer contains a contiguous array of samples for CH A followed by a contiguous array of samples for CH B where the record arrangement depends on the acquisition mode Note that this flag must be set if your board does not have on board memory For example an ATS9462 FIFO requires this flag Also note that this flag must not be set if your board has on board memory Enable a board to interleave samples from both digitizer channels in dual channel acquisition mode This results in higher data transfer rates on boards 79 SDK Programm
29. 7F FO 7F 00 80 FO 7F FO F 10 80 EO 7F 00 80 000010 FO F 00 000020 00 80 FO F 00 80 DO F FO F E0 F EO F 00 80 000030 FO F FO F 00 80 Ed F 00 80 FO F FO F 00 80 000040 FO E FO 7F EO 7F EO F 10 80 00 80 EO F 10 80 000050 00 80 EO F E0 7F FO 7F EO F 10 80 FO F 00 80 000060 00 80 DO F FO 7F FO F EO F 00 80 00 80 FO F 000070 00 80 FO F 00 80 EO F OO 80 FO F FO F EO 7 F Each 12 bit sample value occupies a 2 bytes in the buffer so the figure displays 64 sample values 128 bytes 2 bytes per sample The first 2 bytes in the buffer shown highlighted are OxE0 and 0x7F Two byte sample values are stored in little endian byte order in the buffer so the first sample value in the buffer is Ox7FEO The following code fragment demonstrates how to access each 16 bit sample value in a buffer Ul6 pSamples U16 buffer for U32 sample 0 sample lt samplesPerBuffer sample Ul6 sampleValue pSamples printf sample value 04X n sampleValue 2003 2010 Alazar Technologies Inc 49 SDK Programmer s Guide 2 5 1 2 2 Getting 12 bit sample codes from 16 bit sample values A12 bit sample code is stored in the most significant bits of each 16 bit sample value so right shift each 16 bit value by 4 or divide by 16 to obtain the 12 bit sample code In the example above the 16 bit sample value 0x7FEO right shifted by four results in the 12 bit sample code 0x7FE or 2046 decimal 16 bit sample
30. 8191 OxIFFF 100 100 mV tIV 8191 OXIFFF 100 I00mV HV The following code fragment demonstrates how to convert a 2 byte sample value containing a signed 14 bit sample code to in volts double SampleToVoltsU14 U16 sampleValue double inputRange volts Right shift 16 bit sample word by 2 to get 14 bit sample code int bitShift 2 U16 sampleCode sampeWord gt gt bitShift AlazarTech digitizers are calibrated as follows int bitsPerSample 14 double codeZero 1 lt lt bitsPerSample 1 0 5 double codeRange 1 lt lt bitsPerSample 1 0 5 Convert the signed code to unsigned sampleCode sampleCode 0x2000 Ox1FFF Convert sample code to volts double sampleVolts inputRange_volts double sampleCode codeZero codeRange return sampleVolts 2 5 1 4 ATS660 ATS9462 2 5 1 4 1 Getting 2 byte sample values from the buffer The figure below displays the first 128 bytes of data in a buffer from a 16 bit digitizer such as the ATS660 or ATS9462 Figure 2 9 16 bit sample data 000000 14 SOJFB 7F FB 7F 08 80 FB F 00 80 02 80 ED 7F 000010 OB 80 FF 000020 FF F E F FA 7F 15 80 F8 F EC F OC 80 EF 7F 000030 EF F Fl F FS 7F 06 80 FA F 02 80 E2 F FC 7 7F 000040 17 80 FB F 04 80 04 80 08 80 00 80 07 80 OB 80 000050 FF F 04 80 06 80 04 80 04 80 OB 80 F8 F FC 7F 000060 FS F F 7F 18 80 09 80 03 80 00 80 FS E OA 80 000070 F2 F F4
31. AlazarBeforeAsyncRead HANDLE BoardHandle U32 ChannelSelect long TransferOffset U32 SamplesPerRecord U32 RecordsPerBuffer U32 RecordsPerAcquisition U32 Flags Ye VisualBasic AlazarBeforeAsyncRead ByVal BoardHandle As Integer ByVal ChannelSelect As Long ByVal TransferOffset As Long ByVal SamplesPerRecord As Long ByVal RecordsPerBuffer As Long ByVal RecordsPerAcquisition As Long ByVal Flags As Long As Long Parameters BoardHandle in Handle to board ChannelSelect in Select the channel to control This parameter may be one of the following identifiers or values CHANNEL_A Acquire from CH A onl CHANNEL_B Acquire from CH B onl CHANNEL A CHANNEL B Acquire from both CH A and B TransferOffset in Specify the first sample from each on board record to transfer from on board to host memory This value is a sample relative to the trigger position in an on board record SamplesPerRecord in Specify the number of samples from each record to transfer from on board to host memory See remarks below RecordsPerBuffer 2003 2010 Alazar Technologies Inc 76 SDK Programmer s Guide in Specify the number of records in each buffer See remarks below RecordsPerAcquisition in Specify the number of records in to acquire during acquisition Set to Ox7fffffff to acquire indefinitely until the acquisition is aborted See remarks below Flags in Specify AutoDMA mode a
32. Byte ByRef RevisionNumber As Byte As Long Parameters MajorNumbr out The driver major version number MinorNumber out The driver minor version number RevisionNumber out The driver revision number Return value The function returns ApiSuccess 512 if it was successful Otherwise the function returns an error code that indicates the reason that it failed See Table 1 for a list of error codes Remarks Driver releases are given a version number with the format X Y Z where X is the major release number Y is the minor release number and Z is the minor revision number See Also AlazarGetCPLD Version AlazarGetSDK Version 2003 2010 Alazar Technologies Inc 111 SDK Programmer s Guide 3 3 29 AlazarGetMaxRecordsCapable Calculate the maximum number of records that can be captured to on board memory given the requested number of samples per record Syntax C Cast RETURN CODE AlazarGetMaxRecordsCapable HANDLE BoardHandle U32 SamplesPerRecord U32 MaxRecordsPerCapture VisualBasic AlazarGetMaxRecordsCapable ByVal BoardHandle As Integer ByVal SamplesPerRecord As Long ByRef MaxRecordsPerCapture As Long As Long Parameters BoardHandle in The handle a board in a board system SamplesPerRecord in The desired number of samples per record MaxRecordsPerCapture out The maximum number of records per capture possible with the requested samples per record Retur
33. HANDLE board handle preTriggerSamples U32 pre trigger samples postTriggerSamples U32 post trigger samples 3 2 Set record count AlazarSetRecordCount boardHandle HANDLE board handle recordsPerCapture U32 records per acquisition 3 Arm the board to wait for trigger events AlazarStartCapture boardHandle 4 Wait for the board to receive all trigger events and capture all records to on board memory while AlazarBusy boardHandle The acquisition is in progress N N 2003 2010 Alazar Technologies Inc SDK Programmer s Guide 5 The acquisition is finished Call AlazarRead or AlazarHyperDisp to transfer records from either channel from on board memory to an application buffer 2 4 1 1 2 Single channel mode ATS9870 and ATS9350 digitizer boards can be configured to dedicate all on board memory to one of a board s input channels A single port acquisition in single channel mode only captures samples from the specified channel to on board memory and after the acquisition is complete only allows samples from the specified channel to be transferred from on board memory to an application buffer To program a board acquire to on board memory in single channel mode 1 Call AlazarSetRecordSize to set the number of samples per record where a record may contain samples before and after its trigger event 2 Call AlazarSetRecordCount to set the number
34. LOCKED PAGES IN PROCESS 0x000000CB bug check error under Windows or leak the locked memory under Linux This may happen for example if a programmer runs an application that uses the API under a debugger stops at a breakpoint and then stops the debugging session without letting the application or API exit normally 2 4 2 6 5 Buffer count An application should supply at least two buffers to a board This allows the board to fill one buffer while the application consumes the other As long as the application can consume buffers faster than the board can fill them the acquisition can continue indefinitely However Microsoft Windows and general purpose Linux distributions are not real time operating systems An application thread may be suspended for an indeterminate amount 2003 2010 Alazar Technologies Inc 41 SDK Programmer s Guide of time to allow other threads with higher priority to run As a result buffer processing may take longer than expected The board is filling AutoDMA buffers with sample data in real time If an application is unable to supply buffers as fast a board fills them the board will run out of buffers into which it can transfer sample data The board can continue to acquire data until it fills is on board memory but then it will abort the acquisition and report a buffer overflow error It is recommended that an application supply three or more buffers to a board This allows some tolerance for operatin
35. MHz sample clock from an external 10 MHz reference input The 500 MS s sample data can be decimated by 1 2 4 or any multiple of 5 2003 2010 Alazar Technologies Inc 10 SDK Programmer s Guide Call AlazarSetCaptureClock specifying EXTERNAL CLOCK 10MHz REF as the clock source and 500 MHz as the sample rate and select a decimation of 1 2 4 or any multiple of 5 up to 100000 For example the following code fragment shows how to generate a 100 MS s sample rate with a 10 MHz external clock input AlazarSetCaptureClock handle HANDLE board handle EXTERNAL CLOCK 10MHz REF U32 clock source Id 500000000 U32 sample rate Id CLOCK EDGE RISING U32 clock edge Id 5 U32 decimation 2 3 2 Input control AlazarTech digitizers have analog amplifier sections that process the signals input to its CH A and CH B connectors before they are sampled by the ADC converters The gain coupling and termination of the amplifier sections should be configured to match the properties of the input signals Figure 2 3 CHA and CHB connectors on PCI PCle mounting bracket 2003 2010 Alazar Technologies Inc 11 SDK Programmer s Guide 2 3 2 1 Input range coupling and impedance Call AlazarInputControl to specify the desired input range termination and coupling of an input channel The following code fragment configures input CH A for a range of 800 mV
36. See the ReadMe htm file in the ATS_ SDK DIR Samples directory for a description of all of the samples included for your board model Note that the sample programs contain parameters that should be modified as required These lines of code are preceded by TODO comments 1 4 Contacting us Please contact us if you have any questions or comments about this document or the SDK sample code Mail Alazar Technologies Inc 6600 Trans Canada Highway Suite 310 Pointe Claire QC Canada H9R 482 Note that you can download the latest drivers and documentation here http www alazartech com support downloads htm 2003 2010 Alazar Technologies Inc SDK Programmer s Guide 2 Programmer s Guide 2 1 Addressing a board 2 1 1 Getting a board identifier The AlazarTech API organizes digitizer boards into board systems A board system is a group of one or more digitizer boards that share clock and trigger signals Two or more boards form a board system when they are connected together using an AlazarTech SyncBoard The API assigns a system identifier to each board system where the first board system detected is assigned a system identifier number of 1 The API assigns a board identifier to each board in a board system This number uniquely identifies a board within its board system e Ifa digitizer board is not connected to any other boards using a SyncBoard then the API assigns it a boa
37. Suln systemId boardld Get a handle to the board HANDLE handle AlazarGetBoardBySystemID systemId boardld Toggle the LED on the board s PCI PCIe mounting bracket AlazarSetLED handle LED ON Sleep 500 AlazarSetLED handle LED OFF 2 1 2 3 System handles Several API functions require a system handle A system handle is the handle of the master board in a board system e Ifa board is not connected to other boards using a SyncBoard then its board handle is the system handle e Ifa board is connected to other boards using a SyncBoard then the board that is connected to the master connector on the SyncBoard is the master board and its board handle is the system handle 2 1 3 Closing a board handle The AlazarTech API maintains a list of board handles in order to support master slave board systems The API creates board handles when it is loaded into memory and destroys these handles when it is unloaded from memory An application should not need to close a board handle 2 1 4 Using a board handle The API exports a number of functions that return information about a board specified by 1ts handle These functions include AlazarGetBoardKind Get a board s model from its handle AlazarGetChamnellnfo Get the number of bits per sample and on board memory size in samples per channel AlazarGetCPLD Version Get the CPLD version of a board
38. The AlazarTech SDK includes a wrapper class that declares many of the constants and unmanaged functions exported by AlazarTech device drivers This class is provided both as a Cf source file AlazarApi cs and as a compiled assembly AlazarApiNet dll The SDK setup program copies AlazarApi cs to the Samples_CSharp AlazarApiNet AlazarApiNet directory and AlazarApiNet dll to the Samples CSharp directory Note that you can use the solution Samples CSharp AlazarApiNet to build AlazarApiNet dll from AlazarApi cs 1 2 4 Linux C C programmers under Linux should include the following header files in source files that use functions exported by the AlazarTech API library tinclude AlazarError h include AlazarApi h tinclude AlazarCmd h These modules should also link against libPIxApi so The RPM package for Linux installs the header files in ATS SDK _DIR Include and the library files in ATS_ SDK DIR Library where ATS SDK DIR defaults to usr local AlazarTech 1 3 Sample code The AlazarTech SDK includes sample programs that demonstrate how to program AlazarTech digitizer boards The SDK setup program installs the sample programs to ATS SDK DIR Samples where ATS_SDK_DIR defaults to 2003 2010 Alazar Technologies Inc 2 SDK Programmer s Guide C AlazarTech ATS API API_VERSION under Microsoft Windows and asr local AlazarTech under Linux
39. a complete understanding of the Usage of the API AlazarEvents refer to the pseudo code example provided in the API_AlazarWaitForBufferReady Ga Syntax C Csr RE TURN_CODE AlazarEvents HANDLE h U32 enable Ve VisualBasic AlazarEvents ByVal h As Integer ByVal enable As Integer As Integer Parameters h in Handle to the device enable in This parameter may have one of the following values Identifier SW_EVENTS OFF 0 Disable events usage SW_EVENTS_ON Return value ApiSuccess 512 signifies that the API was able to enable the events ApiFailed 513 signifies that the current driver does not support this feature Remarks This functionality is only present on the ATS460 ATS660 and ATSS860 devices It must be called before calling AlazarStartAutoDMA If AlazarEvents h 1 was not used calling AlazarWaitForBuffer will return 672 and will not disrupt any ongoing signal captures 2003 2010 Alazar Technologies Inc 94 SDK Programmer s Guide See Also AlazarWaitForBufferReady Using synchronous AutoDMA O 2003 2010 Alazar Technologies Inc 95 SDK Programmer s Guide 3 3 17 AlazarFlushAutoDMA THIS FUNCTION IS DEPRECATED DO NOT USE IN NEW DESIGNS The primary use of the API is to stop a Synchronous NPT acquisition Scanning type applications are usually configured such that the data capture is ongoing and stopping is done by an external event In thi
40. acquisition into one buffer while at the same time the application processes a previous segment of the acquisition in another buffer The following table compares the asynchronous and synchronous AutoDMA APIs Asynchronous AutoDMA Synchronous AutoDMA Application defined Two API allocated buffers CPU usage Interrupt driven so very low Polling loop so very high Less CPU More CPU cycles are available cycles are available to application to application threads threads Data DMA directly into user DMA into API allocated buffer then transfer supplied buffer No CPU copy to user supplied buffer CPU cycles cycles are used to copy data used to copy data are not available to application threads DMA re Next DMA started by Next DMA started in polling loop arm time hardware interrupt Latency is Latency is higher and data throughput is lowest and data throughput is lower F ully supported Not recommended 2003 2010 Alazar Technologies Inc 30 SDK Programmer s Guide The synchronous AutoDMA API is deprecated it is maintained for compatibility with existing applications The asynchronous AutoDMA API is recommended for all new applications 2 4 2 1 Traditional AutoDMA Use traditional mode to acquire multiple records one per trigger event with sample points after and optionally before the trigger event in each record A record header may optionally precede each record in the AutoDMA buffer T
41. board this function returns a handle to that board See Also AlazarBoardsInSystemByHandle AlazarBoardsInSystemBySystemID 2003 2010 Alazar Technologies Inc 123 SDK Programmer s Guide 3 3 37 AlazarGetTriggerAddress Get the timestamp and trigger address of the trigger event in a record acquired to on board memory Syntax CY Carr RETURN_CODE AlazarGetTriggerAddress HANDLE BoardHandle U32 Record U32 TriggerAddress U32 TimestampHighPart U32 TimestampLowPart NE VisualBasic AlazarGetTriggerAddress ByVal BoardHandle As Integer ByVal Record As Long ByRef TriggerAddress As Long ByRef TimestampHighPart As Long ByRef TimestampLowPart As Long As Long Parameters BoardHandle in Handle to board Record in Record in acquisition 1 indexed TriggerAddress in The trigger address TimestampHighPart in The most significant 32 bits of a record timestamp TimestampLowPart in The least significant 8 bits of a record timestamp Return value The function returns ApiSuccess 512 if it was successful Otherwise the function returns an error code that indicates the reason that it failed See Table 1 for a list of error codes Remarks This function is part of the single port data acquisition API It cannot be used to retrieve the timestamp of records acquired using dual port AutoDMA APIs 2003 2010 Alazar Technologies Inc 124 SDK Programmer s Guide The followin
42. code that demonstrates how to make most types of acquisitions and provide a starting point for creating new applications Note that this document includes descriptions of board specific features and options that may not be available on your particular digitizer Please refer your board s user manual for its specifications 1 2 Programming environments 1 2 1 Visual C C C programmers should include the following header files in source files that use functions exported by the API library include AlazarError h include AlazarApi h include AlazarCmd h These applications should also link against the 32 or 64 bit version of ATSApi lib as required 2003 2010 Alazar Technologies Inc l SDK Programmer s Guide The SDK setup program installs the header files in ATS SDK DIR Include and the library files in ATS SDK DIR Library where ATS SDK DIR defaults to C AlazarTech 1 2 2 VisualBasic VisualBasic programmers should include the module ATSApiVB bas in their projects It provides a Visual Basic interface to the many of the constants and functions used by AlazarTech device drivers The SDK setup program installs this module in ATS SDK DIR Include where ATS_SDK_DIR is by default C AlazarTech 1 2 3 CH C programmers should either e Add the file AlazarApi cs to their project or e Adda reference to AlazarApiNet dll to their project
43. level See Also AlazarSetCaptureClock 2003 2010 Alazar Technologies Inc 159 SDK Programmer s Guide 3 3 55 AlazarSetExternalTrigger Set the external trigger range and coupling Syntax CETT RETURN_CODE AlazarSetExternalTrigger HANDLE BoardHandle U32 Couplingld U32 Rangeld VisualBasic AlazarSetExternalTrigger ByVal BoardHandle As Integer ByVal Couplingld As Long ByVal Rangeld As Long As Long Parameters BoardHandle in Handle to board Couplingld in Specifies the external trigger coupling This parameter may have one of the following values Value AC COUPLING AC coupled trigger input DC COUPLING DC coupled trigger input Rangeld in Specifies the external trigger range This parameter may have one of the following values Identifier ETR_5V O_ 5V external trigger range ge ETR_1V Return value If the function succeeds it returns ApiSuccess 512 If the function fails 1t returns an error code that indicates the reason that it failed See Table 1 for a list of error codes Remarks See Also 2003 2010 Alazar Technologies Inc 160 SDK Programmer s Guide AlazarSetTriggerDelay AlazarSetTriggerOperation AlazarSetTriggerTimeOut O 2003 2010 Alazar Technologies Inc 161 SDK Programmer s Guide 3 3 56 AlazarSetLED Control LED on a board s PCI PCIe mounting bracket Syntax CY Car RE TURN_CODE AlazarSetLED H
44. low ADMA InternalBuffer2Invalid 5 The routine cannot allocate enough memory because system resources are low ADMA OverFlow 6 A hardware overflow occurred ADMA_DMAInProgress 8 A memory transfer is in progress ADMA UseHeaderNotSet__ 9 UseHeader mustbeset_ ADMA InvalidRecsPerBuffer 11 RecordCount must be a perfect multiple of RecsPerBuffer Return value Upon success i e error ADMA_Success the TimeStamp will be returned in a floating point format If an error has occurred then 0 will be returned Remarks See Also AlazarGetAutoDMA HeaderV alue AlazarGetAutoDMA Ptr 2003 2010 Alazar Technologies Inc 100 SDK Programmer s Guide 3 3 21 AlazarGetAutoDMAHeaderValue THIS FUNCTION IS DEPRECATED DO NOT USE IN NEW DESIGNS This routine is a helper function that can be used to retrieve all the various elements available in the header of an AutoDMA record It will only operate on records that were captured when the Use Header variable in AlazarStartAutoDMA was set to a 1 Syntax C C U32 AlazarGetAutoDMAHeaderValue HANDLE h U32 Channel void DataBuffer U32 Record U32 Parameter AUTODMA SAUS Sror 8 VisualBasic AlazarGetAutoDMAHeaderValue ByVal h As Integer ByVal Channel As Long ByRef DataBuffer As Any ByVal Record As Long ByVal Parameter As Long ByRef error As Long As Long Parameters h in Handle to the device Channel in Thi
45. of application buffers passed to the following data transfer functions must meet the buffer aligment requirement in the table above AlazarRead AlazarReadEx 2003 2010 Alazar Technologies Inc Nn SDK Programmer s Guide AlazarAsyncRead AlazarPostAsyncBuffer and AlazarWaitAsyncBufferComplete For example the address of a buffer passed to AlazarPostAsyncBuffer to receive data from an ATS9350 must be aligned to a 32 sample or 64 byte address Note that AlazarWaitNextAsyncBufferComplete has no aligment requirements As a result an application can use this function to transfer data if it is impossible to allocate correctly aligned buffers 2 4 4 Data format By default AlazarTech digitizers generate unsigned sample data For example 8 bit digitizers such as the ATS9870 generate sample codes between 0 and 255 OxFF where 0 represents a negative full scale input voltage 128 0x80 represents OV input voltage 255 OxFF represents a positive full scale input voltage Some AlazarTech digitizer can be configured to generate signed sample data in two s complement format For example the ATS9870 can be configured to generate sample codes where 0 represents OV input voltage 127 0x7F represents a positive full scale input voltage and 128 0x80 represents a negative full scale input voltage Call AlazarSetParameter with parameter SET DATA FORMAT before the start of an acquisition to set the sample data format an
46. positive full scale input voltage and 128 0x80 represents a negative full scale input voltage The following table illustrates how signed 8 bit sample codes map to values in volts according to the full scale input range of the input channel Sample Sample value as a Sample value in Sample value in code in percentage of full volts if full scale volts if full decimal scale input range input range is scale input 100 mV range is 1 V 100 100 mV 64 o 0x0 Jo j0w OV 2003 2010 Alazar Technologies Inc 48 SDK Programmer s Guide The following code fragment shows how to convert a 1 byte sample value containing a signed 8 bit sample code to in volts double SampleToVoltsS8 U8 sampleValue double inputRange volts AlazarTech digitizers are calibrated as follows int bitsPerSample 8 double codeZero 1 lt lt bitsPerSample 1 0 5 double codeRange 1 lt lt bitsPerSample 1 0 5 Convert signed code to unsigned U8 sampleCode sampleValue 0x80 Convert sample code to volts double sampleVolts inputRange_volts double sampleCode codeZero codeRange return sampleVolts 2 5 1 2 ATS310 ATS330 ATS9350 2 5 1 2 1 Getting 2 byte sample values from the buffer The figure below displays the first 128 bytes of data in a buffer from a 12 bit digitizer such as the ATS310 ATS330 or ATS9350 Figure 2 7 12 bit sample data 000000 EO
47. records per acquisition the board captures one record per trigger event 3 Call AlazarSetParameter with the parameter SET SINGLE CHANNEL MODE and specify the channel to use all memory 4 Call AlazarStartCapture to arm the board to wait for trigger events 5 Call AlazarBusy in a loop to poll until the board has received all trigger events in the acquisition and has captured all records to on board memory 6 Call AlazarRead AlazarReadEx or AlazarHyperDisp to transfer records from on board memory to host memory 7 Repeat from step 3 if necessary The following code fragment acquires to on board memory from CH A in single channel mode 1 1 Set record size AlazarSetRecordSize boardHandle HANDLE board handle preTriggerSamples U32 pre trigger samples postTriggerSamples U32 post trigger samples 2 Set record count AlazarSetRecordCount boardHandle HANDLE board handle recordsPerCapture U32 records per acquisition 3 Enable single channel mode AlazarSetParameter boardHandle HANDLE board handle 0 U8 channel Id not used SET SINGLE CHANNEL MODE U32 parameter CHANNEL A long CHANNE 1 A or CHANNEL B r 2003 2010 Alazar Technologies Inc 23 SDK Programmer s Guide 4 Arm the board to wait for trigger events AlazarStartCapture boardHandle 5 Wait for the board to re
48. saa da asic a eared te es 46 2 5 1 Converting samples A ti 46 E inay Ml a ada taeda aa 56 A i 59 AN PAP A RN A PARA 59 E A A 62 EPM AAA AAA hand pntantesicid 62 AS And sii 62 3 2 3 Confirurati n and CORA ii ii ii i 62 A E id do 63 A A A ea cones as tie 65 3 32 Fe i i he a aaa hes a i il 2a Alazar NN opal ie aetna er aaal ahead sence ae ein 13 AMA diana td hanes amis aaa emacs at boncien 74 339 A Ne IN ac case E NN maadlai conn dings 76 ESO E ck sh cc iad hee Sareea A ia 82 2003 2010 Alazar Technologies Inc iv SDK Programmer s Guide 3 3 I AlozarBoardsFonas EVA EEE nL EERE a 3 12 a 8 EE 21 AlazarGetAutoDMAHeaderValue acota ttl 3 3 22 Oltra DMA 3 4 25 AlazarGetBoardK ind 3 3 26 Al 3 3 27 Alar CPLO VEO iii nic icincicaata L O ERA A iaaa LI 3 3 29 AlazarGetMaxRecordsCapable A teammate nama 3 3 30 AlazarGetNextAutoD MA Butter iccccccsscccssesseccenesseccesassncsesansecsenarsnesesasszerasen 113 3 3 31 PA AA LLG 3 3 32 AlazarGetParameter erred i ied 33 334 lara Parametros ANO 3 3 34 AlazarGetS DK Version ic errar LD L 3 2 39 S AlazarGetSiatus a aia is TI 1 3 3 49 ee iio A E 3 3 50 Akeake di AER OA AAA Y EXA AlazarResetTimeStam AA E DI A id O 2003 2010 Alazar Technologies Inc v SDK Programmer s Guide 3 3 SAA DE astra 162 3 3 57 AlazarSetParameter EEE arcane E E ern EN 1
49. value in decimal 32736 16 bit sample value in hex TFEO 16 bit sample value in binar 0111 1111 1110 0000 12 bit sample code from most significant bits of 16 bit sample 0111 1101 1110 value 12 bit sample code in hex 12 bit sample code in decimal 2046 2 5 1 2 3 Converting unsigned 12 bit sample codes to volts An unsigned code of 2048 0x800 represents OV input voltage 4095 OxFFF represents a positive full scale input voltage and 0 represents a negative full scale input voltage The following table illustrates how unsigned 12 bit sample codes map to values in volts according to the full scale input range of the input channel Sample Sample Sample value as a Sample value in Sample value in code in code in percentage of full volts if full scale volts 1f full decimal hex scale input range input range is scale input 100 mV range is 1 V 0 0x0 100 100 mV 1024 0x400 2048 0x800 3072 0xC00 3072 4095 OxFFF 100 100 mV The following code fragment demonstrates how to convert a 2 byte word containing an unsigned 12 bit sample code to in volts double SampleToVoltsU12 U16 sampleValue double inputRange volts Right shift 16 bit sample word by 4 to get 12 bit sample code int bitShift 4 U16 sampleCode sampeValue gt gt bitShift AlazarTech digitizers are calibrated as follows int bitsPerSample 12 double codeZero 1 lt lt bitsPerSample 1 0 5 double codeRange 1
50. was transferred into RecordsTransferred in out Indicates how many records have been transferred This value will always be a multiple of RecordsPerBuffer It is the application s responsibility to initialize the variable to 0 prior to the first call Error out Error code This error code may be one of the following values Identifier Value ADMA Completed ADMA Success ADMA Bufferl Invalid ADMA Buffer2Invalid ADMA BoardHandlelnvalid ADMA InternalBuffer1 Invalid Meaning No errors occurred No errors occurred Bufferl is not a suitable buffer Buffer2 is not a suitable buffer Board handle is not valid The routine cannot allocate enough memory because system resources are low ADMA InternalBuffer2Invalid 5 The routine cannot allocate enough memory because system resources are low A hardware overflow occurred The channel selected is invalid jak N ADMA OverFlow ADMA InvalidChannel Value po o a 2 Ca 6 7 2003 2010 Alazar Technologies Inc 114 SDK Programmer s Guide ADMA_DMAInProgress 8 A memory transfer is in progress ADMA UseHeaderNotSet 9 UseHeader must be set ADMA HeaderNotValid An invalid header was encountered ADMA InvalidRecsPerBuffer 11 RecordCount must be a perfect multiple of RecsPerBuffer rl in RESERVED r2 in RESERVED TriggersOccurred out This is the total number of triggers that have been captured since the last start capture r4
51. 2 seal 2 VisualBasic AlazarGetNextAutoDMABuf fer ByVal h As Integer ByRef Bufferl As Any ByRef Buffer2 As Any ByRef WhichOne As Long ByRef RecordsTransferred As Long ByRef error As Long ByVal iil As LONG ByVal r2 As Long ByRef TriggersOccurred As Long ByRef r4 As Long As Long Parameters h in Handle to the device 2003 2010 Alazar Technologies Inc 11 SDK Programmer s Guide Buffer out This Buffer is used to transfer a complete set of Records from the Device back to the user application It is one of two buffers that are alternated between The second buffer is Buffer2 Buffer should be large enough to contain RecordsPerBuffer TransferLength many 16 bit values VB Integer C amp C short If the Record header is selected UseHeader 1 then Buffer should be large enough to hold RecordsPerBuffer TransferLength sizeof ALAZAR HEADER many 16bit values Buffer2 out This Buffer is used to transfer a complete set of Records from the Device back to the user It is one of two buffers that are alternated between The other buffer is Buffer Buffer2 should be large enough to contain RecordsPerBuffer TransferLength many 16 bit values VB Integer C amp C short If the Record header is selected UseHeader 1 then Buffer2 should be large enough to hold WhichOne out This is a return value that indicates to the user which of the two Buffers Buffer or Buffer2 the data
52. 2003 2010 Alazar Technologies Inc 1s SDK Programmer s Guide SampleRateld in ATS310 sample rate identifiers Identifier SAMPLE RATE 20KSPS SAMPLE RATE 5MSPS SAMPLE RATE USER DEF ATS330 ATS850 sample rate identifiers SAMPLE RATE _10KSPS SAMPLE RATE 500KSPS SAMPLE RATE USER DEF ATS460 sample rate identifiers 2003 2010 Alazar Technologies Inc SDK Programmer s Guide ATS660 sample rate identifiers Sample rate value in Hz 100000000 100 130 MHz apie clock in 130000000 steps of 1MHz from 10 MHz PLL clock ATS860 sample rate identifiers SAMPLE_RATE_2KSPS SAMPLE RATE 20KSPS 2003 2010 Alazar Technologies Inc 154 SDK Programmer s Guide SAMPLE RATE 500KSPS SAMPLE RATE 5MSPS SAMPLE RATE 125MSPS ATS9462 sample rate identifiers Identifier SAMPLE RATE 2KSPS SAMPLE RATE 500KSPS SAMPLE RATE 20MSPS Sample rate value in Hz 150000000 150 180 MHz in steps of 1 MHz 180000000 sample clock from 10 MHz PLL external clock ATS9870 sample rate identifiers Identifier SAMPLE RATE 1KSPS 0x00000001 1 KS s internal clock SAMPLE RATE 2KSPS 0x00000002 2 KS s internal clock SAMPLE RATE 5KSPS 0x00000004 5KS s internal clock SAMPLE RATE 10KSPS 0x00000008 10 KS s internal clock 2003 2010 Alazar Technologies Inc 155 SDK Programmer s Guide 1GHz reference clock value 1000000000 1GHz reference clock from 10 MHz PLL exte
53. 3 20 AlazarGetAutoDMAHeaderTimeStamp THIS FUNCTION IS OBSOLETE DO NOT USE IN NEW DESIGNS This routine is a helper function which can be used to retrieve the 40 bit TimeStamp from the header of a particular record The resulting number is composed of both the TimeStampHighPart and TimeStampLowPart thus alleviating the user from calculating the time stamp using the header values Syntax C Css float AlazarGetAutoDMAHeaderTimeStamp HANDLE h U32 Channel WOH aD aie als bets era U32 Record AUTODMA STATUS error De VisualBasic AlazarGetAutoDMAHeaderTimeStamp ByVal h As Integer ByVal Channel As Long ByRef DataBuffer As Any ByVal Record As Long ByRef error As Long As Double Parameters h in Handle to the device Channel in This parameter may be one of the following identifiers or values DataBuffer in The data buffer as returned from AlazarGetNextAutoDMABuffer Record in Signifies the record number of interest for the given Data Buffer Error out Error return code This error code may be one of the following values 2003 2010 Alazar Technologies Inc 99 SDK Programmer s Guide ADMA Completed 0 Noerrorsoccurred ADMA Success 0 Noerrorsoccurred ADMA Buffer2Invalid Buffer2 is not a suitable buffer ADMA BoardHandleInvalid Board handle is not valid ADMA InternalBuffer1 Invalid The routine cannot allocate enough memory because system resources are
54. 330 and ATS850 See Also 2003 2010 Alazar Technologies Inc 149 SDK Programmer s Guide 3 3 52 AlazarSetBWLimit Control bandwidth of an input channel Syntax C C RE TURN_CODE AlazarSetBWLimit HANDLE BoardHandle U32 Channelld U32 Flag 8 VisualBasic AlazarSetBWLimit ByVal BoardHandle As Integer ByVal Channelld As Long ByVal Flag As Long As Long Parameters BoardHandle in Handle to board Channelld in Channel identifier Flag in Enable bandwidth limit flag The flag can be one of the following values 0 Disable bandwidth limit Enable bandwidth limit Return value If the function succeeds it returns ApiSuccess 512 If the function fails it returns an error code that indicates the reason that it failed See Table 1 for a list of error codes Remarks The bandwidth limiter is disabled by default When enabled the bandwidth limiter reduces input bandwidth to approximately 20 MHz See Also AlazarInputControl 2003 2010 Alazar Technologies Inc 150 SDK Programmer s Guide 3 3 53 AlazarSetCaptureClock Configure sample clock source edge and decimation Syntax CACA RETURN_CODE AlazarSetCaptureClock HANDLE BoardHandle U32 Sourceld U32 SampleRateld U32 Edgeld U32 Decimation DA VisualBasic AlazarSetCaptureClock ByVal BoardHandle As Integer ByVal Sourceld As Long ByVal SampleRateld As Long ByVal Edgeld As Long
55. 63 SL Albar SoPa a did 165 3 3 59 AlazarSeRecordCount AR ON CR NI AE 167 O 2003 2010 Alazar Technologies Inc vi SDK Programmer s Guide 1 Getting Started 1 1 Introduction AlazarTech supplies Windows and Linux device drivers that allow applications to control AlazarTech digitizer boards and transfer sample data from the boards to application buffers The AlazarTech SDK includes the header and library files necessary for programmers to use functions exported by the device drivers in their applications as well as documentation and sample code describing how to use these functions This document is a part of the AlazarTech SDK It describes how to use the functions exported by the device drivers to control one or more digitizer boards It is divided into the following sections e A programming guide that describes how to configure and acquire data from digitizer boards e A reference guide that describes the functions exported by the device drivers Programmers who wish to integrate the AlazarTech SDK into their applications should 1 Read the user manual supplied their AlazarTech digitizer board It provides an overview of the board s hardware features as well as detailed specifications 2 Read the Programmer s guide section of this document It describes how to program the hardware to make an acquisition and to transfer sample data into application buffers 3 Browse the SDK sample programs They include
56. ANDLE BoardHandle U32 Ledon YE VisualBasic AlazarSetLED ByVal BoardHandle As Integer ByVal LedOn as Integer As Integer Parameters BoardHandle in Handle to board LedOn in Specify LED state This parameter may have one of the following values LED OFF 0 Tum off LED Return value If the function succeeds it returns ApiSuccess 512 If the function fails it returns an error code that indicates the reason that it failed See Table 1 for a list of error codes Remarks See the ATS_SDK_DIR Samples AlazarSysInfo for a sample program that controls the LED See Also 2003 2010 Alazar Technologies Inc 162 SDK Programmer s Guide 3 3 57 AlazarSetParameter Set a device parameter as a signed long value Syntax CY Car RE TURN_CODE AlazarSetParameter HANDLE BoardHandle U8 Channelld U32 Parameterld long Value VG VisualBasic AlazarSetParameter ByVal BoardHandle As Integer ByVal Channelld As Byte ByVal Parameterld As Long ByVal Value As Long As Long Parameters BoardHandle in Handle to board Channelld in The channel to control This channel identifier may be one of the following values CHANNEL A Apply parameter to CH A CHANNEL B Apply parameter to CH B oo JO The parameter does not apply to a channel Parameterld in Parameter to modify The parameter identifier may be one of the following values See Alaza
57. AlazarTech SDK Programmer s Guide Version 5 8 2 May 28 2010 o AlazarTech SDK Programmer s Guide License Agreement Important By using this software you accept the following terms of this License Agreement If you do not agree with these terms you should not use the software and promptly return it for a refund Ownership Alazar Technologies Inc retains the ownership of this copy of the enclosed software package It is licensed to you for use under the following conditions Grant of License You may only concurrently use the enclosed software on the computers that have an Alazar Technologies Inc waveform digitizer card plugged in for example if you have purchased one Alazar Technologies Inc card you have a license for one concurrent usage If the number of users of the software exceeds the number of Alazar Technologies Inc cards you have purchased you must have a reasonable process in place to assure that the number of persons concurrently using the software does not exceed the number of Alazar Technologies Inc cards purchased You may transfer this software to another party if the other party agrees to the terms and conditions of the agreement and completes and returns a registration card to Alazar Technologies Inc The registration card is available by writing to Alazar Technologies Inc If you transfer the software you must simultaneously transfer all documentation and related disks Restrictions
58. AutoDMA operating modes AutoDMA Triggered Pre Record Description mode trigger headers samples Traditional Yes Yes Optional Acquire multiple records one per trigger event Each record may contain samples before and after its trigger event Each buffer contains one or more records A record header may optionally precede each record PT NoPreTrigger Acquire multiple records one per trigger event Each record may contain only samples after its 2003 2010 Alazar Technologies Inc 29 SDK Programmer s Guide PEO FO E O AAA one or more records Continuous Acquire a single gapless record streaming spanning multiple buffers where each buffer contains a segment from the record Do not wait for a trigger event before acquiring the record Acquire a single gapless record streaming spanning multiple buffers where each buffer contains a segment from the record Wait for a trigger event before acquiring the record To make an AutoDMA acquisition an application must e Specify the AutoDMA mode samples per record records per buffer and records per acquisition Arm the board to start the acquisition Wait for an AutoDMA buffer to be filled process the buffer and repeat until the acquisition is complete The AlazarTech SDK supplies two groups of functions to make AutoDMA acquisitions the Asynchronous AutoDMA and Synchronous AutoDMA APIs Both allow a board to transfer a segment of an AutoDMA
59. Dual port Synchronous AutoDMA Name Purpose AlazarAbortAutoDma Abort synchronous AutoDMA acquisition AlazarCloseAUTODma Release any resources allocated during a 2003 2010 Alazar Technologies Inc 64 SDK Programmer s Guide po synchronous AutoDMA acquisition AlazarEvents Enable a board to wait for the end of an AutoDMA transfer AlazarForceTriggerEnable Generate a software trigger enable event AlazarFlushAutoDMA Stop a synchronous AutoDMA acquisition buffer AutoDMA buffer record in an AutoDMA buffer AlazarGetNextAutoDMABuffer AlazarGetNextBuffer AutoDMA acquisition DMA request to the board AlazarWaitForBufferRead Wait for an AutoDMA transfer to complete 3 2 5 All functions AlazarAbortAsyncRead Abort an asynchronous AutoDMA acquisition and release any resources allocated during the acquisition AlazarAbortAutoDma AlazarAbortCapture Abort a ae ported acquisition to on board memor available to be filled by a board Configure a board to make an asynchronous AutoDMA acquisition AlazarAutoCalibrate Performa a board specific calibration AlazarBoardsFound Get the number of boards detected in all board systems AlazarBoardsInSystemByHandle Get the number of boards in the board system specified by the handle to its master board system specified by its system identifier memory is in progress AlazarClose Close a board handle AlazarCloseAUTODma Ba any resources allocated dur
60. EF clock source the decimation value must be 1 2 4 or any multiple of 5 Note that the sample rate identifier value must be 500000000 and the sample rate will be 500 MHz divided by the decimation value See Also 2003 2010 Alazar Technologies Inc 158 SDK Programmer s Guide 3 3 54 AlazarSetExternalClockLevel Set the external clock comparator level Syntax C C RE TURN_CODE AlazarSetExternalClockLevel HANDLE BoardHandle ctloat Level percent De VisualBasic AlazarSetExternalClocklevel ByVal BoardHandle As Integer ByVal level percent As Single As Long Parameters BoardHandle in Handle to board Level percent in The external clock comparator level in percent Return value If the function succeeds it returns ApiSuccess 512 If the function fails it returns an error code that indicates the reason that it failed See Table 1 for a list of error codes Note that the function fails with error code ApiUnsupportedFunction 533 if the digitizer does not support setting the external clock comparator level The following table lists the boards that support this feature ATS310 ATS330 ATS460 ATS850 No ATS860 ATS660 ATS9350 ATS9462 ATS9870 Remarks The ATS9350 has an auto adjusting AC coupled external clock input receiver that should work correctly with most external clock signals As a result most applications should not need to adjust the external clock comparator
61. F F3 7F FO F FC F FA F 01 80 EF F Each 16 bit sample value occupies 2 bytes in the buffer so the figure displays 64 sample values 128 bytes 2 bytes per sample 2003 2010 Alazar Technologies Inc 54 SDK Programmer s Guide The first 2 bytes in the buffer shown highlighted are 0x14 and 0x80 Two byte samples values are stored in little endian byte order in the buffer so the first sample value is 0x8014 The following code fragment demonstrates how to access each 16 bit sample value in a buffer Ul6 pSamples Ul6 buffer for U32 sample 0 sample lt samplesPerBuffer sample Ul6 sampleValue pSamples printf sample value 04X n sampleValue 2 5 1 4 2 Getting 16 bit sample codes from 16 bit sample values A16 bit sample code is stored in each 16 bit sample value in the buffer In the example above the first sample code is 0x8014 or 32788 decimal 2 5 1 4 3 Converting unsigned 16 bit sample codes to volts An unsigned code of 32768 0x8000 represents OV input voltage 65535 OxFFFF represents a positive full scale input voltage and 0 represents a negative full scale input voltage The following table illustrates how unsigned 16 bit sample codes map to values in volts according to the full scale input range of an input channel Sample Sample value as a Sample value in Sample value in code in percentage of full volts 1f full scale volts 1f full decimal scale input rang
62. IN falls below 2 V assuming the signal s range is less than 5V with DC coupling Calculate the trigger level code from the level and range double triggerLevel volts 2 trigger level double triggerRange volts 5 input range U32 triggerLevel code U32 128 127 triggerLevel volts triggerRange volts Configure trigger engine J to generate a trigger event on the falling edge of an external trigger signal AlazarSetTriggerOperation handle HANDLE board handle TRIG ENGINE OP J U32 trigger operation TRIG ENGINE J U32 trigger engine id TRIG EXTERNAL U32 trigger source id TRIGGER SLOPE NEGATIVE U32 trigger slope id triggerLevel U32 trigger level 0 255 TRIG ENGINE K U32 trigger engine id TRIG DISABLE U32 trigger source id for engine K TRIGGER SLOPE POSITIVE U32 trigger slope id 128 U32 trigger level 0 255 Configure the external trigger input to 5V range with DC coupling AlazarSetExternalTrigger handle HANDLE board handle DC_COUPLING U32 coupling id ETR_5V U32 external range id 2 3 3 4 Trigger timeout AlazarTech digitizer boards can be configured to automatically trigger when the board is waiting for a trigger event but no trigger events arrive after a spe
63. MA mode and options chosen See section 2 4 2 Dual port AutoDMA above Also note that AlazarTech digitizer boards generate unsigned sample codes by default See section 2 4 3 Data format above 2 5 1 1 ATS850 ATS860 ATS9870 2 5 1 1 1 Getting 1 byte sample values from the buffer The figure below shows the first 128 bytes of data in a buffer from an 8 bit digitizer such as the ATS850 ATS860 or ATS9870 Figure 2 6 8 bit sample data 000000 FE 7F 7F 7F 7F 7F 7F 7F 7E 7F 7F 7F 7F 7F 7F 7F 000010 7F F E E 7F 7F 7F 7F 7E F 7F 7F 7F E 7F 7F 000020 E F 7F E 7F 7E 7F 7F F 7F 7F 7F 7F E 7F 7F 000030 7F F E E E 7F 7F 7F F F 7F 7F 7F 7F 7F 7F 000040 7F 7F 7F E F 7E 7E 7E F E 7F 7F 7F F 7 7E 7F 000050 E F 7F E 7F 7E 7F 7E 7E F 7F 7F 7F 7F 7F 7E 000060 E 7F 7F E E 7F 7F 7F F F 7F 7F 7F 7F 7F 7F 000070 E F 7F F F F 7F F F F 7F F 7F 7F F F Each 8 bit sample occupies 1 byte in the buffer so the figure displays 128 samples 128 bytes 1 byte per sample The following code fragment demonstrates how to access each 8 bit sample value in a buffer U8 pSamples U8 buffer for U32 sample 0 sample lt samplesPerBuffer sample U8 sampleValue pSamples printf sample value 02X n sampleValue 2 5 1 1 2 Getting 8 bit sample codes from 1 byte sample values Each 8 bit sample value stores an 8 bit sample code For example the first byte in buffer abov
64. Otherwise the function returns an error code that indicates the reason that it failed See Table 1 for a list of error codes Remarks To convert the trigger delay from seconds to sample clocks multiple the sample rate in samples per second by the trigger delay in seconds For example if the sample rate is 50 MS s and the desired trigger delay is 1 ms then the trigger delay in sample clocks is 50e6 samples per second x le 3 seconds 50000 samples The trigger delay value may be 0 to 9 999 999 samples The trigger delay value must be a multiple of 4 for the ATS850 and ATS860 See Also AlazarSetExternalTrigger AlazarSetTriggerOperation AlazarSetTriggerTimeQut 2003 2010 Alazar Technologies Inc 171 SDK Programmer s Guide 3 3 62 AlazarSetTriggerOperation Configure the trigger system Syntax C C RETURN_CODE AlazarSetT HAND YSZ U32 U32 032 US U32 U32 U32 Iy VisualBasi aa rig Pica Pe aL Sou gerOperation LE BoardHandle ggerOperation ggerEngineldl mes LCL Slopeldl Lev TEE Sou uN e ell ggerEngineld2 os lez lopeld2 U32 Level2 AlazarSetTriggerOperation ByVal B ByVal ByVal oardHandle As Integer TriggerOperation As Long TriggerEngineldl As Long ByVal S s ourceldl As Long ByVal ByVal I opeldl As Long ievell As Long ByVal I riggerEngineld2 As Long
65. PI described in section 2 4 2 below 2003 2010 Alazar Technologies Inc 21 SDK Programmer s Guide 2 4 1 1 Acquiring to on board memory 2 4 1 1 1 Dual channel mode By default AlazarTech digitizer boards share on board memory equally between both of a board s input channels A single port acquisition in dual channel mode captures samples from both input channels simultaneously to on board memory and after the acquisition is complete allows samples from either input channel to be transferred from on board memory to an application buffer To program a board acquire to on board memory in dual channel mode 1 Call AlazarSetRecordSize to set the number of samples per record where a record may contain samples before and after its trigger event 2 Call AlazarSetRecordCount to set the number records per acquisition the board captures one record per trigger event 3 Call AlazarStartCapture to arm the board to wait for trigger events 4 Call AlazarBusy in a loop to poll until the board has received all trigger events in the acquisition and has captured all records to on board memory 5 Call AlazarRead AlazarReadEx or AlazarHyperDisp to transfer records from on board memory to host memory 6 Repeat from step 3 if necessary The following code fragment acquires to on board memory with on board memory shared between both input channels 1 Set record size AlazarSetRecordSize boardHandle
66. Remarks Y ou must call AlazarBeforeAsyncRead and AlazarPostAsyncBuffer before calling AlazarWaitAsyncBufferComplete Y ou must call AlazarAbortAsyncRead before your application exits if you have called AlazarPostAsyncBuffer and buffers are pending when you wish to exit your application Each call to AlazarPostAsyncBuffer adds a buffer to end of a list of buffers to be filled by the board AlazarWaitAsyncBufferComplete expects to wait on the buffer at the head of the list of buffers available to be filled by the board As a result you must wait for buffers in the same order that they were posted When AlazarWaitAsyncBufferComplete returns ApiSuccess 512 the buffer is removed from the list of buffers to be filled by the board The arrangement of sample data in each buffer depends on the AutoDMA mode specified in the call to AlazarBeforeAsyncRead See Also AlazarAbortAsyncRead AlazarBeforeAsyncRead AlazarPostAsyncBuffer Using asynchronous AutoDMA 2003 2010 Alazar Technologies Inc 185 SDK Programmer s Guide 3 3 70 AlazarWaitForBufferReady THIS FUNCTION IS DEPRECATED DO NOT USE IN NEW DESIGNS This function will stall the current thread of execution for tms number milliseconds or until a buffer has been successfully transferred to a user space AutoDMA buffer The function must be called after API AlazarEvents h 1 and before API AlazarGetNextAutoDMA Buffer It will wait on the driver to signal the Driver s
67. S860 256M about 2 5 seconds to transfer a 250 000 000 sample record from on board memory across the PCI bus to a buffer in host memory With HyperDisp enabled it would take the on board FPGA a fraction of a second to process the record and transfer a few hundred samples from on board memory across the PCI bus to a buffer in host memory Example The ATS SDK _DIR SinglePort HD sample program demonstrates how to use the AlazarHyperDisp API See Also AlazarGetTriggerAddress AlazarRead AlazarReadEx 2003 2010 Alazar Technologies Inc 133 SDK Programmer s Guide 3 3 42 AlazarlnputControl Select the input coupling range and impedance of a digitizer channel Syntax CETT RETURN_CODE AlazarInputControl HANDLE BoardHandle U8 Channelld US2 Comolilae hol U32 Rangeld U32 Impedanceld VisualBasic AlazarInputControl ByVal BoardHandle As Integer ByVal Channelld As Byte ByVal Couplingld As Long ByVal Rangeld As Long ByVal Impedanceld As Long As Long Parameters BoardHandle in Handle to a board Channelld in Select the channel to control This parameter may be one of the following identifiers or values Couplingld in Specify coupling of selected channel This parameter may be one of the following identifiers or values See the remarks below AC COUPLING DC COUPLING Rangeld in Specify full scale input range of selected channel This parameter may be one
68. This may be useful if a full record is too large to transfer as a single block or if only part of a record is of interest Use AlazarRead or AlazarReadEx to transfer records with less than 2 147 483 648 samples Use AlazarReadEx to transfer records with 2 147 483 648 or more samples Examples See Also AlazarRead AlazarHyperDisp AlazarGetTriggerAddress Using AlazarRead 2003 2010 Alazar Technologies Inc 148 SDK Programmer s Guide 3 3 51 AlazarResetTimeStamp Control record timestamp counter resets Syntax Care RE TURN_CODE AlazarResetTimeStamp HANDLE BoardHandle U32 Option ye VisualBasic AlazarResetTimeStamp ByVal BoardHandle As Integer ByVal Option As Long As Integer Parameters BoardHandle in Handle to board Option in Record timestamp counter reset options The option can be one of the following values See AlazarApi h for a complete list Identifier TIMESTAMP RESET FIRSTTIME ONL Reset the timestamp counter to Y zero on the next call to 0 AlazarStartCapture but not thereafter TIMESTAMP RESET ALWAYS Reset the timestamp counter to 1 zero on each call to AlazarStartCapture This is the default operation Return value If the function succeeds it returns ApiSuccess 512 If the function fails it returns an error code that indicates the reason that it failed See Table 1 for a list of error codes Remarks This function is not supported by the ATS310 ATS
69. aFlags Add two or more b uffers toa available to for i 0 i lt be filled by the AlazarAsyncRead BUFFER COUNT i an Au toDMA acquisition HANDLE board handle U32 enabled channel mask long trigger ofset U32 samples per buffer U32 records per buffer U32 records per acquisition U32 AutoDMA flags lt list of buffers board handle HANDLE board handle ToBufferArray i buffer void buffer ToBufferArray i bytesPerBuffer U32 buffer length amp loBufferArray i overlapped OVERLAPPED Arm the board to begin the acquisition AlazarStartCapture handle Wait for each buffer in the acquisition to be filled U32 buffersCompleted 0 while buffersCompleted lt buffersPerAcquisition Wait for the board to receives sufficient trigger events to fil list of available bu The event hand e will ffers the buffer is U32 bufferIndex ull buff IO BUFFER plo WaitForSingl buffersCompl leted Buffer r The buffer is full ll the buffer at the head of its be set to the signaled state when rsCompleted BUFFER COUNT ToBufferArray bufferIndex leObject pIloBuffer gt hEvent process it 2003 2010 Alazar Technologies Inc INFINTE 40 SDK Programmer
70. actor of 1 to 100000 Call AlazarSetCaptureClock specifying EXTERNAL CLOCK 10MHz RFF as the clock source the desired sample rate between 150 and 180 MHz in 1 MHz steps and the decimation factor For example the following code fragment shows how to generate a 15 MS s sample rate with a 10 MHz external clock input AlazarSetCaptureClock handle HANDLE board handle EXTERNAL CLOCK 10MHz REF U32 clock source Id 150000000 U32 sample rate Id or value CLOCK EDGE RISING U32 clock edge Id 10 U32 decimation 3 2 3 1 4 3 ATS9870 In 10 MHz PLL external clock mode the ATS9870 generates a 1 GHz sample clock from an external 10 MHz reference input The 1 GS s sample data can be decimated by 1 2 4 or any multiple of 10 Call AlazarSetCaptureClock specifying EXTERNAL_CLOCK_10MHz_REF as the clock source and 1 GHz as the sample rate value and select a decimation of 1 2 4 or any multiple of 10 up to 100000 For example the following code fragment shows how to generate a 250 MS s sample rate with a 10 MHz external clock input AlazarSetCaptureClock handle HANDLE board handle EXTERNAL CLOCK 10MHz REF U32 clock source Id 1000000000 U32 sample rate Id or value CLOCK EDGE RISING U32 clock edge Id 4 U32 decimation 2 3 1 4 4 ATS9350 In 10 MHz PLL external clock mode the ATS9350 generates a 500
71. al clock comparator level of a board AlazarSetExternalTrigger Configure the TRIG IN connector of a board AlazarSetLED Control the LED on the PCI PCIe mounting bracket of a board AlazarSetParameter Set a board property as a signed 32 bit value value on board memory AlazarSetRecordSize Specify the number of samples before and after the sample at the trigger position in a record AlazarSetTriggerDelay Specify the amount of time between the arrival of a trigger event and the acquisition of the first sample of a record AlazarSetTriggerOperation Configure the trigger system of a board AlazarSetTriggerTimeOut Specify the amount of time to wait for a 2003 2010 Alazar Technologies Inc 67 SDK Programmer s Guide hardware trigger before automatically generating a software trigger event AlazarSleepDevice Turn off the ADC converters AlazarStartAutoDMA Configure a board to make a synchronous AutoDMA acquisition AlazarStartCapture Arm a board to wait for trigger events AlazarStopAutoDMA Inhibit the software from issuing any new DMA request to the board AlazarTriggered Determine if a board has received at least one trigger event since the start of an acquisition AlazarWaitAsyncBufferComplete Wait a specified amount of time for a board to receive sufficient trigger events to fill the specified AutoDMA buffer AlazarWaitForBufferReady Sleep until an AutoDMA transfer has completed AlazarWaitNextAsy
72. ameter in AlazarWaitNextAsyncBufferComplete to zero so that data is written to disk without copying data to the user supplied buffer See Also AlazarWaitNextAsyncBufferComplete Using asynchronous AutoDMA 2003 2010 Alazar Technologies Inc 92 SDK Programmer s Guide 3 3 15 AlazarErrorToText Convert a numerical return code to a NULL terminated string Syntax CACA const ehani AlazarErrorToText RETURN_CODE retCode VisualBasic Not available Parameters retCode in Return code from API function Return value Null terminated string containing the identifier name Remarks It is often easier to work with a descriptive error name rather than an error number For example RETURN CODE retCode ApiSuccess printf Return code u means s n retCode AlazarErrorToText retCode The output from this code would be the following Return code 512 means ApiSuccess See Also 2003 2010 Alazar Technologies Inc 93 SDK Programmer s Guide 3 3 16 AlazarEvents THIS FUNCTION IS DEPRECATED DO NOT USE IN NEW DESIGNS This function allows a user to enable or disable usage of software events in AutoDMA mode The driver manages the event processing and a user can only use an event in conjunction with the API AlazarWaitForBufferReady When the events are enabled AlazarWaitForBufferReady will wait until an AutoDMA buffer is available to the users application For
73. ameter must be set to 1 in continuous streaming and triggered streaming AutoDMA modes The RecordsPerAcquisition parameter must be either e Aneven multiple of the RecordsPerBuffer parameter or e Ox7FFFFFFF to indicate that the acquisition should continue indefinitely until aborted When record headers are not enabled the total number of bytes per AutoDMA buffer is given by BytesPerBuffer BytesPerSample SamplesPerRecord RecordsPerBuffer When record headers are enabled the total number bytes per AutoDMA buffer is given by Each record header occupies 16 bytes BytesPerBuffer 16 BytesPerSample SamplesPerRecord RecordsPerBuffer For best performance AutoDMA parameters should be selected so that the total number of bytes per buffer is greater than about 1 MB This allows for relatively long DMA transfers times compared to the time required to prepare a buffer for a DMA transfer and to re arm a DMA engine ATS460 ATS660 and ATS860 digitizer boards require that AutoDMA parameters be selected so that the total number of bytes per buffer is less than 4MB See Also AlazarAsyncRead AlazarAbortAsyncRead AlazarPostAsyncBuffer AlazarWaitAsyncBufferComplete AlazarWaitNextAsyncBufferComplete Using asynchronous AutoDMA 2003 2010 Alazar Technologies Inc 81 SDK Programmer s Guide 3 3 6 AlazarAutoCalibrate Perform a board specific calibration Syntax C C RE TURN CODE Alaz
74. arAutoCalibrate HANDLE BoardHandle VisualBasic AlazarAutoCalibrate ByVal BoardHandle As Integer As Long Parameters BoardHandle in Handle to board Return value The function returns ApiSuccess 512 if it was successful Otherwise the function returns an error code that should indicate the reason that it failed See Table 1 for a list of error codes Remarks This function is not implemented See Also 2003 2010 Alazar Technologies Inc 82 SDK Programmer s Guide 3 3 7 AlazarBoardsFound Determine the number of digitizer boards that were detected in all board systems Syntax C C U32 AlazarBoardsFound VisualBasic AlazarBoardsFound As Integer Parameters None Return value The total number of digitizer boards detected Remarks None See Also AlazarNumOfSystems 2003 2010 Alazar Technologies Inc 83 SDK Programmer s Guide 3 3 8 AlazarBoardsInSystemByHandle Return the number of digitizer boards in a board system specified by the handle of its master board Syntax CY Cast U32 AlazarBoardsInSystemByHandle HANDLE BoardHandle VisualBasic AlazarBoardsFound ByVal BoardHandle As Integer As Integer Parameters BoardHandle in Handle to master board Return value The number of boards in the specified board system Remarks If this function is called with the handle to the master board is a master slave system it
75. arGetCPLD Version AlazarGetDriverVersion 2003 2010 Alazar Technologies Inc 121 SDK Programmer s Guide 3 3 35 AlazarGetStatus Return a bitmask with board status information Syntax CY Car U32 AlazarGetStatus HANDLE BoardHandle I VisualBasic AlazarGetStatus ByVal BoardHandle As Integer As Long Parameters BoardHandle in Handle to board Return value If the function fails the return value is Oxffffffff If the function succeeds the return value is contains board attributes The attributes can include one or more of the following values Attribute At least one trigger timeout occurred At least one CHA sample was out of range during the last acquisition At least one CHB sample was out of range during the last acquisition 8 The PLL is locked ATS660 only Remarks See Also 2003 2010 Alazar Technologies Inc 122 SDK Programmer s Guide 3 3 36 AlazarGetSystemHandle Return the handle of the master board in the specified board system Syntax C C HANDLE AlazarGetSystemHandle U32 SystemId VisualBasic AlazarGetSystemHandle ByVal SystemId As Integer As Integer Parameters Systemld in System identification number Return value If this function succeeds it returns a handle to the master board in the specified board system If the function fails it returns NULL Remarks If the board system specified contains a single independent
76. as Integer As Integer Parameters Systemld in System identifier number Boardld in Board identifier of a board in the specified board system RecordNumber in Record in acquisition 1 indexed Return value The function returns one of the following values 0 This board did not cause the system to trigger 6 Both CH B and EXT TRIG IN on this board caused the system to trigger A trigger timeout on this board caused the system to trigger Remarks This function is part of the single port data acquisition API It cannot be used with the dual port AutoDMA APIs 2003 2010 Alazar Technologies Inc 130 SDK Programmer s Guide Note that this API routine will not work with ATS850 version 1 2 hardware Version 1 3 and higher version number of ATS850 are fully supported as are all versions of ATS330 and ATS310 See Also AlazarGetWhoTriggeredBySystemHandle 2003 2010 Alazar Technologies Inc 131 SDK Programmer s Guide 3 3 41 AlazarHyperDisp Enable the on board FPGA to process records acquired to on board memory and transfer the processed data to host memory Syntax C CFF RE TURN_CODE AlazarHyperDisp HANDLE BoardHandle void Po BNUIE IESE y U32 BufferSize U8 ViewBuffer U32 ViewBufferSize USZ NumOfPixels U32 Option Use ChannelSelect YSZ Record long TransferOffset U32 EREA y VisualBasic Not supported Parameters BoardHandle in
77. azar Technologies Inc 104 SDK Programmer s Guide Error out Error return code This error code may be one of the following values ADMA Completed O No errors occurred ADMA Success O Noerrors occurred Board handle is not valid A DMA_InternalBufferl Invalid dl The routine cannot allocate enough memory because system resources are low memory because system resources are low ADMA OverFlow 6 A hardware overflow occurred ADMA InternalBuffer2Invalid The routine cannot allocate enough 7 ADMA DMAInProgress 8 A memory transfer is in progress ADMA UseHeaderNotSet__ 9 UseHeader mustbeset_ ADMA InvalidRecsPerBuffer 11 RecordCount must be a perfect multiple of RecsPerBuffer Return value See Table 1 for a list of error codes Remarks See Also AlazarGetAutoDMA HeaderTimeStamp AlazarGetAutoDMA HeaderValue 2003 2010 Alazar Technologies Inc 105 SDK Programmer s Guide 3 3 23 AlazarGetBoardBySystemHandle Get a handle to a board in a board system where the board system is specified by a handle to its master board and the board by its identifier within the board system Syntax C C HANDLE AlazarGetBoardBySystemHandle HANDLE BoardHandle U32 Boardld y VisualBasic AlazarGetBoardBySystemHandle ByVal BoardHandle As Integer ByVal BoardId As Integer As Integer Parameters BoardHandle in Handle to master board Boardld in Board identifier in boa
78. ceive all trigger events and capture all records to on board memory while AlazarBusy boardHandle The acquisition is in progress 6 The acquisition is finished Call AlazarRead or AlazarHyperDisp to transfer records from on board memory to your buffer Note that a call to AlazarSetParameter must be made before each call to AlazarStartCapture If the of number of samples per record specified in AlazarSetRecordSize is greater than the maximum number of samples per channel in dual channel mode but is less than the maximum number of samples per record in single channel mode and AlazarSetParameter is not called before calling AlazarStartCapture then AlazarStartCapture will fail with error ApiNotSupportedInDualChannelMode 591 2 4 1 2 Using AlazarRead Use AlazarRead to transfer samples from records acquired to on board memory to a buffer in host memory 2 4 1 2 1 Transferring full records The following code fragment transfers a full CH A record from on board memory to a buffer in host memory Allocate a buffer to hold one record Note that the buffer must be at least 16 samples larger than the number of samples per record U32 allocBytes bytesPerSample samplesPerRecord 16 void buffer malloc allocBytes Y Transfer a CHA record into our buffer AlazarRead boardHandle HANDLE board handle CHANNEL_A U32 channel Id buffer
79. cified time interval This behavior is similar to the automatic trigger mode of oscilloscopes and may be useful to capture waveforms when trigger conditions are unknown Call AlazarSetTriggerTimeOut to specify the amount of time that a board should wait for a hardware trigger event before automatically generating a software trigger event and as 2003 2010 Alazar Technologies Inc 17 SDK Programmer s Guide a result acquiring one record The timeout value is expressed in 10 us units where 0 means disable the timeout counter and wait forever for a trigger event The trigger timeout value should be set to zero once stable trigger parameters have been found Otherwise a board may generate unexpected trigger events if the trigger timeout interval expires before a hardware trigger event occurs The following code fragment configures a board to automatically trigger and acquire one record if it does not receive a trigger event after 1 ms double timeout_sec 1 e 3 1 ms U32 timeout_ticks U32 timeout_sec 10 e 6 0 5 AlazarSetTriggerTimeOut boardHandle HANDLE board handle timeout_ticks U32 timeout_sec 10 e 6 0 infinite The following code fragment configures a board to wait forever for trigger events AlazarSetTriggerTimeOut boardHandle HANDLE board handle 0 U32 timeout_sec 10 e 6 0 infinite 2 3 3 5 Trigger delay An AlazarTech digitizer board can be config
80. d call AlazarGetParameter with GET _ DATA FORMAT to get the current data format The following code fragment demonstrates how to select signed sample data output AlazarSetParameter handle HANDLE board handle 0 U8 channel Id not used SET_DATA FORMAT U32 parameter to set DATA FORMAT SIGNED long value 0 unsigned 1 signed 2 5 Processing data 2 5 1 Converting samples values to volts The data acquisition API s transfer an array of sample values into an application buffer Each sample value occupies 1 or 2 bytes in the buffer where a sample code is stored in the most significant bits of the sample values Sample values that occupy two bytes are stored with their least significant bytes at the lower byte addresses little endian byte order in the buffer To convert sample values in the buffer to volts e Geta sample value from the buffer e Get the sample code from the most significant bits of the sample value e Convert the sample code to volts 2003 2010 Alazar Technologies Inc 46 SDK Programmer s Guide Note that the arrangement of samples values in the buffer into records and channels depends on the API used to acquire the data e Single port acquisitions return a contiguous array of samples for a specified channel See section 2 4 1 Single port acquisitions above e Dual port AutoDMA acquisitions return sample data whose arrangement depends on the AutoD
81. dicate all on board memory to a single channel The on board memory size reported by these boards is the maximum samples per channel in single channel mode In dual channel mode the on board memory is shared equally between both channels See Also 2003 2010 Alazar Technologies Inc 109 SDK Programmer s Guide 3 3 27 AlazarGetCPLDVersion Get the CPLD version number of the specified board Syntax CC RE TURN_CODE AlazarGetCPLDVersion HANDLE BoardHandle U8 MajorNumber U8 MinorNumber De VisualBasic AlazarGetCPLDVersion ByVal BoardHandle As Integer ByRef MajorNumber As Byte ByRef MinorNumber As Byte As Long Parameters BoardHandle in Handle to board MajorNumber out The CPLD major revision number MinorNumber out The CPLD minor revision number Return value The function returns ApiSuccess 512 if it was successful Otherwise the function returns an error code that indicates the reason that it failed See Table 1 for a list of error codes Remarks See Also AlazarGetDriverVersion AlazarGetSDK Version 2003 2010 Alazar Technologies Inc 110 SDK Programmer s Guide 3 3 28 AlazarGetDriverVersion Get the device driver version of the most recently opened device Syntax C C RE TURN_CODE AlazarGetDriverVersion U8 MajorNumber U8 MinorNumber U8 RevisionNumber De VisualBasic AlazarGetDriverVersion ByRef MajorNumber As Byte ByRef MinorNumber As
82. ds in segments 2 4 1 3 Using AlazarReadEx AlazarRead can transfer samples from records acquired to on board memory that contain up to 2 147 483 647 samples If a record contains 2 147 483 648 or more samples use AlazarReadEx rather than AlazarRead AlazarReadEx uses signed 64 bit transfer offsets while AlazarRead uses signed 32 bit transfer offsets Otherwise AlazarReadEx and AlazarRead are identical 2 4 1 4 Using AlazarHyperDisp HyperDisp technology enables the FPGA on an AlazarTech digitizer board to process sample data The FPGA divides a record in on board memory into intervals finds the minimum and maximum sample values during each interval and transfers an array of minimum and maximum value pairs to host memory This allows the acquisition of relatively long records to on board memory but the transfer of relatively short processed records across the PCI PCle bus to host memory For example an ATS860 256M would require over 2 seconds per channel to transfer 256 000 000 samples across the PCI bus However with HyperDisp enabled the ATS860 would require a fraction of a second to calculate HyperDisp data and transfer a few kilobytes of processed data across the PCI bus If an application was searching these records for glitches it may save a considerable amount of time by searching HyperDisp data for the glitches and if a glitch were found transfer the raw sample data from the interval from on board memory to host memory Use A
83. e e Record headers are only available in Traditional AutoDMA mode To enable record headers call AlazarStartAutoDMA with the UseHeader parameter set to 1 and with the mode in the CFlags parameter set to ADMA TRADITIONAL MODE e AlazarGetNextAutoDMABuffer copies sample data from internally allocated AutoDMA buffers to an application buffer An application may call this function with a pointer to a single application allocated buffer rather than two application allocated buffers Buffer 0 and Buffer 1 above without affecting AutoDMA operation e Calling AlazarWaitNextAsyncBufferComplete in a polling loop is equivalent to calling AlazarEvents AlazarWaitForBufferReady and AlazarGetNextAutoDMABuffer but provides more internally allocated buffers better throughput and a simpler programming interface 2 4 2 8 Scanning applications Scanning applications divide an acquisition into frames where each frame is composed of a number of scan lines and each scan line is composed of a number of sample points These applications typically e Wait for a start of frame event e Wait for a number of start of line events capturing a specified number of sample points after each start of line event e Wait for the next start of frame event and repeat To implement a scanning application using a hardware start of frame signal e Connect a TTL signal that will serve as the start of frame event to the AUX I O connecto
84. e input range is scale input 100 mV range is 1 V o o0xo000 100 100 mV 16384 0x4000 32768 0x8000 49152 0xC000 65535 OxFFFF 100 100 mV The following code fragment demonstrates how to convert a 2 byte sample value containing an unsigned 16 bit sample code to in volts double SampleToVoltsU16 U16 sampleValue double inputRange volts AlazarTech digitizers are calibrated as follows int bitsPerSample 16 double codeZero 1 lt lt bitsPerSample 1 0 5 double codeRange 1 lt lt bitsPerSample 1 0 5 Convert sample code to volts double sampleVolts inputRange volts double sampleValu codeZero codeRange Nn Nn 2003 2010 Alazar Technologies Inc SDK Programmer s Guide return sampleVolts 2 5 1 4 4 Converting signed 16 bit sample codes to volts A signed code of 32767 Ox7FFF represents a positive full scale input voltage 0 represents OV input voltage and 32768 0x8000 represents a negative full scale input voltage The following table illustrates how signed 16 bit sample codes map to values in volts according to the full scale input range of the input channel Sample Sample value as a Sample value in Sample value in code in percentage of full volts if full scale volts if full decimal scale input range input range is scale input 100 mV The following code fragment demonstrates how to convert a 2 byte sample wo
85. e following table shows the buffer layout if a board has on board memory Record headers are not supported if a board does not have on board memory Enabled channels H1A RIA H2A R2A HnA RnA HIB RIB H2B R2B HnB RnB Both CH A and CHB HIA RIA HIB RIB H2A R2A H2B R2B HnA RnA HnB RnB Uy WW 2003 2010 Alazar Technologies Inc SDK Programmer s Guide Note that Rxy is a contiguous array of samples for one channel and Hxy is a 16 byte record header 2 4 2 5 1 Record headers A record header is a 16 byte structure defined in AlazarApi h as follows struct HEADERO unsigned int SerialNumber 18 bits 17 0 unsigned int SystemNumber 4 bits 21 18 unsigned int WhichChannel 1 bit 22 unsigned int BoardNumber 4 bits 26 23 unsigned int SampleResolution 3 bits 29 27 unsigned int DataFormat 2 bits 31 30 y struct HEADER1 unsigned int RecordNumber 24 bits 23 0 unsigned int BoardType 8 bits 31 24 y struct HEADER2 U32 TimeStampLowPart bits 31 0 y struct HEADER3 unsigned int TimeStampHighPart 8 bits 7 0 unsigned int ClockSource 2 bits 9 8 unsigned int ClockEdge 1 bit 10 unsigned int SampleRate 7 bits 17 11 unsigned int InputRange 5 bits 22 18 unsigned int InputCoupling 2 bits 24 23
86. e input range input range is scale input 100 mV The following code fragment demonstrates how to convert a 2 byte sample value containing an unsigned 14 bit sample code to in volts double SampleToVoltsU14 U16 sampleValue double inputRange volts Right shift 16 bit sample word by 2 to get 14 bit sample code int bitShift 2 Ul6 sampleCode sampleValue gt gt bitShift AlazarTech digitizers are calibrated as follows int bitsPerSample 14 double codeZero 1 lt lt bitsPerSample 1 0 5 double codeRange 1 lt lt bitsPerSample 1 0 5 Convert sample code to volts double sampleVolts inputRange volts double sampleCod codeZero codeRange return sampleVolts 2 5 1 3 4 Converting signed 14 bit sample codes to volts A signed code of 0 represents OV input voltage 8191 0x1 FFF represents a positive full scale input voltage and 8192 0x2000 represents a negative full scale input voltage The following table illustrates how signed 14 bit sample codes map to values in volts depending on the full scale input range of the input channel Sample Sample Sample value as a Sample value in Sample value in code in code in volts if full scale volts if full decimal hex input range is scale input 2003 2010 Alazar Technologies Inc 53 SDK Programmer s Guide SSS A AA EA 8191 0x2001 100 100 mV 4096 0x3000 o 0x0000 4096 0x1000
87. e stores the sample code 0x7F or 127 decimal 2 5 1 1 3 Converting unsigned 8 bit sample codes to volts A sample code of 128 0x80 represents OV input voltage 255 OxFF represents a positive full scale input voltage and 0 represents a negative full scale input voltage 2003 2010 Alazar Technologies Inc 47 SDK Programmer s Guide The following table illustrates how unsigned 8 bit sample codes map to values in volts according to the full scale input range of the input channel Sample Sample Sample value as a Sample value in Sample value in code in code in percentage of full volts if full scale volts 1f full decimal hex scale input range input range is scale input 100 mV range is 1 V po oxo0 100 I00mv fvw 100 100 mV The following code fragment shows how to convert a 1 byte sample value containing an unsigned 8 bit code to in volts double SampleToVoltsU8 U8 sampleValue double inputRange volts AlazarTech digitizers are calibrated as follows int bitsPerSample 8 double codeZero 1 lt lt bitsPerSample 1 0 5 double codeRange 1 lt lt bitsPerSample 1 0 5 Convert sample code to volts double sampleVolts inputRange volts double sampleValu codeZero codeRange return sampleVolts 2 5 1 1 4 Converting signed 8 bit sample codes to volts A signed code of 0 represents 0V input voltage 127 0x7F represents a
88. e when it crosses the trigger voltage level that is required to generate a trigger event This parameter can be one of the following values Identifier TRIGGER SLOPE POSITIVE The trigger engine output goes from low to high when sample values from the trigger source rise above a specified level TRIGGER SLOPE NEGATIVE 2 The trigger engine output goes from low to high when sample values from the trigger source fall below a specified level Level Level2 in Select the voltage level that the trigger source signal for the specified trigger engine must pass through to generate a trigger event See the remarks below 2003 2010 Alazar Technologies Inc 173 SDK Programmer s Guide Return value The function returns ApiSuccess 512 if it was able to retrieve the value of the specified parameter Otherwise the function returns an error code that indicates the reason that it failed See Table 1 for a list of error codes Remarks The trigger level is specified in terms as an unsigned 8 bit code that represents a fraction of the full scale input voltage of the trigger source 0 represents the negative limit 128 represents the 0 level and 255 represents the positive limit For example if the trigger source is CH A and the CH A input range is 800 mV then 0 represents a 800 mV trigger level 128 represents a 0 V trigger level and 255 represents 800 mV trigger level In general the trigger level code is gi
89. eateStreamFile API function This function creates a binary data file and enables the API to save each buffer received during an AutoDMA acquisition to this file The API uses high performance disk I O functions that would be difficult to implement in high level environments like LabVIEW and Visual Basic As a result it allows an application in such an environment to perform high performance disk streaming with a single additional function call The following code fragment outlines how to write a disk streaming application using AlazarCreateStreamFile Allow the API to allocate and manage AutoDMA buffers flags ADMA ALLOC BUFFERS Configure the board to make an AutoDMA acquisition AlazarBeforeAsyncRead handle HANDLE board handle channelMask U32 enabled channel mask long preTriggerSamples long trigger offset samplesPerRecord U32 samples per record recordsPerBuffer U32 records per buffer recordsPerAcquisition U32 records per acquisition flags U32 AutoDMA mode and options Create a binary data file and enable the API save each AutoDMA buffer to this file AlazarCreateStreamFile handle data bin Arm the board to begin the acquisition AlazarStartCapture handle Wait for each buffer in the acquisition to be filled RETURN_CODE retCode ApiSuccess while retCode ApiSuccess 2003 2010 Alaza
90. ed UseHeader 1 then Bufferl should be large enough to hold RecordsPerBuffer TransferLength sizeof ALAZAR_ HEADER many 16bit values See Also 2003 2010 Alazar Technologies Inc 179 SDK Programmer s Guide AlazarA bortAutoDma AlazarGetNextAutoDMA Buffer Using synchronous AutoDMA 2003 2010 Alazar Technologies Inc 180 SDK Programmer s Guide 3 3 66 AlazarStartCapture Arm a board to start an acquisition Syntax C Ca RETURN CODE AlazarStartCapture HANDLE BoardHandle VisualBasic AlazarStartCapture ByVal BoardHandle As Integer As Long Parameters BoardHandle in Handle to board Return value The function returns ApiSuccess 512 1f 1t was able to retrieve the value of the specified parameter Otherwise the function returns an error code that indicates the reason that it failed See Table 1 for a list of error codes Remarks Only call AlazarStartCapture on the master board in a master slave board system See Also AlazarBeforeAsyncRead AlazarStartAutoDMA 2003 2010 Alazar Technologies Inc 181 SDK Programmer s Guide 3 3 67 AlazarStopAutoDMA THIS FUNCTION IS DEPRECATED DO NOT USE IN NEW DESIGNS This APT is used to inhibit the software from issuing any new DMA request to the device It is meant as a helper function for the AlazarFlushAutoDMA API function Syntax C C Void AlazarStopAutoDMA HANDLE h VisualBasic AlazarStopAut
91. er s Guide that support this option Note that this flag has no effect in single channel mode and is currently only supported by the ATS9870 and ATS9350 When the flag is set each buffer contains data organized as follows RO ABAB RI ABAB R2 ABAB That is each sample from CH A is followed by a sample from CH B When this flag is not set each record in a buffer contains a contiguous array of samples for CH A followed by a contiguous array of samples for CH B where the record arrangement depends on the acquisition mode ADMA GET PROCESSED DATA Enable the API to process each buffer 0x00002000 so that the sample data in a buffer is always arranged as in NPT mode ROA RIA R2A RBO RIB R2B If this flag is not set the data arrangement in a buffer depends on the acquisition mode LabVIEW and other higher level applications may use this flag to simplify data processing since all data buffers will have the same arrangement independent of the acquisition mode Note that the ADMA_ALLOC_BUFFERS flag must also be set to use this option Return value If the function succeeds it returns ApiSuccess 512 If the function fails 1t returns an error code that indicates the reason that it failed See Table 1 for a list of error codes 2003 2010 Alazar Technologies Inc 80 SDK Programmer s Guide Remarks The SamplesPerRecord parameter must be a multiple of 16 The RecordsPerBuffer par
92. er are identical Please refer to Als Remarks AlazarGetNextBuffer and Al er are identical See Also 2003 2010 Alazar Technologies Inc 116 SDK Programmer s Guide 3 3 32 AlazarGetParameter Get a device attribute as a signed long value Syntax CY Car RE TURN_CODE AlazarGetParameter HANDLE BoardHandle U8 Channel U32 Parameter long Value DE VisualBasic AlazarGetParameter ByVal BoardHandle As Integer ByVal Channel As Byte ByVal Parameter As Long ByRef Value As Long As Long Parameters BoardHandle in Handle to board Channel in The channel of the attribute if required Parameter in The parameter identifier Parameter identifiers include the following values See AlazarApi h for a complete list of list of identifiers AA ES ee DATA_WIDTH Get the number of bits per 0x 10000009 sample 0x 10000039 API allocated DMA 0x 10000040 allocated DMA buffers GET DATA FORMAT Return 0 if the data format is 0x 10000042 unsigned or 1 if the data format is signed 0x 10000044 clocks per timestamp clock 0x 10000045 number of records captured 2003 2010 Alazar Technologies Inc 117 SDK Programmer s Guide GET ASYNC_ BUFFERS PENDING 0x 10000050 GET_ASYNC_ BUFFERS PENDING FULL 0x10000051 GET_ASYNC_BUFFERS PENDING EMPTY 0x 10000052 Value out The parameter s value Return value since the start of the acquisition single
93. er engine The trigger engine identifier parameter specifies which of the two trigger engines you wish to configure The parameter may have one of the following values Identifier TRIG ENGINE J 0 Configure trigger engine J TRIG_ENGINE_K 2003 2010 Alazar Technologies Inc 13 SDK Programmer s Guide 2 3 3 1 2 Data source The data source identifier parameter selects the where the specified trigger engine should get its data The parameter may have one of the following values TRIG CHAN A 0 Use samples from CH A TRIG CHAN B Use samples from CH B TRIG EXTERNAL Use a signal from TRIG IN TRIG DISABLE Disable this trigger engine 2 3 3 1 3 Trigger slope The trigger slope identifier parameter selects if the output of the specified trigger engine should become active when sample values from the specified trigger source rise above or fall below a specified level The parameter may have one of the following values TRIGGER SLOPE POSITIVE The trigger engine output goes from low to high when sample values from the trigger source rise above a specified level TRIGGER SLOPE NEGATIVE 2 The trigger engine output goes from low to high when sample values from the trigger source fall below a specified level 2 3 3 1 4 Trigger level The trigger level parameter sets the level that the trigger source must rise above or fall below for the selected trigger engine to become active The trigger level is specified as a
94. error Syntax C C RE TURN_CODE AlazarCloseAUTODma HANDLE h ye VisualBasic AlazarCloseAUTODma ByVal h As Integer As Long Parameters h in Board identification handle Return values See Table 1 for a list of error codes Remarks See Also AlazarA bortAutoDma Using synchronous AutoDMA 2003 2010 Alazar Technologies Inc 88 SDK Programmer s Guide 3 3 13 AlazarConfigureAuxlO Configure the AUX I O connector as an input or output signal Syntax CC RE TURN_CODE AlazarConfigureAuxI0 HANDLE BoardHandle U32 Mode U32 Parameter De VisualBasic AlazarConfigureAuxIo ByVal BoardHandle As Integer ByVal Mode As Long ByVal Parameter As Long As Long Parameters BoardHandle in Handle to board Mode in Specify AUX I O mode This parameter may be one of the following values See AlazarApi h for a complete list of list of parameter identifiers AUX OUT TRIGGER Output a trigger signal synchronized with the sample clock T O connector as an AutoDMA trigger enable signal Output sample clock divided by user defined value Use the AUX I O connector as a general purpose digital output AUX OUT TRIGGER ENABLE Output a TTL high signal during the AUX IN TRIGGER ENABLE Use the edge of a pulse to the AUX trigger enable period Softare calls AlazarForceTriggerEnable to generate a trigger enable event Parameter in Parameter value The meaning of the
95. ers set the BytesToCopy parameter to zero This will cause AlazarWaitNextAsyncBufferComplete to wait for a buffer to complete but not copy any data into the application buffer To enable disk streaming using high performance disk I O functions call AlazarCreateStreamFile before calling AlazarWaitNextAsyncBufferComplete For best performance set the BytesToCopy parameter to zero so that data is streamed to disk without making any intermediate copies in memory If AlazarBeforeAsyncRead is called with the ADMA GET PROCESSED DATA flag AlazarWaitNextAsyncBuferComplete will process buffers so that the data always appears in NPT format RIA R2A RnA RIB R2B RnB This may simply you application but it comes at the expense of added processing time for each buffer If AlazarBeforeAsyncRead is not called with the called with the ADMA GET PROCESSED DATA flag set then arrangement of sample data in a buffer depends on the AutoDMA mode See Also AlazarAbortAsyncRead AlazarBeforeAsyncRead AlazarPostAsyncBuffer Using asynchronous AutoDMA 2003 2010 Alazar Technologies Inc 189
96. ersion information ystemHandle Get a handle to the master board in a board system specified by its system identifier acquired to on board memor acquired to on board memory AlazarGetWhoTriggeredBySystemHandle Get the event that caused a board system 2003 2010 Alazar Technologies Inc 66 SDK Programmer s Guide specified by the handle to its master board to trigger AlazarGetWhoTriggeredBySystemID Get the event that caused a board system specified by its system identifier to trigger AlazarHyperDisp Enable the on board FPGA to divide a record acquired to on board memory into intervals and return the minimum and maximum sample values over each interval AlazarInputControl Configure the range coupling and termination of an input channel of a board AlazarNumOfSystems Get the number of board systems in a PC AlazarOEMDownLoadFPGA Download an FPGA image file to a board AlazarOpen Open a board handle name available to be filled by a board value AlazarRead Transfer all or part of a record acquired to on board memory AlazarReadEx Transfer all or part of a record acquired to on board memory when the record has 2 147 483 648 or more samples AlazarResetTimeStamp Control record timestamp counter reset AlazarSetBW Limit Enable or disable the 20 MHz low pass filter of an input channel of board AlazarSetCaptureClock Configure the timebase of a board AlazarSetExternalClockLevel Set the extern
97. evelJd volts 5 500 mV trigger level U32 triggerLevelJ U32 trigger level J 192 U32 128 127 triggerlevelJ_volts inputRange volts double triggerLevelK volts 2 200 mV trigger level U32 triggerLevelK U32 trigger level K 103 U32 128 127 triggerlevelK volts inputRange volts AlazarSetTriggerOperation handle HANDLE board handle TRIG ENGINE OP J OR K U32 trigger operation TRIG ENGINE J U32 trigger engine id TRIG CHAN B U32 trigger source id TRIGGER SLOPE POSITIVE U32 trigger slope id triggerlevelJ U32 trigger level from 0 to 255 TRIG ENGINE K U32 trigger engine id TRIG DISABLE U32 trigger source id for engine K TRIGGER SLOPE POSITIVE U32 trigger slope id triggerLevelK U32 trigger level from 0 to 255 E 2 3 3 3 External trigger AlazarTech digitizer boards can trigger on a signal connected to its TRIG IN BNC connector Figure 2 4 External trigger connector on PCI PCTe mounting bracket O 2003 2010 Alazar Technologies Inc 16 SDK Programmer s Guide To use an external trigger input e Call AlazarSetTriggerOperation with TRIG_EXTERNAL as the trigger source identifier of at least one of the trigger engines and e Call AlazarSetExternalTrigger to select the range and coupling of the external trigger input The following code fragment configures a board to trigger when the signal connected to the TRIG
98. fied capability Otherwise the function returns an error code that indicates the reason that it failed See Table 1 for a list of error codes Remarks Capability identifiers include the following items See AlazarApi h for a complete list of list of capability identifiers Identifier GET SERIAL NUMBER 0x10000024 Return the board serial number GET LATEST CAL DATE 0x10000026 Return the board s latest 2003 2010 Alazar Technologies Inc 143 SDK Programmer s Guide GET_LATEST_ CAL DATE MONT H GET_LATEST_ CAL DATE DAY GET_LATEST_ CAL DATE YEAR MEMORY SIZE BOARD_TYPE 0x1000002B Return the board type identifier See AlazarGetBoardKind for more information signature GET_PCIE LINK SPEED GET_PCIE LINK WIDTH See Also AlazarGetBoardKind AlazarGetChannelInfo AlazarGetParameter AlazarGetParameterUL 2003 2010 Alazar Technologies Inc calibration date as a decimal number with the format MMDDYY where M is 1 12 DD is 1 31 and YY is 00 99 from 2000 0x1000002D Return the month of the board s latest calibration date as a decimal number with the format MM where M is 1 12 0x1000002E Return the day of month of the board s latest calibration date as a decimal number with the format DD where DD is 1 31 0x1000002F Return the year of the board s latest calibration date as a decimal number with the format YY where YY is 00 99 from 2000 0x1000002A Return the o
99. g code fragment demonstrates how to convert the trigger timestamp returned by AlazarGetTriggerAddress from counts to seconds _ int64 timeStamp_cnt timeStamp cnt _ int64 timestampHighPart lt lt 8 timeStamp_cnt timestampLowPart amp Ox0ff double samplesPerTimestampCount 2 board specific constant double samplesPerSec 50 e6 sample rate double timeStamp sec double samplesPerTimestampCount timeStamp cnt samplesPerSec The following table lists the board specific sample clocks per timestamp count values count ATS310 ATS330 ATS460 ATS660 ATS9462 2 ATS9870 ATS9350 ATS850 ATS860 Example See ATS SDK_DIR Samples SinglePort AR_ Timestamp for a complete sample program demonstrates how to use AlazarGetTriggerAddress and convert the timestamp value to seconds See Also AlazarRead AlazarHyperDisp Nn 2003 2010 Alazar Technologies Inc 12 SDK Programmer s Guide 3 3 38 AlazarGetTriggerTimestamp Retrieve the timestamp in sample clock periods of a record acquired to on board memory Syntax CY Cast RETURN CODE AlazarGetTriggerTimestamp HANDLE BoardHandle U32 Record U64 Timestamp samples 9 VisualBasic AlazarGetTriggerTimestmap ByVal BoardHandle As Integer ByVal Record As Long ByRef Timestamp samples As Currency As Long Parameters BoardHandle in Handle to board Record in Record in acquisition 1 i
100. g system latencies The programmer may need to increase the number of buffers according to the application Note that the number of buffers required by a board is not the same as the number of buffers required by an application There may be little benefit in supplying a board with more than a few tens of buffers each of a few million samples If an application requires much more sample data for data analysis or other purposes the programmer should consider managing application buffers separately from AutoDMA buffers 2 4 2 7 Using synchronous AutoDMA Synchronous DMA API assumes that the PCI digitizer being controlled has dual port acquisition memory As shown below the user program consumes data synchronously with the acquisition loop Hence the name Synchronous DMA A typical sequence of API calls for Synchronous DMA API is shown below For readability purposes the following is pseudo code Please refer to the sample programs provided for exact syntax and details of what the various parameters passed to these routines mean Set up two AutoDMA buffers and start the DMA engine Data will be captured in the two buffers in a pin pong mode You will be able to process the first buffer while data is being captured into the second buffer and vice versa AlazarStartAutoDMA h UserDatal 0 UseHeader mode long bd PreDepth transferlength RecsPerBuffer bd RecordCount amp error CFlags anil r3 r4
101. ggered and AlazarForceTrigger See ATS_ SDK _DIR Samples SinglePort AR_MasterSlave for a sample program that demonstrates how to acquire from a master slave system 2 4 2 Dual port AutoDMA AutoDMA allows a board to capture sample data to on board dual port memory while at the same time transferring sample data from on board dual port memory to a buffer in host memory Data acquisition and data transfer are done in parallel so any trigger events that occur while the board is transferring data will not be missed AutoDMA may be used if e A board has dual port or FIFO on board memory e An application acquires at an average rate in MB s that is less than maximum transfer rate of your board s PCI or PCIe host bus interface AutoDMA must be used if e A board has FIFO on board memory e An application cannot miss trigger events that occur while it transfers data to host memory or re arms for another acquisition e An application acquires more sample points or records than can be stored in on board memory Applications such as ultrasonic testing OCT radar and imaging should use AutoDMA An AutoDMA acquisition is divided into segments AutoDMA hardware on a board transfers sample data one segment at a time from on board memory to a buffer in host memory There may be an unlimited number of segments in an AutoDMA acquisition so a board can be armed to make an acquisition of infinite duration There are four
102. he programmer specifies the number of samples per record records per buffer and buffers in the acquisition Each buffer is organized as follows if a board has on board memory Enabled channels Buffer organization RIA R2A R3A RIB R2B R3B RnB Both CH A and CH B RIA RIB R2A R2B R3A R3B RnA RnB Each buffer is organized as follows if a board does not have on board memory or if sample interleave is enabled Enabled channels RIA R2A R3A RnA CHB RIB R2B R3B RnB Both CH A and CHB RI ABAB R2 ABAB Rn ABAB Note that Rxy is a record with a contiguous array of samples from a channel and Rx AB is a record with interleaved samples from both CH A and CH B See ATS_SDK_DIR Samples DualPort TR for a sample program that demonstrates how to make an AutoDMA acquisition in Traditional mode If record headers are enabled then a 16 byte record header will precede each record in an AutoDMA buffer The record header contains a record timestamp as well as acquisition metadata See section 2 4 2 5 below for a discussion of AutoDMA record headers 2 4 2 2 NPT AutoDMA Use NPT mode to acquire multiple records one per trigger event with no sample points before the trigger event in each record and with no record headers The programmer specifies the number of samples per record records per buffer and buffers in the acquisition Note that NPT mode is highly optimized and suppor
103. i ee ar PEPPI N fo laza while rStartAutoDMA looping 1 AlazarWaitForBufferReady h 10 status AlazarGetNextAutoDMABuffer f status 513 H looping 0 Valid data exists in either UserData 0 or UserData 1 if WhichOne 0 WhichO0ne 1 Process Your Data here if error ADMA OverFlow looping 0 returnValue 4 lazarCloseAUTODma lazarEvents h 0 NPN PSH See Also AlazarEvents Using synchronous AutoDMA 2003 2010 Alazar Technologies Inc 187 SDK Programmer s Guide 3 3 71 AlazarWaitNextAsyncBufferComplete This function returns when the board has received sufficient trigger events to fill the buffer or the timeout interval has elapsed To use this function AlazarBeforeAsyncRead must be called with the ADMA ALLOC BUFFERS flag Syntax O Caras RETURN_CODE AlazarWaitNextAsyncBufferComplete HANDLE BoardHandle MONOS Urea U32 BytesToCopy U32 Timeout_ms 3 VisualBasic AlazarWaitNextAsyncBufferComplete ByVal BoardHandle As Integer ByRef Buffer As Any ByVal BytesToCopy As Long ByVal Timeout_ms As Long As Long Parameters BoardHandle in Handle to board Buffer out Pointer to a buffer to receive sample data from the digitizer board BytesToCopy in The number of bytes to copy into the buffer Timeout_ms in Specify the time to wait in milliseconds for
104. iggerAddress boardHandle HANDLE board handle record U32 record number 1 indexed amp triggerAddress U32 trigger address amp timestampHigh U32 timestamp high part amp timestampLow U32 timestamp low part r Convert the record timestamp from counts to seconds _ int64 timeStamp_cnt timeStamp_cnt __int64 timestampHigh lt lt 8 timeStamp_cnt timestampLow amp 0x0ff double samplesPerTimestampCount 2 board specific constant double samplesPerSec 50 e6 sample rate double timeStamp sec double samplesPerTimestampCount timeStamp_cnt samplesPerSec Call AlazarGetParameter with the GET SAMPLES PER TIMESTAMP CLOCK parameter to obtain the board specific samples per timestamp count value The following table lists these values Samples per timestamp count ATS310 ATS330 ATS460 ATS660 ATS9462 ATS9870 ATS9350 ATS850 ATS860 See ATS_ SDK _DIR Samples SinglePort AR_Timestamps for a complete sample program that demonstrates how to retrieve record timestamps and convert them to seconds 2 4 1 6 Master slave applications If the single port API is used to acquire from master slave board system only the master board in the board system should receive calls to the following API functions 2003 2010 Alazar Technologies Inc 28 SDK Programmer s Guide AlazarStartCapture AlazarAbortCapture AlazarBusy AlazarTri
105. ing a chronous AutoDMA acquisition AlazarConfigureAuxlO Configure the AUX I O connector of a 2003 2010 Alazar Technologies Inc 65 SDK Programmer s Guide for a board terminated string AutoDMA transfer AlazarFlushAutoDMA Stop a synchronous AutoDMA acquisition AlazarForceTrigger Generate a software trigger event AlazarForceTriggerEnable Generate a software trigger enable event buffer AutoDMA buffer of a record in an AutoDMA buffer AlazarGetBoardBySystemHandle Get a handle to a board specified by its board identifier and handle to the master board in its board system AlazarGetBoardBySystemID Get a handle to a board specified by its system identifier and board identifier AlazarGetBoardKind Get a board s model from its handle AlazarGetChannelInfo Get the number of bits per sample and on board memory size in samples per channel AlazarGetCPLDVersion Get the CPLD version of a board AlazarGetDriverVersion Get the driver version of a board AlazarGetMaxRecordsCapable Find the maximum number of records that can be captured to on board memory given a number of samples per record AlazarGetNextAutoDMA Buffer Poll for an AutoDMA transfer to complete AlazarGetNextBuffer Poll for an AutoDMA transfer to complete AlazarGetParameter Get a board parameter as a signed 32 bit value AlazarGetParameterUL Get a board parameter as an unsigned 32 bit value AlazarGetSDK Version Get the API v
106. ion 2003 2010 Alazar Technologies Inc 175 SDK Programmer s Guide 3 3 64 AlazarSleepDevice Control power to ADC devices Syntax CUCA RETURN_CODE AlazarSleepDevice HANDLE BoardHandle U32 SleepState VisualBasic AlazarSleepDevice ByVal BoardHandle As Integer ByVal SleepState As Long As Long Parameters BoardHandle in Handle to board SleepState in Specify power state of ADC converters This parameter can be one of the following values POWER OFF 0 Turn off power to ADC devices POWER ON Turn on power to ADC devices Return value The function returns ApiSuccess 512 if it was able to retrieve the value of the specified parameter Otherwise the function returns an error code that indicates the reason that it failed See Table 1 for a list of error codes Remarks The API automatically powers up all devices when it loads See Also 2003 2010 Alazar Technologies Inc 176 SDK Programmer s Guide 3 3 65 AlazarStartAutoDMA THIS FUNCTION IS DEPRECATED DO NOT USE IN NEW DESIGNS This routine is used to enable the AUTODMA functionalities of the device It must be called prior to calling A r Syntax Parameters h in Handle to the device Bufferl out Data buffer for the first set of transferred records Buffer1 should be large enough to contain RecordsPerBuffer TransferLength many 16 bit values VB Integer C amp C
107. ise the function returns an error code that indicates the reason that it failed See Table 1 for a list of error codes Remarks The number of pre trigger samples must be a multiple of 64 and must not exceed the number of samples per record minus 64 The number of samples per record is the sum of the pre and post trigger samples The number of samples per record has the following requirements Board type Minimum Alignment samples A ATS310 ATS330 116 ATS850 256 4 2003 2010 Alazar Technologies Inc 169 SDK Programmer s Guide The number of samples per transfer is the number of samples per record multiplied by the number of records per transfer in dual port mode using AutoDMA samples samp A a ATS9350 ATS9870 See Also AlazarBeforeAsyncRead AlazarRead AlazarStartAutoDMA 2003 2010 Alazar Technologies Inc 170 SDK Programmer s Guide 3 3 61 AlazarSetTriggerDelay Set the time in sample clocks to wait after receiving a trigger event before capturing a record for the trigger Syntax C Cat RETURN CODE AlazarSetTriggerDelay HANDLE BoardHandle U32 Value VisualBasic AlazarSetTriggerDelay ByVal BoardHandle As Integer ByVal Value As Long As Lomg Parameters BoardHandle in Handle to board Value in Trigger delay in sample clocks Return value The function returns ApiSuccess 512 if it was able to retrieve the value of the specified parameter
108. itsPerSample 12 double codeZero 1 lt lt bitsPerSample 1 0 5 double codeRange 1 lt lt bitsPerSample 1 0 5 Convert sample code to volts double sampleVolts inputRange volts double sampleCod codeZero codeRange return sampleVolts 2003 2010 Alazar Technologies Inc 5I SDK Programmer s Guide 2 5 1 3 ATS460 2 5 1 3 1 Getting 2 byte sample values from the buffer The figure below displays the first 128 bytes of data in a buffer from a 14 bit digitizer such as the ATS460 Figure 2 8 14 bit sample data 000000 4C 7F EC 7F 3C 80 98 80 DO 80 24 81 7C 81 B4 81 000010 3C 82 B4 82 A8 82 60 83 9C 83 14 84 40 84 88 84 000020 EO 84 50 85 DO 85 FC 85 2C 86 BO 86 10 87 58 87 000030 AC 8 10 88 38 88 CC 88 30 89 94 89 98 89 30 BA 000040 44 8A DS 8A 64 8B C8 8B B4 8B 34 8C 78 8C BO 8C 000050 28 8D 94 8D D8 8D 40 8E 90 8E C4 8E 6C 8F 3C 8F 000060 04 90 C8 8F 40 SF E8 8E BO SE 74 8E EO 8D B4 8D 000070 48 8D E8 8C 98 8C 2C 8C F4 8B 70 8B 3C 8B FC 8A Each sample value occupies a 2 bytes in the buffer so the figure displays 64 sample values 128 bytes 2 bytes per sample The first 2 bytes in the buffer shown highlighted are 0x4C and 0x7F Two byte sample values are stored in little endian byte order in the buffer so the first sample value in the buffer is Ox7F4C The following code fragment demonstrates how to access each 16 bit sample value in a buffer Ul6 pSa
109. lazarBusy ByVal BoardHandle As Integer As Long Parameters BoardHandle in Handle to board Return value If the board is busy acquiring to on board memory this function returns 1 Otherwise this function returns 0 Remarks This function is part of the single port acquisition API Once an acquisition to on board memory is finished use the AlazarRead AlazarReadEx or AlazarHyperDisp functions to transfer sample data from on board to host memory See Also AlazarHyperDisp AlazarRead AlazarReadEx AlazarStartCapture 2003 2010 Alazar Technologies Inc 86 SDK Programmer s Guide 3 3 11 AlazarClose THIS FUNCTION IS OBSOLETE DO NOT USE IN NEW DESIGNS Close a board handle Syntax C Csr void AlazarClose HANDLE BoardHandle Ne VisualBasic AlazarClose ByVal BoardHandle As Integer Parameters BoardHandle in Handle to board Return value If the board is acquiring to on board memory this function returns 1 Otherwise this function returns 0 Remarks The API manages board handles internally This function should only be used in applications that are written for single board digitizer systems See Also AlazarOpen 2003 2010 Alazar Technologies Inc 87 SDK Programmer s Guide 3 3 12 AlazarCloseAUTODma THIS FUNCTION IS DEPRECATED DO NOT USE IN NEW DESIGNS This routine will close the AUTODMA capabilities of the device Only call this upon exit or
110. lazarHyperDisp to enable a board to process records in on board memory and transfer processed records to host memory The following code fragment enables an ATS860 256M to process a record in on board memory containing 250 000 000 samples into an array of 100 HyperDisp points where each point contains the minimum and maximum sample values over an interval of 2 500 000 samples in the record Specify number of samples per record 2003 2010 Alazar Technologies Inc 26 SDK Programmer s Guide U32 preTriggerSamples 125000000 U32 postTriggerSamples 125000000 U32 samplesPerRecord preTriggerSamples postTriggerSamples U32 recordsPerCapture 1 Acquire to on board memory omitted Specify the number of HyperDisp points U32 pointsPerRecord 100 Allocate a buffer to store the HyperDisp data U32 bytesPerSample 1 ATS860 constant U32 samplesPerPoint 2 HyperDisp constant U32 bytesPerBuffer bytesPerSample samplesPerPoint pointsPerRecord U8 buffer U8 malloc bytesPerBuffer Enable ATS860 FPGA to process the 250M sample record in on board memory into an array of 100 HyperDisp points and transfer the HyperDisp points into our buffer U32 error AlazarHyperDisp boardHandle HANDLE board handle NULL void reserved samplesPerRecord U32 BufferSize U8 buffer U8 ViewBuffer bytesPerBuffer U32
111. le Output a TTL high signal on the AUX connector e Wait for the number of trigger events necessary to capture the number of records per buffer in one AutoDMA buffer specified at the start of the acquisition Output a TLL low signal on the AUX connector e Repeat The following code fragment configures the AUX I O connector to acquire records per buffer records after it receives a software trigger enable event AlazarConfigureAuxlI10 handle HANDLE board handle AUX_OUT_TRIGGER ENABLE U32 mode 0 U32 parameter not used See section 2 4 2 8 AutoDMA Scanning Applications for more information 2 3 4 5 Trigger enable input The AUX I O connector can be configured as an AutoDMA trigger enable input signal When enabled a board will 2003 2010 Alazar Technologies Inc 20 SDK Programmer s Guide Wait for a rising or falling edge on the AUX I O Wait for the number of trigger events necessary to capture the number of records per buffer in one AutoDMA segment specified at the start of the acquisition e Repeat The following code fragment configures the AUX I O connector to acquire records per buffer records after it receives the rising edge of a TTL pulse connected on the AUX I O connector AlazarConfigureAuxlo handle HANDLE board handle AUX IN TRIGGER ENABLE U32 mode TRIGGER SLOPE POSITIVE U32 parameter
112. le channelMask U32 enabled channel mask long preTriggerSamples long trigger offset samplesPerRecord U32 samples per record recordsPerBuffer U32 records per buffer recordsPerAcquisition U32 records per acquisition flags U32 AutoDMA mode and options 2003 2010 Alazar Technologies Inc 38 SDK Programmer s Guide Arm the board to begin the acquisition AlazarStartCapture handle Wait for each buffer in the acquisition to be filled RETURN_CODE retCode ApiSuccess while retCode ApiSuccess Wait for the board to receive sufficient trigger events to fill an internal AutoDMA buffer The API will copy data from the internal buffer to the user supplied buffer retCode AlazarWaitNextAsyncBufferComplete handle HANDLE board handle pBuffer woid buffer to receive data bytesToCopy U32 bytes to copy into buffer timeout_ms U32 time to wait for buffer The buffer is full process it Note that while the application processes this buffer the board is filling the next available internal buffer as trigger events arrive ProcessBuffer pBuffer bytesPerBuffer ion and release resources be called after an acquisition Abort the acquisit This function must AlazarAbortAsyncRead boardHandle See ATS SDK DIR Samples DualPort CS WaitNextBuffer
113. lthough Alazar Technologies Inc has tested the software and reviewed the documentation ALAZAR TECHNOLOGIES INC MAKES NO WARRANTY OF REPRESENTATION EITHER EXPRESSED OR IMPLIED WITH RESPECT TO THIS SOFTWARE OR DOCUMENTATION ITS QUALITY PERFORMANCE MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE AS A RESULT THIS SOFTWARE AND DOCUMENTATION IS LICENSED as is AND YOU THE LICENSEE ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND PERFORMANCE IN NO EVENT WILL ALAZAR TECHNOLOGIES INC BE LIABLE FOR DIRECT INDIRECT SPECIAL INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THIS SOFTWARE OR DOCUMENTATION even if advised of the possibility of such damages In particular Alazar Technologies Inc shall have no liability for any data acquired stored or processed with this software including the costs of recovering such data THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS ORAL OR WRITTEN EXPRESSED OR IMPLIED No Alazar Technologies Inc dealer agent or employee is authorized to make any modifications or additions to this warranty Information in this document is subject to change without notice and does not represent a commitment on the part of Alazar Technologies Inc The software described in this document is furnished under this license agreement The software may be used or copied only in accordance with the terms of the agreement It is against the law to cop
114. lues ADMA Completed 0 Noerrorsoccurred ADMA InternalBuffer1 Invalid The routine cannot allocate enough memory because system resources are low ADMA InternalBuffer2Invalid The routine cannot allocate enough ADMA BoardHandlelnvalid Board handle is not valid 2003 2010 Alazar Technologies Inc 178 SDK Programmer s Guide A AA low ADMA OverFlow 6 A hardware overflow occurred ADMA InvalidChannel The channel selected is invalid ADMA_DMAInProgress 8 A memory transfer is in progress ADMA UseHeaderNotSet 9 UseHeader must be set ADMA HeaderNotValid An invalid header was encountered ADMA InvalidRecsPerBuffer 11 RecordCount must be a perfect multiple of RecsPerBuffer cFlags in Control Flags 0 The routine will automatically start the acquisition 1 The user application must call AlazarStartCapture to start the acquisition The constants available are as follows Identifier ADMA EXTERNAL_STARTCAPTURE The User must call 0x00000001 AlazarStartCapture to start the acquisition 0x00000000 0x00000100 trigger 0x00000200 r2 in RESERVED r3 out RESERVED r4 out RESERVED Return value See Table 1 for a list of error codes Remarks The user must ensure that Buffer1 is a valid buffer of the appropriate size Bufferl should be large enough to contain RecordsPerBuffer TransferLength many 16 bit values VB Integer C amp C short If the Record header is select
115. mples U16 buffer for U32 sample 0 sample lt samplesPerBuffer sample Ul6 sampleValue pSamples printf sample value 04X n sampleValue 2 5 1 3 2 Getting 14 bit sample codes from 16 bit sample values A 14 bit sample code is stored in the most significant bits of each 16 bit sample value in the buffer so right shift each 16 bit value by 2 or divide by 4 to obtain the 14 bit sample code In the example above the 16 bit value 0x7F4C right shifted by two results in the 14 bit sample code 0x1FD3 or 8147 decimal 16 bit sample value in decimal 32588 16 bit sample value in hex TF4C 16 bit sample value in bina 0111 1111 0100 1100 14 bit sample code from most significant bits of 16 bit sample 01 1111 1101 0011 value 14 bit sample code in hex 1FD3 14 bit sample code in decimal 8147 2 5 1 3 3 Converting unsigned 14 bit sample codes to volts 2003 2010 Alazar Technologies Inc Nn N SDK Programmer s Guide An unsigned code of 8192 0x2000 represents 0V input voltage 16383 Ox3FFF represents a positive full scale input voltage and 0 represents a negative full scale input voltage The following table illustrates how unsigned 14 bit sample codes map to values in volts according to the full scale input range of an input channel Sample Sample Sample value as a Sample value in Sample value in code in code in percentage of full volts if full scale volts if full decimal hex scal
116. n after all of the buffers preceding it have been filled AlazarPostAsyncBuffer handle pBuffer bytesPerBuffer Abort the acquisition and release resources This function must be called after an acquisition AlazarAbortAsyncRead boardHandle See ATS_ SDK _DIR Samples DualPort NPT for a full sample program that demonstrates make an AutoDMA acquisition using AlazarPostAsyncBuffer 2 4 2 6 2 ADMA_ALLOC_BUFERS C and LabVIEW applications may find it more convenient to allow the API to allocate and manage a list of buffers available to be filled by the board These applications should call AlazarBeforeAsyncRead with the AMDA ALLOC BUFFERS option selected in the Flags parameter This option will cause the API to allocate and manage a list of buffers available to be filled by the board The application must call AlazarWaitNextAsyncBufferComplete to wait for a buffer to be filled When the board receives sufficient trigger events to fill a buffer the API will copy the data from the internal buffer to the user supplied buffer The following code fragment outlines how make an AutoDMA acquisition using ADMA ALLOC BUFERS flag and AlazarWaitNextAsyncBufferComplete Allow the API to allocate and manage AutoDMA buffers flags ADMA ALLOC BUFFERS Configure a board to make an AutoDMA acquisition AlazarBeforeAsyncRead handle HANDLE board hand
117. n board memory size in maximum samples per channel in single channel mode See AlazarGetChannellnfo for more information 0x 10000030 Return the PCIe link speed negotiated between a PCIe digitizer board and the host PCIe bus 0x10000031 Return the PCIe link width negociated between a PCIe digitizer board and the host PCIe bus 144 SDK Programmer s Guide 3 3 49 AlazarRead Read all or part of a record from an acquisition to on board memory from on board memory to a buffer in host memory The record must be less than 2 147 483 648 samples long Syntax C CFF U32 AlazarRead HANDLE BoardHandle U32 Channelld void Buffer int ElementSize long Record long 1 TransferOffset U32 TransferLength ye VisualBasic AlazarRead ByVal BoardHandle As Integer ByVal Channelld As Long ByRef Buffer As Any ByVal ElementSize As Integer ByVal Record As Long ByVal TransferOffset As Long ByVal TransferLength As Long As Long Parameters BoardHandle in Handle to a board Channelld out Channel identifier of record Buffer out Buffer to receive sample data ElementSize in Number of bytes per sample Record in Record in on board memory to transfer to buffer 1 indexed TransferOffset in The offset in samples from the trigger position in the record of the first sample in the record in on board memory to transfer into the buffer TransferLength in The
118. n unsigned 8 bit code that represents a fraction of the full scale input range of the trigger source 0 represents the negative full scale input 128 represents a 0 volt input and 255 represents the positive full scale input For example if the trigger source is CH A and the CH A input range is 800 mV then 0 represents a 800 mV trigger level 128 represents a 0 V trigger level and 255 represents 800 mV trigger level In general the trigger level value is given by TriggerLevelCode 128 127 TriggerLevelVolts InputRangeVolts The following table gives examples of how trigger level codes map to trigger levels in volts according to the full scale input range of the trigger source Trigger Trigger level as Trigger level if Trigger level if level code fraction of source input range 2003 2010 Alazar Technologies Inc 14 SDK Programmer s Guide o fao JE EXA 1V 2 3 3 1 5 Trigger operation Finally the trigger operation identifier specifies how the outputs of from the two trigger engines are combined to generate trigger events This parameter may have one of the following values where the symbol T represents the output of trigger engine J and Tk represents the output of trigger engine K Identifier Value Meaning Generate a trigger event when TRIG ENGINE OP J 0 T goes low to high TRIG ENGINE OP K T goes low to high JE OP J TRIG ENGINE OR K 2 T goes low to high o
119. n value The function returns ApiSuccess 512 if it was successful Otherwise the function returns an error code that indicates the reason that it failed See Table 1 for a list of error codes Remarks This function is part of the single port API It should not be used with AutoDMA API functions See Also AlazarHyperDisp AlazarRead AlazarReadEx 2003 2010 Alazar Technologies Inc 112 SDK Programmer s Guide 3 3 30 AlazarGetNextAutoDMABuffer THIS FUNCTION IS DEPRECATED DO NOT USE IN NEW DESIGNS After an application has called AlazarStartAutoDMA the application must call AlazarGetNextAutoDMABuffer to retrieve the data buffers Because of the nature of Auto Dma two buffers are required The device driver dll will arbitrate to which buffer the data will be returned After a buffer has been filled variable WhichOne equals the buffer id thus if the id is 0 then Bufferl was used and likewise if the id is 1 then Buffer2 was used In the case where data is not available WhichOne will equal 1 This routine will always return ApiSuccess 512 when either data has been transferred or when WhichOne 1 A return value of ApiFailed 513 indicates that all the Records Per Buffer has been transferred Syntax C Csr RETURN CODE AlazarGetNextAutoDMABuf fer HANDLE h WOU e ui ls Weel IBUHEIESIE 5 long WhichOne long RecordsTransferred AUTODMA STATUS error USZ iil USZ 122 long TriggersOccurred US
120. nal clock 180 MS s internal clock 200 MS s internal clock SAMPLE RATE 250MSPS 250 MS s internal clock 500 MS s internal clock SA MPLE RATE USER DEF 0x00000040 External clock that is not the 10MHz PLL See the remarks below for 10 MHz PLL external clock mode Edgeld in Select the external clock edge on which to latch samples data The clock edge identifier may be one of the following values CLOCK EDGE RISING 0 Sample on rising edge of external clock CLOCK EDGE FALLING Sample on falling edge of external clock Decimation in Clock decimation value See the remarks below Return value 2003 2010 Alazar Technologies Inc 157 SDK Programmer s Guide If the function succeeds it returns ApiSuccess 512 If the function fails it returns an error code that indicates the reason that it failed See Table 1 for a list of error codes Remarks The clock decimation value may be any integer between 0 and 100000 with the following exceptions Note that a decimation value of 0 means disable decimation e Ifan ATS460 ATS660 ATS860 uses a SLOW EXTERNAL CLOCK clock source the maximum decimation value is 1 e Ifan ATS9870 uses an EXTERNAL CLOCK 10MHz REF clock source the decimation value must be 1 2 4 or any multiple of 10 Note that the sample rate identifier value must be 1000000000 and the sample rate will be 1 GHz divided by the decimation value e Ifan ATS350 uses an EXTERNAL CLOCK_10MHz_R
121. ncBufferComplete Wait a specified amount of time for a board to receive sufficient trigger events to fill an AutoDMA buffer managed by the API 2003 2010 Alazar Technologies Inc 68 SDK Programmer s Guide 3 3 Function Reference This section provides an alphabetical list of the functions exported by the AlazarTech API and their descriptions 3 3 1 AlazarAbortAsyncRead Aborts any in progress DMA transfers and cancel any pending transfers Syntax Cy Cars RETURN CODE AlazarAbortAsyncRead HANDLE BoardHandle VisualBasic AlazarAbortAsyncRead ByVal BoardHandle As Integer As Long Parameters BoardHandle in Handle to board Return value If the function succeeds it returns ApiSuccess 512 If the function fails because it was unable to abort an in progress DMA transfer it returns ApiDmalnProgress 518 If AlazarAbortAsyncRead fails under Windows because the Windows Cancello system call failed the function returns ApiFailed 513 Call the Windows GetLastError API for more information If the function fails for some other reason it returns an error code that indicates the reason that it failed See Table 1 for a list of error codes Remarks If you have called AlazarAsyncRead or AlazarPostAsyncBuffer and there are buffers pending you must call AlazarAbortAsyncRead before your application exits If you do not when you program exits Microsoft Windows may stop with a blue screen error
122. nctions The maximum number of records per capture is a function of the board type the maximum number of samples per channel SPC ax and the current number of samples per record SPR ATS850 ATS310 ATS330 SPC max SPR 16 or 10000 whichever is smaller ATS460 ATS660 SPC max SPR 16 or 256000 records whichever is ATS9462 smaller ATS860 ATS9350 SPC max SPR 32 or 256000 records whichever is 2003 2010 Alazar Technologies Inc 167 SDK Programmer s Guide pf smal ATS9870 SPC max SPR 64 or 256000 records whichever is smaller See Also AlazarRead AlazarHyperDisp AlazarGetTriggerAddress 2003 2010 Alazar Technologies Inc 168 SDK Programmer s Guide 3 3 60 AlazarSetRecordSize Set the number of pre and post trigger samples per record Syntax CETT RETURN_CODE AlazarSetRecordSize HANDLE BoardHandle U32 PreTriggerSamples U32 PostTriggerSamples VisualBasic AlazarSetRecordSize ByVal BoardHandle As Integer ByVal PreTriggerSamples As Long ByVal PostTriggerSamples As Long As Long Parameters BoardHandle in Handle to board PreTriggerSamples in The number of samples before the trigger position in each record PostTriggerSamples in The number of samples at or after the trigger position in each record Return value The function returns ApiSuccess 512 if it was able to retrieve the value of the specified parameter Otherw
123. nd a board was in progress data corruption may occur 2 3 Configuring a board Before acquiring data from a board system an application must configure the timebase analog inputs and trigger system of each board in the board system 2 3 1 Timebase The timebase of the ADC converters on AlazarTech digitizer boards may be supplied by e Its on board oscillators e A user supplied external clock signal e An on board PLL clocked by a user supplied 10 MHz reference signal 2 3 1 1 Internal clock To use on board oscillators as a timebase call AlazarSetCaptureClock specifying INTERNAL CLOCK as the clock source identifier and select the desired sample rate with a sample rate identifier appropriate for the board The following code fragment shows how to select a 10 MS s internal sample rate 2003 2010 Alazar Technologies Inc 7 SDK Programmer s Guide AlazarSetCaptureClock handle HANDLE board handle INTERNAL CLOCK U32 clock source Id SAMPLE RATE 10MSPS U32 sample rate Id or value CLOCK EDGE RISING U32 clock edge Id 0 U32 decimation See AlazarSetCaptureClock or the board reference manual for a list of sample rate identifiers appropriate for a board 2 3 1 2 External clock AlazarTech boards optionally support using a user supplied external clock signal input to the ECLK connector on its PCI PCIe mounting bracket to clock its ADC converters Figu
124. nd options AutoDMA mode must be one of the following values Identifier ADMA TRADITIONAL MODE Acquire multiple records one per trigger 0x00000000 event Each record may include pre and post trigger samples and a record header that includes its trigger timestamp If a board has on board memory and sample interleave is not enabled each buffer will contain samples organized as follows R1A R1B R2A R2B If a board does not have on board memory or sample interleave is enabled the buffer will contain samples organized as follows RI AB R2 AB ADMA NPT Acquire multiple records one per trigger 0x00000200 event Each record contains only post trigger samples If a board has on board memory and sample interleave is not enabled each buffer will contain samples organized as follows RIA R2A RIB R2B If a board does not have on board memory or sample interleave is enabled the buffer will contain samples organized as follows RI AB R2 AB ADMA CONTINUOUS MODE Acquire a single gapless record 0x00000100 spanning multiple buffers Do not wait for trigger event before starting the acquisition If a board has on board memory and sample interleave is not enabled each buffer will contain samples organized as follows RIA RIB 2003 2010 Alazar Technologies Inc 77 SDK Programmer s Guide ADMA TRIGGERED STREAMING 0x00000400 If a board does not have on board mem
125. ndexed Timestamp out Record timestamp in sample clock periods Return value The function returns ApiSuccess 512 and if it was successful The function returns 604 if the record parameter is greater than 1000 Otherwise the function returns an error code that indicates the reason that it failed See Table 1 for a list of error codes Remarks This function is part of the single port data acquisition API It cannot be used to retrieve the timestamp of records acquired using dual port AutoDMA APIs Divide by the trigger timestamp value in sample clock periods by the sample rate to obtain the trigger timestamp value in seconds For example Get the trigger timestamp of the first record in sample clocks U64 timestmap samples AlazarGetTriggerTimestamp handle 1 timestamp samples 2003 2010 Alazar Technologies Inc 126 SDK Programmer s Guide Convert the timestamp from sample clocks to seconds double samplesPerSec 100 e6 double timestamp seconds timestmap samples samplesPerSec See Also AlazarRead AlazarHyperDisp 2003 2010 Alazar Technologies Inc 127 SDK Programmer s Guide 3 3 39 AlazarGetWhoTriggeredBySystemHandle Return which event caused a board system to trigger and capture a record to on board memory Syntax C CFF U32 AlazarGetWhoTriggeredBySystemHandle HANDLE BoardHandle USA BOATE U32 RecordNumber VisualBasic AlazarGetWhoTriggeredBySystemHandle
126. ng bracket of a board AlazarSetParameter Set a board property as a signed 32 bit value AlazarSetParameterUL Set a board property as an unsigned 32 bit value AlazarSetTriggerDelay Specify the amount of time between the arrival of a trigger event and the acquisition of the first sample of a record AlazarSetTriggerTimeQut Specify the amount of time to wait for a hardware trigger before automatically generating a software trigger event AlazarSleepDevice Turn off the ADC converters 3 2 4 Acquisition 3 2 4 1 General Generate a software trigger event AlazarSetRecordSize Specify the number of samples before and after the sample at the trigger position in a record AlazarStartCapture Arm a board to wait for trigger events AlazarTriggered Determine if a board has received at least one trigger event since the start of an acquisition 3 2 4 2 CIA port Name Purpose AlazarAbortCapture Abort a single ported acquisition to on board PE memory AlazarBusy Determine if an acquisition to on board memory is in progress AlazarGetMaxRecordsCapable Find the maximum number of records that can be captured to on board memory given a number of samples per record AlazarGetTriggerAddress Get the trigger address and timestamp of a record acquired to on board memory 2003 2010 Alazar Technologies Inc 63 SDK Programmer s Guide AlazarGetTriggerTimestamp acquired to on board memory AlazarGetWhoTriggeredBySys
127. number 0x000000CB DRIVER LEFT LOCKED PAGES IN PROCESS Linux may leak the memory used by the DMA buffers See Also 2003 2010 Alazar Technologies Inc 69 SDK Programmer s Guide AlazarAsyncRead AlazarPostAsyncBuffer Using asynchronous AutoDMA O 2003 2010 Alazar Technologies Inc 70 SDK Programmer s Guide 3 3 2 AlazarAbortAutoDma THIS FUNCTION IS DEPRECATED DO NOT USE IN NEW DESIGNS This routine is used to terminate the AutoDMA capture in cases where the trigger system stopped generating triggers before the buffer was filled by the AutoDMA engine The routine will populate the buffer with the appropriate number of records that have been successfully captured Syntax CY Cart RE TURN_CODE AlazarAbortAutoDMA HANDLE h VOO Ea AUTODMA STATUS error USZ weil YSZ ie 2 YSZ ied J2 Si Ip VisualBasic AlazarAbortAutoDMA ByVal h As Integer ByRef Bufferl As Any ByRef error As Long ByVal rl As Long ByVal r2 As Long ByRef r3 As Long ByRef r4 As Long As Long Parameters h in Board identification handle Buffer out This Buffer is used to transfer a set of Records from the Device back to the user application Error out Error return code This error code may be one of the following values ADMA_ Completed 0 No errors occurred ADMA Success 0 No errors occurred No errors occurred ADMA BufferlInvalid Buffer1 is n
128. number of samples to transfer from the record in on board memory into the buffer 2003 2010 Alazar Technologies Inc 145 SDK Programmer s Guide Return values If the function succeeds it returns ApiSuccess 512 If the function fails 1t returns an error code that indicates the reason that it failed See Table 1 for a list of error codes Remarks AlazarRead is part of the single port data acquisition API It cannot be used with the dual port AutoDMA APIs AlazarRead can transfer segments of a record acquired to on board memory This may be useful if a full record is too large to transfer as a single block or if only part of a record is of interest Use either AlazarRead or AlazarReadEx to transfer records with less than 2 147 483 648 samples Use AlazarReadEx to transfer records with 2 147 483 648 or more samples Examples The ATS SDK DIR Samples SinglePort AR sample program demonstrates how to use AlazarRead The ATS SDK DIR Samples SinglePort AR Segments sample program demonstrates how to use AlazarRead to split records in to segments for transfer from on board to host memory See Also AlazarHyperDisp AlazarGetTriggerAddress AlazarReadEx Using AlazarRead 2003 2010 Alazar Technologies Inc 146 SDK Programmer s Guide 3 3 50 AlazarReadEx Read all or part of a record from an acquisition to on board memory from on board memory to a buffer in host memory The record may be 2 147
129. o adjusting AC coupled external clock input receiver that should work correctly with most external clock signals As a result most ATS9350 applications should not need to adjust the external clock comparator level 2 3 1 4 10 MHz PLL Some boards can generate a timebase from an on board PLL clocked by user supplied external 10 MHz reference signal input to its ECLK connector 2 3 1 4 1 ATS660 In 10 MHz PLL external clock mode the ATS660 can generate a sample clock between 110 and 130 MHz in 1 MHz steps from an external 10 MHz reference input The sample data can be decimated by a factor of 1 to 100000 Call AlazarSetCaptureClock specifying EXTERNAL CLOCK 10MHz RFF as the clock source identifier the desired sample rate between 110 and 130 MHz in 1 MHz steps and the decimation factor The following code fragment shows how to generate a 32 5 MS s sample rate from a 10 MHz PLL external clock input AlazarSetCaptureClock handle HANDLE board handle EXTERNAL CLOCK 10MHz REF U32 clock source Id 130000000 U32 sample rate Id or value CLOCK EDGE RISING U32 clock edge Id 3 U32 decimation e 2003 2010 Alazar Technologies Inc 9 SDK Programmer s Guide 2 3 1 4 2 ATS9462 In 10 MHz PLL external clock mode the ATS9462 can generate a sample clock between 150 and 180 MHz in 1 MHz steps from an external 10 MHz reference input Sample data can be decimated by a f
130. oDMA ByVal h As Integer Parameters h in Handle to board Return value None Remarks This function is useful in situations where the application software has multiple threads The software can call this routine to stop the device from issuing DMA requests in preparation for calling API AlazarFlushAutoDMA See Also AlazarFlushAutoDMA Using synchronous AutoDMA 2003 2010 Alazar Technologies Inc 182 SDK Programmer s Guide 3 3 68 AlazarTriggered Determine if a board has triggered during the current acquisition Syntax CACA U32 AlazarTriggered HANDLE BoardHandle VisualBasic AlazarTriggered ByVal BoardHandle As Integer As Long Parameters BoardHandle in Handle to board Return value If the board has received at least one trigger event since the last call to AlazarStartCapture this function returns 1 Otherwise this function returns 0 Remarks See Also AlazarStartCapture 2003 2010 Alazar Technologies Inc 183 SDK Programmer s Guide 3 3 69 AlazarWaitAsyncBufferComplete This function returns when a board has received sufficient triggers to fill the specified buffer or the timeout interval elapses Syntax C CFF RE TURN_CODE AlazarWaitAsyncBufferComplete HANDLE BoardHandle WOILCl BIBLE Sie U32 Timeout_ms E VisualBasic AlazarWaitAsyncBufferComplete ByVal h As Integer ByRef Buffer As Any ByVal Timeout_ms As Long As Long Parameter
131. of the following identifiers or values See the remarks below INPUT RANGE PM 20 MV 2003 2010 Alazar Technologies Inc 134 SDK Programmer s Guide INPUT RANGE PM 40 MV INPUT RANGE PM 50 MV INPUT RANGE PM 80 MV INPUT RANGE PM 200 MV INPUT RANGE PM 500 MV INPUT RANGE PM 800 MV INPUT RANGE PM 1 V Impedanceld in Specify termination of selected channel This parameter may be one of the following identifiers or values See the remarks below IMPEDANCE _1M OHM IMPEDANCE 50 OHM Return values If the function succeeds it returns ApiSuccess 512 If the digitizer board does not support the specified input range coupling or the impedance the function returns ApiFailed 513 Otherwise the function returns an error code that indicates the reason that it failed See Table 1 for a list of error codes Remarks The ATS9870 only supports 50Q input impedance The input range table lists all possible input range identifiers The values supported by a particular board depend on the board model and selected input coupling Please refer to specification sheet for your board to determine the support values See Also AlazarSetB WLimit 2003 2010 Alazar Technologies Inc ES Nn SDK Programmer s Guide 3 3 43 AlazarNumOfSystems Get the total number of board systems detected Syntax C Car U32 AlazarNumOfSystems VisualBasic AlazarNumOfSystems As Integer Parameters None
132. ory or sample interleave is enabled the buffer will contain samples organized as follows RI AB Acquire a single gapless record spanning multiple buffers Wait for a trigger event before starting the acquisition If a board has on board memory and sample interleave is not enabled each buffer will contain samples organized as follows RIA RIB If a board does not have on board memory or sample interleave is enabled the buffer will contain samples organized as follows RI AB AutoDMA options may be a combination of one or more of the following values Identifier ADMA EXTERNAL STARTCAPTURE If this flag is set the acquisition will 0x00000001 start when the application calls AlazarStartCaputre If this flag is not set the acquisition will start before AlazarBeforeAsyncRead returns ADMA ENABLE RECORD HEADERS If this flag is set precede each record 0x00000008 ADMA ALLOC BUFFERS 0x00000020 2003 2010 Alazar Technologies Inc in each buffer with a 16 byte header that includes the record s trigger timestamp Note that this flag can only be used in traditional AutoDMA mode Record headers are not available in NPT streaming or triggered streaming modes If this flag is set the API will allocate and manage a list of DMA buffers This flag may be used by LabVIEW and in other high level development environments where it may be more convenient for the application to let
133. ot a suitable buffer ADMA Buffer2Invalid Buffer2 is not a suitable buffer 2003 2010 Alazar Technologies Inc 71 SDK Programmer s Guide ADMA _InternalBufferl Invalid 4 The routine cannot allocate enough memory because system resources are low ADMA InternalBuffer2Invalid 5 The routine cannot allocate enough memory because system resources are low ADMA OverFlow_____ 6 A hardware overflow occurred ADMA DMAlnProgress 8 A memory transfer is in progress ADMA UseHeaderNotSet___ 9 UseHeader must be set ADMA InvalidRecsPerBuffer 11 RecordCount must be a perfect multiple of RecsPerBuffer rl in RESERVED r2 in RESERVED r3 out RESERVED r4 out RESERVED Return values See Table 1 for a list of error codes Remarks See Also AlazarStartAutoDMA AlazarCloseAUTODma Using synchronous AutoDMA 2003 2010 Alazar Technologies Inc 72 SDK Programmer s Guide 3 3 3 AlazarAbortCapture Abort an acquisition to on board memory Syntax C Car RETURN CODE AlazarAbortCapture HANDLE BoardHandle VisualBasic AlazarAbortCapture ByVal BoardHandle As Integer As Long Parameters BoardHandle in Handle to board Return value The function returns ApiSuccess 512 if it was successful Otherwise the function returns an error code that indicates the reason that it failed See Table 1 for a list of error codes Remarks None See Also AlazarRead
134. parameter value depends on the AUX I O mode 2003 2010 Alazar Technologies Inc 89 SDK Programmer s Guide AUX OUT TRIGGER The value is ignored AUX IN TRIGGER ENABLE The value specifies slope of TTL trigger enable signal e TRIGGER SLOPE POSITIVE 1 The trigger enable signal is the rising edge of a TTL pulse to the AUX I O connector TRIGGER SLOPE NEGATIVE 2 The trigger enable signal is the falling edge of a TTL pulse to the AUX I O connector Note that the divider must be greater than 2 AUX OUT SERIAL DATA The value specifies the TTL output level e 0 TTL low level Return value If the function succeeds it returns ApiSuccess 512 Otherwise the function returns an error code that indicates the reason that it failed See Table 1 for a list of error codes Remarks The AUX I O connector generates TTL level signals when configured as an output and expects TTL level signals when configured as an input AUX I O output signals may be limited by the bandwidth of the AUX output drivers See Also 2003 2010 Alazar Technologies Inc 90 SDK Programmer s Guide 3 3 14 AlazarCreateStreamFile Create a binary data file for this board and enable saving AutoDMA data from this board to disk Syntax C CFF RETURN_CODE AlazarCreateStreamFileA HANDLE BoardHandle char FilePath VW RETURN CODE AlazarCreateStreamFilew HANDLE BoardHandle WCHAR FilePath JA VisualBasic AlazarCrea
135. peration again or abort the acquisition ApiWaitCanceled ApiBufferTooSmall ApiBufferOverflow The board overflowed its on board memory Try reducing the sample rate reducing the number of enabled channels increasing the size of each DMA buffer or increasing the number of DMA buffers 2003 2010 Alazar Technologies Inc 60 SDK Programmer s Guide ApunvalidBuffer ApilnvalidRecordsPerBuffer ApiDmaPending ApiLockAndProbePagesFailed ApiWaitAbandoned ApiWaitFailed ApiTransferComplete ApiPlINotLocked ApiNotSupportedInDualChannelMode 2003 2010 Alazar Technologies Inc l u Comment AAA EA A EA An asynchronous I O operation was successfully started on the board It will be completed when sufficient trigger events are supplied to the board to fill the buffer The driver or operating system was unable to prepare the specified buffer for a DMA transfer Try reducing the buffer size or total number of buffers This buffer is the last in the current acquisition 590 A hardware error has occurred Contact AlazarTech The requested number of samples per channel is too large to fit in on board memory Try reducing the number of samples per channel or switching to single channel mode 61 SDK Programmer s Guide 3 2 Function Groups The AlazarTech API is organized into the following functional groups See AlazarApi h for function declarations 3 2 1 Initialization Name Pur
136. port or buffer dual port Get the number of DMA buffers that have been queued by an application to this board Get the number of DMA buffers for this board that are full and waiting to be processed by the application Get the number of DMA buffers for this board that are empty and waiting to be filled by the board The function returns ApiSuccess 512 if it was able to retrieve the value of the specified parameter Otherwise the function returns an error code that indicates the reason that it failed See Table 1 for a list of error codes Remarks See Also AlazarGetParameterUL AlazarSetParameter AlazarSetParameterUL 2003 2010 Alazar Technologies Inc 118 SDK Programmer s Guide 3 3 33 AlazarGetParameterUL Get a device attribute as an unsigned 32 bit value Syntax CY Car RE TURN_CODE AlazarGetParameterUL HANDLE BoardHandle U8 Channel U32 Parameter UsZ VWallwe DE VisualBasic AlazarGetParameterUL ByVal BoardHandle As Integer ByVal Channel As Byte ByVal Parameter As Long ByRef Value As Long As Long Parameters BoardHandle in Handle to board Channel in The channel of the attribute if required Parameter in The parameter identifier Parameter identifiers include the following values See AlazarApi h for a complete list of list of identifiers GET MAX PRETRIGGER SAMPLES Return the maximum number of pre 0x 10000046 trigger samples suppor
137. pose systems specified by the handle to its master board specified by its system identifier AlazarClose Close a board handle AlazarGetBoardBySystemHandle Get a handle to a board specified by its board identifier and handle to the master board in its board system identifier and board identifier specified by its system identifier AlazarOEMDownLoadFPGA AlazarParseFPGAName 3 2 2 Status and information AlazarErrorToText Convert API error number to NULL terminated string AlazarGetBoardKind Get a board s model from its handle AlazarGetChannelInfo Get the number of bits per sample and on board memory size in samples per channel AlazarGetCPLDVersion Get the CPLD version of a board AlazarGetDriverVersion AlazarGetParameterUL AlazarGetSDK Version 3 2 3 Configuration and control Name Purpose 2003 2010 Alazar Technologies Inc 62 SDK Programmer s Guide AlazarConfigureAuxIO gureAuxlO Configure the AUX I O connector of a board AlazarInputControl Configure the range coupling and termination of an input channel AlazarSetBW Limit Enable or disable the 20 MHz low pass filter of an input channel of board AlazarSetCaptureClock Configure the timebase of a board AlazarSetExternalClockLevel Set the external clock comparator level of a board AlazarSetExternalTrigger Configure the TRIG IN connector of a board AlazarSetLED Control the LED on the PCI PCle mounti
138. r e Call AlazarConfigureAuxIO specifying AUX IN TRIGGER ENABLE as the mode and the active edge of the trigger enable signal as the parameter e Configure the board to make an AutoDMA acquisition in NPT or Traditional mode where the number of records per buffer is equal to the number of scan lines per frame To implement a scanning application using a software start of frame command e Call AlazarConfigureAuxlO specifying AUX_OUT_TRIGGER_ENABLE as the mode e Configure the board to make an AutoDMA acquisition in NPT or Traditional mode where the number of records per buffer is equal to the number of scan lines per frame e Call AlazarForceTriggerEnable to arm the board to acquire one frame wait for the board to receive sufficient trigger events to fill one buffer process the buffer and repeat Note that if the number of records per acquisition is set to infinite then software arms the digitizer once to make an AutoDMA acquisition with an infinite number of frames The hardware will continue acquiring frame data until the acquisition is aborted 2003 2010 Alazar Technologies Inc 44 SDK Programmer s Guide See AATS_SDK_DIR Samples lDualPorANPT_Scan for sample programs that demonstrate how to make a scanning application using a hardware trigger enable signal 2 4 2 9 Master slave applications If a dual port acquisition API is used to acquire from master slave board system e Call AlazarBeforeA
139. r Technologies Inc 57 SDK Programmer s Guide Wait for the board to receive sufficient trigger events to fill an internal buffer The API will save the buffer to a binary data file but will not copy any data into our buffer retCode AlazarWaitNextAsyncBufferComplete handle HANDLE board handle NULL void buffer to receive data 0 U32 bytes to copy into buffer timeout_ms U32 time to wait for buffer Abort the acquisition and release resources This function must be called after an acquisition AlazarAbortAsyncRead boardHandle See ATS SDK DIR Samples DualPort CS_ CreateStreamFile for a full sample program that demonstrates how to stream sample data to disk using AlazarCreateStreamFile 2003 2010 Alazar Technologies Inc SDK Programmer s Guide 3 Reference 3 1 Error Codes The following table lists the error codes that are returned by the API their numerical values and their descriptions These error codes are declared in AlazarError h Table 1 Error Codes ApiAccessDenied SAP ApiDmaChannelUnavailable 515 S ApiDmaChannellnvalid 516 ApiDmaChannelTypeEror ST ApiDmalnProgress SB PO ApiDmaDone SIP ApiDmaPaused 520 PO ApiDmaNotPaused ai ApiDmaCommandInvalid 522 ApiDmaManReady 53 ApiDmaManNotReady 54 ApiDmalnvalidChannelPriority 525 S ApiDmaManCorupted 526 ApiDmalnvalidElementIndex_ 527_ gt S
140. r Tk goes low to high TRIG ENGINE OP J AND K T AND Ty goes low to high TRIG ENGINE OP J XOR K T XOR Ty goes low to high TRIG ENGINE OP J AND NOT K T AND NOT T goes low to high TRIG ENGINE OP NOT J AND K y NOT T AND T goes low to high 2 3 3 2 AlazarSetTriggerOperation examples The following code fragment configures a board to trigger when the signal connected to CH A rises above OV This example only uses trigger engine J AlazarSetTriggerOperation handle HANDLE board handle TRIG ENGINE OP J U32 trigger operation TRIG ENGINE J U32 trigger engine id TRIG CHAN A U32 trigger source id TRIGGER SLOPE POSITIVE U32 trigger slope id 128 U32 trigger level 128 OV TRIG ENGINE K U32 trigger engine id TRIG DISABLE U32 trigger source id for engine K TRIGGER SLOPE POSITIVE U32 trigger slope id 128 U32 trigger level 0 255 E The following code fragment configures a board to trigger when the signal connected to CH B rises above 500 mV or falls below 200 mV if CH B s input range is 1 V This example uses both trigger engine J and K 2003 2010 Alazar Technologies Inc 15 SDK Programmer s Guide double inputRange volts 1 1V range double TriggerL
141. r a list input coupling identifiers InputImpedence Input impedance identifier for this channel See AlazarInputControl for a list input impedance identifiers This bit is set if TRIG IN on this board caused the board system to trigger and capture this record Otherwise this bit is cleared This bit is set if CH B on this board caused the board system to trigger and capture this record Otherwise this bit is cleared This bit is set if CH A on this board caused the board system to trigger and capture this record Otherwise this bit is cleared This bit is set if a trigger timeout expired on a trigger engine on this board caused the board system to trigger and capture this record Otherwise this bit is cleared ThisChannelTriggered This bit is set if the channel specified by the WhichChannel field on this board caused the board ExternalTriggered ChannelBTriggered ChannelA Triggered TimeOutOccurred 1 1 1 1 1 1 system to trigger and capture this record Otherwise this bit is cleared Od Nn 2003 2010 Alazar Technologies Inc SDK Programmer s Guide See AATS_SDK_DIR Samples lDualPorATR_Header for a full sample program that demonstrates how to make an AutoDMA acquisition in Traditional mode with record headers 2 4 2 5 2 Record timestamps AlazarTech digitizer boards include a high speed 40 bit counter that is clocked by the sample clock source scaled by a board specific divider When a board
142. rApi h for a complete list of list of parameter identifiers Identifier SETGET ASYNC_ BUFFCOUNT 0x10000040 Select number of API allocated DMA buffers SET DATA FORMAT 0x 10000041 Select sample data format 0 unsigned signed Value in Parameter value 2003 2010 Alazar Technologies Inc 163 SDK Programmer s Guide Return value The function returns ApiSuccess 512 if it was able to retrieve the value of the specified parameter Otherwise the function returns an error code that indicates the reason that it failed See Table 1 for a list of error codes Remarks See Also AlazarGetParameter AlazarGetParameterUL AlazarSetParameterUL 2003 2010 Alazar Technologies Inc 164 SDK Programmer s Guide 3 3 58 AlazarSetParameterUL Set a device parameter as an unsigned 32 bit value Syntax CY Car RE TURN_CODE AlazarSetParameterUL HANDLE BoardHandle U8 ChannellId U32 Parameterld U32 Value DE VisualBasic AlazarSetParameterUL ByVal BoardHandle As Integer ByVal Channelld As Byte ByVal Parameterld As Long ByVal Value As Long As Long Parameters BoardHandle in Handle to board Channelld in The channel to control This channel identifier may be one of the following values CHANNEL A Apply parameter to CH A CHANNEL B Apply parameter to CH B oo JO The parameter does not apply to a channel Parameterld in Parameter to modify Value
143. rameters BoardName in Name of board created by driver For example ATS850 0 Return value A handle to the board Remarks The ATS library manages board handles internally This function should only be used in applications that are written for single board digitizer systems See Also AlazarClose 2003 2010 Alazar Technologies Inc 138 SDK Programmer s Guide 3 3 46 AlazarParseFPGAName Decode an OEM FPGA image file name Syntax CY Car RETURN CODE AlazarParseFPGAName conce ehari ial Lewes char FileName U32 BoardType U32 MemorySizeld U32 HardwareMajorVersion U32 HardwareMinorVersion U32 FpgaMajorVersion U32 FpgaMinorVersion USO VisualBasic AlazarParseFPGAName ByRef FilePath As Any ByRef FileName As Any ByRef BoardType As Long ByRef MemorySizeld As Long ByRef HardwareMajorVersion As Long ByRef HardwareMinorVersion As Long ByRef FpgaMajorVersion As Long ByRef FpgaMinorRevision As Long ByRef Error As Long As Long Parameters FilePath in Full path to FPGA image file FileName out FPGA image file name MemorySizeld out The memory size identifier of the memory in samples per channel required on the digitizer board HardwareMajorVersion out Pointer to digitizer board major version number HardwareMinorVersion out Pointer to digitizer board minor version number FpgaMajorVersion out Pointer to FPGA major version number
144. rd containing a signed 16 bit sample code to in volts double SampleToVoltsS16 U16 sampleValue double inputRange volts AlazarTech digitizers are calibrated as follows int bitsPerSample 16 double codeZero 1 lt lt bitsPerSample 1 0 5 double codeRange 1 lt lt bitsPerSample 1 0 5 Convert signed sample value to unsigned code Ul6 sampleCode sampleValue 0x8000 Convert sample code to volts double sampleVolts inputRange volts double sampleCod codeZero codeRange return sampleVolts 2 5 2 Saving binary files If an application saves sample data to a binary data file for later processing it may be possible to improve disk write speeds by considering the following recommendations 2003 2010 Alazar Technologies Inc 56 SDK Programmer s Guide 2 5 2 1 C C applications If the application is written in C C and is running under Windows use the Windows CreateFile API with the FILE FLAG NO BUFFERING flag for file I O if possible Sequential disk write speeds are often substantially higher when this option is selected See ATS SDK DIR Samples DualPort TS DisableFileCache for a sample program that demonstrates how to use this API to stream data to disk 2 5 2 2 Visual Basic LabVIEW applications If the application is written in VisualBasic LabVIEW or another high level programming environment the consider using the AlazarCr
145. rd identifier number of 1 e If two or more boards are connected together using a SyncBoard then the API assigns each board a board identifier number that depends on how the board is connected to the SycnBoard The board connected to the master slot on the SyncBoard is the master board in the board system and is assigned a board identifier of 1 Call the AlazarNumOfSystems API function to determine the number of board systems detected by the API and call the AlazarBoardsInSystemBySystemID API function to determine the number of boards in a board system specified by its system identifier The following code fragment lists the system and board identifiers of each board detected by the device drivers U32 systemCount AlazarNumOfSystems for U32 systemId 1 systemId lt systemCount systemld U32 boardCount AlazarBoardsInSystemBySystemID systemId for U32 boardId 1 boardId lt boardCount boardId printf Found SystemID Su Board ID Sun systemid boardld 2 1 2 Getting a board handle The AlazarTech API associates a handle with each digitizer board 2003 2010 Alazar Technologies Inc 4 SDK Programmer s Guide Most API functions require a board handle as a parameter For example the AlazarSetLED API function allows an application to control the LED on the PCI PCIe mounting bracket of a board specified by its handle Figure 2 1 PCI PCIe mounting bracket LED ie
146. rd system Return value This function returns a handle to the specified board if it was found The function returns NULL if the master board handle is invalid or a board with the specified board identifier was not found in the specified board system Remarks The board identifier of a master board in a board system is always 1 See Also AlazarGetBoardBySystemID AlazarGetSystemHandle 2003 2010 Alazar Technologies Inc 106 SDK Programmer s Guide 3 3 24 AlazarGetBoardBySystemID Get a handle to a board in a board system where the board system is specified its system identifier and the board by its board identifier within the board system Syntax CY Cat HANDLE AlazarGetBoardBySystemID U32 Systemld U32 BoardId VisualBasic Public Declare Function AlazarGetBoardBySystemID ByVal SystemId As Integer ByVal BoardId As Integer As Integer Parameters Systemld in System identifier number Boardld in Board identifier in system Return value This function returns a handle to the specified board if it was found It returns NULL if the board system with the specified ID was not found or a board with the specified ID was not found within the specified board system Remarks See Also AlazarGetBoardBySystemHandle AlazarGetSystemHandle 2003 2010 Alazar Technologies Inc 107 SDK Programmer s Guide 3 3 25 AlazarGetBoardKind Get a board model identifier of the board associa
147. re 2 2 External clock connector on PCI PCIe mounting bracket To use an external clock signal as a timebase call AlazarSetCaptureClock specifying SAMPLE RATE USER DEF as the sample rate identifier and select a clock source identifier appropriate for the board model and the external clock properties The following code fragment shows how to configure an ATS460 to acquire at 100 MS s with a 100 MHz external clock AlazarSetCaptureClock handle HANDLE board handle FAST EXTERNAL CLOCK U32 clock source Id 2003 2010 Alazar Technologies Inc 8 SDK Programmer s Guide SAMPLE RATE USER DEF U32 sample rate Id or value CLOCK EDGE RISING U32 clock edge Id 0 U32 decimation 3 See the board reference manual for the properties of an external clock signal that are appropriate for a board and AlazarSetCaptureClock for a list of external clock source identifiers 2 3 1 3 External clock level Some boards allow adjusting the comparator level of the external clock input receiver to match the receiver to the clock signal supplied to the ECLK connector If necessary call AlazarSetExternalClockLevel to set the relative external clock input receiver comparator level in percent AlazarSetExternalClockLevel handle HANDLE board handle level pecent float exernal clock level in percent 7 Note that ATS9350 has an aut
148. receives a trigger event to capture a record to on board memory it latches the value of this counter This timestamp value gives the time relative to when the counter was reset when the trigger event for this record occurred By default this counter is reset to zero at the start of each acquisition Use AlazarResetTimeStamp to control when the record timestamp counter is reset The following code fragment demonstrates how to extract the timestamp from a record header and covert the value from counts to seconds double samplesPerTimestampCount 2 board specific constant double samplesPerSec 100 e6 sample rate void pRecord points to record header in buffer ALAZAR HEADER pHeader ALAZAR HEADER pRecord _ int64 timestamp counts timestamp counts INT64 pHeader gt hdr2 TimeStampLowPart timestamp counts timestamp counts __int64 pHeader gt hdr3 TimeStampHighPart amp Ox0ff lt lt 32 double timestamp sec samplesPerTimestampCount timestamp counts samplesPerSec Call AlazarGetParameter with the GET SAMPLES PER TIMESTAMP CLOCK parameter to determine the board specific samples per timestamp count value The following table lists these values Samples per timestamp count ATS310 ATS330 ATS460 ATS660 ATS9462 ATS9870 ATS9350 ATS850 ATS860 See ATS_ SDK_DIR Samples DualPort TR_Header for a full sample program that demons
149. returns the total number of boards in the system including the master If this function is called with the handle an independent board it returns 1 If this function is called with the handle to a slave board in a master slave system or with an invalid handle it returns 0 See Also AlazarBoardsInSystemBySystemID AlazarGetSystemHandle 2003 2010 Alazar Technologies Inc 84 SDK Programmer s Guide 3 3 9 AlazarBoardsinSystemBySystemID Return the number of digitizer boards in a board system specified its system ID Syntax CY Cat U32 AlazarBoardsInSystemBySystemID U32 Systemid VisualBasic AlazarBoardsInSystemBySystemID ByVal SystemId As Integer As Integer Parameters Systemld in Board system identifier Return value The number of boards in the specified system Remarks If this function is called with the identifier of a master slave system it returns the total number of boards in the system including the master If this function is called with identifier of an independent board system it returns 1 If this function is called with the identifier of an invalid board system it returns 0 See Also AlazarBoardsInSystemByHandle AlazarGetSystemHandle 2003 2010 Alazar Technologies Inc 85 SDK Programmer s Guide 3 3 10 AlazarBusy Determine if an acquisition to on board memory is in progress Syntax C C U32 AlazarBusy HANDLE BoardHandle 2 VisualBasic A
150. rnal clock Use decimation to generate sample clock from reference clock ATS9350 sample rate identifiers SAMPLE RATE 20KSPS SAMPLE RATE 200KSPS SAMPLE RATE 2MSPS 100 MS s internal clock 125 MS s internal clock 250 MS s internal clock SAMPLE RATE 500MSPS 0x00000030 500 MS s internal clock SAMPLE RATE USER DEF 0x00000040 External clock 500 MHz reference clock 500000000 500 MHz reference clock from 10 MHz PLL external clock Use 2003 2010 Alazar Technologies Inc 156 MPLE RATE 10MSPS 0x0000001C 10 MS s internal clock A A A A SA SA SA SA SA SA SA A A A A SDK Programmer s Guide decimation to generate sample clock from reference clock Identifier Description SAMPLE RATE 1KSPS 1 KS s internal clock SAMPLE RATE 2KSPS 2 KS s internal clock SAMPLE RATE 5KSPS 5KS s internal clock SAMPLE RATE 10KSPS 10 KS s internal clock SAMPLE RATE 20KSPS 20 KS s internal clock SAMPLE RATE 50KSPS 50 KS s internal clock SAMPLE RATE 100KSPS 100 KS s internal clock SAMPLE RATE 200KSPS 200 KS s internal clock SAMPLE RATE 500KSPS 500 KS s internal clock SAMPLE RATE 1MSPS 1 MS s internal clock SAMPLE RATE 2MSPS 2 MS s internal clock SAMPLE RATE 5MSPS 5 MS s internal clock SAMPLE RATE 10MSPS 10 MS s internal clock SAMPLE RATE 20MSPS 20 MS s internal clock SAMPLE RATE 25MSPS 25 MS s internal clock SAMPLE _RATE_50MSPS 100 MS s internal clock 125 MS s internal clock SAMPLE RATE 160MSPS 160 MS s inter
151. rror code that indicates the reason that it failed See Table 1 for a list of error codes Remarks Y ou must call AlazarBeforeAsyncRead before calling AlazarPostAsyncBuffer You must call AlazarAbortAsyncRead before your application exits if you have called AlazarPostAsyncBuffer and buffers are pending when your application exits The BufferLength parameter must be equal to the product of the number of bytes per record the number of records per buffer and the number of enabled channels If record 2003 2010 Alazar Technologies Inc 141 SDK Programmer s Guide headers are enabled the number of bytes per record must include the size of the record header 16 bytes See Also AlazarAbortAsyncRead AlazarBeforeAsyncRead Using asynchronous AutoDMA O 2003 2010 Alazar Technologies Inc SDK Programmer s Guide 3 3 48 AlazarQueryCapability Get a device attribute Syntax CY Car RE TURN_CODE AlazarQueryCapability HANDLE BoardHandle U32 Cejocig ILE U32 Reserved U32 Value VG VisualBasic AlazarQueryCapability ByVal BoardHandle As Integer ByVal Capability As Long ByVal Reserved As Long ByRef Value As Long As Long Parameters BoardHandle in Handle to board Capability in Capability identifier See remarks below Reserved in Reserved Set to 0 Value out Capability value Return value The function returns ApiSuccess 512 if it was able to retrieve value of the speci
152. ry Allocate a buffer to hold one record segment Note that the buffer must be at least 16 samples larger than the number of samples per buffer U32 allocBytes bytesPerSample samplesPerBuffer 16 void buffer malloc allocBytes Transfer a record in segments from on board memory a U32 samplesToRead samplesPerRecord long triggerOffset samples long preTriggerSamples while samplesToRead gt 0 Transfer a record segment from on board memory U32 samplesThisRead if samplesToRead gt samplesPerBuffer samplesThisRead samplesPerBuffer else ToRead samplesThisRead samples AlazarRead boardHandle HANDLE board handle CHANNEL A U32 channel Id buffer void buffer bytesPerSample int bytes per sample long record long record 1 indexed triggerOffset_samples long trigger offset samplesThisRead U32 samples to transfer 3 2003 2010 Alazar Technologies Inc 25 SDK Programmer s Guide Process the record segment here WriteSamplesToFile buffer samplesThisRead Point to next record segment in on board memory triggerOffset samples samplesThisRead Decrement number of samples left to read samplesToRead samplesThisRead See ATS SDK DIR Samples SinglePort AR Segments for a complete sample program that demonstrates how to read recor
153. s BoardHandle in Handle to board Buffer out Pointer to a buffer to receive sample data from the digitizer board Timeout_ms in Specify the time to wait in milliseconds for the buffer to be filled Return values If the board receives sufficient trigger events to fill this buffer before the timeout interval elapses the function returns ApiSuccess 512 If the timeout interval elapses before the board receives sufficient trigger events to fill the buffer the function returns ApiWaitTimeout 579 If the board overflows its on board memory the function returns ApiBufferOverflow 582 The board may overflow its on board memory because the rate at which it is acquiring data is faster than the rate at which the data is being transferred from on board memory to host memory across the host bus interface PCI or PCIe If this is the case try reducing the sample rate number of enabled channels or amount of time spent processing each buffer If this buffer was not found in the listof buffers available to be filled by the board the function returns ApiBufferNotReady 573 2003 2010 Alazar Technologies Inc 184 SDK Programmer s Guide If this buffer 1s not the buffer at the head of the list of buffers to be filled by the board this returns ApiDmalnProgress 518 If the function fails for some other reason it returns an error code that indicates the reason that it failed See Table 1 for a list of error codes
154. s U32 AutoDMA uisition d handle channel mask igger offset per record per buffer per acquisition mode and options Add two or more buffers to a list of buffers available to be filled by the board for i 0 i lt BUFFER COUNT 1 AlazarPostAsyncBuffer handle HANDLE board handle BufferArray il void buffer pointer BytesPerBuffer U32 buffer length in bytes Arm the board to begin the acquisition AlazarStartCapture handle Wait for each buffer in the acquisition to be filled U32 buffersCompleted 0 while buffersCompleted lt buffersPerAcquisition Wait for the board to receives sufficient trigger events to fill the buffer at the head of its list of available buffers U32 bufferIndex buffersCompleted BUFFER COUNT Ul6 pBuffer BufferArray bufferlndex AlazarWaitAsyncBufferComplete handle pBu buffersCompleted 2003 2010 Alazar Technologies Inc ffer timeout_ms 37 SDK Programmer s Guide The buffer is full process it Note that while the application processes this buffer the board is filling the next available buffer as trigger events arrive ProcessBuffer pBuffer bytesPerBuffer Add the buffer to the end of the list of buffers available to be filled by this board The board will fill it with another segment of the acquisitio
155. s Guide Note that while the application processes this buffer the board is filling the next available buffer as trigger events arrive ProcessBuffer ploBuffer gt buffer ploBuffer gt bytesPerBuffer Add the buffer to the end of the list of buffers The board will fill it with another segment from the acquisition after the buffers preceding it have been filled AlazarAsyncRead handle HANDLE board handle ploBuffer gt buffer void buffer ploBuffer gt bytesPerBuffer U32 buffer length amp ploBuffer gt overlapped OVERLAPPED Stop the acquisition This function must be called if unfilled buffers are pending AlazarAbortAsyncRead handle See ATS_ SDK_DIR Samples DualPort CS_AsyncRead for a full sample program that demonstrates make an AutoDMA acquisition using AlazarAsyncRead 2 4 2 6 4 AlazarAbortAsyncRead The asynchronous API driver locks application buffers into memory so that boards may DMA directly into them When a buffer is completed the driver unlocks it from memory An application must call AlazarAbortAsyncRead if at the end of an acquisition any of the buffers that it supplies to a board have not been completed AlazarAbortAsyncRead completes any pending buffers and unlocks them from memory If an application exits without calling AlazarAbortAsyncRead the API driver may generate a DRIVER LEFT
156. s case trigger events have stopped and this API permits the last buffer to be returned to the application Syntax CC long AlazarFlushAutoDMA HANDLE h VisualBasic AlazarEvents ByVal h As Integer As Long Parameters h in Handle to the device Return value The number of valid triggers in the last buffer Remarks Suppose an acquisition is running and all of the sudden triggers stop coming in Once the software has determined that the acquisition is to be aborted AlazarFlushAutoDMA should be called The routine will automatically generate the missing triggers in order to complete the last buffer A last call to AlazarGetNextAutoDMABuffer is needed to read the LAST buffer You will get ApiFailed as a return value from AlazarGetNextAutoDMABuffer indicating a successful last buffer At this point depending on your design you may terminate the program or start a new acquisition NOTE Internally this routine calls AlazarStopAutoDMA so as not to allow the software to re arm any new DMA requests Only a call to AlazarStartAutoDMA will reset this action See Also AlazarGetNextAutoDMA Buffer AlazarStartAutoDMA Using synchronous AutoDMA 2003 2010 Alazar Technologies Inc 96 SDK Programmer s Guide 3 3 18 AlazarForceTrigger Generate a software trigger event Syntax CACA RETURN_CODE AlazarForceTrigger HANDLE BoardHandle VisualBasic AlazarForceTrigger ByVal BoardHandle As Integer
157. s parameter may be one of the following identifiers or values CHANNEL B DataBuffer in The data buffer as returned from AlazarGetNextAutoDMABuffer Record in Signifies the record number of interest for the provided Data Buffer Parameter in Signifies which element the routine should extract from the record s header This parameter may be one of the following identifiers or values 2003 2010 Alazar Technologies Inc 101 SDK Programmer s Guide Value AD D D D D D D D MA MA TIMEOUT MA THISCHANTRIGGERED 11 MA SERIALNUMBER MA N N N ADMA BOARDNUMBER 14 ADMA WHICHCHANNEL _ 15 ADMA SAMPLERESOLUTION 16 Error A A ADMA_SYSTEMNUMBER _ 13 A A out Error return code This error code may be one of the following values ADMA Completed O Noerrorsoccurred ADMA Success 0 Noerrorsoccurred_ 2 3 Board handle is not valid z memory because system resources are low MA InternalBufferlInvalid 4 The routine cannot allocate enough 7 ADMA DMAInProgress 8 A memory transfer is in progress A MA _HeaderNotValid An invalid header was encountered 1 ADMA InvalidRecsPerBuffer 1 RecordCount must be a perfect multiple of RecsPerBuffer Return value D D D D D D D D D D D D ADMA InternalBuffer2Invalid 5 The routine cannot allocate enough memory because system resources are low 2003 2010 Alazar Technologies Inc 102
158. se try reducing the sample rate number of enabled channels or amount of time spent processing each buffer If the function fails because the buffer is too large for the driver or operating system to prepare for scatter gather DMA transfer it returns ApiLockAndProbePagesFailed 586 2003 2010 Alazar Technologies Inc 74 SDK Programmer s Guide Try reducing the size of each buffer or reducing the number of buffers queued by the application If the function fails for some other reason it returns an error code that indicates the reason that it failed See Table 1 for a list of error codes Remarks AlazarAsyncRead is only available under Windows You must call AlazarBeforeAsyncRead before calling AlazarAsyncRead You must call AlazarAbortAsyncRead before your application exits if you have called AlazarAsyncRead and buffers are pending when you wish to exit your application The BytesToRead parameter must be equal to the product of the number of bytes per record the number of records per buffer and the number of enabled channels If record headers are enabled the number of bytes per record must include the size of the record header 16 bytes See Also AlazarAbortAsyncRead AlazarBeforeAsyncRead Using asynchronous AutoDMA 2003 2010 Alazar Technologies Inc 75 SDK Programmer s Guide 3 3 5 AlazarBeforeAsyncRead Configure a board to make an asynchronous AutoDMA acquisition Syntax CCA RETURN_CODE
159. syncRead on all slave boards before the master board e Call AlazarStartCapture only on the master board e Call AlazarAbortAsyncRead on the master board before the slave boards e The board system acquires the boards in the board system in parallel As a result an application must consume a buffer from each board in the board system during each cycle of the acquisition loop e Do not use synchronous API functions with master slave systems use the asynchronous API functions instead The following sample programs demonstrate how to acquire from a master slave system ATS_SDK_ DIR Samples DualPort TR_MS ATS_SDK_ DIR Samples DualPort NPT_MS ATS SDK DIR Samples DualPort CS_MS and ATS SDK DIR Samples DualPort TS MS 2 4 3 Buffer size and alignment AlazarTech digitizer boards must be configured to acquire at least a minimum number of samples per record and each record must be a multiple of a specified number of samples Records may shift within a buffer if aligment requirements are not met The following table lists the requirements for each board model Board Minimum record size Buffer Buffer alignment in NPT mode type samples alignment samples samples ATS310 ATS330 ATS460 The number of pre trigger samples in single port and dual port traditional AutoDMA mode must be a multiple of 64 samples See AlazarSetRecordCount and AlazarSetRecordSize for more information The address
160. teStreamFileA ByVal BoardHandle As Integer ByRef FileName As Any As Integer AlazarCreateStreamFilew ByVal BoardHandle As Integer ByRef FileName As Any As Integer Parameters BoardHandle in Handle to board FilePath in Pointer to a NULL terminated string that specifies the name of the file Return values If this function succeeds it returns ApiSuccess 512 If this function fails it returns ApiFailed 513 Call the Windows GetLastError API for more information Remarks AlazarCreateStreamFileA accepts 8 bit ACSII or MBCS paths and AlazarCreateStreamFileW accepts 16 bit UNICODE paths C C applications may use AlazarCreateStreamFile It is defined in AlazarApi h as follows 2003 2010 Alazar Technologies Inc 91 SDK Programmer s Guide ifdef UNICODE define AlazarCreateStreamFil AlazarCreateStreamFileW ls define AlazarCreateStreamFil AlazarCreateStreamFileA If possible select AlazarBeforeAsyncRead parameters that result in DMA buffers whose length in bytes is evenly divisible into sectors on the volume specified by FilePath If the DMA buffer length is evenly divisible into sectors AlazarCreateStreamFile disables file caching to obtain the highest possible sequential write performance An AutoDMA buffers is saved to disk when an application calls AlazarWaitNextAsyncBufferComplete For best performance set the BytesToCopy par
161. ted by this board Value out The parameter s value Return value The function returns ApiSuccess 512 if it was able to retrieve value of the specified parameter Otherwise the function returns an error code that indicates the reason that it failed See Table 1 for a list of error codes 2003 2010 Alazar Technologies Inc 119 SDK Programmer s Guide Remarks See AlazarApi h for a complete list of list of parameter identifiers See Also AlazarGetParameter AlazarSetParameter AlazarSetParameterUL 2003 2010 Alazar Technologies Inc 120 SDK Programmer s Guide 3 3 34 AlazarGetSDKVersion Get the SDK version Syntax CU Ct RE TURN_CODE AlazarGetSDKVersion U8 MajorNumber U8 MinorNumber U8 RevisionNumber De VisualBasic AlazarGetSDKVersion ByRef MajorNumber As Byte ByRef MinorNumber As Byte ByRef RevisionNumber As Byte As Long Parameters MajorNumber out The SDK major version number MinorNumber out The SDK minor version number RevisionNumber out The SDK revision number Return value The function returns ApiSuccess 512 if it was successful Otherwise the function returns an error code that indicates the reason that it failed See Table 1 for a list of error codes Remarks SDK releases are given a version number with the format X Y Z where X is the major release number Y is the minor release number and Z is the minor revision number See Also Alaz
162. ted with a board handle Syntax C C U32 AlazarGetBoardKind HANDLE BoardHandle 2 VisualBasic Public Declare Function AlazarGetBoardKind ByVal BoardHandle As Integer As Integer Parameters BoardHandle in Handle to board Return value If the function succeeds it returns a non zero board model identifier If the function fails it returns 0 Remarks The following lists currently supported board model identifiers and their values See AlazarApi h for a complete list of board type identifiers ATS860 8 ATS660 9 See Also 2003 2010 Alazar Technologies Inc 108 SDK Programmer s Guide 3 3 26 AlazarGetChannellnfo Get the on board memory in samples per channel and sample size in bits per sample Syntax CY Car RE TURN_CODE AlazarGetChannelInfo HANDLE BoardHandle U32 MemorySizeInSamples U8 BitsPerSample Y VisualBasic AlazarGetChannelInfo ByVal BoardHandle As Integer ByRef MemorySizeInSamples As Long ByRef BitsPerSample As Byte JAS hong Parameters BoardHandle in Handle to board MemorySizelnSamples out The on board memory size in samples per channel bitsPerSample out The number of bits per sample Return value The function returns ApiSuccess 512 if it was successful Otherwise the function returns an error code that indicates the reason that it failed See Table 1 for a list of error codes Remarks The ATS9870 and ATS9350 can de
163. temHandle Get the event that caused a board system specified by the handle to its master board to trigger AlazarGetWhoTriggeredBySystemID specified by its system identifier to trigger AlazarHyperDisp Enable the on board FPGA to divide a record acquired to on board memory into intervals and return the minimum and maximum sample values over each interval AlazarRead Transfer all or part of a record acquired to on board memory AlazarReadEx Transfer all or part of a record acquired to on board memory when the record has 2 147 483 648 or more samples AlazarSetRecordCount Specify the number of records to capture to on board memory 3 2 4 3 Dual port Asynchronous AutoDMA Purpose AlazarAbortAsyncRead Abort an asynchronous AutoDMA acquisition and release any resources allocated during the acquisition AlazarAsyncRead Add a buffer to the end of a list of buffers available to be filled by a board AlazarBeforeAsyncRead Configure a board to make an asynchronous AutoDMA acquisition c r AlazarCreateStreamFile Create a binary data file to store sample data for a board available to be filled by a board AlazarWaitAsyncBufferComplete Wait a specified amount of time for a board to receive sufficient trigger events to fill the specified AutoDMA buffer AlazarWaitNextAsyncBufferComplete Wait a specified amount of time for a board to receive sufficient trigger events to fill an AutoDMA buffer managed by the API 3 2 4 4
164. the buffer to be filled Return values If the board receives sufficient trigger events to fill the next available buffer before the timeout interval elapses and the buffer is not the last buffer in the acquisition the function returns ApiSuccess 512 If the board receives sufficient trigger events to fill the next available buffer before the timeout interval elapses and the buffer is the last buffer in the acquisition the function returns ApiTransferComplete 589 If the timeout interval elapses before the board receives sufficient trigger events to fill the next available buffer the function returns ApiWaitTimeout 579 2003 2010 Alazar Technologies Inc 188 SDK Programmer s Guide If the board overflows its on board memory the function returns ApiBufferOverflow 582 The board may overflow its on board memory because the rate at which it is acquiring data is faster than the rate at which the data is being transferred from on board memory to host memory across the host bus interface PCI or PCIe If this is the case try reducing the sample rate number of enabled channels or amount of time spent processing each buffer If the function fails for some other reason it returns an error code that indicates the reason that it failed See Table 1 for a list of error codes Remarks Y ou must call AlazarBeforeAsyncRead with the ADMA GET PROCESSED DATA flag before calling AlazarWaitNextAsyncBufferComplete To discard buff
165. trates how to make an AutoDMA acquisition in Traditional mode with record headers and convert the timestamp to seconds 2 4 2 6 Using asynchronous AutoDMA The asynchronous AutoDMA functions allow an application to add user defined number of buffers to a list of buffers available to be filled by a board and to wait for the board to 2003 2010 Alazar Technologies Inc 36 SDK Programmer s Guide receive sufficient trigger events to fill the buffers with sample data The board uses AutoDMA to transfer data directly into a buffer without making any intermediate copies in memory As soon as one buffer is filled the driver automatically starts an AutoDMA transfer into the next available buffer 2 4 2 6 1 AlazarPostBuffer C C and VisualBasic applications should call AlazarPostAsyncBuffer to make buffers available to be filled by the board and AlazarWaitAsyncBufferComplete to wait for the board to receive sufficient trigger events to fill the buffers The following code fragment outlines the steps required to make an AutoDMA acquisition using AlazarPostAsyncBuffer and AlazarWaitAsyncBufferComplete Configure the board to make an AutoDMA acq AlazarBeforeAsyncRead handle ES channelMask long preTriggerSamples samplesPerRecord recordsPerBuffer recordsPerAcquisition flags HANDLE boar U32 enabled long tr U32 samples U32 records U32 record
166. ts higher trigger repeats rate than possible in Traditional mode 2003 2010 Alazar Technologies Inc 31 SDK Programmer s Guide Each buffer is organized as follows if a board has on board memory Enabled channels RIA R2A R3A RIB R2B R3B RnB Both CH A and CH B RIA R2A R3A RnA RIB R2B R3B RnB Each buffer is organized as follows if a board does not have on board memory or if sample interleave is enabled Enabled channels RIA R2A R3A RnA CHB_ RIB R2B R3B RnB Both CH A and CH B RI ABAB R2 ABAB Rn ABAB Note that Rxy is a record with a contiguous array of samples from a channel and Rx AB is a record with interleaved samples from both CH A and CH B See ATS_ SDK_DIR Samples DualPort NPT for a sample program that demonstrates how to make an AutoDMA acquisition in NPT mode 2 4 2 3 Continuous streaming AutoDMA Use continuous streaming mode to acquire a single gapless record that spans multiple buffers without waiting for a trigger event to start the acquisition The programmer specifies the number of samples per buffer and buffers per acquisition Each buffer is organized as follows if a board has on board memory Enabled channels Both CH A and CH B RIA RIB Each buffer is organized as follows if a board does not have on board memory or if sample interleave is enabled Enabled channels Both CH A and CH B RI ABAB Note that Rx
167. ured to wait for a specified amount of time after it receives a trigger event before capturing a record for the trigger Call AlazarSetTriggerDelay to specify a time in sample clock periods to wait after receiving a trigger event for a record before capturing samples for that record The following code fragment shows how to set a trigger delay of 1 ms given a sample rate of 100 MS s double triggerDelay sec l e 3 1 ms double samplesPerSec 100 e6 100 MS s U32 triggerDelay samples U32 triggerDelay sec samplesPerSec 0 5 AlazarSetTriggerDelay boardHandle HANDLE board handle triggerDelay samples U32 trigger delay in samples 2 3 4 AUX I O AlazarTech digitizer boards with an AUX I O BNC connector can be configured to supply a 5V TTL level output signal or to receive a TTL level input signal on this connector 2003 2010 Alazar Technologies Inc 18 SDK Programmer s Guide Figure 2 5 Auxiliary I O connector on PCI PCIe mounting bracket Use AlazarConfigureAuxIO to configure the function of the AUX I O connector 2 3 4 1 Trigger output The AUX I O connector can be configured to supply a trigger output signal where the edge of the trigger output signal is synchronized with the edge of the sample clock Note that this is the default power on mode for the AUX I O connector The following code fragment configures the AUX I O connector as a trigger o
168. utput signal AlazarConfigureAuxlo handle HANDLE board handle AUX OUT TRIGGER U32 mode 0 U32 parameter 2 3 4 2 Pacer output The AUX I O connector can be configured to output the sample clock divided by a programmable value This option may be used to generate a clock signal synchronized with the sample clock of the digitizer board The following code fragment generates a 10 MHz signal on an AUX I O connector assuming a sample rate of 180 MS s 2003 2010 Alazar Technologies Inc 19 SDK Programmer s Guide AlazarConfigureAuxlo handle HANDLE board handle AUX_OUT_PACER U32 mode 18 U32 sample clock divider Note that the sample rate divider value must be greater than 2 and that signal output may be limited by the bandwidth of the output s TTL drivers 2 3 4 3 Digital output The AUX I O connector can be configured to output a TTL high or low signal This mode allows a programmer to use the AUX I O connector as a general purpose digital output The following code fragment configures the AUX I O connector as a digital output AlazarConfigureAuxlo handle HANDLE board handle AUX_OUT SERIAL DATA U32 mode 0 U32 0 low 1 high 2 3 4 4 Trigger enable output The AUX I O connector can be configured as an AutoDMA trigger enable output signal When enabled a board will e Wait for softare to call AlazarForceTriggerEnab
169. ven by TriggerLevelCode 128 127 TriggerLevelVolts InputRangeVolts Note that AlazarSetExternalTrigger is used to select the trigger input range if the trigger source is an external trigger signal connected to the TRIG IN BNC connector See Also Trigger control AlazarSetTriggerDelay AlazarSetExternalTrigger AlazarSetTriggerTimeQut 2003 2010 Alazar Technologies Inc 174 SDK Programmer s Guide 3 3 63 AlazarSetTriggerTimeOut Set the time to wait for a trigger event before automatically generating a trigger event Syntax C C RE TURN_CODE AlazarSetTriggerTimeOut HANDLE BoardHandle U32 TimeoutTicks De VisualBasic AlazarSetTriggerTimeOut ByVal BoardHandle As Integer ByVal TimeoutTicks As Long As Long Parameters BoardHandle in Handle to board TimeoutTicks in Trigger timeout in 10 us units or 0 to wait forever for a trigger event Return value The function returns ApiSuccess 512 if it was able to retrieve the value of the specified parameter Otherwise the function returns an error code that indicates the reason that it failed See Table 1 for a list of error codes Remarks To convert the trigger timeout from seconds to trigger timeout ticks multiply the timeout value in seconds by 1e5 For example a trigger timeout of 1 ms is equal to le 3 1e5 100 ticks See Also Trigger control AlazarSetExternalTrigger AlazarSetTriggerDelay AlazarSetTriggerOperat
170. y is a record with a contiguous array of samples from a channel and Rx AB is a record with interleaved samples from both CH A and CH B ee N 2003 2010 Alazar Technologies Inc SDK Programmer s Guide See ATS_SDK_DIR Samples DualPort CS for a sample program that demonstrates how to make an AutoDMA acquisition in continuous streaming mode 2 4 2 4 Triggered streaming AutoDMA Use triggered streaming mode to acquire a single gapless record that spans two or more buffers after waiting for a trigger event to start the acquisition The programmer specifies the number of samples in each buffer and buffers in the acquisition Each buffer is organized as follows if a board has on board memory Enabled channels Buffer organization RIA Both CH A and CH B RIA RIB Each buffer is organized as follows if a board does not have on board memory or if sample interleave is enabled Enabled channels Buffer organization RIA Both CH A and CH B RI ABAB Note that Rxy is a record with a contiguous array of samples from a channel and Rx AB is a record with interleaved samples from both CH A and CH B See ATS_SDK_DIR Samples DualPort TS for a sample program that demonstrates how to make a triggered streaming AutoDMA acquisition 2 4 2 5 Record headers and timestamps In traditional AutoDMA mode a 16 byte record header may optionally precede each record in a buffer When record headers are enabled th
171. y the software on any medium except as specifically allowed in the license agreement No part of this manual may be reproduced or transmitted in any form or by any means electronic or mechanical including photocopying and recording for any purpose without the written permission of Alazar Technologies Inc Some jurisdictions do not allow the exclusion of implied warranties or liability for incidental or consequential damages so the above limitation or exclusion may not apply to you This warranty gives you specific legal rights and you may also have other rights which vary from jurisdiction to jurisdiction 2003 2010 Alazar Technologies Inc 111 SDK Programmer s Guide Contents i AAA A fn naa nk 1 MAA AAA 1 2 Programing ns AAA ataia eiaeaen Eai 1 PLA EI A EA 1 AI ha ane tb hd na a tha eed A AE A N EL NE 2 Pe MAA AAA A fi E A A A rore ear ey 2 EE A II ay em Meee ROOT omer eae 2 Rie AA AA IA EATA ER 3 A A A E 4 21 Addressing O ii li 4 AA a board A e A a di 4 A O a board handle A A ada tans tera 4 21 AA A A ergeey ea 6 APA a AMA 6 O A Lal aang cele ne ddillaas 7 23 MN PM MAA E Z al TO ii A A AAA A eoaa lad bit 7 WM ten kaa Tene mene mene nt ne ne ee crores remem Tm 11 A O E E A A a eee 13 A CUD gE aa AA 18 A AAA 21 A A pori a 21 A e 29 243 DUES and AL iiiaae iaeia 45 LAADA O a Peer miter errr eh eter Reet ieorr ere Tene tr 46 E Process

AlazarTech SDK Programmer`s Guide

Contents

Download Pdf Manuals

Related Search

Related Contents