Change Thread V2

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.

To keep the internal FifoInV3 and FifoOutV3 modules in sync when the module status is inactive or mute, internal modules use custom inactive and mute functions with minimal load.

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.

Module Pack

Advanced

ClassID

classID =

Type Definition

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

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.