flex_check_buffer_rtn

NI-Motion Functions

flex_check_buffer_rtn

Device Compatibility

Device Compatibility
7330
N
7340
Y
7344
Y
7350
Y
7390
N
NI SoftMotion Controller for CANopen—Xenus
Y
NI SoftMotion Controller for CANopen—Accelnet
Y

Check Buffer Return

Usage

status = flex_check_buffer_rtn(u8 boardID, u8 buffer, u8 returnVector, u32* backlog, u16* bufferState, u32* pointsDone);

Purpose

Returns information about the current state of the buffer.

Parameters

Name Type Description
boardID u8 assigned by Measurement & Automation Explorer (MAX)
buffer u8 buffer to check
backlog u32* points that can be read from or written to the buffer
bufferState u16* current state of the buffer
pointsDone u32* number of points the controller has written or read

Parameter Discussion

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

backlog is the number of 32-bit data points that can be safely read from or written to the buffer without violating the oldDataStop condition. This value is useful when oldDataStop is set to true in the Configure Buffer function.

bufferState is the current state of the buffer.

Error Number Description
NIMC_BUFFER_NOT_EXIST 0 The buffer does not exist. This also returns error -70137.
NIMC_BUFFER_READY 1 The buffer is configured but is not being used by any resource.
NIMC_BUFFER_ACTIVE 2 The buffer is configured and is being used by a resource.
NIMC_BUFFER_DONE 3 The buffered operation is complete.
NIMC_BUFFER_OLDDATASTOP 4 The operation stopped on unread data
that would be overwritten.

pointsDone gives the total number of points read from the buffer by the controller or written to the buffer by the controller because the operation started.

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.

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.

Write: 0                                    
                                     
Read: 0                                   

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.

                Write: 5                    
3   4   5                      
Read: 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.

                Write: 5                    
3   4   5                      
        Read: 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.

        Write: 13                            
11  12  13   4   5   6    7    8    9    10   
            Read: 4