Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Scroll Documents: Update page title prefix

...

It is important to understand how to use and manipulate these classes in order to properly use all of the features of Audio Weaver.  We begin by describing each class and then document additional MATLAB commands used for constructing modules.

@awe_variable

A variable in Audio Weaver represents a single scalar or array variable on the target processor.  Even if you are not developing modules, it is good to understand the @awe_variable object so that you can fully utilize variables.

...

Code Block
filter = Biquad // 2nd order IIR filter

     b0: 1          // First numerator coefficient
     b1: 0          // Second numerator coefficient
     b2: 0          // Third numerator coefficient
     a1: 0          // Second denominator coefficient
     a2: 0          // Third denominator coefficient
  state: 0
          0]

@awe_module

This class represents a single primitive audio processing function on the target.  A module consists of the following components: a set of names, input and output pins, variables, and functions.  All of these items exist in MATLAB and many of them have duals on the target itself.

Class Object
Anchor
ClassObject
ClassObject

To create an audio module object, call the function M=awe_module(CLASSNAME, DESCRIPTION)

...

  • name — name of the module within the subsystem.  This is specified when the module is instantiated and cannot be changed thereafter.  Not user editable.

  • className — name of the underlying module class.  This is specified when the module is instantiated and cannot be changed thereafter.  Not user editable.

  • description — short comment indicating what the module does.  User editable.

  • classID — unique integer which identifies the module class on the target.  This value is set by the code generator and is normally blank.  Not user editable.

  • constructorArgumentlist of the arguments to the module. Module must be called with all arguments while generating the code. This field is important for AWE Designer to pass arguments to module.

  • defaultName Fixed default name of the module.

  • moduleVersion Version of the module.

  • classVersion Version of the module class.

  • isDeprecated Boolean indicates whether the module is deprecated in the current version of AWE Designer.

  • isInterpreted Boolean indicates whether the module is Interpreted or not.

  • mfilePath — full path to the m-file which instantiated the module (the one containing the call to @awe_module).  Used by the code generator.  Not user editable.

  • mfileDirectory — the directory portion of mfilePath.  Not user editable.

  • mfileName — the file name portion of mfilePath.  Not user editable.

  • mode — string indicating the current module status.  This can be either 'Active', 'Bypassed', 'Muted', or 'Inactive'.  Used internally and is not user editable.  Use the functions awe_setstatus.m and awe_getstatus.m to manipulate the module status.

  • clockDivider — integer indicating how often the module will be run within the layout.  This is currently always set to 1 (meaning run every time).  This is reserved for new Audio Weaver functionality planned in the future.  Not user editable.

  • inputPin — cell array of input pin information.  This information is set by the add_pin.m function and should not be changed.  You'll frequently access this to determine the properties of the input pins.  Each cell value contains a data structure such as:

    Code Block
    SYS.agc.core.inputPin{1}
    
    ans = 
    
                  type: [1x1 struct]
                 usage: 'input'
                  name: 'in'
           description: 'Audio input'
        referenceCount: 0
            isFeedback: 0
              drawInfo: [1x1 struct]
             wireIndex: 1
  • outputPin — similar to inputPin.  It is a cell array describing the output pins.

  • scratchPin - similar to inputPin.  It is a cell array describing the scratch pins.

  • variable — a cell array of @awe_variable objects corresponding to the variables in this module.  This array is updated by the add_variable.m function.  Not user editable.

  • variableName — a cell array of strings, one for each variable in the module.  This cell array is used to speed up variable accesses.  This array is updated by the add_variable.m command.  Not user editable.

  • control — holds internal information related to the inspector.  Not user editable.

  • wireAllocation — a string specifying how wires should be allocated for the module.  Possibilites are 'across' and 'distinct'.

  • getFunc — optional MATLAB function pointer specifying the module's get function.  This function is called whenever a variable in the module is queried.  Used very rarely.  Normally this is set to the empty matrix.

  • setFunc — optional MATLAB function pointer specifying the module's set (or control) function.

  • processFunc — optional MATLAB function pointer specifying the module's processing function.  The processing function is a MATLAB implementation of the audio processing performed by the module.

  • bypassFunc — optional MATLAB function pointer specifying the module's bypass behavior.

  • muteFunc — optional MATLAB function pointer specifying the module’s mute behavior.

  • preBuildFunc — optional MATLAB function pointer specifying the module's prebuild functionality.  The prebuild function is called prior to building the module or generating code and resolves pin types and array sizes.

  • postBuildFunc — optional MATLAB function pointer specifying the module’s postbuild functionality. Generally most of the module will have this field as empty.

  • testHarnessFunc — optional MATLAB function pointer specifying the module’s test harness script.

  • profileFunc — optional MATLAB function pointer specifying the module’s profile function.

  • isHidden — Boolean specifying whether the module should be shown when part of a subsystem.  Similar to the .isHidden field of @awe_variable objects.  User editable.

  • isPreset — Boolean that indicates whether the module will be included in generated presets.  By default, this is set to 1.  User editable.

  • isMeta — Boolean specifying whether this is a meta-module which switches out at build time.

  • metaFuncName — optional string specifying the name of the underlying module to instantiate if this is a meta module.

  • requiredClasses — This is the list of classes required for the current instantiation of the

  •  module.  For meta modules it could be a subset of requiredClassesBrowser.

  • consArgPatchFunc — Custom function to matchup older version of system with new module.

  • moduleBrowser — This is the information for displaying the module in AWE Designer GUI. It includes the image of the module in the designer module tree, search tag, name of the module in browser etc. Look for .moduleBrowser for more information.

  • textLabelFunc — Function for generating a text lablel when drawn in the AWE Designer GUI. Look at the .textLablelFunc for more information.

  • textInfo — Text label properties information.

  • shapeInfo — Is a structure which holds shape information of the module in the AWE Designer GUI. It includes the name of the SVG image used to draw on the layout, size of the module, shape of the module etc. Look at .shapeInfo for more information. Default shape information is Rectangle box with Solid lines with Black color. This can be overwritten by initializing fields in this structure.

  • freqRespFunc — Optional MATLAB function pointer for computing the frequency response of the module.

  • bypassFreqRespFunc — Frequency response function of the module in bypass mode.

  • prepareToSaveFunc — Function for clearing out internal pointers or other state that is not needed when the module is saved.

  • copyVarFunc — optional MATLAB function pointer that is called when a module’s variables need to be copied. User can over right the default generic copy variables function.

  • inspectFunc — optional MATLAB function for drawing custom inspector.

  • inspectHandle — Figure handle of the custom inspector, internal to the Audio Weaver.

  • inspectPosition — Position, [x y], of the custom inspector in MATLAB coordinates used by the “inspect” function of the Audio Weaver.

  • inspectUserData — Custom inspector persisted information.

  • numericInspectHandle — Numeric inspector handle of the module for AWE Designer.

  • numericInspectPosition — Position, [x y], of the numeric inspector of the module in MATLAB coordinates for designer.

  • freqRespHandle — Module’s frequency response handle.

  • freqRespPosition — Position, [x y], of the frequency response to be drawn in MATLAB coordinates for designer.

  • isTunable — Boolean indicating whether the variables in the module are real time tunable or not in designer.

  • View — Structure of various fields internal to Audio Weaver holds the view settings in the designer.

  • isLive —Boolean indicating whether the module has been built and is running on the target.  When a module is first instantiated, this is set to 0 and then changed to 1 by the build process.  Not user editable.

  • hierarchyName — hierarchical name of the module within the subsystem.  This is filled in during the build process.  Not user editable.

  • hasFired — Boolean field that is used internally by the routing algorithm.  Not user editable.

  • targetInfo — data structure holding target specific information.  This is filled in by the build process and is used internally for tuning.  Not user editable.

  • codeMarker — a cell array holding all of the code markers.  Code markers are used for module generation and described in Section 5.2.  Not user editable.

  • isTopLevel — Boolean set by the buid process.  A value of 1 indicates that a module is the highest level item in a system.  All modules have .isTopLevel=0; only the top-level subsystem has .isTopLevel=1.  Not user editable.

  • guiInfo — data structure used for drawing inspectors.  Some fields are user editable. See Overriding Default GUI Settings for information about creating custom inspector interfaces.

  • drawInfo — data structure used internally when creating drawings of subsystems and modules.  Not user editable.

  • docInfo — data structure containing documentation information.  This is set in the module's m-file and is used by the automated documentation generator.  Some user editable fields.  Refer to the Section 6.

  • isLocked — internal field used to accelerate references.  Not user editable.

  • class — string specifying the underlying object class.  This is always 'awe_module'.  Not user editable.

  • fieldNames — internal cell array of field names (actually the names of the fields in this data structure).  It is used to accelerate references.  Not user editable.

...

MATLAB Functions for Constructing Modules

The following functions are commonly used for constructing audio modules.  They are briefly mentioned here and are documented later in this guide.

...

add_codemarker.m — adds information related to code generation.

add_control.m — exposes a single control on the inspector.

...

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 — the @awe_module object.

.bypassFunc

Provides a custom bypass function for a module.  The function signature is identical to the .processFunc

...

  • M — the @awe_module object.

  • 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:

...

  • M — the @awe_module object.

  • H_IN — a cell array of corresponding to the input data.

  • W — vector of frequencies at which frequency response to be computed.

  • 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:

...

  • M — the @awe_module object.

  • 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 Class Object.

...

  • isPrebuilt — a Boolean specifying where the system has already been through the prebuild process.  This is used internally and is not user editable.

  • preProcessFunc — pointer to a MATLAB function which is called prior to the subsystem being executed.  It is the MATLAB dual to the 'preProcessFunc' code marker and is used for simulating subsystems in MATLAB.

  • postProcessFunc — pointer to a MATLAB function which is called after the subsystem has executed.  It is the MATLAB dual to the 'postProcessFunc' code marker and is used for simulating subsystems in MATLAB.

  • buildFunc — pointer to a MATLAB function which builds the subsystem on the target.  This is empty except for top level systems.

  • drawFunc — pointer to a MATLAB function which overrides drawing of the module in figure windows.  This is not yet used and is provided for future enhancements.

  • module — cell array of the internal modules used by the subsystem.  Not user editable.

  • moduleName — cell array of internal module names.  This is used to accelerate references.  Not user editator.

  • connection — cell array describing all of the connections in the subsystem.  This array is populated by calls to connect.m.  Not user editable.

  • flattenOnBuild — a Boolean describing how this subsystem is treated during code generation and building.  When creating new module classes out of subsystems, set .flattenOnBuild = 1.  See Section 7.3 for an example.

  • 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 MATLAB Scripting 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
Anchor
new_pin_type.m
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:

...

Code Block
>> PT=new_pin_type([], [], [], '*32')

PT = 

         numChannels: 1
           blockSize: 32
          sampleRate: 48000
            dataType: 'float'
           isComplex: 0
    numChannelsRange: []
      blockSizeRange: []
     sampleRateRange: []
       dataTypeRange: {'float'  'int'  'fract32'}
      isComplexRange: 0

add_pin.m
Anchor
add_pin.m
add_pin.m

Pins are added to a module by the add_pin.m function.  Each pin has an associated Pin Type as described in new_pin_type.m.  After creating the Pin Type, call the function

...

  • Pins of the same direction should have no duplicate names.

  • If the module has number of pins depends on the argument then the number of pins must be passed as last argument to add_pin(). For example, interleave_module.m has input pins depends on argument, NUMIN. Input pins must be added as below:
    add_pin(M, 'input', 'in', 'Input signal', PT, NUMIN);
    The module will display input pins as in1, in2 …. in<NUMIN> in the designer. Here ‘in’ is the base name.

  • If the module has scalar pin along with pin array, then the scalar pin name must not match the bas name of a pin array.

add_variable.m
Anchor
add_variable.m
add_variable.m

M=add_variable(M, VAR)

Adds a single scalar variable to an @awe_module or @awe_subsystem object and returns the updated object.

...

Note that after a variable is added to a module, it appears as a field within the module’s structure and the name of the field equals the name of the variable.  Attributes of an individual variable are referenced using the “.” structure notation.  Refer to Audio Module Instance Structure to see the correspondence between variables in the MATLAB object and variables in the C type definition.

add_argument.m
Anchor
add_argument.m
add_argument.m

M = add_argument(M, VAR, varargin)

...

  • M — @awe_module or @awe_subsystem object to which to add the argument

  • VAR — @awe_variable object that describes the input parameter, OR use the second through N arguments to create the variable as described in the previous section.

...

add_array.m
Anchor
add_array.m
add_array.m

M=add_array(M, VAR)

Adds an array to an @awe_module or @awe_subsystem object and returns the updated object.

...

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: you will not be able to examine the contents of pointer variables from MATLAB, since is unaware of the data type of the variable.

add_module.m
Anchor
add_module.m
add_module.m

Modules are added to subsystems one at a time using the function

...

Code Block
for i=1:length(SYS.module)
      fprintf(1, '%s\n', SYS.module{i}.name);
end

connect.m

Creates a connection between two pins in a subsystem.  The general form is:

...

If the subsystem has a direct connection from an input pin to an output pin, then a copier_module is inserted.  If a module output fans out to N outputs of the subsystem, then N-1 copier modules are inserted. This is required since each output of the subsystem is stored in a separate buffer.

get_variable.m and set_variable.m
Anchor
get_variable.mandset_variable.m
get_variable.mandset_variable.m

Extract and assign individual @awe_variable objects within an audio module.  This is needed because of the object-oriented nature of the Audio Weaver interface.  When accessing a variable "var" within a module "M", as in:

...

Note: 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.

...