...
The following functions are commonly used for constructing audio modules. They are briefly mentioned here and are documented later on in this guide.
add_variable.m – adds a scalar variable to an audio module object.
add_array.m – adds an indirect array to an audio module object.
add_pin.m – adds an input, output, or scratch pin to an audio module object.
add_codemarker.m – adds information related to code generation.
add_control.m – exposes a single control on the inspector.
set_variable.m – replaces an existing module variable
...
.
...
get_variable.m – extracts a variable from a module and returns an @awe_variable object
...
.
...
...
Internal Module Functions
Every module in Audio Weaver has an associated MATLAB function file that constructs an @awe_module object describing the module. Audio Weaver uses the convention that these module constructor functions end in "_module.m". In addition to configuring the module’s input and output pins, and defining instance variables, the constructor function also assigns a number of method functions, and these functions are typically contained as sub-functions in the constructor file.
...
MATLAB Function Name | Target Function Name |
Purpose |
*_module.m | *_Constructor() | Constructs an instance of a module class. The function allocates memory for the base instance structure. The MATLAB function sets default values while on the target default values are passed into the constructor. Required. |
.processFunc | *_Process() | Real-time processing function. Required for C code. Optional for MATLAB. |
.setFunc | *_Set() | Implements the module's control functionality. The function converts high-level interface parameters to lower-level derived values. This function should be called whenever a variable in a module is modified. Optional. |
.getFunc | *_Get() | The counterpart to the _Set() function but is used when module variables are read. Most modules do not use this function. When a module instance variable is read, this function is first called and then the instance variable is returned. It could be used, for example, to convert a measurement from energy to dB. |
.bypassFunc | *_Bypass() | Implements the module's bypass functionality. This is an optional function; when it is empty, a generic bypass function is used instead. |
.preBuildFunc | N/A | This function exists only in MATLAB and it is called as part of the build procedure. The prebuild function propagates pin information and may update array sizes. The prebuild function is useful for setting variable values that depend upon the pin type. The prebuild function is optional; if it doesn't exist, the pin type information from the module's first input pin is propagated to the output. |
.freqRespFunc
| N/A | This optional function exists only in MATLAB and it computes the frequency response of the module. |
.profileFunc
| N/A | This optional function exists only in MATLAB and it profiles the module for various settings like different block size and etc. |
.textLabelFunc
| N/A | This optional function exists only in MATLAB and it draws the text label for the AWE Designer GUI. |
...
MATLAB Module M-File
The MATLAB m-file associated with an audio module creates and returns an instance of the module. The typical function signature for a module m-file is
...
The main difference between the MATLAB instantiation function and the C constructor is that the C constructor is responsible for all memory allocation. MATLAB, on the other hand, has the option of doing memory allocation in the prebuild function.
...
.
...
processFunc
This function provides a MATLAB implementation of the module's processing function. The function signature is:
...
SR = (float) ClassWire_GetSampleRate(pWires[0]);
...
.setFunc
Implements the main control functional for a module. This function is called whenever a variable within the audio module is updated. The function signature is:
...
Note that the MATLAB set function does not have a MASK argument indicating which variable changed.
...
.getFunc
Implements secondary control functionality. This function is called when a variable in the module is read. The function signature is identical to the .setFunc
...
M – is the @awe_module object.
...
.bypassFunc
Provides a custom bypass function for a module. The function signature is identical to the .processFunc
...
WIRE_IN – a cell array of corresponding to the input data to be processed by the module.
...
.
...
preBuildFunc
This function is called when a system is built for execution on a target. The function updates any internal variables which depend upon the sample rate, block size, or number of channels. The function also implements non-standard pin propagation functionality. The function signature is:
...
The function updates and returns the module object M.
...
.
...
freqRespFunc
This function computes the frequency response of the system. The function signature is:
...
H_OUT – a cell array of frequency response output of corresponding input data.
...
.textLabelFunc
This is an optional function which returns text labels to be displayed in AWE Designer. The function signature is:
...
L – a cell array of strings with desired text labels in AWE Designer
...
@awe_subsystem
This class represents both systems and subsystems; they are equivalent and no distinction is made in Audio Weaver. A subsystem has all of the characteristics of an audio module: a class name, input and output pins, variables, and associated sub-functions. In addition, a subsystem contains two other items:
...
Key subsystem functions are described next.
...
ClassObject
The call to create a new empty subsystem is similar to the call to create a new module described in Section 3.2.1
...
targetSpecificInfo – a data structure populated by the build process. It is used to enable real-time tuning on a target. Not user editable.
...
MATLAB Functions for Constructing Subsystems
All of the functions listed in Section 3.2.2 which are used to construct modules also apply to subsystems. Additional commands for constructing subsystems are:
...
These commands are documented in the Audio Weaver Matlab API.
...
Internal Subsystem Functions
Each subsystem has a set of subfunctions that mirror the module functions described in 3.2.3. Fortunately, for most subsystems, generic or generated versions of the functions can be used. The table below describes the operation of each of the functions in the context of generated code.
MATLAB Function Name | Target Function Name |
Purpose |
*_module.m | *_Constructor() | This MATLAB code must be manually written as described above. Modules are manually added, configured, and connected. The C code version of this function is automatically generated. The function calls the base module constructor function and then calls the _Constructor() function for all internal modules. The internal modules parameters are set according to their values at build time. |
.processFunc | *_Process() | Audio Weaver automatically generates the MATLAB and C versions of these functions. |
.setFunc | *_Set() | In all cases, this must be manually written. |
.getFunc | *_Get() | In all cases, this must be manually written. |
.bypassFunc | *_Bypass() | The generic function utilized by modules can also be used here. |
.preBuildFunc | N/A | Not needed. The existing pin propagation function can propagate the information through subsystems. |
...
Top-Level Systems
Thus far, we have been using the terms system and subsystem interchangeably. There is a slight difference, though, that you need to be aware of. The highest level system object that is passed to the build command must be a top-level system created by the function:
...
and the type information for output pins is determined by pin propagation.
...
new_pin_type.m
This function returns a data structure representing a pin. The internal structure of a pin can be seen by examining the pin data structure. At the MATLAB command prompt type:
...
Using indirect arrays enables arrays to have variable length and also to be placed in distinct memory banks. This is last time is useful, for example, on the SHARC processor to enable simultaneous memory reads.
...
add_pointer.m
add_pointer(M, NAME, CTYPE, [USAGE], [DESCRIPTION], [ISHIDDEN]))
...
Note that you will not be able to examine the contents of pointer variables from Matlab since Matlab is unaware of the data type of the variable.
...
add_module.m
| Anchor | ||||
|---|---|---|---|---|
|
Modules are added to subsystems one at a time using the function
...
fprintf(1, '%s\n', SYS.module{i}.name);
end
...
connect.m
Creates a connection between two pins in a subsystem. The general form is:
...
get_variable.m and set_variable.m also apply to @awe_subsystem objects.
...
Module for AWE Designer
This section focus on the module browser information related to AWE Designer. Every module must initialize the moduleBrowser and shapeInfo structure of the MATLAB module object. Below is the example settings of downsampler_example_module.m module. Refer the section 3.2 for complete information of these structures.
...