AWE Target Configurator

AWE Target Configurator (or AWETC) is additional tooling which generates deployment files for the target SOC. AWETC is used by the System Integrator based on input from the Audio Engineer as shown below.

The Audio Engineer uses Designer and the Wave Library Generator to create the following artifacts:

Container file (.awc) for the top-level signal flow. Tunable variables are exposed using objectIDs.
Container file(s) (.awc) for any Subcanvases used. Tunable variables are exposed using objectIDs.
Flash File System (.bin) containing WAV files used by the Flash WAV players in the design.

The System Integrator then adds deployment specific information by editing YML files. This information includes:

Processor core and instance IDs
Processor speeds
Heap sizes
Thread priorities
Core affinities
Stack sizes
Logging and warning levels

This information is used by Audio Weaver BSP code to initialize each instance of the AWECore library in the system. If you need to make changes during development (such as increasing or decreasing heap memory sizes), then it is accomplished by editing YML files rather than writing code.

Setup and Installation

The Audio Weaver tools can be downloaded from this Box folder:
https://dspconcepts.app.box.com/folder/308070071270?s=yyjwu2kb7wkfaozk77vb1f0i479ah583

Look for the folder containing the R4.3 release. Inside a directory called ‘AWE-Target-Configurator’ you will find AWETC.

Basically, AWE-TC is a set of Python packages (wheel files) to be installed on your PC, typically into a dedictated Python environment (as opposed to a system-wide installation).

In that installation folder there is a README file containing detailed instructions to install AWE-TC.

Full Documentation

Once AWE-TC is installed including the doc package, the full documentation is available locally on your PC. Please execute:

CODE

> awetc docs

Getting Started

After you have installed AWETC, you can check which version you have installed using, for example:

CODE

> awetc version
AWE-TC version: 0.5.1

If you see any version not following the major.minor.patch pattern for the version info, you are on a development version. Please contact DSPC.

To generate a skeleton projects with all the files configured as a starting point, use

awetc init

This will create the folder and file structure:

CODE

_stages\deploy\
_stages\signalflow\
_stages\targetconfig\

The files generated are template files and come with reasonable default values.

Still, you edit the files in “signalflow” and “targetconfig”. Then awetc will generate files and store them in “deploy”.

The main files to edit are:

File Location	Description
`_stages\signalflow\config.yml`	Specifies the container files which holds the top level system and subcanvases. This file is typically the only file to edit! Basic.
`_stages\targetconfig\awecore.yml`	Contains the bulk of the BSP configuration information such as how many audio DSPs there are, their heap sizes, etc. Basic.
`_stages\targetconfig\devices_tdm.yml`	Configures TDM devices. Basic. This will be removed in R4.4.
`_stages\targetconfig\awc_extensions.yml`	Allows you to add meta data to tunable variable information, assign alias names, etc. Advanced.
`_stages\targetconfig\codegen_app.yml`	Used to configure parameter control for application. Advanced.
`_stages\targetconfig\aweidl_mcu_chimeplay.yml`	Example how to configure early chimes. Referred to by `codegen_app.yml`. Advanced.
`_stages\targetconfig\aweidl_mercury_playback.yml`	Example how to configure parameter control. Referred to by `codegen_app.yml`. Advanced.
`_stages\targetconfig\cpucores.yml`	Names and numbers CPU cores. Typically not modified. Advanced.
`_stages\targetconfig\modulelist_gpdsp.yml`	An example file how the a list of modules available on a DSP can be stored. Advanced.
`_stages\targetconfig\threads.yml`	Specifies thread priorities and core affinities. Advanced.

After you have edited the YML files, the deployment files are generated with this command:

awetc

Typical output is as shown below

CODE

.  extract_awb
.  aweconfig_bin
-- hello
-- codegen_app
.  awemgr_awc:canvas-toplevel
.  gen_ffs             --> skipped: No FFS configured

Lines that starts with “.” indicate that a file was generated. Lines that start with “--” indicate no change.

It is recommended that you delete the contents of the _stages\deploy folder before running awetc. This ensures that no stale files remain from an earlier run. Alternatively, run awetc with --always-execute parameter.

The generated files can now be found in the _stages\deploy folder:

CODE

early_0_on_ADSP.awb         % AWB file to initialize the ADSP
early_1_on_GPDSP0.awb       % AWB file to initialize GPDSP0
early_2_on_GPDSP1.awb       % AWB file to initialize GPDSP1
3_on_ARM.awb                % AWB file to initialize the Arm processor
awc_index.txt               % Control information to initialize AWE Manager/Service
awe_config.bin              % Binary blob used during early audio
full_design.awb             % AWB file to initialize all processors

This list of files depends on your signal flow configuration and will likely look a bit different when you run AWETC.

The bottom 4 files are most frequently used and you should copy them to the /etc folder of the target. The early_* AWB files are only for reference. They contain the instructions for the early audio processing and are part of awe_config.bin as well.

One way to copy them is via a useful batch file which configures ADB and pushes the files to the target as shown below. Put this in the same directory as the “_stages” folder and name it “push_all.bat”. After copying files, the target is rebooted and Audio Weaver is initialized with the new settings during the boot process.

CODE

adb root
adb remount
adb shell "mount -o remount,rw / && setenforce 0"
adb devices

adb push _stages\deploy\awc_index.txt /etc
adb push _stages\deploy\awe_config.bin /etc
adb push _stages\deploy\full_design.awb /etc
adb push _stages\deploy\3_on_ARM.awb /etc

adb shell sync
adb shell sleep 1
adb shell reboot -f

awc_index.txt is used by the AWE audio service to control modules and variables. This service initializes tinyplay and tinycapture with the information contained in awc_index.txt.

If you change control modules or you assign different object IDs in your signal flow, you need to regenerate the top-level container, push the updated awc_index.txt file to the target, and reboot the target. Just building and running from Designer is insufficient.

During the boot process, the Hexagon DSPs log status information to shared memory. This information can be downloaded and displaying using the batch file check_log.bat shown below:

CODE

@echo off
adb wait-for-device
adb root
adb remount
adb shell "mount -o remount,rw / && setenforce 0"
adb shell awe_log_shmem
adb shell cat /data/awe_log_shmem.log
echo.

The main work is done by awe_log_shmem which writes the log information to the file /data/awe_log_shmem.log. This file contains about 100 lines and the last line is the most useful. It should show something similar to:

CODE

00:00:18.441518|awe_bsp.c                     |awe_child_pump_audio_thread   |  3296 | The first time to pump audio on core: 2

This indicates that GPDSP1 successfully booted, was able to load its signal flow (AWB file) and that real-time audio interrupts have started. Check similar lines for the other cores.

Common System Configuration Changes

This section walks you through common changes to the YML files. It assumes that the starting point is the initial YML files generated by “awetc init” and highlights the changes necessary. It shows you the subset of lines in each YML file which need to be modified.

The processor booting logic used by early audio requires that the signal flow include processing for ADSP, GPDSP0, and GPDSP1 on the 8255. If you do not include modules for all of these DSPs, then Audio Weaver will not boot successfully and the Server will be unable to attach to the Snapdragon.

Changing the block size from 48 samples to 12 samples

AWD Signal Flow

Input TDM port is set to “Synchronous Aligned” with a block size of 12 samples.

Output TDM port is set to “Synchronous Master” with a 12 sample block size

Hardware I/O pins are set to 12 samples

signalflow/config.xml

Note: This file always has to be changed and must point to the AWC files to be used. The change highlighted here is not specific for cutting down the blocksize from 48 samples to 12.

targetconfig/awecore.yml

targetconfig/devices_tdm.yml

Note, there are no changes here but want to reinforce that the Synchronous Master device must be properly configured in this file and must match the settings in the signal flow. The Synchronous Master is the output device and using interface {LPAIF_VA, 0}.

Making GPDSP1 the Primary Audio Controller and 12 Sample Block Size

This example shows how to make GPDSP1 the “Primary Audio Controller” and host the Synchronous Master TDM device. The changes required are:

Set GPDSP1 to be instance 0 since the Primary Audio Controller must always be on instance 0.
Set ADSP to instance 1, and GPDSP0 to instance 2.
Make GPDSP1 have “is_primary = True” and all others “is_primary = False”
No changes to the signal flow since the TDM devices remain on instance 0

The deltas shown below relative to the previous 12 sample block size example.

AWD Signal Flow

No changes to the previous example showing 12 sample block size.

signalflow/config.xml

No changes

targetconfig/awecore.yml

targetconfig/devices_tdm.yml

No changes

Changing with TDM Port is the Synchronous Master

Subcanvases and Presets

Your Toplevel signal flow may include Subcanvas modules. Each subcanvas module contains a complete signal flow and can be loaded and unloaded at runtime. To get a Subcanvas module supported in AWE-TC, it has to be part of the signal flow configuration.

Each Subcanvas configuration entry in the config.yml file has a name, a path pointing to the module instance in the Toplevel signal flow and a file path to its AWC file.

CODE

signalflow:
  name: Main
  awc: path-to-toplevel.awc

  sub_canvases:
    - name: AVAS
      awe_path: SubSys/SubcanvasModuleName
      awc: path-to-avas-signalflow.awc
    - name: RNC
      awe_path: Another_Path_to_SubcanvasModule
      awc: path-to-rnc-signalflow.awc

Every Toplevel as well as Subcanvas signal flow may require specific settings later to re-configure the audio processing behavior. This “skinning” of the signal flow is done via preset AWB files - read more about those here.

AWE-TC configuration lists the presets with a name and file path. Presets can be attached to Toplevel as well as to Subcanvas entries, for example:

CODE

signalflow:
  name: Main
  awc: path-to-toplevel.awc

  presets:
    - name: PlatformX
      awb: path-to-platformx-modifications.awb
    - name: PlatformY
      awb: path-to-platformy-modifications.awb

  sub_canvases:
    - name: AVAS
      awe_path: SubSys/SubcanvasModuleName
      awc: path-to-avas-signalflow.awc

      presets:
        - name: Avas_SettingX
          awb: avas-specific-platformx-modifications.awb

After awetc has been executed the list of files in the “deploy” folder will also contain the corresponding AWB files for Subcanvases and presets:

CODE

subcanvas_*.awb   % AWB files for Subcanvas modules
preset_*.awb      % preset AWB files for Toplevel and Subcanvas modules

After the files have all been pushed into the same directory in which awc_index.txt is stored on the target system, AWE Audio service or AWE-Manager Shell can use a Subcanvas or a preset-AWB by simply using their name, for example:

CODE

awemgr_shell> load_design -name AVAS
awemgr_shell> load_design -name Avas_SettingX
awemgr_shell> unload_design -name RNC

Command Line Usage

AWE-TC builds on a task execution model. It is possible to run only specific tasks, by specifying the task name on the command line, e.g. awetc aweconfig_bin to run only the generation of the binary blob used during early audio. To view a list of available tasks use awetc list.

There are also generic commands to be executed, like the above mentioned awetc init. To get a list of supported commands use awetc help.

To see possible parameters a task or a command may have, use awetc help <taskname> or awetc help <cmd>, for example awetc help init.

YML File Contents

Add commented YML files and a description of how to configure them.

Highlight the most frequently used items.

Describe the recommended default settings and when you would need to change them.

Generated Files

Add detailed information about what each of the generated files contains

awc_index.txt - document every line in this file.

awe_config.bin

others

Advanced Features

Plug-ins

Tasks

Subcommands

Utilities: awe-file, awb-file, awe-ffs, awetc-aweconfig-dumper

Logging