Multi-Buffered Output Data Exchange¶

Description¶

Seamless output buffer exchange with ALERT interrupt generation

This resource is used to exchange multiple-buffered output data seamlessly with the System CPU application. This simplifies data communication, particularly when the Sensor Controller continues to produce output data while the System CPU is waiting to or is processing previous data.

The number of output data structure buffers can be configured between 2 and 256. The resource should only be enabled when required, since it increases memory usage and also adds overhead when accessing output data structure variables.

When using this resource, the Sensor Controller task code accesses variables in the output data structure as normal, however all accesses will be done indirectly to the current buffer (as opposed to normal direct accesses).

Task code must call fwSwitchOutputBuffer() to hand over the current output buffer to the System CPU application. Normally, this will assign a new output buffer to the output data structure and trigger an ALERT interrupt. Subsequent accesses to output data structure variables will be to the new output buffer.

Buffer overflow can optionally be indicated and/or prevented by fwSwitchOutputBuffer() . Task code can also call fwCheckOutputBuffer() to find whether the current output buffer can be written without causing overrun. The following can be configured in the Task Panel resource list:

Whether fwSwitchOutputBuffer() shall indicate overflow if attempting to switch to an unavailable buffer (default = enabled).
Whether fwCheckOutputBuffer() shall indicate overflow if the current buffer is unavailable (default = disabled).
Whether fwSwitchOutputBuffer() shall abort if the next buffer is unavailable (default = disabled).

If overflow handling is required in the application (for example when buffers cannot be dropped silently), the application must call scifGetAlertEvents() to check for errors before accessing output buffers.

The ALERT interrupt generation takes effect at the end of the Sensor Controller wake-up, after all executed tasks have finished. If multiple tasks generate ALERT interrupt during the same wake-up, there will only be one ALERT event callback from the SCIF driver.

For details on how to handle ALERT interrupts, see the SCIF driver documentation.

Examples¶

Buffer Switch Without Overflow Handling¶

// Add data to the current output buffer
...

// Hand off the buffer to the application
fwSwitchOutputBuffer();

Buffer Switch With Overflow Prevention¶

// Make sure that the currently used output buffer is available before producing data:
U16 isOutputBufferAvailable;
fwCheckOutputBuffer(isOutputBufferAvailable);
if (isOutputBufferAvailable == 1) {

    // Add data to the current output buffer
    ...

    // Hand off the buffer to the application
    fwSwitchOutputBuffer();
}

Procedures Overview¶

Name	Brief description
`fwCheckOutputBuffer()`	Checks whether the current output buffer (one instance of the multi-buffered `output` data structure) is available, meaning one of the following. More …
`fwSwitchOutputBuffer()`	Hands the current output buffer to System CPU and provides the task with a new output buffer. More …

Constants¶

Name	Description
`FW_OUTPUT_CHECK_IND_OVF`	Whether fwCheckOutputBuffer() overflow indication is enabled (configuration)
`FW_OUTPUT_SWITCH_IND_OVF`	Whether fwSwitchOutputBuffer() overflow indication is enabled (configuration)
`FW_OUTPUT_SWITCH_PREV_OVF`	Whether fwSwitchOutputBuffer() overflow prevention is enabled (configuration)

Global Variables¶

None.

Procedures¶

fwCheckOutputBuffer¶

Prototype: fwCheckOutputBuffer(isAvailable)

Checks whether the current output buffer (one instance of the multi-buffered output data structure) is available, meaning one of the following:

It has not yet been used
It has been used, but has then been processed and handed back by the System CPU application

To use this procedure to prevent buffer overrun:

Call fwCheckOutputBuffer() before starting to work on a new output buffer to make sure it is available
Do not write to the new output buffer or call fwSwitchOutputBuffer() until fwCheckOutputBuffer() returns 1

Note: If overflow indication at buffer check is enabled, use the scifGetAlertEvents() function in the application to check for errors. See the driver sample documentation for details.

Return value(s)¶

isAvailable : 1 if the current output buffer is available, otherwise 0

fwSwitchOutputBuffer¶

Prototype: fwSwitchOutputBuffer()

Hands the current output buffer to System CPU and provides the task with a new output buffer.

Note: If there is risk of buffer overrun, use the scifGetAlertEvents() function in the application to check for errors. See the driver sample documentation for details.

Note: Task Testing simplifies multiple-buffering by resetting associated control variables (head and tail pointers) between task iterations. This means that after calling fwSwitchOutputBuffer() , further accesses to the output data structure should be avoided until the next task iteration.