Write Buffer

Usage

status = flex_write_buffer(u8 boardID, u8 buffer, u32 numberOfPoints, u16 regenerationMode, i32* data, u8 inputVector);

Purpose

Writes data to a previously configured buffer.

Parameters

Parameter Discussion

buffer is the buffer to write to. Valid buffer numbers are 1 through 255 (0x01 through 0xFF). numberOfPoints is the number of 32-bit data points to write to the buffer.

regenerationMode allows you to specify that this write is the last write for the buffered operation. This parameter is normally set to 0 (No Change), but can be set to 1 (Last Write) when the total number of points you want to output is not known ahead of time.

When all of the data in the buffer is consumed, the operation then completes with a normal status, even if it completed by encountering older data.

data is the array of data to write to the buffer.

inputVector indicates the source of the data for this function. Available input vectors include immediate (0xFF), variable (0x01 through 0x78), or indirect variable (0x81 through 0xF8). Refer to Input and Return Vectors for more detailed information.

Using This Function

After a buffer has been configured for an output operation such as contouring, write data to the buffer before starting the operation. When all of the data fits in the buffer (totalPoints is less than or equal to bufferSize), you need only fill the buffer one time with the appropriate data.

When using the buffer as a circular buffer (totalPoints > bufferSize), with oldDataStop turned on, you need to write fresh data to the buffer faster than the NI motion controller consumes the data. After filling the buffer once, and starting the buffered operation, you can determine the number of points you can safely write to the buffer by calling the Check Buffer function. The backlog parameter indicates how many points you can safely write to the buffer without overwriting data that has yet to be consumed by the controller.

If you try to write new data on top of old data (data that has not been consumed by the controller), the data is not written, and the controller generates an NIMC_oldDataStopError. However, if you configured the buffer with oldDataStop set to false, you can write data freely to the buffer, and the controller does not enforce the oldDataStop condition.

Basic Uses

Suppose you have a contour move of 25,107 points, and configure a buffer with bufferSize of 1,000 points and totalPoints of 25,107. You set oldDataStop in the Configure Buffer function to True, and use the Check Buffer and Write Buffer functions as you write data to the buffer in small chunks while the data is being consumed by the NI motion controller. When you write the last points to the controller, you can still set regenerationMode to 0 (no change) and the NI motion controller knows you are done writing data to the buffer because you have written 25,107 points in total. When the controller is unable to read any more because the read mark has caught up to the write mark, the controller checks regenerationMode, recognizes this stop is intentional because the total points written to the buffer is equal to totalPoints, and completes the operation without generating an oldDataStop error.

Advanced Uses

To write data to the buffer from onboard variables, you must use an inputVector other than 0xFF. The variable you specify for the inputVector indicates the starting point for the data for this function, including the numberOfPoints parameter and the regenerationMode parameter, followed by the data to write to the buffer. To write 10 data points to the buffer, you need to use 12 variables. Under no circumstances can data be written to an input buffer after the specified number of points has already been written to the buffer. A NIMC_illegalBufferOperation error is generated in this case. The number of points is generally defined as the number of iterations times the size of the buffer.

The regenerationMode parameter allows you to gracefully complete a buffered output operation without generating an NIMC_olddatastopError, even though the operation completes as the read mark catches up to the write mark and the operation terminates because there's no more data available for the controller to consume.

For example, assume you have a contour move of less than 16,000 points, so you configure a buffer for 1,000 points and 16,000 total points. You set the oldDataStop parameter to True with Configure Buffer, and use the Check Buffer and Write Buffer functions to write the points to the buffer as the data is being consumed by the NI motion controller. During runtime you are able to determine the exact number of points needed for the contoured operation, and you discover you only need to write x more points to the buffer instead of the originally configured 16,000. To force the controller to stop after reading those x remaining points and prevent oldDataStop error conditions, set the regenerationMode parameter to 1 (Last Write) when you write the last set of points to the buffer. When the controller is unable to read any more data from the buffer because the read mark has caught up to the write mark, the controller recognizes that this was intentional because the Last Write condition was set and does not generate an NIMC_olddatastopError.