Check Buffer

Usage

status = flex_check_buffer(u8 boardID, u8 buffer, u8 returnVector);

Purpose

Returns information about the current state of the buffer.

Parameters

Parameter Discussion

buffer is the buffer to check. Valid buffer numbers are 1 through 255 (0x01 through 0xFF).

returnVector indicates the destination for the return data generated by this function. Available return vectors include return data to the host (0xFF), to a variable (0x01 through 0x78), to an indirect variable (0x81 through 0xF8), and return no data (0). Refer to Input and Return Vectors for more detailed information. returnVector returns data in the following order: backlog, bufferState, and pointsDone.

Using This Function

This function provides you with current information about the state of the buffer. In single iteration situations (totalPoints was set to bufferSize in the Configure Buffer function), the bufferState parameter is most useful in determining that the operation has completed.

For a finer resolution view of the state of the buffer, the backlog parameter indicates the number of points that can safely be written to or read from the buffer without violating the oldDataStop condition. Refer to Configure Buffer for more information.

pointsDone is the number of points read from the buffer by the controller (in the case of an output buffer) or written to the buffer by the controller (in the case of an input buffer). pointsDone is from the point of view of the controller, rather than the user. In the output case (contouring for example), even after the buffer has been filled by the user but the move has not yet been started, pointsDone is still 0, because the controller has not yet read any data from the buffer. After the move has started, and some points have been read from the buffer by the NI motion controller, pointsDone is non-zero. In the input case (high-speed capture readback for example), after the controller has filled the buffer with high-speed capture positions once, pointsDone is the size of the buffer, even if the user has not yet read any data out of the buffer.

Note  This function returns data in the following order: backlog, bufferState, and pointsDone.

As an example, in the case of contouring (output buffer), the backlog parameter aids you in determining when you can write more data to the buffer, while the pointsDone parameter tells you how many points have actually been splined together by the controller. pointsDone reflects what is happening in the real world where motion occurs.

Example (Output Buffer)

After a 10-point buffer is configured for contouring, the contents are indeterminate and both the read and write heads are at zero.

After writing five points to the buffer, with the values 1 through 5, the write head has moved to the sixth position in the buffer, where the next write takes place. The read head is still at zero, because no data has been read from the buffer yet. Likewise, pointsDone is still 0.

The contouring operation is started by calling the Start Motion function, and the controller starts reading data from the buffer. After reading three points, the read head is at the fourth buffer element, with a value of 3. pointsDone is equal to 3.

Upon calling the Check Buffer function, the backlog is 8, meaning that eight points can be safely written to the buffer without overwriting data still remaining to read by the controller. The pointsDone parameter is still equal to 3. At this point, another Format call of eight points with values between 6 and 13 results in a write head with a value of 13 at the fourth buffer element. In the meantime, another point has been read from the buffer by the controller in the course of doing the contouring operation, causing the read head to advance by one.