AlazarBeforeAsyncRead

Function Syntax

RETURN_CODE AlazarBeforeAsyncRead(HANDLE handle, U32 channelSelect, long transferOffset, U32 transferLength, U32 recordsPerBuffer, U32 recordsPerAcquisition, U32 flags)

Configure a board to make an asynchronous AutoDMA acquisition.

In non-DSP mode, 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 formula changes to:

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 transfer times compared to the time required to prepare a buffer for DMA transfer and re-arm the DMA engines.

ATS460, ATS660 and ATS860 digitizer boards require that AutoDMA parameters be selected so that the total number of bytes per buffer is less than 4 MB. Other boards require that the total number of bytes per buffer be less than 64 MB. It is however recommended to keep the DMA buffer size below 16 MB for all boards.

Return

ApiSuccess upon success, or an error code. See RETURN_CODE for more detailed information.

Remark

transferLength must meet certain alignment criteria which depend on the board model and the acquisition type. Please refer to board-specific documentation for more information.

Remark

recordsPerBuffer must be set to 1 in continuous streaming and triggered streaming AutoDMA modes.

Remark

recordsPerAcquisition must be 0x7FFFFFFF in Continuous Streaming and Triggered Streaming modes. The acquisition runs continuously until AlazarAbortAsyncRead() is called. In other modes, it must be either:

• A multiple of recordsPerBuffer

• 0x7FFFFFFF to indicate that the acquisition should continue indefinitely.

Parameters

• [in] handle: Handle to board

• [in] channelSelect: Select the channel(s) to control. This can be one or more of the channels of ALAZAR_CHANNELS, assembled with the OR bitwise operator.

• [in] transferOffset: 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.

• [in] transferLength: Specify the number of samples from each record to transfer from on-board to host memory. In DSP-mode, it takes the number of bytes instead of samples. See remarks.

• [in] recordsPerBuffer: The number of records in each buffer. See remarks.

• [in] recordsPerAcquisition: The number of records to acquire during one acquisition. Set this value to 0x7FFFFFFF to acquire indefinitely until the acquisition is aborted. This parameter is ignored in Triggered Streaming and Continuous Streaming modes. See remarks.

• [in] flags: Specifies AutoDMA mode and option. Must be one element of ALAZAR_ADMA_MODES combined with zero or more element(s) of ALAZAR_ADMA_FLAGS using the bitwise OR operator.

LabVIEW Block Diagram

Related Enumerations

enum ALAZAR_ADMA_MODES

AutoDMA acquisition modes. See AlazarBeforeAsyncRead().

Values:

ADMA_TRADITIONAL_MODE = 0x00000000

Acquire multiple records: one per trigger 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: R1[AB...], R2[AB...] ...

ADMA_CONTINUOUS_MODE = 0x00000100

Acquire a single, gapless record 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: R1A, R1B.

If a board does not have on-board memory, or sample interleave is enabled, the buffer will contain samples organized as follows: R1[AB...]

ADMA_NPT = 0x00000200

Acquire multiple records: one per trigger 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: R1A, R2A, ... R1B, R2B ...

If a board does not have on-board memory, or sample interleave is enabled, the buffer will contain samples organized as follows: R1[AB...], R2[AB...] ...

ADMA_TRIGGERED_STREAMING = 0x00000400

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: R1A, R1B.

If a board does not have on-board memory, or sample interleave is enabled, the buffer will contain samples organized as follows: R1[AB...]

enum ALAZAR_ADMA_FLAGS

AutoDMA acquisition options. See AlazarBeforeAsyncRead().

Values:

ADMA_EXTERNAL_STARTCAPTURE = 0x00000001

The acquisition only starts when AlazarStartCapture() is called if this flag is set. Otherwise, it starts before the current function returns.

ADMA_ENABLE_RECORD_HEADERS = 0x00000008

If this flag is set, precede each record 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.

ADMA_ALLOC_BUFFERS = 0x00000020

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 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.

ADMA_FIFO_ONLY_STREAMING = 0x00000800

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: R0[ABAB...], R1[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.

ADMA_INTERLEAVE_SAMPLES = 0x00001000

Enable a board to interleave samples from both digitizer channels in dual-channel acquisition mode. This results in higher data transfer rates on boards that support this option.

Note that this flag has no effect in single channel mode, and is supported by only PCIe digitizers (except the ATS9462).

When the flag is set, each buffer contains data organized as follows: R0[ABAB...], R1[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 = 0x00002000

Enable the API to process each buffer So that the sample data in a buffer is Always arranged as in NPT mode: R0A, R1A, R2A, ... RB0, R1B, 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.

ADMA_DSP = 0x00004000

Activates the DSP mode that must be used for using the on-FPGA DSP modules such as the on-FPGA FFT.

ADMA_ENABLE_RECORD_FOOTERS = 0x00010000

Activate record footers, that are appended to each acquired record. Please note that this feature is not available on all boards, and can only be activated in NPT mode.

struct _ALAZAR_HEADER

Traditional Record Header.

Public Members

struct _HEADER0 hdr0

Substructure 0.

struct _HEADER1 hdr1

Substructure 1.

struct _HEADER2 hdr2

Substructure 2.

struct _HEADER3 hdr3

Substructure 3.

struct _HEADER0

Traditional Record Header Substructure 1.

Public Members

unsigned int SerialNumber : 18

18-bit serial number of this board as a signed integer

unsigned int SystemNumber : 4

4-bit system identifier number for this board

unsigned int WhichChannel : 1

1-bit input channel of this header. 0 is channel A, 1 is channel B

unsigned int BoardNumber : 4

4-bit board identifier number of this board

unsigned int SampleResolution : 3

3-bit reserved field

unsigned int DataFormat : 2

2-bit reserved field

struct _HEADER1

Traditional Record Header Substructure 1.

Public Members

unsigned int RecordNumber : 24

24-bit index of record in the acquisition

unsigned int BoardType : 8

8-bit board type identifier. See BoardTypes for a list of existing board types.

struct _HEADER2

Traditional Record Header Substructure 2.

Public Members

unsigned int TimeStampLowPart

Lower 32 bits of 40-bit record timestamp.

struct _HEADER3

Traditional Record Header Substructure 3.

Public Members

unsigned int TimeStampHighPart : 8

8-bit field containing the upper part of the 40-bit record timestamp

unsigned int ClockSource : 2

2-bit clock source identifier. See ALAZAR_CLOCK_SOURCES

unsigned int ClockEdge : 1

1-bit clock edge identifier. See ALAZAR_CLOCK_EDGES

unsigned int SampleRate : 7

7-bit sample rate identifier. See ALAZAR_SAMPLE_RATES

unsigned int InputRange : 5

5-bit input range identifier. See ALAZAR_INPUT_RANGES

unsigned int InputCoupling : 2

2-bit input coupling identifier. See ALAZAR_COUPLINGS

unsigned int InputImpedence : 2

2-bit input impedance identifier. See ALAZAR_IMPEDANCES

unsigned int ExternalTriggered : 1

1-bit field set if and only if TRIG IN on this board caused the board to

unsigned int ChannelBTriggered : 1

capture this record.

1-bit field set if and only if CH B on this board caused the board to

unsigned int ChannelATriggered : 1

capture this record.

1-bit field set if and only if CH A on this board caused the board to

unsigned int TimeOutOccurred : 1

capture this record.

1-bit field set if and only if a timeout on a trigger engine on this

unsigned int ThisChannelTriggered : 1

board caused it to capture this record.

1-bit field set if and only if the channel specified by _HEADER0::WhichChannel caused the