ChangeThreadV2

Overview

Buffer data between instances or between threads in the same instance through shared heap or regular heap

Discussion

ChangeThreadV2 routes all input wire data to a user-defined instance ID. If the connected target is a new multi-instance model, all of the downstream modules connected to the output pin will inherit the instance ID configured by the user. If the connected target is a legacy multi-canvas model, targetInstance ID is ignored (has no effect) and the instance ID selected in the Designer drop down list is used in all the modules in the layout. This module requires the configuration and initialization of the AWECore shared heap on all instances of a new multi-instance model target. Designs including ChangeThreadV2 will fail to build without the existence of shared heap in multi-instance model targets.

ChangeThreadV2 allows a user to select the instance ID to which all input pin data will route to using the parameter targetInstance. This is effective only on multi-instance model targets and has no effect in legacy models. ChangeThreadV2 does not modify the input data in any way, but instead handles the IPC layer routing through AWECore's shared heap or regular heap depending on the source and target instances, to provide an abstracted multi-instance design interface.

The module supports multiple input and output pins. The input wires must all be on the same clock divider, but they can all have different block sizes, sample rates, and data types.

The module optionally allows you to increase or decrease the clock divider by an integer factor (bufferUpDownFactor). This causes the output block size to increase or decrease by bufferUpDownFactor as well. This means that if bufferUpDownFactor > 0 then the output clock divider and block size are increased by bufferUpDownFactor, and if bufferUpDownFactor < 0 then the output clock divider and block size are decreased by bufferUpDownFactor. If bufferUpDownFactor == 0 then the output clock divider and block size are inherited from the input pin Larger clock dividers end up going into lower priority layouts.

The module also optionally allows you to specify the output layoutSubID. The layoutSubID allows you to run multiple sets of modules at the same clockDivider but in different layouts. For example, you might have multiple layouts all at a clock divider of 1 operating in a SMP core system. When using Designer, layoutSubID is selected in a droplist to be 'A' to 'P' which corresponds to 16 unique layouts. When using Matlab scripts, layoutSubID is an integer in the range [0 15] which maps directly to [A P]. If layoutSubID is empty, then the thread ID is inherited from the input pin.

Layouts are specified using a combination of bufferUpDownFactor and layoutSubID. The system input pin is always in layout 1A. The system output pin can be on any of the clockDivider 1 layouts (1A, 1B, etc.). If you want multiple layouts all at the same block time as the input pin, then select 1B, 1C, and so forth.

This module introduces a sample latency equal to the bufferUpDownFactor times input pin's block size if bufferUpDownFactor > 0 and input pin's block size otherwise.

When the module is Bypassed, it behaves same as Active. i.e. module process function is called even when the module is bypassed, to make sure corresponding FiFoIn and FiFoOut module are in sync.

Compared the ChangeThread module, this V2 module improves the robustness of the synchronization between different instances and layouts.

There are two examples in Examples\Module_Usage, ChangeThreadV2MultiInstance.awd and ChangeThreadV2SingleInstance.awd which demonstrate this module usage in multi-instance and single-instance systems respectively.

Type Definition

typedef struct _ModuleChangeThreadV2
{
    ModuleInstanceDescriptor instance;            // Common Audio Weaver module instance structure
} ModuleChangeThreadV2Class;

Variables

Properties

Pins

Input Pins

                Name: in1

         Description: audio input

           Data type: {float, int, fract32}

       Channel range: Unrestricted

    Block size range: Unrestricted

   Sample rate range: Unrestricted

     Complex support: Real and Complex

Output Pins

                Name: out1

         Description: audio output

           Data type: {float, int, fract32}

MATLAB Usage

File Name: change_thread_v2_subsystem.m

 SYS = change_thread_v2_subsystem(NAME, NUMPINS, TARGETINSTANCE, BUFFER_UP_DOWN_FACTOR, LAYOUT_SUB_ID)
 Creates an audio module which occupies shared or regular heap memory, allowing for 
 multi-instance or same instance multi-thread audio buffer sharing to abstract IPC audio routing.
    NAME - name of the module.
    NUMPINS - number of pins on input and output
    TARGETINSTANCE - the output layout can run on a different coreID than the
    input layout. TARGETINSTANCE specifies which instanceID layout the
    FifoOutV3 buffer will be processed from.
       By default, TARGETINSTANCE='Inherit'.
    BUFFER_UP_DOWN_FACTOR - the output instance can run at a larger or smaller clock divider
       (block size) compared to the input instance.  BUFFER_UP_DOWN_FACTOR is the
       multiplicative or divisor factor which connects the input and output:
       If BUFFER_UP_DOWN_FACTOR is > 0:
           outputBlockSize = inputBlockSize * BUFFER_UP_DOWN_FACTOR
           outputClockDivider = inputClockDivider * BUFFER_UP_DOWN_FACTOR
       If BUFFER_UP_DOWN_FACTOR < 0:
           outputBlockSize = inputBlockSize / abs(BUFFER_UP_DOWN_FACTOR)
           outputClockDivider = inputClockDivider / abs(BUFFER_UP_DOWN_FACTOR)
       If BUFFER_UP_DOWN_FACTOR is empty or 'Inherit' or 0:
           outputBlockSize = inputBlockSize
           outputClockDivider = inputClockDivider
       By default, BUFFER_UP_DOWN_FACTOR='Inherit' which inherits properties from input to output.
    LAYOUT_SUB_ID - allows you to specify which sublayout ID will be used to process
       the output clockDivider.  By default, this is empty which indicates that
       the ID from input is inherited to output. The sublabel is an integer in the range [0 15] which
       provides finer control over which layout to join.  By default,
       LAYOUT_SUB_ID=[] or 16, which results in inheriting from the input pin.